codekingpro/portable-devtools
114k
1#ifndef NVPERF_COMMON_H
2#define NVPERF_COMMON_H
3
4/*
5 * Copyright 2014-2023 NVIDIA Corporation. All rights reserved.
6 *
7 * NOTICE TO USER:
8 *
9 * This source code is subject to NVIDIA ownership rights under U.S. and
10 * international Copyright laws.
11 *
12 * This software and the information contained herein is PROPRIETARY and
13 * CONFIDENTIAL to NVIDIA and is being provided under the terms and conditions
14 * of a form of NVIDIA software license agreement.
15 *
16 * NVIDIA MAKES NO REPRESENTATION ABOUT THE SUITABILITY OF THIS SOURCE
17 * CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR
18 * IMPLIED WARRANTY OF ANY KIND. NVIDIA DISCLAIMS ALL WARRANTIES WITH
19 * REGARD TO THIS SOURCE CODE, INCLUDING ALL IMPLIED WARRANTIES OF
20 * MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
21 * IN NO EVENT SHALL NVIDIA BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL,
22 * OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
23 * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
24 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
25 * OR PERFORMANCE OF THIS SOURCE CODE.
26 *
27 * U.S. Government End Users. This source code is a "commercial item" as
28 * that term is defined at 48 C.F.R. 2.101 (OCT 1995), consisting of
29 * "commercial computer software" and "commercial computer software
30 * documentation" as such terms are used in 48 C.F.R. 12.212 (SEPT 1995)
31 * and is provided to the U.S. Government only as a commercial end item.
32 * Consistent with 48 C.F.R.12.212 and 48 C.F.R. 227.7202-1 through
33 * 227.7202-4 (JUNE 1995), all U.S. Government End Users acquire the
34 * source code with only those rights set forth herein.
35 *
36 * Any use of this source code in individual and commercial software must
37 * include, in the user documentation and internal comments to the code,
38 * the above Disclaimer and U.S. Government End Users Notice.
39 */
40
41#include <stddef.h>
42#include <stdint.h>
43
44#if defined(__GNUC__) && defined(NVPA_SHARED_LIB)
45 #pragma GCC visibility push(default)
46 #if !defined(NVPW_LOCAL)
47 #define NVPW_LOCAL __attribute__ ((visibility ("hidden")))
48 #endif
49#else
50 #if !defined(NVPW_LOCAL)
51 #define NVPW_LOCAL
52 #endif
53#endif
54
55#ifdef __cplusplus
56extern "C" {
57#endif
58
59/**
60 * @file nvperf_common.h
61 */
62
63#ifndef NVPERF_NVPA_STATUS_DEFINED
64#define NVPERF_NVPA_STATUS_DEFINED
65
66 /// Error codes.
67 typedef enum NVPA_Status
68 {
69 /// Success
70 NVPA_STATUS_SUCCESS = 0,
71 /// Generic error.
72 NVPA_STATUS_ERROR = 1,
73 /// Internal error. Please file a bug!
74 NVPA_STATUS_INTERNAL_ERROR = 2,
75 /// NVPW_InitializeTarget() or NVPW_InitializeHost() has not been called yet.
76 NVPA_STATUS_NOT_INITIALIZED = 3,
77 /// The NvPerf DLL/DSO could not be loaded during NVPW_Initialize*(). Please ensure they are placed in the
78 /// appropriate location that can be founder by a dynamic linker. And on Linux systems, confirm that the
79 /// LD_LIBRARY_PATH environment variable is set correctly. Alternatively, you may utilize
80 /// NVPW_SetLibraryLoadPaths() to define additional library search paths.
81 NVPA_STATUS_NOT_LOADED = 4,
82 /// The function was not found in this version of the NvPerf DLL/DSO. Or if you are directly calling
83 /// NVPA_GetProcAddress(), please ensure the function name is spelled correctly.
84 NVPA_STATUS_FUNCTION_NOT_FOUND = 5,
85 /// The request was intentionally not supported.
86 NVPA_STATUS_NOT_SUPPORTED = 6,
87 /// The request was not implemented by this version.
88 NVPA_STATUS_NOT_IMPLEMENTED = 7,
89 /// Invalid argument.
90 NVPA_STATUS_INVALID_ARGUMENT = 8,
91 /// UNUSED
92 NVPA_STATUS_INVALID_METRIC_ID = 9,
93 /// No driver has been loaded via NVPW_*_LoadDriver().
94 NVPA_STATUS_DRIVER_NOT_LOADED = 10,
95 /// Failed memory allocation.
96 NVPA_STATUS_OUT_OF_MEMORY = 11,
97 /// UNUSED
98 NVPA_STATUS_INVALID_THREAD_STATE = 12,
99 /// UNUSED
100 NVPA_STATUS_FAILED_CONTEXT_ALLOC = 13,
101 /// The specified GPU is not supported. It is recommended to call IsGpuSupported() for more information
102 NVPA_STATUS_UNSUPPORTED_GPU = 14,
103 /// The installed NVIDIA driver is too old.
104 NVPA_STATUS_INSUFFICIENT_DRIVER_VERSION = 15,
105 /// UNUSED
106 NVPA_STATUS_OBJECT_NOT_REGISTERED = 16,
107 /// Profiling permission not granted; see https://developer.nvidia.com/nvidia-development-tools-solutions-
108 /// ERR_NVGPUCTRPERM-permission-issue-performance-counters
109 NVPA_STATUS_INSUFFICIENT_PRIVILEGE = 17,
110 /// UNUSED
111 NVPA_STATUS_INVALID_CONTEXT_STATE = 18,
112 /// UNUSED
113 NVPA_STATUS_INVALID_OBJECT_STATE = 19,
114 /// The request could not be fulfilled because a system resource is already in use.
115 NVPA_STATUS_RESOURCE_UNAVAILABLE = 20,
116 /// UNUSED
117 NVPA_STATUS_DRIVER_LOADED_TOO_LATE = 21,
118 /// The provided buffer is not large enough.
119 NVPA_STATUS_INSUFFICIENT_SPACE = 22,
120 /// UNUSED
121 NVPA_STATUS_OBJECT_MISMATCH = 23,
122 /// Virtualized GPU (vGPU) is not supported.
123 NVPA_STATUS_VIRTUALIZED_DEVICE_NOT_SUPPORTED = 24,
124 /// Profiling permission was not granted or the device was disabled.
125 NVPA_STATUS_PROFILING_NOT_ALLOWED = 25,
126 NVPA_STATUS__COUNT
127 } NVPA_Status;
128
129
130 inline void NVPW_NVPAStatusToString(NVPA_Status status, const char** ppStatusStr, const char** ppCommentStr)
131 {
132 switch (status)
133 {
134 case NVPA_STATUS_SUCCESS:
135 *ppStatusStr = "NVPA_STATUS_SUCCESS";
136 *ppCommentStr = "Success";
137 return;
138 case NVPA_STATUS_ERROR:
139 *ppStatusStr = "NVPA_STATUS_ERROR";
140 *ppCommentStr = "Generic error.";
141 return;
142 case NVPA_STATUS_INTERNAL_ERROR:
143 *ppStatusStr = "NVPA_STATUS_INTERNAL_ERROR";
144 *ppCommentStr = "Internal error. Please file a bug!";
145 return;
146 case NVPA_STATUS_NOT_INITIALIZED:
147 *ppStatusStr = "NVPA_STATUS_NOT_INITIALIZED";
148 *ppCommentStr = "NVPW_InitializeTarget() or NVPW_InitializeHost() has not been called yet.";
149 return;
150 case NVPA_STATUS_NOT_LOADED:
151 *ppStatusStr = "NVPA_STATUS_NOT_LOADED";
152 *ppCommentStr = "The NvPerf DLL/DSO could not be loaded during NVPW_Initialize*(). Please ensure they are placed in the appropriate location that can be founder by a dynamic linker. And on Linux systems, confirm that the LD_LIBRARY_PATH environment variable is set correctly. Alternatively, you may utilize NVPW_SetLibraryLoadPaths() to define additional library search paths.";
153 return;
154 case NVPA_STATUS_FUNCTION_NOT_FOUND:
155 *ppStatusStr = "NVPA_STATUS_FUNCTION_NOT_FOUND";
156 *ppCommentStr = "The function was not found in this version of the NvPerf DLL/DSO. Or if you are directly calling NVPA_GetProcAddress(), please ensure the function name is spelled correctly.";
157 return;
158 case NVPA_STATUS_NOT_SUPPORTED:
159 *ppStatusStr = "NVPA_STATUS_NOT_SUPPORTED";
160 *ppCommentStr = "The request was intentionally not supported.";
161 return;
162 case NVPA_STATUS_NOT_IMPLEMENTED:
163 *ppStatusStr = "NVPA_STATUS_NOT_IMPLEMENTED";
164 *ppCommentStr = "The request was not implemented by this version.";
165 return;
166 case NVPA_STATUS_INVALID_ARGUMENT:
167 *ppStatusStr = "NVPA_STATUS_INVALID_ARGUMENT";
168 *ppCommentStr = "Invalid argument.";
169 return;
170 case NVPA_STATUS_INVALID_METRIC_ID:
171 *ppStatusStr = "NVPA_STATUS_INVALID_METRIC_ID";
172 *ppCommentStr = "UNUSED";
173 return;
174 case NVPA_STATUS_DRIVER_NOT_LOADED:
175 *ppStatusStr = "NVPA_STATUS_DRIVER_NOT_LOADED";
176 *ppCommentStr = "No driver has been loaded via NVPW_*_LoadDriver().";
177 return;
178 case NVPA_STATUS_OUT_OF_MEMORY:
179 *ppStatusStr = "NVPA_STATUS_OUT_OF_MEMORY";
180 *ppCommentStr = "Failed memory allocation.";
181 return;
182 case NVPA_STATUS_INVALID_THREAD_STATE:
183 *ppStatusStr = "NVPA_STATUS_INVALID_THREAD_STATE";
184 *ppCommentStr = "UNUSED";
185 return;
186 case NVPA_STATUS_FAILED_CONTEXT_ALLOC:
187 *ppStatusStr = "NVPA_STATUS_FAILED_CONTEXT_ALLOC";
188 *ppCommentStr = "UNUSED";
189 return;
190 case NVPA_STATUS_UNSUPPORTED_GPU:
191 *ppStatusStr = "NVPA_STATUS_UNSUPPORTED_GPU";
192 *ppCommentStr = "The specified GPU is not supported. It is recommended to call IsGpuSupported() for more information";
193 return;
194 case NVPA_STATUS_INSUFFICIENT_DRIVER_VERSION:
195 *ppStatusStr = "NVPA_STATUS_INSUFFICIENT_DRIVER_VERSION";
196 *ppCommentStr = "The installed NVIDIA driver is too old.";
197 return;
198 case NVPA_STATUS_OBJECT_NOT_REGISTERED:
199 *ppStatusStr = "NVPA_STATUS_OBJECT_NOT_REGISTERED";
200 *ppCommentStr = "UNUSED";
201 return;
202 case NVPA_STATUS_INSUFFICIENT_PRIVILEGE:
203 *ppStatusStr = "NVPA_STATUS_INSUFFICIENT_PRIVILEGE";
204 *ppCommentStr = "Profiling permission not granted; see https://developer.nvidia.com/nvidia-development-tools-solutions-ERR_NVGPUCTRPERM-permission-issue-performance-counters";
205 return;
206 case NVPA_STATUS_INVALID_CONTEXT_STATE:
207 *ppStatusStr = "NVPA_STATUS_INVALID_CONTEXT_STATE";
208 *ppCommentStr = "UNUSED";
209 return;
210 case NVPA_STATUS_INVALID_OBJECT_STATE:
211 *ppStatusStr = "NVPA_STATUS_INVALID_OBJECT_STATE";
212 *ppCommentStr = "UNUSED";
213 return;
214 case NVPA_STATUS_RESOURCE_UNAVAILABLE:
215 *ppStatusStr = "NVPA_STATUS_RESOURCE_UNAVAILABLE";
216 *ppCommentStr = "The request could not be fulfilled because a system resource is already in use.";
217 return;
218 case NVPA_STATUS_DRIVER_LOADED_TOO_LATE:
219 *ppStatusStr = "NVPA_STATUS_DRIVER_LOADED_TOO_LATE";
220 *ppCommentStr = "UNUSED";
221 return;
222 case NVPA_STATUS_INSUFFICIENT_SPACE:
223 *ppStatusStr = "NVPA_STATUS_INSUFFICIENT_SPACE";
224 *ppCommentStr = "The provided buffer is not large enough.";
225 return;
226 case NVPA_STATUS_OBJECT_MISMATCH:
227 *ppStatusStr = "NVPA_STATUS_OBJECT_MISMATCH";
228 *ppCommentStr = "UNUSED";
229 return;
230 case NVPA_STATUS_VIRTUALIZED_DEVICE_NOT_SUPPORTED:
231 *ppStatusStr = "NVPA_STATUS_VIRTUALIZED_DEVICE_NOT_SUPPORTED";
232 *ppCommentStr = "Virtualized GPU (vGPU) is not supported.";
233 return;
234 case NVPA_STATUS_PROFILING_NOT_ALLOWED:
235 *ppStatusStr = "NVPA_STATUS_PROFILING_NOT_ALLOWED";
236 *ppCommentStr = "Profiling permission was not granted or the device was disabled.";
237 return;
238 default:
239 *ppStatusStr = "Unrecognized status";
240 *ppCommentStr = "This status is unrecognized. Is it coming from a newer version of NvPerf library?";
241 return;
242 }
243 }
244
245
246#endif // NVPERF_NVPA_STATUS_DEFINED
247
248
249#ifndef NVPERF_NVPA_ACTIVITY_KIND_DEFINED
250#define NVPERF_NVPA_ACTIVITY_KIND_DEFINED
251
252 /// The configuration's activity-kind dictates which types of data may be collected.
253 typedef enum NVPA_ActivityKind
254 {
255 /// Invalid value.
256 NVPA_ACTIVITY_KIND_INVALID = 0,
257 /// A workload-centric activity for serialized and pipelined collection.
258 ///
259 /// Profiler is capable of collecting both serialized and pipelined metrics. The library introduces any
260 /// synchronization required to collect serialized metrics.
261 NVPA_ACTIVITY_KIND_PROFILER,
262 /// A realtime activity for sampling counters from the CPU or GPU.
263 NVPA_ACTIVITY_KIND_REALTIME_SAMPLED,
264 /// A realtime activity for profiling counters from the CPU or GPU without CPU/GPU synchronizations.
265 NVPA_ACTIVITY_KIND_REALTIME_PROFILER,
266 NVPA_ACTIVITY_KIND__COUNT
267 } NVPA_ActivityKind;
268
269
270#endif // NVPERF_NVPA_ACTIVITY_KIND_DEFINED
271
272
273#ifndef NVPERF_NVPA_BOOL_DEFINED
274#define NVPERF_NVPA_BOOL_DEFINED
275 /// The type used for boolean values.
276 typedef uint8_t NVPA_Bool;
277#endif // NVPERF_NVPA_BOOL_DEFINED
278
279#ifndef NVPA_STRUCT_SIZE
280#define NVPA_STRUCT_SIZE(type_, lastfield_) (offsetof(type_, lastfield_) + sizeof(((type_*)0)->lastfield_))
281#endif // NVPA_STRUCT_SIZE
282
283#ifndef NVPW_FIELD_EXISTS
284#define NVPW_FIELD_EXISTS(pParams_, name_) \
285 ((pParams_)->structSize >= (size_t)((const uint8_t*)(&(pParams_)->name_) + sizeof(pParams_)->name_ - (const uint8_t*)(pParams_)))
286#endif // NVPW_FIELD_EXISTS
287
288
289#ifndef NVPERF_NVPA_GETPROCADDRESS_DEFINED
290#define NVPERF_NVPA_GETPROCADDRESS_DEFINED
291
292typedef NVPA_Status (*NVPA_GenericFn)(void);
293
294
295 ///
296 /// Gets the address of an NvPerf API function.
297 ///
298 /// \return A function pointer to the function, or NULL if the function is not available.
299 ///
300 /// \param pFunctionName [in] Name of the function to retrieve.
301 NVPA_GenericFn NVPA_GetProcAddress(const char* pFunctionName);
302
303#endif
304
305#ifndef NVPERF_NVPW_SETLIBRARYLOADPATHS_DEFINED
306#define NVPERF_NVPW_SETLIBRARYLOADPATHS_DEFINED
307
308
309 typedef struct NVPW_SetLibraryLoadPaths_Params
310 {
311 /// [in]
312 size_t structSize;
313 /// [in] assign to NULL
314 void* pPriv;
315 /// [in] number of paths in ppPaths
316 size_t numPaths;
317 /// [in] array of null-terminated paths
318 const char** ppPaths;
319 } NVPW_SetLibraryLoadPaths_Params;
320#define NVPW_SetLibraryLoadPaths_Params_STRUCT_SIZE NVPA_STRUCT_SIZE(NVPW_SetLibraryLoadPaths_Params, ppPaths)
321
322 /// Sets library search path for \ref NVPW_InitializeHost() and \ref NVPW_InitializeTarget().
323 /// \ref NVPW_InitializeHost() and \ref NVPW_InitializeTarget load the NvPerf DLL/DSO. This function sets
324 /// ordered paths that will be searched with the LoadLibrary() or dlopen() call.
325 /// If load paths are set by this function, the default set of load paths
326 /// will not be attempted.
327 /// Each path must point at a directory (not a file name).
328 /// This function is not thread-safe.
329 /// Example Usage:
330 /// \code
331 /// const char* paths[] = {
332 /// "path1", "path2", etc
333 /// };
334 /// NVPW_SetLibraryLoadPaths_Params params{NVPW_SetLibraryLoadPaths_Params_STRUCT_SIZE};
335 /// params.numPaths = sizeof(paths)/sizeof(paths[0]);
336 /// params.ppPaths = paths;
337 /// NVPW_SetLibraryLoadPaths(¶ms);
338 /// NVPW_InitializeHost();
339 /// params.numPaths = 0;
340 /// params.ppPaths = NULL;
341 /// NVPW_SetLibraryLoadPaths(¶ms);
342 /// \endcode
343 NVPA_Status NVPW_SetLibraryLoadPaths(NVPW_SetLibraryLoadPaths_Params* pParams);
344
345 typedef struct NVPW_SetLibraryLoadPathsW_Params
346 {
347 /// [in]
348 size_t structSize;
349 /// [in] assign to NULL
350 void* pPriv;
351 /// [in] number of paths in ppwPaths
352 size_t numPaths;
353 /// [in] array of null-terminated paths
354 const wchar_t** ppwPaths;
355 } NVPW_SetLibraryLoadPathsW_Params;
356#define NVPW_SetLibraryLoadPathsW_Params_STRUCT_SIZE NVPA_STRUCT_SIZE(NVPW_SetLibraryLoadPathsW_Params, ppwPaths)
357
358 /// Sets library search path for \ref NVPW_InitializeHost() and \ref NVPW_InitializeTarget().
359 /// \ref NVPW_InitializeHost() and \ref NVPW_InitializeTarget load the NvPerf DLL/DSO. This function sets
360 /// ordered paths that will be searched with the LoadLibrary() or dlopen() call.
361 /// If load paths are set by this function, the default set of load paths
362 /// will not be attempted.
363 /// Each path must point at a directory (not a file name).
364 /// This function is not thread-safe.
365 /// Example Usage:
366 /// \code
367 /// const wchar_t* wpaths[] = {
368 /// L"path1", L"path2", etc
369 /// };
370 /// NVPW_SetLibraryLoadPathsW_Params params{NVPW_SetLibraryLoadPathsW_Params_STRUCT_SIZE};
371 /// params.numPaths = sizeof(wpaths)/sizeof(wpaths[0]);
372 /// params.ppwPaths = wpaths;
373 /// NVPW_SetLibraryLoadPathsW(¶ms);
374 /// NVPW_InitializeHost();
375 /// params.numPaths = 0;
376 /// params.ppwPaths = NULL;
377 /// NVPW_SetLibraryLoadPathsW(¶ms);
378 /// \endcode
379 NVPA_Status NVPW_SetLibraryLoadPathsW(NVPW_SetLibraryLoadPathsW_Params* pParams);
380
381#endif
382
383
384
385#ifdef __cplusplus
386} // extern "C"
387#endif
388
389#if defined(__GNUC__) && defined(NVPA_SHARED_LIB)
390 #pragma GCC visibility pop
391#endif
392
393#endif // NVPERF_COMMON_H
394