codekingpro/portable-devtools
114k
1/*
2 * Copyright 2010-2023 NVIDIA Corporation. All rights reserved.
3 *
4 * NOTICE TO LICENSEE:
5 *
6 * This source code and/or documentation ("Licensed Deliverables") are
7 * subject to NVIDIA intellectual property rights under U.S. and
8 * international Copyright laws.
9 *
10 * These Licensed Deliverables contained herein is PROPRIETARY and
11 * CONFIDENTIAL to NVIDIA and is being provided under the terms and
12 * conditions of a form of NVIDIA software license agreement by and
13 * between NVIDIA and Licensee ("License Agreement") or electronically
14 * accepted by Licensee. Notwithstanding any terms or conditions to
15 * the contrary in the License Agreement, reproduction or disclosure
16 * of the Licensed Deliverables to any third party without the express
17 * written consent of NVIDIA is prohibited.
18 *
19 * NOTWITHSTANDING ANY TERMS OR CONDITIONS TO THE CONTRARY IN THE
20 * LICENSE AGREEMENT, NVIDIA MAKES NO REPRESENTATION ABOUT THE
21 * SUITABILITY OF THESE LICENSED DELIVERABLES FOR ANY PURPOSE. IT IS
22 * PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY OF ANY KIND.
23 * NVIDIA DISCLAIMS ALL WARRANTIES WITH REGARD TO THESE LICENSED
24 * DELIVERABLES, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY,
25 * NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
26 * NOTWITHSTANDING ANY TERMS OR CONDITIONS TO THE CONTRARY IN THE
27 * LICENSE AGREEMENT, IN NO EVENT SHALL NVIDIA BE LIABLE FOR ANY
28 * SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, OR ANY
29 * DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
30 * WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
31 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
32 * OF THESE LICENSED DELIVERABLES.
33 *
34 * U.S. Government End Users. These Licensed Deliverables are a
35 * "commercial item" as that term is defined at 48 C.F.R. 2.101 (OCT
36 * 1995), consisting of "commercial computer software" and "commercial
37 * computer software documentation" as such terms are used in 48
38 * C.F.R. 12.212 (SEPT 1995) and is provided to the U.S. Government
39 * only as a commercial end item. Consistent with 48 C.F.R.12.212 and
40 * 48 C.F.R. 227.7202-1 through 227.7202-4 (JUNE 1995), all
41 * U.S. Government End Users acquire the Licensed Deliverables with
42 * only those rights set forth herein.
43 *
44 * Any use of the Licensed Deliverables in individual and commercial
45 * software must include, in the user documentation and internal
46 * comments to the code, the above Disclaimer and U.S. Government End
47 * Users Notice.
48 */
49
50#if !defined(__CUPTI_CALLBACKS_H__)
51#define __CUPTI_CALLBACKS_H__
52
53#include <cuda.h>
54#include <builtin_types.h>
55#include <string.h>
56#include <cuda_stdint.h>
57#include <cupti_result.h>
58
59#ifndef CUPTIAPI
60#ifdef _WIN32
61#define CUPTIAPI __stdcall
62#else
63#define CUPTIAPI
64#endif
65#endif
66
67#if defined(__cplusplus)
68extern "C" {
69#endif
70
71#if defined(__GNUC__) && defined(CUPTI_LIB)
72 #pragma GCC visibility push(default)
73#endif
74
75/**
76 * \defgroup CUPTI_CALLBACK_API CUPTI Callback API
77 * Functions, types, and enums that implement the CUPTI Callback API.
78 * @{
79 */
80
81/**
82 * \brief Specifies the point in an API call that a callback is issued.
83 *
84 * Specifies the point in an API call that a callback is issued. This
85 * value is communicated to the callback function via \ref
86 * CUpti_CallbackData::callbackSite.
87 */
88typedef enum {
89 /**
90 * The callback is at the entry of the API call.
91 */
92 CUPTI_API_ENTER = 0,
93 /**
94 * The callback is at the exit of the API call.
95 */
96 CUPTI_API_EXIT = 1,
97 CUPTI_API_CBSITE_FORCE_INT = 0x7fffffff
98} CUpti_ApiCallbackSite;
99
100/**
101 * \brief Callback domains.
102 *
103 * Callback domains. Each domain represents callback points for a
104 * group of related API functions or CUDA driver activity.
105 */
106typedef enum {
107 /**
108 * Invalid domain.
109 */
110 CUPTI_CB_DOMAIN_INVALID = 0,
111 /**
112 * Domain containing callback points for all driver API functions.
113 */
114 CUPTI_CB_DOMAIN_DRIVER_API = 1,
115 /**
116 * Domain containing callback points for all runtime API
117 * functions.
118 */
119 CUPTI_CB_DOMAIN_RUNTIME_API = 2,
120 /**
121 * Domain containing callback points for CUDA resource tracking.
122 */
123 CUPTI_CB_DOMAIN_RESOURCE = 3,
124 /**
125 * Domain containing callback points for CUDA synchronization.
126 */
127 CUPTI_CB_DOMAIN_SYNCHRONIZE = 4,
128 /**
129 * Domain containing callback points for NVTX API functions.
130 */
131 CUPTI_CB_DOMAIN_NVTX = 5,
132 /**
133 * Domain containing callback points for various states.
134 */
135 CUPTI_CB_DOMAIN_STATE,
136 CUPTI_CB_DOMAIN_SIZE,
137
138 CUPTI_CB_DOMAIN_FORCE_INT = 0x7fffffff
139} CUpti_CallbackDomain;
140
141/**
142 * \brief Callback IDs for resource domain.
143 *
144 * Callback IDs for resource domain, CUPTI_CB_DOMAIN_RESOURCE. This
145 * value is communicated to the callback function via the \p cbid
146 * parameter.
147 */
148typedef enum {
149 /**
150 * Invalid resource callback ID.
151 */
152 CUPTI_CBID_RESOURCE_INVALID = 0,
153 /**
154 * A new context has been created.
155 */
156 CUPTI_CBID_RESOURCE_CONTEXT_CREATED = 1,
157 /**
158 * A context is about to be destroyed.
159 */
160 CUPTI_CBID_RESOURCE_CONTEXT_DESTROY_STARTING = 2,
161 /**
162 * A new stream has been created.
163 */
164 CUPTI_CBID_RESOURCE_STREAM_CREATED = 3,
165 /**
166 * A stream is about to be destroyed.
167 */
168 CUPTI_CBID_RESOURCE_STREAM_DESTROY_STARTING = 4,
169 /**
170 * The driver has finished initializing.
171 */
172 CUPTI_CBID_RESOURCE_CU_INIT_FINISHED = 5,
173 /**
174 * A module has been loaded.
175 */
176 CUPTI_CBID_RESOURCE_MODULE_LOADED = 6,
177 /**
178 * A module is about to be unloaded.
179 */
180 CUPTI_CBID_RESOURCE_MODULE_UNLOAD_STARTING = 7,
181 /**
182 * The current module which is being profiled.
183 */
184 CUPTI_CBID_RESOURCE_MODULE_PROFILED = 8,
185 /**
186 * CUDA graph has been created.
187 */
188 CUPTI_CBID_RESOURCE_GRAPH_CREATED = 9,
189 /**
190 * CUDA graph is about to be destroyed.
191 */
192 CUPTI_CBID_RESOURCE_GRAPH_DESTROY_STARTING = 10,
193 /**
194 * CUDA graph is cloned.
195 */
196 CUPTI_CBID_RESOURCE_GRAPH_CLONED = 11,
197 /**
198 * CUDA graph node is about to be created
199 */
200 CUPTI_CBID_RESOURCE_GRAPHNODE_CREATE_STARTING = 12,
201 /**
202 * CUDA graph node is created.
203 */
204 CUPTI_CBID_RESOURCE_GRAPHNODE_CREATED = 13,
205 /**
206 * CUDA graph node is about to be destroyed.
207 */
208 CUPTI_CBID_RESOURCE_GRAPHNODE_DESTROY_STARTING = 14,
209 /**
210 * Dependency on a CUDA graph node is created.
211 */
212 CUPTI_CBID_RESOURCE_GRAPHNODE_DEPENDENCY_CREATED = 15,
213 /**
214 * Dependency on a CUDA graph node is destroyed.
215 */
216 CUPTI_CBID_RESOURCE_GRAPHNODE_DEPENDENCY_DESTROY_STARTING = 16,
217 /**
218 * An executable CUDA graph is about to be created.
219 */
220 CUPTI_CBID_RESOURCE_GRAPHEXEC_CREATE_STARTING = 17,
221 /**
222 * An executable CUDA graph is created.
223 */
224 CUPTI_CBID_RESOURCE_GRAPHEXEC_CREATED = 18,
225 /**
226 * An executable CUDA graph is about to be destroyed.
227 */
228 CUPTI_CBID_RESOURCE_GRAPHEXEC_DESTROY_STARTING = 19,
229 /**
230 * CUDA graph node is cloned.
231 */
232 CUPTI_CBID_RESOURCE_GRAPHNODE_CLONED = 20,
233 /**
234 * CUDA stream attribute is changed.
235 */
236 CUPTI_CBID_RESOURCE_STREAM_ATTRIBUTE_CHANGED = 21,
237
238 CUPTI_CBID_RESOURCE_SIZE,
239 CUPTI_CBID_RESOURCE_FORCE_INT = 0x7fffffff
240} CUpti_CallbackIdResource;
241
242/**
243 * \brief Callback IDs for synchronization domain.
244 *
245 * Callback IDs for synchronization domain,
246 * CUPTI_CB_DOMAIN_SYNCHRONIZE. This value is communicated to the
247 * callback function via the \p cbid parameter.
248 */
249typedef enum {
250 /**
251 * Invalid synchronize callback ID.
252 */
253 CUPTI_CBID_SYNCHRONIZE_INVALID = 0,
254 /**
255 * Stream synchronization has completed for the stream.
256 */
257 CUPTI_CBID_SYNCHRONIZE_STREAM_SYNCHRONIZED = 1,
258 /**
259 * Context synchronization has completed for the context.
260 */
261 CUPTI_CBID_SYNCHRONIZE_CONTEXT_SYNCHRONIZED = 2,
262 CUPTI_CBID_SYNCHRONIZE_SIZE,
263 CUPTI_CBID_SYNCHRONIZE_FORCE_INT = 0x7fffffff
264} CUpti_CallbackIdSync;
265
266/**
267 * \brief Callback IDs for state domain.
268 *
269 * Callback IDs for state domain,
270 * CUPTI_CB_DOMAIN_STATE. This value is communicated to the
271 * callback function via the \p cbid parameter.
272 */
273typedef enum {
274 /**
275 * Invalid state callback ID.
276 */
277 CUPTI_CBID_STATE_INVALID = 0,
278 /**
279 * Notification of fatal errors - high impact, non-recoverable
280 * When encountered, CUPTI automatically invokes cuptiFinalize()
281 * User can control behavior of the application in future from
282 * receiving this callback - such as continuing without profiling, or
283 * terminating the whole application.
284 */
285 CUPTI_CBID_STATE_FATAL_ERROR = 1,
286 /**
287 * Notification of non fatal errors - high impact, but recoverable
288 * This notification is not issued in the current release.
289 */
290 CUPTI_CBID_STATE_ERROR = 2,
291 /**
292 * Notification of warnings - low impact, recoverable
293 * This notification is not issued in the current release.
294 */
295 CUPTI_CBID_STATE_WARNING = 3,
296
297 CUPTI_CBID_STATE_SIZE,
298 CUPTI_CBID_STATE_FORCE_INT = 0x7fffffff
299} CUpti_CallbackIdState;
300
301/**
302 * \brief Data passed into a runtime or driver API callback function.
303 *
304 * Data passed into a runtime or driver API callback function as the
305 * \p cbdata argument to \ref CUpti_CallbackFunc. The \p cbdata will
306 * be this type for \p domain equal to CUPTI_CB_DOMAIN_DRIVER_API or
307 * CUPTI_CB_DOMAIN_RUNTIME_API. The callback data is valid only within
308 * the invocation of the callback function that is passed the data. If
309 * you need to retain some data for use outside of the callback, you
310 * must make a copy of that data. For example, if you make a shallow
311 * copy of CUpti_CallbackData within a callback, you cannot
312 * dereference \p functionParams outside of that callback to access
313 * the function parameters. \p functionName is an exception: the
314 * string pointed to by \p functionName is a global constant and so
315 * may be accessed outside of the callback.
316 */
317typedef struct {
318 /**
319 * Point in the runtime or driver function from where the callback
320 * was issued.
321 */
322 CUpti_ApiCallbackSite callbackSite;
323
324 /**
325 * Name of the runtime or driver API function which issued the
326 * callback. This string is a global constant and so may be
327 * accessed outside of the callback.
328 */
329 const char *functionName;
330
331 /**
332 * Pointer to the arguments passed to the runtime or driver API
333 * call. See generated_cuda_runtime_api_meta.h and
334 * generated_cuda_meta.h for structure definitions for the
335 * parameters for each runtime and driver API function.
336 */
337 const void *functionParams;
338
339 /**
340 * Pointer to the return value of the runtime or driver API
341 * call. This field is only valid within the exit::CUPTI_API_EXIT
342 * callback. For a runtime API \p functionReturnValue points to a
343 * \p cudaError_t. For a driver API \p functionReturnValue points
344 * to a \p CUresult.
345 */
346 void *functionReturnValue;
347
348 /**
349 * Name of the symbol operated on by the runtime or driver API
350 * function which issued the callback. This entry is valid only for
351 * driver and runtime launch callbacks, where it returns the name of
352 * the kernel.
353 */
354 const char *symbolName;
355
356 /**
357 * Driver context current to the thread, or null if no context is
358 * current. This value can change from the entry to exit callback
359 * of a runtime API function if the runtime initializes a context.
360 */
361 CUcontext context;
362
363 /**
364 * Unique ID for the CUDA context associated with the thread. The
365 * UIDs are assigned sequentially as contexts are created and are
366 * unique within a process.
367 */
368 uint32_t contextUid;
369
370 /**
371 * Pointer to data shared between the entry and exit callbacks of
372 * a given runtime or drive API function invocation. This field
373 * can be used to pass 64-bit values from the entry callback to
374 * the corresponding exit callback.
375 */
376 uint64_t *correlationData;
377
378 /**
379 * The activity record correlation ID for this callback. For a
380 * driver domain callback (i.e. \p domain
381 * CUPTI_CB_DOMAIN_DRIVER_API) this ID will equal the correlation ID
382 * in the CUpti_ActivityAPI record corresponding to the CUDA driver
383 * function call. For a runtime domain callback (i.e. \p domain
384 * CUPTI_CB_DOMAIN_RUNTIME_API) this ID will equal the correlation
385 * ID in the CUpti_ActivityAPI record corresponding to the CUDA
386 * runtime function call. Within the callback, this ID can be
387 * recorded to correlate user data with the activity record. This
388 * field is new in 4.1.
389 */
390 uint32_t correlationId;
391
392} CUpti_CallbackData;
393
394/**
395 * \brief Data passed into a resource callback function.
396 *
397 * Data passed into a resource callback function as the \p cbdata
398 * argument to \ref CUpti_CallbackFunc. The \p cbdata will be this
399 * type for \p domain equal to CUPTI_CB_DOMAIN_RESOURCE. The callback
400 * data is valid only within the invocation of the callback function
401 * that is passed the data. If you need to retain some data for use
402 * outside of the callback, you must make a copy of that data.
403 */
404typedef struct {
405 /**
406 * For CUPTI_CBID_RESOURCE_CONTEXT_CREATED and
407 * CUPTI_CBID_RESOURCE_CONTEXT_DESTROY_STARTING, the context being
408 * created or destroyed. For CUPTI_CBID_RESOURCE_STREAM_CREATED and
409 * CUPTI_CBID_RESOURCE_STREAM_DESTROY_STARTING, the context
410 * containing the stream being created or destroyed.
411 */
412 CUcontext context;
413
414 union {
415 /**
416 * For CUPTI_CBID_RESOURCE_STREAM_CREATED and
417 * CUPTI_CBID_RESOURCE_STREAM_DESTROY_STARTING, the stream being
418 * created or destroyed.
419 */
420 CUstream stream;
421 } resourceHandle;
422
423 /**
424 * Reserved for future use.
425 */
426 void *resourceDescriptor;
427} CUpti_ResourceData;
428
429
430/**
431 * \brief Module data passed into a resource callback function.
432 *
433 * CUDA module data passed into a resource callback function as the \p cbdata
434 * argument to \ref CUpti_CallbackFunc. The \p cbdata will be this
435 * type for \p domain equal to CUPTI_CB_DOMAIN_RESOURCE. The module
436 * data is valid only within the invocation of the callback function
437 * that is passed the data. If you need to retain some data for use
438 * outside of the callback, you must make a copy of that data.
439 */
440
441typedef struct {
442 /**
443 * Identifier to associate with the CUDA module.
444 */
445 uint32_t moduleId;
446
447 /**
448 * The size of the cubin.
449 */
450 size_t cubinSize;
451
452 /**
453 * Pointer to the associated cubin.
454 */
455 const char *pCubin;
456} CUpti_ModuleResourceData;
457
458/**
459 * \brief CUDA graphs data passed into a resource callback function.
460 *
461 * CUDA graphs data passed into a resource callback function as the \p cbdata
462 * argument to \ref CUpti_CallbackFunc. The \p cbdata will be this
463 * type for \p domain equal to CUPTI_CB_DOMAIN_RESOURCE. The graph
464 * data is valid only within the invocation of the callback function
465 * that is passed the data. If you need to retain some data for use
466 * outside of the callback, you must make a copy of that data.
467 */
468
469typedef struct {
470 /**
471 * CUDA graph
472 */
473 CUgraph graph;
474 /**
475 * The original CUDA graph from which \param graph is cloned
476 */
477 CUgraph originalGraph;
478 /**
479 * CUDA graph node
480 */
481 CUgraphNode node;
482 /**
483 * The original CUDA graph node from which \param node is cloned
484 */
485 CUgraphNode originalNode;
486 /**
487 * Type of the \param node
488 */
489 CUgraphNodeType nodeType;
490 /**
491 * The dependent graph node
492 * The size of the array is \param numDependencies.
493 */
494 CUgraphNode dependency;
495 /**
496 * CUDA executable graph
497 */
498 CUgraphExec graphExec;
499} CUpti_GraphData;
500
501/**
502 * \brief Data passed into a synchronize callback function.
503 *
504 * Data passed into a synchronize callback function as the \p cbdata
505 * argument to \ref CUpti_CallbackFunc. The \p cbdata will be this
506 * type for \p domain equal to CUPTI_CB_DOMAIN_SYNCHRONIZE. The
507 * callback data is valid only within the invocation of the callback
508 * function that is passed the data. If you need to retain some data
509 * for use outside of the callback, you must make a copy of that data.
510 */
511typedef struct {
512 /**
513 * The context of the stream being synchronized.
514 */
515 CUcontext context;
516 /**
517 * The stream being synchronized.
518 */
519 CUstream stream;
520} CUpti_SynchronizeData;
521
522/**
523 * \brief Data passed into a NVTX callback function.
524 *
525 * Data passed into a NVTX callback function as the \p cbdata argument
526 * to \ref CUpti_CallbackFunc. The \p cbdata will be this type for \p
527 * domain equal to CUPTI_CB_DOMAIN_NVTX. Unless otherwise notes, the
528 * callback data is valid only within the invocation of the callback
529 * function that is passed the data. If you need to retain some data
530 * for use outside of the callback, you must make a copy of that data.
531 */
532typedef struct {
533 /**
534 * Name of the NVTX API function which issued the callback. This
535 * string is a global constant and so may be accessed outside of the
536 * callback.
537 */
538 const char *functionName;
539
540 /**
541 * Pointer to the arguments passed to the NVTX API call. See
542 * generated_nvtx_meta.h for structure definitions for the
543 * parameters for each NVTX API function.
544 */
545 const void *functionParams;
546
547 /**
548 * Pointer to the return value of the NVTX API call. See
549 * nvToolsExt.h for each NVTX API function's return value.
550 */
551 const void *functionReturnValue;
552} CUpti_NvtxData;
553
554/**
555 * \brief Stream attribute data passed into a resource callback function
556 * for CUPTI_CBID_RESOURCE_STREAM_ATTRIBUTE_CHANGED callback
557
558 * Data passed into a resource callback function as the \p cbdata
559 * argument to \ref CUpti_CallbackFunc. The \p cbdata will be this
560 * type for \p domain equal to CUPTI_CB_DOMAIN_RESOURCE. The
561 * stream attribute data is valid only within the invocation of the callback
562 * function that is passed the data. If you need to retain some data
563 * for use outside of the callback, you must make a copy of that data.
564 */
565typedef struct {
566 /**
567 * The CUDA stream handle for the attribute
568 */
569 CUstream stream;
570
571 /**
572 * The type of the CUDA stream attribute
573 */
574 CUstreamAttrID attr;
575
576 /**
577 * The value of the CUDA stream attribute
578 */
579 const CUstreamAttrValue *value;
580} CUpti_StreamAttrData;
581
582/**
583 * \brief Data passed into a State callback function.
584 *
585 * Data passed into a State callback function as the \p cbdata argument
586 * to \ref CUpti_CallbackFunc. The \p cbdata will be this type for \p
587 * domain equal to CUPTI_CB_DOMAIN_STATE and callback Ids belonging to CUpti_CallbackIdState.
588 * Unless otherwise noted, the callback data is valid only within the invocation of the callback
589 * function that is passed the data. If you need to retain some data
590 * for use outside of the callback, you must make a copy of that data.
591 */
592typedef struct {
593 union {
594 /**
595 * Data passed along with the callback Ids
596 * Enum CUpti_CallbackIdState used to denote callback ids
597 */
598 struct {
599 /**
600 * Error code
601 */
602 CUptiResult result;
603 /**
604 * String containing more details. It can be NULL.
605 */
606 const char *message;
607 } notification;
608 };
609} CUpti_StateData;
610/**
611 * \brief An ID for a driver API, runtime API, resource or
612 * synchronization callback.
613 *
614 * An ID for a driver API, runtime API, resource or synchronization
615 * callback. Within a driver API callback this should be interpreted
616 * as a CUpti_driver_api_trace_cbid value (these values are defined in
617 * cupti_driver_cbid.h). Within a runtime API callback this should be
618 * interpreted as a CUpti_runtime_api_trace_cbid value (these values
619 * are defined in cupti_runtime_cbid.h). Within a resource API
620 * callback this should be interpreted as a \ref
621 * CUpti_CallbackIdResource value. Within a synchronize API callback
622 * this should be interpreted as a \ref CUpti_CallbackIdSync value.
623 */
624typedef uint32_t CUpti_CallbackId;
625
626/**
627 * \brief Function type for a callback.
628 *
629 * Function type for a callback. The type of the data passed to the
630 * callback in \p cbdata depends on the \p domain. If \p domain is
631 * CUPTI_CB_DOMAIN_DRIVER_API or CUPTI_CB_DOMAIN_RUNTIME_API the type
632 * of \p cbdata will be CUpti_CallbackData. If \p domain is
633 * CUPTI_CB_DOMAIN_RESOURCE the type of \p cbdata will be
634 * CUpti_ResourceData. If \p domain is CUPTI_CB_DOMAIN_SYNCHRONIZE the
635 * type of \p cbdata will be CUpti_SynchronizeData. If \p domain is
636 * CUPTI_CB_DOMAIN_NVTX the type of \p cbdata will be CUpti_NvtxData.
637 *
638 * \param userdata User data supplied at subscription of the callback
639 * \param domain The domain of the callback
640 * \param cbid The ID of the callback
641 * \param cbdata Data passed to the callback.
642 */
643typedef void (CUPTIAPI *CUpti_CallbackFunc)(
644 void *userdata,
645 CUpti_CallbackDomain domain,
646 CUpti_CallbackId cbid,
647 const void *cbdata);
648
649/**
650 * \brief A callback subscriber.
651 */
652typedef struct CUpti_Subscriber_st *CUpti_SubscriberHandle;
653
654/**
655 * \brief Pointer to an array of callback domains.
656 */
657typedef CUpti_CallbackDomain *CUpti_DomainTable;
658
659/**
660 * \brief Get the available callback domains.
661 *
662 * Returns in \p *domainTable an array of size \p *domainCount of all
663 * the available callback domains.
664 * \note \b Thread-safety: this function is thread safe.
665 *
666 * \param domainCount Returns number of callback domains
667 * \param domainTable Returns pointer to array of available callback domains
668 *
669 * \retval CUPTI_SUCCESS on success
670 * \retval CUPTI_ERROR_NOT_INITIALIZED if unable to initialize CUPTI
671 * \retval CUPTI_ERROR_INVALID_PARAMETER if \p domainCount or \p domainTable are NULL
672 */
673CUptiResult CUPTIAPI cuptiSupportedDomains(size_t *domainCount,
674 CUpti_DomainTable *domainTable);
675
676/**
677 * \brief Initialize a callback subscriber with a callback function
678 * and user data.
679 *
680 * Initializes a callback subscriber with a callback function and
681 * (optionally) a pointer to user data. The returned subscriber handle
682 * can be used to enable and disable the callback for specific domains
683 * and callback IDs.
684 * \note Only a single subscriber can be registered at a time. To ensure
685 * that no other CUPTI client interrupts the profiling session, it's the
686 * responsibility of all the CUPTI clients to call this function before
687 * starting the profling session. In case profiling session is already
688 * started by another CUPTI client, this function returns the error code
689 * CUPTI_ERROR_MULTIPLE_SUBSCRIBERS_NOT_SUPPORTED.
690 * Note that this function returns the same error when application is
691 * launched using NVIDIA tools like nvprof, Visual Profiler, Nsight Systems,
692 * Nsight Compute, cuda-gdb and cuda-memcheck.
693 * \note This function does not enable any callbacks.
694 * \note \b Thread-safety: this function is thread safe.
695 *
696 * \param subscriber Returns handle to initialize subscriber
697 * \param callback The callback function
698 * \param userdata A pointer to user data. This data will be passed to
699 * the callback function via the \p userdata parameter.
700 *
701 * \retval CUPTI_SUCCESS on success
702 * \retval CUPTI_ERROR_NOT_INITIALIZED if unable to initialize CUPTI
703 * \retval CUPTI_ERROR_MULTIPLE_SUBSCRIBERS_NOT_SUPPORTED if there is already a CUPTI subscriber
704 * \retval CUPTI_ERROR_INVALID_PARAMETER if \p subscriber is NULL
705 */
706CUptiResult CUPTIAPI cuptiSubscribe(CUpti_SubscriberHandle *subscriber,
707 CUpti_CallbackFunc callback,
708 void *userdata);
709
710/**
711 * \brief Unregister a callback subscriber.
712 *
713 * Removes a callback subscriber so that no future callbacks will be
714 * issued to that subscriber.
715 * \note \b Thread-safety: this function is thread safe.
716 *
717 * \param subscriber Handle to the initialize subscriber
718 *
719 * \retval CUPTI_SUCCESS on success
720 * \retval CUPTI_ERROR_NOT_INITIALIZED if unable to initialized CUPTI
721 * \retval CUPTI_ERROR_INVALID_PARAMETER if \p subscriber is NULL or not initialized
722 */
723CUptiResult CUPTIAPI cuptiUnsubscribe(CUpti_SubscriberHandle subscriber);
724
725/**
726 * \brief Get the current enabled/disabled state of a callback for a specific
727 * domain and function ID.
728 *
729 * Returns non-zero in \p *enable if the callback for a domain and
730 * callback ID is enabled, and zero if not enabled.
731 *
732 * \note \b Thread-safety: a subscriber must serialize access to
733 * cuptiGetCallbackState, cuptiEnableCallback, cuptiEnableDomain, and
734 * cuptiEnableAllDomains. For example, if cuptiGetCallbackState(sub,
735 * d, c) and cuptiEnableCallback(sub, d, c) are called concurrently,
736 * the results are undefined.
737 *
738 * \param enable Returns non-zero if callback enabled, zero if not enabled
739 * \param subscriber Handle to the initialize subscriber
740 * \param domain The domain of the callback
741 * \param cbid The ID of the callback
742 *
743 * \retval CUPTI_SUCCESS on success
744 * \retval CUPTI_ERROR_NOT_INITIALIZED if unable to initialized CUPTI
745 * \retval CUPTI_ERROR_INVALID_PARAMETER if \p enabled is NULL, or if \p
746 * subscriber, \p domain or \p cbid is invalid.
747 */
748CUptiResult CUPTIAPI cuptiGetCallbackState(uint32_t *enable,
749 CUpti_SubscriberHandle subscriber,
750 CUpti_CallbackDomain domain,
751 CUpti_CallbackId cbid);
752
753/**
754 * \brief Enable or disabled callbacks for a specific domain and
755 * callback ID.
756 *
757 * Enable or disabled callbacks for a subscriber for a specific domain
758 * and callback ID.
759 *
760 * \note \b Thread-safety: a subscriber must serialize access to
761 * cuptiGetCallbackState, cuptiEnableCallback, cuptiEnableDomain, and
762 * cuptiEnableAllDomains. For example, if cuptiGetCallbackState(sub,
763 * d, c) and cuptiEnableCallback(sub, d, c) are called concurrently,
764 * the results are undefined.
765 *
766 * \param enable New enable state for the callback. Zero disables the
767 * callback, non-zero enables the callback.
768 * \param subscriber - Handle to callback subscription
769 * \param domain The domain of the callback
770 * \param cbid The ID of the callback
771 *
772 * \retval CUPTI_SUCCESS on success
773 * \retval CUPTI_ERROR_NOT_INITIALIZED if unable to initialized CUPTI
774 * \retval CUPTI_ERROR_INVALID_PARAMETER if \p subscriber, \p domain or \p
775 * cbid is invalid.
776 */
777CUptiResult CUPTIAPI cuptiEnableCallback(uint32_t enable,
778 CUpti_SubscriberHandle subscriber,
779 CUpti_CallbackDomain domain,
780 CUpti_CallbackId cbid);
781
782/**
783 * \brief Enable or disabled all callbacks for a specific domain.
784 *
785 * Enable or disabled all callbacks for a specific domain.
786 *
787 * \note \b Thread-safety: a subscriber must serialize access to
788 * cuptiGetCallbackState, cuptiEnableCallback, cuptiEnableDomain, and
789 * cuptiEnableAllDomains. For example, if cuptiGetCallbackEnabled(sub,
790 * d, *) and cuptiEnableDomain(sub, d) are called concurrently, the
791 * results are undefined.
792 *
793 * \param enable New enable state for all callbacks in the
794 * domain. Zero disables all callbacks, non-zero enables all
795 * callbacks.
796 * \param subscriber - Handle to callback subscription
797 * \param domain The domain of the callback
798 *
799 * \retval CUPTI_SUCCESS on success
800 * \retval CUPTI_ERROR_NOT_INITIALIZED if unable to initialized CUPTI
801 * \retval CUPTI_ERROR_INVALID_PARAMETER if \p subscriber or \p domain is invalid
802 */
803CUptiResult CUPTIAPI cuptiEnableDomain(uint32_t enable,
804 CUpti_SubscriberHandle subscriber,
805 CUpti_CallbackDomain domain);
806
807/**
808 * \brief Enable or disable all callbacks in all domains.
809 *
810 * Enable or disable all callbacks in all domains.
811 *
812 * \note \b Thread-safety: a subscriber must serialize access to
813 * cuptiGetCallbackState, cuptiEnableCallback, cuptiEnableDomain, and
814 * cuptiEnableAllDomains. For example, if cuptiGetCallbackState(sub,
815 * d, *) and cuptiEnableAllDomains(sub) are called concurrently, the
816 * results are undefined.
817 *
818 * \param enable New enable state for all callbacks in all
819 * domain. Zero disables all callbacks, non-zero enables all
820 * callbacks.
821 * \param subscriber - Handle to callback subscription
822 *
823 * \retval CUPTI_SUCCESS on success
824 * \retval CUPTI_ERROR_NOT_INITIALIZED if unable to initialized CUPTI
825 * \retval CUPTI_ERROR_INVALID_PARAMETER if \p subscriber is invalid
826 */
827CUptiResult CUPTIAPI cuptiEnableAllDomains(uint32_t enable,
828 CUpti_SubscriberHandle subscriber);
829
830/**
831 * \brief Get the name of a callback for a specific domain and callback ID.
832 *
833 * Returns a pointer to the name c_string in \p **name.
834 *
835 * \note \b Names are available only for the DRIVER and RUNTIME domains.
836 *
837 * \param domain The domain of the callback
838 * \param cbid The ID of the callback
839 * \param name Returns pointer to the name string on success, NULL otherwise
840 *
841 * \retval CUPTI_SUCCESS on success
842 * \retval CUPTI_ERROR_INVALID_PARAMETER if \p name is NULL, or if
843 * \p domain or \p cbid is invalid.
844 */
845CUptiResult CUPTIAPI cuptiGetCallbackName(CUpti_CallbackDomain domain,
846 uint32_t cbid,
847 const char **name);
848
849/** @} */ /* END CUPTI_CALLBACK_API */
850
851#if defined(__GNUC__) && defined(CUPTI_LIB)
852 #pragma GCC visibility pop
853#endif
854
855#if defined(__cplusplus)
856}
857#endif
858
859#endif // file guard
860
861