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.

When a CUDBGEvent is created, the debugger is notified by calling the callback functions registered with setNotifyNewEventCallback() after the API struct initialization. It is up to the debugger to decide what method is best to be notified. The debugger API routines cannot be called from within the callback function or the routine will return an error.

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;
        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.

Enumerations

CUDBGEventKind: Kinds of events sent by the debug engine to the API client.
CUDBGEventQueueType: Application event queue type.

Structs

CUDBGEvent: Event information container.
CUDBGEvent30: Event information container for API version 3.0.
CUDBGEvent32: Event information container for API version 3.2.
CUDBGEvent42: Event information container for API version 4.2.
CUDBGEvent50: Event information container for API version 5.0.
CUDBGEvent55: Event information container for API version 5.5.
CUDBGEventCallbackData: Callback data passed to callback set with setNotifyNewEventCallback function.
CUDBGEventCallbackData40: Callback data passed to callback set with setNotifyNewEventCallback40 function.
CUDBGEventCallbackData41: Callback data passed to callback set with setNotifyNewEventCallback41 function.

Typedefs

CUDBGNotifyNewEventCallback: Function type of the function called to notify debugger of the presence of a new event in the event queue.
CUDBGNotifyNewEventCallback31: Function type of the function called to notify debugger of the presence of a new event in the event queue.
CUDBGNotifyNewEventCallback40: Function type of the function called to notify debugger of the presence of a new event in the event queue.
CUDBGNotifyNewEventCallback41: Function type of the function called to notify debugger of the presence of a new event in the event queue.

Variables

CUDBGResult(* CUDBGAPI_st::acknowledgeEvent30: 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: Fills a user-provided buffer with an error message encoded as a null-terminated ASCII string.
CUDBGResult(* CUDBGAPI_st::getNextAsyncEvent50: Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue.
CUDBGResult(* CUDBGAPI_st::getNextAsyncEvent55: Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue.
CUDBGResult(* CUDBGAPI_st::getNextEvent: Copies the next available event into 'event' and removes it from the queue.
CUDBGResult(* CUDBGAPI_st::getNextEvent30: Copies the next available event in the event queue into 'event' and removes it from the queue.
CUDBGResult(* CUDBGAPI_st::getNextEvent32: Copies the next available event in the event queue into 'event' and removes it from the queue.
CUDBGResult(* CUDBGAPI_st::getNextEvent42: Copies the next available event in the event queue into 'event' and removes it from the queue.
CUDBGResult(* CUDBGAPI_st::getNextSyncEvent50: Copies the next available event in the synchronous event queue into 'event' and removes it from the queue.
CUDBGResult(* CUDBGAPI_st::getNextSyncEvent55: Copies the next available event in the synchronous event queue into 'event' and removes it from the queue.
CUDBGResult(* CUDBGAPI_st::setNotifyNewEventCallback: Provides the API with the function to call to notify the debugger of a new application or device event.
CUDBGResult(* CUDBGAPI_st::setNotifyNewEventCallback31: Provides the API with the function to call to notify the debugger of a new application or device event.
CUDBGResult(* CUDBGAPI_st::setNotifyNewEventCallback40: Provides the API with the function to call to notify the debugger of a new application or device event.
CUDBGResult(* CUDBGAPI_st::setNotifyNewEventCallback41: Provides the API with the function to call to notify the debugger of a new application or device event.

Enumerations

enum CUDBGEventKind

Kinds of events sent by the debug engine to the API client.

Values:

enumerator CUDBG_EVENT_INVALID: Invalid event.

enumerator CUDBG_EVENT_ELF_IMAGE_LOADED: The ELF image for a CUDA source module is available.

enumerator CUDBG_EVENT_KERNEL_READY: A CUDA kernel is about to be launched.

Note

DEPRECATED: This event is unreliable and will be removed in a future release.

enumerator CUDBG_EVENT_KERNEL_FINISHED: A CUDA kernel has terminated.

Note

DEPRECATED: This event is unreliable and will be removed in a future release.

enumerator CUDBG_EVENT_INTERNAL_ERROR

An internal error occurred.

The API may be unstable.

enumerator CUDBG_EVENT_CTX_PUSH: A CUDA context has been pushed.

enumerator CUDBG_EVENT_CTX_POP: A CUDA context has been popped.

enumerator CUDBG_EVENT_CTX_CREATE: A CUDA context has been created.

enumerator CUDBG_EVENT_CTX_DESTROY: A CUDA context has been, popped if pushed, then destroyed.

enumerator CUDBG_EVENT_TIMEOUT

A timeout event is sent at regular interval.

This event can safely be ignored. Only sent by the classic backend.

enumerator CUDBG_EVENT_ATTACH_COMPLETE: The attach process has completed and debugging of device code may start.

enumerator CUDBG_EVENT_DETACH_COMPLETE: The detach process has completed.

enumerator CUDBG_EVENT_ELF_IMAGE_UNLOADED: The ELF image for CUDA kernel(s) no longer available.

enumerator CUDBG_EVENT_FUNCTIONS_LOADED: 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.

enumerator CUDBG_EVENT_ALL_DEVICES_SUSPENDED

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.

enumerator CUDBG_EVENT_CUDA_LOGS_AVAILABLE

(Async or Sync) CUDA Logs are available for the debugger to consume.

After receiving this event, debuggers should drain all available log entries by repeatedly calling consumeCudaLogs until no more logs are available. For asynchronous CUDA logs, this event is only sent for the first log message that’s generated after the client has read all logs with consumeCudaLogs. For synchronous CUDA logs, this event is sent for each log message that’s generated and the emitting thread will wait for the client to acknowledge the event. See CUDBGAPI_st::setCudaLogRules for more details. It is not sent by default, and can be enabled via the capability CUDBG_DEBUGGER_CAPABILITY_ENABLE_CUDA_LOGS.

enumerator CUDBG_EVENT_CUDA_LOGS_THRESHOLD_REACHED

(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.

enumerator CUDBG_EVENT_SINGLE_STEP_COMPLETE

(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.

enumerator CUDBG_EVENT_CUDA_LOGS_RULESET_CHANGED

(Async) The CUDA log ruleset has changed.

This event is sent after the new ruleset has been applied. The client can call consumeCudaLogs to drain the log buffer, after which it’s guaranteed that the new logs will only match the ruleset with the index larger than or equal to the ruleset index of this event. This allows the clients to stop tracking the old rulesets.

enum CUDBGEventQueueType

Application event queue type.

Values:

enumerator CUDBG_EVENT_QUEUE_TYPE_SYNC: Synchronous event queue.

enumerator CUDBG_EVENT_QUEUE_TYPE_ASYNC: Asynchronous event queue.

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.

Param data: - pointer to the event callback data.

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.

Note

DEPRECATED: Use CUDBGNotifyNewEventCallback instead.

Param data: - pointer to the event callback data.

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.

Note

DEPRECATED: Use CUDBGNotifyNewEventCallback instead.

Param data: - pointer to the event callback data.

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.

Note

DEPRECATED: Use CUDBGNotifyNewEventCallback instead.

Param data: - pointer to the event callback data.