NvSciStream APIs

Detailed Description

Methods to setup and stream sequences of data packets.

Functions
NvSciError	NvSciStreamBlockConnect (NvSciStreamBlock const upstream, NvSciStreamBlock const downstream)
	Establishes connection between two blocks referenced by the given NvSciStreamBlock(s). More...
NvSciError	NvSciStreamProducerCreate (NvSciStreamBlock const pool, NvSciStreamBlock *const producer)
	Creates an instance of producer block, associates the given pool referenced by the given NvSciStreamBlock with it and returns a NvSciStreamBlock referencing the created producer block. More...
NvSciError	NvSciStreamConsumerCreate (NvSciStreamBlock const queue, NvSciStreamBlock *const consumer)
	Creates an instance of consumer block, associates the given queue block referenced by the given NvSciStreamBlock with it and returns a NvSciStreamBlock referencing the created consumer block. More...
NvSciError	NvSciStreamStaticPoolCreate (uint32_t const numPackets, NvSciStreamBlock *const pool)
	Creates an instance of static pool block and returns a NvSciStreamBlock referencing the created pool block. More...
NvSciError	NvSciStreamMailboxQueueCreate (NvSciStreamBlock *const queue)
	Creates an instance of mailbox queue block and returns a NvSciStreamBlock referencing the created mailbox queue block. More...
NvSciError	NvSciStreamFifoQueueCreate (NvSciStreamBlock *const queue)
	Creates an instance of FIFO queue block and returns a NvSciStreamBlock referencing the created FIFO queue block. More...
NvSciError	NvSciStreamMulticastCreate (uint32_t const outputCount, NvSciStreamBlock *const multicast)
	Creates an instance of multicast block and returns a NvSciStreamBlock referencing the created multicast block. More...
NvSciError	NvSciStreamIpcSrcCreate (NvSciIpcEndpoint const ipcEndpoint, NvSciSyncModule const syncModule, NvSciBufModule const bufModule, NvSciStreamBlock *const ipc)
	Creates an instance of IpcSrc block and returns a NvSciStreamBlock referencing the created IpcSrc block. More...
NvSciError	NvSciStreamIpcDstCreate (NvSciIpcEndpoint const ipcEndpoint, NvSciSyncModule const syncModule, NvSciBufModule const bufModule, NvSciStreamBlock *const ipc)
	Creates an instance of IpcDst block and returns a NvSciStreamBlock referencing the created IpcDst block. More...
NvSciError	NvSciStreamBlockEventQuery (NvSciStreamBlock const block, int64_t const timeoutUsec, NvSciStreamEvent *const event)
	Queries for the next NvSciStreamEvent from block referenced by the given NvSciStreamBlock, optionally waiting, and returns it to the caller. More...
NvSciError	NvSciStreamBlockSyncRequirements (NvSciStreamBlock const block, bool const synchronousOnly, NvSciSyncAttrList const waitSyncAttrList)
	Sets NvSciSyncObj waiter requirements to the block referenced by the given NvSciStreamBlock. More...
NvSciError	NvSciStreamBlockSyncObjCount (NvSciStreamBlock const block, uint32_t const count)
	Sets NvSciSyncObj count to the block referenced by the given NvSciStreamBlock. More...
NvSciError	NvSciStreamBlockSyncObject (NvSciStreamBlock const block, uint32_t const index, NvSciSyncObj const syncObj)
	Sets NvSciSyncObj to the block referenced by the given NvSciStreamBlock. More...
NvSciError	NvSciStreamBlockPacketElementCount (NvSciStreamBlock const block, uint32_t const count)
	Sets packet element count to the block referenced by the given NvSciStreamBlock. More...
NvSciError	NvSciStreamBlockPacketAttr (NvSciStreamBlock const block, uint32_t const index, uint32_t const type, NvSciStreamElementMode const syncMode, NvSciBufAttrList const bufAttrList)
	Sets packet element information to the block referenced by the given NvSciStreamBlock. More...
NvSciError	NvSciStreamPoolPacketCreate (NvSciStreamBlock const pool, NvSciStreamCookie const cookie, NvSciStreamPacket *const handle)
	Creates a new packet and adds it to the pool block referenced by the given NvSciStreamBlock, associates the given NvSciStreamCookie with the packet and returns a NvSciStreamPacket which references the created packet. More...
NvSciError	NvSciStreamPoolPacketInsertBuffer (NvSciStreamBlock const pool, NvSciStreamPacket const handle, uint32_t const index, NvSciBufObj const bufObj)
	Registers a NvSciBufObj to the packet element referenced by the given index of the packet referenced by the given NvSciStreamPacket, if the packet is associated with the pool block referenced by the given NvSciStreamBlock. More...
NvSciError	NvSciStreamPoolPacketDelete (NvSciStreamBlock const pool, NvSciStreamPacket const handle)
	Removes a packet referenced by the given NvSciStreamPacket from the pool block referenced by the given NvSciStreamBlock. More...
NvSciError	NvSciStreamBlockPacketAccept (NvSciStreamBlock const block, NvSciStreamPacket const handle, NvSciStreamCookie const cookie, NvSciError const err)
	Accepts a packet referenced by the given NvSciStreamPacket. More...
NvSciError	NvSciStreamBlockElementAccept (NvSciStreamBlock const block, NvSciStreamPacket const handle, uint32_t const index, NvSciError const err)
	Accepts a packet element referenced by the given index of the packet referenced by the given NvSciStreamPacket. More...
NvSciError	NvSciStreamProducerPacketGet (NvSciStreamBlock const producer, NvSciStreamCookie *const cookie, NvSciSyncFence *const prefences)
	Instructs the producer referenced by the given NvSciStreamBlock to get a packet from the pool. More...
NvSciError	NvSciStreamProducerPacketPresent (NvSciStreamBlock const producer, NvSciStreamPacket const handle, NvSciSyncFence const *const postfences)
	Instructs the producer referenced by the given NvSciStreamBlock to insert a packet referenced by the given NvSciStreamPacket and the associated NvSciSyncFence array to every queue(s) in the stream configuration for consumer processing. More...
NvSciError	NvSciStreamConsumerPacketAcquire (NvSciStreamBlock const consumer, NvSciStreamCookie *const cookie, NvSciSyncFence *const prefences)
	Instructs the consumer referenced by the given NvSciStreamBlock to get a ready packet from the queue. More...
NvSciError	NvSciStreamConsumerPacketRelease (NvSciStreamBlock const consumer, NvSciStreamPacket const handle, NvSciSyncFence const *const postfences)
	Instructs the consumer referenced by the given NvSciStreamBlock to release a consumed packet referenced by the given NvSciStreamPacket and the associated NvSciSyncFence array to pool block for producer processing . More...
NvSciError	NvSciStreamBlockDelete (NvSciStreamBlock const block)
	Destroys a block referenced by the given NvSciStreamBlock. More...
NvSciError	NvSciStreamAttributeQuery (NvSciStreamQueryableAttrib const attr, int32_t *const value)
	Queries the value of one of the NvSciStreamQueryableAttrib. More...

Function Documentation

NvSciStreamAttributeQuery()

NvSciError NvSciStreamAttributeQuery	(	NvSciStreamQueryableAttrib const	attr,
		int32_t *const	value
	)

Queries the value of one of the NvSciStreamQueryableAttrib.

Preconditions

• None.

Actions

• NvSciStream looks up the value for the given NvSciStreamQueryableAttrib and returns it.

Postconditions

• None.

Parameters

[in]	attr	NvSciStreamQueryableAttrib to query.
[out]	value	The value queried.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Query is successful.
• NvSciError_BadParameter attr is invalid or value is null.

NvSciStreamBlockConnect()

NvSciError NvSciStreamBlockConnect	(	NvSciStreamBlock const	upstream,
		NvSciStreamBlock const	downstream
	)

Establishes connection between two blocks referenced by the given NvSciStreamBlock(s).

• Connects an available output of one block with an available input of another block.
• Each input and output can only have one connection. A stream is operational when all inputs and outputs of all blocks in the stream have a connection.

Preconditions

• The upstream block has an available output connection.
• The downstream block has an available input connection.

Actions

• Establish a connection between the two blocks.

Postconditions

• When a block has a connection to producer as well as connection to every consumer(s) in the stream, it will receive a NvSciStreamEventType_Connected event.

Parameters

[in]	upstream	NvSciStreamBlock which references an upstream block. Valid value: A valid NvSciStreamBlock which does not reference a Pool or Queue block.
[in]	downstream	NvSciStreamBlock which references a downstream block. Valid value: A valid NvSciStreamBlock which does not reference a Pool or Queue block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success The connection was made successfully.
• NvSciError_InsufficientResource block referenced by upstream argument has no available outputs or block referenced by downstream argument has no available inputs.
• NvSciError_AccessDenied: block referenced by upstream argument or block referenced by downstream argument does not allow explicit connection via NvSciStreamBlockConnect().

NvSciStreamBlockDelete()

NvSciError NvSciStreamBlockDelete

(

NvSciStreamBlock const

block

)

Destroys a block referenced by the given NvSciStreamBlock.

• Schedules a block for destruction, disconnecting the stream if this hasn't already occurred.
• The block's handle may no longer be used for any function calls.
• Resources associated with the block may not be freed immediately.
• Any pending data packets downstream of the destroyed block will still be available for the consumer to acquire.
• No new packets upstream of the destroyed block can be presented. Once packets are released, they will be freed.

Preconditions

• None.

Actions

• The block is scheduled for destruction.
• A NvSciStreamEventType_Disconnected event is sent to all upstream and downstream blocks, if they haven't received one already.

Postconditions

• The referenced NvSciStreamBlock is no longer valid.

Parameters

[in]

block

NvSciStreamBlock which references a block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Block successfully destroyed.

NvSciStreamBlockElementAccept()

NvSciError NvSciStreamBlockElementAccept	(	NvSciStreamBlock const	block,
		NvSciStreamPacket const	handle,
		uint32_t const	index,
		NvSciError const	err
	)

Accepts a packet element referenced by the given index of the packet referenced by the given NvSciStreamPacket.

• Used with producer and consumer to send their acceptance status of the NvSciStreamPacket element to pool block.
• Upon receiving a NvSciStreamEventType_PacketElement event, the producer and consumer should map the NvSciBufObj(s) into their space and report the status by calling this function.
• If successfully mapped, the error value should be NvSciError_Success. Otherwise it should be an error code indicating what failed.

Preconditions

• The NvSciStreamPacket handle has been received in a previous NvSciStreamEventType_PacketCreate event, and the NvSciBufObj for an indexed element has been received in a previous NvSciStreamEventType_PacketElement event.

Actions

• A NvSciStreamEventType_ElementStatusProducer or NvSciStreamEventType_ElementStatusConsumer event will be sent to the pool, depending on whether the argument block references a producer or consumer block.

Postconditions

• If successful, the NvSciBufObj(s) for the NvSciStreamPacket elements may now be used for producer and consumer processing.

Parameters

[in]	block	NvSciStreamBlock which references a producer or consumer block.
[in]	handle	NvSciStreamPacket which references the actual packet.
[in]	index	Index of the element within the packet. Valid value: 0 to packet element count received from pool through NvSciStreamEventType_PacketElementCount event.
[in]	err	Status of mapping operation.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success: Packet element status is successfully reported.
• NvSciError_BadParameter: index is invalid.
• NvSciError_NotImplemented The argument block is valid but it does not reference a producer or consumer block.
• NvSciError_InvalidState: If status for the same packet element is sent already.
• Error/panic behavior of this API includes any error/panic behavior that NvSciIpcWrite() can generate when the element acceptance status is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamBlockEventQuery()

NvSciError NvSciStreamBlockEventQuery	(	NvSciStreamBlock const	block,
		int64_t const	timeoutUsec,
		NvSciStreamEvent *const	event
	)

Queries for the next NvSciStreamEvent from block referenced by the given NvSciStreamBlock, optionally waiting, and returns it to the caller.

The appropriate handling of each NvSciStreamEventType is described in the section for the corresponding NvSciStreamEvent structure.

Preconditions

• The block to query has been created.

Actions

• Wait until an NvSciStreamEvent is pending on the block or the specified timeout period is reached, whichever comes first.
• Retrieves the next NvSciStreamEvent (if any) from the block, filling in the NvSciStreamEvent data structure.

Postconditions

• As defined for each NvSciStreamEventType, dequeuing an NvSciStreamEvent may allow other operations on the block to proceed.

Parameters

[in]	block	NvSciStreamBlock which references a block.
[in]	timeoutUsec	Timeout in microseconds (-1 to wait forever).
[out]	event	NvSciStreamEvent filled with corresponding event data.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success The output argument event is filled with the queried event data.
• NvSciError_Timeout The timeoutUsec period was reached before an NvSciStreamEvent became available.
• NvSciError_BadParameter The output argument event is null.

NvSciStreamBlockPacketAccept()

NvSciError NvSciStreamBlockPacketAccept	(	NvSciStreamBlock const	block,
		NvSciStreamPacket const	handle,
		NvSciStreamCookie const	cookie,
		NvSciError const	err
	)

Accepts a packet referenced by the given NvSciStreamPacket.

• Used with producer and consumer to send their acceptance status of the packet to pool block.
• Upon receiving a NvSciStreamEventType_PacketCreate event, the producer and consumer should set up their own internal data structures for the packet and assign a NvSciStreamCookie which they will use to look up the data structure. Afterwards, they should then call this function.
• If the client setup is successful, the error value should be set to NvSciError_Success, and the NvSciStreamCookie assigned to the packet should be provided. NvSciStream will track the NvSciStreamCookie with the packet and use it for all subsequent events related to the packet.
• If the client setup is not successful, an error value should be provided to indicate what went wrong. The cookie is ignored.

Preconditions

• The packet handle has been received in a previous NvSciStreamEventType_PacketCreate event, and has not yet been accepted.

Actions

• Associates the NvSciStreamCookie with the packet if err argument is NvSciError_Success.
• A NvSciStreamEventType_PacketStatusProducer or NvSciStreamEventType_PacketStatusConsumer event will be sent to the pool, depending on whether the argument block references a producer or consumer block.

Postconditions

• If successful, the NvSciStreamEventType_PacketElement event(s) may now be received.

Parameters

[in]	block	NvSciStreamBlock which references a producer or consumer block.
[in]	handle	NvSciStreamPacket which references the actual packet.
[in]	cookie	Block's NvSciStreamCookie to be associated with the NvSciStreamPacket. Valid value: cookie > NvSciStreamCookie_Invalid.
[in]	err	Status of packet setup.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet cookie/status is successfully reported.
• NvSciError_BadParameter cookie is NvSciStreamCookie_Invalid but the err is NvSciError_Success.
• NvSciError_BadParameter: cookie is valid but the err is not NvSciError_Success.
• NvSciError_NotImplemented The argument block is valid but it does not reference a producer or consumer block.
• NvSciError_InvalidState: If status for the packet is sent already.
• Error/panic behavior of this API includes any error/panic behavior that NvSciIpcWrite() can generate when the packet cookie and acceptance status is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamBlockPacketAttr()

NvSciError NvSciStreamBlockPacketAttr	(	NvSciStreamBlock const	block,
		uint32_t const	index,
		uint32_t const	type,
		NvSciStreamElementMode const	syncMode,
		NvSciBufAttrList const	bufAttrList
	)

Sets packet element information to the block referenced by the given NvSciStreamBlock.

• Used with the consumer to indicate what packet elements it desires, the producer to indicate what packet elements it can provide, and the pool to establish the combined packet element list.
• This function is expected to be called only once per packet element at setup time. The packet element information is immutable during streaming.

Preconditions

• For producer and consumer, must have received appropriate NvSciStreamEventType_Connected event from the other endpoint(s).
• For pool, must have received all NvSciStreamEventType_PacketAttrProducer and NvSciStreamEventType_PacketAttrConsumer events.

Actions

• If the argument block references a producer or consumer block, a NvSciStreamEventType_PacketAttrProducer or NvSciStreamEventType_PacketAttrConsumer event will be sent to pool.
• If the argument block references a pool block, a NvSciStreamEventType_PacketAttr event will be sent to both producer and consumer endpoints.

Postconditions

• For the pool, packets may now be created.

Parameters

[in]	block	NvSciStreamBlock which references a producer or consumer or pool block.
[in]	index	Index of element within list of packet elements. Valid value: 0 to count set earlier with NvSciStreamBlockPacketElementCount() - 1.
[in]	type	User-defined type to identify element.
[in]	syncMode	Preferred NvSciStreamElementMode for element data.
[in]	bufAttrList	NvSciBufAttrList for packet element.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet element information is sent successfully.
• NvSciError_BadParameter bufAttrList is NULL or index exceeds the maximum allowed.
• NvSciError_NotImplemented The argument block is valid but it does not reference a producer or consumer or pool block.
• NvSciError_InvalidState Packet element information for the index is already sent.
• NvSciError_InvalidState: The argument block references a pool block but NvSciStreamEventType_PacketAttrProducer and NvSciStreamEventType_PacketAttrConsumer events are not yet queried from pool block.
• Error/panic behavior of this API includes:
  • Any error/panic behavior that NvSciBufAttrListClone() or NvSciBufAttrListIpcExportUnreconciled() or NvSciBufAttrListIpcExportReconciled() can generate when bufAttrList argument is passed to it.
  • Any error/panic behavior that NvSciIpcWrite() can generate when NvSciBufAttrList descriptor for the bufAttrList is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamBlockPacketElementCount()

NvSciError NvSciStreamBlockPacketElementCount	(	NvSciStreamBlock const	block,
		uint32_t const	count
	)

Sets packet element count to the block referenced by the given NvSciStreamBlock.

• Used with the consumer to indicate the number of packet elements it desires, the producer to indicate the number of packet elements it can provide, and the pool to determine the combined number of packet elements.
• The element count is implicitly set to one.
• If the block needs or provides no element, the application must make this call with count equal to zero.
• The number of packet elements is immutable during streaming.

Preconditions

• For producer and consumer, must have received appropriate NvSciStreamEventType_Connected event from the other endpoint(s).
• For pool, must have received all NvSciStreamEventType_PacketAttrProducer and NvSciStreamEventType_PacketAttrConsumer events.
• This call could be skipped if block needs (or provides) only one element per packet.

Actions

• If the argument block references a producer or consumer block, a NvSciStreamEventType_PacketElementCountProducer or NvSciStreamEventType_PacketElementCountConsumer event will be sent to pool.
• If the argument block references a pool block, a NvSciStreamEventType_PacketElementCount event will be sent to both producer and consumer endpoints.

Postconditions

• None.

Parameters

[in]	block	NvSciStreamBlock which references a producer or consumer or pool block.
[in]	count	Number of elements per packet. Valid value: 0 to NvSciStreamQueryableAttrib_MaxElements attribute value queried by successful call to NvSciStreamAttributeQuery() API.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet element count is sent successfully.
• NvSciError_BadParameter count exceeds the maximum allowed.
• NvSciError_NotImplemented The argument block is valid but it does not reference a producer or consumer or pool block.
• NvSciError_InvalidState: The argument block references a pool block but NvSciStreamEventType_PacketAttrProducer and NvSciStreamEventType_PacketAttrConsumer events are not yet queried from pool block.
• NvSciError_InvalidState: If the count is already sent.
• Error/panic behavior of this API includes any error/panic behavior that NvSciIpcWrite() can generate when the count is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamBlockSyncObjCount()

NvSciError NvSciStreamBlockSyncObjCount	(	NvSciStreamBlock const	block,
		uint32_t const	count
	)

Sets NvSciSyncObj count to the block referenced by the given NvSciStreamBlock.

• Used with producer and consumer to pass the information on the number of NvSciSyncObj(s) will be created and shared with the other endpoint(s).
• The NvSciSyncObj count is implicitly set to one.
• If the block provides no NvSciSyncObj, the application must make this call, with count equal to zero, to advance the state of the stream and inform the other endpoint(s).

Preconditions

• Block must have received NvSciStreamEventType_SyncAttr event from the other endpoint(s).
• This call could be skipped if the block provides only one NvSciSyncObj.

Actions

• A NvSciStreamEventType_SyncCount event is sent to the other endpoint(s).

Postconditions

• None.

Parameters

[in]	block	NvSciStreamBlock which references a producer or consumer block.
[in]	count	NvSciSyncObj count to be sent. Valid value: 0 to NvSciStreamQueryableAttrib_MaxSyncObj attribute value queried by successful call to NvSciStreamAttributeQuery() API.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success NvSciSyncObj count is sent successfully.
• NvSciError_InvalidOperation NvSciStreamEventType_SyncAttr event from the block is not yet queried by the application.
• NvSciError_InvalidOperation: If stream is in synchronous mode (if the synchronousOnly flag received through NvSciStreamEventType_SyncAttr from other endpoint is true), but the count is greater than zero.
• NvSciError_BadParameter the count exceeds the maximum allowed.
• NvSciError_NotImplemented The argument block is valid but it does not reference a producer or consumer block.
• NvSciError_InvalidState: If the count is already sent.
• Error/panic behavior of this API includes any error/panic behavior that NvSciIpcWrite() can generate when the count is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamBlockSyncObject()

NvSciError NvSciStreamBlockSyncObject	(	NvSciStreamBlock const	block,
		uint32_t const	index,
		NvSciSyncObj const	syncObj
	)

Sets NvSciSyncObj to the block referenced by the given NvSciStreamBlock.

Used with producer and consumer to share the created NvSciSyncObj(s) with other endpoint(s).

Preconditions

• Block must have received NvSciStreamEventType_SyncAttr event from the other endpoint(s).

Actions

• A NvSciStreamEventType_SyncDesc event is sent to the other endpoint(s).

Postconditions

• None.

Parameters

[in]	block	NvSciStreamBlock which references a producer or consumer block.
[in]	index	Index in list of NvSciSyncObj(s). Valid value: 0 to count set earlier with NvSciStreamBlockSyncObjCount() - 1.
[in]	syncObj	NvSciSyncObj.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success NvSciSyncObj is sent to the other endpoint(s) successfully.
• NvSciError_BadParameter index exceeds the NvSciSyncObj count count set earlier with NvSciStreamBlockSyncObjCount().
• NvSciError_InvalidOperation NvSciStreamEventType_SyncAttr event from the block is not yet queried by the application.
• NvSciError_InvalidOperation: If stream is in synchronous mode (if the synchronousOnly flag received through NvSciStreamEventType_SyncAttr from other endpoint is true).
• NvSciError_NotImplemented The argument block is valid but it does not reference a producer or consumer block.
• Error/panic behavior of this API includes:
  • Any error/panic behavior that NvSciSyncObjDup() or NvSciSyncObjIpcExport() can generate when syncObj argument is passed to it.
  • Any error/panic behavior that NvSciIpcWrite() can generate when NvSciSyncObjIpcExportDescriptor for the syncObj is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamBlockSyncRequirements()

NvSciError NvSciStreamBlockSyncRequirements	(	NvSciStreamBlock const	block,
		bool const	synchronousOnly,
		NvSciSyncAttrList const	waitSyncAttrList
	)

Sets NvSciSyncObj waiter requirements to the block referenced by the given NvSciStreamBlock.

Used with producer and consumer to establish their waiter requirements for NvSciSyncObj(s) provided by the other endpoint(s).

Preconditions

• Block must have received appropriate NvSciStreamEventType_Connected event from the other endpoint(s).

Actions

• A NvSciStreamEventType_SyncAttr event is sent to the other endpoint(s).

Postconditions

• None.

Parameters

[in]	block	NvSciStreamBlock which references a producer or consumer block.
[in]	synchronousOnly	Flag to indicate whether the endpoint supports NvSciSyncObj(s) or not.
[in]	waitSyncAttrList	Requirements for endpoint to wait for NvSciSyncObj(s). This parameter should be NULL if synchronousOnly parameter is true.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success NvSciSyncObj waiter requirements are registered successfully.
• NvSciError_BadParameter waitSyncAttrList is NULL and synchronousOnly flag is false.
• NvSciError_NotImplemented The argument block is valid but it does not reference a producer or consumer block.
• NvSciError_InvalidOperation synchronousOnly flag is true but waitSyncAttrList is not NULL.
• NvSciError_InvalidState If NvSciSyncObj waiter requirements are already sent to other endpoint.
• Error/panic behavior of this API includes:
  • Any error/panic behavior that NvSciSyncAttrListClone() or NvSciSyncAttrListIpcExportUnreconciled() can generate when waitSyncAttrList argument is passed to it.
  • Any error/panic behavior that NvSciIpcWrite() can generate when NvSciSyncAttrList descriptor for the waitSyncAttrList is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamConsumerCreate()

NvSciError NvSciStreamConsumerCreate	(	NvSciStreamBlock const	queue,
		NvSciStreamBlock *const	consumer
	)

Creates an instance of consumer block, associates the given queue block referenced by the given NvSciStreamBlock with it and returns a NvSciStreamBlock referencing the created consumer block.

• Creates a block for the consumer end of a stream. All streams require at least one consumer block. A consumer block must have a queue associated with it for managing pending packets. Consumer blocks have one input connection and no output connections.
• Once the stream is operational, this block can be used to exchange NvSciSync information with the producer and NvSciBuf information with the pool.

Preconditions

• None.

Actions

• Creates a new instance of consumer block.
• Associates the given queue block with the consumer block.

Postconditions

• The block is ready to be connected to other stream blocks.
• The block can be queried for NvSciStreamEvent(s).

Parameters

[in]	queue	NvSciStreamBlock which references a queue block to be associated with the consumer block.
[out]	consumer	NvSciStreamBlock which references a new consumer block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success A new consumer block was set up successfully.
• NvSciError_BadParameter If the output parameter consumer is a null pointer or the queue parameter does not reference a queue block.
• NvSciError_InsufficientResource If the queue block is already bound to another consumer.
• NvSciError_StreamInternalError The consumer block cannot be initialized properly.

NvSciStreamConsumerPacketAcquire()

NvSciError NvSciStreamConsumerPacketAcquire	(	NvSciStreamBlock const	consumer,
		NvSciStreamCookie *const	cookie,
		NvSciSyncFence *const	prefences
	)

Instructs the consumer referenced by the given NvSciStreamBlock to get a ready packet from the queue.

• If a packet is ready for consumer processing, this function will retrieve it from the queue and assign it to the consumer.
• The consumer may hold multiple packets for rendering, and is not required to return them in the order they were obtained.

Preconditions

• The consumer block must have received NvSciStreamEventType_PacketReady event from queue block for processing the ready packet.
• All packets have been accepted by the producer and the consumer(s).
• Packet must be associated with queue block.

Actions

• Retrieves a packet ready for consumer processing and returns it to the caller.
• Disassociates the packet from the queue.

Postconditions

• None.

Parameters

[in]	consumer	NvSciStreamBlock which references a consumer block.
[out]	cookie	NvSciStreamCookie identifying packet.
[out]	prefences	Pointer to an array of NvSciSyncFence(s) to wait for before using the packet. Valid value: Must be at least large enough to hold one NvSciSyncFence for each NvSciSyncObj created by the producer. If the NvSciSyncObj count received through NvSciStreamEventType_SyncCount event from producer is zero, it can be NULL.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet was successfully acquired.
• NvSciError_BadParameter If cookie is NULL.
• NvSciError_BadParameter If prefences is NULL and NvSciSyncObj count received through NvSciStreamEventType_SyncCount event from producer block is greater than zero.
• NvSciError_NotImplemented The argument consumer is valid but it does not reference a consumer block.
• NvSciError_NoStreamPacket No packet is available with the queue.

NvSciStreamConsumerPacketRelease()

NvSciError NvSciStreamConsumerPacketRelease	(	NvSciStreamBlock const	consumer,
		NvSciStreamPacket const	handle,
		NvSciSyncFence const *const	postfences
	)

Instructs the consumer referenced by the given NvSciStreamBlock to release a consumed packet referenced by the given NvSciStreamPacket and the associated NvSciSyncFence array to pool block for producer processing .

Preconditions

• The NvSciStreamPacket must be associated with the consumer.

Actions

• The NvSciStreamPacket is sent back upstream. Once released by all consumers:
  • It will be put in the pool where it can be obtained by the producer block.
  • A NvSciStreamEventType_PacketReady event will be sent to the producer block.
• The NvSciStreamPacket is disassociated with the consumer block.

Postconditions

• None.

Parameters

[in]	consumer	NvSciStreamBlock which references a consumer block.
[in]	handle	NvSciStreamPacket which references the actual packet.
[in]	postfences	A pointer to array of NvSciSyncFences associated with the packet.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet was successfully released.
• NvSciError_BadParameter postfences is NULL.
• NvSciError_NotImplemented The argument consumer is valid but it does not reference a consumer block.
• NvSciError_InvalidOperation If packet is not currently held by the application.
• Error/panic behavior of this API includes:
  • Any error/panic behavior that NvSciSyncFenceDup() or NvSciSyncIpcExportFence() can generate when an entry of the postfences array is passed to it.
  • Any error/panic behavior that NvSciIpcWrite() can generate when NvSciSyncFence descriptor for an entry of the postfences array is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamFifoQueueCreate()

NvSciError NvSciStreamFifoQueueCreate

(

NvSciStreamBlock *const

queue

)

Creates an instance of FIFO queue block and returns a NvSciStreamBlock referencing the created FIFO queue block.

• Creates a block for tracking the list of packets available to be used by the consumer. This is one available type of queue block. Every consumer must own a queue block, provided at the time the consumer is created.
• A FIFO queue holds a list of packets, which will be acquired in the order they were presented.
• If a new packet arrives, it is added to the end of the FIFO.
• This type of queue is intended for consumer applications which must process every packet that is produced.
• Once connected, the application does not directly interact with this block. The consumer block will communicate with it to obtain new packets.

Preconditions

• None.

Actions

• Initialize a queue to manage waiting packets.

Postconditions

• The block is ready to be connected to other stream blocks.

Parameters

[out]

queue

NvSciStreamBlock which references a new FIFO queue block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success A new FIFO queue block was set up successfully.
• NvSciError_BadParameter The output parameter queue is a null pointer.
• NvSciError_StreamInternalError The FIFO queue block cannot be initialized properly.

NvSciStreamIpcDstCreate()

NvSciError NvSciStreamIpcDstCreate	(	NvSciIpcEndpoint const	ipcEndpoint,
		NvSciSyncModule const	syncModule,
		NvSciBufModule const	bufModule,
		NvSciStreamBlock *const	ipc
	)

Creates an instance of IpcDst block and returns a NvSciStreamBlock referencing the created IpcDst block.

• Creates the downstream half of an IPC block pair which allows packets to be transmitted between processes.
• IpcDst block has one output connection and no input connection.
• An IpcDst block connects to upstream through the NvSciIpcEndpoint used to create the block.

Preconditions

• None.

Actions

• Establishes connection through NvSciIpcEndpoint.

Postconditions

• The block is ready to be connected to other stream blocks.

Parameters

[in]	ipcEndpoint	NvSciIpcEndpoint handle.
[in]	syncModule	NvSciSyncModule that is used to import a NvSciSyncAttrList across an IPC boundary. This must be same module that was used to create NvSciSyncAttrList when specifying the NvSciSyncObj waiter requirements.
[in]	bufModule	NvSciBufModule that is used to import a NvSciBufAttrList across an IPC boundary. This must be same module that was used to create NvSciBufAttrList when specifying the packet element information.
[out]	ipc	NvSciStreamBlock which references a new IpcDst block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success A new IpcDst block was set up successfully.
• NvSciError_StreamInternalError: If connection establishment through ipcEndpoint fails.
• NvSciError_BadParameter The output parameter ipc is a null pointer.
• NvSciError_StreamInternalError The IpcDst block can't be initialized properly.

NvSciStreamIpcSrcCreate()

NvSciError NvSciStreamIpcSrcCreate	(	NvSciIpcEndpoint const	ipcEndpoint,
		NvSciSyncModule const	syncModule,
		NvSciBufModule const	bufModule,
		NvSciStreamBlock *const	ipc
	)

Creates an instance of IpcSrc block and returns a NvSciStreamBlock referencing the created IpcSrc block.

• Creates the upstream half of an IPC block pair which allows packets to be transmitted between processes.
• IpcSrc block has one input connection and no output connection.
• An IpcSrc block connects to downstream through the NvSciIpcEndpoint used to create the block.

Preconditions

• None.

Actions

• Establishes connection through NvSciIpcEndpoint.

Postconditions

• The block is ready to be connected to other stream blocks.

Parameters

[in]	ipcEndpoint	NvSciIpcEndpoint handle.
[in]	syncModule	NvSciSyncModule that is used to import a NvSciSyncAttrList across an IPC boundary. This must be same module that was used to create NvSciSyncAttrList when specifying the NvSciSyncObj waiter requirements.
[in]	bufModule	NvSciBufModule that is used to import a NvSciBufAttrList across an IPC boundary. This must be same module that was used to create NvSciBufAttrList when specifying the packet element information.
[out]	ipc	NvSciStreamBlock which references a new IpcSrc block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success A new IpcSrc block was set up successfully.
• NvSciError_StreamInternalError: If connection establishment through ipcEndpoint fails.
• NvSciError_BadParameter The output parameter ipc is a null pointer.
• NvSciError_StreamInternalError The IpcSrc block cannot be initialized properly.

NvSciStreamMailboxQueueCreate()

NvSciError NvSciStreamMailboxQueueCreate

(

NvSciStreamBlock *const

queue

)

Creates an instance of mailbox queue block and returns a NvSciStreamBlock referencing the created mailbox queue block.

• Creates a block for managing the packets that are ready to be consumed by the consumer. This is one available type of queue block. Every consumer must own a queue block, provided at the time the consumer is created.
• A mailbox queue holds a single packet. If a new packet arrives, the old one is replaced and returned to the pool for reuse without ever being acquired.
• This type of queue is intended for consumer applications which don't need to process every packet and always wish to have the latest input available.
• Once connected, the application does not directly interact with this block. The consumer block will communicate with it to obtain new packets.

Preconditions

• None.

Actions

• Initialize a queue to hold a single packet for acquire.

Postconditions

• The block is ready to be connected to other stream blocks.

Parameters

[out]

queue

NvSciStreamBlock which references a new mailbox queue block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success A new mailbox queue block was set up successfully.
• NvSciError_BadParameter The output parameter queue is a null pointer.
• NvSciError_StreamInternalError The mailbox queue block cannot be initialized properly.

NvSciStreamMulticastCreate()

NvSciError NvSciStreamMulticastCreate	(	uint32_t const	outputCount,
		NvSciStreamBlock *const	multicast
	)

Creates an instance of multicast block and returns a NvSciStreamBlock referencing the created multicast block.

• Creates a block allowing for one input and one or more outputs.
• Multicast block broadcasts messages sent from upstream to all of the downstream blocks.
• Mulitcast block aggregates messages of the same type from downstreams into one before sending it upstream.

Preconditions

• None.

Actions

• Initializes a block that takes one input and one or more outputs.

Postconditions

• The block is ready to be connected to other stream blocks.

Parameters

[in]	outputCount	Number of output blocks that will be connected. Valid value: 1 to NvSciStreamQueryableAttrib_MaxMulticastOutputs attribute value queried by successful call to NvSciStreamAttributeQuery() API.
[out]	multicast	NvSciStreamBlock which references a new multicast block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success A new multicast block was set up successfully.
• NvSciError_BadParameter The output parameter multicast is a null pointer or outputCount is larger than the number allowed.
• NvSciError_StreamInternalError The multicast block cannot be initialized properly.

NvSciStreamPoolPacketCreate()

NvSciError NvSciStreamPoolPacketCreate	(	NvSciStreamBlock const	pool,
		NvSciStreamCookie const	cookie,
		NvSciStreamPacket *const	handle
	)

Creates a new packet and adds it to the pool block referenced by the given NvSciStreamBlock, associates the given NvSciStreamCookie with the packet and returns a NvSciStreamPacket which references the created packet.

Preconditions

• Final packet element information must have been specified for the pool.
• For static pool, the number of packets already created has not reached the limit which was set when the static pool was created.

Actions

• A new NvSciStreamPacket is assigned to the created packet and returned to the caller.
• A NvSciStreamEventType_PacketCreate event will be sent to the producer and the consumer endpoints.

Postconditions

• The application can register NvSciBufObj(s) to the created packet.

Parameters

[in]	pool	NvSciStreamBlock which references a pool block.
[in]	cookie	Pool's NvSciStreamCookie for the packet. Valid value: cookie > NvSciStreamCookie_Invalid.
[out]	handle	NvSciStreamPacket which references the created packet.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet successfully created.
• NvSciError_BadParameter cookie argument is either invalid or already used for other packet.
• NvSciError_BadParameter handle argument is NULL.
• NvSciError_NotImplemented The argument pool is valid but it does not reference a pool block.
• NvSciError_InsufficientMemory: If unable to create a new packet instance.
• NvSciError_InvalidOperation: Pool has reached its limit with the maximum number of packets that can be created from it.
• Error/panic behavior of this API includes any error/panic behavior that NvSciIpcWrite() can generate when the packet create information is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamPoolPacketDelete()

NvSciError NvSciStreamPoolPacketDelete	(	NvSciStreamBlock const	pool,
		NvSciStreamPacket const	handle
	)

Removes a packet referenced by the given NvSciStreamPacket from the pool block referenced by the given NvSciStreamBlock.

Schedules an existing packet to be removed from the pool. If the packet is currently in the pool, it is removed right away. Otherwise this is deferred until the packet returns to the pool.

Preconditions

• Specified packet must exist.

Actions

• If the pool holds the specified packet or when it is returned to the pool, the pool releases resources associated with it and sends a NvSciStreamEventType_PacketDelete event to the producer and consumer endpoint(s).

Postconditions

• The packet may no longer be used for pool operations.

Parameters

[in]	pool	NvSciStreamBlock which references a pool block.
[in]	handle	NvSciStreamPacket which references the actual packet.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet successfully deleted.
• NvSciError_NotImplemented The argument pool is valid but it does not reference a pool block.
• NvSciError_BadParameter: If the Packet is already marked for deletion.
• Error/panic behavior of this API includes any error/panic behavior that NvSciIpcWrite() can generate when the packet delete information is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamPoolPacketInsertBuffer()

NvSciError NvSciStreamPoolPacketInsertBuffer	(	NvSciStreamBlock const	pool,
		NvSciStreamPacket const	handle,
		uint32_t const	index,
		NvSciBufObj const	bufObj
	)

Registers a NvSciBufObj to the packet element referenced by the given index of the packet referenced by the given NvSciStreamPacket, if the packet is associated with the pool block referenced by the given NvSciStreamBlock.

Preconditions

• The number of NvSciBufObj(s) already registered to the packet hasn't reached the NvSciBufObj count set to pool by NvSciStreamBlockPacketElementCount().

Actions

• The NvSciBufObj is registered to the given packet element.

Postconditions

• A NvSciStreamEventType_PacketElement event (one per packet element) will be sent to producer and consumer endpoints.

Parameters

[in]	pool	NvSciStreamBlock which references a pool block.
[in]	handle	NvSciStreamPacket which references the actual packet.
[in]	index	Index of element within packet. Valid value: 0 to count set to pool earlier with NvSciStreamBlockPacketElementCount() - 1.
[in]	bufObj	NvSciBufObj to be registered.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success bufObj has been successfully registered.
• NvSciError_BadParameter bufObj is NULL or index exceeds the maximum allowed.
• NvSciError_NotImplemented The argument pool is valid but it does not reference a pool block.
• NvSciError_InvalidState: If NvSciBufObj for the same index is already registered.
• Error/panic behavior of this API includes:
  • Any error/panic behavior that NvSciBufObjDup() or NvSciBufObjIpcExport() can generate when bufObj argument is passed to it.
  • Any error/panic behavior that NvSciIpcWrite() can generate when NvSciBufObjIpcExportDescriptor for the bufObj is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamProducerCreate()

NvSciError NvSciStreamProducerCreate	(	NvSciStreamBlock const	pool,
		NvSciStreamBlock *const	producer
	)

Creates an instance of producer block, associates the given pool referenced by the given NvSciStreamBlock with it and returns a NvSciStreamBlock referencing the created producer block.

• Creates a block for the producer end of a stream. All streams require one producer block. A producer block must have a pool associated with it for managing available packets. Producer blocks have one output connection and no input connections.
• Once the stream is operational, this block can be used to exchange NvSciSync information with the consumer and NvSciBuf information with the pool.

Preconditions

• None.

Actions

• Creates a new instance of producer block.
• Associates the given pool block with the producer block.

Postconditions

• The block is ready to be connected to other stream blocks.
• The block can be queried for NvSciStreamEvent(s).

Parameters

[in]	pool	NvSciStreamBlock which references a pool block to be associated with the producer block.
[out]	producer	NvSciStreamBlock which references a new producer block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success A new producer block was set up successfully.
• NvSciError_BadParameter If the output parameter producer is a null pointer or the pool parameter does not reference a pool block.
• NvSciError_InsufficientResource If the pool block is already bound to another producer.
• NvSciError_StreamInternalError The producer block cannot be initialized properly.

NvSciStreamProducerPacketGet()

NvSciError NvSciStreamProducerPacketGet	(	NvSciStreamBlock const	producer,
		NvSciStreamCookie *const	cookie,
		NvSciSyncFence *const	prefences
	)

Instructs the producer referenced by the given NvSciStreamBlock to get a packet from the pool.

• If a packet is available for producer processing, this function will retrieve it from the pool and assign it to the producer.
• The producer may hold multiple packets for rendering, and is not required to present them in the order they were obtained.

Preconditions

• The producer block must have received the NvSciStreamEventType_PacketReady event from pool for processing the next available packet.
• All packets have been accepted by the producer and the consumer(s).

Actions

• Retrieves an available packet for producer processing and returns it to the caller.
• Disassociates the packet from the pool block.

Postconditions

• None.

Parameters

[in]	producer	NvSciStreamBlock which references a producer block.
[out]	cookie	NvSciStreamCookie identifying the packet.
[out]	prefences	Pointer to an array of NvSciSyncFence(s) to wait for before using the packet. Valid value: Must be at least large enough to hold one NvSciSyncFence for each NvSciSyncObj created by the consumer. If the NvSciSyncObj count received through NvSciStreamEventType_SyncCount event from consumer is zero, it can be NULL.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet successfully retrieved.
• NvSciError_BadParameter If cookie is NULL
• NvSciError_BadParameter If prefences is NULL and NvSciSyncObj count received through NvSciStreamEventType_SyncCount event from consumer block(s) is greater than zero.
• NvSciError_NotImplemented The argument producer is valid but it does not reference a producer block.
• NvSciError_NoStreamPacket No packet available with the pool.

NvSciStreamProducerPacketPresent()

NvSciError NvSciStreamProducerPacketPresent	(	NvSciStreamBlock const	producer,
		NvSciStreamPacket const	handle,
		NvSciSyncFence const *const	postfences
	)

Instructs the producer referenced by the given NvSciStreamBlock to insert a packet referenced by the given NvSciStreamPacket and the associated NvSciSyncFence array to every queue(s) in the stream configuration for consumer processing.

Preconditions

• The NvSciStreamPacket must be associated with the producer block.

Actions

• The NvSciStreamPacket is sent to the queue(s) where it will be held until acquired by the consumer or returned without acquisition.
• If a NvSciStreamPacket is not already pending in the queue, a NvSciStreamEventType_PacketReady event will be sent to each consumer. The NvSciStreamPacket is disassociated from the producer block.

Postconditions

• None.

Parameters

[in]	producer	NvSciStreamBlock which references a producer block.
[in]	handle	NvSciStreamPacket which references the actual packet.
[in]	postfences	A pointer to array of NvSciSyncFences associated with the packet.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success Packet successfully presented.
• NvSciError_BadParameter postfences is NULL.
• NvSciError_NotImplemented The argument producer is valid but it does not reference a producer block.
• NvSciError_InvalidOperation If packet is not currently held by the application.
• Error/panic behavior of this API includes:
  • Any error/panic behavior that NvSciSyncFenceDup() or NvSciSyncIpcExportFence() can generate when an entry of the postfences array is passed to it.
  • Any error/panic behavior that NvSciIpcWrite() can generate when NvSciSyncFence descriptor for an entry of the postfences array is exported over NvSciIpc channel if one is in use by the stream.

NvSciStreamStaticPoolCreate()

NvSciError NvSciStreamStaticPoolCreate	(	uint32_t const	numPackets,
		NvSciStreamBlock *const	pool
	)

Creates an instance of static pool block and returns a NvSciStreamBlock referencing the created pool block.

• Creates a block for management of a stream's packet pool. Every producer must own a pool block, provided at the producer's creation.
• A static pool has a fixed number of packets which must be defined before streaming begins, and is intended for safety-certified usage.
• Once the stream is operational and the application component has determined the packet requirements(packet element count and packet element buffer attributes), this block can be used to associate NvSciBufObj(s) to each packet.

Preconditions

• None.

Actions

• Allocates data structures to describe packets.
• Initializes queue of available packets.

Postconditions

• The block is ready to be connected to other stream blocks.
• The block can be queried for NvSciStreamEvent(s).

Parameters

[in]	numPackets	Number of packets.
[out]	pool	NvSciStreamBlock which references a new pool block.

Returns

NvSciError, the completion code of this operation.

• NvSciError_Success A new pool block was set up successfully.
• NvSciError_BadParameter The output parameter pool is a null pointer.
• NvSciError_StreamInternalError The pool block cannot be initialized properly.