Icmsg multi-endpoint IPC library API

Multi-endpoint extension of icmsg IPC library. More...

Data Structures
struct	icmsg_me_data_t

Typedefs
typedef uint8_t	icmsg_me_ept_id_t

Functions
int	icmsg_me_init (const struct icmsg_config_t *conf, struct icmsg_me_data_t *data)
	Initialize an icmsg_me instance.
int	icmsg_me_open (const struct icmsg_config_t *conf, struct icmsg_me_data_t *data, const struct ipc_service_cb *cb, void *ctx)
	Open an icmsg_me instance.
void	icmsg_me_wait_for_icmsg_bind (struct icmsg_me_data_t *data)
	Wait until the underlying icmsg instance calls bound callback.
void	icmsg_me_icmsg_bound (struct icmsg_me_data_t *data)
	Notify the icmsg_me instance that the underlying icmsg was bound.
void	icmsg_me_received_data (struct icmsg_me_data_t *data, icmsg_me_ept_id_t id, const void *msg, size_t len)
	Notify the icmsg_me instance that data for an endpoint was received.
int	icmsg_me_set_empty_ept_cfg_slot (struct icmsg_me_data_t *data, const struct ipc_ept_cfg *ept_cfg, icmsg_me_ept_id_t *id)
	Set endpoint configuration in an empty endpoint slot.
int	icmsg_me_set_ept_cfg (struct icmsg_me_data_t *data, icmsg_me_ept_id_t id, const struct ipc_ept_cfg *ept_cfg)
	Set endpoint configuration in a selected endpoint slot.
int	icmsg_me_get_ept_cfg (struct icmsg_me_data_t *data, icmsg_me_ept_id_t id, const struct ipc_ept_cfg **ept_cfg)
	Get endpoint configuration from a selected endpoint slot.
void	icmsg_me_reset_ept_cfg (struct icmsg_me_data_t *data, icmsg_me_ept_id_t id)
	Reset endpoint configuration in a selected endpoint slot.
int	icmsg_me_send (const struct icmsg_config_t *conf, struct icmsg_me_data_t *data, icmsg_me_ept_id_t id, const void *msg, size_t len)
	Send a message to the remote icmsg_me endpoint.

Detailed Description

Multi-endpoint extension of icmsg IPC library.

Typedef Documentation

icmsg_me_ept_id_t

typedef uint8_t icmsg_me_ept_id_t

#include <zephyr/ipc/icmsg_me.h>

Function Documentation

icmsg_me_get_ept_cfg()

int icmsg_me_get_ept_cfg	(	struct icmsg_me_data_t *	data,
		icmsg_me_ept_id_t	id,
		const struct ipc_ept_cfg **	ept_cfg
	)

#include <zephyr/ipc/icmsg_me.h>

Get endpoint configuration from a selected endpoint slot.

When the icmsg_me instance receives data from a remote endpoint, it must get the endpoint configuration based on the id of the endpoint. This function is designed for this purpose.

If retrieved endpoint configuration is not set, ept_cfg points to NULL.

Parameters

[in,out]	data	Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.
[in]	id	The value uniquely identifyig endpoint.
[in]	ept_cfg	Configuration data of the endpoint with given id.

Return values

0	on success.
-ENOENT	when id is out of range of available slots.

icmsg_me_icmsg_bound()

void icmsg_me_icmsg_bound

(

struct icmsg_me_data_t *

data

)

#include <zephyr/ipc/icmsg_me.h>

Notify the icmsg_me instance that the underlying icmsg was bound.

The icmsg_me API users are responsible to implement the callback functions called by the underlying icmsg instance. One of the actions of the bound callback must be calling this function.

Parameters

[in,out]

data

Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.

icmsg_me_init()

int icmsg_me_init	(	const struct icmsg_config_t *	conf,
		struct icmsg_me_data_t *	data
	)

#include <zephyr/ipc/icmsg_me.h>

Initialize an icmsg_me instance.

This function is intended to be called during system initialization. It initializes the underlying icmsg instace as one of the initialization steps.

Parameters

[in]	conf	Structure containing configuration parameters for the underlying icmsg instance being created.
[in,out]	data	Structure containing run-time data used by the icmsg_me instance. The structure shall be filled with zeros when calling this function. The content of this structure must be preserved while the icmsg_me instance is active.

Return values

0	on success.
other	errno codes from dependent modules.

icmsg_me_open()

int icmsg_me_open	(	const struct icmsg_config_t *	conf,
		struct icmsg_me_data_t *	data,
		const struct ipc_service_cb *	cb,
		void *	ctx
	)

#include <zephyr/ipc/icmsg_me.h>

Open an icmsg_me instance.

Open an icmsg_me instance to be able to send and receive messages to a remote instance. This function is blocking until the handshake with the remote instance is completed. This function is intended to be called late in the initialization process, possibly from a thread which can be safely blocked while handshake with the remote instance is being pefromed.

Parameters

[in]	conf	Structure containing configuration parameters for the underlying icmsg instance.
[in,out]	data	Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.
[in]	cb	Structure containing callback functions to be called on events generated by this icmsg_me instance. The pointed memory must be preserved while the icmsg_me instance is active.
[in]	ctx	Pointer to context passed as an argument to callbacks.

Return values

0	on success.
other	errno codes from dependent modules.

icmsg_me_received_data()

void icmsg_me_received_data	(	struct icmsg_me_data_t *	data,
		icmsg_me_ept_id_t	id,
		const void *	msg,
		size_t	len
	)

#include <zephyr/ipc/icmsg_me.h>

Notify the icmsg_me instance that data for an endpoint was received.

The icmsg_me API users are responsible to implement the callback functions called by the underlying icmsg instance. If the data received by the icmsg instance contains data frame destined to one of the endpoints, this function must be called.

Parameters

[in,out]	data	Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.
[in]	id	The value identifyig the endpoint.
[in]	msg	Data frame received from the peer, stripped of the multi-endpoint header.
[in]	len	Size of the data pointed by msg.

icmsg_me_reset_ept_cfg()

void icmsg_me_reset_ept_cfg	(	struct icmsg_me_data_t *	data,
		icmsg_me_ept_id_t	id
	)

#include <zephyr/ipc/icmsg_me.h>

Reset endpoint configuration in a selected endpoint slot.

If handshake fails or an endpoint is disconnected, then configuration slot for given endpoint should be vacated. This function is intended to be used for this purpose.

Parameters

[in,out]	data	Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.
[in]	id	The value uniquely identifyig endpoint.

icmsg_me_send()

int icmsg_me_send	(	const struct icmsg_config_t *	conf,
		struct icmsg_me_data_t *	data,
		icmsg_me_ept_id_t	id,
		const void *	msg,
		size_t	len
	)

#include <zephyr/ipc/icmsg_me.h>

Send a message to the remote icmsg_me endpoint.

Parameters

[in]	conf	Structure containing configuration parameters for the underlying icmsg instance.
[in,out]	data	Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.
[in]	id	Id of the endpoint to use.
[in]	msg	Pointer to a buffer containing data to send.
[in]	len	Size of data in the msg buffer.

Return values

0	on success.
-EBADMSG	when the requested data to send is too big.
other	errno codes from dependent modules.

icmsg_me_set_empty_ept_cfg_slot()

int icmsg_me_set_empty_ept_cfg_slot	(	struct icmsg_me_data_t *	data,
		const struct ipc_ept_cfg *	ept_cfg,
		icmsg_me_ept_id_t *	id
	)

#include <zephyr/ipc/icmsg_me.h>

Set endpoint configuration in an empty endpoint slot.

During endpoint handshake the handshake initiator must select an id number and store endpoint metadata required to finalize handshake and maintain the connection. This function is a helper which stores the configuration in an empty configuration slot and provides the unique id value associated with the selected slot.

Note

This function is not reentrant for a single icmsg_me instance. It must be protected by the caller using mutex, critical section, spinlock, or similar solution. This function is reentrant for different icmsg_me instances. The protection scope might be limited to a single instance.

Parameters

[in,out]	data	Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.
[in]	ept_cfg	Configuration data of the endpoint for which the handshake procedure is being initiated.
[out]	id	The value uniquely identifyig this endpoint.

Return values

0	on success.
-ENOMEM	when there are no more empty endpoint configuration slots.

icmsg_me_set_ept_cfg()

int icmsg_me_set_ept_cfg	(	struct icmsg_me_data_t *	data,
		icmsg_me_ept_id_t	id,
		const struct ipc_ept_cfg *	ept_cfg
	)

#include <zephyr/ipc/icmsg_me.h>

Set endpoint configuration in a selected endpoint slot.

During endpoint handshake the handshake follower must store endpoint id and metadata required to finalize handshake and maintain the connection. This function is a helper which stores the configuration in a configuration slot associated with the id of the endpoint.

Parameters

[in,out]	data	Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.
[in]	id	The value uniquely identifyig this endpoint.
[in]	ept_cfg	Configuration data of the endpoint for which the handshake procedure is ongoing.

Return values

0	on success.
-ENOENT	when id is out of range of available slots.

icmsg_me_wait_for_icmsg_bind()

void icmsg_me_wait_for_icmsg_bind

(

struct icmsg_me_data_t *

data

)

#include <zephyr/ipc/icmsg_me.h>

Wait until the underlying icmsg instance calls bound callback.

This function blocks calling thread until the underlying icmsg connection is bound. If the connection was bound before this function is called, the function ends immediately without any delay.

This function is intended to be used in the endpoints handshake procedure to make sure that handshake is not performed until the icmsg channel is ready to pass handshake messages.

Parameters

[in,out]

data

Structure containing run-time data used by the icmsg_me instance. The structure is initialized with icmsg_me_init and its content must be preserved while the icmsg_me instance is active.