Zephyr zbus - 2 API说明

Creative Commons
本作品采用知识共享署名
发表于 | 分类于 | | 阅读次数：

本文说明zbus API的用途和参数。

API参考

ZBUS_OBS_DECLARE(...)
声明观察者，可同时声明多个，其他文件中声明后可访问该观察者

ZBUS_CHAN_DECLARE(...)
声明zbus通道，可同时声明多个，其他文件中声明后可访问该通道

ZBUS_OBSERVERS(...)
此宏为通道列出观察者，观察者通知的顺序与列出的顺序相同。作为宏ZBUS_CHAN_DEFINE的_observers参数

ZBUS_OBSERVERS_EMPTY
如果通道没有观察者，用该宏指示。作为宏ZBUS_CHAN_DEFINE的_observers参数

ZBUS_CHAN_DEFINE(_name, _type, _validator, _user_data, _observers, _init_val)
定义通道

  1. _name: 通道名称
  2. _type: 通道使用消息类型，一个结构体
  3. _validator: 消息验证器函数指针
  4. _user_data: 用户数据指针
  5. _observers: 观察者列表，由ZBUS_OBSERVERS列出
  6. _init_val: 消息初始值，由ZBUS_MSG_INIT完成

ZBUS_MSG_INIT(_val, ...)
初始化 zbus 消息，可变参列表，c99的结构体初始化模式, 与消息类型结构体一致，例如：
ZBUS_INIT(0) 等于 {0}
ZBUS_INIT(.a=10, .b=30) 等于 {.a=10, .b=30}.

ZBUS_SUBSCRIBER_DEFINE(_name, _queue_size)
定义订阅者

  1. _name: 订阅者名称
  2. _queue_size: 订阅者队列大小

ZBUS_LISTENER_DEFINE(_name, _cb)
定义监听者

  1. _name: 监听器名称
  2. _cb: 监听回调函数指针

int zbus_chan_pub(const struct zbus_channel *chan, const void *msg, k_timeout_t timeout)
向指定通道发布消息，如果成功发布消息，则返回值为 0；否则，返回一个负数错误码。

  1. chan: 指向要发布消息的通道的指针。
  2. msg: 指向要发布的消息数据的指针。
  3. timeout: 发布操作的超时时间。

int zbus_chan_read(const struct zbus_channel *chan, void *msg, k_timeout_t timeout)
从指定的通道读取消息，该函数将阻塞当前线程，直到从通道中读取到消息或者超时时间到达。如果成功读取到消息，则将其存储在 msg 缓冲区中，并返回消息数据的长度。如果超时时间到达而没有读取到任何消息，则返回一个负数错误码。

  1. chan: 指向要读取消息的 zbus 通道的指针。
  2. msg: 指向存储消息数据的缓冲区的指针。
  3. timeout: 读取操作的超时时间。

int zbus_chan_claim(const struct zbus_channel *chan, k_timeout_t timeout)
认领指定通道，请求成功后该通道无法发布和读取，直到完成认领该通道。请求通道就是对该通道上锁。该函数将阻塞当前线程，直到成功获取到消息缓冲区或者超时时间到达。如果成功获取到消息缓冲区，则返回一个指向该缓冲区的指针；否则，返回一个负数错误码。

  1. chan: 指向要认领通道的指针。
  2. timeout: 请求操作的超时时间。

int zbus_chan_finish(const struct zbus_channel *chan)
完成认领指定通道，必须和zbus_chan_claim配对使用。如果成功释放消息缓冲区，则返回值为 0；否则，返回一个负数错误码。

  1. chan: 指向完成认领通道的指针。

int zbus_chan_notify(const struct zbus_channel *chan, k_timeout_t timeout)
强制通道nodify，一般使用在claiming/finishing，通常是手动修改chan内message后才会调用，该函数将阻塞当前线程，直到成功发送通知信号或者超时时间到达。如果成功发送通知信号，则返回值为 0；否则，返回一个负数错误码。

  1. chan: 指向要发送通知通道的指针。
  2. timeout: 等待操作的超时时间

static inline const char *zbus_chan_name(const struct zbus_channel *chan)
获取指定通道的名称

static inline void *zbus_chan_msg(const struct zbus_channel *chan)
获取指定通道消息引用指针，通常在监听器内部调用该函数获取消息。

static inline const void *zbus_chan_const_msg(const struct zbus_channel *chan)
获取指定通道消息常量引用指针，通常在监听器内部调用该函数获取消息。该函数可以防止监听器修改消息。

static inline uint16_t zbus_chan_msg_size(const struct zbus_channel *chan)
获取通道消息的大小，也就是消息结构体的大小

static inline void *zbus_chan_user_data(const struct zbus_channel *chan)
获取消息中用户数据的指针

int zbus_chan_add_obs(const struct zbus_channel *chan, const struct zbus_observer *obs, k_timeout_t timeout)
向指定通道添加一个观察者，该函数将阻塞当前线程，直到成功添加观察者或者超时时间到达。如果成功添加观察者，则返回值为 0；否则，返回一个负数错误码。

  1. chan: 指向要添加观察者的 zbus 通道的指针。
  2. obs: 指向要添加的观察者的指针。
  3. timeout: 等待操作的超时时间。

int zbus_chan_rm_obs(const struct zbus_channel *chan, const struct zbus_observer *obs, k_timeout_t timeout)
从指定通道中删除一个观察者，该函数将阻塞当前线程，直到成功删除观察者或者超时时间到达。如果成功删除观察者，则返回值为 0；否则，返回一个负数错误码。

  1. chan: 指向要删除观察者的 zbus 通道的指针。
  2. obs: 指向要删除的观察者的指针。
  3. timeout: 等待操作的超时时间。

struct k_mem_slab *zbus_runtime_obs_pool(void)
获取运行时的观察者内存池，运行时创建的观察者从该内存池中分配

static inline int zbus_obs_set_enable(struct zbus_observer *obs, bool enabled)
启用或禁用指定的观察者，如果成功设置了观察者的启用状态，则返回值为 0；否则，返回一个负数错误码。

  1. obs: 指向要启用或禁用的观察者的指针。
  2. enabled: 一个布尔值，表示是否启用观察者。

static inline const char *zbus_obs_name(const struct zbus_observer *obs)
获取观察者名称

int zbus_sub_wait(const struct zbus_observer *sub, const struct zbus_channel **chan, k_timeout_t timeout)
等待观察者在通道上收到消息。该函数将阻塞当前线程，直到观察者接收到一个消息或者超时时间到达。如果成功接收到一个消息，则返回值为 0；否则，返回一个负数错误码。

  1. sub: 指向要等待的观察者的指针。
  2. chan: 指向要等待消息通道的指针。
  3. timeout: 等待操作的超时时间。

bool zbus_iterate_over_channels(bool (*iterator_func)(const struct zbus_channel *chan))
用iterator_func遍历所有通道

bool zbus_iterate_over_observers(bool (*iterator_func)(const struct zbus_observer *obs))
用iterator_func遍历所有观察者

参考

https://docs.zephyrproject.org/3.3.0/services/zbus/index.html