GTPin: Opcodeprof Sample Tool

The Opcodeprof tool provides the dynamic frequencies of each of the kernel instructions ("instruction mix"), in the form of opcode histograms

Running the Opcodeprof tool

To run the Opcodeprof tool (in its default configuration), use the following command:

Profilers/Bin/gtpin -t opcodeprof -- app

How to understand Opcodeprof results

When you run the in-house GTPin Opcodeprof tool in its default configuration, the tool generates the directory: GTPIN_PROFILE_OPCODEPROF0. The profiling results are stored in the sub-folder: GTPIN_PROFILE_OPCODEPROF0\Session_Final. Results are provided for each kernel/shader configuration, and also in an accumulated (total) configuration.

For each binary kernel/shader that was dispatched to the device, the tool generates a directory with an extended kernel name: KernelName__CompilerGeneratedName, as shown in the following screenshot:

NOTE: If GTPin does not know the name of the kernel, then a compiler-generated name -- with the format CS_asmf54af91315561f54_simd8 -- is assigned as the kernel name. In the compiler-generated name, the prefix indicates the kernel type; the suffix indicates the SIMD width to which this kernel was compiled; and the 16-digit number is the hash ID of the IR representation of this kernel. This is shown in the previous screenshot.

Each kernel/shader folder contains the resulting file opcodeprof_total.out, which summarizes the results for this specific kernel/shader. In addition, an opcodeprof_total.out summarizing the results for this specific kernel/shader. In addition, a opcodeprof_total.out file in the root directory summarizes all the application kernels/shaders together.

Each individual opcodeprof_total.out file has the following format:

DYNAMIC OPCODE HISTOGRAMS PER EXECUTION DATA TYPES
==================================================

DATA TYPE: ud

OPCODE Report :  Opcode  SIMD         Static (%)            Dynamic (%)
                 sendsc    16              2 (16.7%)          11870 (16.7%)
                  sends    16              2 (16.7%)          11870 (16.7%)
                    mov     1              2 (16.7%)          11870 (16.7%)
                    add     1              1 ( 8.3%)           5935 ( 8.3%)
                    mov     8              1 ( 8.3%)           5935 ( 8.3%)


DATA TYPE: f

OPCODE Report :  Opcode  SIMD         Static (%)            Dynamic (%)
                    pln    16              4 (33.3%)          23740 (33.3%)


// kernel name:    PS_asm537c7dc831196b2d_simd32

Static  instruction count = 12
Dynamic instruction count = 71220


[           5935]     (W)      mov (8|M0)               r21.0<1>:ud   r0.0<8;8,1>:ud                   {Compacted}
[           5935]     (W)      pln (16|M0)              r19.0<1>:f    r12.4<0;1,0>:f    r3.0<8;8,1>:f    {Compacted}
[           5935]     (W)      pln (16|M0)              r17.0<1>:f    r12.0<0;1,0>:f    r3.0<8;8,1>:f    {Compacted}
[           5935]     (W)      add (1|M0)               a0.0<1>:ud    r11.0<0;1,0>:ud   0x102:ud         {Compacted}
[           5935]     (W)      mov (1|M0)               r21.3<1>:ud   r11.1<0;1,0>:ud                 
[           5935]     (W)      pln (16|M16)             r15.0<1>:f    r12.4<0;1,0>:f    r7.0<8;8,1>:f   
[           5935]     (W)      mov (1|M0)               r21.2<1>:ud   0x0:ud                           {Compacted}
[           5935]     (W)      pln (16|M16)             r13.0<1>:f    r12.0<0;1,0>:f    r7.0<8;8,1>:f   
[           5935]              sends (16|M0)            r0:w     r21     r17     a0.0        0x28C00FC
[           5935]              sends (16|M16)           r112:w   r21     r13     a0.0        0x28C00FC
[           5935]              sendsc (16|M0)           null:w   r0      null    0x5         0x10031000
[           5935]              sendsc (16|M16)          null:w   r112    null    0x25        0x10031800 {EOT}

The results are presented as dynamic histograms of opcodes, grouped by operational data type. For each data type and for each opcode, the following information is reported: the opcode mnemonic, its operational SIMD width, the static count of the tuple (Opcode, SIMD, data type) encountered within the kernel, the percentage among all static instructions of the kernel, the dynamic count of the above tuple, and its percentage among all dynamic instructions that were counted. The following data is then reported: kernel name, total number of static instructions, and the total number of dynamic instructions. Finally this data is reported: a listing of all assembly instructions of the kernel, along with the dynamic count of each instruction.

In the root directory, the file opcodeprof_total.out summarizes the results of all kernels/shaders of the application. It provides the total number of binary kernels, the total dynamic number of instructions, the dynamic opcode histograms per data type, and the listing of all assembly kernels, along with dynamic frequencies of each instruction, as shown here:

Total number of kernels:      8
Total number of instructions: 1907624

DYNAMIC OPCODE HISTOGRAMS PER EXECUTION DATA TYPES
==================================================

DATA TYPE: ud

OPCODE Report :  Opcode  SIMD        Dynamic (%)
                  sends     8         146262 ( 7.7%)
                  sends    16          92520 ( 4.9%)
                    add     1          89247 ( 4.7%)
                    mov     1          38574 ( 2.0%)
                 sendsc    16          22560 ( 1.2%)
                    mov     8           9615 ( 0.5%)
                 sendsc     8           6342 ( 0.3%)


DATA TYPE: d

OPCODE Report :  Opcode  SIMD        Dynamic (%)
                    mov     8          69960 ( 3.7%)


DATA TYPE: uw

OPCODE Report :  Opcode  SIMD        Dynamic (%)
                    mov     1          69960 ( 3.7%)


DATA TYPE: f

OPCODE Report :  Opcode  SIMD        Dynamic (%)
                    mad     8         559680 (29.3%)
                    mul     8         285182 (14.9%)
                    add     8         279840 (14.7%)
                    mov     8         145262 ( 7.6%)
                    pln    16          45120 ( 2.4%)
                    mul    16          17408 ( 0.9%)
                    mov    16          17408 ( 0.9%)
                    pln     8          12684 ( 0.7%)




[          34980]     (W)      mov (1|M0)               r0.2<1>:ud    0x0:uw
[          34980]     (W)      add (1|M0)               a0.0<1>:ud    r2.2<0;1,0>:ud    0xA:ud           {Compacted}
[          34980]              mov (8|M0)               r119.0<1>:f   r6.0<8;8,1>:f                    {Compacted}
[          34980]     (W)      sends (16|M0)            r117:w   r0      null    a0.0        0x22843FC  //  wr:1h+?, rd:2, ?
[          34980]              mov (8|M0)               r120.0<1>:f   r7.0<8;8,1>:f                    {Compacted}
[          34980]     (W)      mov (8|M0)               r112.0<1>:d   r1.0<8;8,1>:d     

Opcodeprof tool: modes of operation

To print the total results of just the application profiling, use the following command line:

Profilers/Bin/gtpin -t opcodeprof --total_only -- app

In the above case, only one file is generated: GTPIN_PROFILE_OPCODEPROF0\Session_Final\opcodeprof_total.out.

To obtain the profiling for each HW thread, use the following command line:

Profilers/Bin/gtpin -t opcodeprof --per_thread_data --num_thread_blocks 0 -- app

In this case, the files like opcodeprof__s_0_ss_2_eu_7_tid_5.out are also generated for each binary kernel/shader in the corresponding sub-folder. In the files, S indicates Slice number, SS indicates Sub-Slice number, EU indicates Execution Unit number, and TID indicates the HW Thread ID number.

(Back to the list of all GTPin Sample Tools)

opcodeprof.h

/*========================== begin_copyright_notice ============================
Copyright (C) 2018-2024 Intel Corporation

SPDX-License-Identifier: MIT
============================= end_copyright_notice ===========================*/

/*!
 * @file Opcodeprof tool definitions
 */

#ifndef OPCODEPROF_H_
#define OPCODEPROF_H_

#include <map>
#include <vector>
#include <string>
#include <tuple>

#include "gtpin_api.h"
#include "gtpin_tool_utils.h"
#include "opcodeprof_utils.h"

using namespace gtpin;


/* ============================================================================================= */
// Class Opcodeprof
/* ============================================================================================= */
/*!
 * Implementation of the IGtTool interface for the opcodeprof tool
 */
class Opcodeprof : public GtTool
{
public:
    /// Implementation of the IGtTool interface
    const char* Name() const { return "opcodeprof"; }

    void OnKernelBuild(IGtKernelInstrument& instrumentor);
    void OnKernelRun(IGtKernelDispatch& dispatcher);
    void OnKernelComplete(IGtKernelDispatch& dispatcher);

public:

    static Opcodeprof* Instance();               ///< @return Single instance of this class
    static void OnFini() { Instance()->Fini(); } ///< Callback function registered with atexit()

private:
    Opcodeprof() = default;
    Opcodeprof(const Opcodeprof&) = delete;
    Opcodeprof& operator = (const Opcodeprof&) = delete;
    ~Opcodeprof() = default;

    void Fini();              /// Post process and dump profiling data

private:
    std::map<GtKernelId, OpcodeprofKernelProfile> _kernels;  ///< Collection of kernel profiles
};

#endif

opcodeprof.cpp

/*========================== begin_copyright_notice ============================
Copyright (C) 2018-2025 Intel Corporation

SPDX-License-Identifier: MIT
============================= end_copyright_notice ===========================*/

/*!
 * @file Implementation of the Opcodeprof tool
 */

#include <fstream>
#include <sstream>
#include <iomanip>
#include <algorithm>
#include <functional>

#include "opcodeprof.h"

using namespace gtpin;

/* ============================================================================================= */
// Configuration
/* ============================================================================================= */
Knob<int>  knobNumThreadBuckets("num_thread_buckets", 32, "Number of thread buckets. 0 - maximum thread buckets");

/* ============================================================================================= */
// Opcodeprof implementation
/* ============================================================================================= */
Opcodeprof* Opcodeprof::Instance()
{
    static Opcodeprof instance;
    return &instance;
}

void Opcodeprof::OnKernelBuild(IGtKernelInstrument& instrumentor)
{
    const IGtKernel&           kernel    = instrumentor.Kernel();
    const IGtCfg&              cfg       = instrumentor.Cfg();
    const IGtGenCoder&         coder     = instrumentor.Coder();
    const IGtGenModel&         genModel  = kernel.GenModel();
    IGtProfileBufferAllocator& allocator = instrumentor.ProfileBufferAllocator();
    IGtVregFactory&            vregs     = coder.VregFactory();
    IGtInsFactory&             insF      = coder.InstructionFactory();

    // Initialize virtual registers
    GtReg addrReg = vregs.MakeMsgAddrScratch(); ///< Virtual register that holds address within profile buffer

    // Allocate the profile buffer. It will hold single OpcodeprofRecord per each basic block in each thread bucket
    uint32_t numThreadBuckets = (knobNumThreadBuckets == 0) ? genModel.MaxThreadBuckets() : knobNumThreadBuckets;
    uint32_t numRecords = cfg.NumBbls();
    GtProfileArray profileArray(sizeof(OpcodeprofRecord), numRecords, numThreadBuckets);
    profileArray.Allocate(allocator);

    // Instrument basic blocks
    for (auto bblPtr : cfg.Bbls())
    {
        if (!bblPtr->IsEmpty())
        {
            GtGenProcedure proc;
            uint32_t recordNum = bblPtr->Id();

            // addrReg =  address of the current thread's OpcodeprofRecord in the profile buffer
            profileArray.ComputeAddress(coder, proc, addrReg, recordNum);

            // [addrReg].freq++
            proc += insF.MakeAtomicInc(NullReg(), addrReg, GED_DATA_TYPE_ud);

            if (!proc.empty()) { proc.front()->AppendAnnotation(__func__); }
            InstrumentBbl(instrumentor , *bblPtr, GtIpoint::Before(), proc);
        }
    }

    // Create OpcodeprofKernelProfile object that represents profile of this kernel
    _kernels.emplace(kernel.Id(), OpcodeprofKernelProfile(kernel, cfg, profileArray));
}

void Opcodeprof::OnKernelRun(IGtKernelDispatch& dispatcher)
{
    bool isProfileEnabled = false;

    const IGtKernel& kernel = dispatcher.Kernel();
    GtKernelExecDesc execDesc; dispatcher.GetExecDescriptor(execDesc);
    if (kernel.IsInstrumented() && IsKernelExecProfileEnabled(execDesc, kernel.GpuPlatform(), kernel.Name().Get()))
    {
        auto it = _kernels.find(kernel.Id());

        if (it != _kernels.end())
        {
            IGtProfileBuffer*          buffer        = dispatcher.CreateProfileBuffer(); GTPIN_ASSERT(buffer);
            OpcodeprofKernelProfile&   kernelProfile = it->second;
            const GtProfileArray&      profileArray  = kernelProfile.GetProfileArray();
            if (profileArray.Initialize(*buffer))
            {
                isProfileEnabled = true;
            }
            else
            {
                GTPIN_ERROR_MSG("OPCODEPROF: " + std::string(kernel.Name()) + " : Failed to write into memory buffer");
            }
        }
    }
    dispatcher.SetProfilingMode(isProfileEnabled);
}

void Opcodeprof::OnKernelComplete(IGtKernelDispatch& dispatcher)
{
    if (!dispatcher.IsProfilingEnabled())
    {
        return; // Do nothing with unprofiled kernel dispatches
    }

    const IGtKernel& kernel = dispatcher.Kernel();
    auto it = _kernels.find(kernel.Id());

    if (it != _kernels.end())
    {
        const IGtProfileBuffer*  buffer        = dispatcher.GetProfileBuffer(); GTPIN_ASSERT(buffer);
        OpcodeprofKernelProfile& kernelProfile = it->second;
        const GtProfileArray&    profileArray  = kernelProfile.GetProfileArray();

        for (uint32_t recordNum = 0; recordNum != profileArray.NumRecords(); ++recordNum)
        {
            for (uint32_t threadBucket = 0; threadBucket < profileArray.NumThreadBuckets(); ++threadBucket)
            {
                OpcodeprofRecord record;
                if (!profileArray.Read(*buffer, &record, recordNum, 1, threadBucket))
                {
                    GTPIN_ERROR_MSG("OPCODEPROF: " + std::string(kernel.Name()) + " : Failed to read from memory buffer");
                }
                else
                {
                    kernelProfile.Accumulate(record, (BblId)recordNum);
                }
            }
        }
    }
}

void Opcodeprof::Fini()
{
    DumpProfile(_kernels);
    DumpAsm(_kernels);
}

/* ============================================================================================= */
// GTPin_Entry
/* ============================================================================================= */
EXPORT_C_FUNC void GTPin_Entry(int argc, const char* argv[])
{
    ConfigureGTPin(argc, argv);
    Opcodeprof::Instance()->Register();
    atexit(Opcodeprof::OnFini);
}

(Back to the list of all GTPin Sample Tools)