gtpin::IGtKernelInstrument Class Reference

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