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. NvSciIpcWaitEventQnx(), 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) uses thread pool to manage concurrent request from multiple NvSciIpc client processes using NvSciIpc library. io-nvsciipc is used during opening endpoint. Drive OS users should evaluate thread pool capacity of io-nvsciipc 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.
Checksum for data integrity
NvSciIpc does not provide checksum for data to be transferred or check for data integrity error. If such a mechanism is required, the client user should implement checksum processing routine for data.
Recommended Read/Write APIs
Using NvSciIpcReadSafe() and NvSciIpcWriteSafe() 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 NvSciIpcReadSafe(), NvSciIpcWriteSafe() 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 500 endpoints. QNX NvSciIpc opens two device nodes in opening endpoint. QNX OS kernel supports 1024 100 open channels without disabling kernel preemption. User client needs one channel/connection pair to receive an endpoint notification.
Concurrent read/write Client processes who want concurrent read and write operation on endpoints need to open two endpoints, one for read and the other for write operation. Read and write operation on different endpoint work exclusively without any external locking mechanism in multiple threads. Channel memory consumption will be doubled in using two endpoints.
Use ChannelCreatePulsePool() - QNX OS
In using legacy event handling (without NvSciEventService) on NvSciIpc, user has to create chid and coid using ChannelCreate_r() and ConnectAttach_r() before calling NvSciIpcSetQnxPulseParamSafe(). This ChannelCreate() uses global pulse message pool. If privileged and non-privileged processes use the same global pool, unprivileged processes can potentially interfere with privileged processes by receiving and not handling large numbers of pulses (thereby causing denial of service attack). So, ChannelCreatePulsePool() API is recommended to use fixed private pool of pulses instead of using ChannelCreate_r().
struct nto_channel_config { struct sigevent event; // initialize using SIGEV_SEM_INIT() macro unsigned num_pulses; // threshold to trigger semaphore event unsigned rearm_threshold; // 0 ~ num_pulses unsigned options; // _NTO_CHO_CUSTOM_EVENT unsigned reserved[3]; }
If you're experienced pulse pool shortage issue in normal operation, increase num_pulses by double of previous setting.
More information can be found in QNX OS manual page.
In order to detect IVC signalling storm, user needs to create separate thread to receive semaphore event which is set in nto_channel_config structure and call sem_wait() in that thread. NvSciIpcInspectEventQnx() API returns NvSciIpcEndpoint handle in which IVC signalling storm happens. User can decide post action (i.e. close endpoint, restart process, deinit NvSciIpc etc.) per system usecase scenario after detecting issue.
Regarding fork() - QNX OS safety build
NvSciIpc library depends on QNX_BSP::NvDVMS to check VM state restriction. Hence parent process should not use fork(). Instead, posix_spawn() should be used to spawn child process.
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 0x01U |
| Specifies the IPC read event. More... | |
| #define | NV_SCI_IPC_EVENT_WRITE 0x02U |
| Specifies the IPC write event. More... | |
| #define | NV_SCI_IPC_EVENT_CONN_EST 0x04U |
| Specifies the IPC connection established event. More... | |
| #define | NV_SCI_IPC_EVENT_CONN_RESET 0x08U |
| Specifies the IPC connection reset event. More... | |
| #define | NV_SCI_IPC_EVENT_WRITE_EMPTY 0x10U |
| Specifies the IPC write fifo empty event. More... | |
| #define | NV_SCI_IPC_EVENT_ASYNC_ERROR 0x20U |
| Specifies the IPC asynchronous error event. More... | |
| #define | NV_SCI_IPC_EVENT_CONN_EST_ALL |
| Specifies single event mask to check IPC connection establishment. More... | |
| #define | NVSCIIPC_INFINITE_WAIT -1LL |
| infinite timeout for NvSciIpcWaitEventQnx() More... | |
| #define | NV_SCI_ASYNC_PCIE_EDMA_XFER_ERROR 0x1U |
| Indicates there is eDMA error during PCIE operation. More... | |
| #define | NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_FATAL 0x2U |
| Indicates there is uncorrectable fatal error during PCIE operation. More... | |
| #define | NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_NONFATAL 0x4U |
| Indicates there is uncorrectable non fatal error during PCIE operation. More... | |
| #define | NV_SCI_ASYNC_PCIE_VALIDATION_ERROR 0x8U |
| Indicates there is validation error. More... | |
Typedefs | |
| typedef uint64_t | NvSciIpcEndpoint |
| Handle to the NvSciIpc endpoint. More... | |
| typedef struct NvSciIpcEndpointInfo | NvSciIpcEndpointInfo |
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... | |
| NvSciError | NvSciIpcCloseEndpointSafe (NvSciIpcEndpoint handle, bool clear) |
| Closes an endpoint with the given handle (safety version) More... | |
| void | NvSciIpcResetEndpoint (NvSciIpcEndpoint handle) |
| Resets an endpoint. More... | |
| NvSciError | NvSciIpcResetEndpointSafe (NvSciIpcEndpoint handle) |
| Resets an endpoint. More... | |
| NvSciError | NvSciIpcRead (NvSciIpcEndpoint handle, void *buf, size_t size, int32_t *bytes) |
| Reads a frame from the endpoint. More... | |
| NvSciError | NvSciIpcReadSafe (NvSciIpcEndpoint handle, void *buf, uint32_t size, uint32_t *bytes) |
| Reads a frame from the endpoint (safety version) More... | |
| NvSciError | NvSciIpcReadGetNextFrame (NvSciIpcEndpoint handle, const volatile void **buf) |
| Get a pointer to the read frame from the endpoint. More... | |
| NvSciError | NvSciIpcReadAdvance (NvSciIpcEndpoint handle) |
| Advance to the next read frame of the endpoint. More... | |
| NvSciError | NvSciIpcWrite (NvSciIpcEndpoint handle, const void *buf, size_t size, int32_t *bytes) |
| Writes a frame to the endpoint. More... | |
| NvSciError | NvSciIpcWriteSafe (NvSciIpcEndpoint handle, const void *buf, uint32_t size, uint32_t *bytes) |
| Writes a frame to the endpoint. More... | |
| NvSciError | NvSciIpcWriteGetNextFrame (NvSciIpcEndpoint handle, volatile void **buf) |
| Get a pointer to the write frame from the endpoint. More... | |
| NvSciError | NvSciIpcWriteAdvance (NvSciIpcEndpoint handle) |
| Advance to the next write frame of the endpoint. More... | |
| NvSciError | NvSciIpcGetEndpointInfo (NvSciIpcEndpoint handle, 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 | NvSciIpcGetEventSafe (NvSciIpcEndpoint handle, uint32_t *events) |
| Get Events (safety version) More... | |
| NvSciError | NvSciIpcGetAsyncErrors (NvSciIpcEndpoint handle, uint32_t *errors) |
| Get asynchronouse errors. More... | |
| NvSciError | NvSciIpcEnableNotification (NvSciIpcEndpoint handle, bool flag) |
| Enable event notification (or polling) More... | |
| NvSciError | NvSciIpcCheckVersionCompatibility (uint32_t majorVer, uint32_t minorVer, bool *isCompatible) |
| Check NvSciIpc library version compatibility. More... | |
| #define NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_FATAL 0x2U |
Indicates there is uncorrectable fatal error during PCIE operation.
Definition at line 367 of file nvsciipc.h.
| #define NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_NONFATAL 0x4U |
Indicates there is uncorrectable non fatal error during PCIE operation.
Definition at line 369 of file nvsciipc.h.
| #define NV_SCI_ASYNC_PCIE_EDMA_XFER_ERROR 0x1U |
Indicates there is eDMA error during PCIE operation.
Definition at line 365 of file nvsciipc.h.
| #define NV_SCI_ASYNC_PCIE_VALIDATION_ERROR 0x8U |
Indicates there is validation error.
Definition at line 371 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_ASYNC_ERROR 0x20U |
Specifies the IPC asynchronous error event.
Definition at line 354 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_CONN_EST 0x04U |
Specifies the IPC connection established event.
Definition at line 348 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_CONN_EST_ALL |
Specifies single event mask to check IPC connection establishment.
Definition at line 356 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_CONN_RESET 0x08U |
Specifies the IPC connection reset event.
Definition at line 350 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_READ 0x01U |
Specifies the IPC read event.
Definition at line 344 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_WRITE 0x02U |
Specifies the IPC write event.
Definition at line 346 of file nvsciipc.h.
| #define NV_SCI_IPC_EVENT_WRITE_EMPTY 0x10U |
Specifies the IPC write fifo empty event.
Definition at line 352 of file nvsciipc.h.
| #define NVSCIIPC_INFINITE_WAIT -1LL |
infinite timeout for NvSciIpcWaitEventQnx()
Definition at line 361 of file nvsciipc.h.
| #define NVSCIIPC_MAX_ENDPOINT_NAME 64U |
Specifies maximum Endpoint name length including null terminator.
Definition at line 340 of file nvsciipc.h.
| typedef uint64_t NvSciIpcEndpoint |
Handle to the NvSciIpc endpoint.
Definition at line 322 of file nvsciipc.h.
| typedef struct NvSciIpcEndpointInfo NvSciIpcEndpointInfo |
Definition at line 324 of file nvsciipc.h.
| NvSciError NvSciIpcCheckVersionCompatibility | ( | uint32_t | majorVer, |
| uint32_t | minorVer, | ||
| bool * | isCompatible | ||
| ) |
Check NvSciIpc library version compatibility.
Checks if loaded NvSciIpc library version is compatible with the version the application was compiled against. This function checks loaded NvSciIpc library version with input NvSciIpc library version and sets output variable true provided major version of the loaded library is same as majorVer and minor version of the loaded library is not less than minorVer, else sets output to false
| [in] | majorVer | build major version. |
| [in] | minorVer | build minor version. |
| [out] | isCompatible | boolean value stating if loaded NvSciIpc library is compatible or not. |
Usage considerations
| 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
| NvSciError NvSciIpcCloseEndpointSafe | ( | NvSciIpcEndpoint | handle, |
| bool | clear | ||
| ) |
Closes an endpoint with the given handle (safety version)
The function frees the NvSciIpc endpoint associated with the given handle.
| [in] | handle | A handle to the endpoint to close. |
| [in] | clear | Reserved for future use and any value has no change to the function behavior. |
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 NvSciIpcCloseEndpointSafe().
void
Usage considerations
| NvSciError NvSciIpcEnableNotification | ( | NvSciIpcEndpoint | handle, |
| bool | flag | ||
| ) |
Enable event notification (or polling)
Control notification when connection or FIFO status is changed. If notification is disabled, NvSciIpc doesn't send notification to remote endpoint. notification is enabled by default unless user disables it using this API explicitly. User can use this API to choose asynchronous event notification mode or polling mode. Once notification is disabled in both endpoints, user shall not call event blocking API (i.e. poll, NvSciIpcWaitEventQnx, WaitForEvent, WaitForMultipleEvents etc.). If connection recovery is required (i.e. remote endpoint is restarted) after disabling notification, user shall call NvSciIpcGetEventSafe() till it doesn't return NV_SCI_IPC_EVENT_CONN_RESET any more.
| [in] | handle | NvSciIpc endpoint handle. |
| [in] | flag | flag to enable IPC notification. |
Usage considerations
| NvSciError NvSciIpcGetAsyncErrors | ( | NvSciIpcEndpoint | handle, |
| uint32_t * | errors | ||
| ) |
Get asynchronouse errors.
Returns error codes that can happen asynchronousely in the backend component. It could be errors from eDMA or PCIE in case of C2C backend.
There are four errors reported in mask and this API returns bitwise OR operaton on new errors that has occurred since the last call to it.
NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_FATAL NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_NONFATAL NV_SCI_ASYNC_PCIE_EDMA_XFER_ERROR NV_SCI_ASYNC_PCIE_VALIDATION_ERROR | [in] | handle | NvSciIpc endpoint handle. |
| [out] | mask | place holder to store bitwise OR errors |
Usage considerations
| NvSciError NvSciIpcGetEndpointInfo | ( | NvSciIpcEndpoint | handle, |
| 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 6 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 resetNV_SCI_IPC_EVENT_WRITE_EMPTY : IPC write FIFO emptyNV_SCI_IPC_EVENT_ASYNC_ERROR : Asynchronous errorNV_SCI_IPC_EVENT_CONN_EST and NV_SCI_IPC_EVENT_CONN_RESET events are connection event. They're edge-triggered events and once they're read by user, events are cleared.
NV_SCI_IPC_EVENT_WRITE, NV_SCI_IPC_EVENT_READ and NV_SCI_IPC_EVENT_WRITE_EMPTY events are FIFO status event. As long as free buffer is available on write FIFO or data are available in read FIFO, API keeps reporting same events. All these events mean that connection is still alive.
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.
An NV_SCI_IPC_EVENT_WRITE_EMPTY event occurs on an endpoint when write FIFO is empty. user can utilize this event to check if remote endpoint reads all data which local endpoint sent.
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 NvSciIpcCloseEndpointSafe(), 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 NvSciIpcGetEventSafe | ( | NvSciIpcEndpoint | handle, |
| uint32_t * | events | ||
| ) |
Get Events (safety version)
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 6 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 resetNV_SCI_IPC_EVENT_WRITE_EMPTY : IPC write FIFO emptyNV_SCI_IPC_EVENT_ASYNC_ERROR : Asynchronous errorNV_SCI_IPC_EVENT_CONN_EST and NV_SCI_IPC_EVENT_CONN_RESET events are connection event. They're edge-triggered events and once they're read by user, events are cleared.
NV_SCI_IPC_EVENT_WRITE, NV_SCI_IPC_EVENT_READ and NV_SCI_IPC_EVENT_WRITE_EMPTY events are FIFO status event. As long as free buffer is available on write FIFO or data are available in read FIFO, API keeps reporting same events. All these events mean that connection is still alive.
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.
An NV_SCI_IPC_EVENT_WRITE_EMPTY event occurs on an endpoint when write FIFO is empty. user can utilize this event to check if remote endpoint reads all data which local endpoint sent.
An NV_SCI_IPC_EVENT_ASYNC_ERROR event occurs on an endpoint when there is a asynchronouse error, i.e. failure on eDMA or PCIE. To get detailed error information, the user can call NvSciIpcGetAsyncError().
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 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. |
Usage considerations
| 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 NvSciEventLoopServiceCreateSafe(). 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 | ||
| ) |
Reads a frame from the endpoint.
This function copies a new frame contents into a buffer and advances to the next frame. 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 NvSciIpcResetEndpointSafe(), 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, not to exceed the length of the destination buffer and configured frame size of the endpoint. |
| [out] | bytes | The number of bytes read on success. |
Usage considerations
| NvSciError NvSciIpcReadAdvance | ( | NvSciIpcEndpoint | handle | ) |
Advance to the next read frame of the 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 NvSciIpcResetEndpointSafe(), 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 | ||
| ) |
Get a pointer to the read frame from the endpoint.
This is a non-blocking call. This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpointSafe(), 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
| NvSciError NvSciIpcReadSafe | ( | NvSciIpcEndpoint | handle, |
| void * | buf, | ||
| uint32_t | size, | ||
| uint32_t * | bytes | ||
| ) |
Reads a frame from the endpoint (safety version)
This function copies a new frame contents into a buffer and advances to the next frame. 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 NvSciIpcResetEndpointSafe(), 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, not to exceed the length of the destination buffer and configured frame size of the endpoint. |
| [out] | bytes | The number of bytes read 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 at most once per endpoint handle during Init mode 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 or NvSciIpcWaitEventQnx) 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 NvSciIpcResetEndpointSafe | ( | NvSciIpcEndpoint | handle | ) |
Resets an endpoint.
(safety version)
Initiates a reset on the endpoint and notifies the remote endpoint. Applications must call this function at most once per endpoint handle during Init mode 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 or NvSciIpcWaitEventQnx) 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. |
Usage considerations
| NvSciError NvSciIpcWrite | ( | NvSciIpcEndpoint | handle, |
| const void * | buf, | ||
| size_t | size, | ||
| int32_t * | bytes | ||
| ) |
Writes a 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 and configured frame size of the endpoint. |
| [out] | bytes | The number of bytes written on success. |
Usage considerations
| NvSciError NvSciIpcWriteAdvance | ( | NvSciIpcEndpoint | handle | ) |
Advance to the next write frame of 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 NvSciIpcResetEndpointSafe(), 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 | ||
| ) |
Get a pointer to the write frame from the endpoint.
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 NvSciIpcResetEndpointSafe(), 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
| NvSciError NvSciIpcWriteSafe | ( | NvSciIpcEndpoint | handle, |
| const void * | buf, | ||
| uint32_t | size, | ||
| uint32_t * | bytes | ||
| ) |
Writes a frame to the endpoint.
(safety version)
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 and configured frame size of the endpoint. |
| [out] | bytes | The number of bytes written on success. |
Usage considerations