The NvSciStream library is a layer on top of NvSciBuf and NvSciSync libraries that provides utilities for streaming sequences of data packets between multiple application modules to support a wide variety of use cases.
Data Structures | |
struct | NvSciStreamEvent |
Describes a component event. More... | |
struct | NvSciStreamElementAttr |
The following data structures are no longer used by any interfaces and are deprecated. More... | |
struct | NvSciStreamElementDesc |
struct | NvSciStreamSyncAttr |
struct | NvSciStreamSyncDesc |
struct | NvSciStreamPayload |
Typedefs | |
typedef uintptr_t | NvSciStreamBlock |
Handle to a stream component. More... | |
typedef uintptr_t | NvSciStreamPacket |
NvSciStream-assigned handle for a packet. More... | |
typedef uintptr_t | NvSciStreamCookie |
Component-assigned cookie for a packet. More... | |
Functions | |
NvSciError | NvSciStreamBlockConnect (NvSciStreamBlock const upstream, NvSciStreamBlock const downstream) |
Connects two stream blocks. More... | |
NvSciError | NvSciStreamProducerCreate (NvSciStreamBlock const pool, NvSciStreamBlock *const producer) |
Creates a stream producer block. More... | |
NvSciError | NvSciStreamConsumerCreate (NvSciStreamBlock const queue, NvSciStreamBlock *const consumer) |
Creates a stream consumer block. More... | |
NvSciError | NvSciStreamStaticPoolCreate (uint32_t const numPackets, NvSciStreamBlock *const pool) |
Creates a static stream pool block. More... | |
NvSciError | NvSciStreamMailboxQueueCreate (NvSciStreamBlock *const queue) |
Creates a mailbox queue block. More... | |
NvSciError | NvSciStreamFifoQueueCreate (NvSciStreamBlock *const queue) |
Creates a FIFO queue block. More... | |
NvSciError | NvSciStreamMulticastCreate (uint32_t const outputCount, NvSciStreamBlock *const multicast) |
Creates a multicast block. More... | |
NvSciError | NvSciStreamIpcSrcCreate (NvSciIpcEndpoint const ipcEndpoint, NvSciSyncModule const syncModule, NvSciBufModule const bufModule, NvSciStreamBlock *const ipc) |
Creates an IPC source block. More... | |
NvSciError | NvSciStreamIpcDstCreate (NvSciIpcEndpoint const ipcEndpoint, NvSciSyncModule const syncModule, NvSciBufModule const bufModule, NvSciStreamBlock *const ipc) |
Creates an IPC destination block. More... | |
NvSciError | NvSciStreamBlockEventQuery (NvSciStreamBlock const block, int64_t const timeoutUsec, NvSciStreamEvent *const event) |
Queries for the next event from block's event queue, optionally waiting, and returns it to the caller. More... | |
NvSciError | NvSciStreamBlockSyncRequirements (NvSciStreamBlock const block, bool const synchronousOnly, NvSciSyncAttrList const waitSyncAttrList) |
Sets block sync object requirements. More... | |
NvSciError | NvSciStreamBlockSyncObjCount (NvSciStreamBlock const block, uint32_t const count) |
Provides block's number of sync objects. More... | |
NvSciError | NvSciStreamBlockSyncObject (NvSciStreamBlock const block, uint32_t const index, NvSciSyncObj const syncObj) |
Provides block's sync object. More... | |
NvSciError | NvSciStreamBlockPacketElementCount (NvSciStreamBlock const block, uint32_t const count) |
Block sets the number of elements in a packet. More... | |
NvSciError | NvSciStreamBlockPacketAttr (NvSciStreamBlock const block, uint32_t const index, uint32_t const type, NvSciStreamElementMode const syncMode, NvSciBufAttrList const bufAttrList) |
Sets block packet requirements/capabilities. More... | |
NvSciError | NvSciStreamPoolPacketCreate (NvSciStreamBlock const pool, NvSciStreamCookie const cookie, NvSciStreamPacket *const handle) |
Adds a new packet to the pool. More... | |
NvSciError | NvSciStreamPoolPacketInsertBuffer (NvSciStreamBlock const pool, NvSciStreamPacket const handle, uint32_t const index, NvSciBufObj const bufObj) |
Registers a buffer to the packet. More... | |
NvSciError | NvSciStreamPoolPacketDelete (NvSciStreamBlock const pool, NvSciStreamPacket const handle) |
Removes a packet from the pool. More... | |
NvSciError | NvSciStreamBlockPacketAccept (NvSciStreamBlock const block, NvSciStreamPacket const handle, NvSciStreamCookie const cookie, NvSciError const err) |
Accepts a packet provided by the pool. More... | |
NvSciError | NvSciStreamBlockElementAccept (NvSciStreamBlock const block, NvSciStreamPacket const handle, uint32_t const index, NvSciError const err) |
Accepts a packet element provided by the pool. More... | |
NvSciError | NvSciStreamProducerPacketGet (NvSciStreamBlock const producer, NvSciStreamCookie *const cookie, NvSciSyncFence *const prefences) |
Instructs the producer to get a packet from the pool. More... | |
NvSciError | NvSciStreamProducerPacketPresent (NvSciStreamBlock const producer, NvSciStreamPacket const handle, NvSciSyncFence const *const postfences) |
Inserts a data packet into the stream. More... | |
NvSciError | NvSciStreamConsumerPacketAcquire (NvSciStreamBlock const consumer, NvSciStreamCookie *const cookie, NvSciSyncFence *const prefences) |
Instructs the consumer to get a packet from the queue. More... | |
NvSciError | NvSciStreamConsumerPacketRelease (NvSciStreamBlock const consumer, NvSciStreamPacket const handle, NvSciSyncFence const *const postfences) |
Returns a data packet to the stream. More... | |
NvSciError | NvSciStreamBlockDelete (NvSciStreamBlock const block) |
Destroys a stream block. More... | |
NvSciError | NvSciStreamAttributeQuery (NvSciStreamQueryableAttrib const attr, int32_t *const value) |
Queries NvSciStream attributes. More... | |
Variables | |
static const NvSciStreamPacket | NvSciStreamPacket_Invalid = 0U |
Constant variable denoting invalid packet. More... | |
static const NvSciStreamCookie | NvSciStreamCookie_Invalid = 0U |
Constant variable denoting invalid cookie. More... | |
typedef uintptr_t NvSciStreamBlock |
typedef uintptr_t NvSciStreamCookie |
typedef uintptr_t NvSciStreamPacket |
Defines packet element access modes.
Definition at line 95 of file nvscistream.h.
enum NvSciStreamEventType |
Defines component event types.
Definition at line 112 of file nvscistream.h.
Defines NvSciStream attributes that are queryable.
Definition at line 82 of file nvscistream.h.
NvSciError NvSciStreamAttributeQuery | ( | NvSciStreamQueryableAttrib const | attr, |
int32_t *const | value | ||
) |
Queries NvSciStream attributes.
Queries the value of one of the queryable NvSciStream attributes.
Preconditions
None.
Actions
Postconditions
None changed.
[in] | attr | The attribute to query. |
[out] | value | The value queried. |
NvSciError NvSciStreamBlockConnect | ( | NvSciStreamBlock const | upstream, |
NvSciStreamBlock const | downstream | ||
) |
Connects two stream blocks.
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 fully connected when all inputs and outputs of all blocks in the stream have a connection.
Preconditions
Actions
Postconditions
[in] | upstream | Handle of the upstream block. |
[in] | downstream | Handle of the downstream block. |
NvSciError NvSciStreamBlockDelete | ( | NvSciStreamBlock const | block | ) |
Destroys a stream block.
Schedules a stream 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, and may be reassigned to a new block if more are created.
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
Postconditions
[in] | block | Block handle. |
NvSciError NvSciStreamBlockElementAccept | ( | NvSciStreamBlock const | block, |
NvSciStreamPacket const | handle, | ||
uint32_t const | index, | ||
NvSciError const | err | ||
) |
Accepts a packet element provided by the pool.
Upon receiving a PacketElement event, the producer and consumer should map the buffers 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
Actions
Postconditions
[in] | block | Producer or consumer block handle. |
[in] | handle | Packet handle. |
[in] | index | Index of the element within the packet. |
[in] | err | Status of mapping operation. |
NvSciError NvSciStreamBlockEventQuery | ( | NvSciStreamBlock const | block, |
int64_t const | timeoutUsec, | ||
NvSciStreamEvent *const | event | ||
) |
Queries for the next event from block's event queue, optionally waiting, and returns it to the caller.
The appropriate handling of each type of event is described in the section for the corresponding event structure.
Preconditions
Actions
Postconditions
[in] | block | Block handle. |
[in] | timeoutUsec | Timeout in microseconds (-1 to wait forever). |
[out] | event | Event and the corresponding event data. |
NvSciError_StreamInternalError An internal system error occurred, such as a mutex-locking failure.
On safety-critical systems, this function never generates this error. A system-wide mechanism shall be notified and intervene when such error occurs.
NvSciError NvSciStreamBlockPacketAccept | ( | NvSciStreamBlock const | block, |
NvSciStreamPacket const | handle, | ||
NvSciStreamCookie const | cookie, | ||
NvSciError const | err | ||
) |
Accepts a packet provided by the pool.
Upon receiving a PacketCreate event, the producer and consumer should set up their own internal data structures for the packet and assign a cookie 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 cookie assigned to the packet should be provided. NvSciStream will track the cookie 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
Actions
Postconditions
[in] | block | Producer or consumer block handle. |
[in] | handle | Packet handle. |
[in] | cookie | Block's cookie for the packet handle. |
[in] | err | Status of packet structure setup. |
NvSciError NvSciStreamBlockPacketAttr | ( | NvSciStreamBlock const | block, |
uint32_t const | index, | ||
uint32_t const | type, | ||
NvSciStreamElementMode const | syncMode, | ||
NvSciBufAttrList const | bufAttrList | ||
) |
Sets block packet requirements/capabilities.
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.
For safety-critical platforms, this function is called only once per packet element at setup time. The packet attributes are immutable during streaming.
For non-safety platforms, the producer may call it again during streaming to modify portions of the memory attributes, such as changing the dimensions or image format of some elements.
It may not modify the types of elements. The pool application is expected to respond by updating the complete packet attribute set, deleting the old packets, and creating new ones.
Preconditions
Actions
Postconditions
[in] | block | Block handle. |
[in] | index | Index of element within list |
[in] | type | User-defined type to identify element |
[in] | syncMode | Prefered access mode for element data |
[in] | bufAttrList | Attributes for element buffer |
NvSciError NvSciStreamBlockPacketElementCount | ( | NvSciStreamBlock const | block, |
uint32_t const | count | ||
) |
Block sets the number of elements in a packet.
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
Actions
Postconditions
[in] | block | The block handle. |
[in] | count | Number of elements per packet. |
NvSciError NvSciStreamBlockSyncObjCount | ( | NvSciStreamBlock const | block, |
uint32_t const | count | ||
) |
Provides block's number of sync objects.
Used with producer and consumer to pass the number of sync objects they will write into to the other endpoint(s).
The sync object count is implicitly set to one.
If the block provides no sync object, 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
Actions
Postconditions
None.
[in] | block | Block handle. |
[in] | count | Number of sync objects to be sent. |
NvSciError NvSciStreamBlockSyncObject | ( | NvSciStreamBlock const | block, |
uint32_t const | index, | ||
NvSciSyncObj const | syncObj | ||
) |
Provides block's sync object.
Used with producer and consumer to pass the sync objects they will write into to the other endpoint(s).
Preconditions
Actions
Postconditions
None.
[in] | block | Block handle. |
[in] | index | Index in list of sync objects |
[in] | syncObj | Handle of sync object |
NvSciError NvSciStreamBlockSyncRequirements | ( | NvSciStreamBlock const | block, |
bool const | synchronousOnly, | ||
NvSciSyncAttrList const | waitSyncAttrList | ||
) |
Sets block sync object requirements.
Used with producer and consumer to establish their requirements for sync objects provided by the other endpoint(s).
Preconditions
Actions
Postconditions
None.
[in] | block | Block handle. |
[in] | synchronousOnly | If true, endpoint cannot support sync objects |
[in] | waitSyncAttrList | Requirements for endpoint to wait for sync objects |
NvSciError NvSciStreamConsumerCreate | ( | NvSciStreamBlock const | queue, |
NvSciStreamBlock *const | consumer | ||
) |
Creates a stream consumer block.
Create a block for the consumer end of a stream. All streams require at least one consumer block. Consumer blocks must have a queue attached to feed them pending frames. Consumer blocks have one input connection and no output connections.
Once the stream is fully connected, this block can be used to retrieve producer requirements and finalize consumer settings.
Preconditions: None.
Actions:
Postconditions:
[in] | queue | The queue associated with the block. |
[out] | consumer | Handle for new consumer block. |
NvSciError NvSciStreamConsumerPacketAcquire | ( | NvSciStreamBlock const | consumer, |
NvSciStreamCookie *const | cookie, | ||
NvSciSyncFence *const | prefences | ||
) |
Instructs the consumer to get a packet from the queue.
If a packet is available for reading, this function will retrieve it from the queue and assign it to the consumer.
The consumer may hold multiple packets for reading, and is not required to return them in the order they were obtained.
Preconditions
Actions
Postconditions
[in] | consumer | Consumer block handle. |
[out] | cookie | Cookie identifying packet. |
[out] | prefences | Array of fences to wait for before using the packet. Must be at least large enough to hold one fence for each sync object created by the producer. If the sync object count is zero, may be NULL. |
NvSciError_StreamInternalError An internal system error occurred, such as a mutex-locking failure.
On safety-critical systems, this function never generates this error. A system-wide mechanism shall be notified and intervene when such error occurs.
NvSciError NvSciStreamConsumerPacketRelease | ( | NvSciStreamBlock const | consumer, |
NvSciStreamPacket const | handle, | ||
NvSciSyncFence const *const | postfences | ||
) |
Returns a data packet to the stream.
Instructs the consumer to return a used data packet to the stream, where it will be sent to the producer for reuse.
Preconditions
Actions
Postconditions
[in] | consumer | Consumer block handle. |
[in] | handle | Packet handle. |
[in] | postfences | A pointer to list of postfences for the data. The postfences in the array should be in the order according to the indices specified in NvSciStreamSyncDesc. |
That is, if the sync object is set with index == 1, its fence should be the 2nd element in the postfences array.
NvSciError_StreamInternalError An internal system error occurred, such as a mutex-locking failure.
On safety-critical systems, this function never generates this error. A system-wide mechanism shall be notified and intervene when such error occurs.
NvSciError NvSciStreamFifoQueueCreate | ( | NvSciStreamBlock *const | queue | ) |
Creates a FIFO queue block.
Create a block for tracking the list of packets available to be acquired. 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
Postconditions
[out] | queue | Handle for the new queue block. |
NvSciError NvSciStreamIpcDstCreate | ( | NvSciIpcEndpoint const | ipcEndpoint, |
NvSciSyncModule const | syncModule, | ||
NvSciBufModule const | bufModule, | ||
NvSciStreamBlock *const | ipc | ||
) |
Creates an IPC destination block.
Creates the downstream half of an IPC block pair which allows packets to be transmitted between processes.
IPC destination blocks have one output connection and no input connection.
An IPC destination block connects to upstream through the ipcEndpoint used to create the block.
Preconditions
None.
Actions
Postconditions
[in] | ipcEndpoint | IPC endpoint handle. |
[in] | syncModule | NvSciSyncModule that is used to import a NvSciSyncAttrList across an IPC / IVC boundary. |
This must be same module that was used to create NvSciSyncAttrList when specifying the associated NvSciStreamSyncAttr object.
[in] | bufModule | NvSciBufModule that is used to import a NvSciBufAttrList across an IPC / IVC boundary. |
This must be same module that was used to create NvSciBufAttrList when specifying the associated NvSciStreamElementAttr object.
[out] | ipc | Handle for new NvSciStream IPC destination block. |
NvSciError NvSciStreamIpcSrcCreate | ( | NvSciIpcEndpoint const | ipcEndpoint, |
NvSciSyncModule const | syncModule, | ||
NvSciBufModule const | bufModule, | ||
NvSciStreamBlock *const | ipc | ||
) |
Creates an IPC source block.
Creates the upstream half of an IPC block pair which allows packets to be transmitted between processes.
IPC source blocks have one input connection and no output connection.
A IPC source block connects to downstream through the ipcEndpoint used to create the block.
Preconditions
None.
Actions
Postconditions
[in] | ipcEndpoint | IPC endpoint handle. |
[in] | syncModule | NvSciSyncModule that is used to import a NvSciSyncAttrList across an IPC / IVC boundary. |
This must be same module that was used to create NvSciSyncAttrList when specifying the associated NvSciStreamSyncAttr object.
[in] | bufModule | NvSciBufModule that is used to import a NvSciBufAttrList across an IPC / IVC boundary. |
This must be same module that was used to create NvSciBufAttrList when specifying the associated NvSciStreamElementAttr object.
[out] | ipc | Handle for the new NvSciStream IPC source block. |
NvSciError NvSciStreamMailboxQueueCreate | ( | NvSciStreamBlock *const | queue | ) |
Creates a mailbox queue block.
Create a block for tracking the next packet available to be acquired. 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
Postconditions
[out] | queue | Handle for new queue block. |
NvSciError NvSciStreamMulticastCreate | ( | uint32_t const | outputCount, |
NvSciStreamBlock *const | multicast | ||
) |
Creates a multicast block.
Create 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
Postconditions
[in] | outputCount | number of output blocks that will be connected. |
[out] | multicast | Handle for the new multicast block. |
NvSciError NvSciStreamPoolPacketCreate | ( | NvSciStreamBlock const | pool, |
NvSciStreamCookie const | cookie, | ||
NvSciStreamPacket *const | handle | ||
) |
Adds a new packet to the pool.
Creates a new packet for the pool to make available to the producer. The description should contain the pool's cookie for the new packet.
Preconditions
Actions
Postconditions
[in] | pool | Pool block handle. |
[in] | cookie | Pool's cookie for the packet. |
[out] | handle | New handle assigned to the packet. |
NvSciError NvSciStreamPoolPacketDelete | ( | NvSciStreamBlock const | pool, |
NvSciStreamPacket const | handle | ||
) |
Removes a packet from the pool.
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.
Note: This will not be supported in the safety-certified driver. It is only to support non-safety cases where buffers can be added and removed at any time.
Preconditions
Actions
Postconditions
[in] | pool | Pool block handle. |
[in] | handle | Packet handle. |
NvSciError NvSciStreamPoolPacketInsertBuffer | ( | NvSciStreamBlock const | pool, |
NvSciStreamPacket const | handle, | ||
uint32_t const | index, | ||
NvSciBufObj const | bufObj | ||
) |
Registers a buffer to the packet.
Preconditions
Actions
Postconditions
[in] | pool | Pool block handle. |
[in] | handle | Packet handle. |
[in] | index | Index of element within packet. |
[in] | bufObj | Handle of buffer for element. |
NvSciError NvSciStreamProducerCreate | ( | NvSciStreamBlock const | pool, |
NvSciStreamBlock *const | producer | ||
) |
Creates a stream producer block.
Create a block for the producer end of a stream. All streams require one producer block. Producer blocks must have a pool attached to feed them their buffers. Producer blocks have one output connection and no input connections.
Once the stream is fully connected, this block can be used to retrieve consumer requirements and finalize producer settings.
Preconditions: None.
Actions:
Postconditions:
[in] | pool | The pool associated with the block. |
[out] | producer | Handle for new producer block. |
NvSciError NvSciStreamProducerPacketGet | ( | NvSciStreamBlock const | producer, |
NvSciStreamCookie *const | cookie, | ||
NvSciSyncFence *const | prefences | ||
) |
Instructs the producer to get a packet from the pool.
If a packet is available for writing, 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
Actions
Postconditions
[in] | producer | Producer block handle. |
[out] | cookie | Cookie identifying packet. |
[out] | prefences | Array of fences to wait for before using the packet. Must be at least large enough to hold one fence for each sync object created by the consumer. If the sync object count is zero, may be NULL. |
NvSciError_StreamInternalError An internal system error occurred, such as a mutex-locking failure.
On safety-critical systems, this function never generates this error. A system-wide mechanism shall be notified and intervene when such error occurs.
NvSciError NvSciStreamProducerPacketPresent | ( | NvSciStreamBlock const | producer, |
NvSciStreamPacket const | handle, | ||
NvSciSyncFence const *const | postfences | ||
) |
Inserts a data packet into the stream.
Instructs the producer to insert a completed data packet into the stream, where it will be sent to the consumer(s) for acquisition.
Preconditions
Actions
Postconditions
[in] | producer | Producer block handle. |
[in] | handle | Packet handle. |
[in] | postfences | A pointer to array of postfences for the data. The postfences in the array should be in the order according to the indices specified in NvSciStreamSyncDesc. That is, if the sync object is set with index == 1, its fence should be the 2nd element in the postfences array. |
NvSciError_StreamInternalError An internal system error occurred, such as a mutex-locking failure.
On safety-critical systems, this function never generates this error. A system-wide mechanism shall be notified and intervene when such error occurs.
NvSciError NvSciStreamStaticPoolCreate | ( | uint32_t const | numPackets, |
NvSciStreamBlock *const | pool | ||
) |
Creates a static stream pool block.
Create 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 fully defined before streaming begins, and is intended for safety-certified usage.
Once the stream is fully connected and the application (which may or may not be the same as the producer application) has determined the packet requirements, this block can be used to bind memory buffers to each packet.
Preconditions
None.
Actions
Postconditions
[in] | numPackets | Number of packets. |
[out] | pool | Handle for the new pool block. |
|
static |
|
static |