DriveWorks SDK Reference
3.0.4260 Release
For Test and Development only

Core Context

Detailed Description

Defines the core Context methods of the SDK.

Note
SW Release Applicability: These APIs are available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

Data Structures

struct  dwContextParameters
 A set of parameters that is passed to the SDK to create the context. More...
 
struct  dwCustomizedFileFunctions
 Data structure representing a customize FileStream that can be passed in. More...
 

Typedefs

typedef struct dwContextObject const * dwConstContextHandle_t
 
typedef struct dwContextObject * dwContextHandle_t
 Context handle. More...
 
typedef void * dwCustomizedFileHandle
 FileStream function pointers handle. More...
 
typedef struct dwVisualizationContextObject const * dwVisualizationConstContextHandle_t
 
typedef struct dwVisualizationContextObject * dwVisualizationContextHandle_t
 Context handle. More...
 

Functions

DW_API_PUBLIC dwStatus dwContext_getCUDAProperties (int32_t *driverVersion, int32_t *apiVersion, dwContextHandle_t context)
 Returns Driver and Runtime API version of CUDA on the current machine. More...
 
DW_API_PUBLIC dwStatus dwContext_getCurrentTime (dwTime_t *time, dwContextHandle_t context)
 Returns the current timestamp. More...
 
DW_API_PUBLIC dwStatus dwContext_getDataPath (const char **dataPath, dwContextHandle_t context)
 Gets the data path of the library that contains the driveworks context. More...
 
DW_API_PUBLIC dwStatus dwContext_getDLAEngineCount (int32_t *count, dwContextHandle_t context)
 Get the available DLA engines count. More...
 
DW_API_PUBLIC dwStatus dwContext_getGPUArchitecture (const char **architecture, dwContextHandle_t context)
 Returns the architecture for the currently selected CUDA device. More...
 
DW_API_PUBLIC dwStatus dwContext_getGPUAttribute (int32_t *value, cudaDeviceAttr attribute, int32_t deviceNum, dwContextHandle_t context)
 Returns the value of the selected CUDA attribute for the specific CUDA device. More...
 
DW_API_PUBLIC dwStatus dwContext_getGPUCount (int32_t *count, dwContextHandle_t context)
 Get the available GPU devices count. More...
 
DW_API_PUBLIC dwStatus dwContext_getGPUDeviceCurrent (int32_t *deviceNumber, dwContextHandle_t context)
 Returns the currently selected GPU device. More...
 
DW_API_PUBLIC dwStatus dwContext_getGPUDeviceType (dwGPUDeviceType *deviceType, int32_t deviceNum, dwContextHandle_t context)
 Returns the device type of the input GPU number. More...
 
DW_API_PUBLIC dwStatus dwContext_getGPUProperties (cudaDeviceProp *properties, int32_t deviceNum, dwContextHandle_t context)
 Returns the properties for the specific CUDA device. More...
 
DW_API_PUBLIC dwStatus dwContext_getPVAEngineCount (uint32_t *count, dwContextHandle_t context)
 Get the available PVA engines count. More...
 
DW_API_PUBLIC dwStatus dwContext_isTimePTPSynchronized (bool *flag, dwContextHandle_t context)
 Check if the used time source inside the context is synchronized over PTP. More...
 
DW_API_PUBLIC dwStatus dwContext_selectGPUDevice (int32_t deviceNumber, dwContextHandle_t context)
 Selects a GPU device, if available. More...
 
DW_API_PUBLIC dwStatus dwContext_setCustomFileFunctions (dwContextHandle_t context, dwCustomizedFileFunctions *fileFunctionPtr)
 Set the customized fileStream function pointers in context. More...
 
DW_API_PUBLIC dwStatus dwGetLastError (const char **errorMsg)
 Retrieves the last error encountered. More...
 
DW_API_PUBLIC dwStatus dwInitialize (dwContextHandle_t *context, dwVersion header_version, const dwContextParameters *params)
 Creates and initializes an SDK context. More...
 
DW_API_PUBLIC dwStatus dwRelease (dwContextHandle_t context)
 Releases the context. More...
 
DW_VIZ_API_PUBLIC dwStatus dwVisualizationGetDWContext (dwContextHandle_t *dwctx, dwVisualizationContextHandle_t context)
 Return DW context associated with this visualization library. More...
 
DW_VIZ_API_PUBLIC dwStatus dwVisualizationInitialize (dwVisualizationContextHandle_t *vizContext, dwContextHandle_t ctx)
 Creates and initializes a Visualization SDK context. More...
 
DW_VIZ_API_PUBLIC dwStatus dwVisualizationRelease (dwVisualizationContextHandle_t context)
 Releases the context. More...
 

Data Structure Documentation

◆ dwContextParameters

struct dwContextParameters
Data Fields
const char * dataPath Path where all DriveWorks related data required during runtime are stored.

If path is set to NULL, then a data folder is looked for in typical install locations in relation to the current driveworks library install location.

bool enableCudaTaskGraph if true, Cuda task-graph will be used where possible.
bool enablePVA if true, PVA platform will be enabled.
Note
Without PVA some SDK modules will stop working properly.
There can be maximum 8 SDK contexts with PVA running simultaneously.
bool skipCudaInit if true will skip CUDA initialization in the context
Note
Without CUDA some SDK modules will stop working properly.

Typedef Documentation

◆ dwConstContextHandle_t

typedef struct dwContextObject const* dwConstContextHandle_t

Definition at line 81 of file Context.h.

◆ dwContextHandle_t

typedef struct dwContextObject* dwContextHandle_t

Context handle.

Definition at line 80 of file Context.h.

◆ dwCustomizedFileHandle

typedef void* dwCustomizedFileHandle

FileStream function pointers handle.

Definition at line 128 of file Context.h.

◆ dwVisualizationConstContextHandle_t

typedef struct dwVisualizationContextObject const* dwVisualizationConstContextHandle_t

Definition at line 70 of file Visualization.h.

◆ dwVisualizationContextHandle_t

typedef struct dwVisualizationContextObject* dwVisualizationContextHandle_t

Context handle.

Definition at line 69 of file Visualization.h.

Function Documentation

◆ dwContext_getCUDAProperties()

DW_API_PUBLIC dwStatus dwContext_getCUDAProperties ( int32_t *  driverVersion,
int32_t *  apiVersion,
dwContextHandle_t  context 
)

Returns Driver and Runtime API version of CUDA on the current machine.

Parameters
[out]driverVersionDriver version.
[out]apiVersionRuntime API version.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if context handle, driverVersion or apiVersion are NULL.
DW_CUDA_ERROR in case of an underlying CUDA failure
DW_SUCCESS

◆ dwContext_getCurrentTime()

DW_API_PUBLIC dwStatus dwContext_getCurrentTime ( dwTime_t time,
dwContextHandle_t  context 
)

Returns the current timestamp.

Timestamps from the same context are guaranteed to be in sync. The returned time represents the absolute time as received through system time source. On POSIX based systems, the time is measured using CLOCK_MONOTONIC time source. On Windows based systems, the returned time is relative to the epoch, i.e., 31std dec, 1969.

Parameters
[out]timeA pointer to the return time to a given location, in [us].
[in]contextSpecifies the context.
Returns
DW_INVALID_ARGUMENT if given context handle or time is are NULL.
DW_SUCCESS

◆ dwContext_getDataPath()

DW_API_PUBLIC dwStatus dwContext_getDataPath ( const char **  dataPath,
dwContextHandle_t  context 
)

Gets the data path of the library that contains the driveworks context.

Parameters
[out]dataPathPath to the Driveworks data.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if context handle or descriptor pointer are NULL.
DW_SUCCESS

◆ dwContext_getDLAEngineCount()

DW_API_PUBLIC dwStatus dwContext_getDLAEngineCount ( int32_t *  count,
dwContextHandle_t  context 
)

Get the available DLA engines count.

Parameters
[out]countThe number of DLA engines available.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if context handle is NULL.
DW_SUCCESS

◆ dwContext_getGPUArchitecture()

DW_API_PUBLIC dwStatus dwContext_getGPUArchitecture ( const char **  architecture,
dwContextHandle_t  context 
)

Returns the architecture for the currently selected CUDA device.

Parameters
[out]architectureA string containing the architecture.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if value pointer or context handle is NULL.
DW_SUCCESS

◆ dwContext_getGPUAttribute()

DW_API_PUBLIC dwStatus dwContext_getGPUAttribute ( int32_t *  value,
cudaDeviceAttr  attribute,
int32_t  deviceNum,
dwContextHandle_t  context 
)

Returns the value of the selected CUDA attribute for the specific CUDA device.

Parameters
[out]valueInteger representing the value of the requested attribute.
[in]attributeSpecifies the attribute requested.
[in]deviceNumSpecifies the device number.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if value pointer or context handle is NULL or context is NULL or the selected device doesn't exist.
DW_CUDA_ERROR in case of an underlying CUDA failure
DW_NOT_AVAILABLE if no GPU devices are available
DW_SUCCESS

◆ dwContext_getGPUCount()

DW_API_PUBLIC dwStatus dwContext_getGPUCount ( int32_t *  count,
dwContextHandle_t  context 
)

Get the available GPU devices count.

Parameters
[out]countThe number of GPU devices available.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if context handle is NULL.
DW_SUCCESS

◆ dwContext_getGPUDeviceCurrent()

DW_API_PUBLIC dwStatus dwContext_getGPUDeviceCurrent ( int32_t *  deviceNumber,
dwContextHandle_t  context 
)

Returns the currently selected GPU device.

If no device is selected, will return -1.

Parameters
[out]deviceNumberThe number of GPU device.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if context handle is NULL.
DW_SUCCESS

◆ dwContext_getGPUDeviceType()

DW_API_PUBLIC dwStatus dwContext_getGPUDeviceType ( dwGPUDeviceType deviceType,
int32_t  deviceNum,
dwContextHandle_t  context 
)

Returns the device type of the input GPU number.

Parameters
[out]deviceTypeThe type of GPU device.
[in]deviceNumSpecifies the device number.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if context handle is NULL or number is invalid.
DW_SUCCESS

◆ dwContext_getGPUProperties()

DW_API_PUBLIC dwStatus dwContext_getGPUProperties ( cudaDeviceProp properties,
int32_t  deviceNum,
dwContextHandle_t  context 
)

Returns the properties for the specific CUDA device.

Parameters
[out]propertiesA struct containing the properties.
[in]deviceNumSpecifies the device number.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if value pointer or context handle is NULL or deviceNum doesn't exist.
DW_CUDA_ERROR in case of an underlying CUDA failure
DW_NOT_AVAILABLE if no GPU devices are available
DW_SUCCESS

◆ dwContext_getPVAEngineCount()

DW_API_PUBLIC dwStatus dwContext_getPVAEngineCount ( uint32_t *  count,
dwContextHandle_t  context 
)

Get the available PVA engines count.

Parameters
[out]countThe number of PVA engines available.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if context handle is NULL.
DW_SUCCESS

◆ dwContext_isTimePTPSynchronized()

DW_API_PUBLIC dwStatus dwContext_isTimePTPSynchronized ( bool *  flag,
dwContextHandle_t  context 
)

Check if the used time source inside the context is synchronized over PTP.

PTP synchronization is available starting from PDK 4.1.6.4 and provides a solution to synchronize mutiple DrivePX2 or AutoCruise boxes to a common clock base. All sensor readings as well as the 'dwContext_getCurrentTime()' method will be based on the same time source.

Parameters
[out]flagReturn true if PTP synchronized time is used.
[in]contextSpecifies the context.
Returns
DW_INVALID_ARGUMENT if given context handle or time is are NULL.
DW_NOT_SUPPORTED if the method is called on a system where PTP synchronized time is not supported, i.e. PDK < 4.1.6.4 or x86 based host.
DW_SUCCESS
Note
Synchronized time is only available if PTP daemon has been identified during context creation.
PTP time base is not guaranteed to be epoch based.
It might happen at run-time that the PTP daemon is not responding anymore and PTP synchronization will be lost. In such case DW context will continue to count based on the last synced PTP time. There is no current mechanism to determine whether the PTP framework lost its sync during runtime.

◆ dwContext_selectGPUDevice()

DW_API_PUBLIC dwStatus dwContext_selectGPUDevice ( int32_t  deviceNumber,
dwContextHandle_t  context 
)

Selects a GPU device, if available.

Note that the selected gpu is valid for the current thread

Parameters
[in]deviceNumberThe number of GPU device.
[in]contextSpecifies the context handle.
Returns
DW_INVALID_ARGUMENT if context handle is NULL or the selected device doesn't exist.
DW_NOT_AVAILABLE if no GPU is available.
DW_CUDA_ERROR in case of an underlying CUDA failure.
DW_SUCCESS

◆ dwContext_setCustomFileFunctions()

DW_API_PUBLIC dwStatus dwContext_setCustomFileFunctions ( dwContextHandle_t  context,
dwCustomizedFileFunctions fileFunctionPtr 
)

Set the customized fileStream function pointers in context.

Parameters
[in]contexthandle
[in]fileFunctionPtrdwCustomizedFileFunctions pointer to be passed into context
Returns
DW_INVALID_ARGUMENT if given context handle or fileFunctionPtr is NULL.
DW_SUCCESS

◆ dwGetLastError()

DW_API_PUBLIC dwStatus dwGetLastError ( const char **  errorMsg)

Retrieves the last error encountered.

When a DriveWorks function reports an error, this error is stored internally. It can later be retrieved by this function. After calling this function, the error is reset and future calls will return 'DW_SUCCESS' until another error is encountered.

Error information is thread local. Each thread has its own last error and an error encountered in one thread will not be visible in another thread.

Parameters
[out]errorMsgA pointer to a pointer to a string containing a description of the last error encountered. Can be NULL to just reset last error.
Returns
The code of the last error encountered, or DW_SUCCESS if no error is recorded.

◆ dwInitialize()

DW_API_PUBLIC dwStatus dwInitialize ( dwContextHandle_t context,
dwVersion  header_version,
const dwContextParameters params 
)

Creates and initializes an SDK context.

The context is required for initialization of the SDK modules.

Parameters
[out]contextA pointer to the context handler is returned here.
[in]header_versionSpecifies current driveworks API version (usually DW_VERSION).
[in]paramsA pointer with a set of parameters to create the SDK. Can be NULL for a default set of parameters.
Returns
DW_INVALID_VERSION - If provided, version does not match the version of the library.
DW_INVALID_ARGUMENT - If provided, context pointer is null.
DW_SUCCESS

◆ dwRelease()

DW_API_PUBLIC dwStatus dwRelease ( dwContextHandle_t  context)

Releases the context.

Any module created with this context must be released before the context can be released.

Note
This method renders the context handle unusable.
Parameters
[in]contextThe context to be released.
Returns
DW_INVALID_HANDLE - If provided context is NULL or invalid.
DW_SUCCESS

◆ dwVisualizationGetDWContext()

DW_VIZ_API_PUBLIC dwStatus dwVisualizationGetDWContext ( dwContextHandle_t dwctx,
dwVisualizationContextHandle_t  context 
)

Return DW context associated with this visualization library.

Parameters
[out]dwctxContext of the DW SDK as given through dwVisualizationInitialize()
[in]contextHandle to existing dwVisualization context, created with dwInitialize.
Returns
DW_INVALID_ARGUMENT - If provided, context pointer is null.
DW_SUCCESS

◆ dwVisualizationInitialize()

DW_VIZ_API_PUBLIC dwStatus dwVisualizationInitialize ( dwVisualizationContextHandle_t vizContext,
dwContextHandle_t  ctx 
)

Creates and initializes a Visualization SDK context.

The context is required for initialization of the Visualization SDK modules.

Parameters
[out]vizContextA pointer to the context handler is returned here.
[in]ctxHandle to existing DW SDK context, created with dwInitialize.
Returns
DW_INVALID_VERSION - If provided context' version does not match the version of the library.
DW_INVALID_ARGUMENT - If provided, context pointer is null.
DW_SUCCESS
Note
Visualization SDK depends on GL components, hence an automatic initialization with dwGLInitialize will happen

◆ dwVisualizationRelease()

DW_VIZ_API_PUBLIC dwStatus dwVisualizationRelease ( dwVisualizationContextHandle_t  context)

Releases the context.

Any module created with this context must be released before the context can be released.

Note
This method renders the context handle unusable.
Parameters
[in]contextThe context to be released.
Returns
DW_INVALID_ARGUMENT - If provided context is NULL.
DW_SUCCESS