NVIDIA DRIVE OS Linux SDK API Reference

5.1.6.0 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Synchronization APIs

Detailed Description

The NvSciSync library allows applications to manage synchronization objects which coordinate when sequences of operations begin and end.

The following constants are defined and have type unsigned int:

In C and C++ these constants are guaranteed to be defined as global const variables.

Upon each new release of NvSciSync:

This version of this specification corresponds to NvSciSync version 1.0 (major version 1, minor version 0).

Different processes using the NvSciSync inter-process APIs may use different minor versions of NvSciSync within the same major version, provided that if a process uses a feature newer than another processor's NvSciSync version, the latter process does not import an unreconciled attribute list (directly or indirectly) from the former process.

In general, an NvSciSync API call will not return an error code if it has caused any side effects other than allocating resources and subsequently freeing those resources.

In general, unless specified otherwise, if a NULL pointer is passed to an NvSciSync API call, the API call will either return NvSciError_BadParameter or (if there are other applicable error conditions as well) an error code corresponding to another error.

Each NvSciSyncAttrList is either unreconciled or reconciled. It is unreconciled if it was:

It is reconciled if it was:

Data Structures

struct  NvSciSyncFence
 Defines the opaque NvSciSyncFence. More...
 
struct  NvSciSyncFenceIpcExportDescriptor
 Defines the exported form of NvSciSyncFence shared across an NvSciIpc channel. More...
 
struct  NvSciSyncObjIpcExportDescriptor
 Defines the exported form of NvSciSyncObj shared across an NvSciIpc channel. More...
 
struct  NvSciSyncAttrKeyValuePair
 Describes the NvSciSyncAttrKey-Value pair. More...
 

Typedefs

typedef struct NvSciSyncModuleRec * NvSciSyncModule
 Represents an instance of the NvSciSync module. More...
 
typedef struct
NvSciSyncCpuWaitContextRec * 
NvSciSyncCpuWaitContext
 Represents the right to perform a CPU wait on an NvSciSyncFence. More...
 
typedef struct NvSciSyncObjRec * NvSciSyncObj
 Holds a pointer to an opaque NvSciSync object. More...
 
typedef struct
NvSciSyncAttrListRec * 
NvSciSyncAttrList
 Holds a pointer to an opaque NvSciSync attribute list. More...
 

Enumerations

enum  NvSciSyncAccessPerm {
  NvSciSyncAccessPerm_WaitOnly,
  NvSciSyncAccessPerm_SignalOnly,
  NvSciSyncAccessPerm_WaitSignal
}
 Describes sync object access permissions. More...
 
enum  NvSciSyncAttrKey {
  NvSciSyncAttrKey_LowerBound,
  NvSciSyncAttrKey_NeedCpuAccess,
  NvSciSyncAttrKey_RequiredPerm,
  NvSciSyncAttrKey_ActualPerm,
  NvSciSyncAttrKey_WaiterContextInsensitiveFenceExports,
  NvSciSyncAttrKey_UpperBound
}
 Describes the types of NvSciSyncAttr keys. More...
 

Functions

NvSciError NvSciSyncModuleOpen (NvSciSyncModule *newModule)
 Initializes an instance of the NvSciSync module within the calling process and provides an NvSciSyncModule representing the instance. More...
 
void NvSciSyncModuleClose (NvSciSyncModule module)
 Releases an instance of the NvSciSync module that was obtained through an earlier call to NvSciSyncModuleOpen(). More...
 
NvSciError NvSciSyncCpuWaitContextAlloc (NvSciSyncModule module, NvSciSyncCpuWaitContext *newContext)
 Allocates a CPU wait context that can be used to perform a CPU wait with NvSciSyncFenceWait(). More...
 
void NvSciSyncCpuWaitContextFree (NvSciSyncCpuWaitContext context)
 Releases a CPU wait context. More...
 
NvSciError NvSciSyncAttrListCreate (NvSciSyncModule module, NvSciSyncAttrList *attrList)
 Creates an attribute list holding the attributes of the NvSciSyncObj to be allocated. More...
 
void NvSciSyncAttrListFree (NvSciSyncAttrList attrList)
 Frees the memory of an attribute list. More...
 
NvSciError NvSciSyncAttrListIsReconciled (NvSciSyncAttrList attrList, bool *isReconciled)
 Returns whether the attribute list is reconciled or unreconciled. More...
 
NvSciError NvSciSyncAttrListValidateReconciled (NvSciSyncAttrList reconciledAttrList, const NvSciSyncAttrList inputUnreconciledAttrListArray[], size_t inputUnreconciledAttrListCount, bool *isReconciledListValid)
 Validates a reconciled attribute list against a set of input unreconciled attribute lists. More...
 
NvSciError NvSciSyncAttrListSetAttrs (NvSciSyncAttrList attrList, const NvSciSyncAttrKeyValuePair *pairArray, size_t pairCount)
 Sets the value of an attribute in an unreconciled attribute list that has not already been set. More...
 
NvSciError NvSciSyncAttrListGetAttrs (NvSciSyncAttrList attrList, NvSciSyncAttrKeyValuePair *pairArray, size_t pairCount)
 Gets the value of attributes from an attribute list. More...
 
size_t NvSciSyncAttrListGetSlotCount (NvSciSyncAttrList attrList)
 Gets the total number of slots contained in a NvSciSyncAttrList. More...
 
NvSciError NvSciSyncAttrListAppendUnreconciled (const NvSciSyncAttrList inputUnreconciledAttrListArray[], size_t inputUnreconciledAttrListCount, NvSciSyncAttrList *newUnreconciledAttrList)
 Appends multiple unreconciled attribute lists together, forming a single new unreconciled attribute list with a slot count equal to the sum of all the slot counts of the input list. More...
 
NvSciError NvSciSyncAttrListClone (NvSciSyncAttrList origAttrList, NvSciSyncAttrList *newAttrList)
 Clones an unreconciled/reconciled attribute list. More...
 
NvSciError NvSciSyncAttrListSlotGetAttrs (NvSciSyncAttrList attrList, size_t slotIndex, NvSciSyncAttrKeyValuePair *pairArray, size_t pairCount)
 Gets the value of attributes from an attribute list at given index in a multi-slot unreconciled attribute list. More...
 
NvSciError NvSciSyncAttrListReconcile (const NvSciSyncAttrList inputArray[], size_t inputCount, NvSciSyncAttrList *newReconciledList, NvSciSyncAttrList *newConflictList)
 Reconciles the input unreconciled attribute list(s) into a new reconciled attribute list. More...
 
NvSciError NvSciSyncAttrListDebugDump (NvSciSyncAttrList attrList, void **buf, size_t *len)
 Dumps the attribute list into a binary blob. More...
 
NvSciError NvSciSyncAttrListIpcExportUnreconciled (const NvSciSyncAttrList unreconciledAttrListArray[], size_t unreconciledAttrListCount, NvSciIpcEndpoint ipcEndpoint, void **descBuf, size_t *descLen)
 Translates the unreconciled attribute list(s) to an exported attribute list descriptor that can potentially be transported by the application to any process as a serialized array of bytes. More...
 
NvSciError NvSciSyncAttrListIpcExportReconciled (const NvSciSyncAttrList reconciledAttrList, NvSciIpcEndpoint ipcEndpoint, void **descBuf, size_t *descLen)
 Translates the reconciled attribute list to an exported attribute list descriptor that can potentially be transported by the application to any process as a serialized array of bytes. More...
 
NvSciError NvSciSyncAttrListIpcImportUnreconciled (NvSciSyncModule module, NvSciIpcEndpoint ipcEndpoint, const void *descBuf, size_t descLen, NvSciSyncAttrList *importedUnreconciledAttrList)
 Translates an exported attribute list descriptor (potentially received from any process) into an attribute list. More...
 
NvSciError NvSciSyncAttrListIpcImportReconciled (NvSciSyncModule module, NvSciIpcEndpoint ipcEndpoint, const void *descBuf, size_t descLen, const NvSciSyncAttrList inputUnreconciledAttrListArray[], size_t inputUnreconciledAttrListCount, NvSciSyncAttrList *importedReconciledAttrList)
 Translates an exported attribute list descriptor (potentially received from any process) into an attribute list. More...
 
void NvSciSyncAttrListFreeDesc (void *descBuf)
 Frees an exported attribute list descriptor previously returned by NvSciSyncAttrListExport(). More...
 
void NvSciSyncFenceClear (NvSciSyncFence *syncFence)
 Frees any resources allocated for the specified fence. More...
 
NvSciError NvSciSyncFenceDup (const NvSciSyncFence *srcSyncFence, NvSciSyncFence *dstSyncFence)
 Duplicates srcSyncFence into dstSyncFence, such that any wait on destSyncFence will complete at the same time as a wait on srcSyncFence. More...
 
NvSciError NvSciSyncObjAlloc (NvSciSyncAttrList reconciledList, NvSciSyncObj *syncObj)
 Allocates a sync object that meets all the constraints in the specified reconciled attribute list. More...
 
NvSciError NvSciSyncObjDup (NvSciSyncObj syncObj, NvSciSyncObj *dupObj)
 Duplicates a valid NvSciSyncObj. More...
 
NvSciError NvSciSyncObjGetAttrList (NvSciSyncObj syncObj, NvSciSyncAttrList *syncAttrList)
 Retrieves the attribute list from an allocated NvSciSync Object. More...
 
void NvSciSyncObjFree (NvSciSyncObj syncObj)
 Destroys the NvSciSync object and all memory that was allocated for it. More...
 
NvSciError NvSciSyncObjIpcExport (NvSciSyncObj syncObj, NvSciSyncAccessPerm permissions, NvSciIpcEndpoint ipcEndpoint, NvSciSyncObjIpcExportDescriptor *desc)
 Exports a NvSciSync object into an NvSciIpc-transferable object binary descriptor. More...
 
NvSciError NvSciSyncObjIpcImport (NvSciIpcEndpoint ipcEndpoint, const NvSciSyncObjIpcExportDescriptor *desc, NvSciSyncAttrList inputAttrList, NvSciSyncAccessPerm permissions, int64_t timeoutUs, NvSciSyncObj *syncObj)
 Creates an NvSciSync object based on supplied binary descriptor and returns the sync object. More...
 
NvSciError NvSciSyncIpcExportFence (const NvSciSyncFence *syncFence, NvSciIpcEndpoint ipcEndpoint, NvSciSyncFenceIpcExportDescriptor *desc)
 Exports a NvSciSyncFence into a binary descriptor shareable across the NvSciIpc channel. More...
 
NvSciError NvSciSyncIpcImportFence (NvSciSyncObj syncObj, const NvSciSyncFenceIpcExportDescriptor *desc, NvSciSyncFence *syncFence)
 Fills in the NvSciSyncFence object based on supplied binary descriptor. More...
 
NvSciError NvSciSyncObjGenerateFence (NvSciSyncObj syncObj, NvSciSyncFence *syncFence)
 Generates next point on sync timeline of an NvSciSync object and fills in the supplied NvSciSyncFence object. More...
 
NvSciError NvSciSyncObjSignal (NvSciSyncObj syncObj)
 Signal the NvSciSync object. More...
 
NvSciError NvSciSyncFenceWait (const NvSciSyncFence *syncFence, NvSciSyncCpuWaitContext context, int64_t timeoutUs)
 Performs a synchronous wait on the NvSciSyncFence object until the fence has been signaled or the timeout expires. More...
 
NvSciError NvSciSyncAttrListGetAttr (NvSciSyncAttrList attrList, NvSciSyncAttrKey key, const void **value, size_t *len)
 NvSciSync Utility functions. More...
 
NvSciError NvSciSyncAttrListReconcileAndObjAlloc (const NvSciSyncAttrList inputArray[], size_t inputCount, NvSciSyncObj *syncObj, NvSciSyncAttrList *newConflictList)
 Reconcile the input unreconciled attribute list(s) into a new reconciled attribute list and allocate a sync object that meets all the constraints in the new reconciled attribute list. More...
 
NvSciError NvSciSyncIpcExportAttrListAndObj (NvSciSyncObj syncObj, NvSciSyncAccessPerm permissions, NvSciIpcEndpoint ipcEndpoint, void **attrListAndObjDesc, size_t *attrListAndObjDescSize)
 Exports an NvSciSync attribute list and object into an NvSciIpc-transferable object binary blob pointed to by the data param. More...
 
void NvSciSyncAttrListAndObjFreeDesc (void *attrListAndObjDescBuf)
 Frees an exported attribute-list-and-sync-object descriptor returned by NvSciSyncIpcExportAttrListAndObj(). More...
 
NvSciError NvSciSyncIpcImportAttrListAndObj (NvSciSyncModule module, NvSciIpcEndpoint ipcEndpoint, const void *attrListAndObjDesc, size_t attrListAndObjDescSize, NvSciSyncAttrList const attrList[], size_t attrListCount, NvSciSyncAccessPerm minPermissions, int64_t timeoutUs, NvSciSyncObj *syncObj)
 Creates an NvSciSync object based on the supplied binary descriptor and returns the sync object. More...
 

Variables

static const uint32_t NvSciSyncMajorVersion = 1U
 NvSciSync version. More...
 
static const uint32_t NvSciSyncMinorVersion = 0U
 
static const NvSciSyncFence NvSciSyncFenceInitializer = {{0U}}
 Defines the value used to zero-initialize the NvSciSyncFence object. More...
 

Typedef Documentation

typedef struct NvSciSyncAttrListRec* NvSciSyncAttrList

Holds a pointer to an opaque NvSciSync attribute list.

Note
Every NvSciSyncAttrList that has been created but not freed holds a reference to the NvSciSync module, preventing the module from being de-initialized.

Definition at line 183 of file nvscisync.h.

typedef struct NvSciSyncCpuWaitContextRec* NvSciSyncCpuWaitContext

Represents the right to perform a CPU wait on an NvSciSyncFence.

It holds resources necessary to perform a CPU wait. It can be used to wait on NvSciSyncFences associated with the same NvSciSyncModule that this NvSciSyncCpuWaitContext is associated with. An NvSciSyncCpuWaitContext can be used to wait on only one NvSciSyncFence at a time. However, a single NvSciSyncCpuWaitContext can be used to wait on different NvSciSyncFences at different instants of time.

Definition at line 124 of file nvscisync.h.

typedef struct NvSciSyncModuleRec* NvSciSyncModule

Represents an instance of the NvSciSync module.

Any NvSciSyncAttrList created or imported using a particular NvSciSyncModule is bound to that module instance, along with any NvSciSyncObjs created or imported using those NvSciSyncAttrLists and any NvSciSyncFences created or imported using those NvSciSyncObjs.

Note
For any NvSciSync API call that has more than one input of type NvSciSyncModule, NvSciSyncAttrList, NvSciSyncObj, and/or NvSciSyncFence, all such inputs must agree on the NvSciSync module instance.

Definition at line 112 of file nvscisync.h.

typedef struct NvSciSyncObjRec* NvSciSyncObj

Holds a pointer to an opaque NvSciSync object.

Note
Every NvSciSyncObj that has been created but not freed holds a reference to the NvSciSync module, preventing the module from being de-initialized.

Definition at line 174 of file nvscisync.h.

Enumeration Type Documentation

Describes sync object access permissions.

Enumerator
NvSciSyncAccessPerm_WaitOnly 

This represents the capability to monitor an NvSciSync object as it progresses through points on its sync timeline.

NvSciSyncAccessPerm_SignalOnly 

This represents the capability to advance an NvSciSync object to its next point on its sync timeline.

NvSciSyncAccessPerm_WaitSignal 

This represents the capability to advance an NvSciSync object to its next point on its sync timeline and also monitor when that next point is reached.

Definition at line 188 of file nvscisync.h.

Describes the types of NvSciSyncAttr keys.

Enumerator
NvSciSyncAttrKey_LowerBound 

Specifies the lower bound - for NvSciSync internal use only.

NvSciSyncAttrKey_NeedCpuAccess 

(bool) Specifies if CPU access is required.

NvSciSyncAttrKey_RequiredPerm 

(NvSciSyncAccessPerm) Specifies the required access permissions.

If NvSciSyncAttrKey_NeedCpuAccess is true, the CPU will be offered at least these permissions. Any hardware accelerators that contribute to this attribute list will be offered at least these permissions.

NvSciSyncAttrKey_ActualPerm 

(NvSciSyncAccessPerm) Actual permission granted after reconciliation.

Note
This key is read-only.
NvSciSyncAttrKey_WaiterContextInsensitiveFenceExports 

(bool) Importing and then exporting an NvSciSyncFenceIpcExportDescriptor has no side effects and yields an identical NvSciSyncFenceIpcExportDescriptor even if the NvSciIpcEndpoints used for import and export are distinct.

NvSciSyncAttrKey_UpperBound 

Specifies the upper bound - for NvSciSync internal use only.

Definition at line 210 of file nvscisync.h.

Function Documentation

void NvSciSyncAttrListAndObjFreeDesc ( void *  attrListAndObjDescBuf)

Frees an exported attribute-list-and-sync-object descriptor returned by NvSciSyncIpcExportAttrListAndObj().

Parameters
[in]attrListAndObjDescBufExported attribute-list-and-sync-object descriptor to be freed.
Returns
void
NvSciError NvSciSyncAttrListAppendUnreconciled ( const NvSciSyncAttrList  inputUnreconciledAttrListArray[],
size_t  inputUnreconciledAttrListCount,
NvSciSyncAttrList newUnreconciledAttrList 
)

Appends multiple unreconciled attribute lists together, forming a single new unreconciled attribute list with a slot count equal to the sum of all the slot counts of the input list.

Parameters
[in]inputUnreconciledAttrListArrayArray containing the unreconciled attribute lists to be appended together.
[in]inputUnreconciledAttrListCountNumber of unreconciled attribute lists to append.
[out]newUnreconciledAttrListAppended attribute list created out of the input unreconciled attribute lists.
Returns
NvSciError, the completion code of the operation:
  • NvSciError_Success if successful.
  • NvSciError_BadParameter if any of the following occurs:
    • inputUnreconciledAttrListArray is NULL or
    • newUnreconciledAttrList is NULL or
    • inputUnreconciledAttrListCount is zero or
    • any of the input attribute lists are reconciled, or
    • not all the NvSciSyncAttrLists in inputUnreconciledAttrListArray are bound to the same NvSciSync module instance.
  • NvSciError_InsufficientMemory if there is insufficient system memory to create the new unreconciled attribute list.
NvSciError NvSciSyncAttrListClone ( NvSciSyncAttrList  origAttrList,
NvSciSyncAttrList newAttrList 
)

Clones an unreconciled/reconciled attribute list.

The cloned attribute list will contain all the values of the original attribute list. If the original attribute list is unreconciled, then modification will be allowed on the cloned list using set attributes APIs, but these calls to set attributes in either list will not affect the other.

Parameters
[in]origAttrListThe list to be cloned.
[out]newAttrListThe new clone of origAttrList.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListCreate ( NvSciSyncModule  module,
NvSciSyncAttrList attrList 
)

Creates an attribute list holding the attributes of the NvSciSyncObj to be allocated.

Parameters
[in]moduleThe NvSciSync module instance with which to associate the new NvSciSyncAttrList.
[out]attrListThe address of the newly created attribute list.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListDebugDump ( NvSciSyncAttrList  attrList,
void **  buf,
size_t *  len 
)

Dumps the attribute list into a binary blob.

Note
This API can be used for debugging purpose.
Parameters
[in]attrListAttribute list to create the blob from.
[out]bufA pointer to binary blob buffer.
[out]lenThe length of the binary blob buffer created.
Returns
NvSciError, the completion code of the operation:
void NvSciSyncAttrListFree ( NvSciSyncAttrList  attrList)

Frees the memory of an attribute list.

Parameters
[in]attrListThe attribute list to be freed.
Returns
void
void NvSciSyncAttrListFreeDesc ( void *  descBuf)

Frees an exported attribute list descriptor previously returned by NvSciSyncAttrListExport().

Parameters
[in]descBufThe exported attribute list descriptor to be freed.
Returns
void
NvSciError NvSciSyncAttrListGetAttr ( NvSciSyncAttrList  attrList,
NvSciSyncAttrKey  key,
const void **  value,
size_t *  len 
)

NvSciSync Utility functions.

Gets the attribute value from the attribute list with the given key.

Parameters
[in]attrListAttribute list to retrieve the attribute key and value from.
[in]keyThe key for the attribute value to retrieve.
[out]valueA pointer to the location where the attribute value is written.
[out]lenLength of the value structure.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListGetAttrs ( NvSciSyncAttrList  attrList,
NvSciSyncAttrKeyValuePair pairArray,
size_t  pairCount 
)

Gets the value of attributes from an attribute list.

The return values, stored in NvSciSyncAttrKeyValuePair, consist of const void* pointers to the attribute values from NvSciSyncAttrList. The application must not write to this data.

Parameters
[in]attrListAttribute list to retrieve the attribute key and value from.
[in,out]pairArrayA pointer to the array of attribute key/value pair structure.
[in]pairCountThe number of elements/entries in pairArray.
Returns
NvSciError, the completion code of the operation:
size_t NvSciSyncAttrListGetSlotCount ( NvSciSyncAttrList  attrList)

Gets the total number of slots contained in a NvSciSyncAttrList.

Parameters
[in]attrListAttribute list to get the slot count from.
Returns
Number of slots or 0 if attrList is NULL or panic if attrList is invalid.
Note
When exporting an array containing multiple unreconciled attribute lists, the importing endpoint still imports just one unreconciled attribute list. This unreconciled attribute list is referred to as a multi-slot attribute list. It logically represents an array of attribute lists, where each key has an array of values, one per slot. This is mainly useful for debugging purpose.
NvSciError NvSciSyncAttrListIpcExportReconciled ( const NvSciSyncAttrList  reconciledAttrList,
NvSciIpcEndpoint  ipcEndpoint,
void **  descBuf,
size_t *  descLen 
)

Translates the reconciled attribute list to an exported attribute list descriptor that can potentially be transported by the application to any process as a serialized array of bytes.

Parameters
[in]reconciledAttrListThe attribute list to be exported.
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller may send the exported attribute list descriptor.
[out]descBufA pointer to the new attribute descriptor, which the caller can deallocate later using NvSciSyncAttrListFreeDesc().
[out]descLenThe size of the new attribute descriptor.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListIpcExportUnreconciled ( const NvSciSyncAttrList  unreconciledAttrListArray[],
size_t  unreconciledAttrListCount,
NvSciIpcEndpoint  ipcEndpoint,
void **  descBuf,
size_t *  descLen 
)

Translates the unreconciled attribute list(s) to an exported attribute list descriptor that can potentially be transported by the application to any process as a serialized array of bytes.

Parameters
[in]unreconciledAttrListArrayAttribute list(s) to be exported.
[in]unreconciledAttrListCountNumber of attribute lists in the array. This value must be non-zero. For a single list, the count must be set 1.
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller may send the exported attribute list descriptor.
[out]descBufA pointer to the new attribute descriptor, which the caller can deallocate later using NvSciSyncAttrListFreeDesc().
[out]descLenThe size of the new attribute descriptor.
Returns
NvSciError, the completion code of the operation:
  • NvSciError_Success if successful.
  • NvSciError_BadParameter if any of the following occurs:
    • unreconciledAttrListCount is zero or
    • unreconciledAttrListArray is NULL or
    • ipcEndpoint is NULL or
    • descBuf is NULL or
    • descLen is NULL or
    • Not all of the NvSciSyncAttrLists in attrListArray are bound to the same NvSciSync module instance.
  • NvSciError_InsufficientMemory if memory allocation failed.
NvSciError NvSciSyncAttrListIpcImportReconciled ( NvSciSyncModule  module,
NvSciIpcEndpoint  ipcEndpoint,
const void *  descBuf,
size_t  descLen,
const NvSciSyncAttrList  inputUnreconciledAttrListArray[],
size_t  inputUnreconciledAttrListCount,
NvSciSyncAttrList importedReconciledAttrList 
)

Translates an exported attribute list descriptor (potentially received from any process) into an attribute list.

It also validates that the attribute list to be imported will be a reconciled attribute list that is consistent with the constraints in an array of input unreconciled attribute lists. This is recommended while importing what is expected to be a reconciled attribute list to cause NvSciSync to validate the reconciled attributes against the input attributes so that the importing process can be sure that an NvSciSync object consistent with the imported reconciled list will satisfy the input constraints.

Parameters
[in]moduleThe NvSciSync module instance with which to associate the imported NvSciSyncAttrList.
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller receives the exported attribute list descriptor.
[in]descBufThe attribute list descriptor to be translated into an attribute list.
[in]descLenThe size of the attribute list descriptor.
[in]inputUnreconciledAttrListArrayThe array of attribute lists against which the new attribute list is to be validated.
[in]inputUnreconciledAttrListCountThe number of attribute lists in inputUnreconciledAttrListArray. If inputUnreconciledAttrListCount is non-zero, then this operation will fail with an error unless all the constraints of all the attribute lists in inputUnreconciledAttrListArray are met by the imported attribute list.
[out]importedReconciledAttrListImported attribute list.
Returns
NvSciError, the completion code of the operation:
  • NvSciError_Success if successful.
  • NvSciError_BadParameter if any of the following occurs:
    • module is NULL or
    • ipcEndpoint is NULL or
    • the array of bytes indicated by descBuf and descLen do not constitute a valid exported attribute list descriptor for a reconciled attribute list or
    • importedReconciledAttrList is NULL or
    • both inputUnreconciledAttrListCount is non-zero and inputUnreconciledAttrListArray is NULL or
    • any of the NvSciSyncAttrLists in inputUnreconciledAttrListArray is not bound to a module.
  • NvSciError_AttrListValidationFailed if the attribute list to be imported either would not be a reconciled attribute list or would not meet at least one of constraints in one of the input unreconciled attribute lists.
  • NvSciError_InsufficientMemory if memory allocation failed.
NvSciError NvSciSyncAttrListIpcImportUnreconciled ( NvSciSyncModule  module,
NvSciIpcEndpoint  ipcEndpoint,
const void *  descBuf,
size_t  descLen,
NvSciSyncAttrList importedUnreconciledAttrList 
)

Translates an exported attribute list descriptor (potentially received from any process) into an attribute list.

Parameters
[in]moduleThe NvSciSyncModule instance with which to associate the imported NvSciSyncAttrList.
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller receives the exported attribute list descriptor.
[in]descBufThe attribute list descriptor to be translated into an attribute list.
[in]descLenThe size of the attribute list descriptor.
[out]importedUnreconciledAttrListImported attribute list.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListIsReconciled ( NvSciSyncAttrList  attrList,
bool *  isReconciled 
)

Returns whether the attribute list is reconciled or unreconciled.

Parameters
[in]attrListAttribute list of type NvSciSyncAttrList.
[out]isReconciledFalse if attrList is unreconciled, true if attrList is reconciled.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListReconcile ( const NvSciSyncAttrList  inputArray[],
size_t  inputCount,
NvSciSyncAttrList newReconciledList,
NvSciSyncAttrList newConflictList 
)

Reconciles the input unreconciled attribute list(s) into a new reconciled attribute list.

On success, this API call allocates memory for the reconciled attribute list which has to be freed by the caller using NvSciSyncAttrListFree().

On reconciliation failure, this API call allocates memory for the conflicting attribute list which has to be freed by the caller using NvSciSyncAttrListFree().

Parameters
[in]inputArrayArray containing unreconciled attribute list(s) to be reconciled.
[in]inputCountThe number of unreconciled attributes lists in inputArray.
[out]newReconciledListReconciled attribute list. This field is populated only if the reconciliation succeeded.
[out]newConflictListUnreconciled attribute list consisting of the key/value pairs which caused the reconciliation failure. This field is populated only if the reconciliation failed.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListReconcileAndObjAlloc ( const NvSciSyncAttrList  inputArray[],
size_t  inputCount,
NvSciSyncObj syncObj,
NvSciSyncAttrList newConflictList 
)

Reconcile the input unreconciled attribute list(s) into a new reconciled attribute list and allocate a sync object that meets all the constraints in the new reconciled attribute list.

Parameters
[in]inputArrayArray containing unreconciled attribute list(s) to reconcile.
[in]inputCountNumber of unreconciled attributes lists in inputArray.
[out]syncObjThe new NvSciSync object.
[out]newConflictListUnreconciled attribute list consisting of the key/value pairs which caused the reconciliation failure. This field is populated only if the reconciliation failed.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListSetAttrs ( NvSciSyncAttrList  attrList,
const NvSciSyncAttrKeyValuePair pairArray,
size_t  pairCount 
)

Sets the value of an attribute in an unreconciled attribute list that has not already been set.

Reads values only during the call, saving copies.

Parameters
[in,out]attrListAn unreconciled attribute list containing the attribute key and value to set.
[in]pairArrayA pointer to the array of attribute key/value pair structure.
[in]pairCountThe number of elements/entries in pairArray.
Returns
NvSciError, the completion code of the operation:
  • NvSciError_Success if successful.
  • NvSciError_BadParameter if any of the following occurs:
    • pairArray is NULL or
    • attrList is NULL or
    • attrList is a reconciled and/or imported attribute list, or
    • attrList already has a value of non-zero length for any of the keys in pairArray.
  • NvSciError_InsufficientMemory if there is insufficient system memory to set the attribute(s).
NvSciError NvSciSyncAttrListSlotGetAttrs ( NvSciSyncAttrList  attrList,
size_t  slotIndex,
NvSciSyncAttrKeyValuePair pairArray,
size_t  pairCount 
)

Gets the value of attributes from an attribute list at given index in a multi-slot unreconciled attribute list.

Note
When exporting an array containing multiple unreconciled attribute lists, the importing endpoint still imports just one unreconciled attribute list. This unreconciled attribute list is referred to as a multi-slot attribute list. It logically represents an array of attribute lists, where each key has an array of values, one per slot. This is mainly useful for debug purpose.

The returned pairArray consist of const void* pointers to the actual attribute values from NvSciSyncAttrList. The application must not overwrite this data.

Parameters
[in]attrListAttribute list to retrieve the attribute key and value from.
[in]slotIndexIndex in the attribute list array.
[in,out]pairArrayA pointer to the array of attribute key/value pair structure.
[in]pairCountIndicates the number of elements/entries in pairArray.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncAttrListValidateReconciled ( NvSciSyncAttrList  reconciledAttrList,
const NvSciSyncAttrList  inputUnreconciledAttrListArray[],
size_t  inputUnreconciledAttrListCount,
bool *  isReconciledListValid 
)

Validates a reconciled attribute list against a set of input unreconciled attribute lists.

Parameters
[in]reconciledAttrListReconciled attribute list to be validated.
[in]inputUnreconciledAttrListArrayArray containing the unreconciled attribute lists used for validation.
[in]inputUnreconciledAttrListCountNumber of unreconciled attribute lists.
[out]isReconciledListValidFlag indicating if the reconciled list satisfies the parameters of set of unreconciled lists.
Returns
NvSciError, the completion code of the operation:
  • NvSciError_Success if successful.
  • NvSciError_BadParameter if any of the following occurs:
    • inputUnreconciledAttrListArray is NULL or
    • inputUnreconciledAttrListCount is 0 or
    • isReconciledListValid is NULL or
    • any of the input attribute lists are reconciled or
    • reconciledAttrList is not reconciled or
    • not all the NvSciSyncAttrLists in inputUnreconciledAttrListArray and the reconciledAttrList are bound to the same NvSciSync module instance.
NvSciError NvSciSyncCpuWaitContextAlloc ( NvSciSyncModule  module,
NvSciSyncCpuWaitContext newContext 
)

Allocates a CPU wait context that can be used to perform a CPU wait with NvSciSyncFenceWait().

Parameters
[in]moduleNvSciSync module instance with which to associate the new CPU wait context.
[out]newContextAddress at which the new context is created.
Returns
NvSciError, the completion code of the operation:
void NvSciSyncCpuWaitContextFree ( NvSciSyncCpuWaitContext  context)

Releases a CPU wait context.

Parameters
[in]contextCPU wait context to be freed.
Returns
void
void NvSciSyncFenceClear ( NvSciSyncFence syncFence)

Frees any resources allocated for the specified fence.

Upon return, the memory pointed to by syncFence is guaranteed to be all zeros and thus the NvSciSyncFence is returned to its initialized state.

Parameters
[in,out]syncFenceA pointer to NvSciSyncFence.
Returns
void
NvSciError NvSciSyncFenceDup ( const NvSciSyncFence srcSyncFence,
NvSciSyncFence dstSyncFence 
)

Duplicates srcSyncFence into dstSyncFence, such that any wait on destSyncFence will complete at the same time as a wait on srcSyncFence.

If srcSyncFence is in a cleared state, then so also will be dstSyncFence.

Parameters
[in]srcSyncFenceThe source NvSciSyncFence object.
[out]dstSyncFenceThe destination NvSciSyncFence object.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncFenceWait ( const NvSciSyncFence syncFence,
NvSciSyncCpuWaitContext  context,
int64_t  timeoutUs 
)

Performs a synchronous wait on the NvSciSyncFence object until the fence has been signaled or the timeout expires.

Any CpuWaitContext may be used for waiting on any NvSciSyncFence provided they were created in the same NvSciSyncModule context. One CpuWaitContext can be used to wait on only one NvSciSyncFence at a time but it can be used to wait on a different NvSciSyncFence at a different time.

Parameters
[in]syncFenceThe syncFence to wait on.
[in]contextCPU wait context holding resources needed to perform waiting.
[in]timeoutUsTimeout to wait for in micro seconds, -1 for infinite wait.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncIpcExportAttrListAndObj ( NvSciSyncObj  syncObj,
NvSciSyncAccessPerm  permissions,
NvSciIpcEndpoint  ipcEndpoint,
void **  attrListAndObjDesc,
size_t *  attrListAndObjDescSize 
)

Exports an NvSciSync attribute list and object into an NvSciIpc-transferable object binary blob pointed to by the data param.

The blob can be transferred to the other signalers and waiters to create a matching NvSciSync object.

Parameters
[in]syncObjNvSciSync object to export.
[in]permissionsFlag indicating the expected access permission.
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller may send the exported attribute list and sync object descriptor.
[out]attrListAndObjDescExported form of attribute list and NvSciSyncObj shareable across an NvSciIpc channel.
[out]attrListAndObjDescSizeSize of the exported blob.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncIpcExportFence ( const NvSciSyncFence syncFence,
NvSciIpcEndpoint  ipcEndpoint,
NvSciSyncFenceIpcExportDescriptor desc 
)

Exports a NvSciSyncFence into a binary descriptor shareable across the NvSciIpc channel.

Parameters
[in]syncFenceA pointer to NvSciSyncFence object to be exported.
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller may send the exported fence descriptor.
[out]descThe exported form of NvSciSyncFence shared across an NvSciIpc channel.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncIpcImportAttrListAndObj ( NvSciSyncModule  module,
NvSciIpcEndpoint  ipcEndpoint,
const void *  attrListAndObjDesc,
size_t  attrListAndObjDescSize,
NvSciSyncAttrList const  attrList[],
size_t  attrListCount,
NvSciSyncAccessPerm  minPermissions,
int64_t  timeoutUs,
NvSciSyncObj syncObj 
)

Creates an NvSciSync object based on the supplied binary descriptor and returns the sync object.

This function is called from the waiter after it receives the binary blob by the signaler who has created the binary descriptor. Waiter will create its own sync object and return as output.

Parameters
[in]moduleA NvSciSyncModule to associate the imported NvSciSyncAttrList with.
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller receives the exported attribute list and sync object descriptor.
[in]attrListAndObjDescExported form of attribute list and NvSciSyncObj received through NvSciIpc channel.
[in]attrListAndObjDescSizeSize of the exported blob.
[in]attrListReceiver/caller side attribute list array.
[in]attrListCountNumber of lists in the attrList array.
[in]minPermissionsFlag indicating the expected access permission.
[in]timeoutUsImport timeout in micro seconds, -1 for infinite wait.
[out]syncObjWaiter's NvSciSync object.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncIpcImportFence ( NvSciSyncObj  syncObj,
const NvSciSyncFenceIpcExportDescriptor desc,
NvSciSyncFence syncFence 
)

Fills in the NvSciSyncFence object based on supplied binary descriptor.

Parameters
[in]syncObjAn object of type NvSciSyncObj.
[in]descThe exported form of NvSciSyncFence.
[out]syncFenceA pointer to NvSciSyncFence object.
Returns
NvSciError, the completion code of the operation:
void NvSciSyncModuleClose ( NvSciSyncModule  module)

Releases an instance of the NvSciSync module that was obtained through an earlier call to NvSciSyncModuleOpen().

Once an NvSciSyncModule is closed and all NvSciSyncAttrLists, NvSciSyncObjs, NvSciSyncFences bound to that module instance are freed, the NvSciSync module instance will be de-initialized in the calling process.

Parameters
[in]moduleThe NvSciSync module instance to close. The calling process must not pass this module to another NvSciSync API call.
Returns
void
NvSciError NvSciSyncModuleOpen ( NvSciSyncModule newModule)

Initializes an instance of the NvSciSync module within the calling process and provides an NvSciSyncModule representing the instance.

Note
A process may call this function multiple times. Each successful invocation will yield a new NvSciSync module instance.
Parameters
[out]newModuleThe new NvSciSync module instance.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncObjAlloc ( NvSciSyncAttrList  reconciledList,
NvSciSyncObj syncObj 
)

Allocates a sync object that meets all the constraints in the specified reconciled attribute list.

Note
This function does not take ownership of the reconciledList. The caller remains responsible for freeing the reconciledList. The caller may free the reconciledList any time after this function is called.
Parameters
[in]reconciledListThe reconciled attribute list generated through NvSciSyncAttrListReconcile().
[out]syncObjIdentifier representing NvSciSync object.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncObjDup ( NvSciSyncObj  syncObj,
NvSciSyncObj dupObj 
)

Duplicates a valid NvSciSyncObj.

Parameters
[in]syncObjThe source NvSciSyncObj.
[out]dupObjThe destination NvSciSyncObj.
Returns
NvSciError, the completion code of the operation:
void NvSciSyncObjFree ( NvSciSyncObj  syncObj)

Destroys the NvSciSync object and all memory that was allocated for it.

Parameters
[in]syncObjA valid NvSciSync object.
Returns
void
NvSciError NvSciSyncObjGenerateFence ( NvSciSyncObj  syncObj,
NvSciSyncFence syncFence 
)

Generates next point on sync timeline of an NvSciSync object and fills in the supplied NvSciSyncFence object.

This function is called when the CPU is the signaler.

Parameters
[in]syncObjA valid NvSciSync object.
[out]syncFenceA pointer to NvSciSyncFence object.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncObjGetAttrList ( NvSciSyncObj  syncObj,
NvSciSyncAttrList syncAttrList 
)

Retrieves the attribute list from an allocated NvSciSync Object.

Note
The retrieved attribute list from an object is always read-only and attribute values in the list cannot be changed using set attribute API. In addition, the returned attribute list must not be freed with NvSciSyncAttrListFree().
Parameters
[in]syncObjHandle corresponding to NvSciSync object from which the attribute list has to be retrieved.
[out]syncAttrListpointer to the retrieved attribute list.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncObjIpcExport ( NvSciSyncObj  syncObj,
NvSciSyncAccessPerm  permissions,
NvSciIpcEndpoint  ipcEndpoint,
NvSciSyncObjIpcExportDescriptor desc 
)

Exports a NvSciSync object into an NvSciIpc-transferable object binary descriptor.

The blob can be transferred to the other signalers and waiters to create a matching NvSciSync object.

Parameters
[in]syncObjNvSciSync object to export.
[in]permissionsFlag indicating the expected access permission.
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller may send the exported sync object descriptor.
[out]descNvSciSync fills in caller-supplied descriptor with exported form of NvSciSyncObj shared across an NvSciIpc channel.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncObjIpcImport ( NvSciIpcEndpoint  ipcEndpoint,
const NvSciSyncObjIpcExportDescriptor desc,
NvSciSyncAttrList  inputAttrList,
NvSciSyncAccessPerm  permissions,
int64_t  timeoutUs,
NvSciSyncObj syncObj 
)

Creates an NvSciSync object based on supplied binary descriptor and returns the sync object.

It is called from the waiter after it receives the binary blob by the signaler who has created the binary descriptor. Waiter will create its own sync object and return as output.

Note
This function does not take ownership of inputAttrList. The caller remains responsible for freeing inputAttrList. The caller may free inputAttrList any time after this function is called.
Parameters
[in]ipcEndpointThe NvSciIpcEndpoint through which the caller receives the exported sync object descriptor.
[in]descThe exported form of NvSciSyncObj received through the NvSciIpc channel.
[in]inputAttrListThe attribute list returned by NvSciSyncImportAttrList().
[in]permissionsFlag indicating the expected access permission.
[in]timeoutUsThe import timeout in micro seconds, -1 for infinite wait.
[out]syncObjThe waiter's NvSciSync Object.
Returns
NvSciError, the completion code of the operation:
NvSciError NvSciSyncObjSignal ( NvSciSyncObj  syncObj)

Signal the NvSciSync object.

This function is called when the CPU is the signaler.

Parameters
[in]syncObjA valid NvSciSync object to signal.
Returns
NvSciError, the completion code of the operation:

Variable Documentation

const NvSciSyncFence NvSciSyncFenceInitializer = {{0U}}
static

Defines the value used to zero-initialize the NvSciSyncFence object.

An NvSciSyncFence that is all zeroes is in a cleared state.

Definition at line 149 of file nvscisync.h.

const uint32_t NvSciSyncMajorVersion = 1U
static

NvSciSync version.

Definition at line 98 of file nvscisync.h.

const uint32_t NvSciSyncMinorVersion = 0U
static

Definition at line 99 of file nvscisync.h.