Vic Diagnostics Synchronization

Detailed Description

The Vic Diagnostics NvSci API encompasses all Vic Diagnostics handling for NvSciSync related functions.

6

Functions
NvMediaStatus	VicDiagnosticsFillNvSciSyncAttrList (VicDiagnostics const *const handle, NvSciSyncAttrList const attrList, NvMediaNvSciSyncClientType const clientType)
	Fills the Vic Diagnostics specific NvSciSync attributes. More...
NvMediaStatus	VicDiagnosticsRegisterNvSciSyncObj (VicDiagnostics const *const handle, NvMediaNvSciSyncObjType const syncObjType, NvSciSyncObj const syncObj)
	Register an NvSciSyncObj with Vic Diagnostics. More...
NvMediaStatus	VicDiagnosticsUnregisterNvSciSyncObj (VicDiagnostics const *const handle, NvSciSyncObj const syncObj)
	Unregisters an NvSciSyncObj with VicDiagnostics. More...
NvMediaStatus	VicDiagnosticsSetNvSciSyncObjforEOF (VicDiagnostics const *const handle, VicDiagnosticsParameters const params, NvSciSyncObj const syncObj)
	Specifies the NvSciSyncObj to be used for EOF event. More...
NvMediaStatus	VicDiagnosticsInsertPreNvSciSyncFence (VicDiagnostics const *const handle, VicDiagnosticsParameters const params, NvSciSyncFence const *const syncFence)
	Insert an NvSciSyncFence as a pre-fence. More...
NvMediaStatus	VicDiagnosticsGetEOFNvSciSyncFence (VicDiagnostics const *const handle, VicDiagnosticsResult const *const result, NvSciSyncFence *const syncFence)
	Gets an EOF NvSciSyncFence for an VicDiagnosticsExecute() operation. More...

Function Documentation

VicDiagnosticsFillNvSciSyncAttrList()

NvMediaStatus VicDiagnosticsFillNvSciSyncAttrList	(	VicDiagnostics const *const	handle,
		NvSciSyncAttrList const	attrList,
		NvMediaNvSciSyncClientType const	clientType
	)

Fills the Vic Diagnostics specific NvSciSync attributes.

This function updates the input NvSciSyncAttrList with values equivalent to the following public attribute key-values:

NvSciSyncAttrKey_RequiredPerm set to

• NvSciSyncAccessPerm_WaitOnly for clientType NVMEDIA_WAITER
• NvSciSyncAccessPerm_SignalOnly for clientType NVMEDIA_SIGNALER
• NvSciSyncAccessPerm_WaitSignal for clientType NVMEDIA_SIGNALER_WAITER

NvSciSyncAttrKey_PrimitiveInfo set to

• NvSciSyncAttrValPrimitiveType_Syncpoint

The application must not set these attributes for the same NvSciSyncAttrList that is passed to this function.

When clientType is NVMEDIA_SIGNALER or NVMEDIA_SIGNALER_WAITER, some of the attribute values returned in attrList are tied to the specific VicDiagnostics context instance passed in handle. NvSciSyncObjs created using such attribute values must not be used after the VicDiagnostics context instance has been destroyed.

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[out]	attrList	Pointer to an NvSciSyncAttrList struct that will be populated with the NvSciSync attributes.
[in]	clientType	An NvMediaNvSciSyncClientType, to indicate whether the attributes filled should be for a waiter or a signaler. The value should be either: NVMEDIA_WAITER NVMEDIA_SIGNALER NVMEDIA_SIGNALER_WAITER.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Attributes filled successfully.
NVMEDIA_STATUS_BAD_PARAMETER	The attributes have already been filled, or one of the parameters has an invalid value. This could be: handle is NULL attrList is invalid clientType is invalid.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to populate the attribute list.

Precondition

• handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().
• attrList must be valid NvSciSyncAttrList handle.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different VicDiagnostics handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

VicDiagnosticsGetEOFNvSciSyncFence()

NvMediaStatus VicDiagnosticsGetEOFNvSciSyncFence	(	VicDiagnostics const *const	handle,
		VicDiagnosticsResult const *const	result,
		NvSciSyncFence *const	syncFence
	)

Gets an EOF NvSciSyncFence for an VicDiagnosticsExecute() operation.

The expiry of an EOF NvSciSyncFence associated with an VicDiagnosticsExecute() operation indicates that the corresponding VicDiagnosticsExecute() operation has finished.

To be able to get the EOF fence using this function, the NvSciSyncObj to be used for EOF event needs to have been set for the VicDiagnosticsParameters handle used with the VicDiagnosticsExecute() operation with VicDiagnosticsSetNvSciSyncObjforEOF().

For example, in this sequence of code:

VicDiagnosticsSetNvSciSyncObjforEOF(handle, params, eofSyncObj);
VicDiagnosticsExecute(handle, params, &result);
VicDiagnosticsGetEOFNvSciSyncFence(handle, &result, &syncFence);

expiry of syncFence indicates that the preceding VicDiagnosticsExecute() operation has finished.

For a given NvSciSyncObj used for the EOF event, the EOF fence for a VicDiagnosticsExecute() operation can be queried using this function only until the next operation using the same NvSciSyncObj for the EOF event is submitted. When more operations are submitted, the VicDiagnosticsResult structs for the previous operations are no longer considered valid by this function.

The fence returned in syncFence is tied to the specific VicDiagnostics context instance passed in handle and must not be used after the VicDiagnostics context instance has been destroyed.

This function will clear syncFence before updating and returning it's new value.

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[in]	result	Pointer to the VicDiagnosticsResult struct.
[out]	syncFence	Pointer to an NvSciSyncFence that will be populated with the EOF fence.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	EOF fence returned successfully.
NVMEDIA_STATUS_BAD_PARAMETER	No NvSciSyncObj was set for the operation EOF event, or one of the parameters has an invalid value. This could be: handle is NULL result is NULL or invalid syncFence is NULL.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to get the fence object.

Precondition

• handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().
• result must be valid VicDiagnosticsResult handle returned by VicDiagnosticsExecute().
• The operation that produced result must have had an EOF sync object configured with VicDiagnosticsSetNvSciSyncObjforEOF().

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different VicDiagnostics handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

See also

VicDiagnosticsRegisterNvSciSyncObj()

VicDiagnosticsSetNvSciSyncObjforEOF()

VicDiagnosticsInsertPreNvSciSyncFence()

NvMediaStatus VicDiagnosticsInsertPreNvSciSyncFence	(	VicDiagnostics const *const	handle,
		VicDiagnosticsParameters const	params,
		NvSciSyncFence const *const	syncFence
	)

Insert an NvSciSyncFence as a pre-fence.

This function inserts the specified NvSciSyncFence as a pre-fence to the diagnostic operation. The VicDiagnosticsExecute() operation is started only after the expiry of the syncFence.

For example, in this sequence of code:

VicDiagnosticsInsertPreNvSciSyncFence(handle, params, syncFence);
VicDiagnosticsExecute(handle, params, NULL);

the VicDiagnosticsExecute () operation is assured to start only after the expiry of syncFence.

You can set a maximum of 16 prefences by calling VicDiagnosticsInsertPreNvSciSyncFence().

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[in]	params	An VicDiagnosticsParameters handle.
[in]	syncFence	Pointer to an NvSciSyncFence.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Pre-fence inserted successfully.
NVMEDIA_STATUS_BAD_PARAMETER	The sync object or its duplicate is not registered as an PRESYNC type with Vic Diagnostics, or one of the parameters has an invalid value. This could be: handle is NULL params is invalid syncFence is NULL.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING	Maximum number of registered pre-fences has been reached.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to insert the pre-fence.

Precondition

• handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().
• params must be valid VicDiagnosticsParameters handle created with VicDiagnosticsGetParameters().
• syncFence must be a valid NvSciSyncFence handle.
• The sync object associated with syncFence must have been previously registered with VicDiagnosticsRegisterNvSciSyncObj() using a PRESYNC event type.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different VicDiagnostics handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

See also

VicDiagnosticsRegisterNvSciSyncObj()

VicDiagnosticsRegisterNvSciSyncObj()

NvMediaStatus VicDiagnosticsRegisterNvSciSyncObj	(	VicDiagnostics const *const	handle,
		NvMediaNvSciSyncObjType const	syncObjType,
		NvSciSyncObj const	syncObj
	)

Register an NvSciSyncObj with Vic Diagnostics.

Every NvSciSyncObj used by Vic Diagnostics must be registered by a call to this function before it is used. Also the NvSciSyncObjs associated with any NvSciSyncFences passed to VicDiagnosticsInsertPreNvSciSyncFence() must be registered.

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[in]	syncObjType	An NvMediaNvSciSyncClientType, to indicate what event the sync object will represent. Must be one of NVMEDIA_PRESYNCOBJ NVMEDIA_EOFSYNCOBJ NVMEDIA_EOF_PRESYNCOBJ
[in]	syncObj	The NvSciSyncObj to be registered.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Sync object registered successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL syncObjType is invalid syncObj is invalid, or the sync object or its duplicate has been already registered.
NVMEDIA_STATUS_INSUFFICIENT_BUFFERING	Maximum number of registered sync objects has been reached.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to register the sync object.

Precondition

• handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().
• syncObj must be valid NvSciSyncObj handle.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different VicDiagnostics handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

See also

VicDiagnosticsUnregisterNvSciSyncObj()

VicDiagnosticsAttributes.maxRegisteredSyncs

VicDiagnosticsSetNvSciSyncObjforEOF()

NvMediaStatus VicDiagnosticsSetNvSciSyncObjforEOF	(	VicDiagnostics const *const	handle,
		VicDiagnosticsParameters const	params,
		NvSciSyncObj const	syncObj
	)

Specifies the NvSciSyncObj to be used for EOF event.

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[in]	params	An VicDiagnosticsParameters handle.
[in]	syncObj	The NvSciSyncObj to be used for the EOF fence.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	EOF fence set successfully.
NVMEDIA_STATUS_BAD_PARAMETER	The sync object or its duplicate is not registered as an EOF event type with Vic Diagnostics, or one of the parameters has an invalid value. This could be: handle is NULL params is invalid syncObj is invalid.

Precondition

• handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().
• params must be valid VicDiagnosticsParameters handle created with VicDiagnosticsGetParameters().
• syncObj must be valid NvSciSyncObj handle.
• syncObj must have been previously registered with VicDiagnosticsRegisterNvSciSyncObj() using an EOF event type.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different VicDiagnostics handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

See also

VicDiagnosticsRegisterNvSciSyncObj()

VicDiagnosticsUnregisterNvSciSyncObj()

NvMediaStatus VicDiagnosticsUnregisterNvSciSyncObj	(	VicDiagnostics const *const	handle,
		NvSciSyncObj const	syncObj
	)

Unregisters an NvSciSyncObj with VicDiagnostics.

Every NvSciSyncObj registered with VicDiagnostics by VicDiagnosticsRegisterNvSciSyncObj() must be unregistered before you call VicDiagnosticsDestroy().

Before the application calls this function, it must ensure that any VicDiagnosticsExecute() operation that uses the NvSciSyncObj has completed. If this function is called while NvSciSyncObj is still in use by any VicDiagnosticsExecute() operation, an error will be returned.

Parameters

[in]	handle	Pointer to the VicDiagnostics context.
[in]	syncObj	The NvSciSyncObj to be unregistered.

Returns

An NvMediaStatus return code.

Return values

NVMEDIA_STATUS_OK	Sync object unregistered successfully.
NVMEDIA_STATUS_BAD_PARAMETER	One of the parameters has an invalid value. This could be: handle is NULL syncObj is invalid, or the sync object or its duplicate was not registered.
NVMEDIA_STATUS_INVALID_STATE	The function was called in incorrect system state.
NVMEDIA_STATUS_PENDING	The sync object is still being used by a pending operation.
NVMEDIA_STATUS_ERROR	An internal failure occurred when trying to unregister the sync object.

Precondition

• handle must be valid VicDiagnostics handle created with VicDiagnosticsCreate().
• syncObj must be valid NvSciSyncObj handle.
• syncObj must have been previously registered with VicDiagnosticsRegisterNvSciSyncObj().

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Each thread uses different VicDiagnostics handle
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: Yes

See also

VicDiagnosticsRegisterNvSciSyncObj()