GTPin: GTReplay: Getting Started

Instructions and recommendations on how to develop, build and run a GTReplay tool

The list of the ready-to-use sample tools can be found in GTReplay Sample Tools

GTReplay tool API

The Profiling tool communicates with the GTReplay framework by means of a Tool API, as shown in the figure below. A Tool API is a set of exposed GTReplay functions. These functions allow a profiling application to inspect the original binary code, register callbacks, and observe register state. The Tool API can be divided into the following groups:

Kernel inspection API
- Allows iteration over Basic Blocks (BBL) and instructions.
Instruction inspection API
- Allows querying of instructions’ static attributes.
Callback Registration API
- Allows you to register callbacks at different points of the kernel.
State Inspection API
- Allows you to observe register state of any HW thread at any point of execution.

Before developing your own tools, please review GTReplay: API reference, to learn about supported interfaces.

Header files

All the header files required to build a GTReplay tool are located in the Profilers\GTReplay\common and Profilers\GTReplay\utils directories.

Callback functions

Any GTReplay tool must implement and register at least two following callback functions:

OnKernelBuild
This function is called by GTReplay when any new trace is loaded. This function traverses all basic blocks (BBL) of the kernel and, if needed, traverses all instructions in each BBL and decides at what points of the code to register callbacks.
OnKernelComplete
This function is called by GTReplay for each kernel upon completion of the trace replay and indicates that the job is done. At this point, the tool can summarize the gathered information.

Upon initialization the tool must register these callback functions within GTReplay.

GTReplay supports a bunch of other callbacks which might be useful for analysis of the kernel execution, such as notification before kernel begins, and after it ends; before any SW thread is dispatched to any of HW threads and after it ends; and before and after any instruction of the kernel. All these callback functions should be registered within OnKernelBuild.

The callback functions’ prototype and callback register functions are defined in GTReplay\gtreplay_callbacks.h. Please review the GTReplay: Callback Registration in GTReplay: API reference for more details.

Tool main function

Each GTReplay tool must implement and expose the function,GTReplay_Entry(int argc, const char *argv[]), which plays the role of the main entry to the tool.

The implementation of this function must do the following tasks:

GTReplay configuration
- Pass arguments to GTReplay by calling the function: ConfigureGTReplay(int argc, const char *argv[]).
Callback registration
- Register OnKernelBuild and OnKernelComplete callbacks in GTReplay.
GTReplay initialization
- To initialize GTReplay, you need the API: GTReplay_Start().

The following is an example of the function: GTReplay_Entry(int argc, const char *argv[])

extern "C"
DLLEXP void FASTCALL GTReplay_Entry(int argc, const char *argv[])
{
    ConfigureGTReplay(argc, argv);
    
    GTReplay_RegisterOnKernelBuildCallback(OnKernelBuild);
    GTReplay_RegisterOnKernelCompleteCallback(OnKernelComplete);

    GTReplay_Start();
}

Configuring GTReplay tools

A user configures GTReplay by providing configuration parameters (knobs) in the command line. See the list of supported parameters in GTReplay Configuration. A developer can define additional parameters to the tool. These parameters are provided to the tool in the same manner as native GTReplay parameters in the command line.

There are three types of parameters a user can define: int, bool, and string.

To define a parameter you must provide its name (string value), its initial (default) value, and an optional help line (string value).

The following example shows how to define parameters of different types:

Knob<int>    myIntKnob("int_param", 10, "My int parameter help line");
Knob<bool>   myBoolKnob("bool_param", False, "My bool parameter help line");
Knob<string> myStringKnob("string_param", "", "My string parameter help line");

NOTE: The definition of new knobs should be done BEFORE calling ConfigureGTReplay().

Once new knobs are defined, they are automatically added to the list of all configuration knobs. No additional work is required. After calling GTReplay_Start(), the tool code can use the values of these parameters.

int    intVal    = myIntKnob;
bool   boolVal   = myBoolKnob;
string stringVal = myStringKnob;

Upon running the application with GTReplay, the user provides the parameters to the code in the following manner:

Profilers\GTReplay\intel64\gtreplay.exe -t toolname --int_param 5 --bool_param --string_param Alex -- path-to-the-directory-containing-the-trace

Note: Providing the bool parameter in the command line will inverse its default value.

How to build GTReplay tool

GTReplay sample tools are provided in the Profilers folder of the package. It is highly recommended that the user, who wants to implement his own profiling tool, takes as a basis, one of the provided tools, and extends/modifies that tool’s code.

To build the modified code, you must perform the following steps:

Step 1: Generate examples solution

In the examples folder, in a command line window, enter:
```
    >mkdir build
    >cd build
```

On Windows, enter:

    >cmake .. -G <cmake's generator> -DARCH=<ia32|intel64> -DGTReplay_KIT=<GTReplay_kit>
        - cmake's generator = "Visual Studio 15" (for 32-bit) / "Visual Studio 15 Win64" (for 64-bit) - to verify the build works as expected
        - GTReplay_kit = absolute path to your GTReplay kit
        - E.g. "cmake .. -G "Visual Studio 15 Win64" -DARCH=intel64 -DGTPIN_KIT=C:\GTPin\Profilers"

On Linux, enter:

    >cmake .. -DCMAKE_BUILD_TYPE=<Release|Debug> -DARCH=<ia32|intel64> -DGTPIN_KIT=<gtpin_kit>
        - gtpin_kit = absolute path to your GTPin kit

Step 2: Build the examples solution that was generated in the previous step:

To build on Windows, you can use the GTReplay_Example.sln OR run:

       >cmake --build . --config <Release|Debug> --target install

To build on Linux, enter:
```
        >make -j 8 install
```

How to run GTReplay tool

The command line to run an application with GTReplay is:

Profilers\GTReplay\intel64\gtreplay.exe [-t <tool1>] [-t <tool2>] [-t <tool3>] [GTReplay args] -- path-to-the-directory-containing-the-trace

if you want to run the tool provided with the GTReplay kit:
- tool = name of tool; for example: icount
if you want to run an extended/new tool of your own, that was built with the previously mentioned guideline:
- tool = Profilers\GTReplay\examples\build\<Release/Debug>\<tool_name>.dll (path to your tool's dll)
  - E.g. C:\GTPin\Profilers\GTReplay\examples\build\Release\icount.dll