NVIDIA DRIVE OS Linux SDK API Reference

5.1.6.0 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Streaming APIs

Detailed Description

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...
 

Enumerations

enum  NvSciStreamQueryableAttrib {
  NvSciStreamQueryableAttrib_MaxElements,
  NvSciStreamQueryableAttrib_MaxSyncObj
}
 Defines NvSciStream attributes that are queryable. More...
 
enum  NvSciStreamElementMode {
  NvSciStreamElementMode_Asynchronous,
  NvSciStreamElementMode_Immediate
}
 Defines packet element access modes. More...
 
enum  NvSciStreamEventType {
  NvSciStreamEventType_ConnectDownstream,
  NvSciStreamEventType_ConnectUpstream,
  NvSciStreamEventType_SyncAttr,
  NvSciStreamEventType_SyncCount,
  NvSciStreamEventType_SyncDesc,
  NvSciStreamEventType_PacketElementCountProducer,
  NvSciStreamEventType_PacketElementCountConsumer,
  NvSciStreamEventType_PacketElementCount,
  NvSciStreamEventType_PacketAttrProducer,
  NvSciStreamEventType_PacketAttrConsumer,
  NvSciStreamEventType_PacketAttr,
  NvSciStreamEventType_PacketCreate,
  NvSciStreamEventType_PacketElement,
  NvSciStreamEventType_PacketDelete,
  NvSciStreamEventType_PacketStatusProducer,
  NvSciStreamEventType_PacketStatusConsumer,
  NvSciStreamEventType_ElementStatusProducer,
  NvSciStreamEventType_ElementStatusConsumer,
  NvSciStreamEventType_PacketReady,
  NvSciStreamEventType_DisconnectDownstream,
  NvSciStreamEventType_DisconnectUpstream
}
 Defines component event types. More...
 

Functions

NvSciError NvSciStreamBlockConnect (NvSciStreamBlock upstream, NvSciStreamBlock downstream)
 Connects two stream blocks. More...
 
NvSciError NvSciStreamProducerCreate (NvSciStreamBlock pool, NvSciStreamBlock *producer)
 Creates a stream producer block. More...
 
NvSciError NvSciStreamConsumerCreate (NvSciStreamBlock queue, NvSciStreamBlock *consumer)
 Creates a stream consumer block. More...
 
NvSciError NvSciStreamStaticPoolCreate (uint32_t numPackets, NvSciStreamBlock *pool)
 Creates a static stream pool block. More...
 
NvSciError NvSciStreamMailboxQueueCreate (NvSciStreamBlock *queue)
 Creates a mailbox queue block. More...
 
NvSciError NvSciStreamFifoQueueCreate (NvSciStreamBlock *queue)
 Creates a FIFO queue block. More...
 
NvSciError NvSciStreamIpcSrcCreate (NvSciIpcEndpoint ipcEndpoint, NvSciSyncModule syncModule, NvSciBufModule bufModule, NvSciStreamBlock *ipc)
 Creates an IPC source block. More...
 
NvSciError NvSciStreamIpcDstCreate (NvSciIpcEndpoint ipcEndpoint, NvSciSyncModule syncModule, NvSciBufModule bufModule, NvSciStreamBlock *ipc)
 Creates an IPC destination block. More...
 
NvSciError NvSciStreamBlockEventQuery (NvSciStreamBlock block, int64_t timeoutUsec, NvSciStreamEvent *event)
 Queries for the next event from block's event queue. More...
 
NvSciError NvSciStreamBlockSyncRequirements (NvSciStreamBlock block, const NvSciStreamSyncAttr *attr)
 Sets block sync object requirements. More...
 
NvSciError NvSciStreamBlockSyncObjCount (NvSciStreamBlock block, uint32_t count)
 Provides block's number of sync objects. More...
 
NvSciError NvSciStreamBlockSyncObject (NvSciStreamBlock block, const NvSciStreamSyncDesc *sync)
 Provides block's sync objects. More...
 
NvSciError NvSciStreamBlockPacketElementCount (NvSciStreamBlock block, uint32_t count)
 Block sets the number of elements in a packet. More...
 
NvSciError NvSciStreamBlockPacketAttr (NvSciStreamBlock block, const NvSciStreamElementAttr *attr)
 Sets block packet requirements/capabilities. More...
 
NvSciError NvSciStreamPoolPacketCreate (NvSciStreamBlock pool, NvSciStreamCookie cookie, NvSciStreamPacket *handle)
 Adds a new packet to the pool. More...
 
NvSciError NvSciStreamPoolPacketInsertBuffer (NvSciStreamBlock pool, const NvSciStreamElementDesc *desc)
 Registers a buffer to the packet. More...
 
NvSciError NvSciStreamPoolPacketDelete (NvSciStreamBlock pool, NvSciStreamPacket handle)
 Removes a packet from the pool. More...
 
NvSciError NvSciStreamBlockPacketAccept (NvSciStreamBlock block, NvSciStreamPacket handle, NvSciStreamCookie cookie, NvSciError err)
 Accepts a packet provided by the pool. More...
 
NvSciError NvSciStreamBlockElementAccept (NvSciStreamBlock block, NvSciStreamPacket handle, uint32_t index, NvSciError err)
 Accepts a packet element provided by the pool. More...
 
NvSciError NvSciStreamProducerPacketGet (NvSciStreamBlock producer, NvSciStreamPayload *payload)
 Instructs the producer to get a packet from the pool. More...
 
NvSciError NvSciStreamProducerPacketPresent (NvSciStreamBlock producer, NvSciStreamPacket handle, NvSciSyncFence *postfences)
 Inserts a data packet into the stream. More...
 
NvSciError NvSciStreamConsumerPacketAcquire (NvSciStreamBlock consumer, NvSciStreamPayload *payload)
 Instructs the consumer to get a packet from the queue. More...
 
NvSciError NvSciStreamConsumerPacketRelease (NvSciStreamBlock consumer, NvSciStreamPacket handle, NvSciSyncFence *postfences)
 Returns a data packet to the stream. More...
 
NvSciError NvSciStreamBlockDelete (NvSciStreamBlock block)
 Destroys a stream block. More...
 
NvSciError NvSciStreamAttributeQuery (NvSciStreamQueryableAttrib attr, int32_t *value)
 Queries NvSciStream attributes. More...
 

Typedef Documentation

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.

Enumeration Type Documentation

Defines packet element access modes.

Enumerator
NvSciStreamElementMode_Asynchronous 

Written asynchronously, typically by hardware engine.

Requires waiting for associated syncpoints before reading.

NvSciStreamElementMode_Immediate 

Written synchronously, typically by CPU.

Available for reading immediately.

Definition at line 66 of file nvscistream.h.

Defines component event types.

Enumerator
NvSciStreamEventType_ConnectDownstream 

Indicates complete downstream connection to consumer.

NvSciStreamEventType_ConnectUpstream 

Indicates complete upstream connection to producer.

NvSciStreamEventType_SyncAttr 

Specifies sync object requirements.

NvSciStreamEventType_SyncCount 

Specifies the number of sync objects sent from the opposite endpoint.

NvSciStreamEventType_SyncDesc 

Specifies a sync object sent from the opposite endpoint.

NvSciStreamEventType_PacketElementCountProducer 

Specifies number of packets elements request from producer.

NvSciStreamEventType_PacketElementCountConsumer 

Specifies number of packets elements requirement from consumer.

NvSciStreamEventType_PacketElementCount 

Specifies the number of packet elements determined by pool.

NvSciStreamEventType_PacketAttrProducer 

Specifies the packet capabilities from producer.

NvSciStreamEventType_PacketAttrConsumer 

Specifies the packet requests from consumer.

NvSciStreamEventType_PacketAttr 

Specifies the packet final settings from pool.

NvSciStreamEventType_PacketCreate 

Specifies the new packet object.

NvSciStreamEventType_PacketElement 

Specifies the new packet element.

NvSciStreamEventType_PacketDelete 

Specifies the discontinued packet object.

NvSciStreamEventType_PacketStatusProducer 

Specifies the status of packet.

NvSciStreamEventType_PacketStatusConsumer 

Specifies the status of packet.

NvSciStreamEventType_ElementStatusProducer 

Specifies the status of element.

NvSciStreamEventType_ElementStatusConsumer 

Specifies the status of element.

NvSciStreamEventType_PacketReady 

Specifies the packet available for reuse or acquire.

NvSciStreamEventType_DisconnectDownstream 

Indicates a downstream component has been destroyed.

NvSciStreamEventType_DisconnectUpstream 

Indicates an upstream component has been destroyed.

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.

Function Documentation

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.

Parameters
[in]attrThe attribute to query.
[out]valueThe value queried.
Returns
NvSciError, the completion code of this operation.
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

  • 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 the block has a complete chain of connections to the producer, it will receive a ConnectUpstream event.
  • When the block has a complete chain of connections to all consumers, it will receive a ConnectDownstream event.
Parameters
[in]upstreamHandle of the upstream block.
[in]downstreamHandle of the downstream block.
Returns
NvSciError, the completion code of this operation.
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

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

Postconditions

  • The block handle is no longer valid.
Parameters
[in]blockBlock handle.
Returns
NvSciError, the completion code of this operation.
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

  • The packet handle has been received in a previous PacketCreate event, and the indexed element has been received in a previous PacketElement event.

Actions

  • Sends a ElementStatus event to the pool.

Postconditions

  • If successful, the element buffers may now be used to send/receive data.
Parameters
[in]blockProducer or consumer block handle.
[in]handlePacket handle.
[in]indexIndex of the element within the packet.
[in]errStatus of mapping operation.
Returns
status code
  • NvSciError_Success: Element successfully mapped.
  • NvSciError_BadParameter: block refers to an invalid instance, or handle does not match any packet in the block, or index is not valid.
  • NvSciError_NotImplemented: block is not a producer or consumer block.
  • NvSciError_StreamNotConnected: Stream is not fully connected.
  • NvSciError_NotPermitted: block is in safety mode. Operation not allowed.
  • NvSciError_InvalidState: Packet is not in a state to be accepted (already accepted).
  • NvSciError_InsufficientMemory: Memory not enough for allocation or for ipc-related operations.
  • NvSciError_StreamInternalError: An internal system error occurred, such as a mutex-locking failure.
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

  • If no event pending on the block, wait for the timeout period.
  • Remove the next event (if any) from the block's event queue, fill in the event data structure, and update the event file descriptor if there are no more events pending.

Postconditions

  • As defined for each event type, dequeuing an event may allow other operations on the block to proceed.
Parameters
[in]blockBlock handle.
[in]timeoutUsecTimeout in microseconds (-1 to wait forever).
[out]eventEvent and the corresponding event data.
Returns
NvSciError, the completion code of this operation.
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

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

Actions

  • Sends a PacketStatus event to the pool.

Postconditions

  • If successful, the packet elements may now be received. data.
Parameters
[in]blockProducer or consumer block handle.
[in]handlePacket handle.
[in]cookieBlock's cookie for the handle.
[in]errStatus of packet structure setup.
Returns
NvSciError, the completion code of this operation.
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

  • For producer and consumer, must have received appropriate Connect event from the other endpoint(s).
  • For pool, must have received PacketAttrProducer and PacketAttrConsumer events.
  • If element count is already set to zero by NvSciStreamBlockPacketElementCount, this call will fail.

Actions

  • Send packet attributes to block.
  • For producer when the attributes for the last element is sent, PacketAttrProducer events (one per element) and a PacketElementCountProducer event will be sent to pool.
  • For consumer when the attributes for the last element is sent, PacketAttrConsumer events (one per element) and a PacketElementCountConsumer event will be sent to pool.
  • For pool, when the attributes for the last element is sent, PacketAttr events (one per element), and a PacketElementCount event will be sent to consumer and producer.

Postconditions

  • For the pool, packets may now be created.
Parameters
[in]blockBlock handle.
[in]attrAttributes for a packet element.
Returns
NvSciError, the completion code of this operation.
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

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

Actions

  • Send number of packet elements to block.

Postconditions

  • If the count is zero, a PacketElementCount* event will be sent to the other endpoint(s) immediately.
  • If the count is zero, for the pool, packets may now be created.
Parameters
[in]blockThe block handle.
[in]countNumber of elements per packet.
Returns
NvSciError, the completion code of this operation.
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

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

Actions

  • Send sync count to block. If count is zero, a SyncCount event will be sent to the other endpoint(s) immediately.

Postconditions

None.

Parameters
[in]blockBlock handle.
[in]countNumber of sync objects to be sent.
Returns
NvSciError, the completion code of this operation.
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

  • Block must have received SyncAttr event from the other endpoint(s).
  • If the sync count is already set to zero by NvSciStreamBlockSyncObjCount, this call will fail.

Actions

  • Send sync object to block.
  • One sync object results in one SyncDesc event. When the last sync object is provided, these SyncDesc events and a SyncCount event will be sent to the other endpoint(s).

Postconditions

None.

Parameters
[in]blockBlock handle.
[in]syncSync description.
Returns
NvSciError, the completion code of this operation.
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

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

Actions

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

Postconditions

None.

Parameters
[in]blockBlock handle.
[in]attrSync attributes.
Returns
NvSciError, the completion code of this operation.
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:

  • The block is ready to be connected to other stream blocks.
  • The block can be monitored for events.
Parameters
[in]queueThe queue associated with the block.
[out]consumerHandle for new consumer block.
Returns
NvSciError, the completion code of this operation.
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

  • The PacketReady event for the next packet in the queue has been handled.
  • On safety-certified platforms, all packets have been accepted by the producer and the consumer.

Actions

  • Retrieves an available packet and returns it to the caller.

Postconditions

  • The packet now resides in the list owned by the consumer.
Parameters
[in]consumerConsumer block handle.
[out]payloadApplication-provided struct, packet cookie and prefences will be filled by the function.
Returns
NvSciError, the completion code of this operation.
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

  • The referenced packet is owned by the consumer.

Actions

  • The packet is sent back upstream. Once released by all consumers:
    • It will be put in the pool where it can be obtained by the producer.
    • A PacketReady event will be sent to the producer.

Postconditions

  • The packet will eventually reside in the list owned by the pool.
Parameters
[in]consumerConsumer block handle.
[in]handlePacket handle.
[in]postfencesA 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.

Returns
NvSciError, the completion code of this operation.
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

  • Initialize a queue to manage waiting packets.

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[out]queueHandle for the new queue block.
Returns
NvSciError, the completion code of this operation.
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

  • Ready IPC endpoint.
  • Allocate buffers for data transmission.

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[in]ipcEndpointIPC endpoint handle.
[in]syncModuleNvSciSync 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.

Parameters
[in]bufModuleNvSciBufModule 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.

Parameters
[out]ipcHandle for new NvSciStream IPC destination block.
Returns
NvSciError, the completion code of this operation.
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

  • Ready IPC endpoint.
  • Allocate buffers for data transmission.

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[in]ipcEndpointIPC endpoint handle.
[in]syncModuleNvSciSync 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.

Parameters
[in]bufModuleNvSciBufModule 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.

Parameters
[out]ipcHandle for the new NvSciStream IPC source block.
Returns
NvSciError, the completion code of this operation.
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

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

Postconditions

  • The block is ready to be connected to other stream blocks.
Parameters
[out]queueHandle for new queue block.
Returns
NvSciError, the completion code of this operation.
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

  • Final packet attributes must have been specified for the pool.
  • For static pool, the number of packets already created has not reached the limit.

Actions

  • A new packet handle is assigned to the packet and returned to the the caller.
  • If the element count is set to zero, a PacketCreate event will be sent to the producer and the consumer.

Postconditions

The application can register buffers to the created packet.

Parameters
[in]poolPool block handle.
[in]cookiePool's cookie for the packet.
[out]handleNew handle assigned to the packet.
Returns
NvSciError, the completion code of this operation.
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

  • Specified packet must exist.

Actions

  • When the specified packet is returned to the pool, the pool releases resources associated with it and sends a PacketDelete event to the producer and consumer.

Postconditions

  • The packet may no longer be used for pool operations.
Parameters
[in]poolPool block handle.
[in]handlePacket handle.
Returns
NvSciError, the completion code of this operation.
NvSciError NvSciStreamPoolPacketInsertBuffer ( NvSciStreamBlock  pool,
const NvSciStreamElementDesc desc 
)

Registers a buffer to the packet.

Preconditions

  • The number of buffers already registered to the packet hasn't reached the number set by NvSciStreamBlockPacketElementCount.

Actions

  • The buffer is added to the packet.

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.

Parameters
[in]poolPool block handle.
[in]descElement description in which index, packet handle, and buffer handle are filled by application.
Returns
NvSciError, the completion code of this operation.
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:

  • The block is ready to be connected to other stream blocks.
  • The block can be monitored for events.
Parameters
[in]poolThe pool associated with the block.
[out]producerHandle for new producer block.
Returns
NvSciError, the completion code of this operation.
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

  • The PacketReady event for the next packet in the pool has been handled.
  • On safety-certified platforms, all packets have been accepted by the producer and the consumer.

Actions

  • Retrieves an available packet and returns it to the caller.

Postconditions

  • The packet now resides in the list owned by the producer.
Parameters
[in]producerProducer block handle.
[out]payloadPacket cookie and prefences.
Returns
NvSciError, the completion code of this operation.
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

  • The referenced packet is owned by the producer.

Actions

  • The packet is sent to the queue(s) where it will be held until acquired by the consumer or returned without acquisition.
  • If one is not already pending, a PacketReady event will be sent to each consumer.

Postconditions

  • The packet now resides in the list owned by the queue(s).
Parameters
[in]producerProducer block handle.
[in]handlePacket handle.
[in]postfencesA 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.
Returns
NvSciError, the completion code of this operation.
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

  • Allocate data structures to describe packets.
  • Initialize queue of available packets.

Postconditions

  • The block is ready to be connected to other stream blocks.
  • The block can be monitored for events.
Parameters
[in]numPacketsNumber of packets.
[out]poolHandle for the new pool block.
Returns
NvSciError, the completion code of this operation.