The NvSciIpc library provides interfaces for any two entities in a system to communicate with each other irrespective of where they are placed. Entities can be in:
Each of these different boundaries will be abstracted by a library providing unified communication (Read/Write) APIs to entities. The communication consists of two bi-directional send/receive queues.
When Init operation group APIs are used, the user should call them in the following order, with or without NvSciEventService.
Typical call flow with NvSciIpc library
1) Init mode
2) Runtime mode (loop)
3) De-Init mode
Typical call flow with NvSciIpc and NvSciEventService library
NvSciEventService provides APIs that replace OS-specific event-blocking API. They are only compatible with an endpoint which is opened with NvSciOpenEndpointWithEventService().
1) Init mode
2) Runtime mode (loop)
3) De-Init mode
Using multi-threading in NvSciIpc - QNX OS
For Inter-VM and Inter-Process backend applications on QNX OS, only a single event-blocking OS API (i.e. MsgReceivePulse_r(), NvSciEventLoopService::WaitForEvent()) is allowed per endpoint in the same process boundary. If a client application tries to use receiving and sending thread separately for the same endpoint handle, the event-blocking OS APIs must be used in a single thread in order to receive remote notification. Once a remote notification arrives in the thread, the notification should be forwarded to the other thread using the same endpoint handle through any OS synchronization method (e.g. sem_post, pthread_cond_signal or MsgSendPulse etc.) Single thread usage is recommended to handle both TX and RX data.
Configuring thread pool of resource manager - QNX OS
NvSciIpc resource manager (io-nvsciipc) and IVC resource manager (devv-nvivc) use thread pool to manage concurrent request from multiple NvSciIpc client processes using NvSciIpc library. io-nvsciipc is used during opening endpoint and devv-nvivc is used for Inter-VM IVC signaling. Drive OS users should evaluate thread pool capacity of io-nvsciipc and devv-nvivc then configure them with -t option in startup script. Thread pool capacity for NvSciIPC can be evaluated based on number of parallel outstanding NvSciIPC requests, at any point of time, that are expected in the system. Default value of thread pool capacity is 10.
Getting events before using Read/Write NvSciIpc API
Before using any Read/Write APIs, the user must check if NV_SCI_IPC_EVENT_READ or NV_SCI_IPC_EVENT_WRITE event is available through NvSciIpcGetEvent(). NvSciIpcGetEvent() has additional support to establish connection between two endpoint software entities.
When to use blocking API
Users of NvSciIpc must call OS event-blocking API to wait for an event when NvSciIpcGetEvent() does not return desired events. The following are OS event-blocking API examples:
If user process needs to wait for events from multiple remote NvSciIpc endpoint processes, use single blocking call from single thread instead of using blocking call per endpoint thread. This is recommended to improve performance by avoiding thread creation per endpoint. NvSciEventLoopService::WaitForMultipleEvents() blocking call is suitable for this use case.
How to check if peer endpoint entity receives a message
NvSciIpc library does not provide information about whether a peer endpoint entity receives all sent messages from a local endpoint entity. If such a mechanism is required, the client user should implement separate message acknowledgment in the application layer.
Recommended Read/Write APIs
Using NvSciIpcRead() and NvSciIpcWrite() is recommended rather than following Read/Write APIs. See detail constraints of API in each function description.
Provide valid buffer pointers
The user of NvSciIpc must provide valid buffer pointers to NvSciIpcRead(), NvSciIpcWrite() and other Read/Write NvSciIpc APIs as NvSciIpc library validation to these parameters is limited to a NULL pointer check.
Maximum number of endpoints
One NvSciIpc client process is allowed to open up to 50 endpoints. QNX OS safety manual imposes a restriction no process SHALL have more than 100 open channels without disabling kernel preemption. User client needs one channel/connection pair to receive an endpoint notification.
Data Structures | |
| struct | NvSciIpcEndpointInfo |
| Defines information about the NvSciIpc endpoint. More... | |
Macros | |
| #define | NVSCIIPC_MAX_ENDPOINT_NAME 64U |
| Specifies maximum Endpoint name length including null terminator. More... | |
| #define | NV_SCI_IPC_EVENT_READ 1U |
| Specifies the IPC read event. More... | |
| #define | NV_SCI_IPC_EVENT_WRITE 2U |
| Specifies the IPC write event. More... | |
| #define | NV_SCI_IPC_EVENT_CONN_EST 4U |
| Specifies the IPC connection established event. More... | |
| #define | NV_SCI_IPC_EVENT_CONN_RESET 8U |
| Specifies the IPC connection reset event. More... | |
| #define | NV_SCI_IPC_EVENT_CONN_EST_ALL (NV_SCI_IPC_EVENT_CONN_EST | NV_SCI_IPC_EVENT_WRITE | NV_SCI_IPC_EVENT_READ) |
| Specifies single event mask to check IPC connection establishment. More... | |
Typedefs | |
| typedef uint64_t | NvSciIpcEndpoint |
| Handle to the NvSciIpc endpoint. More... | |
Functions | |
| NvSciError | NvSciIpcInit (void) |
| Initializes the NvSciIpc library. More... | |
| void | NvSciIpcDeinit (void) |
| De-initializes the NvSciIpc library. More... | |
| NvSciError | NvSciIpcOpenEndpoint (const char *endpoint, NvSciIpcEndpoint *handle) |
| Opens an endpoint with the given name. More... | |
| NvSciError | NvSciIpcOpenEndpointWithEventService (const char *endpoint, NvSciIpcEndpoint *handle, NvSciEventService *eventService) |
| Opens an endpoint with the given name and event service. More... | |
| NvSciError | NvSciIpcGetEventNotifier (NvSciIpcEndpoint handle, NvSciEventNotifier **eventNotifier) |
| Get NvSciIpc event notifier. More... | |
| void | NvSciIpcCloseEndpoint (NvSciIpcEndpoint handle) |
| Closes an endpoint with the given handle. More... | |
| void | NvSciIpcResetEndpoint (NvSciIpcEndpoint handle) |
| Resets an endpoint. More... | |
| NvSciError | NvSciIpcRead (NvSciIpcEndpoint handle, void *buf, size_t size, int32_t *bytes) |
| Returns the contents of the next frame from an endpoint. More... | |
| NvSciError | NvSciIpcReadGetNextFrame (NvSciIpcEndpoint handle, const volatile void **buf) |
| Returns a pointer to the location of the next frame from an endpoint. More... | |
| NvSciError | NvSciIpcReadAdvance (NvSciIpcEndpoint handle) |
| Removes the next frame from an endpoint. More... | |
| NvSciError | NvSciIpcWrite (NvSciIpcEndpoint handle, const void *buf, size_t size, int32_t *bytes) |
| Writes a new frame to the endpoint. More... | |
| NvSciError | NvSciIpcWriteGetNextFrame (NvSciIpcEndpoint handle, volatile void **buf) |
| Returns a pointer to the location of the next frame for writing data. More... | |
| NvSciError | NvSciIpcWriteAdvance (NvSciIpcEndpoint handle) |
| Writes the next frame to the endpoint. More... | |
| NvSciError | NvSciIpcGetEndpointInfo (NvSciIpcEndpoint handle, struct NvSciIpcEndpointInfo *info) |
| Returns endpoint information. More... | |
| NvSciError | NvSciIpcGetLinuxEventFd (NvSciIpcEndpoint handle, int32_t *fd) |
| Returns the NvSciIpc file descriptor for a given endpoint. More... | |
| NvSciError | NvSciIpcGetEvent (NvSciIpcEndpoint handle, uint32_t *events) |
| Get Events. More... | |
| #define NV_SCI_IPC_EVENT_CONN_EST 4U |
Specifies the IPC connection established event.
Definition at line 246 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_CONN_EST_ALL (NV_SCI_IPC_EVENT_CONN_EST | NV_SCI_IPC_EVENT_WRITE | NV_SCI_IPC_EVENT_READ) |
Specifies single event mask to check IPC connection establishment.
Definition at line 250 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_CONN_RESET 8U |
Specifies the IPC connection reset event.
Definition at line 248 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_READ 1U |
Specifies the IPC read event.
Definition at line 242 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_WRITE 2U |
Specifies the IPC write event.
Definition at line 244 of file nvsciipc.h.
| #define NVSCIIPC_MAX_ENDPOINT_NAME 64U |
Specifies maximum Endpoint name length including null terminator.
Definition at line 238 of file nvsciipc.h.
| typedef uint64_t NvSciIpcEndpoint |
Handle to the NvSciIpc endpoint.
Definition at line 222 of file nvsciipc.h.
| void NvSciIpcCloseEndpoint | ( | NvSciIpcEndpoint | handle | ) |
Closes an endpoint with the given handle.
The function frees the NvSciIpc endpoint associated with the given handle.
| [in] | handle | A handle to the endpoint to close. |
void
Usage considerations
| void NvSciIpcDeinit | ( | void | ) |
De-initializes the NvSciIpc library.
This function cleans up the NvSciIpc endpoint internal database created by NvSciIpcInit(). Before calling this API, all existing opened endpoints must be closed by NvSciIpcCloseEndpoint().
void
Usage considerations
| NvSciError NvSciIpcGetEndpointInfo | ( | NvSciIpcEndpoint | handle, |
| struct NvSciIpcEndpointInfo * | info | ||
| ) |
Returns endpoint information.
| [in] | handle | NvSciIpc endpoint handle. |
| [out] | info | A pointer to NvSciIpcEndpointInfo object that this function copies the info to on success. |
Usage considerations
| NvSciError NvSciIpcGetEvent | ( | NvSciIpcEndpoint | handle, |
| uint32_t * | events | ||
| ) |
Get Events.
Returns a bitwise OR operation on new events that occurred since the last call to this function.
This function sets events to the result of a bitwise OR operation of zero or more NV_SCI_IPC_EVENT_* constants corresponding to all new events that have occurred on the endpoint since:
The parameter events is set to zero if no new events have occurred.
There are four types of events:
NV_SCI_IPC_EVENT_CONN_EST : IPC connection establishedNV_SCI_IPC_EVENT_WRITE : IPC writeNV_SCI_IPC_EVENT_READ : IPC readNV_SCI_IPC_EVENT_CONN_RESET : IPC connection resetThese may occur in arbitrary combinations, except for the following:
NV_SCI_IPC_EVENT_CONN_EST is always combined with NV_SCI_IPC_EVENT_WRITE.NV_SCI_IPC_EVENT_CONN_RESET cannot be combined with any other events.There are seven possible event combinations:
NV_SCI_IPC_EVENT_CONN_EST and NV_SCI_IPC_EVENT_WRITE NV_SCI_IPC_EVENT_CONN_EST and NV_SCI_IPC_EVENT_WRITE and NV_SCI_IPC_EVENT_READ NV_SCI_IPC_EVENT_READ NV_SCI_IPC_EVENT_WRITE NV_SCI_IPC_EVENT_WRITE and NV_SCI_IPC_EVENT_READ NV_SCI_IPC_EVENT_CONN_RESET An NV_SCI_IPC_EVENT_CONN_EST event occurs on an endpoint each time a connection is established through the endpoint (between the endpoint and the other end of the corresponding channel).
An NV_SCI_IPC_EVENT_WRITE event occurs on an endpoint:
NV_SCI_IPC_CONN_EST event.NvSciIpcWrite* call returned NvSciError_InsufficientMemory. Note however that an implementation is permitted to delay the delivery of this type of NV_SCI_IPC_EVENT_WRITE event, e.g., for purposes of improving throughput.An NV_SCI_IPC_EVENT_READ event occurs on an endpoint:
NV_SCI_IPC_EVENT_CONN_EST event, if frames can already be read as of delivery.NvSciRead* call returned NvSciError_InsufficientMemory. Note however that an implementation is permitted to delay the delivery of this type of NV_SCI_IPC_EVENT_READ event, e.g., for purposes of improving throughput.An NV_SCI_IPC_EVENT_CONN_RESET event occurs on an endpoint when the user calls NvSciIpcResetEndpoint.
If this function doesn't return desired events, user must call OS-provided blocking API to wait for notification from remote endpoint.
The following are blocking API examples:
In case of QNX OS, in order to authenticate user client process, NvSciIpc uses custom ability "NvSciIpcEndpoint". Use procmgr_ability_lookup() QNX OS API to get ability ID.
| [in] | handle | NvSciIpc endpoint handle. |
| [out] | events | A pointer to the variable into which to store the bitwise OR result of new events on success. |
Usage considerations
| NvSciError NvSciIpcGetEventNotifier | ( | NvSciIpcEndpoint | handle, |
| NvSciEventNotifier ** | eventNotifier | ||
| ) |
Get NvSciIpc event notifier.
This API is used to connect NvSciIpc event handling with OS-provided event interface. It also utilizes NvSciEventService infrastructure. Before calling NvSciIpcCloseEndpoint(), event notifier should be deleted through Delete callback of NvSciEventNotifier.
| [in] | handle | NvSciIpc endpoint handle. |
| [out] | eventNotifier | A pointer to NvSciEventNotifier object on success. |
Usage considerations
| NvSciError NvSciIpcGetLinuxEventFd | ( | NvSciIpcEndpoint | handle, |
| int32_t * | fd | ||
| ) |
Returns the NvSciIpc file descriptor for a given endpoint.
This API is specific to Linux OS. Event handle will be used to plug OS event notification (can be read, can be written, established, reset etc.)
| handle | NvSciIpc endpoint handle |
| fd | A pointer to the endpoint file descriptor. |
| NvSciError NvSciIpcInit | ( | void | ) |
Initializes the NvSciIpc library.
This function parses the NvSciIpc configuration file and creates an internal database of NvSciIpc endpoints that exist in a system.
Usage considerations
| NvSciError NvSciIpcOpenEndpoint | ( | const char * | endpoint, |
| NvSciIpcEndpoint * | handle | ||
| ) |
Opens an endpoint with the given name.
The function locates the NvSciIpc endpoint with the given name in the NvSciIpc configuration table in the internal database, and returns a handle to the endpoint if found. When the operation is successful, endpoint can utilize the allocated shared data area and the corresponding signaling mechanism setup. If the operation fails, the state of the NvSciIpc endpoint is undefined. In case of QNX OS, in order to authenticate user client process, NvSciIpc uses custom ability "NvSciIpcEndpoint". Use procmgr_ability_lookup() QNX OS API to get ability ID.
| [in] | endpoint | The name of the NvSciIpc endpoint to open. |
| [out] | handle | A handle to the endpoint on success. |
Usage considerations
| NvSciError NvSciIpcOpenEndpointWithEventService | ( | const char * | endpoint, |
| NvSciIpcEndpoint * | handle, | ||
| NvSciEventService * | eventService | ||
| ) |
Opens an endpoint with the given name and event service.
This API provides same functionality as NvSciIpcOpenEndpoint(). But, it requires additional event service abstract object as an input parameter to utilize NvSciEventService infrastructure. NvSciEventService can be created through NvSciEventLoopServiceCreate(). NvSciIpcGetEventNotifier() can be used only when this API is invoked successfully. In case of QNX OS, in order to authenticate user client process, NvSciIpc uses custom ability "NvSciIpcEndpoint". Use procmgr_ability_lookup() QNX OS API to get ability ID.
| [in] | endpoint | The name of the NvSciIpc endpoint to open. |
| [out] | handle | A handle to the endpoint on success. |
| [in] | eventService | An abstract object to use NvSciEventService infrastructure. |
Usage considerations
| NvSciError NvSciIpcRead | ( | NvSciIpcEndpoint | handle, |
| void * | buf, | ||
| size_t | size, | ||
| int32_t * | bytes | ||
| ) |
Returns the contents of the next frame from an endpoint.
This function removes the next frame and copies its contents into a buffer. If the destination buffer is smaller than the configured frame size of the endpoint, the trailing bytes are discarded.
This is a non-blocking call. Read channel of the endpoint must not be empty. If read channel of the endpoint was previously full, then the function notifies the remote endpoint.
This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint.
The user shall make sure if actual input buffer size is equal or bigger than requested size before using this API.
| [in] | handle | The handle to the endpoint to read from. |
| [out] | buf | A pointer to a destination buffer to receive the contents of the next frame. |
| [in] | size | The number of bytes to copy from the frame. If size is greater than the size of the destination buffer, the remaining bytes are discarded. |
| [out] | bytes | The number of bytes read on success. |
Usage considerations
| NvSciError NvSciIpcReadAdvance | ( | NvSciIpcEndpoint | handle | ) |
Removes the next frame from an endpoint.
This is a non-blocking call. Read channel of the endpoint must not be empty. If a read channel of the endpoint was previously full, then this function notifies the remote endpoint.
This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint.
Between NvSciIpcReadGetNextFrame() and NvSciIpcReadAdvance(), do not perform any other NvSciIpc read operations with the same endpoint handle. Once a read frame is released by NvSciIpcReadAdvance(), do not use previously returned pointer of NvSciIpcReadGetNextFrame() since it is already invalid.
| [in] | handle | The handle to the endpoint to read from. |
Usage considerations
| NvSciError NvSciIpcReadGetNextFrame | ( | NvSciIpcEndpoint | handle, |
| const volatile void ** | buf | ||
| ) |
Returns a pointer to the location of the next frame from an endpoint.
This is a non-blocking call. This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint. Between NvSciIpcReadGetNextFrame() and NvSciIpcReadAdvance(), do not perform any other NvSciIpc read operations with the same endpoint handle. Once a read frame is released by NvSciIpcReadAdvance(), do not use previously returned pointer of NvSciIpcReadGetNextFrame() since it is already invalid. Do not write through a returned pointer of NvSciIpcReadGetNextFrame(). This is protected by a const volatile pointer return type. Do not read the same memory location multiple times. If required, copy specific memory location to a local buffer before using it.
| [in] | handle | The handle to the endpoint to read from. |
| [out] | buf | A pointer to a destination buffer to receive the contents of the next frame on success. |
Usage considerations
| void NvSciIpcResetEndpoint | ( | NvSciIpcEndpoint | handle | ) |
Resets an endpoint.
Initiates a reset on the endpoint and notifies the remote endpoint. Applications must call this function and complete the reset operation before using the endpoint for communication. Once this API is called, all existing data in channel will be discarded. After invoking this function, client user shall call NvSciIpcGetEvent() to get specific event type (READ, WRITE etc.). if desired event is not returned from GetEvent API, OS-specific blocking call (select/poll/epoll or MsgReceivePulse) should be called to wait remote notification. This sequence must be done repeatedly to get event type that endpoint wants.
| [in] | handle | A handle to the endpoint to reset. |
void
Usage considerations
| NvSciError NvSciIpcWrite | ( | NvSciIpcEndpoint | handle, |
| const void * | buf, | ||
| size_t | size, | ||
| int32_t * | bytes | ||
| ) |
Writes a new frame to the endpoint.
If space is available in the endpoint, this function posts a new frame, copying the contents from the provided data buffer. If size is less than the frame size, then the remaining bytes of the frame are undefined.
This is a non-blocking call. If write channel of the endpoint was previously empty, then the function notifies the remote endpoint.
This operation cannot proceed if the endpoint is being reset.
The user shall make sure if actual input buffer size is equal or bigger than requested size before using this API.
| [in] | handle | The handle to the endpoint to write to. |
| [in] | buf | A pointer to a source buffer for the contents of the next frame. |
| [in] | size | The number of bytes to be copied to the frame, not to exceed the length of the destination buffer. |
| [out] | bytes | The number of bytes written on success. |
Usage considerations
| NvSciError NvSciIpcWriteAdvance | ( | NvSciIpcEndpoint | handle | ) |
Writes the next frame to the endpoint.
This is a non-blocking call. If write channel of the endpoint is not full, then post the next frame. If write channel of the endpoint was previously empty, then this function notifies the remote endpoint.
This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint.
Between NvSciIpcWriteGetNextFrame() and NvSciIpcWriteAdvance(), do not perform any other NvSciIpc write operations with the same endpoint handle. Once transmit message is committed by NvSciIpcWriteAdvance(), do not use previously returned pointer of NvSciIpcWriteGetNextFrame() since it is already invalid.
| [in] | handle | The handle to the endpoint to write to. |
Usage considerations
| NvSciError NvSciIpcWriteGetNextFrame | ( | NvSciIpcEndpoint | handle, |
| volatile void ** | buf | ||
| ) |
Returns a pointer to the location of the next frame for writing data.
This is a non-blocking call. write channel of the endpoint must not be full.
This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint. Between NvSciIpcWriteGetNextFrame() and NvSciIpcWriteAdvance(), do not perform any other NvSciIpc write operations with the same endpoint handle. Once a transmit message is committed by NvSciIpcWriteAdvance(), do not use previously returned pointer of NvSciIpcWriteGetNextFrame() since it is already invalid. Do not read through a returned pointer of NvSciIpcWriteGetNextFrame().
| [in] | handle | The handle to the endpoint to write to. |
| [out] | buf | A pointer to a destination buffer to hold the contents of the next frame on success. |
Usage considerations