NvSciBuf Object APIs

Detailed Description

List of APIs to create/operate on NvSciBufObj.

Functions
NvSciError	NvSciBufObjDup (NvSciBufObj bufObj, NvSciBufObj *dupObj)
	Creates a new NvSciBufObj holding reference to the same Memory object to which input NvSciBufObj holds the reference. More...
NvSciError	NvSciBufAttrListReconcileAndObjAlloc (const NvSciBufAttrList attrListArray[], size_t attrListCount, NvSciBufObj *bufObj, NvSciBufAttrList *newConflictList)
	Reconciles the input unreconciled NvSciBufAttrList(s) into a new reconciled NvSciBufAttrList and allocates NvSciBufObj that meets all the constraints in the reconciled NvSciBufAttrList. More...
void	NvSciBufObjFree (NvSciBufObj bufObj)
	Removes reference to the Memory object by destroying the NvSciBufObj. More...
NvSciError	NvSciBufObjGetAttrList (NvSciBufObj bufObj, NvSciBufAttrList *bufAttrList)
	Retrieves the reconciled NvSciBufAttrList whose attributes define the constraints of the allocated buffer from the NvSciBufObj. More...
NvSciError	NvSciBufObjGetCpuPtr (NvSciBufObj bufObj, void **ptr)
	Gets the CPU virtual address (VA) of the read/write buffer referenced by the NvSciBufObj. More...
NvSciError	NvSciBufObjGetConstCpuPtr (NvSciBufObj bufObj, const void **ptr)
	Gets the CPU virtual address (VA) of the read-only buffer referenced by the NvSciBufObj. More...
NvSciError	NvSciBufObjFlushCpuCacheRange (NvSciBufObj bufObj, uint64_t offset, uint64_t len)
	Flushes the given len bytes at starting offset in the buffer referenced by the NvSciBufObj. More...
NvSciError	NvSciBufObjAlloc (NvSciBufAttrList reconciledAttrList, NvSciBufObj *bufObj)
	Allocates a buffer that satisfies all the constraints defined by the attributes of the specified reconciled NvSciBufAttrList, and outputs a new NvSciBufObj referencing the Memory object containing the allocated buffer properties. More...
NvSciError	NvSciBufObjDupWithReducePerm (NvSciBufObj bufObj, NvSciBufAttrValAccessPerm reducedPerm, NvSciBufObj *newBufObj)
	Creates a new memory object containing a buffer handle representing new NvSciBufAttrValAccessPerm to the same buffer for which buffer handle is contained in the input memory object referenced by input NvSciBufObj and creates a new NvSciBufObj referencing it provided NvSciBufAttrValAccessPerm are less than permissions represented by buffer handle in the memory object referenced by input NvSciBufObj. More...

Function Documentation

NvSciBufAttrListReconcileAndObjAlloc()

NvSciError NvSciBufAttrListReconcileAndObjAlloc	(	const NvSciBufAttrList	attrListArray[],
		size_t	attrListCount,
		NvSciBufObj *	bufObj,
		NvSciBufAttrList *	newConflictList
	)

Reconciles the input unreconciled NvSciBufAttrList(s) into a new reconciled NvSciBufAttrList and allocates NvSciBufObj that meets all the constraints in the reconciled NvSciBufAttrList.

Note

This interface just combines NvSciBufAttrListReconciled() and NvSciBufObjAlloc() interfaces together.

Parameters

[in]	attrListArray	Array containing unreconciled NvSciBufAttrList(s) to reconcile. Valid value: Array of valid unreconciled NvSciBufAttrList(s) where array size is atleast 1.
[in]	attrListCount	The number of unreconciled NvSciBufAttrList(s) in attrListArray. Valid value: 1 to SIZE_MAX.
[out]	bufObj	The new NvSciBufObj.
[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 this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • attrListCount is 0
  • attrListArray is NULL
  • bufObj is NULL
  • any of the NvSciBufAttrList in attrListArray is reconciled.
  • not all the NvSciBufAttrLists in attrListArray are bound to the same NvSciBufModule.
• newConflictList is NULL
• NvSciError_InsufficientMemory if memory allocation failed.
• NvSciError_ReconciliationFailed if reconciliation failed.
• NvSciError_ResourceError if NVIDIA driver stack failed during buffer allocation.
• Panics if any of the unreconciled NvSciBufAttrLists is invalid.

NvSciBufObjAlloc()

NvSciError NvSciBufObjAlloc	(	NvSciBufAttrList	reconciledAttrList,
		NvSciBufObj *	bufObj
	)

Allocates a buffer that satisfies all the constraints defined by the attributes of the specified reconciled NvSciBufAttrList, and outputs a new NvSciBufObj referencing the Memory object containing the allocated buffer properties.

Parameters

[in]	reconciledAttrList	The reconciled NvSciBufAttrList.
[out]	bufObj	The new NvSciBufObj.

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • reconciledList is NULL
  • reconciledList is not a reconciled NvSciBufAttrList
  • bufObj is NULL
• NvSciError_InsufficientMemory if there is insufficient memory to complete the operation.
• NvSciError_ResourceError if NVIDIA driver stack failed during buffer allocation.
• Panics if reconciledAttrList is invalid.

NvSciBufObjDup()

NvSciError NvSciBufObjDup	(	NvSciBufObj	bufObj,
		NvSciBufObj *	dupObj
	)

Creates a new NvSciBufObj holding reference to the same Memory object to which input NvSciBufObj holds the reference.

Note

The new NvSciBufObj created with NvSciBufObjDup() has same NvSciBufAttrValAccessPerm as the input NvSciBufObj.

Parameters

[in]	bufObj	NvSciBufObj from which new NvSciBufObj needs to be created.
[out]	dupObj	The new NvSciBufObj.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if bufObj or dupObj is NULL.
• NvSciError_InsufficientMemory if memory allocation is failed.
• NvSciError_InvalidState if total number of references to the memory object are INT32_MAX and caller tries to take one more reference using this API.
• Panics if bufObj is invalid.

NvSciBufObjDupWithReducePerm()

NvSciError NvSciBufObjDupWithReducePerm	(	NvSciBufObj	bufObj,
		NvSciBufAttrValAccessPerm	reducedPerm,
		NvSciBufObj *	newBufObj
	)

Creates a new memory object containing a buffer handle representing new NvSciBufAttrValAccessPerm to the same buffer for which buffer handle is contained in the input memory object referenced by input NvSciBufObj and creates a new NvSciBufObj referencing it provided NvSciBufAttrValAccessPerm are less than permissions represented by buffer handle in the memory object referenced by input NvSciBufObj.

This interface has same effect as calling NvSciBufObjDup() if NvSciBufAttrValAccessPerm are same as permissions represented by buffer handle in the memory object referenced by input NvSciBufObj.

Parameters

[in]	bufObj	NvSciBufObj.
[in]	reducedPerm	Reduced access permissions that need to be imposed on the new NvSciBufObj (see NvSciBufAttrValAccessPerm). Valid value: NvSciBufAttrValAccessPerm enum value >= NvSciBufAccessPerm_Readonly and <= NvSciBufAttrValAccessPerm represented by NvSciBufGeneralAttrKey_ActualPerm key in reconciled NvSciBufAttrList associated with the input NvSciBufObj.
[out]	newBufObj	The new NvSciBufObj with new permissions.

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • bufObj is NULL
  • newBufObj is NULL
• NvSciError_InsufficientMemory if memory allocation failed.
• NvSciError_ResourceError if NVIDIA driver stack failed while assigning new permission to the buffer handle.
• Panics of bufObj is invalid.

NvSciBufObjFlushCpuCacheRange()

NvSciError NvSciBufObjFlushCpuCacheRange	(	NvSciBufObj	bufObj,
		uint64_t	offset,
		uint64_t	len
	)

Flushes the given len bytes at starting offset in the buffer referenced by the NvSciBufObj.

Flushing is done only when NvSciBufGeneralAttrKey_CpuNeedSwCacheCoherency key is set in reconciled NvSciBufAttrList to true.

Parameters

[in]	bufObj	The NvSciBufObj.
[in]	offset	The starting offset in memory of the NvSciBufObj. Valid value: 0 to buffer size - 1.
[in]	len	The length (in bytes) to flush. Valid value: 1 to buffer size - offset.

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if bufObj is NULL or len is zero or offset + len > buffer size.
• NvSciError_NotPermitted if buffer referenced by bufObj is not mapped to CPU.
• Panics if bufObj is invalid.
• NvSciError_ResourceError if NVIDIA driver stack could not flush the CPU cache range.

NvSciBufObjFree()

void NvSciBufObjFree

(

NvSciBufObj

bufObj

)

Removes reference to the Memory object by destroying the NvSciBufObj.

Note

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

Parameters

[in]

bufObj

The NvSciBufObj to deallocate.

Returns

void

• Panics if bufObj is invalid.

NvSciBufObjGetAttrList()

NvSciError NvSciBufObjGetAttrList	(	NvSciBufObj	bufObj,
		NvSciBufAttrList *	bufAttrList
	)

Retrieves the reconciled NvSciBufAttrList whose attributes define the constraints of the allocated buffer from the NvSciBufObj.

Note

The retrieved NvSciBufAttrList from an NvSciBufObj is read-only, and the attribute values in the list cannot be modified using set attribute APIs. In addition, the retrieved NvSciBufAttrList must not be freed with NvSciBufAttrListFree.

Parameters

[in]	bufObj	The NvSciBufObj to retrieve the NvSciBufAttrList from.
[out]	bufAttrList	The retrieved reconciled NvSciBufAttrList.

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • bufObj is NULL.
  • bufAttrList is NULL.
• Panics if bufObj is invalid.

NvSciBufObjGetConstCpuPtr()

NvSciError NvSciBufObjGetConstCpuPtr	(	NvSciBufObj	bufObj,
		const void **	ptr
	)

Gets the CPU virtual address (VA) of the read-only buffer referenced by the NvSciBufObj.

Note

This interface can be called successfully only if NvSciBufObj was obtained from successful call to NvSciBufObjAlloc() or NvSciBufObj was obtained from successful call to NvSciBufObjIpcImport()/ NvSciBufIpcImportAttrListAndObj() where atleast NvSciBufAccessPerm_Readonly permissions are granted to the imported NvSciBufObj (The permissions of the NvSciBufObj are indicated by NvSciBufGeneralAttrKey_ActualPerm key in the reconciled NvSciBufAttrList associated with it) and CPU access is requested by setting NvSciBufGeneralAttrKey_NeedCpuAccess to true.

Parameters

[in]	bufObj	The NvSciBufObj.
[out]	ptr	the CPU virtual address (VA).

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • bufObj is NULL.
  • ptr is NULL.
• NvSciError_BadParameter NvSciBufObj either did not request for CPU access by setting NvSciBufGeneralAttrKey_NeedCpuAccess to true OR does not have atleast NvSciBufAccessPerm_ReadOnly permissions to the buffer.
• Panics if bufObj is invalid.

NvSciBufObjGetCpuPtr()

NvSciError NvSciBufObjGetCpuPtr	(	NvSciBufObj	bufObj,
		void **	ptr
	)

Gets the CPU virtual address (VA) of the read/write buffer referenced by the NvSciBufObj.

Note

This interface can be called successfully only if NvSciBufObj was obtained from successful call to NvSciBufObjAlloc() or NvSciBufObj was obtained from successful call to NvSciBufObjIpcImport()/ NvSciBufIpcImportAttrListAndObj() where NvSciBufAccessPerm_ReadWrite permissions are granted to the imported NvSciBufObj (The permissions of the NvSciBufObj are indicated by NvSciBufGeneralAttrKey_ActualPerm key in the reconciled NvSciBufAttrList associated with it) and CPU access is requested by setting NvSciBufGeneralAttrKey_NeedCpuAccess to true.

Parameters

[in]	bufObj	The NvSciBufObj.
[out]	ptr	The CPU virtual address (VA).

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • bufObj is NULL.
  • ptr is NULL.
• NvSciError_BadParameter NvSciBufObj either did not request for CPU access by setting NvSciBufGeneralAttrKey_NeedCpuAccess to true OR does not have NvSciBufAccessPerm_ReadWrite to the buffer.
• Panics if bufObj is invalid.