GTPin: gtpin::GtProfileArray Class Reference

GTPin

- Main Page
- Related Pages
- Modules
- Data Structures

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

Public Member Functions
gtpin::GtProfileArray Class Reference
Profile Buffer

Class that represents an array of data records in the profile buffer. More...

`#include <gt_profile_array.h>`

## Public Member Functions
| GtProfileArray ()
| Default constructor.
| GtProfileArray (uint32_t recordSize, uint32_t numRecords, uint32_t numThreadBuckets=1, uint32_t alignment=64)
| Constructor.
bool | Allocate (IGtProfileBufferAllocator &allocator)
| Reserve space required to store all chunks of this array in the profile buffer.
bool | Read (const IGtProfileBuffer &profileBuffer, void *records, uint32_t fistRecordNum, uint32_t numRecords=1, uint32_t threadBucketNum=0) const
| Read data from the specified records of this array in the profile buffer.
bool | Write (IGtProfileBuffer &profileBuffer, const void *records, uint32_t fistRecordNum, uint32_t numRecords=1, uint32_t threadBucketNum=0) const
| Write data into specified records of this array in the profile buffer (see the Read() parameters descriptions)
bool | Initialize (IGtProfileBuffer &profileBuffer) const
| Zero-initialize memory area allocated for this array in the specified profile buffer.
void | ComputeOffset (const IGtGenCoder &coder, IGtGenProcedure &proc, const GtReg &offsetReg, uint32_t recordNum=0, uint32_t offsetInRecord=0) const
| Generate code that computes offset/address within the specified record.
void | ComputeAddress (const IGtGenCoder &coder, IGtGenProcedure &proc, const GtReg &addrReg, uint32_t recordNum=0, uint32_t offsetInRecord=0) const
void | ComputeOffset (const IGtGenCoder &coder, IGtGenProcedure &proc, const GtReg &offsetReg, const GtReg &offsetInChunkReg, uint32_t offsetInRecord=0) const
void | ComputeAddress (const IGtGenCoder &coder, IGtGenProcedure &proc, const GtReg &addrReg, const GtReg &offsetInChunkReg, uint32_t offsetInRecord=0) const
void | ComputeRelAddress (const IGtGenCoder &coder, IGtGenProcedure &proc, const GtReg &addrReg, const GtReg &baseReg, int32_t offset) const
| Generate code that computes address of a (field) location within a record relative to the specified base address within the same record.
uint32_t | RecordOffset (uint32_t recordNum, uint32_t threadBucketNum) const
| Get offset of the specified record in the specified thread bucket, relative to the profile buffer base.
uint32_t | Size () const
| Return size of the memory block, in bytes.
GtProfileBufferOffset | Offset () const
| Return offset of the allocated memory block, or -1.
bool | IsAllocated () const
| Return true if this array has been allocated.
uint32_t | RecordSize () const
| Return size of the record, in bytes.
uint32_t | NumRecords () const
| Return number of data records in the array.
uint32_t | NumThreadBuckets () const
| Return number of thread buckets (chunks)
uint32_t | ChunkSize () const
| Return size of the per-bucket chunk, in bytes.

## Detailed Description

Class that represents an array of data records in the profile buffer.

The data can be collected in a single global array or distributed among multiple thread buckets each of which stores profile data in its own array (chunk)

Terminology:

- GTPin groups threads in buckets to minimize contention of concurrent memory accesses. Thread bucket is a group of threads that store their profile data in the same, shared memory block of the profile buffer. Threads that belong to different buckets use separate, not interleaving memory areas of the profile buffer, called chunks.
  The number of thread buckets (memory chunks) is a configurable value, determined by the tool. The valid range of this value is [1, max. number of HW threads]. To simplify code generation, GTPin requires number of thread buckets to be power-of-two.
  To map a thread into the corresponding thread bucket, GTPin applies some hash function to the thread ID.

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

## Constructor & Destructor Documentation

gtpin::GtProfileArray::GtProfileArray | ( | uint32_t | recordSize,
|  | uint32_t | numRecords,
|  | uint32_t | numThreadBuckets = `1`,
|  | uint32_t | alignment = `64`
| ) |  | `[inline]`

Constructor.

Parameters:

  [in] | recordSize | Size of the record in bytes
  [in] | numRecords | Number of data records in the array
  [in] | numThreadBuckets | Number of thread buckets each of which will collect profile data in its own array, called chunk (see 'Terminology' section). The value of this parameter always rounded up to the next power of two.
  [in] | alignment | Alignment of the array in the profile buffer; must be power of two

## Member Function Documentation

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

Reserve space required to store all chunks of this array in the profile buffer.

Parameters:

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

Returns:
  true - success, false - failure

Precondition:
  !IsAllocated()

void gtpin::GtProfileArray::ComputeAddress | ( | const IGtGenCoder & | coder,
|  | IGtGenProcedure & | proc,
|  | const GtReg & | addrReg,
|  | const GtReg & | offsetInChunkReg,
|  | uint32_t | offsetInRecord = `0`
| ) |  | const`[inline]`

Generate code that computes offset/address within the specified record.

Generate code that computes offset/address within a record that resides in the memory chunk of the currently running HW thread. The offset is relative to the profile buffer base.

Note:
  If both recordNum = 0 and offsetInRecord = 0, the generated code computes offset/address of the memory chunk associated with the currently running HW thread.

Parameters:

  [in] | coder | GEN code generator
  [in] | proc | Procedure, the generated code is appended to
  [in] | offsetReg | Register that receives the calculated offset within the profile buffer
  [in] | addrReg | Register that receives the calculated address
  [in] | recordNum | Ordinal number of the record
  [in] | offsetInChunkReg | 32-bit register that holds offset (of the record) relative to the chunk base
  [in] | offsetInRecord | Offset within the record

Precondition:
  IsAllocated() && (recordNum < NumRecords()) && (offsetInRecord < RecordSize())

void gtpin::GtProfileArray::ComputeAddress | ( | const IGtGenCoder & | coder,
|  | IGtGenProcedure & | proc,
|  | const GtReg & | addrReg,
|  | uint32_t | recordNum = `0`,
|  | uint32_t | offsetInRecord = `0`
| ) |  | const`[inline]`

Generate code that computes offset/address within the specified record.

Generate code that computes offset/address within a record that resides in the memory chunk of the currently running HW thread. The offset is relative to the profile buffer base.

Note:
  If both recordNum = 0 and offsetInRecord = 0, the generated code computes offset/address of the memory chunk associated with the currently running HW thread.

Parameters:

  [in] | coder | GEN code generator
  [in] | proc | Procedure, the generated code is appended to
  [in] | offsetReg | Register that receives the calculated offset within the profile buffer
  [in] | addrReg | Register that receives the calculated address
  [in] | recordNum | Ordinal number of the record
  [in] | offsetInChunkReg | 32-bit register that holds offset (of the record) relative to the chunk base
  [in] | offsetInRecord | Offset within the record

Precondition:
  IsAllocated() && (recordNum < NumRecords()) && (offsetInRecord < RecordSize())

void gtpin::GtProfileArray::ComputeOffset | ( | const IGtGenCoder & | coder,
|  | IGtGenProcedure & | proc,
|  | const GtReg & | offsetReg,
|  | uint32_t | recordNum = `0`,
|  | uint32_t | offsetInRecord = `0`
| ) |  | const`[inline]`

Generate code that computes offset/address within the specified record.

Generate code that computes offset/address within a record that resides in the memory chunk of the currently running HW thread. The offset is relative to the profile buffer base.

Note:
  If both recordNum = 0 and offsetInRecord = 0, the generated code computes offset/address of the memory chunk associated with the currently running HW thread.

Parameters:

  [in] | coder | GEN code generator
  [in] | proc | Procedure, the generated code is appended to
  [in] | offsetReg | Register that receives the calculated offset within the profile buffer
  [in] | addrReg | Register that receives the calculated address
  [in] | recordNum | Ordinal number of the record
  [in] | offsetInChunkReg | 32-bit register that holds offset (of the record) relative to the chunk base
  [in] | offsetInRecord | Offset within the record

Precondition:
  IsAllocated() && (recordNum < NumRecords()) && (offsetInRecord < RecordSize())

void gtpin::GtProfileArray::ComputeOffset | ( | const IGtGenCoder & | coder,
|  | IGtGenProcedure & | proc,
|  | const GtReg & | offsetReg,
|  | const GtReg & | offsetInChunkReg,
|  | uint32_t | offsetInRecord = `0`
| ) |  | const`[inline]`

Generate code that computes offset/address within the specified record.

Generate code that computes offset/address within a record that resides in the memory chunk of the currently running HW thread. The offset is relative to the profile buffer base.

Note:
  If both recordNum = 0 and offsetInRecord = 0, the generated code computes offset/address of the memory chunk associated with the currently running HW thread.

Parameters:

  [in] | coder | GEN code generator
  [in] | proc | Procedure, the generated code is appended to
  [in] | offsetReg | Register that receives the calculated offset within the profile buffer
  [in] | addrReg | Register that receives the calculated address
  [in] | recordNum | Ordinal number of the record
  [in] | offsetInChunkReg | 32-bit register that holds offset (of the record) relative to the chunk base
  [in] | offsetInRecord | Offset within the record

Precondition:
  IsAllocated() && (recordNum < NumRecords()) && (offsetInRecord < RecordSize())

void gtpin::GtProfileArray::ComputeRelAddress | ( | const IGtGenCoder & | coder,
|  | IGtGenProcedure & | proc,
|  | const GtReg & | addrReg,
|  | const GtReg & | baseReg,
|  | int32_t | offset
| ) |  | const`[inline]`

Generate code that computes address of a (field) location within a record relative to the specified base address within the same record.

Parameters:

  [in] | coder | GEN code generator
  [in] | proc | Procedure, the generated code is appended to
  [in] | addrReg | Register that receives the calculated address
  [in] | baseReg | Register that holds an address within the record
  [in] | offset | Offset within the record, relative to 'baseReg'

bool gtpin::GtProfileArray::Initialize | ( | IGtProfileBuffer & | profileBuffer | ) | const`[inline]`

Zero-initialize memory area allocated for this array in the specified profile buffer.

Parameters:

  [in] | profileBuffer | Profile buffer in which this array is allocated

Returns:
  true - success, false - failure

Precondition:
  IsAllocated()

bool gtpin::GtProfileArray::Read | ( | const IGtProfileBuffer & | profileBuffer,
|  | void * | records,
|  | uint32_t | fistRecordNum,
|  | uint32_t | numRecords = `1`,
|  | uint32_t | threadBucketNum = `0`
| ) |  | const`[inline]`

Read data from the specified records of this array in the profile buffer.

Parameters:

  [in] | profileBuffer | Profile buffer to read records from
  [in] | records | Pointer to an array that receives records from the profile buffer. The size of this array should be at least (numRecords * RecordSize()) bytes.
  [in] | threadBucketNum | Ordinal number of the thread bucket (memory chunk) to read records from
  [in] | fistRecordNum | Ordinal number of the first record to read
  [in] | numRecords | Number of records to read

Returns:
  true - success, false - failure

Precondition:
  IsAllocated() && (threadBucketNum < NumThreadBuckets()) && (fistRecordNum + numRecords <= NumRecords())

uint32_t gtpin::GtProfileArray::RecordOffset | ( | uint32_t | recordNum,
|  | uint32_t | threadBucketNum
| ) |  | const`[inline]`

Get offset of the specified record in the specified thread bucket, relative to the profile buffer base.

Parameters:

  [in] | recordNum | Ordinal number of the record
  [in] | threadBucketNum | Ordinal number of the thread bucket

Returns:
  Offset of the specified record

Precondition:
  IsAllocated() && (threadBucketNum < NumThreadBuckets()) && (recordNum < NumRecords())

bool gtpin::GtProfileArray::Write | ( | IGtProfileBuffer & | profileBuffer,
|  | const void * | records,
|  | uint32_t | fistRecordNum,
|  | uint32_t | numRecords = `1`,
|  | uint32_t | threadBucketNum = `0`
| ) |  | const`[inline]`

Write data into specified records of this array in the profile buffer (see the Read() parameters descriptions)

Returns:
  true - success, false - failure

Precondition:
  IsAllocated() && (threadBucketNum < NumThreadBuckets()) && (fistRecordNum + numRecords <= NumRecords())

All Data Structures Functions Variables Typedefs Enumerations Enumerator

      Copyright (C) 2013-2025 Intel Corporation

      SPDX-License-Identifier: MIT