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;
};
 
#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, true, \
 true) \
 
#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))
 
int nrf_rpc_init(nrf_rpc_err_handler_t err_handler);
 
static inline 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);
 
static inline 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);
 
static inline 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);
 
static inline 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);
 
/* Inline definitions. */
 
static inline 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_common(const struct nrf_rpc_group *group, uint32_t cmd,
 uint8_t *packet, size_t len, void *ptr1,
 void *ptr2);
 
 return nrf_rpc_cmd_common(group, cmd, packet, len, handler,
 handler_data);
}
 
static inline 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)
{
 int nrf_rpc_cmd_common(const struct nrf_rpc_group *group, uint32_t cmd,
 uint8_t *packet, size_t len, void *ptr1,
 void *ptr2);
 
 return nrf_rpc_cmd_common(group, cmd | 0x10000, packet, len, rsp_packet,
 rsp_len);
}
 
static inline 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_common_no_err(const struct nrf_rpc_group *group,
 uint32_t cmd, uint8_t *packet,
 size_t len, void *ptr1, void *ptr2);
 
 nrf_rpc_cmd_common_no_err(group, cmd, packet, len, handler,
 handler_data);
}
 
static inline 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)
{
 void nrf_rpc_cmd_common_no_err(const struct nrf_rpc_group *group,
 uint32_t cmd, uint8_t *packet,
 size_t len, void *ptr1, void *ptr2);
 
 nrf_rpc_cmd_common_no_err(group, cmd | 0x10000, packet, len, rsp_packet,
 rsp_len);
}
 
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_ */