IPC APIs

Detailed Description

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

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.

Precondition

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()

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.

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 NvSciIpcGetEventSafe(). NvSciIpcGetEventSafe() has additional support to establish connection between two endpoint software entities.

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.

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.

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.

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.

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.

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

NvSciIpc 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)

Common Privileges

Common QNX privileges required for all NvSciEventService APIs

• Service/Group Name: proc_boot, libc, libslog2, libnvivc, libnvsciipc libnvscievent, libnvos_s3_safety, libnvdvms_client

Macro Definition Documentation

NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_FATAL

#define NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_FATAL   0x2U

Indicates there is uncorrectable fatal error during PCIE operation.

Definition at line 347 of file nvsciipc.h.

NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_NONFATAL

#define NV_SCI_ASYNC_PCIE_AER_UNCORRECTABLE_NONFATAL   0x4U

Indicates there is uncorrectable non fatal error during PCIE operation.

Definition at line 349 of file nvsciipc.h.

NV_SCI_ASYNC_PCIE_EDMA_XFER_ERROR

#define NV_SCI_ASYNC_PCIE_EDMA_XFER_ERROR   0x1U

Indicates there is eDMA error during PCIE operation.

Definition at line 345 of file nvsciipc.h.

NV_SCI_ASYNC_PCIE_VALIDATION_ERROR

#define NV_SCI_ASYNC_PCIE_VALIDATION_ERROR   0x8U

Indicates there is validation error.

Definition at line 351 of file nvsciipc.h.

NV_SCI_IPC_EVENT_ASYNC_ERROR

#define NV_SCI_IPC_EVENT_ASYNC_ERROR   0x20U

Specifies the IPC asynchronous error event.

Definition at line 334 of file nvsciipc.h.

NV_SCI_IPC_EVENT_CONN_EST

#define NV_SCI_IPC_EVENT_CONN_EST   0x04U

Specifies the IPC connection established event.

Definition at line 328 of file nvsciipc.h.

NV_SCI_IPC_EVENT_CONN_EST_ALL

#define NV_SCI_IPC_EVENT_CONN_EST_ALL

Value:

    (NV_SCI_IPC_EVENT_CONN_EST | \
    NV_SCI_IPC_EVENT_WRITE | NV_SCI_IPC_EVENT_WRITE_EMPTY | \
    NV_SCI_IPC_EVENT_READ)

Specifies single event mask to check IPC connection establishment.

Definition at line 336 of file nvsciipc.h.

NV_SCI_IPC_EVENT_CONN_RESET

#define NV_SCI_IPC_EVENT_CONN_RESET   0x08U

Specifies the IPC connection reset event.

Definition at line 330 of file nvsciipc.h.

NV_SCI_IPC_EVENT_READ

#define NV_SCI_IPC_EVENT_READ   0x01U

Specifies the IPC read event.

Definition at line 324 of file nvsciipc.h.

NV_SCI_IPC_EVENT_WRITE

#define NV_SCI_IPC_EVENT_WRITE   0x02U

Specifies the IPC write event.

Definition at line 326 of file nvsciipc.h.

NV_SCI_IPC_EVENT_WRITE_EMPTY

#define NV_SCI_IPC_EVENT_WRITE_EMPTY   0x10U

Specifies the IPC write fifo empty event.

Definition at line 332 of file nvsciipc.h.

NVSCIIPC_INFINITE_WAIT

#define NVSCIIPC_INFINITE_WAIT   -1LL

infinite timeout for NvSciIpcWaitEventQnx()

Definition at line 341 of file nvsciipc.h.

NVSCIIPC_MAX_ENDPOINT_NAME

#define NVSCIIPC_MAX_ENDPOINT_NAME   64U

Specifies maximum Endpoint name length including null terminator.

Definition at line 320 of file nvsciipc.h.

Typedef Documentation

NvSciIpcEndpoint

typedef uint64_t NvSciIpcEndpoint

Handle to the NvSciIpc endpoint.

Definition at line 302 of file nvsciipc.h.

NvSciIpcEndpointInfo

typedef struct NvSciIpcEndpointInfo NvSciIpcEndpointInfo

Definition at line 304 of file nvsciipc.h.

Function Documentation

NvSciIpcCheckVersionCompatibility()

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

Parameters

[in]	majorVer	build major version.
[in]	minorVer	build minor version.
[out]	isCompatible	boolean value stating if loaded NvSciIpc library is compatible or not.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success if successful.
• NvSciError_BadParameter if any of the following occurs:
  • isCompatible is NULL

Precondition

None

Usage considerations

• 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

NvSciIpcCloseEndpoint()

void NvSciIpcCloseEndpoint

(

NvSciIpcEndpoint

handle

)

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.

NvSciIpcCloseEndpointSafe()

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.

Note

This API can be called in Init mode to release resources in error handling or to test functionality.

Parameters

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

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates a successful operation.
• NvSciError_BadParameter Indicates an invalid handle.
• NvSciError_NotInitialized Indicates NvSciIpc is uninitialized.
• NvSciError_NotPermitted Indicates incorrect API group usage.

Precondition

Invocation of NvSciIpcOpenEndpoint() or NvSciIpcOpenEndpointWithEventService() must be successful.

Deleting NvSciEventNotifier

• Before calling NvSciIpcCloseEndpointSafe(), event notifier associated with the closing endpoint through NvSciIpcGetEventNotifier() must be deleted by NvSciEventNotifier::Delete().

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 considerations

• 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: Yes

NvSciIpcDeinit()

void NvSciIpcDeinit

(

void

)

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.

Returns

void

Precondition

Invocation of NvSciIpcInit() must be successful.

Closing endpoints before deinitialization

• Before calling this API, the user shall ensure all existing opened endpoints are closed by NvSciIpcCloseEndpointSafe().

Usage considerations

• 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: Yes

NvSciIpcEnableNotification()

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 (e.g. poll, NvSciIpcWaitEventQnx, WaitForEvent, WaitForMultipleEvents etc.).

Note

This API supports Intra-VM and Inter-VM backend only.

Parameters

[in]	handle	NvSciIpc endpoint handle.
[in]	flag	flag to enable IPC notification.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates a successful operation.
• NvSciError_NotInitialized Indicates NvSciIpc is uninitialized.
• NvSciError_BadParameter Indicates an invalid handle.
• NvSciError_NotSupported Indicates API is not supported in provided endpoint backend type or OS environment.

Precondition

Invocation of NvSciIpcResetEndpointSafe() must be successful.

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 considerations

• 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

NvSciIpcGetAsyncErrors()

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

Parameters

[in]	handle	NvSciIpc endpoint handle.
[out]	mask	place holder to store bitwise OR errors

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates a successful operation.
• NvSciError_BadParameter Indicates an invalid handle or 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.

Precondition

Invocation of NvSciIpcGetEventSafe() must be successful.

Usage considerations

• 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

NvSciIpcGetEndpointInfo()

NvSciError NvSciIpcGetEndpointInfo	(	NvSciIpcEndpoint	handle,
		NvSciIpcEndpointInfo *	info
	)

Returns endpoint information.

Parameters

[in]	handle	NvSciIpc endpoint handle.
[out]	info	A pointer to NvSciIpcEndpointInfo object that this function copies the info to on success.

Returns

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.

Precondition

Invocation of NvSciIpcOpenEndpoint() or NvSciIpcOpenEndpointWithEventService() must be successful.

Usage considerations

• 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

NvSciIpcGetEvent()

NvSciError NvSciIpcGetEvent	(	NvSciIpcEndpoint	handle,
		uint32_t *	events
	)

Get Events.

Warning

This API is deprecated and returns NvSciError_NotSupported without doing anything in safety build. Use NvSciIpcGetEventSafe() instead of this.

NvSciIpcGetEventNotifier()

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.

Note

This API is only compatible with an endpoint that is opened with NvSciIpcOpenEndpointWithEventService()

Parameters

[in]	handle	NvSciIpc endpoint handle.
[out]	eventNotifier	A pointer to NvSciEventNotifier object on success.

Returns

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.

Precondition

Invocation of NvSciIpcOpenEndpointWithEventService() must be successful.

Usage considerations

• 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

NvSciIpcGetEventSafe()

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 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 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 established
• NV_SCI_IPC_EVENT_WRITE : IPC write
• NV_SCI_IPC_EVENT_READ : IPC read
• NV_SCI_IPC_EVENT_CONN_RESET : IPC connection reset
• NV_SCI_IPC_EVENT_WRITE_EMPTY : IPC write FIFO empty
• NV_SCI_IPC_EVENT_ASYNC_ERROR : Asynchronous error

NV_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 also mean that connection is established.

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:

1. In conjunction with the delivery of each NV_SCI_IPC_CONN_EST event.
2. Each time the endpoint's sending FIFO ceases to be full.

An NV_SCI_IPC_EVENT_READ event occurs on an endpoint:

1. In conjunction with the delivery of each NV_SCI_IPC_EVENT_CONN_EST event, if frames can already be read as of delivery.
2. Each time the endpoint's receiving FIFO ceases to be empty.

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, e.g. 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:

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

Parameters

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

Returns

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.

Precondition

NvSciIpcResetEndpointSafe() must be successful.

Usage considerations

• 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

NvSciIpcGetLinuxEventFd()

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

Parameters

handle	NvSciIpc endpoint handle
fd	A pointer to the endpoint file descriptor.

Returns

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.

Precondition

Invocation of NvSciIpcOpenEndpoint() or NvSciIpcOpenEndpointWithEventService() must be successful.

Usage considerations

• 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

NvSciIpcInit()

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.

Returns

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 considerations

• 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

NvSciIpcOpenEndpoint()

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.

Parameters

[in]	endpoint	The name of the NvSciIpc endpoint to open.
[out]	handle	A handle to the endpoint on success.

Returns

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 endpoint was not found.
• NvSciError_Busy Indicates the 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.

Precondition

Invocation of NvSciIpcInit() must be successful.

Usage considerations

• 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

NvSciIpcOpenEndpointWithEventService()

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.

Parameters

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

Returns

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 endpoint was not found.
• NvSciError_Busy Indicates the 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.

Precondition

Invocation of NvSciEventLoopServiceCreateSafe() must be successful. Invocation of NvSciIpcInit() must be successful.

Usage considerations

• 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

NvSciIpcRead()

NvSciError NvSciIpcRead	(	NvSciIpcEndpoint	handle,
		void *	buf,
		size_t	size,
		int32_t *	bytes
	)

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.

NvSciIpcReadAdvance()

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.

Note

This API is used together with NvSciIpcReadGetNextFrame(). Refer to precondition of NvSciIpcReadGetNextFrame()

Parameters

[in]

handle

The handle to the endpoint to read from.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates successful operation.
• NvSciError_BadParameter Indicates an invalid 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.

Precondition

NvSciIpcResetEndpointSafe() must be successful.

Usage considerations

• 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

NvSciIpcReadGetNextFrame()

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.

Parameters

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

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates a successful operation.
• NvSciError_BadParameter Indicates an invalid 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.

Precondition

NvSciIpcResetEndpointSafe() must be successful.

No overlapped read operation

• Between NvSciIpcReadGetNextFrame() and NvSciIpcReadAdvance(), the user must not perform any other NvSciIpc read operations with the same endpoint handle.

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.

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.

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 considerations

• 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

NvSciIpcReadSafe()

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.

Parameters

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

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates a successful operation.
• NvSciError_BadParameter Indicates an invalid handle or 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.

Precondition

NvSciIpcResetEndpointSafe() must be successful.

Usage considerations

• 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

NvSciIpcResetEndpoint()

void NvSciIpcResetEndpoint

(

NvSciIpcEndpoint

handle

)

Resets an endpoint.

Warning

This API is deprecated and returns without doing anything in safety build. Use NvSciIpcResetEndpointSafe() instead of this.

NvSciIpcResetEndpointSafe()

NvSciError NvSciIpcResetEndpointSafe

(

NvSciIpcEndpoint

handle

)

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

Parameters

[in]

handle

A handle to the endpoint to reset.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates a successful operation.
• NvSciError_BadParameter Indicates an invalid 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.

Precondition

Invocation of NvSciIpcSetQnxPulseParamSafe() or NvSciIpcGetLinuxEventFd() or NvSciIpcGetEventNotifier() must be successful.

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 considerations

• 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: Yes

NvSciIpcWrite()

NvSciError NvSciIpcWrite	(	NvSciIpcEndpoint	handle,
		const void *	buf,
		size_t	size,
		int32_t *	bytes
	)

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.

NvSciIpcWriteAdvance()

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.

Note

This API is used together with NvSciIpcWriteGetNextFrame(). Refer to precondition of NvSciIpcWriteGetNextFrame()

Parameters

[in]

handle

The handle to the endpoint to write to.

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates successful operation.
• NvSciError_BadParameter Indicates an invalid 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.

Precondition

NvSciIpcResetEndpointSafe() must be successful.

Populated with data

• The user shall ensure entire outgoing frame is populated with application data or filled with zeros prior call to NvScipcWriteAdvance().

Usage considerations

• 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

NvSciIpcWriteGetNextFrame()

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.

Parameters

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

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates successful operation.
• NvSciError_BadParameter Indicates an invalid 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.

Precondition

NvSciIpcResetEndpointSafe() must be successful.

No overlapped write operation

• Between NvSciIpcWriteGetNextFrame() and NvSciIpcWriteAdvance(), do not perform any other NvSciIpc write operations with the same endpoint handle.

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.

No read operation with pointer to write frame

• Do not read through a returned pointer of NvSciIpcWriteGetNextFrame().

Usage considerations

• 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

NvSciIpcWriteSafe()

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

Parameters

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

Returns

NvSciError, the completion code of the operation:

• NvSciError_Success Indicates a successful operation.
• NvSciError_BadParameter Indicates an invalid handle or 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.

Precondition

NvSciIpcResetEndpointSafe() must be successful.

Usage considerations

• 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