#include <stddef.h>
#include <stdint.h>
#include <zephyr/kernel.h>
#include <zephyr/drivers/mbox.h>
#include <zephyr/ipc/ipc_service.h>
#include <zephyr/sys/atomic.h>
#include <zephyr/sys/spsc_pbuf.h>

Data Structures
struct	icmsg_config_t

struct	icmsg_data_t

Enumerations
enum	icmsg_state { ICMSG_STATE_OFF , ICMSG_STATE_BUSY , ICMSG_STATE_READY }

Functions
int	icmsg_init (const struct icmsg_config_t conf, struct icmsg_data_t dev_data)
	Initialize an icmsg instance. More...

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

int	icmsg_close (const struct icmsg_config_t conf, struct icmsg_data_t dev_data)
	Close an icmsg instance. More...

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

int	icmsg_get_tx_buffer (const struct icmsg_config_t conf, struct icmsg_data_t dev_data, void *data, size_t size)
	Get an empty TX buffer to be sent using icmsg_send_nocopy. More...

int	icmsg_drop_tx_buffer (const struct icmsg_config_t conf, struct icmsg_data_t dev_data, const void *data)
	Drop and release a TX buffer. More...

int	icmsg_send_nocopy (const struct icmsg_config_t conf, struct icmsg_data_t dev_data, const void *msg, size_t len)
	Send a message from a buffer obtained by icmsg_get_tx_buffer to the remote icmsg instance. More...

int	icmsg_clear_tx_memory (const struct icmsg_config_t *conf)
	Clear memory in TX buffer. More...

int	icmsg_clear_rx_memory (const struct icmsg_config_t *conf)
	Clear memory in RX buffer. More...

Enumeration Type Documentation

◆ icmsg_state

enum icmsg_state

Enumerator
ICMSG_STATE_OFF
ICMSG_STATE_BUSY
ICMSG_STATE_READY

Function Documentation

◆ icmsg_clear_rx_memory()

int icmsg_clear_rx_memory ( const struct icmsg_config_t * conf )

Clear memory in RX buffer.

This function is intended to be called at an early stage of boot process, before the instance is initialized and before the remote core has started.

Parameters

[in] conf Structure containing configuration parameters for the icmsg instance being created.

Return values

0	on success.

◆ icmsg_clear_tx_memory()

int icmsg_clear_tx_memory ( const struct icmsg_config_t * conf )

Clear memory in TX buffer.

This function is intended to be called at an early stage of boot process, before the instance is initialized and before the remote core has started.

Parameters

[in] conf Structure containing configuration parameters for the icmsg instance being created.

Return values

0	on success.

◆ icmsg_close()

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

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. The structure is initialized with icmsg_init and its content must be preserved while the icmsg instance is active.

Return values

0	on success.
other	errno codes from dependent modules.

◆ icmsg_drop_tx_buffer()

int icmsg_drop_tx_buffer	(	const struct icmsg_config_t *	conf,
		struct icmsg_data_t *	dev_data,
		const void *	data
	)

Drop and release a TX buffer.

Drop and release a TX buffer. It is possible to drop only TX buffers obtained by using icmsg_get_tx_buffer.

Parameters

[in]	conf	Structure containing configuration parameters for the icmsg instance being created.
[in,out]	dev_data	Structure containing run-time data used by the icmsg instance. The structure is initialized with icmsg_init and its content must be preserved while the icmsg instance is active.
[in]	data	Pointer to the TX buffer.

Return values

-EALREADY	when the buffer was already dropped.
-ENXIO	when the buffer was not obtained using ipc_service_get_tx_buffer
0	on success.

◆ icmsg_get_tx_buffer()

int icmsg_get_tx_buffer	(	const struct icmsg_config_t *	conf,
		struct icmsg_data_t *	dev_data,
		void **	data,
		size_t *	size
	)

Get an empty TX buffer to be sent using icmsg_send_nocopy.

This function can be called to get an empty TX buffer so that the application can directly put its data into the sending buffer avoiding copy performed by the icmsg library.

It is the application responsibility to correctly fill the allocated TX buffer with data and passing correct parameters to icmsg_send_nocopy function to perform data no-copy-send mechanism.

The size parameter can be used to request a buffer with a certain size:

if the size can be accommodated the function returns no errors and the buffer is allocated
if the requested size is too big, the function returns -ENOMEM and the the buffer is not allocated.
if the requested size is '0' the buffer is allocated with the maximum allowed size.

In all the cases on return the size parameter contains the maximum size for the returned buffer.

When the function returns no errors, the buffer is intended as allocated and it is released under one of two conditions: (1) when sending the buffer using icmsg_send_nocopy (and in this case the buffer is automatically released by the backend), (2) when using icmsg_drop_tx_buffer on a buffer not sent.

Parameters

[in]	conf	Structure containing configuration parameters for the icmsg instance being created.
[in,out]	dev_data	Structure containing run-time data used by the icmsg instance. The structure is initialized with icmsg_init and its content must be preserved while the icmsg instance is active.
[out]	data	Pointer to the empty TX buffer.
[in,out]	size	Pointer to store the requested TX buffer size. If the function returns -ENOMEM, this parameter returns the maximum allowed size.

Return values

-ENOBUFS	when there are no TX buffers available.
-EALREADY	when a buffer was already claimed and not yet released.
-ENOMEM	when the requested size is too big (and the size parameter contains the maximum allowed size).
0	on success.

◆ icmsg_init()

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

Initialize an icmsg instance.

This function is intended to be called during system initialization.

Parameters

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

Return values

0	on success.
-EALREADY	when the instance is already opened.
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
	)

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

Parameters

[in]	conf	Structure containing configuration parameters for the icmsg instance being created.
[in,out]	dev_data	Structure containing run-time data used by the icmsg instance. The structure is initialized with icmsg_init and its content must be preserved while the icmsg instance is active.
[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
	)

Send a message to the remote icmsg instance.

Parameters

[in]	conf	Structure containing configuration parameters for the icmsg instance being created.
[in,out]	dev_data	Structure containing run-time data used by the icmsg instance. The structure is initialized with icmsg_init and its content must be preserved while the icmsg instance is active.
[in]	msg	Pointer to a buffer containing data to send.
[in]	len	Size of data in the `msg` buffer.

Return values

0	on success.
-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.

◆ icmsg_send_nocopy()

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

Send a message from a buffer obtained by icmsg_get_tx_buffer to the remote icmsg instance.

This is equivalent to icmsg_send but in this case the TX buffer must have been obtained by using icmsg_get_tx_buffer.

The API user has to take the responsibility for getting the TX buffer using icmsg_get_tx_buffer and filling the TX buffer with the data.

After the icmsg_send_nocopy function is issued the TX buffer is no more owned by the sending task and must not be touched anymore unless the function fails and returns an error.

If this function returns an error, icmsg_drop_tx_buffer can be used to drop the TX buffer.

Parameters

[in]	conf	Structure containing configuration parameters for the icmsg instance being created.
[in,out]	dev_data	Structure containing run-time data used by the icmsg instance. The structure is initialized with icmsg_init and its content must be preserved while the icmsg instance is active.
[in]	msg	Pointer to a buffer containing data to send.
[in]	len	Size of data in the `msg` buffer.

Return values

0	on success.
-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.
-ENXIO	when the buffer was not obtained using ipc_service_get_tx_buffer
other	errno codes from dependent modules.

Data Structures

Enumerations

Functions

Enumeration Type Documentation

◆ icmsg_state

Function Documentation

◆ icmsg_clear_rx_memory()

◆ icmsg_clear_tx_memory()

◆ icmsg_close()

◆ icmsg_drop_tx_buffer()

◆ icmsg_get_tx_buffer()

◆ icmsg_init()

◆ icmsg_open()

◆ icmsg_send()

◆ icmsg_send_nocopy()