nrf_rpc.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef _NRF_RPC_H_
#define _NRF_RPC_H_
 
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
 
#include <nrf_rpc_errno.h>
#include <nrf_rpc_common.h>
#include <nrf_rpc_tr.h>
#include <nrf_rpc_os.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define NRF_RPC_PROTOCOL_VERSION 0
 
#define NRF_RPC_ID_UNKNOWN 0xFF
 
#define NRF_RPC_FLAGS_WAIT_ON_INIT 0x01
 
#define NRF_RPC_FLAGS_INITIATOR 0x02
 
#define NRF_RPC_FLAG_COND(_cond, _flag) ((_cond) ? (_flag) : 0UL)
 
/* Forward declaration. */
struct nrf_rpc_err_report;
struct nrf_rpc_group;
 
enum nrf_rpc_packet_type {
        NRF_RPC_PACKET_TYPE_EVT  = 0x00, 
        NRF_RPC_PACKET_TYPE_RSP  = 0x01, 
        NRF_RPC_PACKET_TYPE_ACK  = 0x02, 
        NRF_RPC_PACKET_TYPE_ERR  = 0x03, 
        NRF_RPC_PACKET_TYPE_INIT = 0x04, 
        NRF_RPC_PACKET_TYPE_CMD  = 0x80, 
};
 
enum nrf_rpc_err_src {
        NRF_RPC_ERR_SRC_RECV,   
        NRF_RPC_ERR_SRC_SEND,   
        NRF_RPC_ERR_SRC_REMOTE, 
};
 
/* Helper nRF group structure declaration needed for callback definition. */
struct nrf_rpc_group;
 
typedef void (*nrf_rpc_handler_t)(const struct nrf_rpc_group *group, const uint8_t *packet,
                                  size_t len, void *handler_data);
 
typedef void (*nrf_rpc_ack_handler_t)(uint8_t id, void *handler_data);
 
typedef void (*nrf_rpc_err_handler_t)(const struct nrf_rpc_err_report *report);
 
typedef void (*nrf_rpc_group_bound_handler_t)(const struct nrf_rpc_group *group);
 
/* Structure used internally to define registered command or event decoder. */
struct _nrf_rpc_decoder {
        uint8_t id;
        nrf_rpc_handler_t handler;
        void *handler_data;
};
 
struct nrf_rpc_group_data {
        uint8_t src_group_id;
        uint8_t dst_group_id;
        struct nrf_rpc_os_event decode_done_event;
        bool transport_initialized;
};
 
struct nrf_rpc_group {
        const void *cmd_array;
        const void *evt_array;
        struct nrf_rpc_group_data *data;
        const struct nrf_rpc_tr *transport;
        nrf_rpc_ack_handler_t ack_handler;
        void *ack_handler_data;
        const char *strid;
        nrf_rpc_err_handler_t err_handler;
        nrf_rpc_group_bound_handler_t bound_handler;
        const uint32_t flags;
};
 
struct nrf_rpc_err_report {
 
        int code;
 
        const struct nrf_rpc_group *group;
 
        enum nrf_rpc_err_src src;
 
        uint8_t id;
 
        enum nrf_rpc_packet_type packet_type;
 
        const char *file;
 
        int line;
 
        const char *func;
};
 
struct nrf_rpc_cleanup_handler
{
        void (*handler)(void *context);
 
        void *context;
 
        struct nrf_rpc_cleanup_handler *next;
};
 
#define NRF_RPC_GROUP_DEFINE_INTERNAL__(_name, _strid, _transport, _ack_handler,  \
                                        _ack_data, _err_handler, _bound_handler,  \
                                        _wait_on_init, _initiator)                \
        NRF_RPC_AUTO_ARR(NRF_RPC_CONCAT(_name, _cmd_array),                       \
                         "cmd_" NRF_RPC_STRINGIFY(_name));                        \
        NRF_RPC_AUTO_ARR(NRF_RPC_CONCAT(_name, _evt_array),                       \
                         "evt_" NRF_RPC_STRINGIFY(_name));                        \
                                                                                  \
        static struct nrf_rpc_group_data NRF_RPC_CONCAT(_name, _group_data) = {   \
                .src_group_id = NRF_RPC_ID_UNKNOWN,                               \
                .dst_group_id = NRF_RPC_ID_UNKNOWN,                               \
                .transport_initialized = false,                                   \
        };                                                                        \
                                                                                  \
        NRF_RPC_AUTO_ARR_ITEM(const struct nrf_rpc_group, _name, "grp",               \
                              _strid) = {                                             \
                .cmd_array = &NRF_RPC_CONCAT(_name, _cmd_array),                      \
                .evt_array = &NRF_RPC_CONCAT(_name, _evt_array),                      \
                .data = &NRF_RPC_CONCAT(_name, _group_data),                          \
                .ack_handler = _ack_handler,                                          \
                .ack_handler_data = _ack_data,                                        \
                .strid = _strid,                                                      \
                .transport = _transport,                                              \
                .err_handler = _err_handler,                                          \
                .bound_handler = _bound_handler,                                      \
                .flags = NRF_RPC_FLAG_COND(_wait_on_init, NRF_RPC_FLAGS_WAIT_ON_INIT) \
                       | NRF_RPC_FLAG_COND(_initiator, NRF_RPC_FLAGS_INITIATOR),      \
        }
 
#define NRF_RPC_GROUP_DEFINE(_name, _strid, _transport, _ack_handler, _ack_data, _err_handler)     \
        NRF_RPC_GROUP_DEFINE_INTERNAL__(_name, _strid, _transport, _ack_handler, _ack_data,        \
                                        _err_handler, NULL,                                        \
                                        IS_ENABLED(CONFIG_NRF_RPC_GROUP_DEFAULT_WAIT_ON_INIT),     \
                                        IS_ENABLED(CONFIG_NRF_RPC_GROUP_DEFAULT_INITIATOR))
 
#define NRF_RPC_GROUP_DEFINE_NOWAIT(_name, _strid, _transport, _ack_handler,      \
                                    _ack_data, _err_handler, _bound_handler,      \
                                    _initiator)                                   \
        NRF_RPC_GROUP_DEFINE_INTERNAL__(_name, _strid, _transport, _ack_handler,  \
                                        _ack_data, _err_handler, _bound_handler,  \
                                        false, _initiator)                        \
 
#define NRF_RPC_GROUP_DECLARE(_name)                                           \
        extern const struct nrf_rpc_group _name
 
#define NRF_RPC_CMD_DECODER(_group, _name, _cmd, _handler, _data)              \
        NRF_RPC_STATIC_ASSERT(_cmd <= 0xFE, "Command out of range");           \
        NRF_RPC_AUTO_ARR_ITEM(const struct _nrf_rpc_decoder,                   \
                              NRF_RPC_CONCAT(_name, _cmd_dec),                 \
                              "cmd_" NRF_RPC_STRINGIFY(_group),                \
                              NRF_RPC_STRINGIFY(_name)) = {                    \
                .id = _cmd,                                                    \
                .handler = _handler,                                           \
                .handler_data = _data,                                         \
        }
 
#define NRF_RPC_EVT_DECODER(_group, _name, _evt, _handler, _data)              \
        NRF_RPC_STATIC_ASSERT(_evt <= 0xFE, "Event out of range");             \
        NRF_RPC_AUTO_ARR_ITEM(const struct _nrf_rpc_decoder,                   \
                               NRF_RPC_CONCAT(_name, _evt_dec),                \
                               "evt_" NRF_RPC_STRINGIFY(_group),               \
                               NRF_RPC_STRINGIFY(_name)) = {                   \
                .id = _evt,                                                    \
                .handler = _handler,                                           \
                .handler_data = _data,                                         \
        }
 
#define NRF_RPC_GROUP_STATUS(_group)                                                            \
        (_group.data->transport_initialized && (_group.data->dst_group_id != NRF_RPC_ID_UNKNOWN))
 
void nrf_rpc_set_bound_handler(nrf_rpc_group_bound_handler_t bound_handler);
 
int nrf_rpc_init(nrf_rpc_err_handler_t err_handler);
 
int nrf_rpc_setup(nrf_rpc_err_handler_t err_handler, nrf_rpc_group_bound_handler_t bound_handler);
 
int nrf_rpc_bind(void);
 
void nrf_rpc_unbind(void);
 
void nrf_rpc_register_cleanup_handler(struct nrf_rpc_cleanup_handler *handler);
 
 
void nrf_rpc_stop(bool cleanup);
 
void nrf_rpc_resume(void);
 
 
int nrf_rpc_cmd(const struct nrf_rpc_group *group, uint8_t cmd, uint8_t *packet,
                size_t len, nrf_rpc_handler_t handler, void *handler_data);
 
int nrf_rpc_cmd_rsp(const struct nrf_rpc_group *group, uint8_t cmd, uint8_t *packet,
                    size_t len, const uint8_t **rsp_packet, size_t *rsp_len);
 
void nrf_rpc_cmd_no_err(const struct nrf_rpc_group *group, uint8_t cmd, uint8_t *packet,
                        size_t len, nrf_rpc_handler_t handler, void *handler_data);
 
void nrf_rpc_cmd_rsp_no_err(const struct nrf_rpc_group *group, uint8_t cmd,
                            uint8_t *packet, size_t len, const uint8_t **rsp_packet,
                            size_t *rsp_len);
 
int nrf_rpc_evt(const struct nrf_rpc_group *group, uint8_t evt, uint8_t *packet,
                size_t len);
 
void nrf_rpc_evt_no_err(const struct nrf_rpc_group *group, uint8_t evt,
                        uint8_t *packet, size_t len);
 
int nrf_rpc_rsp(const struct nrf_rpc_group *group, uint8_t *packet, size_t len);
 
void nrf_rpc_rsp_no_err(const struct nrf_rpc_group *group, uint8_t *packet, size_t len);
 
void nrf_rpc_decoding_done(const struct nrf_rpc_group *group, const uint8_t *packet);
 
void nrf_rpc_err(int code, enum nrf_rpc_err_src src,
                 const struct nrf_rpc_group *group, uint8_t id,
                 uint8_t packet_type);
 
void nrf_rpc_err_impl(int code, enum nrf_rpc_err_src src,
        const struct nrf_rpc_group *group, uint8_t id,
        uint8_t packet_type, const char *file, int line, const char *func);
 
#ifdef CONFIG_NRF_RPC_DETAILED_ERROR_REPORTING
#define nrf_rpc_err(_code, _src, _group, _id, _packet_type) \
        nrf_rpc_err_impl(_code, _src, _group, _id, _packet_type, __FILE__, __LINE__, __func__)
#endif
 
void nrf_rpc_alloc_tx_buf(const struct nrf_rpc_group *group, uint8_t **buf, size_t len);
 
void nrf_rpc_free_tx_buf(const struct nrf_rpc_group *group, uint8_t *buf);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _NRF_RPC_H_ */