NVIDIA DriveOS Linux NSR SDK API Reference
7.0.3.0 Release
Functions
NvSciBuf APIs
Buffer Allocation APIs

Detailed Description

List of APIs to transport NvSciBuf buffers and attribute list objects across various communication boundaries that interact using NvSciIpc.

Functions

NvSciError NvSciBufIpcExportAttrListAndObj (NvSciBufObj bufObj, NvSciBufAttrValAccessPerm permissions, NvSciIpcEndpoint ipcEndpoint, void **attrListAndObjDesc, size_t *attrListAndObjDescSize)
 Exports NvSciBufAttrList and NvSciBufObj into an NvSciIpc-transferable object export descriptor. More...
 
NvSciError NvSciBufIpcImportAttrListAndObj (NvSciBufModule module, NvSciIpcEndpoint ipcEndpoint, const void *attrListAndObjDesc, size_t attrListAndObjDescSize, const NvSciBufAttrList attrList[], size_t count, NvSciBufAttrValAccessPerm minPermissions, int64_t timeoutUs, NvSciBufObj *bufObj)
 This API is invoked by the importing process after it receives the object export descriptor sent by the other process who has created descriptor. More...
 
void NvSciBufAttrListAndObjFreeDesc (void *attrListAndObjDescBuf)
 Frees the descriptor used for exporting both NvSciBufAttrList and NvSciBufObj together. More...
 
NvSciError NvSciBufObjIpcExport (NvSciBufObj bufObj, NvSciBufAttrValAccessPerm accPerm, NvSciIpcEndpoint ipcEndpoint, NvSciBufObjIpcExportDescriptor *exportData)
 Exports the NvSciBufObj into an NvSciIpc-transferable object export descriptor. More...
 
NvSciError NvSciBufObjIpcImport (NvSciIpcEndpoint ipcEndpoint, const NvSciBufObjIpcExportDescriptor *desc, NvSciBufAttrList reconciledAttrList, NvSciBufAttrValAccessPerm minPermissions, int64_t timeoutUs, NvSciBufObj *bufObj)
 Creates the NvSciBufObj based on supplied object export descriptor and returns the NvSciBufObj bound to the reconciled NvSciBufAttrList. More...
 
NvSciError NvSciBufObjAttachPeer (NvSciBufObj bufObj, const NvSciBufAttrList inputArray[], size_t inputCount)
 Allows remote peer NvSciIpcEndpoint to gain access to already allocated NvSciBufObj. More...
 
NvSciError NvSciBufAttrListIpcExportUnreconciled (const NvSciBufAttrList unreconciledAttrListArray[], size_t unreconciledAttrListCount, NvSciIpcEndpoint ipcEndpoint, void **descBuf, size_t *descLen)
 Transforms the input unreconciled NvSciBufAttrList(s) to an exportable unreconciled NvSciBufAttrList descriptor that can be transported by the application to any remote process as a serialized set of bytes over an NvSciIpc channel. More...
 
NvSciError NvSciBufAttrListIpcExportReconciled (NvSciBufAttrList reconciledAttrList, NvSciIpcEndpoint ipcEndpoint, void **descBuf, size_t *descLen)
 Transforms the reconciled NvSciBufAttrList to an exportable reconciled NvSciBufAttrList descriptor that can be transported by the application to any remote process as a serialized set of bytes over an NvSciIpc channel. More...
 
NvSciError NvSciBufAttrListIpcImportUnreconciled (NvSciBufModule module, NvSciIpcEndpoint ipcEndpoint, const void *descBuf, size_t descLen, NvSciBufAttrList *importedUnreconciledAttrList)
 Translates an exported unreconciled NvSciBufAttrList descriptor (potentially received from any process) into an unreconciled NvSciBufAttrList. More...
 
NvSciError NvSciBufAttrListIpcImportReconciled (NvSciBufModule module, NvSciIpcEndpoint ipcEndpoint, const void *descBuf, size_t descLen, const NvSciBufAttrList inputUnreconciledAttrListArray[], size_t inputUnreconciledAttrListCount, NvSciBufAttrList *importedReconciledAttrList)
 Translates an exported reconciled NvSciBufAttrList descriptor (potentially received from any process) into a reconciled NvSciBufAttrList. More...
 
void NvSciBufAttrListFreeDesc (void *descBuf)
 Frees the NvSciBuf exported NvSciBufAttrList descriptor. More...
 

Function Documentation

◆ NvSciBufAttrListAndObjFreeDesc()

void NvSciBufAttrListAndObjFreeDesc ( void *  attrListAndObjDescBuf)

Frees the descriptor used for exporting both NvSciBufAttrList and NvSciBufObj together.

Parameters
[in]attrListAndObjDescBufDescriptor to be freed. The valid value is the one returned by successful call to NvSciBufIpcExportAttrListAndObj().
Returns
void
  • Panics if:
    • if Init Mode API is called in Runtime Mode.
    • attrListAndObjDescBuf is invalid
Precondition
@id{NvSciBufAttrListAndObjFreeDesc_PreCond_001} @asil{QM} Valid descriptor used for exporting both NvSciBufAttrList and NvSciBufObj together is obtained.


Usage considerations

  • Allowed context for the API call
    • Interrupt handler: No
    • Signal handler: No
    • Thread-safe: Yes, with the following conditions:
      • Provided there is no active operation involving the attrListAndObjDescBuf to be freed
    • Re-entrant: No
    • Async/Sync: Sync
  • Required privileges: None
  • API group
    • Init: Yes
    • Runtime: No
    • De-Init: No

◆ NvSciBufAttrListFreeDesc()

void NvSciBufAttrListFreeDesc ( void *  descBuf)

Frees the NvSciBuf exported NvSciBufAttrList descriptor.

Parameters
[in]descBufNvSciBufAttrList descriptor to be freed. The valid value is non-NULL.
Returns
void
  • Panics if:
    • if Init Mode API is called in Runtime Mode.
    • descBuf is invalid
Precondition
@id{NvSciBufAttrListFreeDesc_PreCond_001} @asil{QM} Valid NvSciBufAttrList export descriptor is obtained.


Usage considerations

  • Allowed context for the API call
    • Interrupt handler: No
    • Signal handler: No
    • Thread-safe: Yes, with the following conditions:
      • Provided there is no active operation involving the descBuf to be freed
    • Re-entrant: No
    • Async/Sync: Sync
  • Required privileges: None
  • API group
    • Init: Yes
    • Runtime: No
    • De-Init: No

◆ NvSciBufAttrListIpcExportReconciled()

NvSciError NvSciBufAttrListIpcExportReconciled ( NvSciBufAttrList  reconciledAttrList,
NvSciIpcEndpoint  ipcEndpoint,
void **  descBuf,
size_t *  descLen 
)

Transforms the reconciled NvSciBufAttrList to an exportable reconciled NvSciBufAttrList descriptor that can be transported by the application to any remote process as a serialized set of bytes over an NvSciIpc channel.

Parameters
[in]reconciledAttrListThe reconciled NvSciBufAttrList to be exported.
[in]ipcEndpointNvSciIpcEndpoint. Valid value: The NvSciIpcEndpoint should be obtained from a successful call to NvSciIpcOpenEndpoint() and has not yet been freed using NvSciIpcCloseEndpointSafe().
[out]descBufA pointer to the new reconciled NvSciBufAttrList descriptor, which the caller can deallocate later using NvSciBufAttrListFreeDesc().
[out]descLenThe size of the new reconciled NvSciBufAttrList descriptor.
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.

◆ NvSciBufAttrListIpcExportUnreconciled()

NvSciError NvSciBufAttrListIpcExportUnreconciled ( const NvSciBufAttrList  unreconciledAttrListArray[],
size_t  unreconciledAttrListCount,
NvSciIpcEndpoint  ipcEndpoint,
void **  descBuf,
size_t *  descLen 
)

Transforms the input unreconciled NvSciBufAttrList(s) to an exportable unreconciled NvSciBufAttrList descriptor that can be transported by the application to any remote process as a serialized set of bytes over an NvSciIpc channel.

Parameters
[in]unreconciledAttrListArrayThe unreconciled NvSciBufAttrList(s) to be exported. The valid value is non NULL.
[in]unreconciledAttrListCountNumber of unreconciled NvSciBufAttrList(s) in unreconciledAttrListArray. This value must be non-zero. For a single list, the count must be set 1.
[in]ipcEndpointThe NvSciIpcEndpoint. Valid value: The NvSciIpcEndpoint should be obtained from a successful call to NvSciIpcOpenEndpoint() and has not yet been freed using NvSciIpcCloseEndpointSafe().
[out]descBufA pointer to the new unreconciled NvSciBufAttrList descriptor, which the caller can deallocate later using NvSciBufAttrListFreeDesc().
[out]descLenThe size of the new unreconciled NvSciBufAttrList descriptor.
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.

◆ NvSciBufAttrListIpcImportReconciled()

NvSciError NvSciBufAttrListIpcImportReconciled ( NvSciBufModule  module,
NvSciIpcEndpoint  ipcEndpoint,
const void *  descBuf,
size_t  descLen,
const NvSciBufAttrList  inputUnreconciledAttrListArray[],
size_t  inputUnreconciledAttrListCount,
NvSciBufAttrList *  importedReconciledAttrList 
)

Translates an exported reconciled NvSciBufAttrList descriptor (potentially received from any process) into a reconciled NvSciBufAttrList.

It also validates that the reconciled NvSciBufAttrList to be imported will be a reconciled NvSciBufAttrList that is consistent with the constraints in an array of input unreconciled NvSciBufAttrList(s). This is recommended while importing what is expected to be a reconciled NvSciBufAttrList to cause NvSciBuf to validate the reconciled NvSciBufAttrList against the input un-reconciled NvSciBufAttrList(s), so that the importing process can be sure that an NvSciBufObj will satisfy the input constraints.

Parameters
[in]moduleNvScibufModule with which to associate the imported NvSciBufAttrList.
[in]ipcEndpointNvSciIpcEndpoint. Valid value: The NvSciIpcEndpoint should be obtained from a successful call to NvSciIpcOpenEndpoint() and has not yet been freed using NvSciIpcCloseEndpointSafe().
[in]descBufThe reconciled NvSciBufAttrList descriptor to be translated into a reconciled NvSciBufAttrList. The valid value is non-NULL that points to descriptor received on NvSciIpc channel.
[in]descLenThe size of the reconciled NvSciBufAttrList descriptor. This value must be non-zero.
[in]inputUnreconciledAttrListArrayThe array of unreconciled NvSciBufAttrList against which the new reconciled NvSciBufAttrList is to be validated. NULL pointer is acceptable as a parameter if the validation needs to be skipped.
[in]inputUnreconciledAttrListCountThe number of unreconciled NvSciBufAttrList(s) in inputUnreconciledAttrListArray. If inputUnreconciledAttrListCount is non-zero, then this operation will fail with an error unless all the constraints of all the unreconciled NvSciBufAttrList(s) in inputUnreconciledAttrListArray are met by the imported reconciled NvSciBufAttrList. This value must be non-zero.
[out]importedReconciledAttrListImported reconciled NvSciBufAttrList.
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.

◆ NvSciBufAttrListIpcImportUnreconciled()

NvSciError NvSciBufAttrListIpcImportUnreconciled ( NvSciBufModule  module,
NvSciIpcEndpoint  ipcEndpoint,
const void *  descBuf,
size_t  descLen,
NvSciBufAttrList *  importedUnreconciledAttrList 
)

Translates an exported unreconciled NvSciBufAttrList descriptor (potentially received from any process) into an unreconciled NvSciBufAttrList.

Parameters
[in]moduleNvScibufModule with which to associate the imported NvSciBufAttrList.
[in]ipcEndpointNvSciIpcEndpoint. Valid value: The NvSciIpcEndpoint should be obtained from a successful call to NvSciIpcOpenEndpoint() and has not yet been freed using NvSciIpcCloseEndpointSafe().
[in]descBufThe unreconciled NvSciBufAttrList descriptor to be translated into an unreconciled NvSciBufAttrList. The valid value is non-NULL that points to descriptor received on NvSciIpc channel.
[in]descLenThe size of the unreconciled NvSciBufAttrList descriptor. This value must be non-zero.
[out]importedUnreconciledAttrListThe imported unreconciled NvSciBufAttrList.
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.

◆ NvSciBufIpcExportAttrListAndObj()

NvSciError NvSciBufIpcExportAttrListAndObj ( NvSciBufObj  bufObj,
NvSciBufAttrValAccessPerm  permissions,
NvSciIpcEndpoint  ipcEndpoint,
void **  attrListAndObjDesc,
size_t *  attrListAndObjDescSize 
)

Exports NvSciBufAttrList and NvSciBufObj into an NvSciIpc-transferable object export descriptor.

The blob can be transferred to the other processes to create a matching NvSciBufObj.

Parameters
[in]bufObjNvSciBufObj to export.
[in]permissionsFlag indicating the expected access permission (see NvSciBufAttrValAccessPerm). The valid value is either of NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite such that the value of NvSciBufGeneralAttrKey_ActualPerm set in the reconciled NvSciBufAttrList exported to the peer to which NvSciBufObj is being exported is less than or equal to permissions and permissions is less than or equal to underlying NvSciBufObj permission. Additionally, NvSciBufAccessPerm_Auto value is unconditionally valid.
[in]ipcEndpointNvSciIpcEndpoint to identify the peer process.
[out]attrListAndObjDescNvSciBuf allocates and fills in the exportable form of NvSciBufObj and its corresponding NvSciBufAttrList to be shared across an NvSciIpc channel.
[out]attrListAndObjDescSizeSize of the exported blob.
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.

◆ NvSciBufIpcImportAttrListAndObj()

NvSciError NvSciBufIpcImportAttrListAndObj ( NvSciBufModule  module,
NvSciIpcEndpoint  ipcEndpoint,
const void *  attrListAndObjDesc,
size_t  attrListAndObjDescSize,
const NvSciBufAttrList  attrList[],
size_t  count,
NvSciBufAttrValAccessPerm  minPermissions,
int64_t  timeoutUs,
NvSciBufObj *  bufObj 
)

This API is invoked by the importing process after it receives the object export descriptor sent by the other process who has created descriptor.

The importing process will create its own NvSciBufObj and return as output.

Parameters
[in]moduleNvSciBufModule to be used for importing NvSciBufObj.
[in]ipcEndpointNvSciIpcEndpoint to identify the peer process.
[in]attrListAndObjDescThe exported form of NvSciBufAttrList and NvSciBufObj. The valid value must be non NULL.
[in]attrListAndObjDescSizeSize of the imported blob. This value must be non-zero.
[in]attrList[]Receiver side array of NvSciBufAttrList(s) against which the imported NvSciBufAttrList has to be validated. NULL is valid value here if the validation of the received NvSciBufAttrList needs to be skipped.
[in]countNumber of NvSciBufAttrList objects in the array. This value must be non-zero, provided attrList is non-NULL.
[in]minPermissionsMinimum permissions of the NvSciBufObj that the process is expecting to import it with (see NvSciBufAttrValAccessPerm). The valid value is either of NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite such that the value is less than or equal to NvSciBufAttrValAccessPerm with which NvSciBufObj was exported. Additionally, NvSciBufAccessPerm_Auto value is unconditionally valid.
[in]timeoutUsMaximum delay (in microseconds) before an NvSciBufObj times out. The value of the variable is ignored currently.
[out]bufObjNvSciBufObj duplicated and exported during the importing process. This NvSciBufObj is associated with the reconciled NvSciBufAttrList imported from the attrListAndObjDesc.
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.

◆ NvSciBufObjAttachPeer()

NvSciError NvSciBufObjAttachPeer ( NvSciBufObj  bufObj,
const NvSciBufAttrList  inputArray[],
size_t  inputCount 
)

Allows remote peer NvSciIpcEndpoint to gain access to already allocated NvSciBufObj.

Provided that the allocated NvSciBufObj is according to buffer requirements provided by the input unreconciled attribute list of remote peer interested in gaining access to input NvSciBufObj. On success, the NvSciBufObj is exportable to remote peer NvSciIpcEndpoints whose unreconciled NvSciBufAttrList was provided as input to this function.

Parameters
[in]bufObjThe NvSciBufObj whose access needs to be granted
[in]inputArraylist of unreconciled NvSciBufAttrList imported from remote peers who wants access to the input NvSciBufObj
[in]inputCountCount of unreconciled NvSciBufAttrList provided in input inputArray
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.

◆ NvSciBufObjIpcExport()

NvSciError NvSciBufObjIpcExport ( NvSciBufObj  bufObj,
NvSciBufAttrValAccessPerm  accPerm,
NvSciIpcEndpoint  ipcEndpoint,
NvSciBufObjIpcExportDescriptor *  exportData 
)

Exports the NvSciBufObj into an NvSciIpc-transferable object export descriptor.

Descriptor can be transferred to other end of IPC where matching NvSciBufObj can be created from the descriptor.

Parameters
[in]bufObjNvSciBufObj to export.
[in]accPermFlag indicating the expected access permission (see NvSciBufAttrValAccessPerm). The valid value is either of NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite such that the value of NvSciBufGeneralAttrKey_ActualPerm set in the reconciled NvSciBufAttrList exported to the peer to which NvSciBufObj is being exported is less than or equal to accPerm and accPerm is less than or equal to underlying NvSciBufObj permission. Additionally, NvSciBufAccessPerm_Auto value is unconditionally valid.
[in]ipcEndpointNvSciIpcEndpoint. Valid value: The NvSciIpcEndpoint should be obtained from a successful call to NvSciIpcOpenEndpoint() and has not yet been freed using NvSciIpcCloseEndpointSafe().
[out]exportDataNvSciBuf populates the return value with exportable form of NvSciBufObj shared across an NvSciIpc channel.
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.

◆ NvSciBufObjIpcImport()

NvSciError NvSciBufObjIpcImport ( NvSciIpcEndpoint  ipcEndpoint,
const NvSciBufObjIpcExportDescriptor *  desc,
NvSciBufAttrList  reconciledAttrList,
NvSciBufAttrValAccessPerm  minPermissions,
int64_t  timeoutUs,
NvSciBufObj *  bufObj 
)

Creates the NvSciBufObj based on supplied object export descriptor and returns the NvSciBufObj bound to the reconciled NvSciBufAttrList.

Note
It is not guaranteed that the input reconciled NvSciBufAttrList in this API is the same NvSciBufAttrList that is ultimately associated with the allocated NvSciBufObj. If the user needs to query attributes from an NvSciBufAttrList associated with an NvSciBufObj after allocation, they must first obtain the reconciled NvSciBufAttrList from the NvSciBufObj using NvSciBufObjGetAttrList().
Parameters
[in]ipcEndpointNvSciIpcEndpoint. Valid value: The NvSciIpcEndpoint should be obtained from a successful call to NvSciIpcOpenEndpoint() and has not yet been freed using NvSciIpcCloseEndpointSafe().
[in]descA pointer to an NvSciBufObjIpcExportDescriptor. The valid value is non-NULL that points to descriptor received on NvSciIpc channel.
[in]reconciledAttrListReconciled NvSciBufAttrList returned by NvSciBufAttrListIpcImportReconciled().
[in]minPermissionsMinimum permissions of the NvSciBufObj that the process is expecting to import it with (see NvSciBufAttrValAccessPerm). The valid value is either of NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite such that the value is less than or equal to NvSciBufAttrValAccessPerm with which NvSciBufObj was exported. Additionally, NvSciBufAccessPerm_Auto value is unconditionally valid.
[in]timeoutUsMaximum delay (in microseconds) before an NvSciBufObj times out. The value of the variable is ignored currently.
[out]bufObjImported NvSciBufObj created from the descriptor.
Returns
NvSciError, the completion code of this operation:
  • NvSciError_Success if successful.
  • NvSciError_InvalidState if imported NvSciBufObj cannot be associated with NvSciBufModule with which reconciledAttrList is associated.
  • NvSciError_NotSupported if the internal attribute of reconciledAttrList represents memory domain which is not supported.
  • Panic if reconciledAttrList is invalid
Precondition
@id{NvSciBufObjIpcImport_PreCond_001} @asil{QM} Valid NvSciBufObjIpcExportDescriptor is obtained.
@id{NvSciBufObjIpcImport_PreCond_002} @asil{QM} Valid reconciled NvSciBufAttrList is obtained.
@id{NvSciBufObjIpcImport_PreCond_003} @asil{QM} Valid NvSciIpcEndpoint is obtained. @arr @id{NvSciBufObjIpcImport_REC_001} @asil{QM} NvSciBufObjIpcImport() does not take ownership of input NvSciBufAttrList. The caller remains responsible for freeing input NvSciBufAttrList. The caller may free the input NvSciBufAttrList any time after this function is called. @arr @id{NvSciBufObjIpcImport_RES_002} @asil{B} Input NvSciBufObjIpcExportDescriptor can be used to import NvSciBufObj only once i.e the same desc cannot be used to import NvSciBufObj multiple times.


Usage considerations

  • Allowed context for the API call
    • Interrupt handler: No
    • Signal handler: No
    • Thread-safe: Yes
    • Re-entrant: No
    • Async/Sync: Sync
  • Required privileges: None
  • API group
    • Init: Yes
    • Runtime: No
    • De-Init: No