zbus_proxy_agent.h

Go to the documentation of this file.

/*
 * Copyright (c) 2026 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_ZBUS_PROXY_AGENT_H_
#define ZEPHYR_INCLUDE_ZBUS_PROXY_AGENT_H_
 
#include <zephyr/kernel.h>
#include <zephyr/sys/iterable_sections.h>
#include <zephyr/zbus/zbus.h>
 
#ifdef __cplusplus
extern "C" {
#endif

 
/* Forward declarations */
struct zbus_proxy_agent_backend_api;
struct zbus_proxy_agent;

enum zbus_proxy_agent_backend_type {
        ZBUS_PROXY_AGENT_BACKEND_IPC,
};

struct zbus_shadow_channel {
        const struct zbus_channel *chan;
        const struct zbus_proxy_agent *proxy_agent;
};

struct zbus_proxy_msg {
        uint32_t message_size;
        uint8_t message[CONFIG_ZBUS_PROXY_AGENT_MAX_MESSAGE_SIZE];
        uint32_t channel_name_len;
        char channel_name[CONFIG_ZBUS_PROXY_AGENT_MAX_CHANNEL_NAME_SIZE];
};

struct zbus_proxy_agent_rx_msg {
        const struct zbus_channel *chan;
        uint8_t message[CONFIG_ZBUS_PROXY_AGENT_MAX_MESSAGE_SIZE];
};

struct zbus_proxy_agent {
        const char *name;
        enum zbus_proxy_agent_backend_type type;
        const void *backend_config;
        const struct zbus_proxy_agent_backend_api *backend_api;
        struct k_thread *thread;
        struct k_msgq *msgq;
        k_thread_stack_t *stack;
        k_tid_t *const thread_id;
};

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

struct zbus_proxy_agent_backend_api {
        int (*backend_init)(const struct zbus_proxy_agent *agent);
        int (*backend_send)(const struct zbus_proxy_agent *agent, struct zbus_proxy_msg *msg);
        int (*backend_set_recv_cb)(const struct zbus_proxy_agent *agent,
                                   zbus_proxy_agent_recv_cb_t recv_cb);
};

struct zbus_proxy_agent_backend_desc {
        enum zbus_proxy_agent_backend_type type;
        const struct zbus_proxy_agent_backend_api *api;
};

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

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

int zbus_init_proxy_agent(const struct zbus_proxy_agent *agent);

#define ZBUS_PROXY_AGENT_DEFINE(_name, _type, _backend_dt_node)                                    \
        _ZBUS_PROXY_AGENT_BACKEND_CONFIG_DEFINE(_name, _type, _backend_dt_node)                    \
        K_THREAD_STACK_DEFINE(_name##_thread_stack,                                                \
                              CONFIG_ZBUS_PROXY_AGENT_WORK_QUEUE_STACK_SIZE);                      \
        K_MSGQ_DEFINE(_name##_rx_msgq, sizeof(struct zbus_proxy_agent_rx_msg),                     \
                      CONFIG_ZBUS_PROXY_AGENT_RX_QUEUE_DEPTH, 4);                                  \
        static struct k_thread _name##_thread;                                                     \
        static k_tid_t _name##_thread_id;                                                          \
        const struct zbus_proxy_agent _name = {                                                    \
                .name = #_name,                                                                    \
                .type = _type,                                                                     \
                .backend_config = _ZBUS_PROXY_AGENT_GET_BACKEND_CONFIG(_name, _type),              \
                .backend_api = _ZBUS_PROXY_AGENT_GET_BACKEND_API(_type),                           \
                .thread = &_name##_thread,                                                         \
                .msgq = &_name##_rx_msgq,                                                          \
                .stack = _name##_thread_stack,                                                     \
                .thread_id = &_name##_thread_id,                                                   \
        };                                                                                         \
        static void _name##_zbus_listener_cb(const struct zbus_channel *chan)                      \
        {                                                                                          \
                zbus_proxy_agent_listener_cb(chan, &_name);                                        \
        }                                                                                          \
        ZBUS_LISTENER_DEFINE(_name##_listener, _name##_zbus_listener_cb);                          \
        _ZBUS_PROXY_AGENT_GENERATE_SHADOW_VALIDATOR(_name);                                        \
        static int _name##_init(void)                                                              \
        {                                                                                          \
                return zbus_init_proxy_agent(&_name);                                              \
        }                                                                                          \
        SYS_INIT(_name##_init, APPLICATION, CONFIG_ZBUS_PROXY_AGENT_INIT_PRIORITY)


#define _ZBUS_PROXY_AGENT_BACKEND_CONFIG_DEFINE(_name, _type, _backend_dt_node)                    \
        _ZBUS_PROXY_AGENT_BACKEND_CONFIG_DEFINE_##_type(_name, _backend_dt_node)

#define _ZBUS_PROXY_AGENT_GET_BACKEND_CONFIG(_name, _type)                                         \
        _ZBUS_PROXY_AGENT_GET_BACKEND_CONFIG_##_type(_name)

#define _ZBUS_PROXY_AGENT_GET_BACKEND_API(_type) _ZBUS_PROXY_AGENT_GET_BACKEND_API_##_type

void zbus_proxy_agent_log_shadow_pub_denied(const struct zbus_proxy_agent *agent);

#define _ZBUS_PROXY_AGENT_VALIDATOR(_proxy_name) _proxy_name##_shadow_validator

#define _ZBUS_PROXY_AGENT_GENERATE_SHADOW_VALIDATOR(_proxy_name)                                   \
        bool _proxy_name##_shadow_validator(const void *msg, size_t msg_size)                      \
        {                                                                                          \
                (void)msg;                                                                         \
                (void)msg_size;                                                                    \
                /* Only allow publishing from the proxy agent's dedicated thread */                \
                if (k_current_get() != *_proxy_name.thread_id) {                                   \
                        zbus_proxy_agent_log_shadow_pub_denied(&_proxy_name);                      \
                        return false;                                                              \
                }                                                                                  \
                return true;                                                                       \
        }


#define ZBUS_PROXY_ADD_CHAN(_agent, _chan)                                                         \
        ZBUS_CHAN_ADD_OBS(_chan, _agent##_listener, zz)


#define _ZBUS_SHADOW_CHAN_REGISTER(_name, _proxy_name)                                             \
        extern const struct zbus_proxy_agent _proxy_name;                                          \
        static const STRUCT_SECTION_ITERABLE(zbus_shadow_channel,                                  \
                                             _CONCAT(_zbus_shadow_chan_, _name)) = {               \
                .chan = &_name,                                                                    \
                .proxy_agent = &_proxy_name,                                                       \
        }


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

#define ZBUS_SHADOW_CHAN_DEFINE_WITH_ID(_name, _id, _type, _proxy_name, _user_data, _observers,    \
                                        _init_val)                                                 \
        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)

 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_ZBUS_PROXY_AGENT_H_ */