rocprofiler-sdk/rocprofiler.h Source File

Rocprofiler SDK Developer API 0.6.0 ROCm Profiling API and tools

• rocprofiler-sdk

rocprofiler.h

Go to the documentation of this file.

1// MIT License

2//

3// Copyright (c) 2023-2025 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

25/**

26 *

27 * \file rocprofiler.h

28 * \brief ROCProfiler-SDK API interface.

29 *

30 * \mainpage ROCProfiler-SDK API Specification

31 *

32 * \section introduction Introduction

33 * ROCprofiler-SDK is a library that implements the profiling and performance monitoring

34 * capabilities for AMD's ROCm platform. It provides a comprehensive set of APIs for:

35 *

36 * - Hardware performance counters monitoring

37 * - PC sampling for kernel execution analysis

38 * - Buffer and callback-based tracing mechanisms

39 * - Device and dispatch counting services

40 * - External correlation tracking

41 * - HIP and HSA runtime profiling support

42 *

43 * The library is designed to help developers analyze and optimize the performance

44 * of applications running on AMD GPUs. It offers both low-level hardware access

45 * and high-level profiling abstractions to accommodate different profiling needs.

46 *

47 *

48 * \section compatibility Compatibility

49 * ROCprofiler-SDK is compatible with AMD ROCm platform and supports

50 * profiling of applications using HIP and HSA runtimes.

51 */

52

53#include <stddef.h>

54#include <stdint.h>

55

56#include "rocprofiler-sdk/defines.h"

57#include "rocprofiler-sdk/fwd.h"

58

59/**

60 * @defgroup VERSIONING_GROUP Library Versioning

61 * @brief Version information about the interface and the associated installed library.

62 *

63 * The semantic version of the interface following semver.org rules. A context

64 * that uses this interface is only compatible with the installed library if

65 * the major version numbers match and the interface minor version number is

66 * less than or equal to the installed library minor version number.

67 *

68 * @{

69 */

70

71#include "rocprofiler-sdk/version.h"

72

73ROCPROFILER_EXTERN_C_INIT

74

75/**

76 * @fn rocprofiler_status_t rocprofiler_get_version(uint32_t* major, uint32_t* minor, uint32_t*

77 * patch)

78 * @brief Query the version of the installed library.

79 *

80 * Return the version of the installed library. This can be used to check if

81 * it is compatible with this interface version. This function can be used

82 * even when the library is not initialized.

83 *

84 * @param [out] major The major version number is stored if non-NULL.

85 * @param [out] minor The minor version number is stored if non-NULL.

86 * @param [out] patch The patch version number is stored if non-NULL.

87 */

88rocprofiler_status_t

89rocprofiler_get_version(uint32_t* major, uint32_t* minor, uint32_t* patch) ROCPROFILER_API;

90

91ROCPROFILER_EXTERN_C_FINI

92

93/** @} */

94

95#include "rocprofiler-sdk/agent.h"

96#include "rocprofiler-sdk/buffer.h"

97#include "rocprofiler-sdk/buffer_tracing.h"

98#include "rocprofiler-sdk/callback_tracing.h"

99#include "rocprofiler-sdk/context.h"

100#include "rocprofiler-sdk/counters.h"

101#include "rocprofiler-sdk/device_counting_service.h"

102#include "rocprofiler-sdk/dispatch_counting_service.h"

103#include "rocprofiler-sdk/external_correlation.h"

104#include "rocprofiler-sdk/hip.h"

105#include "rocprofiler-sdk/hsa.h"

106#include "rocprofiler-sdk/intercept_table.h"

107#include "rocprofiler-sdk/internal_threading.h"

108#include "rocprofiler-sdk/marker.h"

109#include "rocprofiler-sdk/pc_sampling.h"

110#include "rocprofiler-sdk/profile_config.h"

111// #include "rocprofiler-sdk/spm.h"

112

113ROCPROFILER_EXTERN_C_INIT

114

115/**

116 * @defgroup MISCELLANEOUS_GROUP Miscellaneous Utility Functions

117 * @brief utility functions for library

118 * @{

119 */

120

121/**

122 * @fn rocprofiler_status_t rocprofiler_get_timestamp(rocprofiler_timestamp_t* ts)

123 * @brief Get the timestamp value that rocprofiler uses

124 * @param [out] ts Output address of the rocprofiler timestamp value

125 */

126rocprofiler_status_t

127rocprofiler_get_timestamp(rocprofiler_timestamp_t* ts) ROCPROFILER_API ROCPROFILER_NONNULL(1);

128

129/**

130 * @fn rocprofiler_status_t rocprofiler_get_thread_id(rocprofiler_thread_id_t* tid)

131 * @brief Get the identifier value of the current thread that is used by rocprofiler

132 * @param [out] tid Output address of the rocprofiler thread id value

133 */

134rocprofiler_status_t

135rocprofiler_get_thread_id(rocprofiler_thread_id_t* tid) ROCPROFILER_API ROCPROFILER_NONNULL(1);

136

137/**

138 * @fn const char* rocprofiler_get_status_name(rocprofiler_status_t status)

139 * @brief Return the string encoding of @ref rocprofiler_status_t value

140 * @param [in] status error code value

141 * @return Will return a nullptr if invalid/unsupported @ref rocprofiler_status_t value is provided.

142 */

143const char*

144rocprofiler_get_status_name(rocprofiler_status_t status) ROCPROFILER_API;

145

146/**

147 * @fn const char* rocprofiler_get_status_string(rocprofiler_status_t status)

148 * @brief Return the message associated with @ref rocprofiler_status_t value

149 * @param [in] status error code value

150 * @return Will return a nullptr if invalid/unsupported @ref rocprofiler_status_t value is provided.

151 */

152const char*

153rocprofiler_get_status_string(rocprofiler_status_t status) ROCPROFILER_API;

154

155/** @} */

156

157ROCPROFILER_EXTERN_C_FINI

agent.h

buffer.h

buffer_tracing.h

callback_tracing.h

context.h

counters.h

defines.h

device_counting_service.h

dispatch_counting_service.h

external_correlation.h

fwd.h

rocprofiler_status_t

rocprofiler_status_t

Status codes.

Definition fwd.h:53

rocprofiler_thread_id_t

uint64_t rocprofiler_thread_id_t

Thread ID. Value will be equivalent to syscall(__NR_gettid)

Definition fwd.h:472

rocprofiler_timestamp_t

uint64_t rocprofiler_timestamp_t

ROCProfiler Timestamp.

Definition fwd.h:467

rocprofiler_get_status_name

const char * rocprofiler_get_status_name(rocprofiler_status_t status)

Return the string encoding of rocprofiler_status_t value.

rocprofiler_get_timestamp

rocprofiler_status_t rocprofiler_get_timestamp(rocprofiler_timestamp_t *ts)

Get the timestamp value that rocprofiler uses.

rocprofiler_get_status_string

const char * rocprofiler_get_status_string(rocprofiler_status_t status)

Return the message associated with rocprofiler_status_t value.

rocprofiler_get_thread_id

rocprofiler_status_t rocprofiler_get_thread_id(rocprofiler_thread_id_t *tid)

Get the identifier value of the current thread that is used by rocprofiler.

rocprofiler_get_version

rocprofiler_status_t rocprofiler_get_version(uint32_t *major, uint32_t *minor, uint32_t *patch)

Query the version of the installed library.

hip.h

hsa.h

intercept_table.h

internal_threading.h

marker.h

pc_sampling.h

profile_config.h

---

Generated by  1.9.8