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

Functions
int	ipc_service_open_instance (const struct device *instance)
	Open an instance.

int	ipc_service_close_instance (const struct device *instance)
	Close an instance.

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.

int	ipc_service_deregister_endpoint (struct ipc_ept *ept)
	Deregister an IPC endpoint from its instance.

int	ipc_service_send (struct ipc_ept ept, const void data, size_t len)
	Send data using given IPC endpoint.

int	ipc_service_get_tx_buffer_size (struct ipc_ept *ept)
	Get the TX buffer size.

int	ipc_service_get_tx_buffer (struct ipc_ept ept, void data, uint32_t size, k_timeout_t wait)
	Get an empty TX buffer to be sent using ipc_service_send_nocopy.

int	ipc_service_drop_tx_buffer (struct ipc_ept ept, const void data)
	Drop and release a TX buffer.

int	ipc_service_send_nocopy (struct ipc_ept ept, const void data, size_t len)
	Send data in a TX buffer reserved by ipc_service_get_tx_buffer using the given IPC endpoint.

int	ipc_service_hold_rx_buffer (struct ipc_ept ept, void data)
	Holds the RX buffer for usage outside the receive callback.

int	ipc_service_release_rx_buffer (struct ipc_ept ept, void data)
	Release the RX buffer for future reuse.

Detailed Description

IPC Service API.

Function Documentation

◆ ipc_service_close_instance()

int ipc_service_close_instance ( const struct device * instance )

#include <include/zephyr/ipc/ipc_service.h>

Close an instance.

Function to be used to close an instance. All bounded endpoints must be deregistered using ipc_service_deregister_endpoint before this is called.

Parameters

[in] instance Instance to close.

Return values

-EINVAL	when instance configuration is invalid.
-EIO	when no backend is registered.
-EALREADY	when the instance is not already opened.
-EBUSY	when an endpoint exists that hasn't been deregistered
0	on success or when not implemented on the backend (not needed).
other	errno codes depending on the implementation of the backend.

◆ ipc_service_deregister_endpoint()

int ipc_service_deregister_endpoint ( struct ipc_ept * ept )

#include <include/zephyr/ipc/ipc_service.h>

Deregister an IPC endpoint from its instance.

Deregisters an IPC endpoint from its instance.

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

Parameters

[in] ept Endpoint object.

Return values

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

◆ ipc_service_drop_tx_buffer()

int ipc_service_drop_tx_buffer	(	struct ipc_ept *	ept,
		const void *	data
	)

#include <include/zephyr/ipc/ipc_service.h>

Drop and release a TX buffer.

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

Parameters

[in]	ept	Registered endpoint by ipc_service_register_endpoint.
[in]	data	Pointer to the TX buffer.

Return values

-EIO	when no backend is registered or send hook is missing from backend.
-EINVAL	when instance or endpoint is invalid.
-ENOENT	when the endpoint is not registered with the instance.
-ENOTSUP	when this is not supported by backend.
-EALREADY	when the buffer was already dropped.
-ENXIO	when the buffer was not obtained using ipc_service_get_tx_buffer
0	on success.
other	errno codes depending on the implementation of the backend.

◆ ipc_service_get_tx_buffer()

int ipc_service_get_tx_buffer	(	struct ipc_ept *	ept,
		void **	data,
		uint32_t *	size,
		k_timeout_t	wait
	)

#include <include/zephyr/ipc/ipc_service.h>

Get an empty TX buffer to be sent using ipc_service_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 without copy from an application buffer.

It is the application responsibility to correctly fill the allocated TX buffer with data and passing correct parameters to ipc_service_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 two conditions: (1) when sending the buffer using ipc_service_send_nocopy (and in this case the buffer is automatically released by the backend), (2) when using ipc_service_drop_tx_buffer on a buffer not sent.

Parameters

[in]	ept	Registered endpoint by ipc_service_register_endpoint.
[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.
[in]	wait	Timeout waiting for an available TX buffer.

Return values

-EIO	when no backend is registered or send hook is missing from backend.
-EINVAL	when instance or endpoint is invalid.
-ENOENT	when the endpoint is not registered with the instance.
-ENOTSUP	when the operation or the timeout is not supported by backend.
-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.
other	errno codes depending on the implementation of the backend.

◆ ipc_service_get_tx_buffer_size()

int ipc_service_get_tx_buffer_size ( struct ipc_ept * ept )

#include <include/zephyr/ipc/ipc_service.h>

Get the TX buffer size.

Get the maximal size of a buffer which can be obtained by ipc_service_get_tx_buffer

Parameters

[in] ept Registered endpoint by ipc_service_register_endpoint.

Return values

-EIO	when no backend is registered or send hook is missing from backend.
-EINVAL	when instance or endpoint is invalid.
-ENOENT	when the endpoint is not registered with the instance.
-ENOTSUP	when the operation is not supported by backend.
size	TX buffer size on success.
other	errno codes depending on the implementation of the backend.

◆ ipc_service_hold_rx_buffer()

int ipc_service_hold_rx_buffer	(	struct ipc_ept *	ept,
		void *	data
	)

#include <include/zephyr/ipc/ipc_service.h>

Holds the RX buffer for usage outside the receive callback.

Calling this function prevents the receive buffer from being released back to the pool of shmem buffers. This function can be called in the receive callback when the user does not want to copy the message out in the callback itself.

After the message is processed, the application must release the buffer using the ipc_service_release_rx_buffer function.

Parameters

[in]	ept	Registered endpoint by ipc_service_register_endpoint.
[in]	data	Pointer to the RX buffer to hold.

Return values

-EIO	when no backend is registered or release hook is missing from backend.
-EINVAL	when instance or endpoint is invalid.
-ENOENT	when the endpoint is not registered with the instance.
-EALREADY	when the buffer data has been hold already.
-ENOTSUP	when this is not supported by backend.
0	on success.
other	errno codes depending on the implementation of the backend.

◆ ipc_service_open_instance()

int ipc_service_open_instance ( const struct device * instance )

#include <include/zephyr/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.

Parameters

[in] instance Instance to open.

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/zephyr/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

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

Note: Keep the variable pointed by cfg alive when endpoint is in use.

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_release_rx_buffer()

int ipc_service_release_rx_buffer	(	struct ipc_ept *	ept,
		void *	data
	)

#include <include/zephyr/ipc/ipc_service.h>

Release the RX buffer for future reuse.

When supported by the backend, this function can be called after the received message has been processed and the buffer can be marked as reusable again.

It is possible to release only RX buffers on which ipc_service_hold_rx_buffer was previously used.

Parameters

[in]	ept	Registered endpoint by ipc_service_register_endpoint.
[in]	data	Pointer to the RX buffer to release.

Return values

-EIO	when no backend is registered or release hook is missing from backend.
-EINVAL	when instance or endpoint is invalid.
-ENOENT	when the endpoint is not registered with the instance.
-EALREADY	when the buffer data has been already released.
-ENOTSUP	when this is not supported by backend.
-ENXIO	when the buffer was not hold before using ipc_service_hold_rx_buffer
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/zephyr/ipc/ipc_service.h>

Send data using given IPC endpoint.

Parameters

[in]	ept	Registered endpoint by ipc_service_register_endpoint.
[in]	data	Pointer to the buffer to send.
[in]	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.
-ENOENT	when the endpoint is not registered with the instance.
-EBADMSG	when the data is invalid (i.e. invalid data format, invalid length, ...)
-EBUSY	when the instance is busy.
-ENOMEM	when no memory / buffers are available.
bytes	number of bytes sent.
other	errno codes depending on the implementation of the backend.

◆ ipc_service_send_nocopy()

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

#include <include/zephyr/ipc/ipc_service.h>

Send data in a TX buffer reserved by ipc_service_get_tx_buffer using the given IPC endpoint.

This is equivalent to ipc_service_send but in this case the TX buffer has been obtained by using ipc_service_get_tx_buffer.

The application has to take the responsibility for getting the TX buffer using ipc_service_get_tx_buffer and filling the TX buffer with the data.

After the ipc_service_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, ipc_service_drop_tx_buffer can be used to drop the TX buffer.

Parameters

[in]	ept	Registered endpoint by ipc_service_register_endpoint.
[in]	data	Pointer to the buffer to send obtained by ipc_service_get_tx_buffer.
[in]	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.
-ENOENT	when the endpoint is not registered with the instance.
-EBADMSG	when the data is invalid (i.e. invalid data format, invalid length, ...)
-EBUSY	when the instance is busy.
bytes	number of bytes sent.
other	errno codes depending on the implementation of the backend.

Data Structures

Functions

Detailed Description

Function Documentation

◆ ipc_service_close_instance()

◆ ipc_service_deregister_endpoint()

◆ ipc_service_drop_tx_buffer()

◆ ipc_service_get_tx_buffer()

◆ ipc_service_get_tx_buffer_size()

◆ ipc_service_hold_rx_buffer()

◆ ipc_service_open_instance()

◆ ipc_service_register_endpoint()

◆ ipc_service_release_rx_buffer()

◆ ipc_service_send()

◆ ipc_service_send_nocopy()