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 the new NvSciBufAttrValAccessPerm to the same buffer for the buffer handle contained in the input memory object referenced by the 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...
NvSciError	NvSciBufObjGetPixels (NvSciBufObj bufObj, const NvSciBufRect *rect, void **dstPtrs, const uint32_t *dstPtrSizes, const uint32_t *dstPitches)
	Gets pixels from the buffer represented by memory object pointed to by bufObj provided NvSciBufGeneralAttrKey_Types is set to NvSciBufType_Image and CPU access to the buffer is requested via NvSciBufGeneralAttrKey_NeedCpuAccess in the unreconciled NvSciBufAttrList(s) used for bufObj allocation by the peer intending to call this API. More...
NvSciError	NvSciBufObjPutPixels (NvSciBufObj bufObj, const NvSciBufRect *rect, const void **srcPtrs, const uint32_t *srcPtrSizes, const uint32_t *srcPitches)
	Writes pixels to the buffer represented by memory object pointed to by bufObj provided NvSciBufGeneralAttrKey_Types is set to NvSciBufType_Image, NvSciBufAccessPerm_ReadWrite permissions are requested for the bufObj via NvSciBufGeneralAttrKey_RequiredPerm and CPU access to the buffer is requested via NvSciBufGeneralAttrKey_NeedCpuAccess in the unreconciled NvSciBufAttrList(s) used for bufObj allocation by the peer intending to call this API. 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 NvSciBufAttrListReconcile() 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 at least 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_InvalidState If the Init Mode API is called in Runtime Mode.
• 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.
  • an NvSciBufAttrList appears multiple times in attrListArray
  • an attribute key necessary for reconciling against the given data type(s) of the NvSciBufAttrList(s) involved in reconciliation is unset
  • an attribute key is set to an unsupported value considering the data type(s) of the NvSciBufAttrList(s) involved in reconciliation
• newConflictList is NULL
• NvSciError_InsufficientMemory if memory allocation failed.
• NvSciError_InvalidState if a new NvSciBufAttrList cannot be associated with the NvSciBufModule associated with the NvSciBufAttrList(s) in the given attrListArray to create the new NvSciBufAttrList.
• NvSciError_NotSupported if an attribute key is set specifying a combination of constraints that are not supported
• NvSciError_Overflow if internal integer overflow is detected.
• NvSciError_ReconciliationFailed if reconciliation failed.
• NvSciError_ResourceError if any of the following occurs:
  • NVIDIA driver stack failed during buffer allocation
  • system lacks resource other than memory
• Panics if any of the unreconciled NvSciBufAttrLists is invalid.

Precondition

• Valid unreconciled NvSciBufAttrList(s) are obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

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.

Note

It is not guaranteed that the input reconciled NvSciBufAttrList in this API is the same NvSciBufAttrList that is ultimately associated with the allocated NvSciBufObj. If the user needs to query attributes from an NvSciBufAttrList associated with an NvSciBufObj after allocation, they must first obtain the reconciled NvSciBufAttrList from the NvSciBufObj using NvSciBufObjGetAttrList().

Parameters

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

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_InvalidState if the Init Mode API is called in Runtime Mode.
• NvSciError_BadParameter if any of the following occurs:
  • reconciledAttrList is NULL
  • reconciledAttrList is not a reconciled NvSciBufAttrList
  • bufObj is NULL
• NvSciError_InsufficientMemory if there is insufficient memory to complete the operation.
• NvSciError_InvalidState if a new NvSciBufObj cannot be associated with the NvSciBufModule with which reconciledAttrList is associated to create the new NvSciBufObj.
• NvSciError_ResourceError if any of the following occurs:
  • NVIDIA driver stack failed during buffer allocation
  • system lacks resource other than memory
• Panics if reconciledAttrList is invalid.

Precondition

• Valid reconciled NvSciBufAttrList is obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

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_InvalidState if the Init Mode API is called in Runtime Mode.
• NvSciError_BadParameter if any of the following occurs:
  • bufObj is NULL
  • dupObj is NULL
• NvSciError_InsufficientMemory if memory allocation is failed.
• NvSciError_InvalidState if the total number of NvSciBufObjs referencing the memory object is INT32_MAX and the caller tries to take one more reference using this API.
• NvSciError_ResourceError if system lacks resource other than memory
• Panics if bufObj is invalid.

Precondition

• Valid NvSciBufObj is obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

NvSciBufObjDupWithReducePerm()

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

Creates a new memory object containing a buffer handle representing the new NvSciBufAttrValAccessPerm to the same buffer for the buffer handle contained in the input memory object referenced by the 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.

When this is the case, the new memory object will contains a new NvSciBufAttrList which is cloned from the original NvSciBufAttrList associated with the input NvSciBufObj, but with the requested NvSciBufAttrValAccessPerm.

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

Parameters

[in]	bufObj	NvSciBufObj.
[in]	reducedPerm	Reduced access permissions that need to be imposed on the new NvSciBufObj (see NvSciBufAttrValAccessPerm). Valid value: NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite, which is <= NvSciBufAttrValAccessPerm represented by the value of the NvSciBufGeneralAttrKey_ActualPerm key in the 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_InvalidState if the Init Mode API is called in Runtime Mode.
• NvSciError_BadParameter if any of the following occurs:
  • bufObj is NULL
  • newBufObj is NULL
  • reducedPerm is not NvSciBufAccessPerm_Readonly or NvSciBufAccessPerm_ReadWrite
  • reducedPerm is greater than the permissions specified in the value of the NvSciBufGeneralAttrKey_ActualPerm key
• NvSciError_InsufficientMemory if memory allocation failed.
• NvSciError_InvalidState if any of the following occurs:
  • the total number of NvSciBufObj(s) referencing the memory object is INT32_MAX and the caller tries to take one more reference using this API.
  • a new NvSciBufObj cannot be associated with the NvSciBufModule with which bufObj is associated to create the new NvSciBufAttrList when the requested access permissions are less than the permissions represented by the input NvSciBufObj
• NvSciError_ResourceError if any of the following occurs:
  • NVIDIA driver stack failed while assigning new permission to the buffer handle
  • system lacks resource other than memory
• NvSciError_NotSupported if this API is called for NvSciBufObj imported from the remote Soc.
• Panics of bufObj is invalid.

Precondition

• Valid NvSciBufObj is obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

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 any of the following occurs:
  • bufObj is NULL
  • len is zero
  • offset + len > buffer size.
• NvSciError_NotPermitted if buffer referenced by bufObj is not mapped to CPU.
• NvSciError_NotSupported if NvSciBufAllocIfaceType associated with the NvSciBufObj is not supported.
• NvSciError_Overflow if offset + len exceeds UINT64_MAX
• NvSciError_ResourceError if NVIDIA driver stack could not flush the CPU cache range.
• Panics if bufObj is invalid.

Precondition

• Valid NvSciBufObj is obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

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:
  • if Init Mode API is called in Runtime Mode.
  • bufObj is invalid.

Precondition

• Valid NvSciBufObj is obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes, with the following conditions:
    • Provided there is no active operation involving the NvSciBufAttrList obtained from NvSciBufObjGetAttrList() to be freed, since the lifetime of that reconciled NvSciBufAttrList is tied to the associated NvSciBufObj
    • Provided there is no active operation involving the NvSciBufObj to be freed
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

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.

Precondition

• Valid NvSciBufObj is obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

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 at least 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 at least NvSciBufAccessPerm_ReadOnly permissions to the buffer.
• Panics if bufObj is invalid.

Precondition

• Valid NvSciBufObj is obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

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.

Precondition

• Valid NvSciBufObj is obtained.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

NvSciBufObjGetPixels()

NvSciError NvSciBufObjGetPixels	(	NvSciBufObj	bufObj,
		const NvSciBufRect *	rect,
		void **	dstPtrs,
		const uint32_t *	dstPtrSizes,
		const uint32_t *	dstPitches
	)

Gets pixels from the buffer represented by memory object pointed to by bufObj provided NvSciBufGeneralAttrKey_Types is set to NvSciBufType_Image and CPU access to the buffer is requested via NvSciBufGeneralAttrKey_NeedCpuAccess in the unreconciled NvSciBufAttrList(s) used for bufObj allocation by the peer intending to call this API.

Note

User must ensure to read the NvSciBufGeneralAttrKey_CpuNeedSwCacheCoherency attribute from the NvSciBufAttrList associated with the bufObj and perform CPU cache flush operation before calling NvSciBufObjGetPixels() if the attribute is set to TRUE.

Parameters

[in]	bufObj	NvSciBufObj.
[in]	rect	NvSciBufRect defining the subset of the surface to be copied to user provided surface. Valid value: rect can be NULL. If rect is NULL, then entire surface represented by NvSciBufObj is copied to user surface. rect can only be non-NULL for NvSciSurfType_RGBA or NvSciSurfType_RAW, it must be NULL for NvSciSurfType_YUV. If rect is non-NULL then x0 or x1 co-ordinate shall not exceed the plane width represented by NvSciBufImageAttrKey_PlaneWidth. Similarly, y0 or y1 co-ordinate shall not exceed the plane height represented by NvSciBufImageAttrKey_PlaneHeight. x0 co-ordinate cannot be greater than x1 co-ordinate. Similarly, y0 co-ordinate cannot be greater than y1 co-ordinate. Width represented by rect (x1 - x0) in bytes shall not exceed the dstPitches supplied by user.
[out]	dstPtrs	an array of pointers to user's planes. For RGBA, RAW and single plane YUV images, it is assumed that the array will have single member representing single user plane. For YUV surfaces with more than one plane, it is assumed that user provides separate plane pointers for Y, U and V planes (where Y is the first plane, U is the second plane, and V is the third plane). For RGB surfaces with three planes, it is assumed that user provides separate plane pointers for R, G and B planes (where R is the first plane, G is the second plane, and B is the third plane) Valid value: dstPtrs must be non-NULL. Every array member of dstPtrs must be non-NULL. param[in] dstPtrSizes an array of plane's sizes. Each size in the dstPtrSizes array shall correspond to the plane at the same index in dstPtrs. Valid value: dstPtrSizes must be non-NULL. Each array member of the dstPtrSizes must be non-zero.
[in]	dstPitches	an array of pitches. Each member in array shall correspond to the pitch of plane at the same index in dstPtrs. Valid value: dstPitches must be non-NULL.

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • bufObj is NULL.
  • NvSciBufAttrList associated with bufObj is NULL.
  • rect is non-NULL and NvSciBufSurfType is NvSciSurfType_YUV .
  • rect is non-NULL and x0 or x1 is greater than plane width represented by NvSciBufImageAttrKey_PlaneWidth.
  • rect is non-NULL and y0 or y1 is greater than plane height represented by NvSciBufImageAttrKey_PlaneHeight.
  • rect is non-NULL and x0 > x1.
  • rect is non-NULL and y0 > y1.
  • rect is non-NULL and width in bytes represented by (x1 - x0) is is greater than that specified in dstPitches for uses planes.
  • dstPtrs is NULL.
  • An array member of dstPtrs is NULL.
  • dstPtrSizes is NULL.
  • An array member of dstPtrSizes is zero.
  • dstPtrs for any of the planes overlap.
  • dstPtrs overlap with the memory represented by bufObj.
  • The size of the plane as specified in dstPtrSizes is smaller than the destination surface to be copied.
  • dstPitches is NULL.
  • An array member of dstPitches is zero.
  • NvSciBufType is not NvSciBufType_Image in the NvSciBufAttrList associated with the bufObj.
  • CPU access is not requested in unreconciled NvSciBufAttrList of the peer calling this API via NvSciBufGeneralAttrKey_NeedCpuAccess.
• NvSciError_NotSupported if any of the following occurs:
  • bufObj represents an image that this API does not understand
• Panics if any of the following occurs:
  • bufObj is invalid.
  • NvSciBufAttrList associated with the bufObj is invalid.

Precondition

• NvSciBufType requested via NvSciBufGeneralAttrKey_Types by the unreconciled NvSciBufAttrList(s) is NvSciBufType_Image.
• CPU access is requested via NvSciBufGeneralAttrKey_NeedCpuAccess by at least one unreconciled NvSciBufAttrList belonging to the SoC on which below API will be called.
• Valid NvSciBufObj is obtained such that the reconciled NvSciBufAttrList associated with the NvSciBufObj is reconciled from the unreconciled NvSciBufAttrList(s) satisfying the conditions stated above.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No

NvSciBufObjPutPixels()

NvSciError NvSciBufObjPutPixels	(	NvSciBufObj	bufObj,
		const NvSciBufRect *	rect,
		const void **	srcPtrs,
		const uint32_t *	srcPtrSizes,
		const uint32_t *	srcPitches
	)

Writes pixels to the buffer represented by memory object pointed to by bufObj provided NvSciBufGeneralAttrKey_Types is set to NvSciBufType_Image, NvSciBufAccessPerm_ReadWrite permissions are requested for the bufObj via NvSciBufGeneralAttrKey_RequiredPerm and CPU access to the buffer is requested via NvSciBufGeneralAttrKey_NeedCpuAccess in the unreconciled NvSciBufAttrList(s) used for bufObj allocation by the peer intending to call this API.

Note

User must ensure to read the NvSciBufGeneralAttrKey_CpuNeedSwCacheCoherency attribute from the NvSciBufAttrList associated with the bufObj and perform CPU cache flush operation after calling NvSciBufObjPutPixels() if the attribute is set to TRUE.

Parameters

[in]	bufObj	NvSciBufObj.
[in]	rect	NvSciBufRect defining the subset of the surface to be copied from user provided surface. Valid value: rect can be NULL. If rect is NULL, then entire user surface is copied to bufObj. rect can only be non-NULL for NvSciSurfType_RGBA or NvSciSurfType_RAW, it must be NULL for NvSciSurfType_YUV. If rect is non-NULL then x0 or x1 co-ordinate shall not exceed the plane width represented by NvSciBufImageAttrKey_PlaneWidth. Similarly, y0 or y1 co-ordinate shall not exceed the plane height represented by NvSciBufImageAttrKey_PlaneHeight. x0 co-ordinate cannot be greater than x1 co-ordinate. Similarly, y0 co-ordinate cannot be greater than y1 co-ordinate. Width represented by rect (x1 - x0) in bytes shall not exceed the srcPitches supplied by user.
[in]	srcPtrs	an array of pointers to user's planes. For RGBA, RAW and single plane YUV images, it is assumed that the array will have single member representing single user plane. For YUV surfaces with more than one plane, it is assumed that user provides separate plane pointers for Y, U and V planes (where Y is the first plane, U is the second plane, and V is the third plane). For RGB surfaces with three planes, it is assumed that user provides separate plane pointers for R, G and B planes (where R is the first plane, G is the second plane, and B is the third plane) Valid value: srcPtrs must be non-NULL. Every array member of srcPtrs must be non-NULL. param[in] srcPtrSizes an array of plane's sizes. Each size in the srcPtrSizes array shall correspond to the plane at the same index in srcPtrs. Valid value: srcPtrSizes must be non-NULL. Each array member of the srcPtrSizes must be non-zero.
[in]	srcPitches	an array of pitches. Each member in array shall correspond to the pitch of plane at the same index in srcPtrs. Valid value: srcPitches must be non-NULL.

Returns

NvSciError, the completion code of this operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • bufObj is NULL.
  • NvSciBufAttrList associated with bufObj is NULL.
  • rect is non-NULL and NvSciBufSurfType is NvSciSurfType_YUV .
  • rect is non-NULL and x0 or x1 is greater than plane width represented by NvSciBufImageAttrKey_PlaneWidth.
  • rect is non-NULL and y0 or y1 is greater than plane height represented by NvSciBufImageAttrKey_PlaneHeight.
  • rect is non-NULL and x0 > x1.
  • rect is non-NULL and y0 > y1.
  • rect is non-NULL and width in bytes represented by (x1 - x0) is is greater than that specified in srcPitches for uses planes.
  • srcPtrs is NULL.
  • An array member of srcPtrs is NULL.
  • srcPtrSizes is NULL.
  • An array member of srcPtrSizes is zero.
  • srcPtrs for any of the planes overlap.
  • srcPtrs overlap with the memory represented by bufObj.
  • The size of the plane as specified in srcPtrSizes is smaller than the source surface to be copied.
  • srcPitches is NULL.
  • An array member of srcPitches is zero.
  • NvSciBufType is not NvSciBufType_Image in the NvSciBufAttrList associated with the bufObj.
  • NvSciBufAccessPerm_ReadWrite is not requested in unreconciled NvSciBufAttrList of the peer calling this API via NvSciBufGeneralAttrKey_RequiredPerm.
  • CPU access is not requested in unreconciled NvSciBufAttrList of the peer calling this API via NvSciBufGeneralAttrKey_NeedCpuAccess.
• NvSciError_NotSupported if any of the following occurs:
  • bufObj represents an image that this API does not understand
• Panics if any of the following occurs:
  • bufObj is invalid.
  • NvSciBufAttrList associated with the bufObj is invalid.

Precondition

• NvSciBufType requested via NvSciBufGeneralAttrKey_Types by the unreconciled NvSciBufAttrList(s) is NvSciBufType_Image.
• CPU access is requested via NvSciBufGeneralAttrKey_NeedCpuAccess by at least one unreconciled NvSciBufAttrList belonging to the SoC on which below API will be called.
• Valid NvSciBufObj is obtained such that the reconciled NvSciBufAttrList associated with the NvSciBufObj is reconciled from the unreconciled NvSciBufAttrList(s) satisfying the conditions stated above.

Usage considerations

• Allowed context for the API call
  • Interrupt handler: No
  • Signal handler: No
  • Thread-safe: Yes
  • Re-entrant: No
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: No
  • Runtime: Yes
  • De-Init: No