1 /* 2 * Copyright (c) 2018-2021 mcumgr authors 3 * Copyright (c) 2022-2024 Nordic Semiconductor ASA 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 8 #ifndef H_MGMT_MGMT_ 9 #define H_MGMT_MGMT_ 10 11 #include <inttypes.h> 12 #include <zephyr/sys/slist.h> 13 #include <zephyr/mgmt/mcumgr/smp/smp.h> 14 #include <zephyr/mgmt/mcumgr/mgmt/mgmt_defines.h> 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 /** 21 * @brief MCUmgr mgmt API 22 * @defgroup mcumgr_mgmt_api MCUmgr mgmt API 23 * @since 1.11 24 * @version 1.0.0 25 * @ingroup mcumgr 26 * @{ 27 */ 28 29 /** @typedef mgmt_alloc_rsp_fn 30 * @brief Allocates a buffer suitable for holding a response. 31 * 32 * If a source buf is provided, its user data is copied into the new buffer. 33 * 34 * @param src_buf An optional source buffer to copy user data from. 35 * @param arg Optional streamer argument. 36 * 37 * @return Newly-allocated buffer on success NULL on failure. 38 */ 39 typedef void *(*mgmt_alloc_rsp_fn)(const void *src_buf, void *arg); 40 41 /** @typedef mgmt_reset_buf_fn 42 * @brief Resets a buffer to a length of 0. 43 * 44 * The buffer's user data remains, but its payload is cleared. 45 * 46 * @param buf The buffer to reset. 47 * @param arg Optional streamer argument. 48 */ 49 typedef void (*mgmt_reset_buf_fn)(void *buf, void *arg); 50 51 #ifdef CONFIG_MCUMGR_SMP_VERBOSE_ERR_RESPONSE 52 #define MGMT_CTXT_SET_RC_RSN(mc, rsn) ((mc->rc_rsn) = (rsn)) 53 #define MGMT_CTXT_RC_RSN(mc) ((mc)->rc_rsn) 54 #else 55 #define MGMT_CTXT_SET_RC_RSN(mc, rsn) 56 #define MGMT_CTXT_RC_RSN(mc) NULL 57 #endif 58 59 /** @typedef mgmt_handler_fn 60 * @brief Processes a request and writes the corresponding response. 61 * 62 * A separate handler is required for each supported op-ID pair. 63 * 64 * @param ctxt The mcumgr context to use. 65 * 66 * @return 0 if a response was successfully encoded, #mcumgr_err_t code on failure. 67 */ 68 typedef int (*mgmt_handler_fn)(struct smp_streamer *ctxt); 69 70 /** 71 * @brief Read handler and write handler for a single command ID. 72 * Set use_custom_payload to true when using a user defined payload type 73 */ 74 struct mgmt_handler { 75 mgmt_handler_fn mh_read; 76 mgmt_handler_fn mh_write; 77 #if defined(CONFIG_MCUMGR_MGMT_HANDLER_USER_DATA) 78 void *user_data; 79 #endif 80 }; 81 82 /** 83 * @brief A collection of handlers for an entire command group. 84 */ 85 struct mgmt_group { 86 /** Entry list node. */ 87 sys_snode_t node; 88 89 /** Array of handlers; one entry per command ID. */ 90 const struct mgmt_handler *mg_handlers; 91 uint16_t mg_handlers_count; 92 93 /** The numeric ID of this group. */ 94 uint16_t mg_group_id; 95 96 #if defined(CONFIG_MCUMGR_SMP_SUPPORT_ORIGINAL_PROTOCOL) 97 /** A function handler for translating version 2 SMP error codes to version 1 SMP error 98 * codes (optional) 99 */ 100 smp_translate_error_fn mg_translate_error; 101 #endif 102 103 #if defined(CONFIG_MCUMGR_MGMT_CUSTOM_PAYLOAD) 104 /** Should be true when using user defined payload */ 105 bool custom_payload; 106 #endif 107 108 #if IS_ENABLED(CONFIG_MCUMGR_GRP_ENUM_DETAILS_NAME) 109 /** NULL-terminated name of group */ 110 const char *mg_group_name; 111 #endif 112 }; 113 114 /** 115 * @brief Registers a full command group. 116 * 117 * @param group The group to register. 118 */ 119 void mgmt_register_group(struct mgmt_group *group); 120 121 /** 122 * @brief Unregisters a full command group. 123 * 124 * @param group The group to register. 125 */ 126 void mgmt_unregister_group(struct mgmt_group *group); 127 128 /** 129 * @brief Group iteration callback 130 * 131 * @param group Group 132 * @param user_data User-supplied data 133 * 134 * @return true to continue with the foreach callback, false to abort 135 */ 136 typedef bool (*mgmt_groups_cb_t)(const struct mgmt_group *group, void *user_data); 137 138 /** 139 * @brief Iterate over groups 140 * 141 * @param user_cb User callback 142 * @param user_data User-supplied data 143 */ 144 void mgmt_groups_foreach(mgmt_groups_cb_t user_cb, void *user_data); 145 146 /** 147 * @brief Finds a registered command handler. 148 * 149 * @param group_id The group of the command to find. 150 * @param command_id The ID of the command to find. 151 * 152 * @return The requested command handler on success; 153 * NULL on failure. 154 */ 155 const struct mgmt_handler *mgmt_find_handler(uint16_t group_id, uint16_t command_id); 156 157 /** 158 * @brief Finds a registered command group. 159 * 160 * @param group_id The group id of the command group to find. 161 * 162 * @return The requested group on success; 163 * NULL on failure. 164 */ 165 const struct mgmt_group *mgmt_find_group(uint16_t group_id); 166 167 /** 168 * @brief Finds a registered command handler. 169 * 170 * @param group The group of the command to find. 171 * @param command_id The ID of the command to find. 172 * 173 * @return The requested command handler on success; 174 * NULL on failure. 175 */ 176 const struct mgmt_handler *mgmt_get_handler(const struct mgmt_group *group, uint16_t command_id); 177 178 #if defined(CONFIG_MCUMGR_SMP_SUPPORT_ORIGINAL_PROTOCOL) 179 /** 180 * @brief Finds a registered error translation function for converting from SMP 181 * version 2 error codes to legacy SMP version 1 error codes. 182 * 183 * @param group_id The group of the translation function to find. 184 * 185 * @return Requested lookup function on success. 186 * @return NULL on failure. 187 */ 188 smp_translate_error_fn mgmt_find_error_translation_function(uint16_t group_id); 189 #endif 190 191 /** 192 * @} 193 */ 194 195 #ifdef __cplusplus 196 } 197 #endif 198 199 #endif /* MGMT_MGMT_H_ */ 200
