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 SMP transport API
19 : * @defgroup mcumgr_transport_smp SMP transport
20 : * @ingroup mcumgr_transport
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 Bluetooth 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 Bluetooth 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 Bluetooth
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
|
