GTPin: gtpin::IGtMemoryMapper Class Reference

GTPin

- Main Page
- Related Pages
- Modules
- Data Structures

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

Public Member Functions
gtpin::IGtMemoryMapper Class Reference
GTPin: Host-to-Device Memory Mapper

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

All Data Structures Functions Variables Typedefs Enumerations Enumerator

      Copyright (C) 2013-2025 Intel Corporation

      SPDX-License-Identifier: MIT