3.10. Events
One of those events will create a CUDBGEvent:
-
the elf image of the current kernel has been loaded and the addresses within its DWARF sections have been relocated (and can now be used to set breakpoints),
-
a device breakpoint has been hit,
-
a CUDA kernel is ready to be launched,
-
a CUDA kernel has terminated.
Upon notification the debugger is responsible for handling the CUDBGEvents in the event queue by using CUDBGAPI_st::getNextEvent(), and for acknowledging the debugger API that the event has been handled by calling CUDBGAPI_st::acknowledgeEvent(). In the case of an event raised by the device itself, such as a breakpoint being hit, the event queue will be empty. It is the responsibility of the debugger to inspect the hardware any time a CUDBGEvent is received.
Example:
CUDBGEvent event; CUDBGResult res; for (res = cudbgAPI->getNextEvent(&event); res == CUDBG_SUCCESS && event.kind != CUDBG_EVENT_INVALID; res = cudbgAPI->getNextEvent(&event)) { switch (event.kind) { case CUDBG_EVENT_ELF_IMAGE_LOADED: //... break; case CUDBG_EVENT_KERNEL_READY: //... break; case CUDBG_EVENT_KERNEL_FINISHED: //... break; default: error(...); } }
See cuda-tdep.c and cuda-linux-nat.c files in the cuda-gdb source code for a more detailed example on how to use CUDBGEvent.
Classes
- struct
- Event information container.
- struct
- Event information container for API version 3.0.
- struct
- Event information container for API version 3.2.
- struct
- Event information container for API version 4.2.
- struct
- Event information container for API version 5.0.
- struct
- Event information container for API version 5.5.
- struct
- Callback data passed to callback set with setNotifyNewEventCallback function.
- struct
- Callback data passed to callback set with setNotifyNewEventCallback40 function.
- struct
- Callback data passed to callback set with setNotifyNewEventCallback41 function.
Typedefs
- typedef void ( *CUDBGNotifyNewEventCallback )( CUDBGEventCallbackData* data )
- Function type of the function called to notify debugger of the presence of a new event in the event queue.
- typedef void ( *CUDBGNotifyNewEventCallback31 )( void* data )
- Function type of the function called to notify debugger of the presence of a new event in the event queue.
- typedef void ( *CUDBGNotifyNewEventCallback40 )( CUDBGEventCallbackData40* data )
- Function type of the function called to notify debugger of the presence of a new event in the event queue.
- typedef void ( *CUDBGNotifyNewEventCallback41 )( CUDBGEventCallbackData41* data )
- Function type of the function called to notify debugger of the presence of a new event in the event queue.
Enumerations
- enum CUDBGEventKind
- Kinds of events sent by the debug engine to the API client.
- enum CUDBGEventQueueType
- Application event queue type.
Variables
- CUDBGResult ( *CUDBGAPI_st::acknowledgeEvent30 )( CUDBGEvent30* event )
- Inform the debugger API that synchronous events have been processed.
- CUDBGResult ( *CUDBGAPI_st::acknowledgeEvents42 )( )
- Inform the debugger API that synchronous events have been processed.
- CUDBGResult ( *CUDBGAPI_st::acknowledgeSyncEvents )( )
- Inform the debugger API that synchronous events have been processed.
- CUDBGResult ( *CUDBGAPI_st::getErrorStringEx )( char* buf, uint32_t bufSz, uint32_t* msgSz )
- Fills a user-provided buffer with an error message encoded as a null-terminated ASCII string.
- CUDBGResult ( *CUDBGAPI_st::getNextAsyncEvent50 )( CUDBGEvent50* event )
- Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue.
- CUDBGResult ( *CUDBGAPI_st::getNextAsyncEvent55 )( CUDBGEvent55* event )
- Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue.
- CUDBGResult ( *CUDBGAPI_st::getNextEvent )( CUDBGEventQueueType type, CUDBGEvent* event )
- Copies the next available event into 'event' and removes it from the queue.
- CUDBGResult ( *CUDBGAPI_st::getNextEvent30 )( CUDBGEvent30* event )
- Copies the next available event in the event queue into 'event' and removes it from the queue.
- CUDBGResult ( *CUDBGAPI_st::getNextEvent32 )( CUDBGEvent32* event )
- Copies the next available event in the event queue into 'event' and removes it from the queue.
- CUDBGResult ( *CUDBGAPI_st::getNextEvent42 )( CUDBGEvent42* event )
- Copies the next available event in the event queue into 'event' and removes it from the queue.
- CUDBGResult ( *CUDBGAPI_st::getNextSyncEvent50 )( CUDBGEvent50* event )
- Copies the next available event in the synchronous event queue into 'event' and removes it from the queue.
- CUDBGResult ( *CUDBGAPI_st::getNextSyncEvent55 )( CUDBGEvent55* event )
- Copies the next available event in the synchronous event queue into 'event' and removes it from the queue.
- CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback )( CUDBGNotifyNewEventCallback callback, void* userData )
- Provides the API with the function to call to notify the debugger of a new application or device event.
- CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback31 )( CUDBGNotifyNewEventCallback31 callback, void* data )
- Provides the API with the function to call to notify the debugger of a new application or device event.
- CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback40 )( CUDBGNotifyNewEventCallback40 callback )
- Provides the API with the function to call to notify the debugger of a new application or device event.
- CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback41 )( CUDBGNotifyNewEventCallback41 callback )
- Provides the API with the function to call to notify the debugger of a new application or device event.
Typedefs
- void ( *CUDBGNotifyNewEventCallback )( CUDBGEventCallbackData* data )
-
Function type of the function called to notify debugger of the presence of a new event in the event queue.
- data
- - pointer to the event callback data.
- void ( *CUDBGNotifyNewEventCallback31 )( void* data )
-
Function type of the function called to notify debugger of the presence of a new event in the event queue.
Note:DEPRECATED: Use CUDBGNotifyNewEventCallback instead.
- data
- - pointer to the event callback data.
- void ( *CUDBGNotifyNewEventCallback40 )( CUDBGEventCallbackData40* data )
-
Function type of the function called to notify debugger of the presence of a new event in the event queue.
Note:DEPRECATED: Use CUDBGNotifyNewEventCallback instead.
- data
- - pointer to the event callback data.
- void ( *CUDBGNotifyNewEventCallback41 )( CUDBGEventCallbackData41* data )
-
Function type of the function called to notify debugger of the presence of a new event in the event queue.
Note:DEPRECATED: Use CUDBGNotifyNewEventCallback instead.
- data
- - pointer to the event callback data.
Parameters
Parameters
Parameters
Parameters
Enumerations
- enum CUDBGEventKind
-
Values
- CUDBG_EVENT_INVALID = 0x000
- Invalid event.
- CUDBG_EVENT_ELF_IMAGE_LOADED = 0x001
- The ELF image for a CUDA source module is available.
- CUDBG_EVENT_KERNEL_READY = 0x002
- A CUDA kernel is about to be launched.
- CUDBG_EVENT_KERNEL_FINISHED = 0x003
- A CUDA kernel has terminated.
- CUDBG_EVENT_INTERNAL_ERROR = 0x004
- An internal error occurred. The API may be unstable.
- CUDBG_EVENT_CTX_PUSH = 0x005
- A CUDA context has been pushed.
- CUDBG_EVENT_CTX_POP = 0x006
- A CUDA context has been popped.
- CUDBG_EVENT_CTX_CREATE = 0x007
- A CUDA context has been created.
- CUDBG_EVENT_CTX_DESTROY = 0x008
- A CUDA context has been, popped if pushed, then destroyed.
- CUDBG_EVENT_TIMEOUT = 0x009
- A timeout event is sent at regular interval. This event can safely be ignored. Only sent by the classic backend.
- CUDBG_EVENT_ATTACH_COMPLETE = 0x00a
- The attach process has completed and debugging of device code may start.
- CUDBG_EVENT_DETACH_COMPLETE = 0x00b
- The detach process has completed.
- CUDBG_EVENT_ELF_IMAGE_UNLOADED = 0x00c
- The ELF image for CUDA kernel(s) no longer available.
- CUDBG_EVENT_FUNCTIONS_LOADED = 0x00d
- A group of functions/kernels have been loaded Will only be sent if the debug engine capability CUDBG_DEBUGGER_CAPABILITY_LAZY_FUNCTION_LOADING is set.
- CUDBG_EVENT_ALL_DEVICES_SUSPENDED = 0x00e
- All CUDA devices have been suspended due to a breakpoint hit or an exception. Does not get sent for GPU events that result in synchronous API method calls, such as singleStepWarp or resumeWarpsUntilPC. Will only be sent if the debug engine capability CUDBG_DEBUGGER_CAPABILITY_SUSPEND_EVENTS is set.
- CUDBG_EVENT_CUDA_LOGS_AVAILABLE = 0x00f
- (Async) CUDA Logs are available for the debugger to consume. After receiving this asynchronous event, debuggers should drain all available log entries by repeatedly calling consumeCudaLogs until no more logs are available. This event is only sent for the first log message that's generated after the client has read all logs with consumeCudaLogs. It is not sent by default, and can be enabled via the capability CUDBG_DEBUGGER_CAPABILITY_ENABLE_CUDA_LOGS.
- CUDBG_EVENT_CUDA_LOGS_THRESHOLD_REACHED = 0x010
- (Sync) CUDA Logs buffer has reached an implementation-defined threshold. The client should call consumeCudaLogs to avoid excessive log buildup. New logs will still be collected even if consumeCudaLogs is not called.
- CUDBG_EVENT_SINGLE_STEP_COMPLETE = 0x011
- (Sync) Asynchronous single step operation has been completed. Call singleStepWarp or resumeWarpsUntilPC with CUDBG_SINGLE_STEP_FLAGS_NON_BLOCKING to enable this event. This event is only sent if the single step operation was completed. If it's interrupted by a breakpoint or an exception, a CUDBG_EVENT_ALL_DEVICES_SUSPENDED event will be sent instead.
- enum CUDBGEventQueueType
-
Values
- CUDBG_EVENT_QUEUE_TYPE_SYNC = 0
- Synchronous event queue.
- CUDBG_EVENT_QUEUE_TYPE_ASYNC = 1
- Asynchronous event queue.
Variables
- CUDBGResult ( *CUDBGAPI_st::acknowledgeEvent30 )( CUDBGEvent30* event )
-
Inform the debugger API that synchronous events have been processed. Behaves exactly like acknowledgeSyncEvents (the event parameter is ignored).
Since CUDA 3.0.
Note:DEPRECATED in CUDA 3.1: Use acknowledgeSyncEvents instead.
See also:
Parameters
- event
- - pointer to the event that has been processed
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INITIALIZATION_FAILURE
- CUDBGResult ( *CUDBGAPI_st::acknowledgeEvents42 )( )
-
Inform the debugger API that synchronous events have been processed. Behaves exactly like acknowledgeSyncEvents.
Since CUDA 3.1.
Note:DEPRECATED in CUDA 5.0: Use acknowledgeSyncEvents instead.
See also:
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INITIALIZATION_FAILURE
- CUDBGResult ( *CUDBGAPI_st::acknowledgeSyncEvents )( )
-
Inform the debugger API that synchronous events have been processed. This resumes any process that was interrupted by the synchronous event (e.g. a context creation, a module load, etc.). This method always acknowledges only those SYNC events that have been read with getNextEvent (or its deprecated variants). SYNC events that haven't been read are not acknowledged and will continue to prevent their corresponding processes from proceeding. ASYNC events do not require acknowledgement.
Since CUDA 5.0.
See also:
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INITIALIZATION_FAILURE
- CUDBGResult ( *CUDBGAPI_st::getErrorStringEx )( char* buf, uint32_t bufSz, uint32_t* msgSz )
-
Fills a user-provided buffer with an error message encoded as a null-terminated ASCII string. The error message is specific to the last failed API call and is invalidated after every API method call except this one. It's possible to query the size of the error message without reading it by passing 0 as `buf` and `bufSz` parameters. The `msgSz` parameter is optional unless 0 as passed in as `buf` and `bufSz`. CUDBG_ERROR_BUFFER_TOO_SMALL is returned when the passed in buffer is too small to contain the message.
Since CUDA 12.2.
Parameters
- buf
- - the destination buffer
- bufSz
- - the size of the destination buffer in bytes
- msgSz
- - the size of the written error message including the terminating null character.
Returns
CUDBG_SUCCESS, CUDBG_ERROR_BUFFER_TOO_SMALL, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL
- CUDBGResult ( *CUDBGAPI_st::getNextAsyncEvent50 )( CUDBGEvent50* event )
-
Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue. Behaves like getNextEvent but only for ASYNC events and doesn't support the latest event struct format so some fields won't be available.
Since CUDA 5.0.
Note:DEPRECATED in CUDA 5.5: Use getNextEvent instead.
See also:
Parameters
- event
- - pointer to an event container where to copy the event parameters
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_CONTEXT
- CUDBGResult ( *CUDBGAPI_st::getNextAsyncEvent55 )( CUDBGEvent55* event )
-
Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue. Behaves like getNextEvent but only for ASYNC events and doesn't support the latest event struct format so some fields won't be available.
Since CUDA 5.5.
Note:DEPRECATED in CUDA 6.0: Use getNextEvent instead.
See also:
Parameters
- event
- - pointer to an event container where to copy the event parameters
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_CONTEXT
- CUDBGResult ( *CUDBGAPI_st::getNextEvent )( CUDBGEventQueueType type, CUDBGEvent* event )
-
Copies the next available event into 'event' and removes it from the queue. CUDBG_ERROR_NO_EVENT_AVAILABLE is returned if the queue is empty. ASYNC and SYNC queues are separate and each one is ordered separately, but it's impossible to find out the relative order of ASYNC and SYNC events.
Since CUDA 6.0.
See also:
Parameters
- type
- - application event queue type
- event
- - pointer to an event container where to copy the event parameters
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_NO_EVENT_AVAILABLE
- CUDBGResult ( *CUDBGAPI_st::getNextEvent30 )( CUDBGEvent30* event )
-
Copies the next available event in the event queue into 'event' and removes it from the queue. Behaves like getNextEvent but only for SYNC events and doesn't support the latest event struct format so some fields won't be available.
Since CUDA 3.0.
Note:DEPRECATED in CUDA 3.1: Use getNextEvent instead.
See also:
Parameters
- event
- - pointer to an event container where to copy the event parameters
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_CONTEXT
- CUDBGResult ( *CUDBGAPI_st::getNextEvent32 )( CUDBGEvent32* event )
-
Copies the next available event in the event queue into 'event' and removes it from the queue. Behaves like getNextEvent but only for SYNC events and doesn't support the latest event struct format so some fields won't be available.
Since CUDA 3.1.
Note:DEPRECATED in CUDA 4.0: Use getNextEvent instead.
See also:
Parameters
- event
- - pointer to an event container where to copy the event parameters
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_CONTEXT
- CUDBGResult ( *CUDBGAPI_st::getNextEvent42 )( CUDBGEvent42* event )
-
Copies the next available event in the event queue into 'event' and removes it from the queue. Behaves like getNextEvent but only for SYNC events and doesn't support the latest event struct format so some fields won't be available.
Since CUDA 4.0.
Note:DEPRECATED in CUDA 5.0: Use getNextEvent instead.
See also:
Parameters
- event
- - pointer to an event container where to copy the event parameters
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_CONTEXT
- CUDBGResult ( *CUDBGAPI_st::getNextSyncEvent50 )( CUDBGEvent50* event )
-
Copies the next available event in the synchronous event queue into 'event' and removes it from the queue. Behaves like getNextEvent but only for SYNC events and doesn't support the latest event struct format so some fields won't be available.
Since CUDA 5.0.
Note:DEPRECATED in CUDA 5.5: Use getNextEvent instead.
See also:
Parameters
- event
- - pointer to an event container where to copy the event parameters
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_CONTEXT
- CUDBGResult ( *CUDBGAPI_st::getNextSyncEvent55 )( CUDBGEvent55* event )
-
Copies the next available event in the synchronous event queue into 'event' and removes it from the queue. Behaves like getNextEvent but only for SYNC events and doesn't support the latest event struct format so some fields won't be available.
Since CUDA 5.5.
Note:DEPRECATED in CUDA 6.0: Use getNextEvent instead.
See also:
Parameters
- event
- - pointer to an event container where to copy the event parameters
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_CONTEXT
- CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback )( CUDBGNotifyNewEventCallback callback, void* userData )
-
Provides the API with the function to call to notify the debugger of a new application or device event. The callback function is called for every ASYNC and SYNC event. The callback function is always called on the same thread. No API methods can be called from that thread except getNextEvent() and acknowledgeSyncEvents() (and their deprecated variants), otherwise CUDBG_ERROR_RECURSIVE_API_CALL will be returned.
Since CUDA 13.0.
See also:
Parameters
- callback
- - the callback function
- userData
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL
- CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback31 )( CUDBGNotifyNewEventCallback31 callback, void* data )
-
Provides the API with the function to call to notify the debugger of a new application or device event. Behaves like setNotifyNewEventCallback but doesn't return the host thread ID from which the event originates.
Since CUDA 3.0.
Note:DEPRECATED in CUDA 3.2: Use setNotifyNewEventCallback instead.
See also:
Parameters
- callback
- - the callback function
- data
- - a pointer to be passed to the callback when called
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL
- CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback40 )( CUDBGNotifyNewEventCallback40 callback )
-
Provides the API with the function to call to notify the debugger of a new application or device event. Behaves like setNotifyNewEventCallback but doesn't allow passing in the user data pointer.
Since CUDA 3.2.
Note:DEPRECATED in CUDA 4.1: Use setNotifyNewEventCallback instead.
See also:
Parameters
- callback
- - the callback function
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL
- CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback41 )( CUDBGNotifyNewEventCallback41 callback )
-
Provides the API with the function to call to notify the debugger of a new application or device event. Behaves like setNotifyNewEventCallback but doesn't allow passing in the user data pointer. The timeout field is always 0.
Since CUDA 4.1.
Note:DEPRECATED in CUDA 13.0: Use setNotifyNewEventCallback instead.
See also:
Parameters
- callback
- - the callback function
Returns
CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL