gtpin::IGtKernelDispatch Class Reference

Interface that controls kernel execution, from submission to completion. More...

#include <igt_kernel.h>

Public Member Functions
virtual const IGtKernel &	Kernel () const =0
	Get IGtKernel object associated with this kernel instance.
virtual GtKernelExecStage	ExecStage () const =0
	Get the current execution stage of this kernel instance.
bool	IsCompleted () const
	Check to see whether this kernel instance has already finished execution.
virtual IGtProfileBuffer *	CreateProfileBuffer ()=0
	Create the profile data storage for this kernel instance, or return pointer to existing, earlier created buffer.
virtual IGtProfileBuffer *	GetProfileBuffer ()=0
	Get profile buffer associated with this kernel instance.
virtual IGtMemoryMapper &	MemoryMapper ()=0
	Get IGtMemoryMapper object associated with this kernel instance.
virtual void	GetExecDescriptor (GtKernelExecDesc &execDesc) const =0
	Get execution descriptor associated with this kernel instance.
virtual void	SetProfilingMode (bool enabled)=0
	Configure GTPin/driver to run either instrumented or original version of the kernel function.
virtual bool	IsProfilingEnabled () const =0
	Check to see whether this kernel instance runs instrumented code.
virtual uint64_t	DispatchId () const =0
virtual bool	ReportFinalDispatchStage ()=0
	Request GTPin to invoke the IGtTool::OnKernelRun callback one more time, as close as possible to the actual execution of the kernel in GPU.
virtual ConstByteSpan	GetPayloadArgumentValue (uint32_t argIndex) const =0
	Get value of the specified payload argument in this kernel dispatch.
virtual GtMemoryBufferConstSpan	GetAllocatedBuffers () const =0
virtual uint32_t	ScratchSpaceSize () const =0
virtual uint32_t	SlmSize () const =0

---

Detailed Description

Interface that controls kernel execution, from submission to completion.

Application can submit (dispatch) the same kernel multiple times, and each such dispatch can be configured to run either instrumented or original version of the kernel function. The IGtKernelDispatch interface provides such functionality.
Additionally, the tool, that chooses the instrumented version of the kernel, can use this interface to allocate and assign the profile buffer for the kernel instance being submitted.

Note:

The lifetime of the IGtKernelDispatch object is limited - it is created before the kernel dispatch, and destroyed after the kernel completion. The tool should not attempt to access the IGtKernelDispatch object after processing the corresponding IGtTool::OnKernelComplete callback.

Availability:

• IGtTool::OnKernelRun
• IGtTool::OnKernelComplete

---

Member Function Documentation

virtual IGtProfileBuffer* gtpin::IGtKernelDispatch::CreateProfileBuffer

(

)

[pure virtual]

Create the profile data storage for this kernel instance, or return pointer to existing, earlier created buffer.

Returns:

Pointer to the profile data storage of this kernel instance

Precondition:

ExecStage().IsDispatch()

virtual uint64_t gtpin::IGtKernelDispatch::DispatchId

(

)

const [pure virtual]

Returns:

Unique ID of the kernel dispatch assigned by GTPin. It can be used to match OnKernelRun and OnKernelComplete callbacks associated with the same kernel dispatch.

virtual GtKernelExecStage gtpin::IGtKernelDispatch::ExecStage

(

)

const [pure virtual]

Get the current execution stage of this kernel instance.

Returns:

Current execution stage of this kernel instance

virtual GtMemoryBufferConstSpan gtpin::IGtKernelDispatch::GetAllocatedBuffers

(

)

const [pure virtual]

Returns:

Sequence of buffers, allocated in the global memory and available to the kernel. The returned sequence does not include profile buffer of the instrumented kernel. It comprises buffers available to the original kernel only. In case of error, the IGtCore::LastError() function provides the specific failure reason.

Note:

Application can allocate memory buffers for the kernel at any point until the final dispatch stage. So, it is recommended to use the GetAllocatedBuffers() function in the 'late' dispatch callback, if supported by the runtime platform.

Precondition:

!IsCompleted()

virtual void gtpin::IGtKernelDispatch::GetExecDescriptor

(

GtKernelExecDesc &

execDesc

)

const [pure virtual]

Get execution descriptor associated with this kernel instance.

Parameters:

[out]

execDesc

Structure that receives execution descriptor

virtual ConstByteSpan gtpin::IGtKernelDispatch::GetPayloadArgumentValue

(

uint32_t

argIndex

)

const [pure virtual]

Get value of the specified payload argument in this kernel dispatch.

Parameters:

[in]

argIndex

Index of an explicit argument in the kernel payload. This must be a valid GtKernelArgument::index value of an argument descriptor, from the Kernel().PayloadArguments() sequence. The valid value of this parameter is less than Kernel().NumExplicitPayloadArguments().

Returns:

The argument value in the form of a raw byte sequence. The returned sequence is empty if queried argument does not exist, or the kernel payload is unknown to GTPin. The byte span { nullptr, size } stands for the null value of the specified size. In case of error, the IGtCore::LastError() function provides the specific failure reason.

Precondition:

!IsCompleted()

argIndex < Kernel().NumExplicitPayloadArguments()

virtual IGtProfileBuffer* gtpin::IGtKernelDispatch::GetProfileBuffer

(

)

[pure virtual]

Get profile buffer associated with this kernel instance.

Returns:

Pointer to the profile data storage of this kernel instance, or nullptr if no profile buffer was created for this instance.

bool gtpin::IGtKernelDispatch::IsCompleted

(

)

const [inline]

Check to see whether this kernel instance has already finished execution.

Returns:

true, if this kernel instance has completed execution

virtual bool gtpin::IGtKernelDispatch::IsProfilingEnabled

(

)

const [pure virtual]

Check to see whether this kernel instance runs instrumented code.

Returns:

true/false, for the kernel instance that is configured to run instrumented/original code.

virtual const IGtKernel& gtpin::IGtKernelDispatch::Kernel

(

)

const [pure virtual]

Get IGtKernel object associated with this kernel instance.

Returns:

Reference to the object that represents a kernel function being compiled/instrumented

virtual IGtMemoryMapper& gtpin::IGtKernelDispatch::MemoryMapper

(

)

[pure virtual]

Get IGtMemoryMapper object associated with this kernel instance.

Returns:

Object that provides host-to-device memory mapping service

virtual bool gtpin::IGtKernelDispatch::ReportFinalDispatchStage

(

)

[pure virtual]

Request GTPin to invoke the IGtTool::OnKernelRun callback one more time, as close as possible to the actual execution of the kernel in GPU.

On plaforms, where the kernel dispatch can be logically divided on stages, the tool may request additional IGtTool::OnKernelRun callback to be invoked on the FINAL_DISPATCH stage of the dispatch process. This additional callback can be helpful if kernel state changes during dispatch stages are important to the tool, e.g. if it uses the GetAllocatedBuffers function.

Returns:

true - the request is accepted; false - the platform does not support multiple dispatch stages. If function returns false, no callbacks will be invoked on the FINAL_DISPATCH stage.

Precondition:

ExecStage().IsDispatch()

virtual uint32_t gtpin::IGtKernelDispatch::ScratchSpaceSize

(

)

const [pure virtual]

Returns:

Size, in bytes, of the per-thread scratch space (PTSS) available to the kernel

virtual void gtpin::IGtKernelDispatch::SetProfilingMode

(

bool

enabled

)

[pure virtual]

Configure GTPin/driver to run either instrumented or original version of the kernel function.

Parameters:

[in]

enabled

true - run instrumented version; false - original

Precondition:

ExecStage().IsDispatch()

virtual uint32_t gtpin::IGtKernelDispatch::SlmSize

(

)

const [pure virtual]

Returns:

Size, in bytes, of the local memory (SLM) available to the kernel's work group