GTPin: gtpin::GtProfileTrace Class Reference

GTPin

- Main Page
- Related Pages
- Modules
- Data Structures

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

Public Member Functions
gtpin::GtProfileTrace Class Reference
Profile Buffer

Class that represents a trace - sequence of data records chronologically collected and stored in the profile buffer. More...

`#include <gt_profile_trace.h>`

## Public Member Functions
| GtProfileTrace ()
| Default constructor.
| GtProfileTrace (uint32_t maxTraceSize, uint32_t maxRecordSize, uint32_t maxThreads=0x1000, uint32_t alignment=64)
| Constructor.
bool | Allocate (IGtProfileBufferAllocator &allocator)
| Reserve space required to store the trace in the profile buffer.
uint32_t | Size (const IGtProfileBuffer &profileBuffer) const
| Get Size of the trace collected in the profile buffer.
bool | IsTruncated (const IGtProfileBuffer &profileBuffer) const
| Return true, if the trace collected in the specified profile buffer has been trimmed to avoid buffer overflow.
bool | Read (const IGtProfileBuffer &profileBuffer, void *data, uint32_t offset, uint32_t size) const
| Read data from the trace located in the specified profile buffer.
bool | Write (IGtProfileBuffer &profileBuffer, const void *data, uint32_t offset, uint32_t size) const
| Write data into the trace located in the specified profile buffer.
bool | Initialize (IGtProfileBuffer &profileBuffer, bool zeroInitRecords=true) const
| Initialize the trace header in the specified profile buffer and, optionally, zero-initialize the memory area allocated for trace records.
void | ComputeNewRecordOffset (const IGtGenCoder &coder, IGtGenProcedure &proc, uint32_t recordSize, const GtReg &offsetReg, uint32_t offsetInRecord=0) const
| Generate code that allocates space for the new record in the trace, and computes offset/address within the record.
void | ComputeNewRecordAddress (const IGtGenCoder &coder, IGtGenProcedure &proc, uint32_t recordSize, const GtReg &addrReg, uint32_t offsetInRecord=0) const
uint32_t | MaxTraceSize () const
| Return maximum size of the trace, in bytes.
uint32_t | MaxRecordSize () const
| Return maximum size of the trace record, in bytes.
bool | IsAllocated () const
| Return true if this trace has been allocated.

## Detailed Description

Class that represents a trace - sequence of data records chronologically collected and stored in the profile buffer.

Availability:
  - IGtTool::OnKernelBuild
  - IGtTool::OnKernelRun
  - IGtTool::OnKernelComplete

## Constructor & Destructor Documentation

gtpin::GtProfileTrace::GtProfileTrace | ( | uint32_t | maxTraceSize,
|  | uint32_t | maxRecordSize,
|  | uint32_t | maxThreads = `0x1000`,
|  | uint32_t | alignment = `64`
| ) |  | `[inline]`

Constructor.

Parameters:

  [in] | maxTraceSize | Maximum size of the trace, in bytes
  [in] | maxRecordSize | Maximum size of the trace record, in bytes. The record size is variable, not exceeding maxRecordSize bytes
  [in] | maxThreads | Maximum number of threads concurrently accessing the trace
  [in] | alignment | Alignment of the trace in the profile buffer; must be power of two

## Member Function Documentation

bool gtpin::GtProfileTrace::Allocate | ( | IGtProfileBufferAllocator & | allocator | ) | `[inline]`

Reserve space required to store the trace in the profile buffer.

Parameters:

  [in] | allocator | Allocator to be used to reserve space

Returns:
  true - success, false - failure

Precondition:
  !IsAllocated()

void gtpin::GtProfileTrace::ComputeNewRecordAddress | ( | const IGtGenCoder & | coder,
|  | IGtGenProcedure & | proc,
|  | uint32_t | recordSize,
|  | const GtReg & | addrReg,
|  | uint32_t | offsetInRecord = `0`
| ) |  | const`[inline]`

Generate code that allocates space for the new record in the trace, and computes offset/address within the record.

The offset is relative to the profile buffer base. If new record can not be allocated due to the trace capacity limitations, the generated procedure sets f0.0:uw bits on. Otherwise, these bit are cleared off.

Parameters:

  [in] | coder | GEN code generator
  [in] | proc | Procedure, the generated code is appended to
  [in] | recordSize | Size of the new record, in bytes
  [in] | offsetReg | Register that receives the calculated offset within the profile buffer
  [in] | addrReg | Register that receives the calculated address
  [in] | offsetInRecord | Offset within the record

Precondition:
  IsAllocated() && (recordSize <= MaxRecordSize())

void gtpin::GtProfileTrace::ComputeNewRecordOffset | ( | const IGtGenCoder & | coder,
|  | IGtGenProcedure & | proc,
|  | uint32_t | recordSize,
|  | const GtReg & | offsetReg,
|  | uint32_t | offsetInRecord = `0`
| ) |  | const`[inline]`

Generate code that allocates space for the new record in the trace, and computes offset/address within the record.

The offset is relative to the profile buffer base. If new record can not be allocated due to the trace capacity limitations, the generated procedure sets f0.0:uw bits on. Otherwise, these bit are cleared off.

Parameters:

  [in] | coder | GEN code generator
  [in] | proc | Procedure, the generated code is appended to
  [in] | recordSize | Size of the new record, in bytes
  [in] | offsetReg | Register that receives the calculated offset within the profile buffer
  [in] | addrReg | Register that receives the calculated address
  [in] | offsetInRecord | Offset within the record

Precondition:
  IsAllocated() && (recordSize <= MaxRecordSize())

bool gtpin::GtProfileTrace::Initialize | ( | IGtProfileBuffer & | profileBuffer,
|  | bool | zeroInitRecords = `true`
| ) |  | const`[inline]`

Initialize the trace header in the specified profile buffer and, optionally, zero-initialize the memory area allocated for trace records.

Parameters:

  [in] | profileBuffer | Profile buffer in which this trace is allocated
  [in] | zeroInitRecords | true - zero-initialize the memory area allocated for trace records false - leave trace records uninitialized

Returns:
  true - success, false - failure

Precondition:
  IsAllocated()

bool gtpin::GtProfileTrace::Read | ( | const IGtProfileBuffer & | profileBuffer,
|  | void * | data,
|  | uint32_t | offset,
|  | uint32_t | size
| ) |  | const`[inline]`

Read data from the trace located in the specified profile buffer.

Parameters:

  [in] | profileBuffer | Profile buffer in which this trace is allocated
  [in] | data | Pointer to an array of bytes that receives data from the trace. There are should be at least 'size' bytes in this array
  [in] | offset | Offset within the trace of the first byte to read from
  [in] | size | Number of bytes to read from the trace into 'data' array

Returns:
  true - success, false - failure

Precondition:
  IsAllocated() && (offset + size <= MaxTraceSize())

uint32_t gtpin::GtProfileTrace::Size | ( | const IGtProfileBuffer & | profileBuffer | ) | const`[inline]`

Get Size of the trace collected in the profile buffer.

Precondition:
  IsAllocated()

Returns:
  Actual size of the trace collected in the specified profile buffer

bool gtpin::GtProfileTrace::Write | ( | IGtProfileBuffer & | profileBuffer,
|  | const void * | data,
|  | uint32_t | offset,
|  | uint32_t | size
| ) |  | const`[inline]`

Write data into the trace located in the specified profile buffer.

Parameters:

  [in] | profileBuffer | Profile buffer in which this trace is allocated
  [in] | data | Pointer to an array of bytes that holds data to be written. There are should be at least 'size' bytes in this array
  [in] | offset | Offset within the trace of the first byte to write into
  [in] | size | Number of bytes to write from 'data' array into the trace

Returns:
  true - success, false - failure

Precondition:
  IsAllocated() && (offset + size <= MaxTraceSize())

All Data Structures Functions Variables Typedefs Enumerations Enumerator

      Copyright (C) 2013-2025 Intel Corporation

      SPDX-License-Identifier: MIT