Debugger API (PDF) - v8.0 (older) - Last updated September 4, 2016 - Send Feedback -

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

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;
                  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
CUDBGEvent
  Event information container.
struct
CUDBGEventCallbackData
  Event information passed to callback set with setNotifyNewEventCallback function.
struct
CUDBGEventCallbackData40
  Event information passed to callback set with setNotifyNewEventCallback 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.

### Enumerations

enum CUDBGEventKind
  CUDA Kernel Events.

### Variables

CUDBGResult ( *CUDBGAPI_st::acknowledgeEvent30 )( CUDBGEvent30* event )
  Inform the debugger API that the event has 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::getNextAsyncEvent50 )( CUDBGEvent50* event )
  Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue. The asynchronous event queue is held separate from the normal event queue, and does not require acknowledgement from the debug client.
CUDBGResult ( *CUDBGAPI_st::getNextAsyncEvent55 )( CUDBGEvent55* event )
  Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue. The asynchronous event queue is held separate from the normal event queue, and does not require acknowledgement from the debug client.
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 )
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 )
  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.

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

void ( *CUDBGNotifyNewEventCallback31 )( void* data )

  function type of the function called to notify debugger of the presence of a new event in the event queue.

### 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 occur. The debugging framework may be unstable.
  CUDBG_EVENT_CTX_PUSH = 0x005
    A CUDA context was pushed.
  CUDBG_EVENT_CTX_POP = 0x006
    A CUDA CTX was popped.
  CUDBG_EVENT_CTX_CREATE = 0x007
    A CUDA CTX was created.
  CUDBG_EVENT_CTX_DESTROY = 0x008
    A CUDA context was destroyed.
  CUDBG_EVENT_TIMEOUT = 0x009
    An timeout event is sent at regular interval. This event can safely ge ignored.
  CUDBG_EVENT_ATTACH_COMPLETE = 0x00a
    The attach process has completed and debugging of device code may start.
  CUDBG_EVENT_DETACH_COMPLETE = 0x00b
  CUDBG_EVENT_ELF_IMAGE_UNLOADED = 0x00c

### Variables

CUDBGResult ( *CUDBGAPI_st::acknowledgeEvent30 )( CUDBGEvent30* event )

  Inform the debugger API that the event has been processed. Since CUDA 3.0.

  ###### Parameters

  `event`
    - pointer to the event that has been processed

  ###### Returns

  CUDBG_SUCCESS

CUDBGResult ( *CUDBGAPI_st::acknowledgeEvents42 )( )

  Inform the debugger API that synchronous events have been processed. Since CUDA 3.1.

  ###### Returns

  CUDBG_SUCCESS

CUDBGResult ( *CUDBGAPI_st::acknowledgeSyncEvents )( )

  Inform the debugger API that synchronous events have been processed. Since CUDA 5.0.

  ###### Returns

  CUDBG_SUCCESS

CUDBGResult ( *CUDBGAPI_st::getNextAsyncEvent50 )( CUDBGEvent50* event )

  Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue. The asynchronous event queue is held separate from the normal event queue, and does not require acknowledgement from the debug client. Since CUDA 5.0.

  ###### Parameters

  `event`
    - pointer to an event container where to copy the event parameters

  ###### Returns

  CUDBG_SUCCESS, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_ARGS

CUDBGResult ( *CUDBGAPI_st::getNextAsyncEvent55 )( CUDBGEvent55* event )

  Copies the next available event in the asynchronous event queue into 'event' and removes it from the queue. The asynchronous event queue is held separate from the normal event queue, and does not require acknowledgement from the debug client. Since CUDA 5.5.

  ###### Parameters

  `event`
    - pointer to an event container where to copy the event parameters

  ###### Returns

  CUDBG_SUCCESS, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_ARGS

CUDBGResult ( *CUDBGAPI_st::getNextEvent )( CUDBGEventQueueType type, CUDBGEvent* event )

  Copies the next available event into 'event' and removes it from the queue. Since CUDA 6.0.

  ###### Parameters

  `type`
    - application event queue type
  `event`
    - pointer to an event container where to copy the event parameters

  ###### Returns

  CUDBG_SUCCESS, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_ARGS

CUDBGResult ( *CUDBGAPI_st::getNextEvent30 )( CUDBGEvent30* event )

  Copies the next available event in the event queue into 'event' and removes it from the queue. Since CUDA 3.0.

  ###### Parameters

  `event`
    - pointer to an event container where to copy the event parameters

  ###### Returns

  CUDBG_SUCCESS, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_ARGS

CUDBGResult ( *CUDBGAPI_st::getNextEvent32 )( CUDBGEvent32* event )

  Copies the next available event in the event queue into 'event' and removes it from the queue. Since CUDA 3.1.

  ###### Parameters

  `event`
    - pointer to an event container where to copy the event parameters

  ###### Returns

  CUDBG_SUCCESS, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_ARGS

CUDBGResult ( *CUDBGAPI_st::getNextEvent42 )( CUDBGEvent42* event )

  Copies the next available event in the event queue into 'event' and removes it from the queue. Since CUDA 4.0.

  ###### Parameters

  `event`
    - pointer to an event container where to copy the event parameters

  ###### Returns

  CUDBG_SUCCESS, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_ARGS

CUDBGResult ( *CUDBGAPI_st::getNextSyncEvent50 )( CUDBGEvent50* event )

  Since CUDA 5.0.

  ###### Parameters

  `event`
    - pointer to an event container where to copy the event parameters

  ###### Returns

  CUDBG_SUCCESS, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_ARGS

CUDBGResult ( *CUDBGAPI_st::getNextSyncEvent55 )( CUDBGEvent55* event )

  Copies the next available event in the synchronous event queue into 'event' and removes it from the queue. Since CUDA 5.5.

  ###### Parameters

  `event`
    - pointer to an event container where to copy the event parameters

  ###### Returns

  CUDBG_SUCCESS, CUDBG_ERROR_NO_EVENT_AVAILABLE, CUDBG_ERROR_INVALID_ARGS

CUDBGResult ( *CUDBGAPI_st::setNotifyNewEventCallback )( CUDBGNotifyNewEventCallback callback )

  Provides the API with the function to call to notify the debugger of a new application or device event. Since CUDA 4.1.

  ###### Parameters

  `callback`
    - the callback function

  ###### Returns

  CUDBG_SUCCESS

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. Since CUDA 3.0.

  ###### Parameters

  `callback`
    - the callback function
  `data`
    - a pointer to be passed to the callback when called

  ###### Returns

  CUDBG_SUCCESS

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. Since CUDA 3.2.

  ###### Parameters

  `callback`
    - the callback function

  ###### Returns

  CUDBG_SUCCESS