Network interface API

Abstraction layer for GNRC’s network interfaces.

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

struct gnrc_netif_ops gnrc_netif_ops_t

Operations to an interface.

gnrc_netif_t * gnrc_netif_create(char * stack, int stacksize, char priority, const char * name, netdev.h::netdev_t * dev, const gnrc/netif.h::gnrc_netif_ops_t * ops)

Creates a network interface.

Parameters

stack:The stack for the network interface’s thread. stacksize:Size of stack. priority:Priority for the network interface’s thread. name:Name for the network interface. May be NULL. dev:Device for the interface. ops:Operations for the network interface.

Note

If doc.txt::DEVELHELP is defined netif_params_t::name is used as the name of the network interface’s thread.

Return values

• The network interface on success.

unsigned gnrc_netif_numof(void)

Get number of network interfaces actually allocated.

Return values

• Number of network interfaces actually allocated

gnrc_netif_t * gnrc_netif_iter(const gnrc_netif_t * prev)

Iterate over all network interfaces.

Parameters

prev:previous interface in iteration. NULL to start iteration.

Return values

• The next network interface after prev.
• NULL, if prev was the last network interface.

gnrc_netif_t * gnrc_netif_get_by_pid(kernel_types.h::kernel_pid_t pid)

Get network interface by PID.

Parameters

pid:A PID of a network interface.

Return values

• The network interface on success.
• NULL, if no network interface with PID exists.

int gnrc_netif_ipv6_addrs_get(const gnrc_netif_t * netif, ipv6_addr_t * addrs, msp430_types.h::size_t max_len)

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

Parameters

netif:The interface. May not be NULL. addrs:Up to the first max_len / sizeof(ipv6_addr_t) addresses assigned to netif. May not be NULL max_len:Number of bytes available in addrs. Must be at least sizeof(ipv6_addr_t). It is recommended to use GNRC_NETIF_IPV6_ADDRS_NUMOF `* sizeof(ipv6_addr_t) here (and have addrs of the according length).

Return values

• Number of addresses in addrs times sizeof(ipv6_addr_t) on success (including 0).
• -ENOTSUP, if netif doesn’t support IPv6.

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)

Parameters

netif:The interface. May not be NULL. addr:The address to add to netif. May not be NULL. pfx_len:The prefix length of addr. Must be greater than 0 and lesser than or equal to 128. flags: for addr. Set gnrc/netif/ipv6.h::GNRC_NETIF_IPV6_ADDRS_FLAGS_STATE_VALID to skip duplicate address detection (when activated).

Return values

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

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)

Parameters

netif:The interface. May not be NULL. addr:The address to remove from netif. May not be NULL.

Return values

• sizeof(ipv6_addr_t) on success.
• -ENOTSUP, if netif doesn’t support IPv6.

int gnrc_netif_ipv6_groups_get(const gnrc_netif_t * netif, ipv6_addr_t * groups, msp430_types.h::size_t max_len)

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

Parameters

netif:The interface. May not be NULL. groups:Up to the first max_len / 8 multicast groups netif is joined to. May not be NULL 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).

Return values

• Number of addresses in groups times sizeof(ipv6_addr_t) on success (including 0).
• -ENOTSUP, if netif doesn’t support IPv6.

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)

Parameters

netif:The interface. group:The address of the multicast group to join on netif. May not be NULL.

Return values

• sizeof(ipv6_addr_t) on success.
• -ENOMEM, if no space is left on netif to add group.
• -ENOTSUP, if netif doesn’t support IPv6.

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)

Parameters

netif:The interface. group:The address of the multicast group to leave on netif. May not be NULL.

Return values

• sizeof(ipv6_addr_t) on success.
• -ENOTSUP, if netif doesn’t support IPv6.

int gnrc_netif_get_from_netdev(gnrc_netif_t * netif, gnrc_netapi_opt_t * opt)

Default operation for gnrc/netif.h::gnrc_netif_ops::get

Note

Can also be used to be called after a custom operation.

Parameters

netif:The network interface. opt:The option parameters.

Return values

• Return value of netdev.h::netdev_driver::get of gnrc/netif.h::gnrc_netif_t::dev of netif.

int gnrc_netif_set_from_netdev(gnrc_netif_t * netif, const gnrc_netapi_opt_t * opt)

Default operation for gnrc/netif.h::gnrc_netif_ops::set

Note

Can also be used to be called after a custom operation.

Parameters

netif:The network interface. opt:The option parameters.

Return values

• Return value of netdev.h::netdev_driver::set of gnrc/netif.h::gnrc_netif_t::dev of netif.

char * gnrc_netif_addr_to_str(const uint8_t * addr, msp430_types.h::size_t addr_len, char * out)

Converts a hardware address to a human readable string.

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

Parameters

addr:A hardware address. addr_len:Length of addr. out:A string to store the output in. Must at least have 3 * addr_len bytes allocated.

Return values

• out.

msp430_types.h::size_t gnrc_netif_addr_from_str(const char * str, uint8_t * out)

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

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

Parameters

str:A string of colon-separated hexadecimals. out:The resulting hardware address. Must at least have netif/conf.h::GNRC_NETIF_L2ADDR_MAXLEN bytes allocated.

Return values

• Actual length of out on success.
• 0, on failure.

struct gnrc_netif_t

Representation of a network interface.

const gnrc/netif.h::gnrc_netif_ops_t * ops

Operations of the network interface.

netdev.h::netdev_t * dev

Network device of the network interface.

rmutex_t mutex

Mutex of the interface.

gnrc_netif_ipv6_t ipv6

IPv6 component.

gnrc_netif_mac_t mac

Common MAC module component

uint32_t flags

Flags for the interface.

See also

net_gnrc_netif_flags

gnrc_netif_6lo_t sixlo

6Lo component

uint8_t cur_hl

Current hop-limit for out-going packets.

uint8_t device_type

Device type.

kernel_types.h::kernel_pid_t pid

PID of the network interface’s thread.

struct gnrc_netif_ops

See also

gnrc/netif.h::gnrc_netif_ops_t

void(* init()

Initializes network interface beyond the default settings.

Parameters

netif:The network interface.

This is called after the default settings were set, right before the interface’s thread starts receiving messages. It is not necessary to lock the interface’s mutex gnrc/netif.h::gnrc_netif_t::mutex, since the thread will already lock it. Leave NULL if you do not need any special initialization.

int(* send()

Send a packet over the network interface.

Note

The function re-formats the content of pkt to a format expected by the netdev.h::netdev_driver::send method of gnrc/netif.h::gnrc_netif_t::dev and releases the packet before returning (so no additional release should be required after calling this method).

Parameters

netif:The network interface. pkt:A packet to send.

Return values

• The number of bytes actually sent on success
• -EBADMSG, if the Generic network interface header in pkt is missing or is in an unexpected format.
• -ENOTSUP, if sending pkt in the given format isn’t supported (e.g. empty payload with Ethernet).
• Any negative error code reported by gnrc/netif.h::gnrc_netif_t::dev.

include/net/gnrc/pkt.h::gnrc_pktsnip_t *(* recv()

Receives a packet from the network interface.

Note

The function takes the bytes received via netdev.h::netdev_driver::recv from gnrc/netif.h::gnrc_netif_t::dev and re-formats it to a packet containing a Generic network interface header and a payload header in receive order.

Parameters

netif:The network interface.

Return values

• The packet received. Contains the payload (with the type marked accordingly) and a Generic network interface header in receive order.
• NULL, if Packet buffer was full.

int(* get()

Gets an option from the network interface.

Use gnrc/netif.h::gnrc_netif_get_from_netdev() to just get options from gnrc/netif.h::gnrc_netif_t::dev.

Parameters

netif:The network interface. opt:The option parameters.

Return values

• Number of bytes in data.
• -EOVERFLOW, if max_len is lesser than the required space.
• -ENOTSUP, if opt is not supported to be set.
• Any negative error code reported by gnrc/netif.h::gnrc_netif_t::dev.

int(* set()

Sets an option from the network interface.

Use gnrc/netif.h::gnrc_netif_set_from_netdev() to just set options from gnrc/netif.h::gnrc_netif_t::dev.

Parameters

netif:The network interface. opt:The option parameters.

Return values

• Number of bytes written to gnrc/netif.h::gnrc_netif_t::dev.
• -EOVERFLOW, if data_len is greater than the allotted space in gnrc/netif.h::gnrc_netif_t::dev or gnrc_netif_t.
• -ENOTSUP, if opt is not supported to be set.
• Any negative error code reported by gnrc/netif.h::gnrc_netif_t::dev.

void(* msg_handler()

Message handler for network interface.

This message handler is used, when the network interface needs to handle message types beyond the ones defined in netapi. Leave NULL if this is not the case.

Parameters

netif:The network interface. msg:Message to be handled.