NvSciBuf Attribute List APIs

Detailed Description

Methods to perform operations on NvSciBuf attribute lists.

Functions
NvSciError	NvSciBufAttrListCreate (NvSciBufModule module, NvSciBufAttrList *newAttrList)
	Creates a new, single slot, unreconciled NvSciBufAttrList associated with the input NvSciBufModule with empty NvSciBufAttrKeys. More...
void	NvSciBufAttrListFree (NvSciBufAttrList attrList)
	Frees the NvSciBufAttrList and removes its association with the NvSciBufModule with which it was created. More...
NvSciError	NvSciBufAttrListSetAttrs (NvSciBufAttrList attrList, NvSciBufAttrKeyValuePair *pairArray, size_t pairCount)
	Sets the values for NvSciBufAttrKey(s) in the NvSciBufAttrList. More...
size_t	NvSciBufAttrListGetSlotCount (NvSciBufAttrList attrList)
	Returns the slot count per NvSciBufAttrKey in a NvSciBufAttrList. More...
NvSciError	NvSciBufAttrListGetAttrs (NvSciBufAttrList attrList, NvSciBufAttrKeyValuePair *pairArray, size_t pairCount)
	Returns an array of NvSciBufAttrKeyValuePair for a given set of NvSciBufAttrKey(s). More...
NvSciError	NvSciBufAttrListSlotGetAttrs (NvSciBufAttrList attrList, size_t slotIndex, NvSciBufAttrKeyValuePair *pairArray, size_t pairCount)
	Returns an array of NvSciBufAttrKeyValuePair(s) from a multi-slot unreconciled NvSciBufAttrList at the given slot index. More...
NvSciError	NvSciBufAttrListDebugDump (NvSciBufAttrList attrList, void **buf, size_t *len)
	Allocates a buffer and then dumps the contents of the specified attribute list into the buffer. More...
NvSciError	NvSciBufAttrListReconcile (const NvSciBufAttrList inputArray[], size_t inputCount, NvSciBufAttrList *newReconciledAttrList, NvSciBufAttrList *newConflictList)
	Reconciles the given unreconciled NvSciBufAttrList(s) into a new reconciled NvSciBufAttrList. More...
NvSciError	NvSciBufAttrListClone (NvSciBufAttrList origAttrList, NvSciBufAttrList *newAttrList)
	Clones an unreconciled/reconciled NvSciBufAttrList. More...
NvSciError	NvSciBufAttrListAppendUnreconciled (const NvSciBufAttrList inputUnreconciledAttrListArray[], size_t inputUnreconciledAttrListCount, NvSciBufAttrList *newUnreconciledAttrList)
	Appends multiple unreconciled NvSciBufAttrList(s) together, forming a single new unreconciled NvSciBufAttrList with a slot count equal to the sum of all the slot counts of NvSciBufAttrList(s) in the input array. More...
NvSciError	NvSciBufAttrListIsReconciled (NvSciBufAttrList attrList, bool *isReconciled)
	Checks if the NvSciBufAttrList is reconciled. More...
NvSciError	NvSciBufAttrListValidateReconciled (NvSciBufAttrList reconciledAttrList, const NvSciBufAttrList unreconciledAttrListArray[], size_t unreconciledAttrListCount, bool *isReconcileListValid)
	Validates a reconciled NvSciBufAttrList against a set of unreconciled NvSciBufAttrList(s). More...

Function Documentation

NvSciBufAttrListAppendUnreconciled()

NvSciError NvSciBufAttrListAppendUnreconciled	(	const NvSciBufAttrList	inputUnreconciledAttrListArray[],
		size_t	inputUnreconciledAttrListCount,
		NvSciBufAttrList *	newUnreconciledAttrList
	)

Appends multiple unreconciled NvSciBufAttrList(s) together, forming a single new unreconciled NvSciBufAttrList with a slot count equal to the sum of all the slot counts of NvSciBufAttrList(s) in the input array.

Parameters

[in]	inputUnreconciledAttrListArray[]	Array containing the unreconciled NvSciBufAttrList(s) to be appended together. Valid value: Array of valid NvSciBufAttrList(s) where the array size is atleast 1.
[in]	inputUnreconciledAttrListCount	Number of unreconciled NvSciBufAttrList(s) in inputUnreconciledAttrListArray. Valid value: inputUnreconciledAttrListCount is valid input if it is non-zero.
[out]	newUnreconciledAttrList	Appended NvSciBufAttrList.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • inputUnreconciledAttrListArray is NULL
  • inputUnreconciledAttrListCount is 0
  • newUnreconciledAttrList is NULL
  • any of the NvSciBufAttrList(s) in @inputUnreconciledAttrListArray is reconciled
• NvSciError_InsufficientMemory if memory allocation failed.
• panics if any NvSciBufAttrList in the inputUnreconciledAttrListArray is invalid

NvSciBufAttrListClone()

NvSciError NvSciBufAttrListClone	(	NvSciBufAttrList	origAttrList,
		NvSciBufAttrList *	newAttrList
	)

Clones an unreconciled/reconciled NvSciBufAttrList.

The resulting NvSciBufAttrList contains all the values of the input NvSciBufAttrList. If the input NvSciBufAttrList is an unreconciled NvSciBufAttrList, then modification to the output NvSciBufAttrList will be allowed using NvSciBufAttrListSetAttrs().

Parameters

[in]	origAttrList	NvSciBufAttrList to be cloned.
[out]	newAttrList	The new NvSciBufAttrList.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • origAttrList is NULL
  • newAttrList is NULL
• NvSciError_InsufficientMemory if there is insufficient system memory to create a new NvSciBufAttrList.
• panics if origAttrList is invalid

NvSciBufAttrListCreate()

NvSciError NvSciBufAttrListCreate	(	NvSciBufModule	module,
		NvSciBufAttrList *	newAttrList
	)

Creates a new, single slot, unreconciled NvSciBufAttrList associated with the input NvSciBufModule with empty NvSciBufAttrKeys.

Parameters

[in]	module	NvSciBufModule to associate with the newly created NvSciBufAttrList.
[out]	newAttrList	The new NvSciBufAttrList.

Returns

NvSciError, the completion status of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • module is NULL
  • newAttrList is NULL
• NvSciError_InsufficientMemory if insufficient system memory to create a NvSciBufAttrList.
• panics if module is invalid.

NvSciBufAttrListDebugDump()

NvSciError NvSciBufAttrListDebugDump	(	NvSciBufAttrList	attrList,
		void **	buf,
		size_t *	len
	)

Allocates a buffer and then dumps the contents of the specified attribute list into the buffer.

Parameters

[in]	attrList	Attribute list to fetch contents from.
[out]	buf	A pointer to the buffer allocated for the debug dump.
[out]	len	The length of the buffer allocated for the debug dump.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if attrList is invalid.

NvSciBufAttrListFree()

void NvSciBufAttrListFree

(

NvSciBufAttrList

attrList

)

Frees the NvSciBufAttrList and removes its association with the NvSciBufModule with which it was created.

Note

Every owner of the NvSciBufAttrList shall call NvSciBufAttrListFree() only after all the functions invoked by the owner with NvSciBufAttrList as an input are completed.

Parameters

[in]

attrList

The NvSciBufAttrList to be freed.

Returns

void

• panics if NvSciBufAttrList is invalid.

NvSciBufAttrListGetAttrs()

NvSciError NvSciBufAttrListGetAttrs	(	NvSciBufAttrList	attrList,
		NvSciBufAttrKeyValuePair *	pairArray,
		size_t	pairCount
	)

Returns an array of NvSciBufAttrKeyValuePair for a given set of NvSciBufAttrKey(s).

This function accepts a set of NvSciBufAttrKey(s) passed in the NvSciBufAttrKeyValuePair structure. The return values, stored back into NvSciBufAttrKeyValuePair, consist of const void* pointers to the attribute values from the NvSciBufAttrList. The application must not write to this data.

Parameters

[in]	attrList	NvSciBufAttrList to fetch the NvSciBufAttrKeyValuePair(s) from.
[in,out]	pairArray	Array of NvSciBufAttrKeyValuePair. Valid value: pairArray is valid input if it is not NULL and key member of every NvSciBufAttrKeyValuePair in the array > NvSciBufAttrKey_LowerBound and < NvSciBufAttrKey_UpperBound.
[in]	pairCount	Number of elements/entries in pairArray. Valid value: pairCount is valid input if it is non-zero.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • attrList is NULL
  • pairArray is NULL
  • pairCount is 0
  • attrList is reconciled and any of the NvSciBufAttrKey(s) specified in NvSciBufAttrKeyValuePair is input only
  • attrList is unreconciled and any of the NvSciBufAttrKey(s) specified in NvSciBufAttrKeyValuePair is output only
• NvSciError_BadParameter if NvSciBufAttrKey specified in @ pairArray is < NvSciBufAttrKey_LowerBound OR > NvSciBufAttrKey_UpperBound
• panics if attrList is invalid

NvSciBufAttrListGetSlotCount()

size_t NvSciBufAttrListGetSlotCount

(

NvSciBufAttrList

attrList

)

Returns the slot count per NvSciBufAttrKey in a NvSciBufAttrList.

Parameters

[in]

attrList

The NvSciBufAttrList to retrieve the slot count from.

Returns

size_t

• Number of slots in the NvSciBufAttrList
• panics if attrList is invalid

NvSciBufAttrListIsReconciled()

NvSciError NvSciBufAttrListIsReconciled	(	NvSciBufAttrList	attrList,
		bool *	isReconciled
	)

Checks if the NvSciBufAttrList is reconciled.

Parameters

[in]	attrList	NvSciBufAttrList to check.
[out]	isReconciled	boolean value indicating whether the attrList is reconciled or not.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • attrList is NULL
  • isReconciled is NULL
• panics if attrList is invalid

NvSciBufAttrListReconcile()

NvSciError NvSciBufAttrListReconcile	(	const NvSciBufAttrList	inputArray[],
		size_t	inputCount,
		NvSciBufAttrList *	newReconciledAttrList,
		NvSciBufAttrList *	newConflictList
	)

Reconciles the given unreconciled NvSciBufAttrList(s) into a new reconciled NvSciBufAttrList.

On success, this API call returns reconciled NvSciBufAttrList, which has to be freed by the caller using NvSciBufAttrListFree().

Parameters

[in]	inputArray	Array containing unreconciled NvSciBufAttrList(s) to be reconciled. inputArray is valid if it is non-NULL.
[in]	inputCount	The number of unreconciled NvSciBufAttrList(s) in inputArray. This value must be non-zero. For a single NvSciBufAttrList, the count must be set 1.
[out]	newReconciledAttrList	Reconciled NvSciBufAttrList. This field is populated only if the reconciliation succeeded.
[out]	newConflictList	Unreconciled NvSciBufAttrList 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_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • inputArray[] is NULL
  • inputCount is 0
  • newReconciledAttrList is NULL
  • any of the NvSciBufAttrList in inputArray is reconciled.
  • not all the NvSciBufAttrLists in inputArray are bound to the same NvSciBufModule.
• newConflictList is NULL
• NvSciError_InsufficientMemory if not enough system memory.
• NvSciError_ReconciliationFailed if reconciliation failed.
• NvSciError_Overflow if internal integer overflow is detected.
• NvSciError_ResourceError if system lacks resource other than memory.
• NvSciError_InvalidState if NvSciBufType of NvSciBufAttrList is invalid.
• Panic if:
  • unreconciled NvSciBufAttrList(s) in inputArray is not valid.

NvSciBufAttrListSetAttrs()

NvSciError NvSciBufAttrListSetAttrs	(	NvSciBufAttrList	attrList,
		NvSciBufAttrKeyValuePair *	pairArray,
		size_t	pairCount
	)

Sets the values for NvSciBufAttrKey(s) in the NvSciBufAttrList.

It only reads values from NvSciBufAttrKeyValuePair array and saves copies during this call.

Note

All combinations of NvSciBufAttrListSetAttrs(), NvSciBufAttrListGetAttrs(), NvSciBufAttrListAppendUnreconciled() and NvSciBufAttrListReconcile() can be called concurrently, however, function completion order is not guaranteed by NvSciBuf and thus outcome of calling these functions concurrently is undefined.

Parameters

[in]	attrList	Unreconciled NvSciBufAttrList.
[in]	pairArray	Array of NvSciBufAttrKeyValuePair structures. Valid value: pairArray is valid input if it is not NULL and key member of every NvSciBufAttrKeyValuePair in the array is an input or input/output attribute and it is > NvSciBufAttrKey_LowerBound and < NvSciBufAttrKey_UpperBound and value member of every NvSciBufAttrKeyValuePair in the array is not NULL.
[in]	pairCount	Number of elements/entries in pairArray. Valid value: pairCount is valid input if it is non-zero.

Returns

NvSciError, the completion status of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • attrList is NULL
  • attrList is reconciled or if any of the NvSciBufAttrKey(s) specified in NvSciBufAttrKeyValuePair array is output only
  • pairArray is NULL
  • pairCount is 0
• NvSciError_BadParameter if NvSciBufAttrKey specified in @ pairArray is < NvSciBufAttrKey_LowerBound OR > NvSciBufAttrKey_UpperBound
• panics if attrList is not valid

NvSciBufAttrListSlotGetAttrs()

NvSciError NvSciBufAttrListSlotGetAttrs	(	NvSciBufAttrList	attrList,
		size_t	slotIndex,
		NvSciBufAttrKeyValuePair *	pairArray,
		size_t	pairCount
	)

Returns an array of NvSciBufAttrKeyValuePair(s) from a multi-slot unreconciled NvSciBufAttrList at the given slot index.

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

Note

When exporting an array containing multiple unreconciled NvSciBufAttrList(s), the importing endpoint still imports just one unreconciled NvSciBufAttrList. This unreconciled NvSciBufAttrList is referred to as a multi-slot NvSciBufAttrList. It logically represents an array of NvSciBufAttrList(s), where each key has an array of values, one per slot.

Parameters

[in]	attrList	NvSciBufAttrList to fetch the NvSciBufAttrKeyValuePair(s) from.
[in]	slotIndex	Index in the NvSciBufAttrList. Valid value: 0 to slot count of NvSciBufAttrList - 1.
[in,out]	pairArray	Array of NvSciBufAttrKeyValuePair. Holds the NvSciBufAttrKey(s) passed into the function and returns an array of NvSciBufAttrKeyValuePair structures. Valid value: pairArray is valid input if it is not NULL and key member of every NvSciBufAttrKeyValuePair in the array > NvSciBufAttrKey_LowerBound and < NvSciBufAttrKey_UpperBound.
[in]	pairCount	Number of elements/entries in pairArray. Valid value: pairCount is valid input if it is non-zero.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • attrList is NULL
  • pairArray is NULL
  • pairCount is 0
  • slotIndex >= slot count of NvSciBufAttrList
• NvSciError_BadParameter if NvSciBufAttrKey specified in @ pairArray is < NvSciBufAttrKey_LowerBound OR > NvSciBufAttrKey_UpperBound.
• panics if attrList is valid

NvSciBufAttrListValidateReconciled()

NvSciError NvSciBufAttrListValidateReconciled	(	NvSciBufAttrList	reconciledAttrList,
		const NvSciBufAttrList	unreconciledAttrListArray[],
		size_t	unreconciledAttrListCount,
		bool *	isReconcileListValid
	)

Validates a reconciled NvSciBufAttrList against a set of unreconciled NvSciBufAttrList(s).

Parameters

[in]	reconciledAttrList	Reconciled NvSciBufAttrList list to be validated. unreconciledAttrListArray is valid if it is non-NULL.
[in]	unreconciledAttrListArray	Set of unreconciled NvSciBufAttrList(s) that need to be used for validation.
[in]	unreconciledAttrListCount	Number of unreconciled NvSciBufAttrList(s). This value must be non-zero. For a single NvSciBufAttrList, the count must be set to 1.
[out]	isReconcileListValid	Flag indicating if the reconciled NvSciBufAttrList satisfies the constraints of set of unreconciled NvSciBufAttrList(s).

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • reconciledAttrList is NULL or
  • unreconciledAttrListArray[] is NULL or
  • unreconciledAttrListCount is zero or
  • isReconcileListValid is NULL
  • any of the NvSciBufAttrList in unreconciledAttrListArray is reconciled.
  • not all the NvSciBufAttrLists in unreconciledAttrListArray are bound to the same NvSciBufModule.
• NvSciError_ReconciliationFailed if validation of reconciled NvSciBufAttrList failed against input unreconciled NvSciBufAttrList(s).
• NvSciError_InsufficientMemory if internal memory allocation failed.
• NvSciError_Overflow if internal integer overflow occurs.
• Panics if:
  • unreconciled NvSciBufAttrList(s) in unreconciledAttrListArray is invalid.
  • reconciledAttrList is not valid.