IPC service APIs

IPC Service API. More...

Data Structures
struct	ipc_service_cb
	Event callback structure. More...
struct	ipc_ept
	Endpoint instance. More...
struct	ipc_ept_cfg
	Endpoint configuration structure. More...
struct	ipc_service_backend
	IPC Service backend. More...

Functions
int	ipc_service_open_instance (const struct device *instance)
	Open an instance. More...
int	ipc_service_register_endpoint (const struct device *instance, struct ipc_ept *ept, const struct ipc_ept_cfg *cfg)
	Register IPC endpoint onto an instance. More...
int	ipc_service_send (struct ipc_ept *ept, const void *data, size_t len)
	Send data using given IPC endpoint. More...

Detailed Description

IPC Service API.

Some terminology:

• INSTANCE: an instance is the external representation of a physical communication channel between two domains / CPUs.

  The actual implementation and internal representation of the instance is peculiar to each backend. For example for OpenAMP-based backends, an instance is usually represented by a shared memory region and a couple of IPM devices for RX/TX signalling.

  It's important to note that an instance per se is not used to send data between domains / CPUs. To send and receive data the user have to create (register) an endpoint in the instance connecting the two domains of interest.

  It's possible to have zero or multiple endpoints in one single instance, each one used to exchange data, possibly with different priorities.

  The creation of the instances is left to the backend (usually at init time), while the registration of the endpoints is left to the user (usually at run time).

• ENDPOINT: an endpoint is the entity the user must use to send / receive data between two domains (connected by the instance). An endpoint is always associated to an instance.
• BACKEND: the backend must take care of at least two different things:

       1) creating the instances at init time
       2) creating / registering the endpoints onto an instance at run
          time when requested by the user
  
       The API doesn't mandate a way for the backend to create the
       instances but itis strongly recommended to use the DT to retrieve
       the configuration parameters for the instance.
  

Function Documentation

ipc_service_open_instance()

int ipc_service_open_instance

(

const struct device *

instance

)

#include <include/ipc/ipc_service.h>

Open an instance.

Function to be used to open an instance before being able to register a new endpoint on it.

Return values

-EINVAL	when instance configuration is invalid.
-EIO	when no backend is registered.
-EALREADY	when the instance is already opened (or being opened).
0	on success or when not implemented on the backend (not needed).
other	errno codes depending on the implementation of the backend.

ipc_service_register_endpoint()

int ipc_service_register_endpoint	(	const struct device *	instance,
		struct ipc_ept *	ept,
		const struct ipc_ept_cfg *	cfg
	)

#include <include/ipc/ipc_service.h>

Register IPC endpoint onto an instance.

Registers IPC endpoint onto an instance to enable communication with a remote device.

The same function registers endpoints for both host and remote devices.

Parameters

instance	Instance to register the endpoint onto.
ept	Endpoint object.
cfg	Endpoint configuration.

Return values

-EIO	when no backend is registered.
-EINVAL	when instance, endpoint or configuration is invalid.
-EBUSY	when the instance is busy.
0	on success.
other	errno codes depending on the implementation of the backend.

ipc_service_send()

int ipc_service_send	(	struct ipc_ept *	ept,
		const void *	data,
		size_t	len
	)

#include <include/ipc/ipc_service.h>

Send data using given IPC endpoint.

Parameters

ept	Registered endpoint by ipc_service_register_endpoint.
data	Pointer to the buffer to send.
len	Number of bytes to send.

Return values

-EIO	when no backend is registered or send hook is missing from backend.
-EINVAL	when instance or endpoint is invalid.
-EBADMSG	when the message is invalid.
-EBUSY	when the instance is busy.
0	on success.
other	errno codes depending on the implementation of the backend.