/* * Copyright (c) 2018-2024, NVIDIA CORPORATION. All rights reserved. * * NVIDIA CORPORATION and its licensors retain all intellectual property * and proprietary rights in and to this software, related documentation * and any modifications thereto. Any use, reproduction, disclosure or * distribution of this software and related documentation without an express * license agreement from NVIDIA CORPORATION is strictly prohibited. */ #ifndef INCLUDED_NVSCIIPC_H #define INCLUDED_NVSCIIPC_H #ifdef __cplusplus extern "C" { #endif #include #include #include "nvscierror.h" #include "nvscievent.h" /** * @file * * @brief NVIDIA Software Communications Interface (SCI) : NvSci Inter-Process Communication * * @version 1.4 * * @section 1.4 Jun/29/2023 * - Add NvSciIpcEnableNotification() * --------------------------------------------------------------------------- * @section 1.3 Jun/26/2023 * - Add NV_SCI_IPC_EVENT_ASYNC_ERROR to NvSciIpcGetEventSafe() * - Add NvSciIpcAsyncError() * - Remove Runtime support of NvSciIpcResetEndpointSafe() * --------------------------------------------------------------------------- * @section 1.2 Mar/07/2023 * - Deprecate non-safe APIs in safety build * NvSciIpcCloseEndpoint * NvSciIpcResetEndpoint * NvSciIpcRead * NvSciIpcWrite * NvSciIpcGetEvent * NvSciIpcSetQnxPulseParam * --------------------------------------------------------------------------- * @section 1.1 Dec/15/2022 * - Add NvSciError_NotPermitted error for incorrect API group usage * in QNX safety only (NvDVMS). * NvSciIpcInit() * NvSciIpcOpenEndpoint() * NvSciIpcOpenEndpointWithEventService() * NvSciIpcGetEventNotifier() * NvSciIpcCloseEndpointSafe() * NvSciIpcSetQnxPulseParamSafe() * --------------------------------------------------------------------------- * @section 1.0 Jun/23/2022 * - Add NvSciIpcGetEventSafe() * - Add NvSciIpcWaitEventQnx() : QNX only * - Add NvSciIpcSetQnxPulseParamSafe() : QNX only * - Add NvSciIpcInspectEventQnx() : QNX only * - Add NvSciIpcCheckVersionCompatibility() * - Add NvSciIpcMajorVersion, NvSciIpcMinorVersion constant */ /* use constant global version variable instead of macro for consistency with * version check API of existing NvSci family */ /** @brief NvSciIpc API Major version number */ static const uint32_t NvSciIpcMajorVersion = 1U; /** @brief NvSciIpc API Minor version number */ static const uint32_t NvSciIpcMinorVersion = 4U; /** * @defgroup nvsci_group_ipc Inter-Process Communication * IPC and Event Service APIs * * @ingroup nvsci_top * @{ */ /** * @defgroup nvsci_ipc_api IPC APIs * * * @ingroup nvsci_group_ipc * @{ * * 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: * - Different threads in the same process * - The same process * - Different processes in the same VM * - Different VMs on the same SoC * @if (SWDOCS_NVSCIIPC_STANDARD) * - Different SoCs * @endif * * 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. * * Programming model in using NvSciIpc library is explained in SDK developer * guide with examples. * * @pre Start-up sequence * - When NvSciIpc APIs are used, the initialization sequence must be exactly * the same as below: * Here two cases, with or without NvSciEventService. * - Call flow with NvSciIpc * ~~~~~~~~~~~~~~~~~~~~~ * NvSciIpcInit() * NvSciIpcOpenEndpoint() * NvSciIpcSetQnxPulseParamSafe() (QNX OS-specific) or * NvSciIpcGetLinuxEventFd() (Linux OS-specific) * NvSciIpcGetEndpointInfo() * NvSciIpcResetEndpointSafe() * ~~~~~~~~~~~~~~~~~~~~~ * - 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(). * ~~~~~~~~~~~~~~~~~~~~~ * NvSciEventLoopServiceCreateSafe() to get eventLoopService * NvSciIpcInit() * NvSciIpcOpenEndpointWithEventService() * NvSciIpcGetEventNotifier() * NvSciEventNotifier::SetHandler() * NvSciIpcGetEndpointInfo() * NvSciIpcResetEndpointSafe() * ~~~~~~~~~~~~~~~~~~~~~ * * @pre Single thread handling Tx and Rx data * - For Inter-VM and Inter-Process backend applications on QNX OS, * only a single event-blocking OS API (e.g. 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. * * @pre Getting events before using Read/Write NvSciIpc API * - Before using any Read/Write APIs, the user must check if * @ref NV_SCI_IPC_EVENT_READ or @ref NV_SCI_IPC_EVENT_WRITE event is available * through NvSciIpcGetEventSafe(). * NvSciIpcGetEventSafe() has additional support to establish connection between * two endpoint software entities. * * @pre 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. * * @pre 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; * unsigned num_pulses; * unsigned rearm_threshold; * unsigned options; * unsigned reserved[3]; * } * ~~~~~~~~~~~~~~~~~~~~~ * - The num_pulses should be based on the number of event notifications that can occur at the same time. * The notifications that can occur on an endpoint are reset /read /write and are independent of each other, * so at least 3 notifications can occur on one endpoint. * ~~~~~~~~~~~~~~~~~~~~~ * num_pulses = 3 * number of endpoints * ~~~~~~~~~~~~~~~~~~~~~ * - 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 (e.g. close endpoint, restart process, deinit * NvSciIpc etc.) per system usecase scenario after detecting issue. * * @note * 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. * 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. * * @note * When to use blocking API * - Users must call OS event-blocking API to wait for an event when * NvSciIpcGetEventSafe() does not return desired events. * The following are OS event-blocking API examples: * - QNX : NvSciIpcWaitEventQnx() * - LINUX: select(), poll() etc. * - NvSciEventService: NvSciEventLoopService::WaitForEvent(),
* NvSciEventLoopService::WaitForMultipleEvents() * * - 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. * * @note * Consideration when choosing Read/Write APIs * - Using NvSciIpcReadSafe() and NvSciIpcWriteSafe() is recommended rather than following * Read/Write APIs. See detail constraints of API in each function description. * - NvSciIpcReadGetNextFrame() * - NvSciIpcWriteGetNextFrame() * - NvSciIpcReadAdvance() * - NvSciIpcWriteAdvance() * However, above functions are better to avoid extra memory copy. * * @note * 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. * * @note * 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. * */ #ifdef __QNX__ /*******************************************************************/ /********************* ACCESS CONTROL ******************************/ /*******************************************************************/ /** * @page page_access_control NvSciIpc Access Control * @section sec_access_control Common Privileges * * Description of QNX custom abilites * * 1) NvSciIpcEndpoint:{List of VUIDs} * - required VUID list is set by QNX_BSP::IOLauncher with -T option * - This ability is used to authenticate client process from NvSciIpc * Driver * * 2) NvSciC2cPcieEndpoint:{List of SGIDs} * - required SGIDs list is set by QNX_BSP::IOLauncher with -T option * - This ability is used to authenticate client process which try to access any * Inter-Chip PCIe device-node provided by NvSciC2c resmgr/process. * * Common QNX privileges required for all NvSciIpc APIs * * 1) Intra-VM and Inter-VM * - Service/Group Name: * proc_boot (GID: 40029), libc (GID: 40002), libslog2 (GID: 40006), * libnvivc (GID: 45031), libnvsciipc (GID: 45047), * libnvos_s3_safety (GID: 45037), libnvdvms_client (GID: 45112) * * 2) Inter-Chip PCIE * - Service/Group Name: * nvsciipc (GID: 2000), nvsys (GID: 3000), devg_nvrm_nvmap (GID: 10100), /usr/ (GID: 40032), * devg_nvrm_nvhost (GID: 10140), /usr/libnvidia/ (GID: 55046), * nvscic2c_pcie_epc_1/2/.../12 (GID: 26001, 26002,..., 26012), * nvscic2c_pcie_epf_1/2/.../12 (GID: 26101, 26002,..., 26112), * libc (GID: 40002), libm (GID: 40005), libslog2 (GID: 40006), libgnat (GID: 40012), * libcatalog (GID: 40052), libnvivc (GID: 45031), libnvos_s3_safety (GID: 45037), * libnvos (GID: 45038), libnvrm_gpu (GID: 45042), libnvrm_host1x (GID: 45043), * libnvscievent (GID: 45046), libnvsciipc (GID: 45047), libnvrm_mem (GID: 45069), * libnvsocsys (GID: 45071), libnvdvms_client (GID: 45112), libnvscibuf (GID: 55016), * libnvscicommon (GID: 55017), libnvscisync (GID: 55019), libnvscic2ccommon (GID: 55075), * libnvscic2c (GID: 55076), libnvscic2cpcie (GID: 55077) */ #endif /* __QNX___ */ /*******************************************************************/ /************************ DATA TYPES *******************************/ /*******************************************************************/ /** * @brief Handle to the NvSciIpc endpoint. */ typedef uint64_t NvSciIpcEndpoint; typedef struct NvSciIpcEndpointInfo NvSciIpcEndpointInfo; /** * @brief Defines information about the NvSciIpc endpoint. */ struct NvSciIpcEndpointInfo { /** Holds the number of frames. */ uint32_t nframes; /** Holds the frame size in bytes. */ uint32_t frame_size; }; /** * Specifies maximum Endpoint name length * including null terminator */ #define NVSCIIPC_MAX_ENDPOINT_NAME 64U /* NvSciIPC Event type */ /** Specifies the IPC read event. */ #define NV_SCI_IPC_EVENT_READ 0x01U /** Specifies the IPC write event. */ #define NV_SCI_IPC_EVENT_WRITE 0x02U /** Specifies the IPC connection established event. */ #define NV_SCI_IPC_EVENT_CONN_EST 0x04U /** Specifies the IPC connection reset event. */ #define NV_SCI_IPC_EVENT_CONN_RESET 0x08U /** Specifies the IPC write fifo empty event. */ #define NV_SCI_IPC_EVENT_WRITE_EMPTY 0x10U /** Specifies the IPC asynchronous error event. */ #define NV_SCI_IPC_EVENT_ASYNC_ERROR 0x20U /** Specifies single event mask to check IPC connection establishment */ #define NV_SCI_IPC_EVENT_CONN_EST_ALL (NV_SCI_IPC_EVENT_CONN_EST | \ NV_SCI_IPC_EVENT_WRITE | NV_SCI_IPC_EVENT_WRITE_EMPTY | \ NV_SCI_IPC_EVENT_READ) /** infinite timeout for NvSciIpcWaitEventQnx() */ #define NVSCIIPC_INFINITE_WAIT -1LL /* NvSciIpc Asynchronous erros */ /** Indicates there is eDMA error during PCIE operation. */ #define NV_SCI_ASYNC_PCIE_EDMA_XFER_ERROR 0x1U /** Indicates there is uncorrectable fatal error during PCIE operation. */ #define NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_FATAL 0x2U /** Indicates there is uncorrectable non fatal error during PCIE operation. */ #define NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_NONFATAL 0x4U /** Indicates there is validation error. */ #define NV_SCI_ASYNC_PCIE_VALIDATION_ERROR 0x8U /*******************************************************************/ /********************* FUNCTION TYPES ******************************/ /*******************************************************************/ /** * @brief Initializes the NvSciIpc library. * * This function parses the NvSciIpc configuration file and creates * an internal database of NvSciIpc endpoints that exist in a system. * * @return ::NvSciError, the completion code of the operation. * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_NotPermitted Indicates initialization has failed. * Indicates incorrect API group usage. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: Yes * - Runtime: No * - De-Init: No */ NvSciError NvSciIpcInit(void); /** * @brief De-initializes the NvSciIpc library. * * This function cleans up the NvSciIpc endpoint internal database * created by NvSciIpcInit(). * * @note This API can be called in Init mode to release resources * in error handling or to test functionality. * * @return @c void * * @pre Invocation of NvSciIpcInit() must be successful. * * @pre Closing endpoints before deinitialization * - Before calling this API, the user shall ensure all existing opened * endpoints are closed by NvSciIpcCloseEndpointSafe(). * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: Yes * - Runtime: No * - De-Init: Yes */ void NvSciIpcDeinit(void); /** * @brief 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. * * @param[in] endpoint The name of the NvSciIpc endpoint to open. * @param[out] handle A handle to the endpoint on success. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_BadParameter Indicates any argument was NULL or invalid. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_NoSuchEntry Indicates the @a endpoint was not found. * - ::NvSciError_Busy Indicates the @a endpoint is already in * use. * - ::NvSciError_InsufficientMemory Indicates memory allocation failed for * the operation. * - ::NvSciError_NotSupported Indicates API is not supported on provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * - ::NvSciError_NotPermitted Indicates process doesn't have the required * privilege. * Indicates incorrect API group usage. * * @pre Invocation of NvSciIpcInit() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): * - "nvdvms/ClientCommGetState" * - "NvSciIpcEndpoint" * - "NvSciC2cPcieEndpoint" (Inter-Chip only) * - "nvsys/system_info" (Inter-Chip only) * - "NvMap/Interfaces:17,19" (Inter-Chip only) * - When used in streaming mode (Inter-Chip only): * - "NvHost/Interfaces:1-2" * - "NvHost/Waiter:1" * OR "NvHost/Waiter:N", where 'N' is the * number of Inter-Chip endpoints application uses in the same process. * - PROCMGR_AID_PROT_EXEC (Inter-Chip only) * - PROCMGR_AID_MAP_FIXED (Inter-Chip only) * - API Group * - Init: Yes * - Runtime: No * - De-Init: No */ NvSciError NvSciIpcOpenEndpoint(const char *endpoint, NvSciIpcEndpoint *handle); /** * @brief 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. * * @param[in] endpoint The name of the NvSciIpc endpoint to open. * @param[out] handle A handle to the endpoint on success. * @param[in] eventService An abstract object to use NvSciEventService * infrastructure. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_BadParameter Indicates any argument was NULL or invalid. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_NoSuchEntry Indicates the @a endpoint was not found. * - ::NvSciError_Busy Indicates the @a endpoint is already in * use. * - ::NvSciError_InsufficientMemory Indicates memory allocation failed for * the operation. * - ::NvSciError_NotSupported Indicates API is not supported on provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * - ::NvSciError_NotPermitted Indicates process doesn't have the required * privilege. * Indicates incorrect API group usage. * * @pre Invocation of NvSciEventLoopServiceCreateSafe() must be successful. * Invocation of NvSciIpcInit() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): * - "nvdvms/ClientCommGetState" * - "NvSciIpcEndpoint" * - "NvSciC2cPcieEndpoint" (Inter-Chip only) * - "nvsys/system_info" (Inter-Chip only) * - "NvMap/Interfaces:17,19" (Inter-Chip only) * - When used in streaming mode (Inter-Chip only): * - "NvHost/Interfaces:1-2" * - "NvHost/Waiter:1" * OR "NvHost/Waiter:N", where 'N' is the * number of Inter-Chip endpoints application uses in the same process. * - PROCMGR_AID_PROT_EXEC (Inter-Chip only) * - PROCMGR_AID_MAP_FIXED (Inter-Chip only) * - API Group * - Init: Yes * - Runtime: No * - De-Init: No */ NvSciError NvSciIpcOpenEndpointWithEventService(const char *endpoint, NvSciIpcEndpoint *handle, NvSciEventService *eventService); /** * @brief Get NvSciIpc event notifier. * * This API is used to connect NvSciIpc event handling with OS-provided * event interface. * It also utilizes NvSciEventService infrastructure. * * @note This API is only compatible with an endpoint that is opened with * NvSciIpcOpenEndpointWithEventService() * * @param[in] handle NvSciIpc endpoint handle. * @param[out] eventNotifier A pointer to NvSciEventNotifier object on success. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. * - ::NvSciError_NotSupported Indicates API is not supported on provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * - ::NvSciError_InsufficientMemory Indicates memory allocation failed for the * operation. * - ::NvSciError_ResourceError Indicates not enough system resources. * - ::NvSciError_NotPermitted Indicates incorrect API group usage. * * @pre Invocation of NvSciIpcOpenEndpointWithEventService() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): * - PROCMGR_AID_INTERRUPTEVENT (Inter-VM only) * - PROCMGR_AID_PUBLIC_CHANNEL * - API Group * - Init: Yes * - Runtime: No * - De-Init: No */ NvSciError NvSciIpcGetEventNotifier(NvSciIpcEndpoint handle, NvSciEventNotifier **eventNotifier); /** * @brief Closes an endpoint with the given handle. * * @warning This API is deprecated and returns without doing anything in safety * build. * Use NvSciIpcCloseEndpointSafe() instead of this. */ void NvSciIpcCloseEndpoint(NvSciIpcEndpoint handle); /** * @brief Closes an endpoint with the given handle (safety version) * * The function frees the NvSciIpc endpoint associated with the given @a handle. * * @note This API can be called in Init mode to release resources * in error handling or to test functionality. * * @param[in] handle A handle to the endpoint to close. * @param[in] clear Reserved for future use and any value has no change to the * function behavior. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_NotPermitted Indicates incorrect API group usage. * * @pre Invocation of NvSciIpcOpenEndpoint() or * NvSciIpcOpenEndpointWithEventService() must be successful. * * @pre Deleting NvSciEventNotifier * - Before calling NvSciIpcCloseEndpointSafe(), event notifier associated with * the closing endpoint through NvSciIpcGetEventNotifier() must be deleted by * NvSciEventNotifier::Delete(). * * @pre Closing Inter-Chip Endpoint * - When used in streaming mode, before calling * NvSciIpcCloseEndpointSafe() for (INTER_CHIP, PCIE) endpoint, * the user must ensure all fences submitted to NvIpc for Inter-Chip * communication for signaling are expired and also all NvSciBufObjs * and NvSciSyncObjs mappings registered, exported and imported with * NvIpc for Inter-Chip communication are un-registered and released. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: Yes * - Runtime: No * - De-Init: Yes */ NvSciError NvSciIpcCloseEndpointSafe(NvSciIpcEndpoint handle, bool clear); /** * @brief Resets an endpoint. * * @warning This API is deprecated and returns without doing anything in safety * build. * Use NvSciIpcResetEndpointSafe() instead of this. */ void NvSciIpcResetEndpoint(NvSciIpcEndpoint handle); /** * @brief Resets an endpoint. (safety version) * * Initiates a reset on the endpoint and notifies the remote endpoint. * Once this API is called, all existing data in channel will be discarded. * After invoking this function, client user shall call NvSciIpcGetEventSafe() * to get specific event type (READ, WRITE etc.). * * @param[in] handle A handle to the endpoint to reset. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_InvalidState Indicates an invalid operation state. * - ::NvSciError_NotSupported Indicates API is not supported on provided * endpoint backend type. * * @pre Invocation of NvSciIpcSetQnxPulseParamSafe() or * NvSciIpcGetLinuxEventFd() or * NvSciIpcGetEventNotifier() must be successful. * * @pre When to reset endpoint * - This API must be called exactly once per endpoint handle during Init * mode to complete the initialization sequence before using the endpoint for * communication,and at most once during De-init mode only if both endpoints * are in the established state (e.g. synchronization for closing channel). In case of * De-Init mode, NvSciIpcGetEventSafe() must NOT be called after * NvSciIpcResetEndpointSafe() is called. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: Yes * - Runtime: No * - De-Init: Yes */ NvSciError NvSciIpcResetEndpointSafe(NvSciIpcEndpoint handle); /** * @brief Reads a frame from the endpoint. * * @warning This API is deprecated and returns NvSciError_NotSupported without * doing anything in safety build. * Use NvSciIpcReadSafe() instead of this. */ NvSciError NvSciIpcRead(NvSciIpcEndpoint handle, void *buf, size_t size, int32_t *bytes); /** * @brief 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. * * @param[in] handle The handle to the endpoint to read from. * @param[out] buf A pointer to a destination buffer to receive the contents * of the next frame. * @param[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. * @param[out] bytes The number of bytes read on success. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle or @a size. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_InsufficientMemory Indicates read channel is empty and * the read operation aborted. * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. * - ::NvSciError_NotSupported Indicates API is not supported on provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @pre NvSciIpcResetEndpointSafe() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: No * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcReadSafe(NvSciIpcEndpoint handle, void *buf, uint32_t size, uint32_t *bytes); /** * @brief 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. * * @param[in] handle The handle to the endpoint to read from. * @param[out] buf A pointer to a destination buffer to receive * the contents of the next frame on success. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_InsufficientMemory Indicates read channel is empty and * the read operation aborted. * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @pre NvSciIpcResetEndpointSafe() must be successful. * * @pre No overlapped read operation * - Between NvSciIpcReadGetNextFrame() and NvSciIpcReadAdvance(), the user must not perform * any other NvSciIpc read operations with the same endpoint handle. * * @pre No use of invalid pointer to read frame * - Once a read frame is released by NvSciIpcReadAdvance(), the user must not use previously * returned pointer of NvSciIpcReadGetNextFrame() since it is already invalid. * * @pre No write operation with pointer to read frame * - The user shall not write through a returned pointer of NvSciIpcReadGetNextFrame(). * This is protected by a const volatile pointer return type. * * @pre Copy data before using it * - The user shall not read the same memory location multiple times. If required, copy * specific memory location to a local buffer before using it. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: No * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcReadGetNextFrame(NvSciIpcEndpoint handle, const volatile void **buf); /** * @brief 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. * * @note This API is used together with NvSciIpcReadGetNextFrame(). * Refer to precondition of NvSciIpcReadGetNextFrame() * * @param[in] handle The handle to the endpoint to read from. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_InsufficientMemory Indicates read channel is empty and * the read operation aborted. * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @pre NvSciIpcResetEndpointSafe() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: No * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcReadAdvance(NvSciIpcEndpoint handle); /** * @brief Writes a frame to the endpoint. * * @warning This API is deprecated and returns NvSciError_NotSupported without * doing anything in safety build. * Use NvSciIpcWriteSafe() instead of this. */ NvSciError NvSciIpcWrite(NvSciIpcEndpoint handle, const void *buf, size_t size, int32_t *bytes); /** * @brief 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 @a size is less than the frame size, then the remaining bytes of the frame * are filled with zero. * * 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. * * @param[in] handle The handle to the endpoint to write to. * @param[in] buf A pointer to a source buffer for the contents of * the next frame. * @param[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. * @param[out] bytes The number of bytes written on success. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle or @a size. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_InsufficientMemory Indicates write channel is full and * the write operation aborted. * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @pre NvSciIpcResetEndpointSafe() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: No * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcWriteSafe(NvSciIpcEndpoint handle, const void *buf, uint32_t size, uint32_t *bytes); /** * @brief 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. * * @param[in] handle The handle to the endpoint to write to. * @param[out] buf A pointer to a destination buffer to hold the contents of * the next frame on success. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_InsufficientMemory Indicates write channel is full and * the write operation aborted. * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @pre NvSciIpcResetEndpointSafe() must be successful. * * @pre No overlapped write operation * - Between NvSciIpcWriteGetNextFrame() and NvSciIpcWriteAdvance(), do not * perform any other NvSciIpc write operations with the same endpoint handle. * * @pre No use of invalid pointer to write * - Once a transmit message is committed by NvSciIpcWriteAdvance(), do not use * previously returned pointer of NvSciIpcWriteGetNextFrame() since it is * already invalid. * * @pre No read operation with pointer to write frame * - Do not read through a returned pointer of NvSciIpcWriteGetNextFrame(). * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: No * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcWriteGetNextFrame(NvSciIpcEndpoint handle, volatile void **buf); /** * @brief 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. * * @note This API is used together with NvSciIpcWriteGetNextFrame(). * Refer to precondition of NvSciIpcWriteGetNextFrame() * * @param[in] handle The handle to the endpoint to write to. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_InsufficientMemory Indicates write channel is full and * the write operation aborted. * - ::NvSciError_ConnectionReset Indicates the endpoint is being reset. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @pre NvSciIpcResetEndpointSafe() must be successful. * * @pre Populated with data * - The user shall ensure entire outgoing frame is populated with application * data or filled with zeros prior call to NvScipcWriteAdvance(). * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: No * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcWriteAdvance(NvSciIpcEndpoint handle); /** * @brief Returns endpoint information. * * * @param[in] handle NvSciIpc endpoint handle. * @param[out] info A pointer to NvSciIpcEndpointInfo object that * this function copies the info to on success. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @pre Invocation of NvSciIpcOpenEndpoint() or * NvSciIpcOpenEndpointWithEventService() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: Yes * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcGetEndpointInfo(NvSciIpcEndpoint handle, NvSciIpcEndpointInfo *info); #ifndef __QNX__ /** * 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.) * * @param handle NvSciIpc endpoint handle * @param fd A pointer to the endpoint file descriptor. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type or OS environment. * * @pre Invocation of NvSciIpcOpenEndpoint() or * NvSciIpcOpenEndpointWithEventService() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges: None * - API Group * - Init: Yes * - Runtime: No * - De-Init: No */ NvSciError NvSciIpcGetLinuxEventFd(NvSciIpcEndpoint handle, int32_t *fd); #endif /* !__QNX__ */ /** * @brief Get Events * * @warning This API is deprecated and returns NvSciError_NotSupported without * doing anything in safety build. * Use NvSciIpcGetEventSafe() instead of this. */ NvSciError NvSciIpcGetEvent(NvSciIpcEndpoint handle, uint32_t *events); /** * @brief Get Events * (safety version) * * Returns a bitwise OR operation on new events that occurred since the * last call to this function. * * This function sets @a events to the result of a bitwise OR operation of zero * or more @c NV_SCI_IPC_EVENT_* constants corresponding to all new events that * have occurred on the endpoint since: * - the preceding call to this function on the endpoint or * - opening the endpoint, if this is the first call to this function on the * endpoint since it was opened. * * The parameter @a events is set to zero if no new events have * occurred. * * There are 6 types of events: * - @c NV_SCI_IPC_EVENT_CONN_EST : IPC connection established * - @c NV_SCI_IPC_EVENT_WRITE : IPC write * - @c NV_SCI_IPC_EVENT_READ : IPC read * - @c NV_SCI_IPC_EVENT_CONN_RESET : IPC connection reset * - @c NV_SCI_IPC_EVENT_WRITE_EMPTY : IPC write FIFO empty * - @c NV_SCI_IPC_EVENT_ASYNC_ERROR : Asynchronous error * * @c NV_SCI_IPC_EVENT_CONN_EST and @c 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. * * @c NV_SCI_IPC_EVENT_WRITE, @c NV_SCI_IPC_EVENT_READ and * @c 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 also mean that * connection is established. * * An @c 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 @c NV_SCI_IPC_EVENT_WRITE event occurs on an endpoint: * -# In conjunction with the delivery of each @c NV_SCI_IPC_CONN_EST event. * -# Each time the endpoint's sending FIFO ceases to be full. * * An @c NV_SCI_IPC_EVENT_READ event occurs on an endpoint: * -# In conjunction with the delivery of each @c NV_SCI_IPC_EVENT_CONN_EST * event, if frames can already be read as of delivery. * -# Each time the endpoint's receiving FIFO ceases to be empty. * * An @c NV_SCI_IPC_EVENT_CONN_RESET event occurs on an endpoint when the user * calls NvSciIpcResetEndpoint. * * An @c 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 @c NV_SCI_IPC_EVENT_ASYNC_ERROR event occurs on an endpoint when there is * a asynchronouse error, e.g. failure on eDMA or PCIE. To get * detailed error information, the user can call @c 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: * - QNX : NvSciIpcWaitEventQnx() * - LINUX: select(), poll() etc. * - NvSciEventService: NvSciEventLoopService::WaitForEvent(),
* NvSciEventLoopService::WaitForMultipleEvents() * * 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. * * @note Before using any read and write NvSciIpc API, user should call this * API to make sure if connection is established. * * @param[in] handle NvSciIpc endpoint handle. * @param[out] events A pointer to the variable into which to store * the bitwise OR result of new events on success. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_BadParameter Indicates an invalid or NULL argument. * - ::NvSciError_InvalidState Indicates an invalid operation state. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type. * * @pre NvSciIpcResetEndpointSafe() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): "NvSciIpcEndpoint" * - API Group * - Init: Yes * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcGetEventSafe(NvSciIpcEndpoint handle, uint32_t *events); #if defined(__QNX__) /** * @brief Wait for an event with timeout * * This API is specific to QNX OS. * Users of NvSciIpc must call this API to wait for an event when * NvSciIpcGetEventSafe() does not return desired events. * This API is a blocking call. * * In using NvSciEventService, call other blocking APIs instead of this API. * - NvSciEventLoopService::WaitForEvent() * - NvSciEventLoopService::WaitForMultipleEvents() * - NvSciEventLoopService::WaitForMultipleEventsExt() * * @note It is only compatible with an endpoint that is opened with * NvSciIpcOpenEndpoint(). * * @param[in] chid The ID of a channel that you established by calling * ChannelCreate_r() or ChannelCreatePulsePool(). * @param[in] microseconds A 64-bit integer timeout in microsecond. * Set to NVSCIIPC_INFINITE_WAIT for an infinite * timeout. * @param[in] bytes The size of @pulse buffer * @param[out] pulse A void * pointer to struct _pulse structure where the * fuction can store the received data. * * @return ::NvSciError, the completion code of the operation: * - ::EOK Indicates a successful operation. * - ::EFAULT Indicates A fault occurred when the kernel tried to access * the buffer provided, or the size of the receive buffer is * less than the size of @a pulse. The pulse is lost in this * case. * - ::EPERM Indicates NvSciIpc is uninitialized. * - ::EINTR Indicates API was interrupted by a signal. * - ::ESRCH Indicates The channel indicated by chid doesn't exist. * - ::ETIMEDOUT Indicates A kernel timeout unblocked the call. * See TimerTimeout(). * - ::EINVAL Indicates a invalid parameter * * @pre ChannelCreate_r() or ChannelCreatePulsePool() must be successful. * NvSciIpcSetQnxPulseParamSafe() must be successful. * * @pre Suitable API to wait for multiple events * - If user process needs to wait for events from multiple remote NvSciIpc * endpoint processes, the user has to use single blocking call from * single thread instead of using blocking call per endpoint thread. * NvSciEventLoopService::WaitForMultipleEvents() blocking call is suitable for * this use case. * * @pre Suspend a thread when accessing with same chid * - If the user of NvSciIpc uses same chid between this API and * NvSciIpcInspectEventQnx(),the user has to suspend a thread which calls this * API before calling NvSciIpcInspectEventQnx() in other monitor thread. * You can suspend thread using delay() or other method. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: No * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: No * - Runtime: Yes * - De-Init: No */ int32_t NvSciIpcWaitEventQnx(int32_t chid, int64_t microseconds, uint32_t bytes, void *pulse); /** * @brief Sets the event pulse parameters for QNX. * * This API is specific to QNX OS. * @warning This API is deprecated and just returns NvSciError_NotSupported without * doing anything in safety build. * Use NvSciIpcSetQnxPulseParamSafe() instead of this. */ NvSciError NvSciIpcSetQnxPulseParam(NvSciIpcEndpoint handle, int32_t coid, int16_t pulsePriority, int16_t pulseCode, void *pulseValue); /** * @brief Sets the event pulse parameters for QNX. * (safety version) * * 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 @a coid to the endpoint, plug OS event notification * and set pulse parameters (@a pulsePriority and @a pulseCode), * thereby enabling the application to receive peer notifications from the * NvSciIpc library. * An application can receive notifications from a peer endpoint using * @c NvSciIpcWaitEventQnx() which is blocking call. * * Prior to calling this function, both @c ChannelCreate_r() / * @c ChannelCreatePulsePool() and @c ConnectAttach_r() must be called in * the application to obtain the value for @a coid to pass to this function. * * To use the priority of the calling thread, set @a pulsePriority to * @c SIGEV_PULSE_PRIO_INHERIT(-1). The priority must fall within the valid * range, which can be determined by calling @c sched_get_priority_min() and * @c sched_get_priority_max(). * * Applications can define any value per endpoint for @a pulseCode. * @a pulseCode will be used by NvSciIpc to signal IPC events and should be * reserved for this purpose by the application. * * @note It is only compatible with an endpoint that is opened with * NvSciIpcOpenEndpoint(). * * @param[in] handle NvSciIpc endpoint handle. * @param[in] coid The connection ID created from calling * @c ConnectAttach_r(). * @param[in] pulsePriority The value for pulse priority. * @param[in] pulseCode The 8-bit positive pulse code specified by the user. * The values must be between @c _PULSE_CODE_MINAVAIL * and @c _PULSE_CODE_MAXAVAIL. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_BadParameter Indicates an invalid @a handle. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type or OS environment. * - ::NvSciError_ResourceError Indicates not enough system resources. * - ::NvSciError_InvalidState Indicates an invalid operation state. * - ::NvSciError_NotPermitted Indicates incorrect API group usage. * * @pre Invocation of NvSciIpcOpenEndpoint() must be successful. * Invocation of ConnectAttach_r() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): * - PROCMGR_AID_INTERRUPTEVENT (Inter-VM only) * - PROCMGR_AID_PUBLIC_CHANNEL * - API Group * - Init: Yes * - Runtime: No * - De-Init: No */ NvSciError NvSciIpcSetQnxPulseParamSafe(NvSciIpcEndpoint handle, int32_t coid, int16_t pulsePriority, int16_t pulseCode); /** * @brief Inspect Event for QNX. * * This API is specific to QNX OS. * When legacy event handling is used, if IVC signalling storm happens in * specific Intra-VM endpoint which is not bound to NvSciEventService object, * this API returns that endpoint handle and unregisters relavant events. * This API is used in a thread to receive semaphore event of * ChannelCreatePulsePool() when pulse can't be obtained from the fixed pool * any more. * In order to prevent unwanted IVC signaling path breakage, Do not call this * API when semaphore event is not triggered by ChannelCreatePulsePool(). * * @note This API is used together with NvSciIpcWaitEventQnx(). * Refer to precondition of NvSciIpcWaitEventQnx() * * @note It is only compatible with endpoints that are opened with * NvSciIpcOpenEndpoint(). * * @param[in] chid A chid which is created by ChannelCreatePulsePool() * @param[in] numEvents A threshold value to unregister Intra-VM IVC * signalling events. This shall be less than * num_pulses which is configured in * ChannelCreatePulsePool(). * @param[in] epCount endpoint handle count in @epHandleArray. * @param[out] epHandleArray Array of NvSciIpc endpoint handle which has * excessive IVC signalling. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_NoSuchEntry Indicates unknown endpoint. * - ::NvSciError_InvalidState Indicates an invalid operation state. * * @pre Invocation of ChannelCreatePulsePool() must be successful. * Invocation of ConnectAttach_r() must be successful. * Invocation of NvSciIpcSetQnxPulseParamSafe() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: No * - Async/Sync: Sync * - Required Privileges: None * - API Group * - Init: No * - Runtime: Yes * - De-Init: No */ NvSciError NvSciIpcInspectEventQnx(int32_t chid, uint16_t numEvents, uint32_t epCount, NvSciIpcEndpoint **epHandleArray); #endif /* __QNX__ */ /** * @brief 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 @a mask and this API returns bitwise OR * operaton on new errors that has occurred since the last call to it. * - @c NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_FATAL * - @c NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_NONFATAL * - @c NV_SCI_ASYNC_PCIE_EDMA_XFER_ERROR * - @c NV_SCI_ASYNC_PCIE_VALIDATION_ERROR * * @param[in] handle NvSciIpc endpoint handle. * @param[out] mask place holder to store bitwise OR errors * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_BadParameter Indicates an invalid @a handle or @a error. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_InvalidState Indicates an invalid operation state. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type or OS environment. * * @pre Invocation of NvSciIpcGetEventSafe() must be successful. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: Yes * - Runtime: Yes * - De-Init: Yes */ NvSciError NvSciIpcGetAsyncErrors(NvSciIpcEndpoint handle, uint32_t* errors); /** * @brief 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 (e.g. poll, NvSciIpcWaitEventQnx, WaitForEvent, * WaitForMultipleEvents etc.). * * @note This API supports Intra-VM and Inter-VM backend only. * * @param[in] handle NvSciIpc endpoint handle. * @param[in] flag flag to enable IPC notification. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success Indicates a successful operation. * - ::NvSciError_NotInitialized Indicates NvSciIpc is uninitialized. * - ::NvSciError_BadParameter Indicates an invalid @a handle. * - ::NvSciError_NotSupported Indicates API is not supported in provided * endpoint backend type or OS environment. * * @pre Invocation of NvSciIpcResetEndpointSafe() must be successful. * * @pre Pending event in disabling notification * - Before calling this API to disable notification, * The user shall ensure that there are no remaining outstanding data * transactions between the two endpoints using their own handshaking mechanism * at the client level. If this is not guaranteed, pending notification might be * delivered from local to remote peer. * In that case, user shall handle (receive or ignore) such spurious * incoming notifications. * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: Yes * - Runtime: No * - De-Init: No */ NvSciError NvSciIpcEnableNotification(NvSciIpcEndpoint handle, bool flag); /** * @brief 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 @a majorVer and minor version of the * loaded library is not less than @a minorVer, else sets output to false * * @param[in] majorVer build major version. * @param[in] minorVer build minor version. * @param[out] isCompatible boolean value stating if loaded NvSciIpc library * is compatible or not. * * @return ::NvSciError, the completion code of the operation: * - ::NvSciError_Success if successful. * - ::NvSciError_BadParameter if any of the following occurs: * - @a isCompatible is NULL * * @pre None * * @usage * - Allowed context for the API call * - Interrupt handler: No * - Signal handler: No * - Thread-safe: Yes * - Async/Sync: Sync * - Required Privileges(QNX): None * - API Group * - Init: Yes * - Runtime: Yes * - De-Init: Yes */ NvSciError NvSciIpcCheckVersionCompatibility( uint32_t majorVer, uint32_t minorVer, bool* isCompatible); /** @} */ /** @} */ #ifdef __cplusplus } #endif #endif /* INCLUDED_NVSCIIPC_H */