Line data Source code
1 1 : /*
2 : * Copyright (c) 2016 Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Network Management API public header
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_NET_NET_MGMT_H_
13 : #define ZEPHYR_INCLUDE_NET_NET_MGMT_H_
14 :
15 : #include <zephyr/sys/__assert.h>
16 : #include <zephyr/net/net_core.h>
17 : #include <zephyr/sys/iterable_sections.h>
18 :
19 : #ifdef __cplusplus
20 : extern "C" {
21 : #endif
22 :
23 : /**
24 : * @brief Network Management
25 : * @defgroup net_mgmt Network Management
26 : * @since 1.7
27 : * @version 2.0.0
28 : * @ingroup networking
29 : * @{
30 : */
31 :
32 : struct net_if;
33 :
34 : /** @cond INTERNAL_HIDDEN */
35 : /**
36 : * @brief NET MGMT event mask basics, normalizing parts of bit fields
37 : */
38 : #define NET_MGMT_EVENT_MASK GENMASK64(63, 63) /* 0x8000000000000000 */
39 : #define NET_MGMT_ON_IFACE_MASK GENMASK64(62, 62) /* 0x4000000000000000 */
40 : #define NET_MGMT_LAYER_MASK GENMASK64(61, 60) /* 0x3000000000000000 */
41 : #define NET_MGMT_SYNC_EVENT_MASK GENMASK64(59, 59) /* 0x0800000000000000 */
42 : #define NET_MGMT_LAYER_CODE_MASK GENMASK64(58, 52) /* 0x07F0000000000000 */
43 : #define NET_MGMT_COMMAND_MASK GENMASK64(51, 0) /* 0x000FFFFFFFFFFFFF */
44 :
45 : #define NET_MGMT_MAX_COMMANDS 52 /* TODO: figure out the value from mask */
46 :
47 : #define NET_MGMT_EVENT_BIT BIT64(63)
48 : #define NET_MGMT_IFACE_BIT BIT64(62)
49 : #define NET_MGMT_SYNC_EVENT_BIT BIT64(59)
50 :
51 : #define NET_MGMT_LAYER(_layer) FIELD_PREP(NET_MGMT_LAYER_MASK, (_layer))
52 : #define NET_MGMT_LAYER_CODE(_code) FIELD_PREP(NET_MGMT_LAYER_CODE_MASK, (_code))
53 :
54 : #define NET_MGMT_EVENT(mgmt_request) FIELD_GET(NET_MGMT_EVENT_MASK, mgmt_request)
55 : #define NET_MGMT_ON_IFACE(mgmt_request) FIELD_GET(NET_MGMT_ON_IFACE_MASK, mgmt_request)
56 : #define NET_MGMT_EVENT_SYNCHRONOUS(mgmt_request) FIELD_GET(NET_MGMT_SYNC_EVENT_MASK, mgmt_request)
57 : #define NET_MGMT_GET_LAYER(mgmt_request) FIELD_GET(NET_MGMT_LAYER_MASK, mgmt_request)
58 : #define NET_MGMT_GET_LAYER_CODE(mgmt_request) FIELD_GET(NET_MGMT_LAYER_CODE_MASK, mgmt_request)
59 : #define NET_MGMT_GET_COMMAND(mgmt_request) FIELD_GET(NET_MGMT_COMMAND_MASK, mgmt_request)
60 :
61 : #define NET_MGMT_CMD(cmd) cmd = BIT64(cmd ##_VAL)
62 :
63 : /* Useful generic definitions */
64 : #define NET_MGMT_LAYER_L2 1
65 : #define NET_MGMT_LAYER_L3 2
66 : #define NET_MGMT_LAYER_L4 3
67 :
68 : /** @endcond */
69 :
70 : /** @brief Central place the definition of the layer codes (7 bit value) */
71 1 : enum net_mgmt_layer_code {
72 : NET_MGMT_LAYER_CODE_UNKNOWN = 0x00, /**< Unknown layer code, do not use */
73 : NET_MGMT_LAYER_CODE_IFACE = 0x01, /**< Network interface layer code */
74 : NET_MGMT_LAYER_CODE_CONN = 0x02, /**< Connectivity layer code */
75 : NET_MGMT_LAYER_CODE_IPV4 = 0x03, /**< IPv4 layer code */
76 : NET_MGMT_LAYER_CODE_IPV6 = 0x04, /**< IPv6 layer code */
77 : NET_MGMT_LAYER_CODE_L4 = 0x05, /**< L4 layer code */
78 : NET_MGMT_LAYER_CODE_COAP = 0x06, /**< CoAP layer code */
79 : NET_MGMT_LAYER_CODE_STATS = 0x07, /**< Statistics layer code */
80 : NET_MGMT_LAYER_CODE_HOSTAP = 0x08, /**< Hostap (wpa_supplicant) layer code */
81 : NET_MGMT_LAYER_CODE_ETHERNET = 0x09, /**< Ethernet layer code */
82 : NET_MGMT_LAYER_CODE_IEEE802514 = 0x0A, /**< IEEE 802.15.4 layer code */
83 : NET_MGMT_LAYER_CODE_PPP = 0x0B, /**< PPP layer code */
84 : NET_MGMT_LAYER_CODE_VIRTUAL = 0x0C, /**< Virtual network interface layer code */
85 : NET_MGMT_LAYER_CODE_WIFI = 0x0D, /**< Wi-Fi layer code */
86 :
87 : /* Out of tree code can use the following userX layer codes */
88 : NET_MGMT_LAYER_CODE_USER3 = 0x7C, /**< User layer code 3 */
89 : NET_MGMT_LAYER_CODE_USER2 = 0x7D, /**< User layer code 2 */
90 : NET_MGMT_LAYER_CODE_USER1 = 0x7E, /**< User layer code 1 */
91 :
92 : /* Reserved layer code for future use */
93 : NET_MGMT_LAYER_CODE_RESERVED = 0x7F /**< Reserved layer code for future use */
94 : };
95 :
96 : #include <zephyr/net/net_event.h>
97 :
98 : /**
99 : * @typedef net_mgmt_request_handler_t
100 : * @brief Signature which all Net MGMT request handler need to follow
101 : * @param mgmt_request The exact request value the handler is being called
102 : * through
103 : * @param iface A valid pointer on struct net_if if the request is meant
104 : * to be tied to a network interface. NULL otherwise.
105 : * @param data A valid pointer on a data understood by the handler.
106 : * NULL otherwise.
107 : * @param len Length in byte of the memory pointed by data.
108 : */
109 1 : typedef int (*net_mgmt_request_handler_t)(uint64_t mgmt_request,
110 : struct net_if *iface,
111 : void *data, size_t len);
112 :
113 : /**
114 : * @brief Generate a network management event.
115 : *
116 : * @param _mgmt_request Management event identifier
117 : * @param _iface Network interface
118 : * @param _data Any additional data for the event
119 : * @param _len Length of the additional data.
120 : */
121 1 : #define net_mgmt(_mgmt_request, _iface, _data, _len) \
122 : net_mgmt_##_mgmt_request(_mgmt_request, _iface, _data, _len)
123 :
124 : /**
125 : * @brief Declare a request handler function for the given network event.
126 : *
127 : * @param _mgmt_request Management event identifier
128 : */
129 1 : #define NET_MGMT_DEFINE_REQUEST_HANDLER(_mgmt_request) \
130 : extern int net_mgmt_##_mgmt_request(uint64_t mgmt_request, \
131 : struct net_if *iface, \
132 : void *data, size_t len)
133 :
134 : /**
135 : * @brief Create a request handler function for the given network event.
136 : *
137 : * @param _mgmt_request Management event identifier
138 : * @param _func Function for handling this event
139 : */
140 1 : #define NET_MGMT_REGISTER_REQUEST_HANDLER(_mgmt_request, _func) \
141 : FUNC_ALIAS(_func, net_mgmt_##_mgmt_request, int)
142 :
143 : struct net_mgmt_event_callback;
144 :
145 : /**
146 : * @typedef net_mgmt_event_handler_t
147 : * @brief Define the user's callback handler function signature
148 : * @param cb Original struct net_mgmt_event_callback owning this handler.
149 : * @param mgmt_event The network event being notified.
150 : * @param iface A pointer on a struct net_if to which the event belongs to,
151 : * if it's an event on an iface. NULL otherwise.
152 : */
153 1 : typedef void (*net_mgmt_event_handler_t)(struct net_mgmt_event_callback *cb,
154 : uint64_t mgmt_event,
155 : struct net_if *iface);
156 :
157 : /**
158 : * @brief Network Management event callback structure
159 : * Used to register a callback into the network management event part, in order
160 : * to let the owner of this struct to get network event notification based on
161 : * given event mask.
162 : */
163 1 : struct net_mgmt_event_callback {
164 : /** Meant to be used internally, to insert the callback into a list.
165 : * So nobody should mess with it.
166 : */
167 1 : sys_snode_t node;
168 :
169 : union {
170 : /** Actual callback function being used to notify the owner
171 : */
172 1 : net_mgmt_event_handler_t handler;
173 : /** Semaphore meant to be used internally for the synchronous
174 : * net_mgmt_event_wait() function.
175 : */
176 1 : struct k_sem *sync_call;
177 0 : };
178 :
179 : #ifdef CONFIG_NET_MGMT_EVENT_INFO
180 : const void *info;
181 : size_t info_length;
182 : #endif
183 :
184 : /** A mask of network events on which the above handler should be
185 : * called in case those events come. Such mask can be modified
186 : * whenever necessary by the owner, and thus will affect the handler
187 : * being called or not.
188 : */
189 : union {
190 : /** A mask of network events on which the above handler should
191 : * be called in case those events come.
192 : * Note that only the command part is treated as a mask,
193 : * matching one to several commands. Layer and layer code will
194 : * be made of an exact match. This means that in order to
195 : * receive events from multiple layers, one must have multiple
196 : * listeners registered, one for each layer being listened.
197 : */
198 1 : uint64_t event_mask;
199 : /** Internal place holder when a synchronous event wait is
200 : * successfully unlocked on a event.
201 : */
202 1 : uint64_t raised_event;
203 1 : };
204 : };
205 :
206 : /**
207 : * @typedef net_mgmt_event_static_handler_t
208 : * @brief Define the user's callback handler function signature
209 : * @param mgmt_event The network event being notified.
210 : * @param iface A pointer on a struct net_if to which the event belongs to,
211 : * if it's an event on an iface. NULL otherwise.
212 : * @param info A valid pointer on a data understood by the handler.
213 : * NULL otherwise.
214 : * @param info_length Length in bytes of the memory pointed by @p info.
215 : * @param user_data Data provided by the user to the handler.
216 : */
217 1 : typedef void (*net_mgmt_event_static_handler_t)(uint64_t mgmt_event,
218 : struct net_if *iface,
219 : void *info, size_t info_length,
220 : void *user_data);
221 :
222 : /** @cond INTERNAL_HIDDEN */
223 :
224 : /* Structure for event handler registered at compile time */
225 : struct net_mgmt_event_static_handler {
226 : uint64_t event_mask;
227 : net_mgmt_event_static_handler_t handler;
228 : void *user_data;
229 : };
230 :
231 : /** @endcond */
232 :
233 : /**
234 : * @brief Define a static network event handler.
235 : * @param _name Name of the event handler.
236 : * @param _event_mask A mask of network events on which the passed handler should
237 : * be called in case those events come.
238 : * Note that only the command part is treated as a mask,
239 : * matching one to several commands. Layer and layer code will
240 : * be made of an exact match. This means that in order to
241 : * receive events from multiple layers, one must have multiple
242 : * listeners registered, one for each layer being listened.
243 : * @param _func The function to be called upon network events being emitted.
244 : * @param _user_data User data passed to the handler being called on network events.
245 : */
246 1 : #define NET_MGMT_REGISTER_EVENT_HANDLER(_name, _event_mask, _func, _user_data) \
247 : const STRUCT_SECTION_ITERABLE(net_mgmt_event_static_handler, _name) = { \
248 : .event_mask = _event_mask, \
249 : .handler = _func, \
250 : .user_data = (void *)_user_data, \
251 : }
252 :
253 : /**
254 : * @brief Helper to initialize a struct net_mgmt_event_callback properly
255 : * @param cb A valid application's callback structure pointer.
256 : * @param handler A valid handler function pointer.
257 : * @param mgmt_event_mask A mask of relevant events for the handler
258 : */
259 : #ifdef CONFIG_NET_MGMT_EVENT
260 : static inline
261 1 : void net_mgmt_init_event_callback(struct net_mgmt_event_callback *cb,
262 : net_mgmt_event_handler_t handler,
263 : uint64_t mgmt_event_mask)
264 : {
265 : __ASSERT(cb, "Callback pointer should not be NULL");
266 : __ASSERT(handler, "Handler pointer should not be NULL");
267 :
268 : cb->handler = handler;
269 : cb->event_mask = mgmt_event_mask;
270 : };
271 : #else
272 : #define net_mgmt_init_event_callback(...)
273 : #endif
274 :
275 : /**
276 : * @brief Add a user callback
277 : * @param cb A valid pointer on user's callback to add.
278 : */
279 : #ifdef CONFIG_NET_MGMT_EVENT
280 1 : void net_mgmt_add_event_callback(struct net_mgmt_event_callback *cb);
281 : #else
282 : #define net_mgmt_add_event_callback(...)
283 : #endif
284 :
285 : /**
286 : * @brief Delete a user callback
287 : * @param cb A valid pointer on user's callback to delete.
288 : */
289 : #ifdef CONFIG_NET_MGMT_EVENT
290 1 : void net_mgmt_del_event_callback(struct net_mgmt_event_callback *cb);
291 : #else
292 : #define net_mgmt_del_event_callback(...)
293 : #endif
294 :
295 : /**
296 : * @brief Used by the system to notify an event.
297 : * @param mgmt_event The actual network event code to notify
298 : * @param iface a valid pointer on a struct net_if if only the event is
299 : * based on an iface. NULL otherwise.
300 : * @param info A valid pointer on the information you want to pass along
301 : * with the event. NULL otherwise. Note the data pointed there is
302 : * normalized by the related event.
303 : * @param length size of the data pointed by info pointer.
304 : *
305 : * Note: info and length are disabled if CONFIG_NET_MGMT_EVENT_INFO
306 : * is not defined.
307 : */
308 : #if defined(CONFIG_NET_MGMT_EVENT)
309 1 : void net_mgmt_event_notify_with_info(uint64_t mgmt_event, struct net_if *iface,
310 : const void *info, size_t length);
311 : #else
312 : #define net_mgmt_event_notify_with_info(...)
313 : #endif
314 :
315 : /**
316 : * @brief Used by the system to notify an event without any additional information.
317 : * @param mgmt_event The actual network event code to notify
318 : * @param iface A valid pointer on a struct net_if if only the event is
319 : * based on an iface. NULL otherwise.
320 : */
321 : #if defined(CONFIG_NET_MGMT_EVENT)
322 1 : static inline void net_mgmt_event_notify(uint64_t mgmt_event,
323 : struct net_if *iface)
324 : {
325 : net_mgmt_event_notify_with_info(mgmt_event, iface, NULL, 0);
326 : }
327 : #else
328 : #define net_mgmt_event_notify(...)
329 : #endif
330 :
331 : /**
332 : * @brief Used to wait synchronously on an event mask
333 : * @param mgmt_event_mask A mask of relevant events to wait on.
334 : * @param raised_event a pointer on a uint32_t to get which event from
335 : * the mask generated the event. Can be NULL if the caller is not
336 : * interested in that information.
337 : * @param iface a pointer on a place holder for the iface on which the
338 : * event has originated from. This is valid if only the event mask
339 : * has bit NET_MGMT_IFACE_BIT set relevantly, depending on events
340 : * the caller wants to listen to.
341 : * @param info a valid pointer if user wants to get the information the
342 : * event might bring along. NULL otherwise.
343 : * @param info_length tells how long the info memory area is. Only valid if
344 : * the info is not NULL.
345 : * @param timeout A timeout delay. K_FOREVER can be used to wait indefinitely.
346 : *
347 : * @return 0 on success, a negative error code otherwise. -ETIMEDOUT will
348 : * be specifically returned if the timeout kick-in instead of an
349 : * actual event.
350 : */
351 : #ifdef CONFIG_NET_MGMT_EVENT
352 1 : int net_mgmt_event_wait(uint64_t mgmt_event_mask,
353 : uint64_t *raised_event,
354 : struct net_if **iface,
355 : const void **info,
356 : size_t *info_length,
357 : k_timeout_t timeout);
358 : #else
359 : static inline int net_mgmt_event_wait(uint64_t mgmt_event_mask,
360 : uint64_t *raised_event,
361 : struct net_if **iface,
362 : const void **info,
363 : size_t *info_length,
364 : k_timeout_t timeout)
365 : {
366 : ARG_UNUSED(mgmt_event_mask);
367 : ARG_UNUSED(raised_event);
368 : ARG_UNUSED(iface);
369 : ARG_UNUSED(info);
370 : ARG_UNUSED(info_length);
371 : ARG_UNUSED(timeout);
372 : return 0;
373 : }
374 : #endif
375 :
376 : /**
377 : * @brief Used to wait synchronously on an event mask for a specific iface
378 : * @param iface a pointer on a valid network interface to listen event to
379 : * @param mgmt_event_mask A mask of relevant events to wait on. Listened
380 : * to events should be relevant to iface events and thus have the bit
381 : * NET_MGMT_IFACE_BIT set.
382 : * @param raised_event a pointer on a uint32_t to get which event from
383 : * the mask generated the event. Can be NULL if the caller is not
384 : * interested in that information.
385 : * @param info a valid pointer if user wants to get the information the
386 : * event might bring along. NULL otherwise.
387 : * @param info_length tells how long the info memory area is. Only valid if
388 : * the info is not NULL.
389 : * @param timeout A timeout delay. K_FOREVER can be used to wait indefinitely.
390 : *
391 : * @return 0 on success, a negative error code otherwise. -ETIMEDOUT will
392 : * be specifically returned if the timeout kick-in instead of an
393 : * actual event.
394 : */
395 : #ifdef CONFIG_NET_MGMT_EVENT
396 1 : int net_mgmt_event_wait_on_iface(struct net_if *iface,
397 : uint64_t mgmt_event_mask,
398 : uint64_t *raised_event,
399 : const void **info,
400 : size_t *info_length,
401 : k_timeout_t timeout);
402 : #else
403 : static inline int net_mgmt_event_wait_on_iface(struct net_if *iface,
404 : uint64_t mgmt_event_mask,
405 : uint64_t *raised_event,
406 : const void **info,
407 : size_t *info_length,
408 : k_timeout_t timeout)
409 : {
410 : ARG_UNUSED(iface);
411 : ARG_UNUSED(mgmt_event_mask);
412 : ARG_UNUSED(raised_event);
413 : ARG_UNUSED(info);
414 : ARG_UNUSED(info_length);
415 : ARG_UNUSED(timeout);
416 : return 0;
417 : }
418 : #endif
419 :
420 : /**
421 : * @brief Used by the core of the network stack to initialize the network
422 : * event processing.
423 : */
424 : #ifdef CONFIG_NET_MGMT_EVENT
425 1 : void net_mgmt_event_init(void);
426 : #else
427 : #define net_mgmt_event_init(...)
428 : #endif /* CONFIG_NET_MGMT_EVENT */
429 :
430 : /**
431 : * @}
432 : */
433 :
434 : #ifdef __cplusplus
435 : }
436 : #endif
437 :
438 : #endif /* ZEPHYR_INCLUDE_NET_NET_MGMT_H_ */
|
