Zbus APIs

Zbus API. More...

Data Structures
struct	zbus_channel
	Type used to represent a channel. More...
struct	zbus_observer
	Type used to represent an observer. More...

Macros
#define	ZBUS_OBS_DECLARE(...)   FOR_EACH(_ZBUS_OBS_EXTERN, (;), __VA_ARGS__)
#define	ZBUS_CHAN_DECLARE(...)   FOR_EACH(_ZBUS_CHAN_EXTERN, (;), __VA_ARGS__)
#define	ZBUS_OBSERVERS_EMPTY
#define	ZBUS_OBSERVERS(...)   __VA_ARGS__
#define	ZBUS_CHAN_DEFINE(_name, _type, _validator, _user_data, _observers, _init_val)
	Zbus channel definition. More...
#define	ZBUS_MSG_INIT(_val, ...)
	Initialize a message. More...
#define	ZBUS_SUBSCRIBER_DEFINE(_name, _queue_size)
	Define and initialize a subscriber. More...
#define	ZBUS_LISTENER_DEFINE(_name, _cb)
	Define and initialize a listener. More...

Functions
int	zbus_chan_pub (const struct zbus_channel *chan, const void *msg, k_timeout_t timeout)
	Publish to a channel. More...
int	zbus_chan_read (const struct zbus_channel *chan, void *msg, k_timeout_t timeout)
	Read a channel. More...
int	zbus_chan_claim (const struct zbus_channel *chan, k_timeout_t timeout)
	Claim a channel. More...
int	zbus_chan_finish (const struct zbus_channel *chan)
	Finish a channel claim. More...
int	zbus_chan_notify (const struct zbus_channel *chan, k_timeout_t timeout)
	Force a channel notification. More...
static const char *	zbus_chan_name (const struct zbus_channel *chan)
	Get the channel's name. More...
static void *	zbus_chan_msg (const struct zbus_channel *chan)
	Get the reference for a channel message directly. More...
static const void *	zbus_chan_const_msg (const struct zbus_channel *chan)
	Get a constant reference for a channel message directly. More...
static uint16_t	zbus_chan_msg_size (const struct zbus_channel *chan)
	Get the channel's message size. More...
static void *	zbus_chan_user_data (const struct zbus_channel *chan)
	Get the channel's user data. More...
int	zbus_chan_add_obs (const struct zbus_channel *chan, const struct zbus_observer *obs, k_timeout_t timeout)
	Add an observer to a channel. More...
int	zbus_chan_rm_obs (const struct zbus_channel *chan, const struct zbus_observer *obs, k_timeout_t timeout)
	Remove an observer from a channel. More...
struct k_mem_slab *	zbus_runtime_obs_pool (void)
	Get zbus runtime observers pool. More...
static int	zbus_obs_set_enable (struct zbus_observer *obs, bool enabled)
	Change the observer state. More...
static const char *	zbus_obs_name (const struct zbus_observer *obs)
	Get the observer's name. More...
int	zbus_sub_wait (const struct zbus_observer *sub, const struct zbus_channel **chan, k_timeout_t timeout)
	Wait for a channel notification. More...
bool	zbus_iterate_over_channels (bool(*iterator_func)(const struct zbus_channel *chan))
	Iterate over channels. More...
bool	zbus_iterate_over_observers (bool(*iterator_func)(const struct zbus_observer *obs))
	Iterate over observers. More...

Detailed Description

Zbus API.

Macro Definition Documentation

ZBUS_CHAN_DECLARE

#define ZBUS_CHAN_DECLARE

(

...

)

FOR_EACH(_ZBUS_CHAN_EXTERN, (;), __VA_ARGS__)

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

This macro list the channels to be used in a file. Internally, it declares the channels with the extern statement. Note it is only necessary when the channels are declared outside the file.

ZBUS_CHAN_DEFINE

#define ZBUS_CHAN_DEFINE	(		_name,
			_type,
			_validator,
			_user_data,
			_observers,
			_init_val
	)

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

Value:

        static _type _CONCAT(_zbus_message_, _name) = _init_val;                             \
        static K_MUTEX_DEFINE(_CONCAT(_zbus_mutex_, _name));                                 \
        ZBUS_RUNTIME_OBSERVERS_LIST_DECL(_CONCAT(_runtime_observers_, _name));               \
        FOR_EACH_NONEMPTY_TERM(_ZBUS_OBS_EXTERN, (;), _observers)                            \
        static const struct zbus_observer *const _CONCAT(_zbus_observers_, _name)[] = {      \
        FOR_EACH_NONEMPTY_TERM(ZBUS_REF, (,), _observers) NULL};                             \
        const _ZBUS_STRUCT_DECLARE(zbus_channel, _name) = {                                  \
                ZBUS_CHANNEL_NAME_INIT(_name)                  /* Name */                    \
                .message_size = sizeof(_type),                 /* Message size */            \
                .user_data = _user_data,                       /* User data */               \
                .message = &_CONCAT(_zbus_message_, _name),    /* Reference to the message */\
                .validator = (_validator),                     /* Validator function */      \
                .mutex = &_CONCAT(_zbus_mutex_, _name),        /* Channel's Mutex */         \
                ZBUS_RUNTIME_OBSERVERS_LIST_INIT(                                            \
                        _CONCAT(_runtime_observers_, _name))   /* Runtime observer list */   \
                .observers = _CONCAT(_zbus_observers_, _name)} /* Static observer list */

Zbus channel definition.

This macro defines a channel.

Parameters

_name	The channel's name.
_type	The Message type. It must be a struct or union.
_validator	The validator function.
_user_data	A pointer to the user data.

See also

struct zbus_channel

Parameters

_observers	The observers list. The sequence indicates the priority of the observer. The first the highest priority.
_init_val	The message initialization.

ZBUS_LISTENER_DEFINE

#define ZBUS_LISTENER_DEFINE	(		_name,
			_cb
	)

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

Value:

        _ZBUS_STRUCT_DECLARE(zbus_observer,                                                        \
                             _name) = {ZBUS_OBSERVER_NAME_INIT(_name) /* Name field */             \
                                               .enabled = true,                                    \
                                       .queue = NULL, .callback = (_cb)}

Define and initialize a listener.

This macro defines an observer of listener type. This macro establishes the callback where the listener will be notified synchronously, and initialize the struct zbus_observer defining the listener.

Parameters

[in]	_name	The listener's name.
[in]	_cb	The callback function.

ZBUS_MSG_INIT

#define ZBUS_MSG_INIT	(		_val,
			...
	)

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

Value:

        {                                                                                          \
                _val, ##__VA_ARGS__                                                                \
        }

Initialize a message.

This macro initializes a message by passing the values to initialize the message struct or union.

Parameters

[in]

_val

Variadic with the initial values. ZBUS_INIT(0) means {0}, as ZBUS_INIT(.a=10, .b=30) means {.a=10, .b=30}.

ZBUS_OBS_DECLARE

#define ZBUS_OBS_DECLARE

(

...

)

FOR_EACH(_ZBUS_OBS_EXTERN, (;), __VA_ARGS__)

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

This macro list the observers to be used in a file. Internally, it declares the observers with the extern statement. Note it is only necessary when the observers are declared outside the file.

ZBUS_OBSERVERS

#define ZBUS_OBSERVERS

(

...

)

__VA_ARGS__

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

This macro indicates the channel has listed observers. Note the sequence of observer notification will follow the same as listed.

ZBUS_OBSERVERS_EMPTY

#define ZBUS_OBSERVERS_EMPTY

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

This macro indicates the channel has no observers.

ZBUS_SUBSCRIBER_DEFINE

#define ZBUS_SUBSCRIBER_DEFINE	(		_name,
			_queue_size
	)

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

Value:

        K_MSGQ_DEFINE(_zbus_observer_queue_##_name, sizeof(const struct zbus_channel *),           \
                      _queue_size, sizeof(const struct zbus_channel *));                           \
        _ZBUS_STRUCT_DECLARE(zbus_observer,                                                        \
                             _name) = {ZBUS_OBSERVER_NAME_INIT(_name) /* Name field */             \
                                               .enabled = true,                                    \
                                       .queue = &_zbus_observer_queue_##_name, .callback = NULL}

Define and initialize a subscriber.

This macro defines an observer of subscriber type. It defines a message queue where the subscriber will receive the notification asynchronously, and initialize the struct zbus_observer defining the subscriber.

Parameters

[in]	_name	The subscriber's name.
[in]	_queue_size	The notification queue's size.

Function Documentation

zbus_chan_add_obs()

int zbus_chan_add_obs	(	const struct zbus_channel *	chan,
		const struct zbus_observer *	obs,
		k_timeout_t	timeout
	)

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

Add an observer to a channel.

This routine adds an observer to the channel.

Parameters

chan	The channel's reference.
obs	The observer's reference to be added.
timeout	Waiting period to add an observer, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Observer added to the channel.
-EALREADY	The observer is already present in the channel's runtime observers list.
-ENOMEM	Returned without waiting.
-EAGAIN	Waiting period timed out.
-EINVAL	Some parameter is invalid.

zbus_chan_claim()

int zbus_chan_claim	(	const struct zbus_channel *	chan,
		k_timeout_t	timeout
	)

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

Claim a channel.

This routine claims a channel. During the claiming period the channel is blocked for publishing, reading, notifying or claiming again. Finishing is the only available action.

Warning

After calling this routine, the channel cannot be used by other thread until the zbus_chan_finish routine is performed.

This routine should only be called once before a zbus_chan_finish.

Parameters

[in]	chan	The channel's reference.
[in]	timeout	Waiting period to claim the channel, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Channel claimed.
-EBUSY	The channel is busy.
-EAGAIN	Waiting period timed out.
-EFAULT	A parameter is incorrect, or the function context is invalid (inside an ISR). The function only returns this value when the CONFIG_ZBUS_ASSERT_MOCK is enabled.

zbus_chan_const_msg()

static const void * zbus_chan_const_msg ( const struct zbus_channel *  chan )

inlinestatic

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

Get a constant reference for a channel message directly.

This routine returns a constant reference of a channel message. This should be used inside listeners to access the message directly. In this way zbus prevents the listener of changing the notifying channel's message during the notification process.

Warning

This function must only be used directly for acquired (locked by mutex) channels. This can be done inside a listener for the receiving channel or after claim a channel.

Parameters

chan	The channel's constant reference.

Returns

A constant channel's message reference.

zbus_chan_finish()

int zbus_chan_finish

(

const struct zbus_channel *

chan

)

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

Finish a channel claim.

This routine finishes a channel claim. After calling this routine with success, the channel will be able to be used by other thread.

Warning

This routine must only be used after a zbus_chan_claim.

Parameters

chan	The channel's reference.

Return values

0	Channel finished.
-EPERM	The channel was claimed by other thread.
-EINVAL	The channel's mutex is not locked.
-EFAULT	A parameter is incorrect, or the function context is invalid (inside an ISR). The function only returns this value when the CONFIG_ZBUS_ASSERT_MOCK is enabled.

zbus_chan_msg()

static void * zbus_chan_msg ( const struct zbus_channel *  chan )

inlinestatic

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

Get the reference for a channel message directly.

This routine returns the reference of a channel message.

Warning

This function must only be used directly for acquired (locked by mutex) channels. This can be done inside a listener for the receiving channel or after claim a channel.

Parameters

chan	The channel's reference.

Returns

Channel's message reference.

zbus_chan_msg_size()

static uint16_t zbus_chan_msg_size ( const struct zbus_channel *  chan )

inlinestatic

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

Get the channel's message size.

This routine returns the channel's message size.

Parameters

chan	The channel's reference.

Returns

Channel's message size.

zbus_chan_name()

static const char * zbus_chan_name ( const struct zbus_channel *  chan )

inlinestatic

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

Get the channel's name.

This routine returns the channel's name reference.

Parameters

chan	The channel's reference.

Returns

Channel's name reference.

zbus_chan_notify()

int zbus_chan_notify	(	const struct zbus_channel *	chan,
		k_timeout_t	timeout
	)

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

Force a channel notification.

This routine forces the event dispatcher to notify the channel's observers even if the message has no changes. Note this function could be useful after claiming/finishing actions.

Parameters

chan	The channel's reference.
timeout	Waiting period to notify the channel, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Channel notified.
-EPERM	The current thread does not own the channel.
-EBUSY	The channel's mutex returned without waiting.
-EAGAIN	Timeout to acquiring the channel's mutex.
-EFAULT	A parameter is incorrect, the notification could not be sent to one or more observer, or the function context is invalid (inside an ISR). The function only returns this value when the CONFIG_ZBUS_ASSERT_MOCK is enabled.

zbus_chan_pub()

int zbus_chan_pub	(	const struct zbus_channel *	chan,
		const void *	msg,
		k_timeout_t	timeout
	)

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

Publish to a channel.

This routine publishes a message to a channel.

Parameters

chan	The channel's reference.
msg	Reference to the message where the publish function copies the channel's message data from.
timeout	Waiting period to publish the channel, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Channel published.
-ENOMSG	The message is invalid based on the validator function or some of the observers could not receive the notification.
-EBUSY	The channel is busy.
-EAGAIN	Waiting period timed out.
-EFAULT	A parameter is incorrect, the notification could not be sent to one or more observer, or the function context is invalid (inside an ISR). The function only returns this value when the CONFIG_ZBUS_ASSERT_MOCK is enabled.

zbus_chan_read()

int zbus_chan_read	(	const struct zbus_channel *	chan,
		void *	msg,
		k_timeout_t	timeout
	)

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

Read a channel.

This routine reads a message from a channel.

Parameters

[in]	chan	The channel's reference.
[out]	msg	Reference to the message where the read function copies the channel's message data to.
[in]	timeout	Waiting period to read the channel, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Channel read.
-EBUSY	The channel is busy.
-EAGAIN	Waiting period timed out.
-EFAULT	A parameter is incorrect, or the function context is invalid (inside an ISR). The function only returns this value when the CONFIG_ZBUS_ASSERT_MOCK is enabled.

zbus_chan_rm_obs()

int zbus_chan_rm_obs	(	const struct zbus_channel *	chan,
		const struct zbus_observer *	obs,
		k_timeout_t	timeout
	)

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

Remove an observer from a channel.

This routine removes an observer to the channel.

Parameters

chan	The channel's reference.
obs	The observer's reference to be removed.
timeout	Waiting period to remove an observer, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Observer removed to the channel.
-EINVAL	Invalid data supplied.
-EBUSY	Returned without waiting.
-EAGAIN	Waiting period timed out.
-ENODATA	no observer found in channel's runtime observer list.
-ENOMEM	Returned without waiting.

zbus_chan_user_data()

static void * zbus_chan_user_data ( const struct zbus_channel *  chan )

inlinestatic

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

Get the channel's user data.

This routine returns the channel's user data.

Parameters

chan	The channel's reference.

Returns

Channel's user data.

zbus_iterate_over_channels()

bool zbus_iterate_over_channels

(

bool(*)(const struct zbus_channel *chan)

iterator_func

)

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

Iterate over channels.

Enables the developer to iterate over the channels giving to this function an iterator_func which is called for each channel. If the iterator_func returns false all the iteration stops.

Return values

true	Iterator executed for all channels.
false	Iterator could not be executed. Some iterate returned false.

zbus_iterate_over_observers()

bool zbus_iterate_over_observers

(

bool(*)(const struct zbus_observer *obs)

iterator_func

)

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

Iterate over observers.

Enables the developer to iterate over the observers giving to this function an iterator_func which is called for each observer. If the iterator_func returns false all the iteration stops.

Return values

true	Iterator executed for all channels.
false	Iterator could not be executed. Some iterate returned false.

zbus_obs_name()

static const char * zbus_obs_name ( const struct zbus_observer *  obs )

inlinestatic

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

Get the observer's name.

This routine returns the observer's name reference.

Parameters

obs	The observer's reference.

Returns

The observer's name reference.

zbus_obs_set_enable()

static int zbus_obs_set_enable ( struct zbus_observer *  obs, bool  enabled  )

inlinestatic

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

Change the observer state.

This routine changes the observer state. A channel when disabled will not receive notifications from the event dispatcher.

Parameters

[in]	obs	The observer's reference.
[in]	enabled	State to be. When false the observer stops to receive notifications.

Return values

0	Observer set enable.
-EFAULT	A parameter is incorrect, or the function context is invalid (inside an ISR). The function only returns this value when the CONFIG_ZBUS_ASSERT_MOCK is enabled.

zbus_runtime_obs_pool()

struct k_mem_slab * zbus_runtime_obs_pool

(

void

)

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

Get zbus runtime observers pool.

This routine returns a reference of the runtime observers pool.

Returns

Reference of runtime observers pool.

zbus_sub_wait()

int zbus_sub_wait	(	const struct zbus_observer *	sub,
		const struct zbus_channel **	chan,
		k_timeout_t	timeout
	)

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

Wait for a channel notification.

This routine makes the subscriber to wait a notification. The notification comes as a channel reference.

Parameters

[in]	sub	The subscriber's reference.
[out]	chan	The notification channel's reference.
[in]	timeout	Waiting period for a notification arrival, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Notification received.
-ENOMSG	Returned without waiting.
-EAGAIN	Waiting period timed out.
-EINVAL	The observer is not a subscriber.
-EFAULT	A parameter is incorrect, or the function context is invalid (inside an ISR). The function only returns this value when the CONFIG_ZBUS_ASSERT_MOCK is enabled.