Zbus APIs

Zbus API . More...

Data Structures
struct	zbus_channel_data
	Type used to represent a channel mutable data. More...
struct	zbus_channel
	Type used to represent a channel. More...
struct	zbus_observer_data
struct	zbus_observer
	Type used to represent an observer. More...

Macros
#define	ZBUS_CHAN_ADD_OBS_WITH_MASK(_chan, _obs, _masked, _prio)
	Add a static channel observation.
#define	ZBUS_CHAN_ADD_OBS(_chan, _obs, _prio)
	Add a static channel observation.
#define	ZBUS_OBS_DECLARE(...)
	This macro list the observers to be used in a file.
#define	ZBUS_CHAN_DECLARE(...)
	This macro list the channels to be used in a file.
#define	ZBUS_OBSERVERS_EMPTY
	This macro indicates the channel has no observers.
#define	ZBUS_OBSERVERS(...)
	This macro indicates the channel has listed observers.
#define	ZBUS_CHAN_DEFINE(_name, _type, _validator, _user_data, _observers, _init_val)
	Zbus channel definition.
#define	ZBUS_MSG_INIT(_val, ...)
	Initialize a message.
#define	ZBUS_SUBSCRIBER_DEFINE_WITH_ENABLE(_name, _queue_size, _enable)
	Define and initialize a subscriber.
#define	ZBUS_SUBSCRIBER_DEFINE(_name, _queue_size)
	Define and initialize a subscriber.
#define	ZBUS_LISTENER_DEFINE_WITH_ENABLE(_name, _cb, _enable)
	Define and initialize a listener.
#define	ZBUS_LISTENER_DEFINE(_name, _cb)
	Define and initialize a listener.
#define	ZBUS_MSG_SUBSCRIBER_DEFINE_WITH_ENABLE(_name, _enable)
	Define and initialize a message subscriber.
#define	ZBUS_MSG_SUBSCRIBER_DEFINE(_name)
	Define and initialize an enabled message subscriber.

Enumerations
enum	zbus_observer_type { ZBUS_OBSERVER_LISTENER_TYPE , ZBUS_OBSERVER_SUBSCRIBER_TYPE , ZBUS_OBSERVER_MSG_SUBSCRIBER_TYPE }
	Type used to represent an observer type. More...

Functions
int	zbus_chan_pub (const struct zbus_channel *chan, const void *msg, k_timeout_t timeout)
	Publish to a channel.
int	zbus_chan_read (const struct zbus_channel *chan, void *msg, k_timeout_t timeout)
	Read a channel.
int	zbus_chan_claim (const struct zbus_channel *chan, k_timeout_t timeout)
	Claim a channel.
int	zbus_chan_finish (const struct zbus_channel *chan)
	Finish a channel claim.
int	zbus_chan_notify (const struct zbus_channel *chan, k_timeout_t timeout)
	Force a channel notification.
static const char *	zbus_chan_name (const struct zbus_channel *chan)
	Get the channel's name.
static void *	zbus_chan_msg (const struct zbus_channel *chan)
	Get the reference for a channel message directly.
static const void *	zbus_chan_const_msg (const struct zbus_channel *chan)
	Get a constant reference for a channel message directly.
static uint16_t	zbus_chan_msg_size (const struct zbus_channel *chan)
	Get the channel's message size.
static void *	zbus_chan_user_data (const struct zbus_channel *chan)
	Get the channel's user data.
static void	zbus_chan_set_msg_sub_pool (const struct zbus_channel *chan, struct net_buf_pool *pool)
	Set the channel's msg subscriber net_buf pool.
static void	zbus_chan_pub_stats_update (const struct zbus_channel *chan)
	Update the publishing statistics for a channel.
static k_ticks_t	zbus_chan_pub_stats_last_time (const struct zbus_channel *chan)
	Get the time a channel was last published to.
static uint32_t	zbus_chan_pub_stats_count (const struct zbus_channel *chan)
	Get the number of times a channel has been published to.
static uint32_t	zbus_chan_pub_stats_avg_period (const struct zbus_channel *chan)
	Get the average period between publishes to a channel.
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.
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.
int	zbus_obs_set_enable (const struct zbus_observer *obs, bool enabled)
	Change the observer state.
static int	zbus_obs_is_enabled (const struct zbus_observer *obs, bool *enable)
	Get the observer state.
int	zbus_obs_set_chan_notification_mask (const struct zbus_observer *obs, const struct zbus_channel *chan, bool masked)
	Mask notifications from a channel to an observer.
int	zbus_obs_is_chan_notification_masked (const struct zbus_observer *obs, const struct zbus_channel *chan, bool *masked)
	Get the notifications masking state from a channel to an observer.
static const char *	zbus_obs_name (const struct zbus_observer *obs)
	Get the observer's name.
int	zbus_obs_attach_to_thread (const struct zbus_observer *obs)
	Set the observer thread priority by attaching it to a thread.
int	zbus_obs_detach_from_thread (const struct zbus_observer *obs)
	Clear the observer thread priority by detaching it from a thread.
int	zbus_sub_wait (const struct zbus_observer *sub, const struct zbus_channel **chan, k_timeout_t timeout)
	Wait for a channel notification.
int	zbus_sub_wait_msg (const struct zbus_observer *sub, const struct zbus_channel **chan, void *msg, k_timeout_t timeout)
	Wait for a channel message.
bool	zbus_iterate_over_channels (bool(*iterator_func)(const struct zbus_channel *chan))
	Iterate over channels.
bool	zbus_iterate_over_channels_with_user_data (bool(*iterator_func)(const struct zbus_channel *chan, void *user_data), void *user_data)
	Iterate over channels with user data.
bool	zbus_iterate_over_observers (bool(*iterator_func)(const struct zbus_observer *obs))
	Iterate over observers.
bool	zbus_iterate_over_observers_with_user_data (bool(*iterator_func)(const struct zbus_observer *obs, void *user_data), void *user_data)
	Iterate over observers with user data.

Detailed Description

Zbus API .

Macro Definition Documentation

ZBUS_CHAN_ADD_OBS

#define ZBUS_CHAN_ADD_OBS	(		_chan,
			_obs,
			_prio )

#include <zephyr/zbus/zbus.h>

Value:

ZBUS_CHAN_ADD_OBS_WITH_MASK(_chan, _obs, false, _prio)

Add a static channel observation.

This macro initializes a channel observation by receiving the channel and the observer.

Parameters

_chan	Channel instance.
_obs	Observer instance.
_prio	Observer notification sequence priority.

ZBUS_CHAN_ADD_OBS_WITH_MASK

#define ZBUS_CHAN_ADD_OBS_WITH_MASK	(		_chan,
			_obs,
			_masked,
			_prio )

#include <zephyr/zbus/zbus.h>

Value:

        const STRUCT_SECTION_ITERABLE(zbus_channel_observation,                                    \
                _CONCAT(_CONCAT(_chan, zz), _CONCAT(_prio, _obs))) = {                             \
                        .chan = &_chan,                                                            \
                        .obs = &_obs,                                                              \
        };                                                                                         \
        STRUCT_SECTION_ITERABLE(zbus_channel_observation_mask,                                     \
                                _CONCAT(_CONCAT(_CONCAT(_chan, zz), _CONCAT(_prio, _obs)),         \
                                        _mask)) = {.enabled = _masked}

Add a static channel observation.

This macro initializes a channel observation by receiving the channel and the observer.

Parameters

_chan	Channel instance.
_obs	Observer instance.
_masked	Observation state.
_prio	Observer notification sequence priority.

ZBUS_CHAN_DECLARE

#define ZBUS_CHAN_DECLARE

(

...

)

#include <zephyr/zbus/zbus.h>

Value:

FOR_EACH(_ZBUS_CHAN_EXTERN, (;), __VA_ARGS__)

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 <zephyr/zbus/zbus.h>

Value:

        static _type _CONCAT(_zbus_message_, _name) = _init_val;                          \
        static struct zbus_channel_data _CONCAT(_zbus_chan_data_, _name) = {              \
                .observers_start_idx = -1,                                                \
                .observers_end_idx = -1,                                                  \
                .sem = Z_SEM_INITIALIZER(_CONCAT(_zbus_chan_data_, _name).sem, 1, 1),     \
                IF_ENABLED(CONFIG_ZBUS_PRIORITY_BOOST, (                                  \
                        .highest_observer_priority = ZBUS_MIN_THREAD_PRIORITY,            \
                ))                                                                        \
                IF_ENABLED(CONFIG_ZBUS_RUNTIME_OBSERVERS, (                               \
                        .observers = SYS_SLIST_STATIC_INIT(                               \
                                &_CONCAT(_zbus_chan_data_, _name).observers),             \
                ))                                                                        \
        };                                                                                \
        static K_MUTEX_DEFINE(_CONCAT(_zbus_mutex_, _name));                              \
        _ZBUS_CPP_EXTERN const STRUCT_SECTION_ITERABLE(zbus_channel, _name) = {           \
                ZBUS_CHANNEL_NAME_INIT(_name) /* Maybe removed */                         \
                .message = &_CONCAT(_zbus_message_, _name),                               \
                .message_size = sizeof(_type),                                            \
                .user_data = _user_data,                                                  \
                .validator = _validator,                                                  \
                .data = &_CONCAT(_zbus_chan_data_, _name),                                \
                IF_ENABLED(ZBUS_MSG_SUBSCRIBER_NET_BUF_POOL_ISOLATION, (                  \
                        .msg_subscriber_pool = &_zbus_msg_subscribers_pool,               \
                ))                                                                        \
        };                                                                                \
        /* Extern declaration of observers */                                             \
        ZBUS_OBS_DECLARE(_observers);                                                     \
        /* Create all channel observations from observers list */                         \
        FOR_EACH_FIXED_ARG_NONEMPTY_TERM(_ZBUS_CHAN_OBSERVATION, (;), _name, _observers)

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 <zephyr/zbus/zbus.h>

Value:

ZBUS_LISTENER_DEFINE_WITH_ENABLE(_name, _cb, true)

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. The listeners are defined in the enabled state with this macro.

Parameters

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

ZBUS_LISTENER_DEFINE_WITH_ENABLE

#define ZBUS_LISTENER_DEFINE_WITH_ENABLE	(		_name,
			_cb,
			_enable )

#include <zephyr/zbus/zbus.h>

Value:

        static struct zbus_observer_data _CONCAT(_zbus_obs_data_, _name) = {                       \
                .enabled = _enable,                                                                \
                IF_ENABLED(CONFIG_ZBUS_PRIORITY_BOOST, (                                           \
                        .priority = ZBUS_MIN_THREAD_PRIORITY,                                      \
                ))                                                                                 \
        };                                                                                         \
        _ZBUS_CPP_EXTERN const STRUCT_SECTION_ITERABLE(zbus_observer, _name) = {                   \
                ZBUS_OBSERVER_NAME_INIT(_name) /* Name field */                                    \
                .type = ZBUS_OBSERVER_LISTENER_TYPE,                                               \
                .data = &_CONCAT(_zbus_obs_data_, _name),                                          \
                .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.
[in]	_enable	The listener initial enable state.

ZBUS_MSG_INIT

#define ZBUS_MSG_INIT	(		_val,
			... )

#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_MSG_SUBSCRIBER_DEFINE

#define ZBUS_MSG_SUBSCRIBER_DEFINE

(

_name

)

#include <zephyr/zbus/zbus.h>

Value:

ZBUS_MSG_SUBSCRIBER_DEFINE_WITH_ENABLE(_name, true)

Define and initialize an enabled message subscriber.

This macro defines an observer of message subscriber type. It defines a FIFO where the subscriber will receive the message asynchronously and initialize the zbus_observer defining the subscriber. The message subscribers are defined in the enabled state with this macro.

Parameters

[in]

_name

The subscriber's name.

ZBUS_MSG_SUBSCRIBER_DEFINE_WITH_ENABLE

#define ZBUS_MSG_SUBSCRIBER_DEFINE_WITH_ENABLE	(		_name,
			_enable )

#include <zephyr/zbus/zbus.h>

Value:

        static K_FIFO_DEFINE(_zbus_observer_fifo_##_name);                    \
        static struct zbus_observer_data _CONCAT(_zbus_obs_data_, _name) = {  \
                .enabled = _enable,                                           \
                IF_ENABLED(CONFIG_ZBUS_PRIORITY_BOOST, (                      \
                        .priority = ZBUS_MIN_THREAD_PRIORITY,                 \
                ))                                                            \
        };                                                                    \
        _ZBUS_CPP_EXTERN const STRUCT_SECTION_ITERABLE(zbus_observer, _name) = {  \
                ZBUS_OBSERVER_NAME_INIT(_name) /* Name field */               \
                .type = ZBUS_OBSERVER_MSG_SUBSCRIBER_TYPE,                    \
                .data = &_CONCAT(_zbus_obs_data_, _name),                     \
                .message_fifo = &_zbus_observer_fifo_##_name,                 \
        }

Define and initialize a message subscriber.

This macro defines an observer of ZBUS_OBSERVER_SUBSCRIBER_TYPE type. It defines a FIFO where the subscriber will receive the message asynchronously and initialize the zbus_observer defining the subscriber.

Parameters

[in]	_name	The subscriber's name.
[in]	_enable	The subscriber's initial state.

ZBUS_OBS_DECLARE

#define ZBUS_OBS_DECLARE

(

...

)

#include <zephyr/zbus/zbus.h>

Value:

FOR_EACH_NONEMPTY_TERM(_ZBUS_OBS_EXTERN, (;), __VA_ARGS__)

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

(

...

)

#include <zephyr/zbus/zbus.h>

Value:

__VA_ARGS__

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 <zephyr/zbus/zbus.h>

This macro indicates the channel has no observers.

ZBUS_SUBSCRIBER_DEFINE

#define ZBUS_SUBSCRIBER_DEFINE	(		_name,
			_queue_size )

#include <zephyr/zbus/zbus.h>

Value:

        ZBUS_SUBSCRIBER_DEFINE_WITH_ENABLE(_name, _queue_size, true)

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. The subscribers are defined in the enabled state with this macro.

Parameters

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

ZBUS_SUBSCRIBER_DEFINE_WITH_ENABLE

#define ZBUS_SUBSCRIBER_DEFINE_WITH_ENABLE	(		_name,
			_queue_size,
			_enable )

#include <zephyr/zbus/zbus.h>

Value:

        K_MSGQ_DEFINE(_zbus_observer_queue_##_name,                           \
                      sizeof(struct zbus_channel *),                          \
                      _queue_size, sizeof(struct zbus_channel *)              \
        );                                                                    \
        static struct zbus_observer_data _CONCAT(_zbus_obs_data_, _name) = {  \
                .enabled = _enable,                                           \
                IF_ENABLED(CONFIG_ZBUS_PRIORITY_BOOST, (                      \
                        .priority = ZBUS_MIN_THREAD_PRIORITY,                 \
                ))                                                            \
        };                                                                    \
        _ZBUS_CPP_EXTERN const STRUCT_SECTION_ITERABLE(zbus_observer, _name) = {  \
                ZBUS_OBSERVER_NAME_INIT(_name) /* Name field */               \
                .type = ZBUS_OBSERVER_SUBSCRIBER_TYPE,                        \
                .data = &_CONCAT(_zbus_obs_data_, _name),                     \
                .queue = &_zbus_observer_queue_##_name,                       \
        }

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.
[in]	_enable	The subscriber initial enable state.

Enumeration Type Documentation

zbus_observer_type

enum zbus_observer_type

#include <zephyr/zbus/zbus.h>

Type used to represent an observer type.

A observer can be a listener or a subscriber.

Enumerator
ZBUS_OBSERVER_LISTENER_TYPE
ZBUS_OBSERVER_SUBSCRIBER_TYPE
ZBUS_OBSERVER_MSG_SUBSCRIBER_TYPE

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 <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 <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 <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 already locked 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 <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.
-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 <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 already locked 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 <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 <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 <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.
-EBUSY	The channel's semaphore returned without waiting.
-EAGAIN	Timeout to take the channel's semaphore.
-ENOMEM	There is not more buffer on the messgage buffers pool.
-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 <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_pub_stats_avg_period()

static uint32_t zbus_chan_pub_stats_avg_period ( const struct zbus_channel * chan )

inlinestatic

#include <zephyr/zbus/zbus.h>

Get the average period between publishes to a channel.

Note

Will return 0 if channel has not yet been published to.

Parameters

chan	The channel's reference.

Returns

Average duration in milliseconds between publishes.

zbus_chan_pub_stats_count()

static uint32_t zbus_chan_pub_stats_count ( const struct zbus_channel * chan )

inlinestatic

#include <zephyr/zbus/zbus.h>

Get the number of times a channel has been published to.

Note

Will return 0 if channel has not yet been published to.

Parameters

chan	The channel's reference.

Returns

The number of times a channel has been published to.

zbus_chan_pub_stats_last_time()

static k_ticks_t zbus_chan_pub_stats_last_time ( const struct zbus_channel * chan )

inlinestatic

#include <zephyr/zbus/zbus.h>

Get the time a channel was last published to.

Note

Will return 0 if channel has not yet been published to.

Parameters

chan	The channel's reference.

Returns

The kernel timestamp of the last publishing action.

zbus_chan_pub_stats_update()

static void zbus_chan_pub_stats_update ( const struct zbus_channel * chan )

inlinestatic

#include <zephyr/zbus/zbus.h>

Update the publishing statistics for a channel.

This function updates the publishing statistics for the zbus_chan_claim -> zbus_chan_finish workflow, which cannot automatically determine whether new data has been published or not.

Warning

This function must only be used directly for already locked channels.

Parameters

chan	The channel's reference.

zbus_chan_read()

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

#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 <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_set_msg_sub_pool()

static void zbus_chan_set_msg_sub_pool ( const struct zbus_channel * chan, struct net_buf_pool * pool )

inlinestatic

#include <zephyr/zbus/zbus.h>

Set the channel's msg subscriber net_buf pool.

Parameters

chan	The channel's reference.
pool	The reference to the net_buf memory pool.

zbus_chan_user_data()

static void * zbus_chan_user_data ( const struct zbus_channel * chan )

inlinestatic

#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(*

iterator_func )(const struct zbus_channel *chan)

)

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

Parameters

[in]

iterator_func

The function that will be execute on each iteration.

Return values

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

zbus_iterate_over_channels_with_user_data()

bool zbus_iterate_over_channels_with_user_data	(	bool(*	iterator_func )(const struct zbus_channel *chan, void *user_data),
		void *	user_data )

#include <zephyr/zbus/zbus.h>

Iterate over channels with user data.

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.

Parameters

[in]	iterator_func	The function that will be execute on each iteration.
[in]	user_data	The user data that can be passed in the function.

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(*

iterator_func )(const struct zbus_observer *obs)

)

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

Parameters

[in]

iterator_func

The function that will be execute on each iteration.

Return values

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

zbus_iterate_over_observers_with_user_data()

bool zbus_iterate_over_observers_with_user_data	(	bool(*	iterator_func )(const struct zbus_observer *obs, void *user_data),
		void *	user_data )

#include <zephyr/zbus/zbus.h>

Iterate over observers with user data.

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.

Parameters

[in]	iterator_func	The function that will be execute on each iteration.
[in]	user_data	The user data that can be passed in the function.

Return values

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

zbus_obs_attach_to_thread()

int zbus_obs_attach_to_thread

(

const struct zbus_observer *

obs

)

#include <zephyr/zbus/zbus.h>

Set the observer thread priority by attaching it to a thread.

Parameters

[in]

obs

The observer's reference.

Return values

0	Observer detached from the thread.
-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_obs_detach_from_thread()

int zbus_obs_detach_from_thread

(

const struct zbus_observer *

obs

)

#include <zephyr/zbus/zbus.h>

Clear the observer thread priority by detaching it from a thread.

Parameters

[in]

obs

The observer's reference.

Return values

0	Observer detached from the thread.
-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_obs_is_chan_notification_masked()

int zbus_obs_is_chan_notification_masked	(	const struct zbus_observer *	obs,
		const struct zbus_channel *	chan,
		bool *	masked )

#include <zephyr/zbus/zbus.h>

Get the notifications masking state from a channel to an observer.

Parameters

	obs	The observer's reference to be added.
	chan	The channel's reference.
[out]	masked	The mask state. When the mask is true, the observer will not receive notifications from the channel.

Return values

0	Retrieved the masked state.
-ESRCH	No observation found for the related pair chan/obs.
-EINVAL	Some parameter is invalid.

zbus_obs_is_enabled()

static int zbus_obs_is_enabled ( const struct zbus_observer * obs, bool * enable )

inlinestatic

#include <zephyr/zbus/zbus.h>

Get the observer state.

This routine retrieves the observer state.

Parameters

[in]	obs	The observer's reference.
[out]	enable	The boolean output's reference.

Returns

Observer state.

zbus_obs_name()

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

inlinestatic

#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_chan_notification_mask()

int zbus_obs_set_chan_notification_mask	(	const struct zbus_observer *	obs,
		const struct zbus_channel *	chan,
		bool	masked )

#include <zephyr/zbus/zbus.h>

Mask notifications from a channel to an observer.

The observer can mask notifications from a specific observing channel by calling this function.

Parameters

obs	The observer's reference to be added.
chan	The channel's reference.
masked	The mask state. When the mask is true, the observer will not receive notifications from the channel.

Return values

0	Channel notifications masked to the observer.
-ESRCH	No observation found for the related pair chan/obs.
-EINVAL	Some parameter is invalid.

zbus_obs_set_enable()

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

#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_sub_wait()

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

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

zbus_sub_wait_msg()

int zbus_sub_wait_msg	(	const struct zbus_observer *	sub,
		const struct zbus_channel **	chan,
		void *	msg,
		k_timeout_t	timeout )

#include <zephyr/zbus/zbus.h>

Wait for a channel message.

This routine makes the subscriber wait for the new message in case of channel publication.

Parameters

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

Return values

0	Message received.
-EINVAL	The observer is not a subscriber.
-ENOMSG	Could not retrieve the net_buf from the subscriber FIFO.
-EILSEQ	Received an invalid channel reference.
-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.