Debugger API :: CUDA Toolkit Documentation

3.3. Device Execution Control

Enumerations

enum CUDBGSingleStepFlags: Single step flags.
enum CUDBGSingleStepType: Single step operation type (API method that was used to start the single step operation).

Variables

CUDBGResult ( *CUDBGAPI_st::executeInternalCommand )( const char* command, char* resultBuffer, uint32_t sizeInBytes ): Execute an internal command (not available in public driver builds).
CUDBGResult ( *CUDBGAPI_st::resumeAllDevices )( ): Resume all running CUDA devices.
CUDBGResult ( *CUDBGAPI_st::resumeDevice )( uint32_t dev ): Resume a suspended CUDA device.
CUDBGResult ( *CUDBGAPI_st::resumeWarpsUntilPC )( uint32_t dev, uint32_t sm, uint64_t warpMask, uint64_t pc, uint32_t flags ): Insert a temporary breakpoint at the specified virtual PC and resume all warps in the specified bitmask on a given SM.
CUDBGResult ( *CUDBGAPI_st::resumeWarpsUntilPC60 )( uint32_t dev, uint32_t sm, uint64_t warpMask, uint64_t virtPC ): Insert a temporary breakpoint at the specified virtual PC and resume all warps in the specified bitmask on a given SM.
CUDBGResult ( *CUDBGAPI_st::setKernelLaunchNotificationMode )( CUDBGKernelLaunchNotifyMode mode ): Set the launch notification policy.
CUDBGResult ( *CUDBGAPI_st::singleStepWarp )( uint32_t dev, uint32_t sm, uint32_t wp, uint32_t laneHint, uint32_t nsteps, uint32_t flags, uint64_t* warpMask ): Single step an individual warp nsteps times on a suspended CUDA device.
CUDBGResult ( *CUDBGAPI_st::singleStepWarp40 )( uint32_t dev, uint32_t sm, uint32_t wp ): Single step an individual warp on a suspended CUDA device.
CUDBGResult ( *CUDBGAPI_st::singleStepWarp41 )( uint32_t dev, uint32_t sm, uint32_t wp, uint64_t* warpMask ): Single step an individual warp on a suspended CUDA device.
CUDBGResult ( *CUDBGAPI_st::singleStepWarp65 )( uint32_t dev, uint32_t sm, uint32_t wp, uint32_t nsteps, uint64_t* warpMask ): Single step an individual warp nsteps times on a suspended CUDA device.
CUDBGResult ( *CUDBGAPI_st::suspendAllDevices )( uint32_t nonBlocking ): Suspend all running CUDA devices.
CUDBGResult ( *CUDBGAPI_st::suspendDevice )( uint32_t dev ): Suspends a running CUDA device.

Enumerations

enum CUDBGSingleStepFlags

Values

CUDBG_SINGLE_STEP_FLAGS_NONE = 0: Default behavior.
CUDBG_SINGLE_STEP_FLAGS_NO_STEP_OVER_WARP_BARRIERS = (1U<<0): Disable optimized warp barrier stepping. Do not step over warp-wide barriers using a breakpoint and resume, instead perform a single step and return. Passing this flag in means that the API client plans to repeat the singleStepWarp() call until the warp barrier is stepped over. This gives a more precise exception information if an exception is encountered by the diverged threads while stepping. This flag is only valid for the singleStepWarp() API method, resumeWarpsUntilPC() always steps over warp-wide barriers.
CUDBG_SINGLE_STEP_FLAGS_NON_BLOCKING = (1U<<1): Don't block on the stepping operations, instead return early and send an event once stepping is done.

enum CUDBGSingleStepType

Values

CUDBG_SINGLE_STEP_TYPE_INVALID = 0: Invalid single step operation type.
CUDBG_SINGLE_STEP_TYPE_SINGLE_STEP_WARP = 1: The singleStepWarp() API method was used to start the single step operation.
CUDBG_SINGLE_STEP_TYPE_RESUME_WARPS_UNTIL_PC = 2: The resumeWarpsUntilPC() API method was used to start the single step operation.

Variables

CUDBGResult ( *CUDBGAPI_st::executeInternalCommand )( const char* command, char* resultBuffer, uint32_t sizeInBytes )

Execute an internal command (not available in public driver builds). Always returns CUDBG_ERROR_NOT_SUPPORTED.

Since CUDA 12.6.

Parameters

command: - the command name and arguments
resultBuffer: - the destination buffer
sizeInBytes: - buffer size in bytes

Returns

CUDBG_ERROR_NOT_SUPPORTED

CUDBGResult ( *CUDBGAPI_st::resumeAllDevices )( )

Resume all running CUDA devices. Since CUDA 13.2.

See also:

suspendAllDevices

Returns

CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_RUNNING_DEVICE, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL

CUDBGResult ( *CUDBGAPI_st::resumeDevice )( uint32_t dev )

Resume a suspended CUDA device. Using this method is discouraged, use resumeAllDevices() instead to avoid race conditions. This method has no effect if the device is already running.

Since CUDA 3.0.

See also:

resumeAllDevices

Parameters

dev: - device index

Returns

CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_RUNNING_DEVICE, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL

CUDBGResult ( *CUDBGAPI_st::resumeWarpsUntilPC )( uint32_t dev, uint32_t sm, uint64_t warpMask, uint64_t pc, uint32_t flags )

Insert a temporary breakpoint at the specified virtual PC and resume all warps in the specified bitmask on a given SM. Compared to resumeDevice(), this method provides finer-grain control by resuming a selected set of warps on the same SM. The main intended usage is to accelerate the single-stepping process when the target PC is known in advance. Instead of single-stepping each warp individually until the target PC is hit, the client can use this method. If an unsteppable barrier is hit by the resumed warps, this method returns early (before reaching the target PC). When this method is used, errors within CUDA kernels will no longer be reported precisely. In the situation where resuming warps is not possible, this method will return CUDBG_ERROR_WARP_RESUME_NOT_POSSIBLE. The client should then fall back to using singleStepWarp() or resumeDevice().

Since CUDA 13.2.

See also:

resumeAllDevices

singleStepWarp

Parameters

dev: - device index
sm: - the SM index
warpMask: - the bitmask of warps to resume (1 = resume, 0 = do not resume)
pc
flags: - flags of type CUDBGSingleStepFlags to change the stepping behavior

Returns

CUDBG_SUCCESS, CUDBG_ERROR_UNKNOWN_FUNCTION, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_RUNNING_DEVICE, CUDBG_ERROR_INVALID_ADDRESS, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_INVALID_CONTEXT, CUDBG_ERROR_WARP_RESUME_NOT_POSSIBLE, CUDBG_ERROR_INVALID_WARP_MASK, CUDBG_ERROR_RECURSIVE_API_CALL

CUDBGResult ( *CUDBGAPI_st::resumeWarpsUntilPC60 )( uint32_t dev, uint32_t sm, uint64_t warpMask, uint64_t virtPC )

Since CUDA 6.0.

Note:

DEPRECATED in CUDA 13.2: Use resumeWarpsUntilPC instead.

See also:

resumeWarpsUntilPC

Parameters

dev: - device index
sm: - SM index
warpMask: - the bitmask of warps to resume (1 = resume, 0 = do not resume)
virtPC: - the virtual PC where the temporary breakpoint will be inserted

Returns

CUDBGResult ( *CUDBGAPI_st::setKernelLaunchNotificationMode )( CUDBGKernelLaunchNotifyMode mode )

Set the launch notification policy. If mode is CUDBG_KNL_LAUNCH_NOTIFY_EVENT, enable synchronous launch notification reporting (via events). This can noticeably slow down the execution of the application. If mode is CUDBG_KNL_LAUNCH_NOTIFY_DEFER, the launch notifications are not reported at all.

Since CUDA 5.5.

Parameters

mode: - mode to deliver kernel launch notifications in

Returns

CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL

CUDBGResult ( *CUDBGAPI_st::singleStepWarp )( uint32_t dev, uint32_t sm, uint32_t wp, uint32_t laneHint, uint32_t nsteps, uint32_t flags, uint64_t* warpMask )

Single step an individual warp nsteps times on a suspended CUDA device. By default, if the warp is on a convergence barrier, resumeWarpsUntilPC is called internally to quickly advance the warp past that barrier. If the CUDBG_SINGLE_STEP_FLAGS_NO_STEP_OVER_WARP_BARRIERS flag is passed in, this optimization is not performed (which would likely lead to diverged threads becoming focused and starting to advance towards the convergence barrier). If a warp is on a block-wide barrier (or wider), other warps required to advance past the barrier are automatically resumed. The output parameter warpMask will have the warps resumed in the current SM. Warps can also be resumed in other SMs, but are not reported via the API. This method is synchronous and will not return until the step is complete.

Since CUDA 12.4.

See also:

resumeAllDevices

resumeWarpsUntilPC

suspendAllDevices

Parameters

dev: - device index
sm: - SM index
wp: - warp index
laneHint: - focused lane (~0 to let the API decide)
nsteps: - number of single steps
flags: - flags of type CUDBGSingleStepFlags to change the stepping behavior
warpMask: - the warps that have been single-stepped

Returns

CUDBG_SUCCESS, CUDBG_ERROR_UNKNOWN_FUNCTION, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_INVALID_WARP, CUDBG_ERROR_RUNNING_DEVICE, CUDBG_ERROR_INVALID_ADDRESS, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_INVALID_CONTEXT, CUDBG_ERROR_WARP_RESUME_NOT_POSSIBLE, CUDBG_ERROR_INVALID_WARP_MASK, CUDBG_ERROR_RECURSIVE_API_CALL

CUDBGResult ( *CUDBGAPI_st::singleStepWarp40 )( uint32_t dev, uint32_t sm, uint32_t wp )

Single step an individual warp on a suspended CUDA device. Behaves like singleStepWarp41 without the output warpMask parameter.

Since CUDA 3.0.

Note:

DEPRECATED in CUDA 4.1: Use singleStepWarp instead.

See also:

singleStepWarp

Parameters

dev: - device index
sm: - SM index
wp: - warp index

Returns

CUDBGResult ( *CUDBGAPI_st::singleStepWarp41 )( uint32_t dev, uint32_t sm, uint32_t wp, uint64_t* warpMask )

Single step an individual warp on a suspended CUDA device. Behaves like singleStepWarp65 with nsteps set to 1.

Since CUDA 4.1.

Note:

DEPRECATED in CUDA 6.5: Use singleStepWarp instead.

See also:

singleStepWarp

Parameters

dev: - device index
sm: - SM index
wp: - warp index
warpMask: - the warps that have been single-stepped

Returns

CUDBGResult ( *CUDBGAPI_st::singleStepWarp65 )( uint32_t dev, uint32_t sm, uint32_t wp, uint32_t nsteps, uint64_t* warpMask )

Single step an individual warp nsteps times on a suspended CUDA device. Behaves like singleStepWarp with no lane hint and the CUDBG_SINGLE_STEP_FLAGS_NO_STEP_OVER_WARP_BARRIERS flag set.

Since CUDA 6.5.

Note:

DEPRECATED in CUDA 12.4: Use singleStepWarp instead.

See also:

singleStepWarp

Parameters

dev: - device index
sm: - SM index
wp: - warp index
nsteps: - number of single steps
warpMask: - the warps that have been single-stepped

Returns

CUDBGResult ( *CUDBGAPI_st::suspendAllDevices )( uint32_t nonBlocking )

Suspend all running CUDA devices. If the nonBlocking flag is non-zero, the function returns immediately and sends CUDBG_EVENT_ALL_DEVICES_SUSPENDED when the operation finishes in the background. Otherwise, if the function returns with CUDBG_SUCCESS, that guarantees that all devices have been suspended.

Since CUDA 13.2.

See also:

resumeAllDevices

Parameters

nonBlocking: - whether or not asynchronous operation is desired

Returns

CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_INTERNAL, CUDBG_ERROR_SUSPENDED_DEVICE, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL

CUDBGResult ( *CUDBGAPI_st::suspendDevice )( uint32_t dev )

Suspends a running CUDA device. Using this method is discouraged, use suspendAllDevices() instead to avoid race conditions. The device has to be suspended in order to execute most operations on it. CUDBG_ERROR_SUSPENDED_DEVICE is returned if the device is already suspended.

Since CUDA 3.0.

See also:

suspendAllDevices

Parameters

dev: - device index

Returns

CUDBG_SUCCESS, CUDBG_ERROR_INVALID_ARGS, CUDBG_ERROR_UNINITIALIZED, CUDBG_ERROR_SUSPENDED_DEVICE, CUDBG_ERROR_INITIALIZATION_FAILURE, CUDBG_ERROR_RECURSIVE_API_CALL