Line data Source code
1 0 : /* 2 : * Copyright Runtime.io 2018. All rights reserved. 3 : * Copyright (c) 2022-2023 Nordic Semiconductor ASA 4 : * 5 : * SPDX-License-Identifier: Apache-2.0 6 : */ 7 : 8 : #ifndef ZEPHYR_INCLUDE_MGMT_SMP_H_ 9 : #define ZEPHYR_INCLUDE_MGMT_SMP_H_ 10 : 11 : #include <zephyr/kernel.h> 12 : 13 : #ifdef __cplusplus 14 : extern "C" { 15 : #endif 16 : 17 : /** 18 : * @brief MCUmgr transport SMP API 19 : * @defgroup mcumgr_transport_smp MCUmgr transport SMP API 20 : * @ingroup mcumgr 21 : * @{ 22 : */ 23 : 24 : struct smp_transport; 25 : struct zephyr_smp_transport; 26 : struct net_buf; 27 : 28 : /** @typedef smp_transport_out_fn 29 : * @brief SMP transmit callback for transport 30 : * 31 : * The supplied net_buf is always consumed, regardless of return code. 32 : * 33 : * @param nb The net_buf to transmit. 34 : * 35 : * @return 0 on success, #mcumgr_err_t code on failure. 36 : */ 37 1 : typedef int (*smp_transport_out_fn)(struct net_buf *nb); 38 : 39 : /** @typedef smp_transport_get_mtu_fn 40 : * @brief SMP MTU query callback for transport 41 : * 42 : * The supplied net_buf should contain a request received from the peer whose 43 : * MTU is being queried. This function takes a net_buf parameter because some 44 : * transports store connection-specific information in the net_buf user header 45 : * (e.g., the BLE transport stores the peer address). 46 : * 47 : * @param nb Contains a request from the relevant peer. 48 : * 49 : * @return The transport's MTU; 50 : * 0 if transmission is currently not possible. 51 : */ 52 1 : typedef uint16_t (*smp_transport_get_mtu_fn)(const struct net_buf *nb); 53 : 54 : /** @typedef smp_transport_ud_copy_fn 55 : * @brief SMP copy user_data callback 56 : * 57 : * The supplied src net_buf should contain a user_data that cannot be copied 58 : * using regular memcpy function (e.g., the BLE transport net_buf user_data 59 : * stores the connection reference that has to be incremented when is going 60 : * to be used by another buffer). 61 : * 62 : * @param dst Source buffer user_data pointer. 63 : * @param src Destination buffer user_data pointer. 64 : * 65 : * @return 0 on success, #mcumgr_err_t code on failure. 66 : */ 67 1 : typedef int (*smp_transport_ud_copy_fn)(struct net_buf *dst, 68 : const struct net_buf *src); 69 : 70 : /** @typedef smp_transport_ud_free_fn 71 : * @brief SMP free user_data callback 72 : * 73 : * This function frees net_buf user data, because some transports store 74 : * connection-specific information in the net_buf user data (e.g., the BLE 75 : * transport stores the connection reference that has to be decreased). 76 : * 77 : * @param ud Contains a user_data pointer to be freed. 78 : */ 79 1 : typedef void (*smp_transport_ud_free_fn)(void *ud); 80 : 81 : /** @typedef smp_transport_query_valid_check_fn 82 : * @brief Function for checking if queued data is still valid. 83 : * 84 : * This function is used to check if queued SMP data is still valid e.g. on a remote device 85 : * disconnecting, this is triggered when smp_rx_remove_invalid() is called. 86 : * 87 : * @param nb net buf containing queued request. 88 : * @param arg Argument provided when calling smp_rx_remove_invalid() function. 89 : * 90 : * @return false if data is no longer valid/should be freed, true otherwise. 91 : */ 92 1 : typedef bool (*smp_transport_query_valid_check_fn)(struct net_buf *nb, void *arg); 93 : 94 : /** 95 : * @brief Function pointers of SMP transport functions, if a handler is NULL then it is not 96 : * supported/implemented. 97 : */ 98 1 : struct smp_transport_api_t { 99 : /** Transport's send function. */ 100 1 : smp_transport_out_fn output; 101 : 102 : /** Transport's get-MTU function. */ 103 1 : smp_transport_get_mtu_fn get_mtu; 104 : 105 : /** Transport buffer user_data copy function. */ 106 1 : smp_transport_ud_copy_fn ud_copy; 107 : 108 : /** Transport buffer user_data free function. */ 109 1 : smp_transport_ud_free_fn ud_free; 110 : 111 : /** Transport's check function for if a query is valid. */ 112 1 : smp_transport_query_valid_check_fn query_valid_check; 113 : }; 114 : 115 : /** 116 : * @brief SMP transport object for sending SMP responses. 117 : */ 118 1 : struct smp_transport { 119 : /* Must be the first member. */ 120 0 : struct k_work work; 121 : 122 : /* FIFO containing incoming requests to be processed. */ 123 0 : struct k_fifo fifo; 124 : 125 : /* Function pointers */ 126 0 : struct smp_transport_api_t functions; 127 : 128 : #ifdef CONFIG_MCUMGR_TRANSPORT_REASSEMBLY 129 : /* Packet reassembly internal data, API access only */ 130 : struct { 131 : struct net_buf *current; /* net_buf used for reassembly */ 132 : uint16_t expected; /* expected bytes to come */ 133 : } __reassembly; 134 : #endif 135 : }; 136 : 137 : /** 138 : * @brief SMP transport type for client registration 139 : */ 140 1 : enum smp_transport_type { 141 : /** SMP serial */ 142 : SMP_SERIAL_TRANSPORT = 0, 143 : /** SMP bluetooth */ 144 : SMP_BLUETOOTH_TRANSPORT, 145 : /** SMP shell*/ 146 : SMP_SHELL_TRANSPORT, 147 : /** SMP UDP IPv4 */ 148 : SMP_UDP_IPV4_TRANSPORT, 149 : /** SMP UDP IPv6 */ 150 : SMP_UDP_IPV6_TRANSPORT, 151 : /** SMP LoRaWAN */ 152 : SMP_LORAWAN_TRANSPORT, 153 : /** SMP user defined type */ 154 : SMP_USER_DEFINED_TRANSPORT 155 : }; 156 : 157 : /** 158 : * @brief SMP Client transport structure 159 : */ 160 1 : struct smp_client_transport_entry { 161 0 : sys_snode_t node; 162 : /** Transport structure pointer */ 163 1 : struct smp_transport *smpt; 164 : /** Transport type */ 165 1 : int smpt_type; 166 : }; 167 : 168 : /** 169 : * @brief Initializes a Zephyr SMP transport object. 170 : * 171 : * @param smpt The transport to construct. 172 : * 173 : * @return 0 If successful 174 : * @return Negative errno code if failure. 175 : */ 176 1 : int smp_transport_init(struct smp_transport *smpt); 177 : 178 : /** 179 : * @brief Used to remove queued requests for an SMP transport that are no longer valid. A 180 : * smp_transport_query_valid_check_fn() function must be registered for this to 181 : * function. If the smp_transport_query_valid_check_fn() function returns false 182 : * during a callback, the queried command will classed as invalid and dropped. 183 : * 184 : * @param zst The transport to use. 185 : * @param arg Argument provided to callback smp_transport_query_valid_check_fn() function. 186 : */ 187 1 : void smp_rx_remove_invalid(struct smp_transport *zst, void *arg); 188 : 189 : /** 190 : * @brief Used to clear pending queued requests for an SMP transport. 191 : * 192 : * @param zst The transport to use. 193 : */ 194 1 : void smp_rx_clear(struct smp_transport *zst); 195 : 196 : /** 197 : * @brief Register a Zephyr SMP transport object for client. 198 : * 199 : * @param entry The transport to construct. 200 : */ 201 1 : void smp_client_transport_register(struct smp_client_transport_entry *entry); 202 : 203 : /** 204 : * @brief Discover a registered SMP transport client object. 205 : * 206 : * @param smpt_type Type of transport 207 : * 208 : * @return Pointer to registered object. Unknown type return NULL. 209 : */ 210 1 : struct smp_transport *smp_client_transport_get(int smpt_type); 211 : 212 : /** 213 : * @} 214 : */ 215 : 216 : #ifdef __cplusplus 217 : } 218 : #endif 219 : 220 : #endif
