rocprofiler-sdk/device_counting_service.h Source File

rocprofiler-sdk/device_counting_service.h Source File#

Rocprofiler SDK Developer API: rocprofiler-sdk/device_counting_service.h Source File
Rocprofiler SDK Developer API 0.6.0
ROCm Profiling API and tools
device_counting_service.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
26#include <rocprofiler-sdk/fwd.h>
27
28/**
29 * @defgroup device_counting_service Agent Profile Counting Service
30 * @brief needs brief description
31 *
32 * @{
33 */
34ROCPROFILER_EXTERN_C_INIT
35
36/**
37 * @brief Callback to set the profile config for the agent.
38 *
39 * @param [in] context_id context id
40 * @param [in] config_id Profile config detailing the counters to collect for this kernel
41 * @return ::rocprofiler_status_t
42 * @retval ::ROCPROFILER_STATUS_ERROR_PROFILE_NOT_FOUND Returned if the config_id is not found
43 * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID Returned if the ctx is not valid
44 * @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Returned if attempting to make this
45 * call outside of context startup.
46 * @retval ::ROCPROFILER_STATUS_ERROR_AGENT_MISMATCH Agent of profile does not match agent of the
47 * context.
48 * @retval ::ROCPROFILER_STATUS_SUCCESS Returned if succesfully configured
49 */
51 rocprofiler_context_id_t context_id,
53
54/**
55 * @brief Configure Profile Counting Service for agent. Called when the context is started.
56 * Selects the counters to be used for agent profiling.
57 *
58 * @param [in] context_id context id
59 * @param [in] agent_id agent id
60 * @param [in] set_config Function to call to set the profile config (see
61 * rocprofiler_agent_set_profile_callback_t)
62 * @param [in] user_data Data supplied to rocprofiler_configure_device_counting_service
63 */
65 rocprofiler_context_id_t context_id,
68 void* user_data);
69
70/**
71 * @brief Configure Device Counting Service for agent. There may only be one counting service
72 * configured per agent in a context and can be only one active context that is profiling a single
73 * agent at a time. Multiple agent contexts can be started at the same time if they are profiling
74 * different agents.
75 *
76 * @param [in] context_id context id
77 * @param [in] buffer_id id of the buffer to use for the counting service. When
78 * rocprofiler_sample_device_counting_service is called, counter data will be written
79 * to this buffer.
80 * @param [in] agent_id agent to configure profiling on.
81 * @param [in] cb Callback called when the context is started for the tool to specify what
82 * counters to collect (rocprofiler_profile_config_id_t).
83 * @param [in] user_data User supplied data to be passed to the callback cb when triggered
84 * @return ::rocprofiler_status_t
85 * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID Returned if the context does not exist.
86 * @retval ::ROCPROFILER_STATUS_ERROR_BUFFER_NOT_FOUND Returned if the buffer is not found.
87 * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Returned if context already has agent
88 * profiling configured for agent_id.
89 * @retval ::ROCPROFILER_STATUS_SUCCESS Returned if succesfully configured
90 */
96 void* user_data)
97 ROCPROFILER_NONNULL(4) ROCPROFILER_API;
98
99/**
100 * @brief Trigger a read of the counter data for the agent profile. The counter data will be
101 * written to the buffer specified in rocprofiler_configure_device_counting_service.
102 * The data in rocprofiler_user_data_t will be written to the buffer along with the counter data.
103 * flags can be used to specify if this call should be performed asynchronously (default is
104 * synchronous).
105 *
106 * @param [in] context_id context id
107 * @param [in] user_data User supplied data, included in records outputted to buffer.
108 * @param [in] flags Flags to specify how the counter data should be collected (defaults to sync).
109 * @param [in/out] output_records Output records collected via sampling (output is also written to
110 * buffer). Must be allocated by caller.
111 * @param [in/out] rec_count On entry, this is the maximum number of records rocprof can store in
112 * output_records. On exit, contains the number of actual records.
113 * @return ::rocprofiler_status_t
114 * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID Returned if the context does not exist or
115 * the context is not configured for agent profiling.
116 * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_ERROR Returned if another operation is in progress (
117 * start/stop ctx or another read).
118 * @retval ::ROCPROFILER_STATUS_ERROR Returned if HSA has not been initialized yet.
119 * @retval ::ROCPROFILER_STATUS_ERROR_OUT_OF_RESOURCES Returned output_records is set but size is
120 * too small to store results
121 * @retval ::ROCPROFILER_STATUS_SUCCESS Returned if read request was successful.
122 * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Returned If ASYNC is being used while
123 * output_records is not null.
124 */
127 rocprofiler_user_data_t user_data,
129 rocprofiler_record_counter_t* output_records,
130 size_t* rec_count) ROCPROFILER_API;
131
132/** @} */
133
134ROCPROFILER_EXTERN_C_FINI
rocprofiler_status_t
Status codes.
Definition fwd.h:53
rocprofiler_counter_flag_t
Enumeration of flags that can be used with some counter api calls.
Definition fwd.h:432
Agent Identifier.
Definition fwd.h:578
Context ID.
Definition fwd.h:539
Profile Configurations.
Definition fwd.h:595
ROCProfiler Profile Counting Counter Record per instance.
Definition fwd.h:720
User-assignable data type.
Definition fwd.h:514
rocprofiler_status_t rocprofiler_sample_device_counting_service(rocprofiler_context_id_t context_id, rocprofiler_user_data_t user_data, rocprofiler_counter_flag_t flags, rocprofiler_record_counter_t *output_records, unsigned long *rec_count)
Trigger a read of the counter data for the agent profile. The counter data will be written to the buf...
void(* rocprofiler_device_counting_service_callback_t)(rocprofiler_context_id_t context_id, rocprofiler_agent_id_t agent_id, rocprofiler_agent_set_profile_callback_t set_config, void *user_data)
Configure Profile Counting Service for agent. Called when the context is started. Selects the counter...
rocprofiler_status_t(* rocprofiler_agent_set_profile_callback_t)(rocprofiler_context_id_t context_id, rocprofiler_profile_config_id_t config_id)
Callback to set the profile config for the agent.
rocprofiler_status_t rocprofiler_configure_device_counting_service(rocprofiler_context_id_t context_id, rocprofiler_buffer_id_t buffer_id, rocprofiler_agent_id_t agent_id, rocprofiler_device_counting_service_callback_t cb, void *user_data)
Configure Device Counting Service for agent. There may only be one counting service configured per ag...