gtpin::IGtMemoryMapper Class Reference

Class that provides the host-to-device memory mapping service. This feature enables transparent data sharing between host and device address spaces. More...

#include <igt_memory_mapper.h>

Public Member Functions
virtual GtProfileBufferOffset	Map (const void *base, uint32_t size, GtMmapMethod mapMethod=GT_MMAP_SHARE, uint32_t alignment=8)=0
	Reserve a memory block of the specified size in the profile buffer.
virtual bool	Read (void *dst, uint32_t size=0) const =0
	Given a memory block [dst, size] mapped into profile buffer, copy the corresponding buffer content to the host block.
virtual bool	Write (const void *src, uint32_t size=0) const =0
	Given a memory block [src, size] mapped into profile buffer, copy its content to the corresponding location within profile buffer.
virtual GtProfileBufferOffset	GetBufferOffset (const void *ptr) const =0
	Find a location in the profile buffer, the specified address is mapped to.
template<typename T >
GtProfileBufferOffset	Map (const T &var, GtMmapMethod mapMethod=GT_MMAP_SHARE)
	Template variant of the virtual Map function.
template<typename E >
GtProfileBufferOffset	Map (const Span< E > &var, GtMmapMethod mapMethod=GT_MMAP_SHARE)
	Specialization of Map<T> method for T = Span<E>
template<typename E >
GtProfileBufferOffset	Map (const std::vector< E > &var, GtMmapMethod mapMethod=GT_MMAP_SHARE)
	Specialization of Map<T> method for T = std::vector<E>

---

Detailed Description

Class that provides the host-to-device memory mapping service. This feature enables transparent data sharing between host and device address spaces.

This mechanism is especially useful in mapping arguments of HLI functions. These functions are executed by a GPU device, so all pointer parameters of the function should refer to objects in the profile buffer. However, for tools that define instrumentation functions in the host (CPU) space, addresses in the device space are unknown.
The host-to-device memory mapping interface allows tools to specify host pointers in function arguments, and instruct GTPin to copy the referenced objects to/from the profile buffer in the device address space.

---

Member Function Documentation

virtual GtProfileBufferOffset gtpin::IGtMemoryMapper::GetBufferOffset

(

const void *

ptr

)

const [pure virtual]

Find a location in the profile buffer, the specified address is mapped to.

Parameters:

[in]

ptr

An address in the host memory

Returns:

Offset in the profile buffer, the specified address is mapped to, or invalid GtProfileBufferOffset value if 'ptr' does not belong in any mapped memory block

Note:

The function returns correct offset even if 'ptr' is not a base address of a mapped block but belongs in some mapped block

Availability:

• Any IGtTool callback

virtual GtProfileBufferOffset gtpin::IGtMemoryMapper::Map	(	const void *	base,
		uint32_t	size,
		GtMmapMethod	mapMethod = GT_MMAP_SHARE,
		uint32_t	alignment = 8
	)		[pure virtual]

Reserve a memory block of the specified size in the profile buffer.

Establish the specified sharing relation between [base, size] memory range in the host address space and the reserved memory block in the device address space.

Parameters:

[in]	base	Base address of the host memory range to be mapped
[in]	size	Size of the memory range to be mapped, in bytes
[in]	mapMethod	The method of the memory mapping and sharing
[in]	alignment	Minimal alignment of the memory block in the profile buffer. Must be power of two, not exceeding page size

Returns:

Offset of the block allocated in the profile buffer, or -1 if mapping failed. In case of error, the IGtCore::LastError() function provides the specific failure reason

Availability:

• IGtTool::OnKernelBuild

template<typename T >

GtProfileBufferOffset gtpin::IGtMemoryMapper::Map	(	const T &	var,
		GtMmapMethod	mapMethod = GT_MMAP_SHARE
	)		[inline]

Template variant of the virtual Map function.

Parameters:

	T	Trivially copyable type
[in]	var	Variable to be mapped
[in]	mapMethod	The method of the memory mapping and sharing

Returns:

Offset of the block allocated in the profile buffer, or -1 if mapping failed.

Availability:

• Any callback that provides IGtMemoryMapper

virtual bool gtpin::IGtMemoryMapper::Read	(	void *	dst,
		uint32_t	size = 0
	)		const [pure virtual]

Given a memory block [dst, size] mapped into profile buffer, copy the corresponding buffer content to the host block.

This function provides convenient access to mapped but not shared memory blocks (GT_MMAP_NO_SHARE). All other sharing methods synchronize mapped blocks automatically.
The specified address range must be entirely contained in a single host memory block mapped by the Map function.

Parameters:

[in]	dst	Destination address in the host memory
[in]	size	Number of bytes to copy. If this parameter is omitted (equal to zero), the entire mapped memory block that contains 'dst' is copied

Returns:

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

Availability:

• IGtTool::OnKernelRun
• IGtTool::OnKernelComplete

virtual bool gtpin::IGtMemoryMapper::Write	(	const void *	src,
		uint32_t	size = 0
	)		const [pure virtual]

Given a memory block [src, size] mapped into profile buffer, copy its content to the corresponding location within profile buffer.

This function provides convenient access to mapped but not shared memory blocks (GT_MMAP_NO_SHARE). All other sharing methods synchronize mapped blocks automatically.
The specified address range must be entirely contained in a single host memory block mapped by the Map function.

Parameters:

[in]	src	Source address in the host memory
[in]	size	Number of bytes to copy. If this parameter is omitted (equal to zero), the entire mapped memory block that contains 'src' is copied

Returns:

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

Availability:

• IGtTool::OnKernelRun
• IGtTool::OnKernelComplete