Loading...
Searching...
No Matches

Abstraction layer for GNRC's network interfaces. More...

Detailed Description

Abstraction layer for GNRC's network interfaces.

Network interfaces in the context of GNRC are threads for protocols that are below the network layer.

Single interface optimizations

If you only have one network interface on the board, you can select the gnrc_netif_single pseudo-module to enable further optimisations.

Modules

 CC1100/CC1100e/CC1101/CC1200 common code
 
 GNRC network interface configurations
 
 Generic network interface header
 
 Link-layer Broadcast deduplication
 Deduplicates broadcast link-layer packets best-effort style.
 
 Send queue for @ref net_gnrc_netif
 

Files

file  gnrc_netif_nrf24l01p_ng.h
 NRF24L01+ (NG) adaptation for Network interface API.
 
file  gnrc_netif_xbee.h
 XBee adaption for Network interface API.
 
file  netif.h
 Definition for GNRC's network interfaces.
 
file  6lo.h
 6LoWPAN definitions for Network interface API
 
file  ethernet.h
 Ethernet adaption for Network interface API.
 
file  flags.h
 Flag definitions for Network interface API.
 
file  ieee802154.h
 IEEE 802.15.4 adaption for Network interface API.
 
file  ipv6.h
 IPv6 definitions for Network interface API.
 
file  lorawan.h
 LoRaWAN adaption for Network interface API.
 
file  lorawan_base.h
 LoRaWAN base Network interface API header.
 
file  mac.h
 Common MAC module definitions for Network interface API
 
file  raw.h
 Raw (i.e.
 

Data Structures

struct  gnrc_netif_t
 Representation of a network interface. More...
 
struct  gnrc_netif_ops
 

Macros

#define GNRC_NETIF_EVQ_INDEX_PRIO_HIGH   (0)
 Index of the high priority queue.
 
#define GNRC_NETIF_EVQ_INDEX_PRIO_LOW   GNRC_NETIF_EVQ_INDEX_PRIO_HIGH
 Index of the low priority queue.
 
#define GNRC_NETIF_EVQ_NUMOF   (GNRC_NETIF_EVQ_INDEX_PRIO_LOW + 1)
 Number of event queues.
 

Typedefs

typedef struct gnrc_netif_ops gnrc_netif_ops_t
 Operations to an interface.
 

Enumerations

enum  gnrc_netif_bus_t { GNRC_NETIF_BUS_IPV6 , GNRC_NETIF_BUS_NUMOF }
 Per-Interface Event Message Buses. More...
 
enum  gnrc_ipv6_event_t { GNRC_IPV6_EVENT_ADDR_VALID }
 Event types for GNRC_NETIF_BUS_IPV6 per-interface message bus. More...
 

Functions

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.
 
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.
 
void gnrc_netif_init_devs (void)
 Initialize all available network interfaces.
 
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.
 
unsigned gnrc_netif_numof (void)
 Get number of network interfaces actually allocated.
 
static bool gnrc_netif_highlander (void)
 Check if there can only be one gnrc_netif_t interface.
 
gnrc_netif_tgnrc_netif_iter (const gnrc_netif_t *prev)
 Iterate over all network interfaces.
 
gnrc_netif_tgnrc_netif_get_by_pid (kernel_pid_t pid)
 Get network interface by PID.
 
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)
 
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)
 
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)
 
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)
 
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)
 
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)
 
int gnrc_netif_default_init (gnrc_netif_t *netif)
 Default operation for gnrc_netif_ops_t::init()
 
int gnrc_netif_get_from_netdev (gnrc_netif_t *netif, gnrc_netapi_opt_t *opt)
 Default operation for gnrc_netif_ops_t::get()
 
int gnrc_netif_set_from_netdev (gnrc_netif_t *netif, const gnrc_netapi_opt_t *opt)
 Default operation for gnrc_netif_ops_t::set()
 
gnrc_netif_tgnrc_netif_get_by_type (netdev_type_t type, uint8_t index)
 Gets an interface by the netdev type (and index)
 
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.
 
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.
 
static int gnrc_netif_send (gnrc_netif_t *netif, gnrc_pktsnip_t *pkt)
 Send a GNRC packet via a given gnrc_netif_t interface.
 
static msg_bus_tgnrc_netif_get_bus (gnrc_netif_t *netif, gnrc_netif_bus_t type)
 Get a message bus of a given gnrc_netif_t interface.
 
bool gnrc_netif_ipv6_wait_for_global_address (gnrc_netif_t *netif, uint32_t timeout_ms)
 Wait for a global address to become available.
 

Macro Definition Documentation

◆ GNRC_NETIF_EVQ_INDEX_PRIO_HIGH

#define GNRC_NETIF_EVQ_INDEX_PRIO_HIGH   (0)

Index of the high priority queue.

Definition at line 82 of file netif.h.

◆ GNRC_NETIF_EVQ_INDEX_PRIO_LOW

#define GNRC_NETIF_EVQ_INDEX_PRIO_LOW   GNRC_NETIF_EVQ_INDEX_PRIO_HIGH

Index of the low priority queue.

Definition at line 90 of file netif.h.

◆ GNRC_NETIF_EVQ_NUMOF

#define GNRC_NETIF_EVQ_NUMOF   (GNRC_NETIF_EVQ_INDEX_PRIO_LOW + 1)

Number of event queues.

Definition at line 96 of file netif.h.

Typedef Documentation

◆ gnrc_netif_ops_t

Operations to an interface.

Definition at line 130 of file netif.h.

Enumeration Type Documentation

◆ gnrc_ipv6_event_t

Event types for GNRC_NETIF_BUS_IPV6 per-interface message bus.

Enumerator
GNRC_IPV6_EVENT_ADDR_VALID 

Address becomes valid.

The event is generated when an address on the interface becomes valid. The message payload contains a pointer to the respective ipv6_addr_t struct.

Note
If the address on the interface changed between sending the event and processing it, the pointer will point to the new address which might not be valid.

Definition at line 112 of file netif.h.

◆ gnrc_netif_bus_t

Per-Interface Event Message Buses.

Enumerator
GNRC_NETIF_BUS_IPV6 

provides gnrc_ipv6_event_t messages to subscribers

Definition at line 101 of file netif.h.

Function Documentation

◆ gnrc_netif_addr_from_str()

static size_t gnrc_netif_addr_from_str ( const char *  str,
uint8_t *  out 
)
inlinestatic

Parses a string of colon-separated hexadecimals to a hardware address.

Note
Compatibility wrapper for
See also
l2util_addr_from_str

The input format must be like xx:xx:xx:xx where xx will be the bytes of addr in hexadecimal representation.

Precondition
(out != NULL)
out MUST have allocated at least GNRC_NETIF_L2ADDR_MAXLEN bytes.
Parameters
[in]strA string of colon-separated hexadecimals.
[out]outThe resulting hardware address. Must at least have GNRC_NETIF_L2ADDR_MAXLEN bytes allocated.
Returns
Actual length of out on success.
0, on failure.

Definition at line 719 of file netif.h.

◆ gnrc_netif_addr_to_str()

static char * gnrc_netif_addr_to_str ( const uint8_t *  addr,
size_t  addr_len,
char *  out 
)
inlinestatic

Converts a hardware address to a human readable string.

Note
Compatibility wrapper for
See also
l2util_addr_to_str

The format will be like xx:xx:xx:xx where xx are the bytes of addr in hexadecimal representation.

Precondition
(out != NULL) && ((addr != NULL) || (addr_len == 0))
out MUST have allocated at least 3 * addr_len bytes.
Parameters
[in]addrA hardware address.
[in]addr_lenLength of addr.
[out]outA string to store the output in. Must at least have 3 * addr_len bytes allocated.
Returns
out.

Definition at line 694 of file netif.h.

◆ gnrc_netif_create()

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.

Parameters
[out]netifThe interface. May not be NULL.
[in]stackThe stack for the network interface's thread.
[in]stacksizeSize of stack.
[in]priorityPriority for the network interface's thread.
[in]nameName for the network interface. May be NULL.
[in]devDevice for the interface.
[in]opsOperations for the network interface.
Note
If DEVELHELP is defined netif_params_t::name is used as the name of the network interface's thread.
Returns
0 on success
negative number on error

◆ gnrc_netif_default_init()

int gnrc_netif_default_init ( gnrc_netif_t netif)

Default operation for gnrc_netif_ops_t::init()

Note
Can also be used to be called before a custom operation. This function calls netif_register internally.
Parameters
[in]netifThe network interface.

◆ gnrc_netif_get_bus()

static msg_bus_t * gnrc_netif_get_bus ( gnrc_netif_t netif,
gnrc_netif_bus_t  type 
)
inlinestatic

Get a message bus of a given gnrc_netif_t interface.

Parameters
netifpointer to the interface
typeGNRC message bus type
Returns
the message bus for the interface

Definition at line 747 of file netif.h.

◆ gnrc_netif_get_by_pid()

gnrc_netif_t * gnrc_netif_get_by_pid ( kernel_pid_t  pid)

Get network interface by PID.

Parameters
[in]pidA PID of a network interface.
Returns
The network interface on success.
NULL, if no network interface with PID exists.

◆ gnrc_netif_get_by_type()

gnrc_netif_t * gnrc_netif_get_by_type ( netdev_type_t  type,
uint8_t  index 
)

Gets an interface by the netdev type (and index)

Precondition
The netdev has been registered with netdev_register
Parameters
[in]typedriver type of the netdev, can be NETDEV_ANY
[in]indexindex of the netdev, can be NETDEV_INDEX_ANY
Returns
The network interface that has a netdev of matching type and index NULL if no matching interface could be found

◆ gnrc_netif_get_from_netdev()

int gnrc_netif_get_from_netdev ( gnrc_netif_t netif,
gnrc_netapi_opt_t opt 
)

Default operation for gnrc_netif_ops_t::get()

Note
Can also be used to be called after a custom operation.
Parameters
[in]netifThe network interface.
[out]optThe option parameters.
Returns
Return value of netdev_driver_t::get() of gnrc_netif_t::dev of netif.

◆ gnrc_netif_highlander()

static bool gnrc_netif_highlander ( void  )
inlinestatic

Check if there can only be one gnrc_netif_t interface.

‍There can only be one!

This function is used to allow compile time optimizations for single interface applications

Returns
true, if there can only only one interface
false, if there can be more than one interface

Definition at line 440 of file netif.h.

◆ gnrc_netif_init_devs()

void gnrc_netif_init_devs ( void  )

Initialize all available network interfaces.

This function is called automatically if the auto_init_gnrc_netif module is used. If only the gnrc_netif_init module is used instead, you can call this function to manually set up the network interfaces at a later time.

◆ gnrc_netif_ipv6_addr_add()

static int gnrc_netif_ipv6_addr_add ( const gnrc_netif_t netif,
const ipv6_addr_t addr,
unsigned  pfx_len,
uint8_t  flags 
)
inlinestatic

Adds an (unicast or anycast) IPv6 address to an interface (if IPv6 is supported)

Precondition
netif != NULL
addr != NULL
(pfx_len > 0) && (pfx_len <= 128)
Parameters
[in]netifThe interface. May not be NULL.
[in]addrThe address to add to netif. May not be NULL.
[in]pfx_lenThe prefix length of addr. Must be greater than 0 and lesser than or equal to 128.
[in]flagsFlags for addr. Set GNRC_NETIF_IPV6_ADDRS_FLAGS_STATE_VALID to skip duplicate address detection (when activated).
Returns
sizeof(ipv6_addr_t) on success.
-ENOMEM, if no space is left on netif to add addr or its corresponding solicited-nodes multicast address.
-ENOTSUP, if netif doesn't support IPv6.

Definition at line 517 of file netif.h.

◆ gnrc_netif_ipv6_addr_remove()

static int gnrc_netif_ipv6_addr_remove ( const gnrc_netif_t netif,
const ipv6_addr_t addr 
)
inlinestatic

Removes a (unicast or anycast) IPv6 address from an interface (if IPv6 is supported)

Precondition
netif != NULL
addr != NULL
Parameters
[in]netifThe interface. May not be NULL.
[in]addrThe address to remove from netif. May not be NULL.
Returns
sizeof(ipv6_addr_t) on success.
-ENOTSUP, if netif doesn't support IPv6.

Definition at line 542 of file netif.h.

◆ gnrc_netif_ipv6_addrs_get()

static int gnrc_netif_ipv6_addrs_get ( const gnrc_netif_t netif,
ipv6_addr_t addrs,
size_t  max_len 
)
inlinestatic

Gets the (unicast on anycast) IPv6 address of an interface (if IPv6 is supported)

Precondition
netif != NULL
addrs != NULL
max_len >= sizeof(ipv6_addr_t)
Parameters
[in]netifThe interface. May not be NULL.
[out]addrsUp to the first max_len / sizeof(ipv6_addr_t) addresses assigned to netif. May not be NULL
[in]max_lenNumber of bytes available in addrs. Must be at least sizeof(ipv6_addr_t). It is recommended to use CONFIG_GNRC_NETIF_IPV6_ADDRS_NUMOF `* sizeof(ipv6_addr_t) here (and have addrs of the according length).
Returns
Size of the array of addresses in addrs on success. (number of addresses times sizeof(ipv6_addr_t)) May be 0 if no addresses are configured.
-ENOTSUP, if netif doesn't support IPv6.

Definition at line 486 of file netif.h.

◆ gnrc_netif_ipv6_group_join()

static int gnrc_netif_ipv6_group_join ( const gnrc_netif_t netif,
const ipv6_addr_t group 
)
inlinestatic

Joins an IPv6 multicast group on an interface (if IPv6 is supported)

Precondition
netif != NULL
group != NULL
Parameters
[in]netifThe interface.
[in]groupThe address of the multicast group to join on netif. May not be NULL.
Returns
sizeof(ipv6_addr_t) on success.
-ENOMEM, if no space is left on netif to add group.
-ENOTSUP, if netif doesn't support IPv6.

Definition at line 595 of file netif.h.

◆ gnrc_netif_ipv6_group_leave()

static int gnrc_netif_ipv6_group_leave ( const gnrc_netif_t netif,
const ipv6_addr_t group 
)
inlinestatic

Leaves an IPv6 multicast group on an interface (if IPv6 is supported)

Precondition
netif != NULL
group != NULL
Parameters
[in]netifThe interface.
[in]groupThe address of the multicast group to leave on netif. May not be NULL.
Returns
sizeof(ipv6_addr_t) on success.
-ENOTSUP, if netif doesn't support IPv6.

Definition at line 617 of file netif.h.

◆ gnrc_netif_ipv6_groups_get()

static int gnrc_netif_ipv6_groups_get ( const gnrc_netif_t netif,
ipv6_addr_t groups,
size_t  max_len 
)
inlinestatic

Gets the IPv6 multicast groups an interface is joined to (if IPv6 is supported)

Precondition
netif != NULL
groups != NULL
max_len >= sizeof(ipv6_addr_t)
Parameters
[in]netifThe interface. May not be NULL.
[out]groupsUp to the first max_len / 8 multicast groups netif is joined to. May not be NULL
[in]max_lenNumber of bytes available in groups. Must be at least sizeof(ipv6_addr_t). It is recommended to use GNRC_NETIF_IPV6_GROUPS_NUMOF `* sizeof(ipv6_addr_t) here (and have groups of the according length).
Returns
Number of addresses in groups times sizeof(ipv6_addr_t) on success (including 0).
-ENOTSUP, if netif doesn't support IPv6.

Definition at line 571 of file netif.h.

◆ gnrc_netif_ipv6_wait_for_global_address()

bool gnrc_netif_ipv6_wait_for_global_address ( gnrc_netif_t netif,
uint32_t  timeout_ms 
)

Wait for a global address to become available.

This function blocks until a valid global address has been configured, e.g. by receiving a router advertisement or via DHCPv6.

Requires the gnrc_netif_bus module.

Parameters
netifpointer to the interface May be NULL, then this checks for a global address on any interface.
timeout_msTime to wait for an address to become available, in ms.
Returns
true if a global address is configured

◆ gnrc_netif_iter()

gnrc_netif_t * gnrc_netif_iter ( const gnrc_netif_t prev)

Iterate over all network interfaces.

Parameters
[in]prevprevious interface in iteration. NULL to start iteration.
Returns
The next network interface after prev.
NULL, if prev was the last network interface.

◆ gnrc_netif_netdev_legacy_api()

static bool gnrc_netif_netdev_legacy_api ( gnrc_netif_t netif)
inlinestatic

Check if the device belonging to the given netif uses the legacy netdev API.

Check netdev_driver_t::confirm_send for info about the old and new netdev API.

netdevs using the legacy API have to depend on the (pseudo-)module netdev_legaqcy_api, netdevs using the new API have to depend on the (pseudo-)module netdev_new_api. If only one of the pseudo modules is used, this function can be constant folded. For boards mixing legacy and new API netdevs, this will check the flavor at runtime.

See also
netdev_driver_t::confirm_send

Definition at line 244 of file netif.h.

◆ gnrc_netif_netdev_new_api()

static bool gnrc_netif_netdev_new_api ( gnrc_netif_t netif)
inlinestatic

Check if the device belonging to the given netif uses the new netdev API.

See also
gnrc_netif_netdev_legacy_api
netdev_driver_t::confirm_send

Definition at line 273 of file netif.h.

◆ gnrc_netif_numof()

unsigned gnrc_netif_numof ( void  )

Get number of network interfaces actually allocated.

Returns
Number of network interfaces actually allocated

◆ gnrc_netif_send()

static int gnrc_netif_send ( gnrc_netif_t netif,
gnrc_pktsnip_t pkt 
)
inlinestatic

Send a GNRC packet via a given gnrc_netif_t interface.

Parameters
netifpointer to the interface
pktpacket to be sent.
Returns
1 if packet was successfully delivered
-1 on error

Definition at line 733 of file netif.h.

◆ gnrc_netif_set_from_netdev()

int gnrc_netif_set_from_netdev ( gnrc_netif_t netif,
const gnrc_netapi_opt_t opt 
)

Default operation for gnrc_netif_ops_t::set()

Note
Can also be used to be called after a custom operation.
Parameters
[in]netifThe network interface.
[in]optThe option parameters.
Returns
Return value of netdev_driver_t::set() of gnrc_netif_t::dev of netif.