Skip to content

Commit 0b80c7e

Browse files
miri64miri64
committed
gnrc_netif2: Introduction of a new GNRC network interface API
1 parent 8d941d5 commit 0b80c7e

File tree

14 files changed

+2991
-0
lines changed

14 files changed

+2991
-0
lines changed

‎sys/include/net/gnrc/netif2.h‎

Lines changed: 322 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
/*
2+
* Copyright (C) 2017 Freie Universität Berlin
3+
*
4+
* This file is subject to the terms and conditions of the GNU Lesser
5+
* General Public License v2.1. See the file LICENSE in the top level
6+
* directory for more details.
7+
*/
8+
9+
/**
10+
* @defgroup net_gnrc_netif2 New network interface API
11+
* @ingroup net_gnrc
12+
* @brief Abstraction layer for GNRC's network interfaces
13+
*
14+
* Network interfaces in the context of GNRC are threads for protocols that are
15+
* below the network layer.
16+
*
17+
* @{
18+
*
19+
* @file
20+
* @brief Definition for GNRC's network interfaces
21+
*
22+
* @author Martine Lenders <[email protected]>
23+
*/
24+
#ifndef NET_GNRC_NETIF2_H
25+
#define NET_GNRC_NETIF2_H
26+
27+
#include <stddef.h>
28+
#include <stdint.h>
29+
#include <stdbool.h>
30+
31+
#include "kernel_types.h"
32+
#include "msg.h"
33+
#include "net/gnrc/netapi.h"
34+
#include "net/gnrc/pkt.h"
35+
#include "net/gnrc/netif2/conf.h"
36+
#ifdef MODULE_GNRC_SIXLOWPAN
37+
#include "net/gnrc/netif2/6lo.h"
38+
#endif
39+
#include "net/gnrc/netif2/flags.h"
40+
#ifdef MODULE_GNRC_IPV6
41+
#include "net/gnrc/netif2/ipv6.h"
42+
#endif
43+
#ifdef MODULE_GNRC_MAC
44+
#include "net/gnrc/netif2/mac.h"
45+
#endif
46+
#include "net/netdev.h"
47+
#include "rmutex.h"
48+
49+
#ifdef __cplusplus
50+
extern "C" {
51+
#endif
52+
53+
/**
54+
* @brief Operations to an interface
55+
*/
56+
typedef struct gnrc_netif2_ops gnrc_netif2_ops_t;
57+
58+
/**
59+
* @brief Representation of a network interface
60+
*/
61+
typedef struct {
62+
const gnrc_netif2_ops_t *ops; /**< Operations of the network interface */
63+
netdev_t *dev; /**< Network device of the network interface */
64+
rmutex_t mutex; /**< Mutex of the interface */
65+
#if defined(MODULE_GNRC_IPV6) || DOXYGEN
66+
gnrc_netif2_ipv6_t ipv6; /**< IPv6 component */
67+
#endif
68+
#if defined(MODULE_GNRC_MAC) || DOXYGEN
69+
gnrc_netif2_mac_t mac; /**< @ref net_gnrc_mac component */
70+
#endif /* MODULE_GNRC_MAC */
71+
/**
72+
* @brief Flags for the interface
73+
*
74+
* @see net_gnrc_netif2_flags
75+
*/
76+
uint32_t flags;
77+
#if (GNRC_NETIF2_L2ADDR_MAXLEN > 0)
78+
/**
79+
* @brief The link-layer address currently used as the source address
80+
* on this interface.
81+
*
82+
* @note Only available if @ref GNRC_NETIF2_L2ADDR_MAXLEN > 0
83+
*/
84+
uint8_t l2addr[GNRC_NETIF2_L2ADDR_MAXLEN];
85+
86+
/**
87+
* @brief Length in bytes of gnrc_netif2_t::l2addr
88+
*
89+
* @note Only available if @ref GNRC_NETIF2_L2ADDR_MAXLEN > 0
90+
*/
91+
uint8_t l2addr_len;
92+
#endif
93+
#if defined(MODULE_GNRC_SIXLOWPAN) || DOXYGEN
94+
gnrc_netif2_6lo_t sixlo; /**< 6Lo component */
95+
#endif
96+
uint8_t cur_hl; /**< Current hop-limit for out-going packets */
97+
uint8_t device_type; /**< Device type */
98+
kernel_pid_t pid; /**< PID of the network interface's thread */
99+
} gnrc_netif2_t;
100+
101+
/**
102+
* @see gnrc_netif2_ops_t
103+
*/
104+
struct gnrc_netif2_ops {
105+
/**
106+
* @brief Initializes network interface beyond the default settings
107+
*
108+
* @pre `netif != NULL`
109+
*
110+
* @param[in] netif The network interface.
111+
*
112+
* This is called after the default settings were set, right before the
113+
* interface's thread starts receiving messages. It is not necessary to lock
114+
* the interface's mutex gnrc_netif_t::mutex, since the thread will already
115+
* lock it. Leave NULL if you do not need any special initialization.
116+
*/
117+
void (*init)(gnrc_netif2_t *netif);
118+
119+
/**
120+
* @brief Send a @ref net_gnrc_pkt "packet" over the network interface
121+
*
122+
* @pre `netif != NULL && pkt != NULL`
123+
*
124+
* @note The function re-formats the content of @p pkt to a format expected
125+
* by the netdev_driver_t::send() method of gnrc_netif_t::dev and
126+
* releases the packet before returning (so no additional release
127+
* should be required after calling this method).
128+
*
129+
* @param[in] netif The network interface.
130+
* @param[in] pkt A packet to send.
131+
*
132+
* @return The number of bytes actually sent on success
133+
* @return -EBADMSG, if the @ref net_gnrc_netif_hdr in @p pkt is missing
134+
* or is in an unexpected format.
135+
* @return -ENOTSUP, if sending @p pkt in the given format isn't supported
136+
* (e.g. empty payload with Ethernet).
137+
* @return Any negative error code reported by gnrc_netif2_t::dev.
138+
*/
139+
int (*send)(gnrc_netif2_t *netif, gnrc_pktsnip_t *pkt);
140+
141+
/**
142+
* @brief Receives a @ref net_gnrc_pkt "packet" from the network interface
143+
*
144+
* @pre `netif != NULL`
145+
*
146+
* @note The function takes the bytes received via netdev_driver_t::recv()
147+
* from gnrc_netif_t::dev and re-formats it to a
148+
* @ref net_gnrc_pkt "packet" containing a @ref net_gnrc_netif_hdr
149+
* and a payload header in receive order.
150+
*
151+
* @param[in] netif The network interface.
152+
*
153+
* @return The packet received. Contains the payload (with the type marked
154+
* accordingly) and a @ref net_gnrc_netif_hdr in receive order.
155+
* @return NULL, if @ref net_gnrc_pktbuf was full.
156+
*/
157+
gnrc_pktsnip_t *(*recv)(gnrc_netif2_t *netif);
158+
159+
/**
160+
* @brief Gets an option from the network interface
161+
*
162+
* Use gnrc_netif2_get_from_netdev() to just get options from
163+
* gnrc_netif2_t::dev.
164+
*
165+
* @param[in] netif The network interface.
166+
* @param[in] opt The option parameters.
167+
*
168+
* @return Number of bytes in @p data.
169+
* @return -EOVERFLOW, if @p max_len is lesser than the required space.
170+
* @return -ENOTSUP, if @p opt is not supported to be set.
171+
* @return Any negative error code reported by gnrc_netif2_t::dev.
172+
*/
173+
int (*get)(gnrc_netif2_t *netif, gnrc_netapi_opt_t *opt);
174+
175+
/**
176+
* @brief Sets an option from the network interface
177+
*
178+
* Use gnrc_netif2_set_from_netdev() to just set options from
179+
* gnrc_netif2_t::dev.
180+
*
181+
* @param[in] netif The network interface.
182+
* @param[in] opt The option parameters.
183+
*
184+
* @return Number of bytes written to gnrc_netif2_t::dev.
185+
* @return -EOVERFLOW, if @p data_len is greater than the allotted space in
186+
* gnrc_netif2_t::dev or gnrc_netif_t.
187+
* @return -ENOTSUP, if @p opt is not supported to be set.
188+
* @return Any negative error code reported by gnrc_netif2_t::dev.
189+
*/
190+
int (*set)(gnrc_netif2_t *netif, const gnrc_netapi_opt_t *opt);
191+
192+
/**
193+
* @brief Message handler for network interface
194+
*
195+
* This message handler is used, when the network interface needs to handle
196+
* message types beyond the ones defined in @ref net_gnrc_netapi "netapi".
197+
* Leave NULL if this is not the case.
198+
*
199+
* @param[in] netif The network interface.
200+
* @param[in] msg Message to be handled.
201+
*/
202+
void (*msg_handler)(gnrc_netif2_t *netif, msg_t *msg);
203+
};
204+
205+
/**
206+
* @brief Creates a network interface
207+
*
208+
* @param[in] stack The stack for the network interface's thread.
209+
* @param[in] stacksize Size of @p stack.
210+
* @param[in] priority Priority for the network interface's thread.
211+
* @param[in] name Name for the network interface. May be NULL.
212+
* @param[in] dev Device for the interface.
213+
* @param[in] ops Operations for the network interface.
214+
*
215+
* @note If @ref DEVELHELP is defined netif_params_t::name is used as the
216+
* name of the network interface's thread.
217+
*
218+
* @return The network interface on success.
219+
* @return NULL, on error.
220+
*/
221+
gnrc_netif2_t *gnrc_netif2_create(char *stack, int stacksize, char priority,
222+
const char *name, netdev_t *dev,
223+
const gnrc_netif2_ops_t *ops);
224+
225+
/**
226+
* @brief Get number of network interfaces actually allocated
227+
*
228+
* @return Number of network interfaces actually allocated
229+
*/
230+
unsigned gnrc_netif2_numof(void);
231+
232+
/**
233+
* @brief Iterate over all network interfaces.
234+
*
235+
* @param[in] prev previous interface in iteration. NULL to start iteration.
236+
*
237+
* @return The next network interface after @p prev.
238+
* @return NULL, if @p prev was the last network interface.
239+
*/
240+
gnrc_netif2_t *gnrc_netif2_iter(const gnrc_netif2_t *prev);
241+
242+
/**
243+
* @brief Get network interface by PID
244+
*
245+
* @param[in] pid A PID of a network interface.
246+
*
247+
* @return The network interface on success.
248+
* @return NULL, if no network interface with PID exists.
249+
*/
250+
gnrc_netif2_t *gnrc_netif2_get_by_pid(kernel_pid_t pid);
251+
252+
/**
253+
* @brief Default operation for gnrc_netif2_ops_t::get()
254+
*
255+
* @note Can also be used to be called *after* a custom operation.
256+
*
257+
* @param[in] netif The network interface.
258+
* @param[out] opt The option parameters.
259+
*
260+
* @return Return value of netdev_driver_t::get() of gnrc_netif2_t::dev of
261+
* @p netif.
262+
*/
263+
int gnrc_netif2_get_from_netdev(gnrc_netif2_t *netif, gnrc_netapi_opt_t *opt);
264+
265+
/**
266+
* @brief Default operation for gnrc_netif2_ops_t::set()
267+
*
268+
* @note Can also be used to be called *after* a custom operation.
269+
*
270+
* @param[in] netif The network interface.
271+
* @param[in] opt The option parameters.
272+
*
273+
* @return Return value of netdev_driver_t::set() of gnrc_netif2_t::dev of
274+
* @p netif.
275+
*/
276+
int gnrc_netif2_set_from_netdev(gnrc_netif2_t *netif,
277+
const gnrc_netapi_opt_t *opt);
278+
279+
/**
280+
* @brief Converts a hardware address to a human readable string.
281+
*
282+
* @details The format will be like `xx:xx:xx:xx` where `xx` are the bytes
283+
* of @p addr in hexadecimal representation.
284+
*
285+
* @pre `(out != NULL) && ((addr != NULL) || (addr_len == 0))`
286+
* @pre @p out **MUST** have allocated at least 3 * @p addr_len bytes.
287+
*
288+
* @param[in] addr A hardware address.
289+
* @param[in] addr_len Length of @p addr.
290+
* @param[out] out A string to store the output in. Must at least have
291+
* 3 * @p addr_len bytes allocated.
292+
*
293+
* @return @p out.
294+
*/
295+
char *gnrc_netif2_addr_to_str(const uint8_t *addr, size_t addr_len, char *out);
296+
297+
/**
298+
* @brief Parses a string of colon-separated hexadecimals to a hardware
299+
* address.
300+
*
301+
* @details The input format must be like `xx:xx:xx:xx` where `xx` will be the
302+
* bytes of @p addr in hexadecimal representation.
303+
*
304+
* @pre `(out != NULL)`
305+
* @pre @p out **MUST** have allocated at least
306+
* @ref GNRC_NETIF2_L2ADDR_MAXLEN bytes.
307+
*
308+
* @param[in] str A string of colon-separated hexadecimals.
309+
* @param[out] out The resulting hardware address. Must at least have
310+
* @ref GNRC_NETIF2_L2ADDR_MAXLEN bytes allocated.
311+
*
312+
* @return Actual length of @p out on success.
313+
* @return 0, on failure.
314+
*/
315+
size_t gnrc_netif2_addr_from_str(const char *str, uint8_t *out);
316+
317+
#ifdef __cplusplus
318+
}
319+
#endif
320+
321+
#endif /* NET_GNRC_NETIF2_H */
322+
/** @} */

‎sys/include/net/gnrc/netif2/6lo.h‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
/*
2+
* Copyright (C) 2017 Freie Universität Berlin
3+
*
4+
* This file is subject to the terms and conditions of the GNU Lesser
5+
* General Public License v2.1. See the file LICENSE in the top level
6+
* directory for more details.
7+
*/
8+
9+
/**
10+
* @ingroup net_gnrc_netif2
11+
* @{
12+
*
13+
* @file
14+
* @brief 6LoWPAN definitions for @ref net_gnrc_netif2
15+
*
16+
* @author Martine Lenders <[email protected]>
17+
*/
18+
#ifndef NET_GNRC_NETIF2_6LO_H
19+
#define NET_GNRC_NETIF2_6LO_H
20+
21+
#include <stdint.h>
22+
23+
#ifdef __cplusplus
24+
extern "C" {
25+
#endif
26+
27+
/**
28+
* @brief 6Lo component of @ref gnrc_netif2_t
29+
*/
30+
typedef struct {
31+
/**
32+
* @brief Maximum fragment size for 6Lo fragmentation.
33+
*
34+
* @note Only available with module
35+
* @ref net_gnrc_sixlowpan_frag "gnrc_sixlowpan_frag".
36+
*/
37+
uint8_t max_frag_size;
38+
} gnrc_netif2_6lo_t;
39+
40+
#ifdef __cplusplus
41+
}
42+
#endif
43+
44+
#endif /* NET_GNRC_NETIF2_6LO_H */
45+
/** @} */

0 commit comments

Comments
 (0)