NVIDIA DRIVE OS Linux SDK API Reference5.1.6.0 Release |
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 | NvSciStreamElementAttr |
Defines attributes of a packet element. More... | |
struct | NvSciStreamElementDesc |
Structure representing a packet element. More... | |
struct | NvSciStreamPayload |
Defines a "frame" of data sent to the consumer or returned to the producer. More... | |
struct | NvSciStreamSyncAttr |
Defines the requirements for an endpoint to be able to read sync objects provided by the other endpoint. More... | |
struct | NvSciStreamSyncDesc |
Describes a single sync object that will be sent to or received from the other endpoint. More... | |
struct | NvSciStreamEvent |
Describes a component event. More... | |
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... | |
typedef uintptr_t NvSciStreamBlock |
Handle to a stream component.
Definition at line 49 of file nvscistream.h.
typedef uintptr_t NvSciStreamCookie |
Component-assigned cookie for a packet.
Definition at line 55 of file nvscistream.h.
typedef uintptr_t NvSciStreamPacket |
NvSciStream-assigned handle for a packet.
Definition at line 52 of file nvscistream.h.
Defines packet element access modes.
Definition at line 66 of file nvscistream.h.
enum NvSciStreamEventType |
Defines component event types.
Definition at line 175 of file nvscistream.h.
Defines NvSciStream attributes that are queryable.
Enumerator | |
---|---|
NvSciStreamQueryableAttrib_MaxElements |
Maximum number of elements allowed per packet. |
NvSciStreamQueryableAttrib_MaxSyncObj |
Maximum number of NvSciSync objects allowed. |
Definition at line 58 of file nvscistream.h.
NvSciError NvSciStreamAttributeQuery | ( | NvSciStreamQueryableAttrib | attr, |
int32_t * | value | ||
) |
Queries NvSciStream attributes.
Queries the value of one of the queryable NvSciStream attributes.
Preconditions
None.
Actions
NvSciStream looks up the value of the attribute.
Postconditions
None changed.
[in] | attr | The attribute to query. |
[out] | value | The value queried. |
NvSciError NvSciStreamBlockConnect | ( | NvSciStreamBlock | upstream, |
NvSciStreamBlock | 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
Establish a connection between the two blocks.
Postconditions
[in] | upstream | Handle of the upstream block. |
[in] | downstream | Handle of the downstream block. |
NvSciError NvSciStreamBlockDelete | ( | NvSciStreamBlock | block | ) |
Destroys a stream block.
Schedules a stream block for destruction, disconnecting the stream if this hadn'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 | block, |
NvSciStreamPacket | handle, | ||
uint32_t | index, | ||
NvSciError | 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. Upon success or failure, they should then call 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 | block, |
int64_t | timeoutUsec, | ||
NvSciStreamEvent * | event | ||
) |
Queries for the next event from block's event queue.
Gets the next event off of a 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
The block to query has been created.
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 | block, |
NvSciStreamPacket | handle, | ||
NvSciStreamCookie | cookie, | ||
NvSciError | 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 handle. |
[in] | err | Status of packet structure setup. |
NvSciError NvSciStreamBlockPacketAttr | ( | NvSciStreamBlock | block, |
const NvSciStreamElementAttr * | attr | ||
) |
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] | attr | Attributes for a packet element. |
NvSciError NvSciStreamBlockPacketElementCount | ( | NvSciStreamBlock | block, |
uint32_t | 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 | block, |
uint32_t | 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 | block, |
const NvSciStreamSyncDesc * | sync | ||
) |
Provides block's sync objects.
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] | sync | Sync description. |
NvSciError NvSciStreamBlockSyncRequirements | ( | NvSciStreamBlock | block, |
const NvSciStreamSyncAttr * | attr | ||
) |
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] | attr | Sync attributes. |
NvSciError NvSciStreamConsumerCreate | ( | NvSciStreamBlock | queue, |
NvSciStreamBlock * | 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 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.
Postconditions:
[in] | queue | The queue associated with the block. |
[out] | consumer | Handle for new consumer block. |
NvSciError NvSciStreamConsumerPacketAcquire | ( | NvSciStreamBlock | consumer, |
NvSciStreamPayload * | payload | ||
) |
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] | payload | Application-provided struct, packet cookie and prefences will be filled by the function. |
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 | consumer, |
NvSciStreamPacket | handle, | ||
NvSciSyncFence * | 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 * | 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 | ipcEndpoint, |
NvSciSyncModule | syncModule, | ||
NvSciBufModule | bufModule, | ||
NvSciStreamBlock * | 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 | NvSciSync Module 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 | ipcEndpoint, |
NvSciSyncModule | syncModule, | ||
NvSciBufModule | bufModule, | ||
NvSciStreamBlock * | 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 | NvSciSync Module 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 * | 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 NvSciStreamPoolPacketCreate | ( | NvSciStreamBlock | pool, |
NvSciStreamCookie | cookie, | ||
NvSciStreamPacket * | 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
The application can register buffers to the created packet.
[in] | pool | Pool block handle. |
[in] | cookie | Pool's cookie for the packet. |
[out] | handle | New handle assigned to the packet. |
NvSciError NvSciStreamPoolPacketDelete | ( | NvSciStreamBlock | pool, |
NvSciStreamPacket | 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 | pool, |
const NvSciStreamElementDesc * | desc | ||
) |
Registers a buffer to the packet.
Preconditions
Actions
Postconditions
When the last buffer is added to the packet, a PacketCreate and PacketElement event (one per packet element) will be sent to producer and consumer.
[in] | pool | Pool block handle. |
[in] | desc | Element description in which index, packet handle, and buffer handle are filled by application. |
NvSciError NvSciStreamProducerCreate | ( | NvSciStreamBlock | pool, |
NvSciStreamBlock * | 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.
Postconditions:
[in] | pool | The pool associated with the block. |
[out] | producer | Handle for new producer block. |
NvSciError NvSciStreamProducerPacketGet | ( | NvSciStreamBlock | producer, |
NvSciStreamPayload * | payload | ||
) |
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] | payload | Packet cookie and prefences. |
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 | producer, |
NvSciStreamPacket | handle, | ||
NvSciSyncFence * | 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 | numPackets, |
NvSciStreamBlock * | 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 producer 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. |