| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| #ifndef H_MGMT_MGMT_ |
| #define H_MGMT_MGMT_ |
| |
| #include <inttypes.h> |
| #include "tinycbor/cbor.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /* MTU for newtmgr responses */ |
| #define MGMT_MAX_MTU 1024 |
| |
| /** Opcodes; encoded in first byte of header. */ |
| #define MGMT_OP_READ 0 |
| #define MGMT_OP_READ_RSP 1 |
| #define MGMT_OP_WRITE 2 |
| #define MGMT_OP_WRITE_RSP 3 |
| |
| /** |
| * The first 64 groups are reserved for system level mcumgr commands. |
| * Per-user commands are then defined after group 64. |
| */ |
| #define MGMT_GROUP_ID_OS 0 |
| #define MGMT_GROUP_ID_IMAGE 1 |
| #define MGMT_GROUP_ID_STAT 2 |
| #define MGMT_GROUP_ID_CONFIG 3 |
| #define MGMT_GROUP_ID_LOG 4 |
| #define MGMT_GROUP_ID_CRASH 5 |
| #define MGMT_GROUP_ID_SPLIT 6 |
| #define MGMT_GROUP_ID_RUN 7 |
| #define MGMT_GROUP_ID_FS 8 |
| #define MGMT_GROUP_ID_SHELL 9 |
| #define MGMT_GROUP_ID_PERUSER 64 |
| |
| /** |
| * mcumgr error codes. |
| */ |
| #define MGMT_ERR_EOK 0 |
| #define MGMT_ERR_EUNKNOWN 1 |
| #define MGMT_ERR_ENOMEM 2 |
| #define MGMT_ERR_EINVAL 3 |
| #define MGMT_ERR_ETIMEOUT 4 |
| #define MGMT_ERR_ENOENT 5 |
| #define MGMT_ERR_EBADSTATE 6 /* Current state disallows command. */ |
| #define MGMT_ERR_EMSGSIZE 7 /* Response too large. */ |
| #define MGMT_ERR_ENOTSUP 8 /* Command not supported. */ |
| #define MGMT_ERR_ECORRUPT 9 /* Corrupt */ |
| #define MGMT_ERR_EPERUSER 256 |
| |
| #define MGMT_HDR_SIZE 8 |
| |
| /* |
| * MGMT event opcodes. |
| */ |
| #define MGMT_EVT_OP_CMD_RECV 0x01 |
| #define MGMT_EVT_OP_CMD_STATUS 0x02 |
| #define MGMT_EVT_OP_CMD_DONE 0x03 |
| |
| struct mgmt_hdr { |
| #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ |
| uint8_t nh_op:3; /* MGMT_OP_[...] */ |
| uint8_t _res1:5; |
| #endif |
| #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__ |
| uint8_t _res1:5; |
| uint8_t nh_op:3; /* MGMT_OP_[...] */ |
| #endif |
| uint8_t nh_flags; /* Reserved for future flags */ |
| uint16_t nh_len; /* Length of the payload */ |
| uint16_t nh_group; /* MGMT_GROUP_ID_[...] */ |
| uint8_t nh_seq; /* Sequence number */ |
| uint8_t nh_id; /* Message ID within group */ |
| }; |
| |
| #define nmgr_hdr mgmt_hdr |
| |
| /* |
| * MGMT_EVT_OP_CMD_STATUS argument |
| */ |
| struct mgmt_evt_op_cmd_status_arg { |
| int status; |
| }; |
| |
| /* |
| * MGMT_EVT_OP_CMD_DONE argument |
| */ |
| struct mgmt_evt_op_cmd_done_arg { |
| int err; /* MGMT_ERR_[...] */ |
| }; |
| |
| /** @typedef mgmt_on_evt_cb |
| * @brief Function to be called on MGMT event. |
| * |
| * This callback function is used to notify application about mgmt event. |
| * |
| * @param opcode MGMT_EVT_OP_[...]. |
| * @param group MGMT_GROUP_ID_[...]. |
| * @param id Message ID within group. |
| * @param arg Optional event argument. |
| */ |
| typedef void mgmt_on_evt_cb(uint8_t opcode, uint16_t group, uint8_t id, |
| void *arg); |
| |
| /** @typedef mgmt_alloc_rsp_fn |
| * @brief Allocates a buffer suitable for holding a response. |
| * |
| * If a source buf is provided, its user data is copied into the new buffer. |
| * |
| * @param src_buf An optional source buffer to copy user data |
| * from. |
| * @param arg Optional streamer argument. |
| * |
| * @return Newly-allocated buffer on success |
| * NULL on failure. |
| */ |
| typedef void *mgmt_alloc_rsp_fn(const void *src_buf, void *arg); |
| |
| /** @typedef mgmt_trim_front_fn |
| * @brief Trims data from the front of a buffer. |
| * |
| * If the amount to trim exceeds the size of the buffer, the buffer is |
| * truncated to a length of 0. |
| * |
| * @param buf The buffer to trim. |
| * @param len The number of bytes to remove. |
| * @param arg Optional streamer argument. |
| */ |
| typedef void mgmt_trim_front_fn(void *buf, size_t len, void *arg); |
| |
| /** @typedef mgmt_reset_buf_fn |
| * @brief Resets a buffer to a length of 0. |
| * |
| * The buffer's user data remains, but its payload is cleared. |
| * |
| * @param buf The buffer to reset. |
| * @param arg Optional streamer argument. |
| */ |
| typedef void mgmt_reset_buf_fn(void *buf, void *arg); |
| |
| /** @typedef mgmt_write_at_fn |
| * @brief Writes data to a CBOR encoder. |
| * |
| * Any existing data at the specified offset is overwritten by the new data. |
| * Any new data that extends past the buffer's current length is appended. |
| * |
| * @param writer The encoder to write to. |
| * @param offset The byte offset to write to, |
| * @param data The data to write. |
| * @param len The number of bytes to write. |
| * @param arg Optional streamer argument. |
| * |
| * @return 0 on success, MGMT_ERR_[...] code on failure. |
| */ |
| typedef int mgmt_write_at_fn(struct cbor_encoder_writer *writer, size_t offset, |
| const void *data, size_t len, void *arg); |
| |
| /** @typedef mgmt_init_reader_fn |
| * @brief Initializes a CBOR reader with the specified buffer. |
| * |
| * @param reader The reader to initialize. |
| * @param buf The buffer to configure the reader with. |
| * @param arg Optional streamer argument. |
| * |
| * @return 0 on success, MGMT_ERR_[...] code on failure. |
| */ |
| typedef int mgmt_init_reader_fn(struct cbor_decoder_reader *reader, void *buf, |
| void *arg); |
| |
| /** @typedef mgmt_init_writer_fn |
| * @brief Initializes a CBOR writer with the specified buffer. |
| * |
| * @param writer The writer to initialize. |
| * @param buf The buffer to configure the writer with. |
| * @param arg Optional streamer argument. |
| * |
| * @return 0 on success, MGMT_ERR_[...] code on failure. |
| */ |
| typedef int mgmt_init_writer_fn(struct cbor_encoder_writer *writer, void *buf, |
| void *arg); |
| |
| /** @typedef mgmt_init_writer_fn |
| * @brief Frees the specified buffer. |
| * |
| * @param buf The buffer to free. |
| * @param arg Optional streamer argument. |
| */ |
| typedef void mgmt_free_buf_fn(void *buf, void *arg); |
| |
| /** |
| * @brief Configuration for constructing a mgmt_streamer object. |
| */ |
| struct mgmt_streamer_cfg { |
| mgmt_alloc_rsp_fn *alloc_rsp; |
| mgmt_trim_front_fn *trim_front; |
| mgmt_reset_buf_fn *reset_buf; |
| mgmt_write_at_fn *write_at; |
| mgmt_init_reader_fn *init_reader; |
| mgmt_init_writer_fn *init_writer; |
| mgmt_free_buf_fn *free_buf; |
| }; |
| |
| /** |
| * @brief Decodes requests and encodes responses for any mcumgr protocol. |
| */ |
| struct mgmt_streamer { |
| const struct mgmt_streamer_cfg *cfg; |
| void *cb_arg; |
| struct cbor_decoder_reader *reader; |
| struct cbor_encoder_writer *writer; |
| }; |
| |
| /** |
| * @brief Context required by command handlers for parsing requests and writing |
| * responses. |
| */ |
| struct mgmt_ctxt { |
| struct CborEncoder encoder; |
| struct CborParser parser; |
| struct CborValue it; |
| }; |
| |
| /** @typedef mgmt_handler_fn |
| * @brief Processes a request and writes the corresponding response. |
| * |
| * A separate handler is required for each supported op-ID pair. |
| * |
| * @param ctxt The mcumgr context to use. |
| * |
| * @return 0 if a response was successfully encoded, |
| * MGMT_ERR_[...] code on failure. |
| */ |
| typedef int mgmt_handler_fn(struct mgmt_ctxt *ctxt); |
| |
| /** |
| * @brief Read handler and write handler for a single command ID. |
| */ |
| struct mgmt_handler { |
| mgmt_handler_fn *mh_read; |
| mgmt_handler_fn *mh_write; |
| }; |
| |
| /** |
| * @brief A collection of handlers for an entire command group. |
| */ |
| struct mgmt_group { |
| /** Points to the next group in the list. */ |
| struct mgmt_group *mg_next; |
| |
| /** Array of handlers; one entry per command ID. */ |
| const struct mgmt_handler *mg_handlers; |
| uint16_t mg_handlers_count; |
| |
| /* The numeric ID of this group. */ |
| uint16_t mg_group_id; |
| }; |
| |
| /** |
| * @brief Uses the specified streamer to allocates a response buffer. |
| * |
| * If a source buf is provided, its user data is copied into the new buffer. |
| * |
| * @param streamer The streamer providing the callback. |
| * @param src_buf An optional source buffer to copy user data |
| * from. |
| * |
| * @return Newly-allocated buffer on success |
| * NULL on failure. |
| */ |
| void *mgmt_streamer_alloc_rsp(struct mgmt_streamer *streamer, |
| const void *src_buf); |
| |
| /** |
| * @brief Uses the specified streamer to trim data from the front of a buffer. |
| * |
| * If the amount to trim exceeds the size of the buffer, the buffer is |
| * truncated to a length of 0. |
| * |
| * @param streamer The streamer providing the callback. |
| * @param buf The buffer to trim. |
| * @param len The number of bytes to remove. |
| */ |
| void mgmt_streamer_trim_front(struct mgmt_streamer *streamer, void *buf, |
| size_t len); |
| |
| /** |
| * @brief Uses the specified streamer to reset a buffer to a length of 0. |
| * |
| * The buffer's user data remains, but its payload is cleared. |
| * |
| * @param streamer The streamer providing the callback. |
| * @param buf The buffer to reset. |
| */ |
| void mgmt_streamer_reset_buf(struct mgmt_streamer *streamer, void *buf); |
| |
| /** |
| * @brief Uses the specified streamer to write data to a CBOR encoder. |
| * |
| * Any existing data at the specified offset is overwritten by the new data. |
| * Any new data that extends past the buffer's current length is appended. |
| * |
| * @param streamer The streamer providing the callback. |
| * @param writer The encoder to write to. |
| * @param offset The byte offset to write to, |
| * @param data The data to write. |
| * @param len The number of bytes to write. |
| * |
| * @return 0 on success, MGMT_ERR_[...] code on failure. |
| */ |
| int mgmt_streamer_write_at(struct mgmt_streamer *streamer, size_t offset, |
| const void *data, int len); |
| |
| /** |
| * @brief Uses the specified streamer to initialize a CBOR reader. |
| * |
| * @param streamer The streamer providing the callback. |
| * @param reader The reader to initialize. |
| * @param buf The buffer to configure the reader with. |
| * |
| * @return 0 on success, MGMT_ERR_[...] code on failure. |
| */ |
| int mgmt_streamer_init_reader(struct mgmt_streamer *streamer, void *buf); |
| |
| /** |
| * @brief Uses the specified streamer to initializes a CBOR writer. |
| * |
| * @param streamer The streamer providing the callback. |
| * @param writer The writer to initialize. |
| * @param buf The buffer to configure the writer with. |
| * |
| * @return 0 on success, MGMT_ERR_[...] code on failure. |
| */ |
| int mgmt_streamer_init_writer(struct mgmt_streamer *streamer, void *buf); |
| |
| /** |
| * @brief Uses the specified streamer to free a buffer. |
| * |
| * @param streamer The streamer providing the callback. |
| * @param buf The buffer to free. |
| */ |
| void mgmt_streamer_free_buf(struct mgmt_streamer *streamer, void *buf); |
| |
| /** |
| * @brief Registers a full command group. |
| * |
| * @param group The group to register. |
| */ |
| void mgmt_register_group(struct mgmt_group *group); |
| |
| /** |
| * @brief Unregisters a full command group. |
| * |
| * @param group The group to register. |
| */ |
| void |
| mgmt_unregister_group(struct mgmt_group *group); |
| |
| /** |
| * @brief Finds a registered command handler. |
| * |
| * @param group_id The group of the command to find. |
| * @param command_id The ID of the command to find. |
| * |
| * @return The requested command handler on success; |
| * NULL on failure. |
| */ |
| const struct mgmt_handler *mgmt_find_handler(uint16_t group_id, |
| uint16_t command_id); |
| |
| /** |
| * @brief Encodes a response status into the specified management context. |
| * |
| * @param ctxt The management context to encode into. |
| * @param status The response status to write. |
| * |
| * @return 0 on success, MGMT_ERR_[...] code on failure. |
| */ |
| int mgmt_write_rsp_status(struct mgmt_ctxt *ctxt, int status); |
| |
| /** |
| * @brief Initializes a management context object with the specified streamer. |
| * |
| * @param ctxt The context object to initialize. |
| * @param streamer The streamer that will be used with the |
| * context. |
| * |
| * @return 0 on success, MGMT_ERR_[...] code on failure. |
| */ |
| int mgmt_ctxt_init(struct mgmt_ctxt *ctxt, struct mgmt_streamer *streamer); |
| |
| /** |
| * @brief Converts a CBOR status code to a MGMT_ERR_[...] code. |
| * |
| * @param cbor_status The CBOR status code to convert. |
| * |
| * @return The corresponding MGMT_ERR_[,,,] code. |
| */ |
| int mgmt_err_from_cbor(int cbor_status); |
| |
| /** |
| * @brief Byte-swaps an mcumgr header from network to host byte order. |
| * |
| * @param hdr The mcumgr header to byte-swap. |
| */ |
| void mgmt_ntoh_hdr(struct mgmt_hdr *hdr); |
| |
| /** |
| * @brief Byte-swaps an mcumgr header from host to network byte order. |
| * |
| * @param hdr The mcumgr header to byte-swap. |
| */ |
| void mgmt_hton_hdr(struct mgmt_hdr *hdr); |
| |
| /** |
| * @brief Register event callback function. |
| * |
| * @param cb Callback function. |
| */ |
| void mgmt_register_evt_cb(mgmt_on_evt_cb *cb); |
| |
| /** |
| * @brief This function is called to notify about mgmt event. |
| * |
| * @param opcode MGMT_EVT_OP_[...]. |
| * @param group MGMT_GROUP_ID_[...]. |
| * @param id Message ID within group. |
| * @param arg Optional event argument. |
| */ |
| void mgmt_evt(uint8_t opcode, uint16_t group, uint8_t id, void *arg); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* MGMT_MGMT_H_ */ |
