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