rocprofiler-sdk/buffer.h Source File

rocprofiler-sdk/buffer.h Source File#

Rocprofiler SDK Developer API: rocprofiler-sdk/buffer.h Source File
Rocprofiler SDK Developer API 0.5.0
ROCm Profiling API and tools
buffer.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
28ROCPROFILER_EXTERN_C_INIT
29
30/**
31 * @defgroup BUFFER_HANDLING Buffer Handling
32 * @brief Creation, destruction, and flushing of buffers populated with data from rocprofiler
33 *
34 * @{
35 *
36 * Every Buffer is associated with a specific service kind.
37 * OR
38 * Every Buffer is associated with a specific service ID.
39 *
40 */
41
42/**
43 * @brief Async callback function.
44 *
45 * @code{.cpp}
46 * for(size_t i = 0; i < num_headers; ++i)
47 * {
48 * rocprofiler_record_header_t* hdr = headers[i];
49 * if(hdr->kind == ROCPROFILER_RECORD_KIND_PC_SAMPLE)
50 * {
51 * auto* data = static_cast<rocprofiler_pc_sample_t*>(&hdr->payload);
52 * ...
53 * }
54 * }
55 * @endcode
56 */
60 size_t num_headers,
61 void* data,
62 uint64_t drop_count);
63
64/**
65 * @brief Create buffer.
66 *
67 * @param [in] context Context identifier associated with buffer
68 * @param [in] size Size of the buffer in bytes
69 * @param [in] watermark - watermark size, where the callback is called, if set
70 * to 0 then the callback will be called on every record
71 * @param [in] policy Behavior policy when buffer is full
72 * @param [in] callback Callback to invoke when buffer is flushed/full
73 * @param [in] callback_data Data to provide in callback function
74 * @param [out] buffer_id Identification handle for buffer
75 * @return ::rocprofiler_status_t
76 */
79 size_t size,
80 size_t watermark,
83 void* callback_data,
84 rocprofiler_buffer_id_t* buffer_id) ROCPROFILER_API
85 ROCPROFILER_NONNULL(5, 7);
86
87/**
88 * @brief Destroy buffer.
89 *
90 * @param [in] buffer_id
91 * @return ::rocprofiler_status_t
92 *
93 * Note: This will destroy the buffer even if it is not empty. The user can
94 * call @ref ::rocprofiler_flush_buffer before it to make sure the buffer is empty.
95 */
98
99/**
100 * @brief Flush buffer.
101 *
102 * @param [in] buffer_id
103 * @return ::rocprofiler_status_t
104 */
107
108/** @} */
109
110ROCPROFILER_EXTERN_C_FINI
rocprofiler_buffer_policy_t
Actions when Buffer is full.
Definition fwd.h:311
rocprofiler_status_t
Status codes.
Definition fwd.h:55
Context ID.
Definition fwd.h:502
Generic record with type identifier(s) and a pointer to data. This data type is used with buffered da...
Definition fwd.h:617
void(* rocprofiler_buffer_tracing_cb_t)(rocprofiler_context_id_t context, rocprofiler_buffer_id_t buffer_id, rocprofiler_record_header_t **headers, unsigned long num_headers, void *data, uint64_t drop_count)
Async callback function.
Definition buffer.h:57
rocprofiler_status_t rocprofiler_create_buffer(rocprofiler_context_id_t context, unsigned long size, unsigned long watermark, rocprofiler_buffer_policy_t policy, rocprofiler_buffer_tracing_cb_t callback, void *callback_data, rocprofiler_buffer_id_t *buffer_id)
Create buffer.
rocprofiler_status_t rocprofiler_destroy_buffer(rocprofiler_buffer_id_t buffer_id)
Destroy buffer.
rocprofiler_status_t rocprofiler_flush_buffer(rocprofiler_buffer_id_t buffer_id)
Flush buffer.