GTPin: gtpin::GtHliFunction< RET, PRMS > Class Template Reference

GTPin

- Main Page
- Related Pages
- Modules
- Data Structures

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

Public Member Functions
gtpin::GtHliFunction< RET, PRMS > Class Template Reference
GTPin: High-Level Instrumentation (HLI) Function

Class that represents an HLI function and provides convenient interface for generating HLI function calls. More...

`#include <gt_hli_function.h>`

## Public Member Functions
| GtHliFunction (const char *funcName, GtHliCallStd callStd=GtHliCallStd::IGC_STACK, bool hasComboParam=false)
std::string | Name () const
| Return name of the function.
GtHliCallStd | CallStd () const
| Return calling convention of the function.
constexpr uint32_t | NumArgs () const
| Return number of function arguments.
constexpr bool | HasReturnValue () const
| Return true if the function has a non-void return value, false - otherwise.
template<typename... ARGS>
void | GeneratePredicatedCall (IGtKernelInstrument &instrumentor, IGtGenProcedure &proc, const GtPredicate &predicate, const GtReg &retReg, const ARGS &...argValues)
template<typename... ARGS>
void | GenerateCall (IGtKernelInstrument &instrumentor, IGtGenProcedure &proc, const GtReg &retReg, const ARGS &...argValues)
template<typename... ARGS>
bool | InsertPredicatedCallAtInstruction (IGtKernelInstrument &instrumentor, const IGtIns &ins, GtIpoint ipoint, const GtPredicate &predicate, const GtReg &retReg, const ARGS &...argValues)
| Insert a call to this HLI function with the specified argument values before/after the specified instruction.
template<typename... ARGS>
bool | InsertCallAtInstruction (IGtKernelInstrument &instrumentor, const IGtIns &ins, GtIpoint ipoint, const GtReg &retReg, const ARGS &...argValues)
template<typename... ARGS>
bool | InsertPredicatedCallAtBbl (IGtKernelInstrument &instrumentor, const IGtBbl &bbl, GtIpoint ipoint, const GtPredicate &predicate, const GtReg &retReg, const ARGS &...argValues)
| Insert call to this HLI function with the specified argument values at the beginning/end of the specified BBL.
template<typename... ARGS>
bool | InsertCallAtBbl (IGtKernelInstrument &instrumentor, const IGtBbl &bbl, GtIpoint ipoint, const GtReg &retReg, const ARGS &...argValues)
template<typename... ARGS>
bool | InsertPredicatedCallAtKernelEntries (IGtKernelInstrument &instrumentor, const GtPredicate &predicate, const GtReg &retReg, const ARGS &...argValues)
| Insert call to this HLI function with the specified argument values at all entries to the kernel.
template<typename... ARGS>
bool | InsertCallAtKernelEntries (IGtKernelInstrument &instrumentor, const GtReg &retReg, const ARGS &...argValues)
template<typename... ARGS>
bool | InsertPredicatedCallAtKernelExits (IGtKernelInstrument &instrumentor, const GtPredicate &predicate, const GtReg &retReg, const ARGS &...argValues)
| Insert call to this HLI function with the specified argument values at all exits of the kernel.
template<typename... ARGS>
bool | InsertCallAtKernelExits (IGtKernelInstrument &instrumentor, const GtReg &retReg, const ARGS &...argValues)

## Detailed Description

### template<typename RET, typename... PRMS>
class gtpin::GtHliFunction< RET, PRMS >

Class that represents an HLI function and provides convenient interface for generating HLI function calls.

The template arguments of this class resemble signature of the function, as declared in the source code of the corresponding function, e.g. in the OpenCL C function declaration.

Note:
  To overcome ABI limitations, a tool can define HLI function so that it receives all argument values on stack, rather than in registers. For this purpose, the tool should
  a) Pass the [hasComboParam = true] value to the GtHliFunction constructor
  b) Define the HLI function with the single parameter - pointer to the array of argument values passed on the stack. The order of arguments values follows the order of template parameters in the GtHliFunction definition. Each argument value is aligned to 8-byte boundary, at minimum. See Example 3 below.

Parameters:

  RET | Type of the return value of the function, either valid HLI parameter type or void
  PRMS | List of valid HLI parameter types that correspond to the types of the function's parameters

     * ========================================================================================================*
     *                                          Examples                                                       *
     * ========================================================================================================*

          // ------------------ Example 1 -----------------------
         bool MyFunc1(uint64_t, uint32_t, MyType*);

         #if defined(__cplusplus)
         GtHliFunction<bool, uint64_t, uint32_t, MyType*> myFunc1 { "MyFunc1" };

         myFunc1.InsertCallAtInstruction(instrumentor, ins, GT_IPOINT_BEFORE,
                                         NullReg(), // [bool]     retVal: unused return value
                                         vreg,      // [uint64_t] arg0:   64-bit integer, passed in a virtual register
                                         IargTid(), // [uint32_t] arg1:   Current Thread ID
                                         &myVar     // [MyType*]  arg2:   Host pointer converted to device pointer
                                         );
         #endif

          // ------------------ Example 2 -----------------------
          uint64_t MyFunc2(uint32_t, uint8_t*);

          #if defined(__cplusplus)
          GtHliFunction<uint64_t, uint32_t, uint8_t*> myFunc2 { "MyFunc2" };

          myFunc2.InsertCallAtBbl(instrumentor, bbl, GT_IPOINT_BEFORE,
                                  myRetReg,             // [uint64_t] retVal: Return value passed in myRetReg
                                  IargFfTid(),          // [uint32_t] arg0:   Fixed Function thread ID
                                  IargDevicePtr(vreg),  // [uint32_t] arg1:   Device pointer passed in a virtual register
                                  );
          #endif

          // ------------------ Example 3 -----------------------
          // Enforce all function arguments to be passed on stack

          #if defined(__cplusplus)
          #define HLIF_ALIGNED alignas(8)
          #else
          #define HLIF_ALIGNED __attribute__ ((aligned (8)))
          #endif

          typedef struct MyArgsOnStack
          {
            uint32_t    arg0 HLIF_ALIGNED;
            uint32_t    arg1 HLIF_ALIGNED;
            uint8_t*    arg2 HLIF_ALIGNED;
            MyType*     arg3 HLIF_ALIGNED;
          } MyArgsOnStack;

          void MyFunc3(const MyArgsOnStack*);

          #if defined(__cplusplus)
          bool hasComboParam = true;
          GtHliFunction<void, uint32_t, uint32_t, uint8_t*, MyType*> myFunc3 { "MyFunc3", GtHliCallStd::IGC_STACK, hasComboParam };

          myFunc3.InsertCallAtBbl(instrumentor, bbl, GT_IPOINT_BEFORE,
                                  NullReg(),                // [void]     retVal: no return value
                                  IargTid(),                // [uint32_t] arg0:   Current Thread ID
                                  IargInsOpMask(ins),       // [uint32_t] arg1:   Mask of scalar operations
                                  IargConstGrfRange(10, 5), // [uint8_t*] arg2:   Array of GRF registers [r10 - r14]
                                  &myVar                    // [MyType*]  arg3:   Host pointer converted to device pointer
                                  );
          #endif

    * ========================================================================================================*

Availability:
  - IGtTool::OnKernelBuild

## Constructor & Destructor Documentation

template<typename RET , typename... PRMS>

gtpin::GtHliFunction< RET, PRMS >::GtHliFunction | ( | const char * | funcName,
|  | GtHliCallStd | callStd = `GtHliCallStd::IGC_STACK`,
|  | bool | hasComboParam = `false`
| ) |  | `[inline]`

Constructor

Parameters:

  [in] | funcName | The name of the HLI function in the module compiled from the corresponding source, e.g. the name of the OpenCL C function
  [in] | callStd | The calling convention of the HLI function. Currently, the only supported calling convention is IGC ABI for compilers targeting Gen, aka stack-call ABI.
  [in] | hasComboParam | true - the function has a single parameter pointing to the array of argument values on stack false - the function has a dedicated parameter for each argument value

## Member Function Documentation

template<typename RET , typename... PRMS>
template<typename... ARGS>

void gtpin::GtHliFunction< RET, PRMS >::GenerateCall | ( | IGtKernelInstrument & | instrumentor,
|  | IGtGenProcedure & | proc,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Generate a procedure that calls this HLI function with the specified list of argument values

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | proc | Procedure, the generated code is appended to
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call. Objects in the list follow the order of the formal function paramters to which they will be assigned

Supported types of argument values

- Any type ARGT that provides a method GtIargType ARGT::Type()
  E.g. IargPrime, IargHostPtr, IargDevicePtr, IargTid, and other Iarg* types defined in the GTPin: High-Level Instrumentation (HLI) Parameters and Arguments section.
  For these types, the corresponding IGtIarg object is generated by the ARGT::Make() method

- Any valid prime type ARGT (IsValidHliPrimeType<ARGT>)
  These types are treated as IargPrime<ARGT>, e.g. int32_t => IargPrime<int32_t>; float => IargPrime<float>; enum E => IargPrime<enum E>; etc.

- The GtReg type
  This type is treated as IargPrime<GtReg>

- Any pointer pointer type ARGT (IsPointer<ARGT>)
  This type is treated as IargHostPtr, e.g. MyType* => IargHostPtr

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

void gtpin::GtHliFunction< RET, PRMS >::GeneratePredicatedCall | ( | IGtKernelInstrument & | instrumentor,
|  | IGtGenProcedure & | proc,
|  | const GtPredicate & | predicate,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Generate a procedure that calls this HLI function with the specified list of argument values

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | proc | Procedure, the generated code is appended to
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call. Objects in the list follow the order of the formal function paramters to which they will be assigned

Supported types of argument values

- Any type ARGT that provides a method GtIargType ARGT::Type()
  E.g. IargPrime, IargHostPtr, IargDevicePtr, IargTid, and other Iarg* types defined in the GTPin: High-Level Instrumentation (HLI) Parameters and Arguments section.
  For these types, the corresponding IGtIarg object is generated by the ARGT::Make() method

- Any valid prime type ARGT (IsValidHliPrimeType<ARGT>)
  These types are treated as IargPrime<ARGT>, e.g. int32_t => IargPrime<int32_t>; float => IargPrime<float>; enum E => IargPrime<enum E>; etc.

- The GtReg type
  This type is treated as IargPrime<GtReg>

- Any pointer pointer type ARGT (IsPointer<ARGT>)
  This type is treated as IargHostPtr, e.g. MyType* => IargHostPtr

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

bool gtpin::GtHliFunction< RET, PRMS >::InsertCallAtBbl | ( | IGtKernelInstrument & | instrumentor,
|  | const IGtBbl & | bbl,
|  | GtIpoint | ipoint,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Insert call to this HLI function with the specified argument values at the beginning/end of the specified BBL.

Insert a call to this HLI function with the specified argument values before/after the specified instruction.

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | ins | Instruction in the original code of the kernel
  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Relative location of the instrumentation point in the original code
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call

See also:
  GeneratePredicatedCall for the list of supported types of argument values

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

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

bool gtpin::GtHliFunction< RET, PRMS >::InsertCallAtInstruction | ( | IGtKernelInstrument & | instrumentor,
|  | const IGtIns & | ins,
|  | GtIpoint | ipoint,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Insert a call to this HLI function with the specified argument values before/after the specified instruction.

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | ins | Instruction in the original code of the kernel
  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Relative location of the instrumentation point in the original code
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call

See also:
  GeneratePredicatedCall for the list of supported types of argument values

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

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

bool gtpin::GtHliFunction< RET, PRMS >::InsertCallAtKernelEntries | ( | IGtKernelInstrument & | instrumentor,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Insert call to this HLI function with the specified argument values at all entries to the kernel.

Insert a call to this HLI function with the specified argument values before/after the specified instruction.

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | ins | Instruction in the original code of the kernel
  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Relative location of the instrumentation point in the original code
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call

See also:
  GeneratePredicatedCall for the list of supported types of argument values

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

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

bool gtpin::GtHliFunction< RET, PRMS >::InsertCallAtKernelExits | ( | IGtKernelInstrument & | instrumentor,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Insert call to this HLI function with the specified argument values at all exits of the kernel.

Insert a call to this HLI function with the specified argument values before/after the specified instruction.

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | ins | Instruction in the original code of the kernel
  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Relative location of the instrumentation point in the original code
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call

See also:
  GeneratePredicatedCall for the list of supported types of argument values

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

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

bool gtpin::GtHliFunction< RET, PRMS >::InsertPredicatedCallAtBbl | ( | IGtKernelInstrument & | instrumentor,
|  | const IGtBbl & | bbl,
|  | GtIpoint | ipoint,
|  | const GtPredicate & | predicate,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Insert call to this HLI function with the specified argument values at the beginning/end of the specified BBL.

Insert a call to this HLI function with the specified argument values before/after the specified instruction.

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | ins | Instruction in the original code of the kernel
  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Relative location of the instrumentation point in the original code
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call

See also:
  GeneratePredicatedCall for the list of supported types of argument values

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

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

bool gtpin::GtHliFunction< RET, PRMS >::InsertPredicatedCallAtInstruction | ( | IGtKernelInstrument & | instrumentor,
|  | const IGtIns & | ins,
|  | GtIpoint | ipoint,
|  | const GtPredicate & | predicate,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Insert a call to this HLI function with the specified argument values before/after the specified instruction.

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | ins | Instruction in the original code of the kernel
  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Relative location of the instrumentation point in the original code
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call

See also:
  GeneratePredicatedCall for the list of supported types of argument values

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

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

bool gtpin::GtHliFunction< RET, PRMS >::InsertPredicatedCallAtKernelEntries | ( | IGtKernelInstrument & | instrumentor,
|  | const GtPredicate & | predicate,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Insert call to this HLI function with the specified argument values at all entries to the kernel.

Insert a call to this HLI function with the specified argument values before/after the specified instruction.

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | ins | Instruction in the original code of the kernel
  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Relative location of the instrumentation point in the original code
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call

See also:
  GeneratePredicatedCall for the list of supported types of argument values

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

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

template<typename RET , typename... PRMS>
template<typename... ARGS>

bool gtpin::GtHliFunction< RET, PRMS >::InsertPredicatedCallAtKernelExits | ( | IGtKernelInstrument & | instrumentor,
|  | const GtPredicate & | predicate,
|  | const GtReg & | retReg,
|  | const ARGS &... | argValues
| ) |  | `[inline]`

Insert call to this HLI function with the specified argument values at all exits of the kernel.

Insert a call to this HLI function with the specified argument values before/after the specified instruction.

Parameters:

  [in] | instrumentor | Object that implements kernel instrumentation interface
  [in] | ins | Instruction in the original code of the kernel
  [in] | bbl | BBL in the original code of the kernel
  [in] | ipoint | Relative location of the instrumentation point in the original code
  [in] | predicate | Predicate of the generated code. Invalid predicate is ignored
  [in] | retReg | Register that receives return value. NULL register indicates that the return value is unused
  [in] | argValues | List of argument values of the function call

See also:
  GeneratePredicatedCall for the list of supported types of argument values

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

Precondition:
  sizeof... (ARGS) == sizeof... (PRMS)
  ARGS types are compatible with the corresponding PRMS types. See GtIargType::IsCompatible()

All Data Structures Functions Variables Typedefs Enumerations Enumerator

      Copyright (C) 2013-2025 Intel Corporation

      SPDX-License-Identifier: MIT