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
224  uint8_t cur_hl;
225  uint8_t device_type;
227 } gnrc_netif_t;
228 
244 static inline bool gnrc_netif_netdev_legacy_api(gnrc_netif_t *netif)
245 {
246  if (!IS_USED(MODULE_NETDEV_NEW_API) && !IS_USED(MODULE_NETDEV_LEGACY_API)) {
247  /* this should only happen for external netdevs or when no netdev is
248  * used (e.g. examples/gcoap can be used without any netdev, as still
249  * CoAP requests to ::1 can be send */
250  return true;
251  }
252 
253  if (!IS_USED(MODULE_NETDEV_NEW_API)) {
254  return true;
255  }
256 
257  if (!IS_USED(MODULE_NETDEV_LEGACY_API)) {
258  return false;
259  }
260 
261  /* both legacy and new API netdevs in use, fall back to runtime test: */
262  return (netif->dev->driver->confirm_send == NULL);
263 }
264 
273 static inline bool gnrc_netif_netdev_new_api(gnrc_netif_t *netif)
274 {
275  return !gnrc_netif_netdev_legacy_api(netif);
276 }
277 
303  int (*init)(gnrc_netif_t *netif);
304 
325  int (*send)(gnrc_netif_t *netif, gnrc_pktsnip_t *pkt);
326 
343  gnrc_pktsnip_t *(*recv)(gnrc_netif_t *netif);
344 
359  int (*get)(gnrc_netif_t *netif, gnrc_netapi_opt_t *opt);
360 
376  int (*set)(gnrc_netif_t *netif, const gnrc_netapi_opt_t *opt);
377 
388  void (*msg_handler)(gnrc_netif_t *netif, msg_t *msg);
389 };
390 
400 
418 int gnrc_netif_create(gnrc_netif_t *netif, char *stack, int stacksize,
419  char priority, const char *name, netdev_t *dev,
420  const gnrc_netif_ops_t *ops);
421 
427 unsigned gnrc_netif_numof(void);
428 
440 static inline bool gnrc_netif_highlander(void)
441 {
442  return IS_USED(MODULE_GNRC_NETIF_SINGLE);
443 }
444 
454 
464 
486 static inline int gnrc_netif_ipv6_addrs_get(const gnrc_netif_t *netif,
487  ipv6_addr_t *addrs,
488  size_t max_len)
489 {
490  assert(netif != NULL);
491  assert(addrs != NULL);
492  assert(max_len >= sizeof(ipv6_addr_t));
493  return gnrc_netapi_get(netif->pid, NETOPT_IPV6_ADDR, 0, addrs, max_len);
494 }
495 
517 static inline int gnrc_netif_ipv6_addr_add(const gnrc_netif_t *netif,
518  const ipv6_addr_t *addr, unsigned pfx_len,
519  uint8_t flags)
520 {
521  assert(netif != NULL);
522  assert(addr != NULL);
523  assert((pfx_len > 0) && (pfx_len <= 128));
524  return gnrc_netapi_set(netif->pid, NETOPT_IPV6_ADDR,
525  ((pfx_len << 8U) | flags), addr,
526  sizeof(ipv6_addr_t));
527 }
528 
542 static inline int gnrc_netif_ipv6_addr_remove(const gnrc_netif_t *netif,
543  const ipv6_addr_t *addr)
544 {
545  assert(netif != NULL);
546  assert(addr != NULL);
548  0, addr, sizeof(ipv6_addr_t));
549 }
550 
571 static inline int gnrc_netif_ipv6_groups_get(const gnrc_netif_t *netif,
572  ipv6_addr_t *groups,
573  size_t max_len)
574 {
575  assert(netif != NULL);
576  assert(groups != NULL);
577  assert(max_len >= sizeof(ipv6_addr_t));
578  return gnrc_netapi_get(netif->pid, NETOPT_IPV6_GROUP, 0, groups, max_len);
579 }
580 
595 static inline int gnrc_netif_ipv6_group_join(const gnrc_netif_t *netif,
596  const ipv6_addr_t *group)
597 {
598  assert(netif != NULL);
599  assert(group != NULL);
600  return gnrc_netapi_set(netif->pid, NETOPT_IPV6_GROUP, 0, group,
601  sizeof(ipv6_addr_t));
602 }
603 
617 static inline int gnrc_netif_ipv6_group_leave(const gnrc_netif_t *netif,
618  const ipv6_addr_t *group)
619 {
620  assert(netif != NULL);
621  assert(group != NULL);
622  return gnrc_netapi_set(netif->pid, NETOPT_IPV6_GROUP_LEAVE, 0, group,
623  sizeof(ipv6_addr_t));
624 }
625 
635 
648 
661  const gnrc_netapi_opt_t *opt);
662 
675 
694 static inline char *gnrc_netif_addr_to_str(const uint8_t *addr, size_t addr_len, char *out)
695 {
696  return l2util_addr_to_str(addr, addr_len, out);
697 }
698 
719 static inline size_t gnrc_netif_addr_from_str(const char *str, uint8_t *out)
720 {
721  return l2util_addr_from_str(str, out);
722 }
723 
733 static inline int gnrc_netif_send(gnrc_netif_t *netif, gnrc_pktsnip_t *pkt)
734 {
735  return gnrc_netapi_send(netif->pid, pkt);
736 }
737 
738 #if defined(MODULE_GNRC_NETIF_BUS) || DOXYGEN
748  gnrc_netif_bus_t type)
749 {
750  assert(type < GNRC_NETIF_BUS_NUMOF);
751  return &netif->bus[type];
752 }
753 
769  uint32_t timeout_ms);
770 #endif /* MODULE_GNRC_NETIF_BUS */
771 
772 #ifdef __cplusplus
773 }
774 #endif
775 
776 #endif /* NET_GNRC_NETIF_H */
6LoWPAN definitions for Network interface API
#define assert(cond)
abort the program if assertion is false
Definition: assert.h:117
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:486
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:273
static int gnrc_netif_ipv6_group_leave(const gnrc_netif_t *netif, const ipv6_addr_t *group)
Leaves an IPv6 multicast group on an interface (if IPv6 is supported)
Definition: netif.h:617
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:719
static int gnrc_netif_ipv6_group_join(const gnrc_netif_t *netif, const ipv6_addr_t *group)
Joins an IPv6 multicast group on an interface (if IPv6 is supported)
Definition: netif.h:595
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:244
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:733
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:517
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:747
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:694
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:571
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:542
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:440
void gnrc_netif_init_devs(void)
Initialize all available network interfaces.
@ 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.
Link-layer helper function definitions.
#define IS_USED(module)
Checks whether a module is being used or not.
Definition: modules.h:71
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.
#define GNRC_NETIF_MSG_QUEUE_SIZE
Message queue size for network interface threads.
Definition: conf.h:182
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:303
int(* set)(gnrc_netif_t *netif, const gnrc_netapi_opt_t *opt)
Sets an option from the network interface.
Definition: netif.h:376
int(* send)(gnrc_netif_t *netif, gnrc_pktsnip_t *pkt)
Send a packet over the network interface.
Definition: netif.h:325
void(* msg_handler)(gnrc_netif_t *netif, msg_t *msg)
Message handler for network interface.
Definition: netif.h:388
int(* get)(gnrc_netif_t *netif, gnrc_netapi_opt_t *opt)
Gets an option from the network interface.
Definition: netif.h:359
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:225
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:224
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:226
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:483
Structure to hold driver state.
Definition: netdev.h:362
const struct netdev_driver * driver
ptr to that driver's interface.
Definition: netdev.h:363
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