6.29. Error Log Management Functions

This section describes the error log management functions of the CUDA runtime application programming interface. The Error Log Management interface will operate on both the CUDA Driver and CUDA Runtime.

Typedefs

typedef void(CUDART_CB*  cudaLogsCallback_t )( void*  data,  cudaLogLevel logLevel, char*  message,  size_t length )

Functions

__host__ ​cudaError_t cudaLogsCurrent ( cudaLogIterator* iterator_out, unsigned int  flags )
Sets log iterator to point to the end of log buffer, where the next message would be written.
__host__ ​cudaError_t cudaLogsDumpToFile ( cudaLogIterator* iterator, const char* pathToFile, unsigned int  flags )
Dump accumulated driver logs into a file.
__host__ ​cudaError_t cudaLogsDumpToMemory ( cudaLogIterator* iterator, char* buffer, size_t* size, unsigned int  flags )
Dump accumulated driver logs into a buffer.
__host__ ​cudaError_t cudaLogsRegisterCallback ( cudaLogsCallback_t callbackFunc, void* userData, cudaLogsCallbackHandle* callback_out )
Register a callback function to receive error log messages.
__host__ ​cudaError_t cudaLogsUnregisterCallback ( cudaLogsCallbackHandle callback )
Unregister a log message callback.

Typedefs

void(CUDART_CB* cudaLogsCallback_t )( void*  data,  cudaLogLevel logLevel, char*  message,  size_t length )

Type of public error reporting callback functions.

Parameters
data
User parameter provided at registration
cudaLogLevel logLevel
message
Error log message being reported
size_t length

Functions

__host__ ​cudaError_t cudaLogsCurrent ( cudaLogIterator* iterator_out, unsigned int  flags )
Sets log iterator to point to the end of log buffer, where the next message would be written.
Parameters
iterator_out
- Location to store an iterator to the current tail of the logs
flags
- Reserved for future use, must be 0
Returns

cudaSuccess, cudaErrorInvalidValue,

Description

__host__ ​cudaError_t cudaLogsDumpToFile ( cudaLogIterator* iterator, const char* pathToFile, unsigned int  flags )
Dump accumulated driver logs into a file.
Parameters
iterator
- Optional auto-advancing iterator specifying the starting log to read. NULL value dumps all logs.
pathToFile
- Path to output file for dumping logs
flags
- Reserved for future use, must be 0
Returns

cudaSuccess, cudaErrorInvalidValue,

Description

Logs generated by the driver are stored in an internal buffer and can be copied out using this API. This API dumps all driver logs starting from iterator into pathToFile provided.

Note:

  • iterator is auto-advancing. Dumping logs will update the value of iterator to receive the next generated log.

  • The driver reserves limited memory for storing logs. The oldest logs may be overwritten and become unrecoverable. An indication will appear in the destination outupt if the logs have been truncated. Call dump after each failed API to mitigate this risk.

__host__ ​cudaError_t cudaLogsDumpToMemory ( cudaLogIterator* iterator, char* buffer, size_t* size, unsigned int  flags )
Dump accumulated driver logs into a buffer.
Parameters
iterator
- Optional auto-advancing iterator specifying the starting log to read. NULL value dumps all logs.
buffer
- Pointer to dump logs
size
- See description
flags
- Reserved for future use, must be 0
Returns

cudaSuccess, cudaErrorInvalidValue,

Description

Logs generated by the driver are stored in an internal buffer and can be copied out using this API. This API dumps driver logs from iterator into buffer up to the size specified in *size. The driver will always null terminate the buffer but there will not be a null character between log entries, only a newline \n. The driver will then return the actual number of bytes written in *size, excluding the null terminator. If there are no messages to dump, *size will be set to 0 and the function will return CUDA_SUCCESS. If the provided buffer is not large enough to hold any messages, *size will be set to 0 and the function will return CUDA_ERROR_INVALID_VALUE.

Note:

  • iterator is auto-advancing. Dumping logs will update the value of iterator to receive the next generated log.

  • The driver reserves limited memory for storing logs. The maximum size of the buffer is 25600 bytes. The oldest logs may be overwritten and become unrecoverable. An indication will appear in the destination outupt if the logs have been truncated. Call dump after each failed API to mitigate this risk.

  • If the provided value in *size is not large enough to hold all buffered messages, a message will be added at the head of the buffer indicating this. The driver then computes the number of messages it is able to store in buffer and writes it out. The final message in buffer will always be the most recent log message as of when the API is called.

__host__ ​cudaError_t cudaLogsRegisterCallback ( cudaLogsCallback_t callbackFunc, void* userData, cudaLogsCallbackHandle* callback_out )
Register a callback function to receive error log messages.
Parameters
callbackFunc
- The function to register as a callback
userData
- A generic pointer to user data. This is passed into the callback function.
callback_out
- Optional location to store the callback handle after it is registered
Returns

cudaSuccess, cudaErrorInvalidValue,

Description

__host__ ​cudaError_t cudaLogsUnregisterCallback ( cudaLogsCallbackHandle callback )
Unregister a log message callback.
Parameters
callback
- The callback instance to unregister from receiving log messages
Returns

cudaSuccess, cudaErrorInvalidValue,

Description