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	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.

file	netif.h
	Definition for GNRC's network interfaces.

Data Structures
struct	gnrc_netif_t
	Representation of a network interface. More...

struct	gnrc_netif_ops

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
void	gnrc_netif_init_devs (void)
	Initialize all available network interfaces. More...

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. More...

unsigned	gnrc_netif_numof (void)
	Get number of network interfaces actually allocated. More...

static bool	gnrc_netif_highlander (void)
	Check if there can only be one gnrc_netif_t interface. More...

gnrc_netif_t *	gnrc_netif_iter (const gnrc_netif_t *prev)
	Iterate over all network interfaces. More...

gnrc_netif_t *	gnrc_netif_get_by_pid (kernel_pid_t pid)
	Get network interface by PID. More...

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) More...

static int	gnrc_netif_ipv6_addr_add (const gnrc_netif_t netif, ipv6_addr_t addr, unsigned pfx_len, uint8_t flags)
	Adds an (unicast or anycast) IPv6 address to an interface (if IPv6 is supported) More...

static int	gnrc_netif_ipv6_addr_remove (const gnrc_netif_t netif, ipv6_addr_t addr)
	Removes a (unicast or anycast) IPv6 address from an interface (if IPv6 is supported) More...

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) More...

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) More...

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) More...

void	gnrc_netif_default_init (gnrc_netif_t *netif)
	Default operation for gnrc_netif_ops_t::init() More...

int	gnrc_netif_get_from_netdev (gnrc_netif_t netif, gnrc_netapi_opt_t opt)
	Default operation for gnrc_netif_ops_t::get() More...

int	gnrc_netif_set_from_netdev (gnrc_netif_t netif, const gnrc_netapi_opt_t opt)
	Default operation for gnrc_netif_ops_t::set() More...

gnrc_netif_t *	gnrc_netif_get_by_type (netdev_type_t type, uint8_t index)
	Gets an interface by the netdev type (and index) More...

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. More...

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. More...

static int	gnrc_netif_send (gnrc_netif_t netif, gnrc_pktsnip_t pkt)
	Send a GNRC packet via a given gnrc_netif_t interface. More...

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. More...

Enumeration Type Documentation

◆ gnrc_ipv6_event_t

enum 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 93 of file netif.h.

◆ gnrc_netif_bus_t

enum 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 82 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]	str	A string of colon-separated hexadecimals.
[out]	out	The 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 625 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]	addr	A hardware address.
[in]	addr_len	Length of `addr`.
[out]	out	A string to store the output in. Must at least have 3 * `addr_len` bytes allocated.

Returns: out.

Definition at line 600 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]	netif	The interface. May not be `NULL`.
[in]	stack	The stack for the network interface's thread.
[in]	stacksize	Size of `stack`.
[in]	priority	Priority for the network interface's thread.
[in]	name	Name for the network interface. May be NULL.
[in]	dev	Device for the interface.
[in]	ops	Operations 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()

void 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.

Parameters

[in] netif The 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

netif	pointer to the interface
type	GNRC message bus type

Returns: the message bus for the interface

Definition at line 653 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] pid A 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]	type	driver type of the netdev, can be NETDEV_ANY
[in]	index	index 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]	netif	The network interface.
[out]	opt	The 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 348 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,
		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]	netif	The interface. May not be `NULL`.
[in]	addr	The address to add to `netif`. May not be `NULL`.
[in]	pfx_len	The prefix length of `addr`. Must be greater than 0 and lesser than or equal to 128.
[in]	flags	Flags 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 424 of file netif.h.

◆ gnrc_netif_ipv6_addr_remove()

static int gnrc_netif_ipv6_addr_remove	(	const gnrc_netif_t *	netif,
		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]	netif	The interface. May not be `NULL`.
[in]	addr	The 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 449 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]	netif	The interface. May not be `NULL`.
[out]	addrs	Up to the first `max_len / sizeof(ipv6_addr_t)` addresses assigned to `netif`. May not be `NULL`
[in]	max_len	Number 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: Number of addresses in addrs times sizeof(ipv6_addr_t) on success (including 0).; -ENOTSUP, if netif doesn't support IPv6.

Definition at line 393 of file netif.h.

◆ gnrc_netif_ipv6_group_join()

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

inlinestatic

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

Precondition: netif != NULL; group != NULL

Parameters

[in]	netif	The interface.
[in]	group	The 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 502 of file netif.h.

◆ gnrc_netif_ipv6_group_leave()

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

inlinestatic

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

Precondition: netif != NULL; group != NULL

Parameters

[in]	netif	The interface.
[in]	group	The 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 524 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]	netif	The interface. May not be `NULL`.
[out]	groups	Up to the first `max_len / 8` multicast groups `netif` is joined to. May not be `NULL`
[in]	max_len	Number 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 478 of file netif.h.

◆ gnrc_netif_iter()

gnrc_netif_t* gnrc_netif_iter ( const gnrc_netif_t * prev )

Iterate over all network interfaces.

Parameters

[in] prev previous interface in iteration. NULL to start iteration.

Returns: The next network interface after prev.; NULL, if prev was the last network interface.

◆ 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

netif	pointer to the interface
pkt	packet to be sent.

Returns: 1 if packet was successfully delivered; -1 on error

Definition at line 639 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]	netif	The network interface.
[in]	opt	The option parameters.

Returns: Return value of netdev_driver_t::set() of gnrc_netif_t::dev of netif.

Detailed Description

Single interface optimizations

Modules

Files

Data Structures

Typedefs

Enumerations

Functions

Enumeration Type Documentation

◆ gnrc_ipv6_event_t

◆ gnrc_netif_bus_t

Function Documentation

◆ gnrc_netif_addr_from_str()

◆ gnrc_netif_addr_to_str()

◆ gnrc_netif_create()

◆ gnrc_netif_default_init()

◆ gnrc_netif_get_bus()

◆ gnrc_netif_get_by_pid()

◆ gnrc_netif_get_by_type()

◆ gnrc_netif_get_from_netdev()

◆ gnrc_netif_highlander()

◆ gnrc_netif_init_devs()

◆ gnrc_netif_ipv6_addr_add()

◆ gnrc_netif_ipv6_addr_remove()

◆ gnrc_netif_ipv6_addrs_get()

◆ gnrc_netif_ipv6_group_join()

◆ gnrc_netif_ipv6_group_leave()

◆ gnrc_netif_ipv6_groups_get()

◆ gnrc_netif_iter()

◆ gnrc_netif_numof()

◆ gnrc_netif_send()

◆ gnrc_netif_set_from_netdev()