GTPin: gtpin::IGtKernelInstrument Class Reference

GTPin

- Main Page
- Related Pages
- Modules
- Data Structures

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

Public Member Functions
gtpin::IGtKernelInstrument Class Reference
Kernel Instrumentation

Instrumentor of the GEN kernel. More...

`#include <igt_kernel.h>`

## Public Member Functions
virtual const IGtKernel & | Kernel () const =0
| Get IGtKernel interface to the kernel being instrumented.
virtual const IGtCfg & | Cfg () const =0
| Get IGtCfg interface to the kernel being instrumented.
virtual const IGtGenCoder & | Coder () const =0
| Get IGtGenCoder interface to the kernel being instrumented.
virtual IGtProfileBufferAllocator & | ProfileBufferAllocator () const =0
| Get IGtProfileBufferAllocator interface to the kernel being instrumented.
virtual IGtMemoryMapper & | MemoryMapper ()=0
| Get IGtMemoryMapper interface to the kernel being instrumented.
virtual IGtIargFactory & | IargFactory () const =0
virtual bool | InstrumentInstruction (const IGtIns &ins, GtIpoint ipoint, const IGtGenProcedure &proc)=0
| Insert the specified instrumentation procedure before/after the specified instruction.
virtual bool | InstrumentBbl (const IGtBbl &bbl, GtIpoint ipoint, const IGtGenProcedure &proc)=0
| Insert the specified instrumentation procedure before/after the specified BBL.
virtual bool | InstrumentEdge (const IGtEdge &igtEdge, const IGtGenProcedure &proc)=0
| Insert the specified instrumentation procedure to the destination bbl and execute it only when entering from the source bbl of the given edge.
virtual bool | InstrumentEntries (const IGtGenProcedure &proc)=0
| Insert the specified instrumentation procedure at all entries to the kernel.
virtual bool | InstrumentExits (const IGtGenProcedure &proc)=0
| Insert the specified instrumentation procedure at all exits of the kernel - before each EOT instruction in the original code of the kernel.
virtual bool | RemoveInstruction (const IGtIns &ins)=0
| Remove the specified instruction from the original code of the kernel.
virtual bool | SetProfileFilter (uint32_t sliceMask, uint32_t dualSubsliceMask, uint32_t subsliceMask, uint32_t euMask, uint32_t threadMask)=0
| Set the profiling filter that controls which version of the kernel code, instrumented or original, will run on the HW slice/EU/thread.
virtual bool | LinkHliModule (IGtHliModuleHandle moduleHandle)=0
| Link the kernel with the specified High-Level Instrumentation (HLI) module.

## Detailed Description

Instrumentor of the GEN kernel.

For each new binary kernel created by the compiler, GTPin invokes the IGtTool::OnKernelBuild function. This function, implemented by the tool, receives the IGtKernelInstrument object that refers to the kernel being compiled and provides methods for instrumenting the kernel. Part of these methods are implemented by the IGtKernelInstrument object itself, while many other methods are implemented by referred objects that provide interfaces like IGtCfg, IGtGenCoder, IGtInsFactory, etc.

Availability:
  - IGtTool::OnKernelBuild

## Member Function Documentation

virtual const IGtCfg& gtpin::IGtKernelInstrument::Cfg | ( |  | ) | const`[pure virtual]`

Get IGtCfg interface to the kernel being instrumented.

Returns:
  Object that provides interface to control flow graph (CFG) of the kernel

virtual const IGtGenCoder& gtpin::IGtKernelInstrument::Coder | ( |  | ) | const`[pure virtual]`

Get IGtGenCoder interface to the kernel being instrumented.

Returns:
  Object that provides code generation interface and assembles instrumentation procedures

virtual IGtIargFactory& gtpin::IGtKernelInstrument::IargFactory | ( |  | ) | const`[pure virtual]`

Get Get IGtIargFactory interface to the factory of arguments of the High-Level Instrumentation (HLI) functions

Returns:
  Factory of HLI arguments associated with this object

virtual bool gtpin::IGtKernelInstrument::InstrumentBbl | ( | const IGtBbl & | bbl,
|  | GtIpoint | ipoint,
|  | const IGtGenProcedure & | proc
| ) |  | `[pure virtual]`

Insert the specified instrumentation procedure before/after the specified BBL.

Parameters:

  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Location in the original code, relative to 'bbl'
  [in] | proc | Instrumentation procedure to be inserted at the specified location

Note:
  If 'ipoint' specifies location after BBL, the insertion position is as following:
  - before the last BBL's instruction, if BBL ends with a control flow or EOT instruction
  - after the last BBL's instruction, if BBL falls through to the next block

Returns:
  true - success, false - failure In case of error, the IGtCore::LastError() function provides the specific failure reason

virtual bool gtpin::IGtKernelInstrument::InstrumentEdge | ( | const IGtEdge & | igtEdge,
|  | const IGtGenProcedure & | proc
| ) |  | `[pure virtual]`

Insert the specified instrumentation procedure to the destination bbl and execute it only when entering from the source bbl of the given edge.

Parameters:

  [in] | edge | edge between two basic blocks in the original code of the kernel
  [in] | proc | Instrumentation procedure to be inserted at the specified location

Returns:
  true - success, false - failure In case of error, the IGtCore::LastError() function provides the specific failure reason

virtual bool gtpin::IGtKernelInstrument::InstrumentEntries | ( | const IGtGenProcedure & | proc | ) | `[pure virtual]`

Insert the specified instrumentation procedure at all entries to the kernel.

Parameters:

  [in] | proc | Instrumentation procedure to be inserted

Note:
  This function guaranties that instrumentation procedure will be executed once per each execution of the kernel. This feature makes it different from the insertion of instrumentation procedure before each Cfg().EntryBbls(). The difference could be important in kernels with multiple (conditionally) connected entries, or kernels looping through entry point.

Returns:
  true - success, false - failure In case of error, the IGtCore::LastError() function provides the specific failure reason

virtual bool gtpin::IGtKernelInstrument::InstrumentExits | ( | const IGtGenProcedure & | proc | ) | `[pure virtual]`

Insert the specified instrumentation procedure at all exits of the kernel - before each EOT instruction in the original code of the kernel.

Parameters:

  [in] | proc | Instrumentation procedure to be inserted

Returns:
  true - success, false - failure In case of error, the IGtCore::LastError() function provides the specific failure reason

virtual bool gtpin::IGtKernelInstrument::InstrumentInstruction | ( | const IGtIns & | ins,
|  | GtIpoint | ipoint,
|  | const IGtGenProcedure & | proc
| ) |  | `[pure virtual]`

Insert the specified instrumentation procedure before/after the specified instruction.

Parameters:

  [in] | ins | Instruction in the original code of the kernel
  [in] | ipoint | Location in the original code, relative to 'ins'
  [in] | proc | Instrumentation procedure to be inserted at the specified location

Returns:
  true - success, false - failure In case of error, the IGtCore::LastError() function provides the specific failure reason

virtual const IGtKernel& gtpin::IGtKernelInstrument::Kernel | ( |  | ) | const`[pure virtual]`

Get IGtKernel interface to the kernel being instrumented.

Returns:
  Object that provides access to basic properties of the kernel

virtual bool gtpin::IGtKernelInstrument::LinkHliModule | ( | IGtHliModuleHandle | moduleHandle | ) | `[pure virtual]`

Link the kernel with the specified High-Level Instrumentation (HLI) module.

Parameters:

  [in] | moduleHandle | Handle to a module in the HLI library (see HliLibrary)

Returns:
  true - success, false - failure In case of error, the IGtCore::LastError() function provides the specific failure reason

Note:
  This function may not detect all possible errors because the module linking can be postponed until after recording all instrumentations. These "late" errors can be processed by error handlers, registered by the RegisterEventHandler function

virtual IGtMemoryMapper& gtpin::IGtKernelInstrument::MemoryMapper | ( |  | ) | `[pure virtual]`

Get IGtMemoryMapper interface to the kernel being instrumented.

Returns:
  Object that provides host-to-device memory mapping service

virtual IGtProfileBufferAllocator& gtpin::IGtKernelInstrument::ProfileBufferAllocator | ( |  | ) | const`[pure virtual]`

Get IGtProfileBufferAllocator interface to the kernel being instrumented.

Returns:
  Allocator of memory blocks within kernel's profile buffer

virtual bool gtpin::IGtKernelInstrument::RemoveInstruction | ( | const IGtIns & | ins | ) | `[pure virtual]`

Remove the specified instruction from the original code of the kernel.

Parameters:

  [in] | ins | Instruction to be removed from the original code of the kernel

Returns:
  true - success, false - failure In case of error, the IGtCore::LastError() function provides the specific failure reason

virtual bool gtpin::IGtKernelInstrument::SetProfileFilter | ( | uint32_t | sliceMask,
|  | uint32_t | dualSubsliceMask,
|  | uint32_t | subsliceMask,
|  | uint32_t | euMask,
|  | uint32_t | threadMask
| ) |  | `[pure virtual]`

Set the profiling filter that controls which version of the kernel code, instrumented or original, will run on the HW slice/EU/thread.

The profiling filter comprises a number of bit masks associated with HW components. Each bit in the mask represents a HW component with the corresponding ID. Instrumented code will be executed on HW components whose corresponding bits in all masks are set on.

Parameters:

  [in] | sliceMask | Slice mask
  [in] | dualSubsliceMask | Dual subslice mask
  [in] | subsliceMask | Subslice mask
  [in] | euMask | EU imask
  [in] | threadMask | HW thread mask

Returns:
  true - success, false - failure

All Data Structures Functions Variables Typedefs Enumerations Enumerator

      Copyright (C) 2013-2025 Intel Corporation

      SPDX-License-Identifier: MIT