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

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()