NvMedia VPI Synchronization

Detailed Description

The NvMedia VPI NvSciSync API encompasses NvMedia VPI functions using synchronization.

Macros
#define	NVMEDIA_VPI_NVSCISYNC_VERSION_MAJOR   1
	Major version number. More...
#define	NVMEDIA_VPI_NVSCISYNC_VERSION_MINOR   0
	Minor version number. More...
#define	NVMEDIA_VPI_MAX_PRENVSCISYNCFENCES   (3U)
	Maximum number of times NvMediaVPIInsertPreNvSciSyncFence() can be called before each VPI queue call. More...
#define	LAST_QUEUED_TASK_IDX   (0xFFFFFFFF)
	Index of last queued task. More...

Functions
NvMediaStatus	NvMediaVPINvSciSyncGetVersion (NvMediaVersion *version)
	Returns the version information for the NvMedia VPI NvSciSync library. More...
NvMediaStatus	NvMediaVPIFillNvSciSyncAttrList (NvMediaVPI *vpi, NvSciSyncAttrList attrlist, NvMediaNvSciSyncClientType clienttype)
	Fills the NvMediaVPI specific NvSciSync attributes. More...
NvMediaStatus	NvMediaVPIRegisterNvSciSyncObj (NvMediaVPI *vpi, NvMediaNvSciSyncObjType syncobjtype, NvSciSyncObj nvscisync)
	Registers an NvSciSyncObj with NvMediaVPI. More...
NvMediaStatus	NvMediaVPIUnRegisterNvSciSyncObj (NvMediaVPI *vpi, NvSciSyncObj nvscisync)
	Unregisters an NvSciSyncObj with NvMediaVPI. More...
NvMediaStatus	NvMediaVPISetNvSciSyncObjforSOF (NvMediaVPI *vpi, NvSciSyncObj nvscisyncSOF)
	Sets the NvSciSyncObj to be used for a Start of Frame (SOF) NvSciSyncFence. More...
NvMediaStatus	NvMediaVPISetNvSciSyncObjforEOF (NvMediaVPI *vpi, NvSciSyncObj nvscisyncEOF)
	Sets the NvSciSyncObj to be used for an End of Frame (EOF) NvSciSyncFence. More...
NvMediaStatus	NvMediaVPIInsertPreNvSciSyncFence (NvMediaVPI *vpi, const NvSciSyncFence *prenvscisyncfence)
	Sets an NvSciSyncFence as a prefence for a VPI submit operation. More...
NvMediaStatus	NvMediaVPIGetSOFNvSciSyncFence (NvMediaVPI *vpi, NvSciSyncObj sofnvscisyncobj, NvSciSyncFence *sofnvscisyncfence, uint32_t opIdx)
	Gets an SOF NvSciSyncFence for a queued VPI task. More...
NvMediaStatus	NvMediaVPIGetEOFNvSciSyncFence (NvMediaVPI *vpi, NvSciSyncObj eofnvscisyncobj, NvSciSyncFence *eofnvscisyncfence, uint32_t opIdx)
	Gets an EOF NvSciSyncFence for a queued VPI task. More...

Macro Definition Documentation

LAST_QUEUED_TASK_IDX

#define LAST_QUEUED_TASK_IDX   (0xFFFFFFFF)

Index of last queued task.

Definition at line 50 of file nvmedia_vpi_nvscisync.h.

NVMEDIA_VPI_MAX_PRENVSCISYNCFENCES

#define NVMEDIA_VPI_MAX_PRENVSCISYNCFENCES   (3U)

Maximum number of times NvMediaVPIInsertPreNvSciSyncFence() can be called before each VPI queue call.

Definition at line 47 of file nvmedia_vpi_nvscisync.h.

NVMEDIA_VPI_NVSCISYNC_VERSION_MAJOR

#define NVMEDIA_VPI_NVSCISYNC_VERSION_MAJOR   1

Major version number.

Definition at line 39 of file nvmedia_vpi_nvscisync.h.

NVMEDIA_VPI_NVSCISYNC_VERSION_MINOR

#define NVMEDIA_VPI_NVSCISYNC_VERSION_MINOR   0

Minor version number.

Definition at line 41 of file nvmedia_vpi_nvscisync.h.

Function Documentation

NvMediaVPIFillNvSciSyncAttrList()

NvMediaStatus NvMediaVPIFillNvSciSyncAttrList	(	NvMediaVPI *	vpi,
		NvSciSyncAttrList	attrlist,
		NvMediaNvSciSyncClientType	clienttype
	)

Fills the NvMediaVPI specific NvSciSync attributes.

This API assumes that attrlist is a valid NvSciSyncAttrList.

This function sets the public attributes:

• NvSciSyncAttrKey_RequiredPerm

The application must not set this attribute.

Parameters

[in]	vpi	An NvMedia VPI device handle.
[in,out]	attrlist	A pointer to an NvSciSyncAttrList structure where NvMedia fills NvSciSync attributes.
[in]	clienttype	Indicates whether the attributes in attrlist are requested for an NvMediaVPI signaler or waiter.

Returns

NvMediaStatus, the completion status of the operation:

• NVMEDIA_STATUS_OK if the call is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if attrlist is NULL or any of the above listed public attributes are already set.

NvMediaVPIGetEOFNvSciSyncFence()

NvMediaStatus NvMediaVPIGetEOFNvSciSyncFence	(	NvMediaVPI *	vpi,
		NvSciSyncObj	eofnvscisyncobj,
		NvSciSyncFence *	eofnvscisyncfence,
		uint32_t	opIdx
	)

Gets an EOF NvSciSyncFence for a queued VPI task.

The expiry of an EOF NvSciSyncFence associated with a queued VPI task indicates that the corresponding submitted VPI task has finished. If you use NvMediaVPIGetEOFNvSciSyncFence(), you must call it after calling NvMediaVPIFlush().

Parameters

[in]	vpi	An NvMedia VPI device handle.
[in]	eofnvscisyncobj	The EOF NvSciSyncObj associated with the NvSciSyncFence being requested.
[out]	eofnvscisyncfence	A pointer to the EOF NvSciSyncFence.
[in]	opIdx	An index of the queued operation for this object's EOF. This value can be: Between 0 and NVMEDIA_VPI_MAX_QUEUED_TASKS or LAST_QUEUED_TASK_IDX to get the EOF for the last queued task. This release supports only LAST_QUEUED_TASK_IDX.

Returns

NvMediaStatus, return status of operation:

• NVMEDIA_STATUS_OK if the function is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if vpi is not a valid NvMediaVPI handle or eofnvscisyncfence is NULL or eofnvscisyncobj was not registered with vpi type NVMEDIA_EOFSYNCOBJ or type NVMEDIA_EOF_PRESYNCOBJ.
• NVMEDIA_STATUS_ERROR if this API is called before calling VPI queue API.

NvMediaVPIGetSOFNvSciSyncFence()

NvMediaStatus NvMediaVPIGetSOFNvSciSyncFence	(	NvMediaVPI *	vpi,
		NvSciSyncObj	sofnvscisyncobj,
		NvSciSyncFence *	sofnvscisyncfence,
		uint32_t	opIdx
	)

Gets an SOF NvSciSyncFence for a queued VPI task.

The expiry of an SOF NvSciFence associated with a queued VPI task indicates that the corresponding submitted VPI task has started. If you use NvMediaVPIGetSOFNvSciSyncFence(), the application must call it after calling NvMediaVPIFlush().

Parameters

[in]	vpi	An NvMedia VPI device handle.
[in]	sofnvscisyncobj	SOF NvSciSyncObj associated with the requested NvSciSyncFence.
[out]	sofnvscisyncfence	A pointer to the SOF NvSciSyncFence.
[in]	opIdx	An index of the queued operation for this object's SOF. This value is between 0 and NVMEDIA_VPI_MAX_QUEUED_TASKS. This release supports only 0 (SOF for first queued task).

Returns

NvMediaStatus, return status of operation:

• NVMEDIA_STATUS_OK if the function is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if vpi is not a valid NvMediaVPI handle, or sofnvscisyncfence is NULL, or sofnvscisyncobj was not registered with vpi of type NVMEDIA_SOFSYNCOBJ or type NVMEDIA_SOF_PRESYNCOBJ.
• NVMEDIA_STATUS_ERROR if this API is called before calling VPI submit API.

NvMediaVPIInsertPreNvSciSyncFence()

NvMediaStatus NvMediaVPIInsertPreNvSciSyncFence	(	NvMediaVPI *	vpi,
		const NvSciSyncFence *	prenvscisyncfence
	)

Sets an NvSciSyncFence as a prefence for a VPI submit operation.

If you use NvMediaVPIInsertPreNvSciSyncFence(), the application must call it before calling a VPI algorithm queue API. The following queued VPI task is started only after the expiry of the prenvscisyncfence.

Currently, before calling NvMediaVPIFlush() for a sequence of queued VPI tasks, you may call NvMediaVPIInsertPreNvSciSyncFence() only once.

You can set a maximum of NVMEDIA_VPI_MAX_PRENVSCISYNCFENCES prefences by calling NvMediaVPIInsertPreNvSciSyncFence() before calling a VPI queue function. After a call to the VPI queue function, all NvSciSyncFences previously inserted by NvMediaVPIInsertPreNvSciSyncFence() are cleared, and they are not reused for the subsequent VPI queue calls.

Parameters

[in]	vpi	An NvMedia VPI device handle. This structure is modified internally.
[in]	prenvscisyncfence	A pointer to NvSciSyncFence.

Returns

NvMediaStatus, the completion status of the operation:

• NVMEDIA_STATUS_OK if the function is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if vpi is not a valid NvMediaVPI handle or prenvscisyncfence is NULL, or if prenvscisyncfence was not generated with an NvSciSyncObj that was registered with vpi as either type NVMEDIA_PRESYNCOBJ or type NVMEDIA_EOF_PRESYNCOBJ.
• NVMEDIA_STATUS_NOT_SUPPORTED if NvMediaVPIInsertPreNvSciSyncFence() was already called at least NVMEDIA_VPI_MAX_PRENVSCISYNCFENCES times with the same vpi NvMediaVPI handle before a VPI queue call.

NvMediaVPINvSciSyncGetVersion()

NvMediaStatus NvMediaVPINvSciSyncGetVersion

(

NvMediaVersion *

version

)

Returns the version information for the NvMedia VPI NvSciSync library.

Parameters

[out]

version

A pointer to an NvMediaVersion structure filled by the VPI NvSciSync library.

Returns

NvMediaStatus, the completion status of the operation:

• NVMEDIA_STATUS_OK if the call is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.

NvMediaVPIRegisterNvSciSyncObj()

NvMediaStatus NvMediaVPIRegisterNvSciSyncObj	(	NvMediaVPI *	vpi,
		NvMediaNvSciSyncObjType	syncobjtype,
		NvSciSyncObj	nvscisync
	)

Registers an NvSciSyncObj with NvMediaVPI.

Every NvSciSyncObj(even duplicate objects) used by NvMediaVPI must be registered by a call to this function before it is used. Only the exact same registered NvSciSyncObj can be passed to the run time APIs.

For a given NvMediaVPI handle, one NvSciSyncObj can be registered as one NvMediaNvSciSyncObjType only. For each NvMediaNvSciSyncObjType, a maximum of 16 NvSciSyncObjs can be registered.

Parameters

[in]	vpi	An NvMedia VPI device handle.
[in]	syncobjtype	Determines how nvscisync is used by vpi.
[in]	nvscisync	The NvSciSyncObj to be registered with vpi.

Returns

NvMediaStatus, the completion status of the operation:

• NVMEDIA_STATUS_OK if the function is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if vpi is NULL or syncobjtype is not a valid NvMediaNvSciSyncObjType.
• NVMEDIA_STATUS_NOT_SUPPORTED if nvscisync is not a compatible NvSciSyncObj which NvMediaVPI can support.
• NVMEDIA_STATUS_ERROR if the maximum number of NvSciScynObjs are already registered for the given syncobjtype, or if nvscisync is already registered with the same vpi handle for a different syncobjtype.

NvMediaVPISetNvSciSyncObjforEOF()

NvMediaStatus NvMediaVPISetNvSciSyncObjforEOF	(	NvMediaVPI *	vpi,
		NvSciSyncObj	nvscisyncEOF
	)

Sets the NvSciSyncObj to be used for an End of Frame (EOF) NvSciSyncFence.

To use NvMediaVPIGetEOFNvSciSyncFence(), the application must call this function before calling a VPI task queue function.

NvMediaVPI currently accepts only one EOF NvSciSyncObj. Therefore, NvMediaVPISetNvSciSyncObjforEOF() can be called only once for an NvMediaVPI handle. Currently, EOF is signaled only upon the completion of the last queued task.

Parameters

[in]	vpi	An NvMedia VPI device handle.
[in]	nvscisyncEOF	A registered NvSciSyncObj which is to be associated with EOF NvSciSyncFence.

Returns

NvMediaStatus, the completion status of the operation:

• NVMEDIA_STATUS_OK if the function is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if vpi is NULL, or if nvscisyncEOF is not registered with vpi as either type NVMEDIA_EOFSYNCOBJ or type NVMEDIA_EOF_PRESYNCOBJ.

NvMediaVPISetNvSciSyncObjforSOF()

NvMediaStatus NvMediaVPISetNvSciSyncObjforSOF	(	NvMediaVPI *	vpi,
		NvSciSyncObj	nvscisyncSOF
	)

Sets the NvSciSyncObj to be used for a Start of Frame (SOF) NvSciSyncFence.

To use NvMediaVPIGetSOFNvSciSyncFence(), the application must call this function before calling a VPI task queue function. NvMediaVPI currently accepts only one SOF NvSciSyncObj. Therefore, NvMediaVPISetNvSciSyncObjforSOF may be called only once for an NvMediaVPI handle before a call to a VPI task queue function. Currently nvscisyncSOF is signaled before the start of the first queued task.

Parameters

[in]	vpi	An NvMedia VPI device handle.
[in]	nvscisyncSOF	A registered NvSciSyncObj to be associated with SOF NvSciSyncFence.

Returns

NvMediaStatus, the completion status of the operation:

• NVMEDIA_STATUS_OK if the function is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if vpi is NULL, or if nvscisyncSOF is not registered with vpi as either type NVMEDIA_SOFSYNCOBJ or type NVMEDIA_SOF_PRESYNCOBJ.

NvMediaVPIUnRegisterNvSciSyncObj()

NvMediaStatus NvMediaVPIUnRegisterNvSciSyncObj	(	NvMediaVPI *	vpi,
		NvSciSyncObj	nvscisync
	)

Unregisters an NvSciSyncObj with NvMediaVPI.

During teardown, every NvSciSyncObj registered with NvMediaVPI must be unregistered before calling NvMediaVPIDestroy().

Before the application calls this function, it must ensure that the application is in teardown mode, and any NvMediaVPI operation using this NvSciSyncObj has completed. If the function is called while NvSciSyncObj is still in use by any NvMediaVPI operations, the behavior is undefined.

Parameters

[in]	vpi	An NvMedia VPI device handle.
[in]	nvscisync	An NvSciSyncObj to be unregistered with vpi.

Returns

NvMediaStatus, the completion status of the operation:

• NVMEDIA_STATUS_OK if the function is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if vpi is NULL, or nvscisync is not registered with vpi.
• NVMEDIA_STATUS_ERROR if vpi is destroyed before this function is called.