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:

The same thread
Different threads in the same process
The same process
Different processes in the same VM
Different VMs on the same SoC
Different SoCs

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.

Data Structures
struct	NvSciIpcEndpointInfo
	Defines information about the IPC endpoint. More...

Macros
#define	NVSCIIPC_MAX_ENDPOINT_NAME 32U
	Specifies maximum Endpoint name length. More...

#define	NV_SCI_IPC_EVENT_READ 1U
	Specifies the IPC read event. More...

#define	NV_SCI_IPC_EVENT_WRITE 2U
	Specifies the IPC write event. More...

#define	NV_SCI_IPC_EVENT_CONN_EST 4U
	Specifies the IPC connection established event. More...

#define	NV_SCI_IPC_EVENT_CONN_RESET 8U
	Specifies the IPC connection reset event. More...

#define	NV_SCI_IPC_EVENT_CONN_EST_ALL
	Specifies single event mask to check IPC connection establishment. More...

Typedefs
typedef uint64_t	NvSciIpcEndpoint
	Handle to the IPC endpoint. More...

Functions
NvSciError	NvSciIpcInit (void)
	Initializes the NvSciIpc library. More...

void	NvSciIpcDeinit (void)
	De-initializes the NvSciIpc library. More...

NvSciError	NvSciIpcOpenEndpoint (const char endpoint, NvSciIpcEndpoint handle)
	Opens an endpoint with the given name. More...

void	NvSciIpcCloseEndpoint (NvSciIpcEndpoint handle)
	Closes an endpoint with the given handle. More...

void	NvSciIpcResetEndpoint (NvSciIpcEndpoint handle)
	Resets an endpoint. More...

NvSciError	NvSciIpcRead (NvSciIpcEndpoint handle, void buf, size_t size, int32_t bytes)
	Returns the contents of the next frame from an endpoint. More...

NvSciError	NvSciIpcReadGetNextFrame (NvSciIpcEndpoint handle, void **buf)
	Returns a pointer to the location of the next frame from an endpoint. More...

NvSciError	NvSciIpcReadAdvance (NvSciIpcEndpoint handle)
	Removes the next frame from an endpoint. More...

NvSciError	NvSciIpcWrite (NvSciIpcEndpoint handle, const void buf, size_t size, int32_t bytes)
	Writes a new frame to the endpoint. More...

NvSciError	NvSciIpcWriteGetNextFrame (NvSciIpcEndpoint handle, void **buf)
	Returns a pointer to the location of the next frame for writing data. More...

NvSciError	NvSciIpcWriteAdvance (NvSciIpcEndpoint handle)
	Writes the next frame to the endpoint. More...

NvSciError	NvSciIpcGetEndpointInfo (NvSciIpcEndpoint handle, struct NvSciIpcEndpointInfo *info)
	Returns endpoint information. More...

NvSciError	NvSciIpcGetLinuxEventFd (NvSciIpcEndpoint handle, int32_t *fd)
	Returns the NvSciIpc file descriptor for a given endpoint. More...

NvSciError	NvSciIpcGetEvent (NvSciIpcEndpoint handle, uint32_t *events)
	Get Events. More...

NvSciError	NvSciIpcSetQnxPulseParam (NvSciIpcEndpoint handle, int32_t coid, int16_t pulsePriority, int16_t pulseCode, void *pulseValue)
	Sets the event pulse parameters for QNX. More...

Macro Definition Documentation

#define NV_SCI_IPC_EVENT_CONN_EST 4U

Specifies the IPC connection established event.

Definition at line 83 of file nvsciipc.h.

#define NV_SCI_IPC_EVENT_CONN_EST_ALL

Value:

(NV_SCI_IPC_EVENT_CONN_EST | \
	NV_SCI_IPC_EVENT_WRITE | \
	NV_SCI_IPC_EVENT_READ)

Specifies single event mask to check IPC connection establishment.

Definition at line 87 of file nvsciipc.h.

#define NV_SCI_IPC_EVENT_CONN_RESET 8U

Specifies the IPC connection reset event.

Definition at line 85 of file nvsciipc.h.

#define NV_SCI_IPC_EVENT_READ 1U

Specifies the IPC read event.

Definition at line 79 of file nvsciipc.h.

#define NV_SCI_IPC_EVENT_WRITE 2U

Specifies the IPC write event.

Definition at line 81 of file nvsciipc.h.

#define NVSCIIPC_MAX_ENDPOINT_NAME 32U

Specifies maximum Endpoint name length.

Definition at line 75 of file nvsciipc.h.

Typedef Documentation

typedef uint64_t NvSciIpcEndpoint

Handle to the IPC endpoint.

Definition at line 62 of file nvsciipc.h.

Function Documentation

void NvSciIpcCloseEndpoint ( NvSciIpcEndpoint handle )

Closes an endpoint with the given handle.

The function frees the NvSciIpc endpoint associated with the given handle.

Parameters

[in] handle A handle to the endpoint to close.

Returns: void

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : No
- Run time : No
- De-initialization: Yes

void NvSciIpcDeinit ( void )

De-initializes the NvSciIpc library.

This function cleans up the NvSciIpc endpoint internal database created by NvSciIpcInit().

Returns: void

Precondition: Invocation of NvSciIpcInit() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : No
Required Privileges(QNX): None
Operation Mode
- Initialization : No
- Run time : No
- De-initialization: Yes

NvSciError NvSciIpcGetEndpointInfo	(	NvSciIpcEndpoint	handle,
		struct 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.

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.

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : Yes
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : Yes
- Run time : Yes
- De-initialization: No

NvSciError NvSciIpcGetEvent	(	NvSciIpcEndpoint	handle,
		uint32_t *	events
	)

Get Events.

Returns a bitwise OR operation on new events that occurred since the last call to this function.

This function sets events to the result of a bitwise OR operation of zero or more NV_SCI_IPC_EVENT_* constants corresponding to all new events that have occurred on the endpoint since:

the 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 four 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

These may occur in arbitrary combinations, except for the following:

NV_SCI_IPC_EVENT_CONN_EST is always combined with NV_SCI_IPC_EVENT_WRITE.
NV_SCI_IPC_EVENT_CONN_RESET cannot be combined with any other events.

There are seven possible event combinations:

0
NV_SCI_IPC_EVENT_CONN_EST and NV_SCI_IPC_EVENT_WRITE
NV_SCI_IPC_EVENT_CONN_EST and NV_SCI_IPC_EVENT_WRITE and NV_SCI_IPC_EVENT_READ
NV_SCI_IPC_EVENT_READ
NV_SCI_IPC_EVENT_WRITE
NV_SCI_IPC_EVENT_WRITE and NV_SCI_IPC_EVENT_READ
NV_SCI_IPC_EVENT_CONN_RESET

An NV_SCI_IPC_EVENT_CONN_EST event occurs on an endpoint each time a connection is established through the endpoint (between the endpoint and the other end of the corresponding channel).

An NV_SCI_IPC_EVENT_WRITE event occurs on an endpoint:

In conjunction with the delivery of each NV_SCI_IPC_CONN_EST event.
Each time the endpoint ceases to be full after a prior NvSciIpcWrite* call returned NvSciError_InsufficientMemory. Note however that an implementation is permitted to delay the delivery of this type of NV_SCI_IPC_EVENT_WRITE event, e.g., for purposes of improving throughput.

An NV_SCI_IPC_EVENT_READ event occurs on an endpoint:

In conjunction with the delivery of each NV_SCI_IPC_EVENT_CONN_EST event, if frames can already be read as of delivery.
Each time the endpoint ceases to be empty after a prior NvSciRead* call returned NvSciError_InsufficientMemory. Note however that an implementation is permitted to delay the delivery of this type of NV_SCI_IPC_EVENT_READ event, e.g., for purposes of improving throughput.

An NV_SCI_IPC_EVENT_CONN_RESET event occurs on an endpoint when the user calls NvSciIpcResetEndpoint.

Parameters

[in]	handle	NvSciIpc endpoint handle.
[out]	events	A pointer to the variable into which to store the bitwise OR result of new events.

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.

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : Yes
- Run time : Yes
- De-initialization: No

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

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : No
Required Privileges(QNX): None
Operation Mode
- Initialization : Yes
- Run time : No
- De-initialization: No

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.

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.

Precondition: Invocation of NvSciIpcInit() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): PROCMGR_AID_MEM_PHYS
Operation Mode
- Initialization : Yes
- Run time : No
- De-initialization: No

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

Returns the contents of the next frame from an endpoint.

This function removes the next frame and copies its contents into a buffer. If the destination buffer is smaller than the configured frame size of the endpoint, the trailing bytes are discarded.

This is a non-blocking call. The endpoint must not be empty. If the endpoint was previously full, then the function notifies the remote endpoint.

This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint.

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. If size is greater than the size of the destination buffer, the remaining bytes are discarded.
[out]	bytes	The number of bytes read.

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 the endpoint is empty and the read operation aborted.
NvSciError_TooBig Indicates size is larger than the configured frame size of the endpoint.
NvSciError_ConnectionReset Indicates the endpoint is being reset.

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : No
- Run time : Yes
- De-initialization: No

NvSciError NvSciIpcReadAdvance ( NvSciIpcEndpoint handle )

Removes the next frame from an endpoint.

This is a non-blocking call. The endpoint must not be empty. If the endpoint was previously full, then this function notifies the remote endpoint.

This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint.

Parameters

[in] handle The handle to the endpoint to read from.

Returns

NvSciError, the completion code of the operation:

NvSciError_Success Indicates the frame was removed successfully.
NvSciError_BadParameter Indicates an invalid handle.
NvSciError_NotInitialized Indicates NvSciIpc is uninitialized.
NvSciError_InsufficientMemory Indicates the endpoint 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.

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : No
- Run time : Yes
- De-initialization: No

NvSciError NvSciIpcReadGetNextFrame	(	NvSciIpcEndpoint	handle,
		void **	buf
	)

Returns a pointer to the location of the next frame from an endpoint.

This is a non-blocking call.

This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint.

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.

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

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : No
- Run time : Yes
- De-initialization: No

void NvSciIpcResetEndpoint ( NvSciIpcEndpoint handle )

Resets an endpoint.

Initiates a reset on the endpoint and notifies the remote endpoint. Applications must call this function and complete the reset operation before using the endpoint for communication.

Parameters

[in] handle A handle to the endpoint to reset.

Returns: void

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : Yes
- Run time : No
- De-initialization: No

NvSciError NvSciIpcSetQnxPulseParam	(	NvSciIpcEndpoint	handle,
		int32_t	coid,
		int16_t	pulsePriority,
		int16_t	pulseCode,
		void *	pulseValue
	)

Sets the event pulse parameters for QNX.

This API is specific to QNX OS.

When a notification from a peer endpoint is available, the NvSciIpc library sends a pulse message to the application. This API is to connect coid to the endpoint, plug OS event notification and set pulse parameters (pulsePriority, pulseCode and pulseValue), thereby enabling the application to receive peer notifications from the NvSciIpc library. An application can receive notifications from a peer endpoint using MsgReceivePulse_r() which is blocking call.

Prior to calling this function, both ChannelCreate_r() and ConnectAttach_r() must be called in the application to obtain the value for coid to pass to this function.

To use the priority of the calling thread, set pulsePriority to SIGEV_PULSE_PRIO_INHERIT(-1). The priority must fall within the valid range, which can be determined by calling sched_get_priority_min() and sched_get_priority_max().

Applications can define any value per endpoint for pulseCode and pulseValue. pulseCode will be used by NvSciIpc to signal IPC events and should be reserved for this purpose by the application. pulseValue can be used for the application cookie data.

Parameters

[in]	handle	NvSciIpc endpoint handle.
[in]	coid	The connection ID created from calling `ConnectAttach_r()`.
[in]	pulsePriority	The value for pulse priority.
[in]	pulseCode	The 8-bit positive pulse code specified by the user. The values must be between `_PULSE_CODE_MINAVAIL` and `_PULSE_CODE_MAXAVAIL`
[in]	pulseValue	A pointer to the user-defined pulse value.

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.

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): PROCMGR_AID_INTERRUPTEVENT
Operation Mode
- Initialization : Yes
- Run time : No
- De-initialization: No

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

Writes a new frame to the endpoint.

If space is available in the endpoint, this function posts a new frame, copying the contents from the provided data buffer. If size is less than the frame size, then the remaining bytes of the frame are undefined.

This is a non-blocking call. If the endpoint was previously empty, then the function notifies the remote endpoint.

This operation cannot proceed if the endpoint is being reset.

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.
[out]	bytes	The number of bytes written.

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 the endpoint is full and the write operation aborted.
NvSciError_TooBig Indicates size is larger than the configured frame size of the endpoint.
NvSciError_ConnectionReset Indicates the endpoint is being reset.

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : No
- Run time : Yes
- De-initialization: No

NvSciError NvSciIpcWriteAdvance ( NvSciIpcEndpoint handle )

Writes the next frame to the endpoint.

This is a non-blocking call. If the endpoint is not full, then post the next frame. If the endpoint was previously empty, then this function notifies the remote endpoint.

This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint.

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

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : No
- Run time : Yes
- De-initialization: No

NvSciError NvSciIpcWriteGetNextFrame	(	NvSciIpcEndpoint	handle,
		void **	buf
	)

Returns a pointer to the location of the next frame for writing data.

This is a non-blocking call. The endpoint must not be full.

This operation cannot proceed if the endpoint is being reset. However, if the remote endpoint has called NvSciIpcResetEndpoint(), calls to this function can still succeed until the next event notification on the local endpoint.

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.

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

Precondition: Invocation of NvSciIpcOpenEndpoint() should be successful.

Note

Allowed context for the API call
- Interrupt : No
- Signal handler: Yes
- Thread : Yes
Is thread safe : Yes
Required Privileges(QNX): None
Operation Mode
- Initialization : No
- Run time : Yes
- De-initialization: No

NVIDIA DRIVE OS Linux SDK API Reference

5.1.12.0 Release

Detailed Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation