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.
Regarding Inter-VM and Inter-Process backend usecase on QNX OS, if client user tries to use receiving and sending thread separately for same endpoint handle, event blocking OS API (i.e. MsgReceivePulse) shall be used in either single thread in order to get remote notification. Once remote notification is arrived to one thread, that should be forwared to the other thread through any OS synchronization method (i.e. sem_post, pthread_cond_signal or MsgSendPulse etc.) Mostly, using single thread is recommended to handle both TX and RX data.
Before using any read/write APIs, user shall check if NV_SCI_IPC_EVENT_READ or NV_SCI_IPC_EVENT_WRITE event is available through NvSciIpcGetEvent(). NvSciIpcGetEvent() has function to establish connection between two endpoint S/W entities.
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 |
| 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... | |
| 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... | |
| NvSciError | NvSciIpcSetQnxPulseParam (NvSciIpcEndpoint handle, int32_t coid, int16_t pulsePriority, int16_t pulseCode, void *pulseValue) |
| Sets the event pulse parameters for QNX. More... | |
| #define NV_SCI_IPC_EVENT_CONN_EST 4U |
Specifies the IPC connection established event.
Definition at line 107 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_CONN_EST_ALL |
Specifies single event mask to check IPC connection establishment.
Definition at line 111 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_CONN_RESET 8U |
Specifies the IPC connection reset event.
Definition at line 109 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_READ 1U |
Specifies the IPC read event.
Definition at line 103 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_WRITE 2U |
Specifies the IPC write event.
Definition at line 105 of file nvsciipc.h.
| #define NVSCIIPC_MAX_ENDPOINT_NAME 64U |
Specifies maximum Endpoint name length including null terminator.
Definition at line 99 of file nvsciipc.h.
| typedef uint64_t NvSciIpcEndpoint |
Handle to the NvSciIpc endpoint.
Definition at line 84 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 | 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 | 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. |
| 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. (i.e. QNX: MsgReceivePulse_r(), LINUX: select(), epoll() etc.)
| [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. |
| 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.
| 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] | endpoint | The name of the NvSciIpc endpoint to open. |
| [out] | handle | A handle to the endpoint on success. |
| 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. |
| 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 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.
| [in] | handle | The handle to the endpoint to read from. |
| 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 same endpoint handle. Once read frame is released by NvSciIpcReadAdvance(), Do not use previously returned pointer of NvSciIpcReadGetNextFrame() since it's already invalid. Do not write through returned pointer of NvSciIpcReadGetNextFrame(). Do not read same memory location in multiple times. If required, copy specific memory location to 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. |
| 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 shall be done repeatedly to get event type that endpoint wants.
| [in] | handle | A handle to the endpoint to reset. |
void | NvSciError NvSciIpcSetQnxPulseParam | ( | NvSciIpcEndpoint | handle, |
| int32_t | coid, | ||
| int16_t | pulsePriority, | ||
| int16_t | pulseCode, | ||
| void * | pulseValue | ||
| ) |
Sets the event pulse parameters for QNX.
This API is specific to QNX OS. When a notification from a peer endpoint is available, the NvSciIpc library sends a pulse message to the application. This API is to connect coid to the endpoint, plug OS event notification and set pulse parameters (pulsePriority, pulseCode and pulseValue), thereby enabling the application to receive peer notifications from the NvSciIpc library. An application can receive notifications from a peer endpoint using MsgReceivePulse_r() which is blocking call.
Prior to calling this function, both ChannelCreate_r() and ConnectAttach_r() must be called in the application to obtain the value for coid to pass to this function.
To use the priority of the calling thread, set pulsePriority to SIGEV_PULSE_PRIO_INHERIT(-1). The priority must fall within the valid range, which can be determined by calling sched_get_priority_min() and sched_get_priority_max().
Applications can define any value per endpoint for pulseCode and pulseValue. pulseCode will be used by NvSciIpc to signal IPC events and should be reserved for this purpose by the application. pulseValue can be used for the application cookie data.
| [in] | handle | NvSciIpc endpoint handle. |
| [in] | coid | The connection ID created from calling ConnectAttach_r(). |
| [in] | pulsePriority | The value for pulse priority. |
| [in] | pulseCode | The 8-bit positive pulse code specified by the user. The values must be between _PULSE_CODE_MINAVAIL and _PULSE_CODE_MAXAVAIL |
| [in] | pulseValue | A pointer to the user-defined pulse value. |
| 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. |
| 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.
| [in] | handle | The handle to the endpoint to write to. |
| 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 same endpoint handle. Once transmit message is committed by NvSciIpcWriteAdvance(), Do not use previously returned pointer of NvSciIpcWriteGetNextFrame() since it's already invalid.
| [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. |