AI/rocm-systems
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor API reference docs (#1125)

Browse Source 
* Refactor API reference docs

* refactor API ref docs

* corrections

* consistent naming

* updates

* Update CHANGELOG.md

* improving SEO

* improving SEO

* Update using-rocprofv3.rst

* Update counter_collection_services.md

* Update using-rocprofv3.rst

* Fixing doc build errors

* changelogs and some formatting issues

---------

Co-authored-by: Gopesh Bhardwaj <gopesh.bhardwaj@amd.com>
This commit is contained in:
srawat
2024-10-30 19:39:08 +05:30
committed by GitHub
parent 762ca819cf
commit 4204042ac6
12 changed files with 412 additions and 354 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/docs/api-reference/buffered_services.md
+62 -75
View File
@@ -1,22 +1,23 @@
# Buffered services
---
myst:
html_meta:
"description": "ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software."
"keywords": "ROCprofiler-SDK API reference, ROCprofiler-SDK buffered services, Buffered services API"
---
For the buffered approach, supported buffer record categories are enumerated in `rocprofiler_buffer_category_t` category field.
# ROCprofiler-SDK buffered services
## Overview
In the buffered approach, the internal (background) thread sends callbacks for batches of records.
Supported buffer record categories are enumerated in `rocprofiler_buffer_category_t` category field and supported buffer tracing services are enumerated in `rocprofiler_buffer_tracing_kind_t`. Configuring
a buffered tracing service requires buffer creation. Flushing the buffer implicitly or explicitly invokes a callback to the tool, which provides an array of one or more buffer records.
To flush a buffer explicitly, use `rocprofiler_flush_buffer` function.
In buffered approach, callbacks are received for batches of records from an internal (background) thread.
Supported buffered tracing services are enumerated in `rocprofiler_buffer_tracing_kind_t`. Configuring
a buffer tracing service requires the creation of a buffer. When the buffer is "flushed", either implicitly
or explicitly, a callback to the tool will be invoked which provides an array of one or more buffer records.
A buffer can be explicitly flushed via the `rocprofiler_flush_buffer` function.
## Subscribing to buffer tracing services
## Subscribing to Buffer Tracing Services
During tool initialization, the tool configures callback tracing using `rocprofiler_configure_buffer_tracing_service`
function. However, before invoking `rocprofiler_configure_buffer_tracing_service`, the tool must create a buffer for the tracing records as shown in the following section.
During tool initialization, tools configure callback tracing via the `rocprofiler_configure_buffer_tracing_service`
function. However, before invoking `rocprofiler_configure_buffer_tracing_service`, the tool must create a buffer
for the tracing records.
### Creating a Buffer
### Creating a buffer
```cpp
rocprofiler_status_t
@@ -29,49 +30,40 @@ rocprofiler_create_buffer(rocprofiler_context_id_t context,
rocprofiler_buffer_id_t* buffer_id);
```
The `size` parameter is the size of the buffer in bytes and will be rounded up to the nearest
memory page size (defined by `sysconf(_SC_PAGESIZE)`); the default memory page size on Linux
Here are the parameters required to create a buffer:
- `size`: Size of the buffer in bytes, which is rounded up to the nearest
memory page size (defined by `sysconf(_SC_PAGESIZE)`). The default memory page size on Linux
is 4096 bytes (4 KB).
The `watermark` parameter specifies the number of bytes at which
the buffer should be "flushed", i.e. when the records in the buffer should invoke the
`callback` parameter to deliver the records to the tool. For example, if a buffer has a size
of 4096 bytes and the watermark is set to 48 bytes, six 8-byte records can be placed in the
- `watermark`: Specifies the number of bytes at which the buffer should be flushed. To flush the buffer, the records in the buffer must invoke the `callback` parameter to deliver the records to the tool. For example, for a buffer of size 4096 bytes with the watermark set to 48 bytes, six 8-byte records can be placed in the
buffer before `callback` is invoked. However, every 64-byte record that is placed in the
buffer will trigger a flush. It is safe to set the `watermark` to any value between
zero and the buffer size.
The `policy` parameter specifies the behavior for when a record is larger than the
amount of free space in the current buffer. For example, if a buffer has a size of
4000 bytes with a watermark set to 4000 bytes and 3998 of the bytes in the buffer
have been populated with records, the `policy` dictates how to handle an incoming record >
2 bytes. The `ROCPROFILER_BUFFER_POLICY_DISCARD` policy dictates that all records greater
than should 2 bytes should be dropped until the tool _explicitly_ flushes the buffer via
a `rocprofiler_flush_buffer` function call whereas the `ROCPROFILER_BUFFER_POLICY_LOSSLESS`
policy dictates that the current buffer should be swapped out for an empty buffer and placed
in that new buffer and former (full) buffer should be _implicitly_ flushed.
- `policy`: Specifies the behavior when a record is larger than the
amount of free space in the current buffer. For example, for a buffer of size 4000 bytes with the watermark set to 4000 bytes and 3998 bytes populated with records, the `policy` dictates how to handle an incoming record greater than 2 bytes. If the environment variable `ROCPROFILER_BUFFER_POLICY_DISCARD` is enabled, all records greater than 2 bytes are dropped until the tool _explicitly_ flushes the buffer using `rocprofiler_flush_buffer` function call whereas, if the environment variable `ROCPROFILER_BUFFER_POLICY_LOSSLESS` is enabled, the current buffer is swapped out for an empty buffer and placed in the new buffer while the former (full) buffer is _implicitly_ flushed.
The `callback` parameter is the function that rocprofiler-sdk should invoke when flushing
the buffer; the value of the `callback_data` parameter will be passed as one of the arguments
to the `callback` function.
- `callback`: Invoked to flush the buffer.
The `buffer_id` parameter is an output parameter for the function call and will have a
- `callback_data`: Value passed as one of the arguments to the `callback` function.
- `buffer_id`: Output parameter for the function call to contain a
non-zero handle field after successful buffer creation.
### Creating a Dedicated Thread for Buffer Callbacks
### Creating a dedicated thread for buffer callbacks
By default, all buffers will use the same (default) background thread created by rocprofiler-sdk to
invoke their callback. However, rocprofiler-sdk provides an interface for tools to specify the
creation of an additional background thread for one or more of their buffers.
By default, all buffers use the same (default) background thread created by ROCprofiler-SDK to
invoke their callback. However, ROCprofiler-SDK provides an interface to allow the tools to create an additional background thread for one or more of their buffers.
Callback threads for buffers are created via the `rocprofiler_create_callback_thread` function:
To create callback threads for buffers, use `rocprofiler_create_callback_thread` function:
```cpp
rocprofiler_status_t
rocprofiler_create_callback_thread(rocprofiler_callback_thread_t* cb_thread_id);
```
Buffers are assigned to that callback thread via the `rocprofiler_assign_callback_thread` function:
To assign buffers to that callback thread, use `rocprofiler_assign_callback_thread` function:
```cpp
rocprofiler_status_t
@@ -79,7 +71,7 @@ rocprofiler_assign_callback_thread(rocprofiler_buffer_id_t buffer_id,
rocprofiler_callback_thread_t cb_thread_id);
```
#### Buffer Callback Thread Creation and Assignment Example
**Example:**
```cpp
{
@@ -101,7 +93,9 @@ rocprofiler_assign_callback_thread(rocprofiler_buffer_id_t buffer_id,
}
```
### Configuring Buffer Tracing Services
### Configuring buffer tracing services
To configure buffer tracing services, use:
```cpp
rocprofiler_status_t
@@ -112,20 +106,21 @@ rocprofiler_configure_buffer_tracing_service(rocprofiler_context_id_t c
rocprofiler_buffer_id_t buffer_id);
```
The `kind` parameter is a high-level specifier of which service to trace (also known as a "domain").
Domain examples include, but are not limited to, the HIP API, the HSA API, and kernel dispatches.
For each domain, there are (often) various "operations", which can be used to restrict the callbacks
to a subset within the domain. For domains which correspond to APIs, the "operations" are the functions
which compose the API. If all operations in a domain should be traced, the `operations` and `operations_count`
parameters can be set to `nullptr` and `0`, respectively. If the tracing domain should be restricted to a subset
of operations, the tool library should specify a C-array of type `rocprofiler_tracing_operation_t` and the
size of the array for the `operations` and `operations_count` parameter.
Here are the parameters required to configure buffer tracing services:
Similar to `rocprofiler_configure_callback_tracing_service`,
`rocprofiler_configure_buffer_tracing_service` will return an error if a buffer service for given context
and given domain is configured more than once.
- `kind`: A high-level specification of the services to be traced. This parameter is also known as "domain".
Domain examples include, but not limited to, the HIP API, HSA API, and kernel dispatches.
#### Example
- `operations`: For each domain, there are often various `operations` that can be used to restrict the callbacks to a subset within the domain. For domains corresponding to APIs, the `operations` are the functions
composing the API. To trace all operations in a domain, set the `operations` and `operations_count`
parameters to `nullptr` and `0` respectively. To restrict the tracing domain to a subset
of operations, the tool library must specify a C-array of type `rocprofiler_tracing_operation_t` for `operations` and size of the array for the `operations_count` parameter.
Similar to the `rocprofiler_configure_callback_tracing_service`,
`rocprofiler_configure_buffer_tracing_service` returns an error if a buffer service for the specified context
and domain is configured more than once.
**Example:**
```cpp
{
@@ -158,9 +153,9 @@ and given domain is configured more than once.
}
```
## Buffer Tracing Callback Function
## Buffer tracing callback function
Rocprofiler-sdk buffer tracing callback functions have the signature:
Here is the buffer tracing callback function:
```cpp
typedef void (*rocprofiler_buffer_tracing_cb_t)(rocprofiler_context_id_t context,
@@ -171,20 +166,14 @@ typedef void (*rocprofiler_buffer_tracing_cb_t)(rocprofiler_context_id_t co
uint64_t drop_count);
```
The `rocprofiler_record_header_t` data type provides three pieces of information:
The `rocprofiler_record_header_t` data type contains the following information:
1. Category (`rocprofiler_buffer_category_t`)
2. Kind
3. Payload
- `category` (`rocprofiler_buffer_category_t`): The `category` is used to classify the buffer record. For all
services configured via `rocprofiler_configure_buffer_tracing_service`, the `category` is equal to the value of `ROCPROFILER_BUFFER_CATEGORY_TRACING`. The other available categories are `ROCPROFILER_BUFFER_CATEGORY_PC_SAMPLING` and `ROCPROFILER_BUFFER_CATEGORY_COUNTERS`.
The category is used to distinguish the classification of the buffer record. For all
services configured via `rocprofiler_configure_buffer_tracing_service`, the category will
be equal to the value of `ROCPROFILER_BUFFER_CATEGORY_TRACING`. The meaning of the kind
field is dependent on the category but when the category is `ROCPROFILER_BUFFER_CATEGORY_TRACING`,
the kind value will be equivalent to the is used
to distinguish the `rocprofiler_buffer_tracing_kind_t` value passed to
`rocprofiler_configure_buffer_tracing_service`, e.g. `ROCPROFILER_BUFFER_TRACING_KERNEL_DISPATCH`.
Once the category and kind have been determined, the payload can be casted:
- `kind`: The `kind` field is dependent on the `category`. For example, for `category` `ROCPROFILER_BUFFER_CATEGORY_TRACING`, the value of `kind` depicts the tracing type such as HSA core API in `ROCPROFILER_BUFFER_TRACING_HSA_CORE_API`.
- `payload`: The `payload` is casted after the category and kind have been determined.
```cpp
{
@@ -199,7 +188,7 @@ Once the category and kind have been determined, the payload can be casted:
}
```
### Buffer Tracing Callback Function Example
**Example:**
```cpp
void
@@ -238,14 +227,12 @@ buffer_callback_func(rocprofiler_context_id_t context,
}
```
## Buffer Tracing Record
## Buffer tracing record
Unlike callback tracing records, there is no common set of data for each buffer tracing record. However,
many buffer tracing records contain a `kind` field and an `operation` field.
The name of a tracing kind can be obtained via the `rocprofiler_query_buffer_tracing_kind_name` function.
The name of an operation specific to a tracing kind can be obtained via the `rocprofiler_query_buffer_tracing_kind_operation_name`
function. One can also iterate over all the buffer tracing kinds and operations for each tracing kind via the
many buffer tracing records contain a `kind` and an `operation` field.
You can obtain the value for the `kind` of tracing using `rocprofiler_query_buffer_tracing_kind_name` function and the value for the `operation` specific to a tracing kind using the `rocprofiler_query_buffer_tracing_kind_operation_name`
function. You can also iterate over all the buffer tracing `kinds` and `operations` for each tracing kind using the
`rocprofiler_iterate_buffer_tracing_kinds` and `rocprofiler_iterate_buffer_tracing_kind_operations` functions.
The buffer tracing record data types can be found in the `rocprofiler-sdk/buffer_tracing.h` header
(`source/include/rocprofiler-sdk/buffer_tracing.h` in the [rocprofiler-sdk GitHub repository](https://github.com/ROCm/rocprofiler-sdk)).
The buffer tracing record data types are available in the [rocprofiler-sdk/buffer_tracing.h](https://github.com/ROCm/rocprofiler-sdk/blob/amd-mainline/source/include/rocprofiler-sdk/buffer_tracing.h) header.