Zbus Proxy Agent API

Topics
	Zbus Proxy Agent IPC Backend

Data Structures
struct	zbus_shadow_channel
	Metadata for shadow channels to track their ownership by proxy agents. More...
struct	zbus_proxy_msg
	Structure for proxy agent message. More...
struct	zbus_proxy_agent_rx_msg
	Internal thread payload for validated received messages. More...
struct	zbus_proxy_agent
	Structure for proxy agent configuration. More...
struct	zbus_proxy_agent_backend_api
	Backend API structure for proxy agent backends. More...
struct	zbus_proxy_agent_backend_desc
	Structure for proxy agent backend descriptor. More...

Macros
#define	ZBUS_PROXY_AGENT_BACKEND_DEFINE(_name, _type, _api)
	Macro to define a proxy agent backend and register it in the iterable section.
#define	ZBUS_PROXY_AGENT_DEFINE(_name, _type, _backend_dt_node)
	Proxy agent definition macro.
#define	ZBUS_PROXY_ADD_CHAN(_agent, _chan)
	Add a channel to be forwarded by the proxy agent.
#define	ZBUS_SHADOW_CHAN_DEFINE(_name, _type, _proxy_name, _user_data, _observers, _init_val)
	Define a shadow channel linked to a proxy agent.
#define	ZBUS_SHADOW_CHAN_DEFINE_WITH_ID(_name, _id, _type, _proxy_name, _user_data, _observers, _init_val)
	Define a shadow channel with a specific ID linked to a proxy agent.

Typedefs
typedef int(*	zbus_proxy_agent_recv_cb_t) (const struct zbus_proxy_agent *agent, const struct zbus_proxy_msg *msg)
	Type definition for the proxy agent receive callback function.

Enumerations
enum	zbus_proxy_agent_backend_type { ZBUS_PROXY_AGENT_BACKEND_IPC }
	Enum for supported proxy agent backend types. More...

Functions
void	zbus_proxy_agent_listener_cb (const struct zbus_channel *chan, const struct zbus_proxy_agent *agent)
	Internal proxy agent listener callback.
int	zbus_init_proxy_agent (const struct zbus_proxy_agent *agent)
	Internal proxy agent receive callback.

Detailed Description

Macro Definition Documentation

ZBUS_PROXY_ADD_CHAN

#define ZBUS_PROXY_ADD_CHAN	(		_agent,
			_chan )

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Value:

ZBUS_CHAN_ADD_OBS(_chan, _agent##_listener, zz)

Add a channel to be forwarded by the proxy agent.

Parameters

_agent	The proxy agent instance that will forward the channel
_chan	The channel to be forwarded by the proxy agent

Note

This macro adds the observer with the priority "zz". as the observer priority is sorted lexicographically in the iterable section, this ensures that the proxy agent listener is called after all other observers for the channel, avoiding potential blocking behavior. When adding other observers for the same channel, their priority should be set to a value lexicographically smaller than "zz" to ensure they are called before the proxy agent listener.

ZBUS_PROXY_AGENT_BACKEND_DEFINE

#define ZBUS_PROXY_AGENT_BACKEND_DEFINE	(		_name,
			_type,
			_api )

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Value:

STRUCT_SECTION_ITERABLE(zbus_proxy_agent_backend_desc, _name) = {                          \
        .type = (_type),                                                                   \
        .api = (_api),                                                                     \
}

Macro to define a proxy agent backend and register it in the iterable section.

Parameters

_name	Name of the backend instance
_type	Backend type (e.g., ZBUS_PROXY_AGENT_BACKEND_IPC)
_api	Pointer to the backend API structure

ZBUS_PROXY_AGENT_DEFINE

#define ZBUS_PROXY_AGENT_DEFINE	(		_name,
			_type,
			_backend_dt_node )

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Proxy agent definition macro.

This macro defines a proxy agent with the specified name, backend type, and backend device tree node.

Parameters

_name	Name of the proxy agent instance
_type	Backend type for the proxy agent (e.g., ZBUS_PROXY_AGENT_BACKEND_IPC)
_backend_dt_node	Device tree node for the backend configuration

ZBUS_SHADOW_CHAN_DEFINE

#define ZBUS_SHADOW_CHAN_DEFINE	(		_name,
			_type,
			_proxy_name,
			_user_data,
			_observers,
			_init_val )

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Value:

ZBUS_CHAN_DEFINE(_name, _type, _ZBUS_PROXY_AGENT_VALIDATOR(_proxy_name), _user_data,       \
                 _observers, _init_val);                                                   \
_ZBUS_SHADOW_CHAN_REGISTER(_name, _proxy_name)

Define a shadow channel linked to a proxy agent.

Note

Shadow channels are local channels that mirror remote channels from other domains. They can only be published to by their associated proxy agent to ensure data integrity.

Parameters

_name	Channel name
_type	Message type structure
_proxy_name	The name of the linked proxy agent
_user_data	User data pointer
_observers	Static list of observers
_init_val	Initial channel value

ZBUS_SHADOW_CHAN_DEFINE_WITH_ID

#define ZBUS_SHADOW_CHAN_DEFINE_WITH_ID	(		_name,
			_id,
			_type,
			_proxy_name,
			_user_data,
			_observers,
			_init_val )

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Value:

ZBUS_CHAN_DEFINE_WITH_ID(_name, _id, _type, _ZBUS_PROXY_AGENT_VALIDATOR(_proxy_name),      \
                         _user_data, _observers, _init_val);                               \
_ZBUS_SHADOW_CHAN_REGISTER(_name, _proxy_name)

Define a shadow channel with a specific ID linked to a proxy agent.

Note

Shadow channels are local channels that mirror remote channels from other domains. They can only be published to by their associated proxy agent to ensure data integrity.

Parameters

_name	Channel name
_id	channel ID
_type	Message type structure
_proxy_name	The name of the linked proxy agent
_user_data	User data pointer
_observers	Static list of observers
_init_val	Initial channel value

Typedef Documentation

zbus_proxy_agent_recv_cb_t

typedef int(* zbus_proxy_agent_recv_cb_t) (const struct zbus_proxy_agent *agent, const struct zbus_proxy_msg *msg)

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Type definition for the proxy agent receive callback function.

This callback is invoked when a proxy agent receives a message. The callback should process the message and return 0 on success or a negative error code on failure.

Parameters

agent	Pointer to the proxy agent instance
msg	Pointer to the received proxy message

Returns

int 0 on success, negative error code on failure

Enumeration Type Documentation

zbus_proxy_agent_backend_type

enum zbus_proxy_agent_backend_type

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Enum for supported proxy agent backend types.

Enumerator
ZBUS_PROXY_AGENT_BACKEND_IPC	IPC backend for inter-process communication.

Function Documentation

zbus_init_proxy_agent()

int zbus_init_proxy_agent

(

const struct zbus_proxy_agent *

agent

)

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Internal proxy agent receive callback.

Note

This function is called by the generated initialization function from sys_init and should not be called directly.

Initializes the proxy agent by setting up the backend and starting the dedicated thread.

Parameters

agent

Proxy agent configuration

Returns

int 0 on success, negative error code on failure

zbus_proxy_agent_listener_cb()

void zbus_proxy_agent_listener_cb	(	const struct zbus_channel *	chan,
		const struct zbus_proxy_agent *	agent )

#include <zephyr/zbus/proxy_agent/zbus_proxy_agent.h>

Internal proxy agent listener callback.

Note

This function is called by the generated listener callback and should not be called directly.

Parameters

agent	Proxy agent configuration
chan	Channel that triggered the callback