netif.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2017-20 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 
29 #ifndef NET_GNRC_NETIF_H
30 #define NET_GNRC_NETIF_H
31 
32 #include <stddef.h>
33 #include <stdint.h>
34 #include <stdbool.h>
35 
36 #include "sched.h"
37 #include "msg.h"
38 #ifdef MODULE_GNRC_NETIF_BUS
39 #include "msg_bus.h"
40 #endif
41 #include "event.h"
42 #include "net/ipv6/addr.h"
43 #include "net/gnrc/netapi.h"
44 #include "net/gnrc/pkt.h"
45 #include "net/gnrc/netif/conf.h"
46 #if IS_USED(MODULE_GNRC_NETIF_LORAWAN)
47 #include "net/gnrc/netif/lorawan.h"
48 #endif
49 #if IS_USED(MODULE_GNRC_NETIF_6LO)
50 #include "net/gnrc/netif/6lo.h"
51 #endif
52 #if defined(MODULE_GNRC_NETIF_DEDUP) && (GNRC_NETIF_L2ADDR_MAXLEN > 0)
53 #include "net/gnrc/netif/dedup.h"
54 #endif
55 #include "net/gnrc/netif/flags.h"
56 #if IS_USED(MODULE_GNRC_NETIF_IPV6)
57 #include "net/gnrc/netif/ipv6.h"
58 #endif
59 #if IS_USED(MODULE_GNRC_NETIF_MAC)
60 #include "net/gnrc/netif/mac.h"
61 #endif
62 #if IS_USED(MODULE_GNRC_NETIF_PKTQ)
64 #endif
65 #include "net/l2util.h"
66 #include "net/ndp.h"
67 #include "net/netdev.h"
68 #include "net/netopt.h"
69 #ifdef MODULE_NETSTATS_L2
70 #include "net/netstats.h"
71 #endif
72 #include "rmutex.h"
73 #include "net/netif.h"
74 
75 #ifdef __cplusplus
76 extern "C" {
77 #endif
78 
82 #define GNRC_NETIF_EVQ_INDEX_PRIO_HIGH (0)
83 
87 #if IS_USED(MODULE_BHP_EVENT)
88 #define GNRC_NETIF_EVQ_INDEX_PRIO_LOW (GNRC_NETIF_EVQ_INDEX_PRIO_HIGH + 1)
89 #else
90 #define GNRC_NETIF_EVQ_INDEX_PRIO_LOW GNRC_NETIF_EVQ_INDEX_PRIO_HIGH
91 #endif
92 
96 #define GNRC_NETIF_EVQ_NUMOF (GNRC_NETIF_EVQ_INDEX_PRIO_LOW + 1)
97 
101 typedef enum {
102 #ifdef MODULE_GNRC_IPV6
105 #endif
106  GNRC_NETIF_BUS_NUMOF
108 
112 typedef enum {
126 
130 typedef struct gnrc_netif_ops gnrc_netif_ops_t;
131 
135 typedef struct {
140 #if IS_USED(MODULE_NETSTATS_L2) || defined(DOXYGEN)
142 #endif
143 #if IS_USED(MODULE_GNRC_NETIF_LORAWAN) || defined(DOXYGEN)
145 #endif
146 #if IS_USED(MODULE_GNRC_NETIF_IPV6) || defined(DOXYGEN)
148 #endif
149 #if IS_USED(MODULE_GNRC_NETIF_MAC) || defined(DOXYGEN)
151 #endif /* IS_USED(MODULE_GNRC_NETIF_MAC) || defined(DOXYGEN) */
152 #if IS_USED(MODULE_GNRC_NETIF_BUS) || DOXYGEN
153  msg_bus_t bus[GNRC_NETIF_BUS_NUMOF];
154 #endif
160  uint32_t flags;
169 #if IS_USED(MODULE_NETDEV_NEW_API) || defined(DOXYGEN)
184 #endif
185 #if (GNRC_NETIF_L2ADDR_MAXLEN > 0) || DOXYGEN
192  uint8_t l2addr[GNRC_NETIF_L2ADDR_MAXLEN];
193 
199  uint8_t l2addr_len;
200 #if defined(MODULE_GNRC_NETIF_DEDUP) || DOXYGEN
207 #endif
208 #endif
209 #if IS_USED(MODULE_GNRC_NETIF_6LO) || defined(DOXYGEN)
211 #endif
212 #if IS_USED(MODULE_GNRC_NETIF_PKTQ) || defined(DOXYGEN)
219 #endif
220  uint8_t cur_hl;
221  uint8_t device_type;
223 } gnrc_netif_t;
224 
240 static inline bool gnrc_netif_netdev_legacy_api(gnrc_netif_t *netif)
241 {
242  if (!IS_USED(MODULE_NETDEV_NEW_API) && !IS_USED(MODULE_NETDEV_LEGACY_API)) {
243  /* this should only happen for external netdevs or when no netdev is
244  * used (e.g. examples/gcoap can be used without any netdev, as still
245  * CoAP requests to ::1 can be send */
246  return true;
247  }
248 
249  if (!IS_USED(MODULE_NETDEV_NEW_API)) {
250  return true;
251  }
252 
253  if (!IS_USED(MODULE_NETDEV_LEGACY_API)) {
254  return false;
255  }
256 
257  /* both legacy and new API netdevs in use, fall back to runtime test: */
258  return (netif->dev->driver->confirm_send == NULL);
259 }
260 
269 static inline bool gnrc_netif_netdev_new_api(gnrc_netif_t *netif)
270 {
271  return !gnrc_netif_netdev_legacy_api(netif);
272 }
273 
299  int (*init)(gnrc_netif_t *netif);
300 
321  int (*send)(gnrc_netif_t *netif, gnrc_pktsnip_t *pkt);
322 
339  gnrc_pktsnip_t *(*recv)(gnrc_netif_t *netif);
340 
355  int (*get)(gnrc_netif_t *netif, gnrc_netapi_opt_t *opt);
356 
372  int (*set)(gnrc_netif_t *netif, const gnrc_netapi_opt_t *opt);
373 
384  void (*msg_handler)(gnrc_netif_t *netif, msg_t *msg);
385 };
386 
396 
414 int gnrc_netif_create(gnrc_netif_t *netif, char *stack, int stacksize,
415  char priority, const char *name, netdev_t *dev,
416  const gnrc_netif_ops_t *ops);
417 
423 unsigned gnrc_netif_numof(void);
424 
436 static inline bool gnrc_netif_highlander(void)
437 {
438  return IS_USED(MODULE_GNRC_NETIF_SINGLE);
439 }
440 
450 
460 
482 static inline int gnrc_netif_ipv6_addrs_get(const gnrc_netif_t *netif,
483  ipv6_addr_t *addrs,
484  size_t max_len)
485 {
486  assert(netif != NULL);
487  assert(addrs != NULL);
488  assert(max_len >= sizeof(ipv6_addr_t));
489  return gnrc_netapi_get(netif->pid, NETOPT_IPV6_ADDR, 0, addrs, max_len);
490 }
491 
513 static inline int gnrc_netif_ipv6_addr_add(const gnrc_netif_t *netif,
514  const ipv6_addr_t *addr, unsigned pfx_len,
515  uint8_t flags)
516 {
517  assert(netif != NULL);
518  assert(addr != NULL);
519  assert((pfx_len > 0) && (pfx_len <= 128));
520  return gnrc_netapi_set(netif->pid, NETOPT_IPV6_ADDR,
521  ((pfx_len << 8U) | flags), addr,
522  sizeof(ipv6_addr_t));
523 }
524 
538 static inline int gnrc_netif_ipv6_addr_remove(const gnrc_netif_t *netif,
539  const ipv6_addr_t *addr)
540 {
541  assert(netif != NULL);
542  assert(addr != NULL);
544  0, addr, sizeof(ipv6_addr_t));
545 }
546 
567 static inline int gnrc_netif_ipv6_groups_get(const gnrc_netif_t *netif,
568  ipv6_addr_t *groups,
569  size_t max_len)
570 {
571  assert(netif != NULL);
572  assert(groups != NULL);
573  assert(max_len >= sizeof(ipv6_addr_t));
574  return gnrc_netapi_get(netif->pid, NETOPT_IPV6_GROUP, 0, groups, max_len);
575 }
576 
591 static inline int gnrc_netif_ipv6_group_join(const gnrc_netif_t *netif,
592  ipv6_addr_t *group)
593 {
594  assert(netif != NULL);
595  assert(group != NULL);
596  return gnrc_netapi_set(netif->pid, NETOPT_IPV6_GROUP, 0, group,
597  sizeof(ipv6_addr_t));
598 }
599 
613 static inline int gnrc_netif_ipv6_group_leave(const gnrc_netif_t *netif,
614  ipv6_addr_t *group)
615 {
616  assert(netif != NULL);
617  assert(group != NULL);
618  return gnrc_netapi_set(netif->pid, NETOPT_IPV6_GROUP_LEAVE, 0, group,
619  sizeof(ipv6_addr_t));
620 }
621 
631 
644 
657  const gnrc_netapi_opt_t *opt);
658 
671 
690 static inline char *gnrc_netif_addr_to_str(const uint8_t *addr, size_t addr_len, char *out)
691 {
692  return l2util_addr_to_str(addr, addr_len, out);
693 }
694 
715 static inline size_t gnrc_netif_addr_from_str(const char *str, uint8_t *out)
716 {
717  return l2util_addr_from_str(str, out);
718 }
719 
729 static inline int gnrc_netif_send(gnrc_netif_t *netif, gnrc_pktsnip_t *pkt)
730 {
731  return gnrc_netapi_send(netif->pid, pkt);
732 }
733 
734 #if defined(MODULE_GNRC_NETIF_BUS) || DOXYGEN
744  gnrc_netif_bus_t type)
745 {
746  assert(type < GNRC_NETIF_BUS_NUMOF);
747  return &netif->bus[type];
748 }
749 
765  uint32_t timeout_ms);
766 #endif /* MODULE_GNRC_NETIF_BUS */
767 
768 #ifdef __cplusplus
769 }
770 #endif
771 
772 #endif /* NET_GNRC_NETIF_H */
6LoWPAN definitions for Network interface API
#define assert(cond)
abort the program if assertion is false
Definition: assert.h:113
Definitions low-level network driver interface.
Flag definitions for Network interface API.
IPv6 definitions for Network interface API.
int16_t kernel_pid_t
Unique process identifier.
Definition: sched.h:139
netdev_type_t
Driver types for netdev.
Definition: netdev.h:305
static int gnrc_netapi_set(kernel_pid_t pid, netopt_t opt, uint16_t context, const void *data, size_t data_len)
Shortcut function for sending GNRC_NETAPI_MSG_TYPE_SET messages and parsing the returned GNRC_NETAPI_...
Definition: netapi.h:254
static int gnrc_netapi_get(kernel_pid_t pid, netopt_t opt, uint16_t context, void *data, size_t max_len)
Shortcut function for sending GNRC_NETAPI_MSG_TYPE_GET messages and parsing the returned GNRC_NETAPI_...
Definition: netapi.h:232
static int gnrc_netapi_send(kernel_pid_t pid, gnrc_pktsnip_t *pkt)
Shortcut function for sending GNRC_NETAPI_MSG_TYPE_SND messages.
Definition: netapi.h:153
#define GNRC_NETIF_L2ADDR_MAXLEN
Maximum length of the link-layer address.
Definition: conf.h:158
static int gnrc_netif_ipv6_addrs_get(const gnrc_netif_t *netif, ipv6_addr_t *addrs, size_t max_len)
Gets the (unicast on anycast) IPv6 address of an interface (if IPv6 is supported)
Definition: netif.h:482
static bool gnrc_netif_netdev_new_api(gnrc_netif_t *netif)
Check if the device belonging to the given netif uses the new netdev API.
Definition: netif.h:269
static size_t gnrc_netif_addr_from_str(const char *str, uint8_t *out)
Parses a string of colon-separated hexadecimals to a hardware address.
Definition: netif.h:715
gnrc_netif_t * gnrc_netif_get_by_type(netdev_type_t type, uint8_t index)
Gets an interface by the netdev type (and index)
gnrc_ipv6_event_t
Event types for GNRC_NETIF_BUS_IPV6 per-interface message bus.
Definition: netif.h:112
#define GNRC_NETIF_EVQ_NUMOF
Number of event queues.
Definition: netif.h:96
static bool gnrc_netif_netdev_legacy_api(gnrc_netif_t *netif)
Check if the device belonging to the given netif uses the legacy netdev API.
Definition: netif.h:240
int gnrc_netif_set_from_netdev(gnrc_netif_t *netif, const gnrc_netapi_opt_t *opt)
Default operation for gnrc_netif_ops_t::set()
static int gnrc_netif_send(gnrc_netif_t *netif, gnrc_pktsnip_t *pkt)
Send a GNRC packet via a given gnrc_netif_t interface.
Definition: netif.h:729
int gnrc_netif_default_init(gnrc_netif_t *netif)
Default operation for gnrc_netif_ops_t::init()
static int gnrc_netif_ipv6_addr_add(const gnrc_netif_t *netif, const ipv6_addr_t *addr, unsigned pfx_len, uint8_t flags)
Adds an (unicast or anycast) IPv6 address to an interface (if IPv6 is supported)
Definition: netif.h:513
unsigned gnrc_netif_numof(void)
Get number of network interfaces actually allocated.
static msg_bus_t * gnrc_netif_get_bus(gnrc_netif_t *netif, gnrc_netif_bus_t type)
Get a message bus of a given gnrc_netif_t interface.
Definition: netif.h:743
bool gnrc_netif_ipv6_wait_for_global_address(gnrc_netif_t *netif, uint32_t timeout_ms)
Wait for a global address to become available.
int gnrc_netif_create(gnrc_netif_t *netif, char *stack, int stacksize, char priority, const char *name, netdev_t *dev, const gnrc_netif_ops_t *ops)
Creates a network interface.
gnrc_netif_bus_t
Per-Interface Event Message Buses.
Definition: netif.h:101
gnrc_netif_t * gnrc_netif_iter(const gnrc_netif_t *prev)
Iterate over all network interfaces.
static char * gnrc_netif_addr_to_str(const uint8_t *addr, size_t addr_len, char *out)
Converts a hardware address to a human readable string.
Definition: netif.h:690
static int gnrc_netif_ipv6_group_leave(const gnrc_netif_t *netif, ipv6_addr_t *group)
Leaves an IPv6 multicast group on an interface (if IPv6 is supported)
Definition: netif.h:613
int gnrc_netif_get_from_netdev(gnrc_netif_t *netif, gnrc_netapi_opt_t *opt)
Default operation for gnrc_netif_ops_t::get()
static int gnrc_netif_ipv6_groups_get(const gnrc_netif_t *netif, ipv6_addr_t *groups, size_t max_len)
Gets the IPv6 multicast groups an interface is joined to (if IPv6 is supported)
Definition: netif.h:567
static int gnrc_netif_ipv6_addr_remove(const gnrc_netif_t *netif, const ipv6_addr_t *addr)
Removes a (unicast or anycast) IPv6 address from an interface (if IPv6 is supported)
Definition: netif.h:538
gnrc_netif_t * gnrc_netif_get_by_pid(kernel_pid_t pid)
Get network interface by PID.
static bool gnrc_netif_highlander(void)
Check if there can only be one gnrc_netif_t interface.
Definition: netif.h:436
void gnrc_netif_init_devs(void)
Initialize all available network interfaces.
static int gnrc_netif_ipv6_group_join(const gnrc_netif_t *netif, ipv6_addr_t *group)
Joins an IPv6 multicast group on an interface (if IPv6 is supported)
Definition: netif.h:591
@ GNRC_IPV6_EVENT_ADDR_VALID
Address becomes valid.
Definition: netif.h:124
@ GNRC_NETIF_BUS_IPV6
provides gnrc_ipv6_event_t messages to subscribers
Definition: netif.h:103
char * l2util_addr_to_str(const uint8_t *addr, size_t addr_len, char *out)
Converts a hardware address to a human readable string.
size_t l2util_addr_from_str(const char *str, uint8_t *out)
Parses a string of colon-separated hexadecimals to a hardware address.
@ NETOPT_IPV6_GROUP
(ipv6_addr_t) get IPv6 multicast groups of an interface as array of ipv6_addr_t or join an IPv6 multi...
Definition: netopt.h:161
@ NETOPT_IPV6_GROUP_LEAVE
(ipv6_addr_t) Leave an IPv6 multicast group on an interface
Definition: netopt.h:165
@ NETOPT_IPV6_ADDR
(ipv6_addr_t[]) get IPv6 addresses of an interface as array of ipv6_addr_t or add an IPv6 address as ...
Definition: netopt.h:133
@ NETOPT_IPV6_ADDR_REMOVE
(ipv6_addr_t) Removes an IPv6 address from an interface
Definition: netopt.h:137
Definition of net statistics.
Definitions for IPv6 addresses.
#define IS_USED(module)
Checks whether a module is being used or not.
Link-layer helper function definitions.
Messaging Bus API for inter process message broadcast.
IPv6 neighbor discovery message type definitions.
General definitions for network packets and their helper functions.
Generic interface to communicate with GNRC modules.
Configuration macros for Network interface API.
LoRaWAN adaption for Network interface API.
Common MAC module definitions for Network interface API
Common network interface API definitions.
Definition of global configuration options.
Recursive Mutex for thread synchronization.
Scheduler API definition.
event queue structure
Definition: event.h:155
event structure
Definition: event.h:147
Data structure to be send for setting (GNRC_NETAPI_MSG_TYPE_SET) and getting (GNRC_NETAPI_MSG_TYPE_GE...
Definition: netapi.h:100
6Lo component of gnrc_netif_t
Definition: 6lo.h:52
Structure to store information on the last broadcast packet received.
Definition: dedup.h:41
IPv6 component for gnrc_netif_t.
Definition: ipv6.h:78
GNRC LoRaWAN interface descriptor.
Definition: lorawan.h:52
Common MAC module component of gnrc_netif_mac_t
Definition: mac.h:72
int(* init)(gnrc_netif_t *netif)
Initializes and registers network interface.
Definition: netif.h:299
int(* set)(gnrc_netif_t *netif, const gnrc_netapi_opt_t *opt)
Sets an option from the network interface.
Definition: netif.h:372
int(* send)(gnrc_netif_t *netif, gnrc_pktsnip_t *pkt)
Send a packet over the network interface.
Definition: netif.h:321
void(* msg_handler)(gnrc_netif_t *netif, msg_t *msg)
Message handler for network interface.
Definition: netif.h:384
int(* get)(gnrc_netif_t *netif, gnrc_netapi_opt_t *opt)
Gets an option from the network interface.
Definition: netif.h:355
A packet queue for Network interface API with a de-queue timer.
Definition: type.h:36
Representation of a network interface.
Definition: netif.h:135
gnrc_netif_lorawan_t lorawan
LoRaWAN component.
Definition: netif.h:144
msg_bus_t bus[GNRC_NETIF_BUS_NUMOF]
Event Message Bus.
Definition: netif.h:153
rmutex_t mutex
Mutex of the interface.
Definition: netif.h:139
netstats_t stats
transceiver's statistics
Definition: netif.h:141
uint32_t flags
Flags for the interface.
Definition: netif.h:160
const gnrc_netif_ops_t * ops
Operations of the network interface.
Definition: netif.h:137
uint8_t device_type
Device type.
Definition: netif.h:221
gnrc_netif_6lo_t sixlo
6Lo component
Definition: netif.h:210
uint8_t cur_hl
Current hop-limit for out-going packets.
Definition: netif.h:220
netif_t netif
network interface descriptor
Definition: netif.h:136
uint8_t l2addr_len
Length in bytes of gnrc_netif_t::l2addr.
Definition: netif.h:199
kernel_pid_t pid
PID of the network interface's thread.
Definition: netif.h:222
event_t event_isr
ISR event for the network device.
Definition: netif.h:168
gnrc_netif_mac_t mac
Common MAC module component
Definition: netif.h:150
gnrc_netif_dedup_t last_pkt
Last received packet information.
Definition: netif.h:206
gnrc_netif_ipv6_t ipv6
IPv6 component.
Definition: netif.h:147
netdev_t * dev
Network device of the network interface.
Definition: netif.h:138
gnrc_pktsnip_t * tx_pkt
Outgoing frame that is currently transmitted.
Definition: netif.h:183
event_t event_tx_done
TX done event for the network device.
Definition: netif.h:175
gnrc_netif_pktq_t send_queue
Packet queue for sending.
Definition: netif.h:218
Type to represent parts (either headers or payload) of a packet, called snips.
Definition: pkt.h:108
A message bus is just a list of subscribers.
Definition: msg_bus.h:54
Describes a message object which can be sent between threads.
Definition: msg.h:196
int(* confirm_send)(netdev_t *dev, void *info)
Fetch the status of a transmission and perform any potential cleanup.
Definition: netdev.h:482
Structure to hold driver state.
Definition: netdev.h:361
const struct netdev_driver * driver
ptr to that driver's interface.
Definition: netdev.h:362
Network interface descriptor.
Definition: netif.h:71
Global statistics struct.
Definition: netstats.h:60
Mutex structure.
Definition: rmutex.h:38
Send queue for Network interface API type definitions
Data type to represent an IPv6 address.
Definition: addr.h:72