rocprofiler-sdk/dispatch_profile.h Source File

rocprofiler-sdk/dispatch_profile.h Source File#

Rocprofiler SDK Developer API: rocprofiler-sdk/dispatch_profile.h Source File
Rocprofiler SDK Developer API 0.5.0
ROCm Profiling API and tools
dispatch_profile.h
Go to the documentation of this file.
1// MIT License
2//
3// Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved.
4//
5// Permission is hereby granted, free of charge, to any person obtaining a copy
6// of this software and associated documentation files (the "Software"), to deal
7// in the Software without restriction, including without limitation the rights
8// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9// copies of the Software, and to permit persons to whom the Software is
10// furnished to do so, subject to the following conditions:
11//
12// The above copyright notice and this permission notice shall be included in all
13// copies or substantial portions of the Software.
14//
15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21// SOFTWARE.
22
23#pragma once
24
27#include <rocprofiler-sdk/fwd.h>
28#include <rocprofiler-sdk/hsa.h>
30
31ROCPROFILER_EXTERN_C_INIT
32
33/**
34 * @defgroup DISPATCH_PROFILE_COUNTING_SERVICE Dispatch Profile Counting Service
35 * @brief Per-dispatch hardware counter collection service
36 *
37 * @{
38 */
39
40/**
41 * @brief Kernel dispatch data for profile counting callbacks.
42 *
43 */
45{
46 uint64_t size; ///< Size of this struct
47 rocprofiler_correlation_id_t correlation_id; ///< Correlation ID for this dispatch
48 rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
49 rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
52
53/**
54 * @brief ROCProfiler Profile Counting Counter Record Header Information
55 *
56 * This is buffer equivalent of ::rocprofiler_profile_counting_dispatch_data_t
57 */
59{
60 uint64_t size; ///< Size of this struct
61 uint64_t num_records; ///< number of ::rocprofiler_record_counter_t records
62 rocprofiler_correlation_id_t correlation_id; ///< Correlation ID for this dispatch
63 rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
64 rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
65 rocprofiler_kernel_dispatch_info_t dispatch_info; ///< Contains the `dispatch_id`
67
68/**
69 * @brief Kernel Dispatch Callback. This is a callback that is invoked before the kernel
70 * is enqueued into the HSA queue. What counters to collect for a kernel are set
71 * via passing back a profile config (config) in this callback. These counters
72 * will be collected and emplaced in the buffer with @ref rocprofiler_buffer_id_t used when
73 * setting up this callback.
74 *
75 * @param [in] dispatch_data @see ::rocprofiler_profile_counting_dispatch_data_t
76 * @param [out] config Profile config detailing the counters to collect for this kernel
77 * @param [out] user_data User data unique to this dispatch. Returned in record callback
78 * @param [in] callback_data_args Callback supplied via buffered_dispatch_profile_counting_service
79 */
83 rocprofiler_user_data_t* user_data,
84 void* callback_data_args);
85
86/**
87 * @brief Counting record callback. This is a callback is invoked when the kernel
88 * execution is complete and contains the counter profile data requested in
89 * @ref rocprofiler_profile_counting_dispatch_callback_t. Only used with
90 * @ref rocprofiler_configure_callback_dispatch_profile_counting_service.
91 *
92 * @param [in] dispatch_data @see ::rocprofiler_profile_counting_dispatch_data_t
93 * @param [in] record_data Counter record data.
94 * @param [in] record_count Number of counter records.
95 * @param [in] user_data User data instance from dispatch callback
96 * @param [in] callback_data_args Callback supplied via buffered_dispatch_profile_counting_service
97 */
100 rocprofiler_record_counter_t* record_data,
101 size_t record_count,
102 rocprofiler_user_data_t user_data,
103 void* callback_data_args);
104
105/**
106 * @brief Configure buffered dispatch profile Counting Service.
107 * Collects the counters in dispatch packets and stores them
108 * in a buffer with @p buffer_id. The buffer may contain packets from more than
109 * one dispatch (denoted by correlation id). Will trigger the
110 * callback based on the parameters setup in buffer_id_t.
111 *
112 * NOTE: Interface is up for comment as to whether restrictions
113 * on agent should be made here (limiting the CB based on agent)
114 * or if the restriction should be performed by the tool in
115 * @ref rocprofiler_profile_counting_dispatch_callback_t (i.e.
116 * tool code checking the agent param to see if they want to profile
117 * it).
118 *
119 * Interface is up for comment as to whether restrictions
120 * on agent should be made here (limiting the CB based on agent)
121 * or if the restriction should be performed by the tool in
122 * @ref rocprofiler_profile_counting_dispatch_callback_t (i.e.
123 * tool code checking the agent param to see if they want to profile
124 * it).
125 *
126 * @param [in] context_id context id
127 * @param [in] buffer_id id of the buffer to use for the counting service
128 * @param [in] callback callback to perform when dispatch is enqueued
129 * @param [in] callback_data_args callback data
130 * @return ::rocprofiler_status_t
131 */
134 rocprofiler_context_id_t context_id,
135 rocprofiler_buffer_id_t buffer_id,
137 void* callback_data_args) ROCPROFILER_API;
138
139/**
140 * @brief Configure buffered dispatch profile Counting Service.
141 * Collects the counters in dispatch packets and calls a callback
142 * with the counters collected during that dispatch.
143 *
144 * @param [in] context_id context id
145 * @param [in] dispatch_callback callback to perform when dispatch is enqueued
146 * @param [in] dispatch_callback_args callback data for dispatch callback
147 * @param [in] record_callback Record callback for completed profile data
148 * @param [in] record_callback_args Callback args for record callback
149 * @return ::rocprofiler_status_t
150 */
153 rocprofiler_context_id_t context_id,
155 void* dispatch_callback_args,
157 void* record_callback_args) ROCPROFILER_API;
158/** @} */
159
160ROCPROFILER_EXTERN_C_FINI
rocprofiler_status_t
Status codes.
Definition fwd.h:55
uint64_t rocprofiler_timestamp_t
ROCProfiler Timestamp.
Definition fwd.h:429
Context ID.
Definition fwd.h:502
ROCProfiler Record Correlation ID.
Definition fwd.h:518
ROCProfiler kernel dispatch information.
Definition fwd.h:653
Profile Configurations.
Definition fwd.h:558
ROCProfiler Profile Counting Counter Record per instance.
Definition fwd.h:683
User-assignable data type.
Definition fwd.h:487
rocprofiler_timestamp_t start_timestamp
start time in nanoseconds
rocprofiler_timestamp_t start_timestamp
start time in nanoseconds
rocprofiler_kernel_dispatch_info_t dispatch_info
Contains the dispatch_id
rocprofiler_kernel_dispatch_info_t dispatch_info
Dispatch info.
rocprofiler_correlation_id_t correlation_id
Correlation ID for this dispatch.
rocprofiler_timestamp_t end_timestamp
end time in nanoseconds
uint64_t num_records
number of rocprofiler_record_counter_t records
rocprofiler_timestamp_t end_timestamp
end time in nanoseconds
rocprofiler_correlation_id_t correlation_id
Correlation ID for this dispatch.
rocprofiler_status_t rocprofiler_configure_buffered_dispatch_profile_counting_service(rocprofiler_context_id_t context_id, rocprofiler_buffer_id_t buffer_id, rocprofiler_profile_counting_dispatch_callback_t callback, void *callback_data_args)
Configure buffered dispatch profile Counting Service. Collects the counters in dispatch packets and s...
rocprofiler_status_t rocprofiler_configure_callback_dispatch_profile_counting_service(rocprofiler_context_id_t context_id, rocprofiler_profile_counting_dispatch_callback_t dispatch_callback, void *dispatch_callback_args, rocprofiler_profile_counting_record_callback_t record_callback, void *record_callback_args)
Configure buffered dispatch profile Counting Service. Collects the counters in dispatch packets and c...
void(* rocprofiler_profile_counting_dispatch_callback_t)(rocprofiler_profile_counting_dispatch_data_t dispatch_data, rocprofiler_profile_config_id_t *config, rocprofiler_user_data_t *user_data, void *callback_data_args)
Kernel Dispatch Callback. This is a callback that is invoked before the kernel is enqueued into the H...
void(* rocprofiler_profile_counting_record_callback_t)(rocprofiler_profile_counting_dispatch_data_t dispatch_data, rocprofiler_record_counter_t *record_data, unsigned long record_count, rocprofiler_user_data_t user_data, void *callback_data_args)
Counting record callback. This is a callback is invoked when the kernel execution is complete and con...
Kernel dispatch data for profile counting callbacks.
ROCProfiler Profile Counting Counter Record Header Information.