Icmsg IPC library API

Icmsg IPC library API. More...

Data Structures
struct	icmsg_config_t
struct	icmsg_data_t

Enumerations
enum	icmsg_state {   ICMSG_STATE_OFF , ICMSG_STATE_INITIALIZING_SID_DISABLED , ICMSG_STATE_INITIALIZING_SID_ENABLED , ICMSG_STATE_INITIALIZING_SID_DETECT ,   ICMSG_STATE_DISCONNECTED , ICMSG_STATE_CONNECTED_SID_DISABLED , ICMSG_STATE_CONNECTED_SID_ENABLED }
enum	icmsg_unbound_mode { ICMSG_UNBOUND_MODE_DISABLE = ICMSG_STATE_INITIALIZING_SID_DISABLED , ICMSG_UNBOUND_MODE_ENABLE = ICMSG_STATE_INITIALIZING_SID_ENABLED , ICMSG_UNBOUND_MODE_DETECT = ICMSG_STATE_INITIALIZING_SID_DETECT }

Functions
int	icmsg_open (const struct icmsg_config_t *conf, struct icmsg_data_t *dev_data, const struct ipc_service_cb *cb, void *ctx)
	Open an icmsg instance.
int	icmsg_close (const struct icmsg_config_t *conf, struct icmsg_data_t *dev_data)
	Close an icmsg instance.
int	icmsg_send (const struct icmsg_config_t *conf, struct icmsg_data_t *dev_data, const void *msg, size_t len)
	Send a message to the remote icmsg instance.

Detailed Description

Icmsg IPC library API.

Enumeration Type Documentation

icmsg_state

enum icmsg_state

#include <zephyr/ipc/icmsg.h>

Enumerator
ICMSG_STATE_OFF	Instance is not initialized yet. In this state: sending will fail, opening allowed.
ICMSG_STATE_INITIALIZING_SID_DISABLED	Instance is initializing without session handshake. In this state: sending will fail, opening will fail.
ICMSG_STATE_INITIALIZING_SID_ENABLED	Instance is initializing with session handshake. It is waiting for remote to acknowledge local session id. In this state: sending will fail, opening is allowed (local session id will change, so the remote may get unbound() callback).
ICMSG_STATE_INITIALIZING_SID_DETECT	Instance is initializing with detection of session handshake support on remote side. It is waiting for remote to acknowledge local session id or to send magic bytes. In this state: sending will fail, opening is allowed (local session id will change, so the remote may get unbound() callback if it supports it).
ICMSG_STATE_DISCONNECTED	Instance was closed on remote side. The unbound() callback was send on local side. In this state: sending will be silently discarded (there may be outdated sends), opening is allowed.
ICMSG_STATE_CONNECTED_SID_DISABLED	Instance is connected without session handshake support. In this state: sending will be successful, opening will fail.
ICMSG_STATE_CONNECTED_SID_ENABLED	Instance is connected with session handshake support. In this state: sending will be successful, opening is allowed (session will change and remote will get unbound() callback).

icmsg_unbound_mode

enum icmsg_unbound_mode

#include <zephyr/ipc/icmsg.h>

Enumerator
ICMSG_UNBOUND_MODE_DISABLE
ICMSG_UNBOUND_MODE_ENABLE
ICMSG_UNBOUND_MODE_DETECT

Function Documentation

icmsg_close()

int icmsg_close	(	const struct icmsg_config_t *	conf,
		struct icmsg_data_t *	dev_data )

#include <zephyr/ipc/icmsg.h>

Close an icmsg instance.

Closing an icmsg instance results in releasing all resources used by given instance including the shared memory regions and mbox devices.

Parameters

[in]	conf	Structure containing configuration parameters for the icmsg instance being closed. Its content must be the same as used for creating this instance with icmsg_open.
[in,out]	dev_data	Structure containing run-time data used by the icmsg instance.

Return values

0	on success.
other	errno codes from dependent modules.

icmsg_open()

int icmsg_open	(	const struct icmsg_config_t *	conf,
		struct icmsg_data_t *	dev_data,
		const struct ipc_service_cb *	cb,
		void *	ctx )

#include <zephyr/ipc/icmsg.h>

Open an icmsg instance.

Open an icmsg 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 performed.

Parameters

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

Return values

0	on success.
-EALREADY	when the instance is already opened.
other	errno codes from dependent modules.

icmsg_send()

int icmsg_send	(	const struct icmsg_config_t *	conf,
		struct icmsg_data_t *	dev_data,
		const void *	msg,
		size_t	len )

#include <zephyr/ipc/icmsg.h>

Send a message to the remote icmsg instance.

Parameters

[in]	conf	Structure containing configuration parameters for the icmsg instance.
[in,out]	dev_data	Structure containing run-time data used by the icmsg instance.
[in]	msg	Pointer to a buffer containing data to send.
[in]	len	Size of data in the msg buffer.

Return values

Number	of sent bytes.
-EBUSY	when the instance has not finished handshake with the remote instance.
-ENODATA	when the requested data to send is empty.
-EBADMSG	when the requested data to send is too big.
-ENOBUFS	when there are no TX buffers available.
other	errno codes from dependent modules.