Ethernet

Overview

Ethernet is a networking technology commonly used in local area networks (LAN). For more information, see this Ethernet Wikipedia article.

Zephyr supports following Ethernet features:

Not all Ethernet device drivers support all of these features. You can see what is supported by net iface net-shell command. It will print currently supported Ethernet features.

API Reference

group ethernet

Ethernet support functions.

Defines

ETH_NET_DEVICE_INIT(dev_id, name, init_fn, pm, data, config, prio, api, mtu)

Create an Ethernet network interface and bind it to network device.

Parameters:

  • dev_id – Network device id.

  • name – The name this instance of the driver exposes to the system.

  • init_fn – Address to the init function of the driver.

  • pm – Reference to struct pm_device associated with the device. (optional).

  • data – Pointer to the device’s private data.

  • config – The address to the structure containing the configuration information for this instance of the driver.

  • prio – The initialization level at which configuration occurs.

  • api – Provides an initial pointer to the API function struct used by the driver. Can be NULL.

  • mtu – Maximum transfer unit in bytes for this network interface.

ETH_NET_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, prio, api, mtu)

Like ETH_NET_DEVICE_INIT but taking metadata from a devicetree.

Create an Ethernet network interface and bind it to network device.

Parameters:

  • node_id – The devicetree node identifier.

  • init_fn – Address to the init function of the driver.

  • pm – Reference to struct pm_device associated with the device. (optional).

  • data – Pointer to the device’s private data.

  • config – The address to the structure containing the configuration information for this instance of the driver.

  • prio – The initialization level at which configuration occurs.

  • api – Provides an initial pointer to the API function struct used by the driver. Can be NULL.

  • mtu – Maximum transfer unit in bytes for this network interface.

ETH_NET_DEVICE_DT_INST_DEFINE(inst, ...)

Like ETH_NET_DEVICE_DT_DEFINE for an instance of a DT_DRV_COMPAT compatible.

Parameters:

  • inst – instance number. This is replaced by DT_DRV_COMPAT(inst) in the call to ETH_NET_DEVICE_DT_DEFINE.

  • ... – other parameters as expected by ETH_NET_DEVICE_DT_DEFINE.

Enums

enum ethernet_hw_caps

Ethernet hardware capabilities.

Values:

enumerator ETHERNET_HW_TX_CHKSUM_OFFLOAD = BIT(0)

TX Checksum offloading supported for all of IPv4, UDP, TCP.

enumerator ETHERNET_HW_RX_CHKSUM_OFFLOAD = BIT(1)

RX Checksum offloading supported for all of IPv4, UDP, TCP.

enumerator ETHERNET_HW_VLAN = BIT(2)

VLAN supported.

enumerator ETHERNET_AUTO_NEGOTIATION_SET = BIT(3)

Enabling/disabling auto negotiation supported.

10 Mbits link supported

100 Mbits link supported

1 Gbits link supported

enumerator ETHERNET_DUPLEX_SET = BIT(7)

Changing duplex (half/full) supported.

enumerator ETHERNET_PTP = BIT(8)

IEEE 802.1AS (gPTP) clock supported.

enumerator ETHERNET_QAV = BIT(9)

IEEE 802.1Qav (credit-based shaping) supported.

enumerator ETHERNET_PROMISC_MODE = BIT(10)

Promiscuous mode supported.

enumerator ETHERNET_PRIORITY_QUEUES = BIT(11)

Priority queues available.

enumerator ETHERNET_HW_FILTERING = BIT(12)

MAC address filtering supported.

enumerator ETHERNET_LLDP = BIT(13)

Link Layer Discovery Protocol supported.

enumerator ETHERNET_HW_VLAN_TAG_STRIP = BIT(14)

VLAN Tag stripping.

enumerator ETHERNET_DSA_SLAVE_PORT = BIT(15)

DSA switch.

enumerator ETHERNET_DSA_MASTER_PORT = BIT(16)
enumerator ETHERNET_QBV = BIT(17)

IEEE 802.1Qbv (scheduled traffic) supported.

enumerator ETHERNET_QBU = BIT(18)

IEEE 802.1Qbu (frame preemption) supported.

enumerator ETHERNET_TXTIME = BIT(19)

TXTIME supported.

enum ethernet_if_types

Types of Ethernet L2.

Values:

enumerator L2_ETH_IF_TYPE_ETHERNET

IEEE 802.3 Ethernet (default)

enumerator L2_ETH_IF_TYPE_WIFI

IEEE 802.11 Wi-Fi.

enum ethernet_flags

Values:

enumerator ETH_CARRIER_UP

Functions

void ethernet_init(struct net_if *iface)

Initialize Ethernet L2 stack for a given interface.

Parameters:

  • iface – A valid pointer to a network interface

void net_eth_ipv4_mcast_to_mac_addr(const struct in_addr *ipv4_addr, struct net_eth_addr *mac_addr)

Convert IPv4 multicast address to Ethernet address.

Parameters:

  • ipv4_addr – IPv4 multicast address

  • mac_addr – Output buffer for Ethernet address

void net_eth_ipv6_mcast_to_mac_addr(const struct in6_addr *ipv6_addr, struct net_eth_addr *mac_addr)

Convert IPv6 multicast address to Ethernet address.

Parameters:

  • ipv6_addr – IPv6 multicast address

  • mac_addr – Output buffer for Ethernet address

static inline enum ethernet_hw_caps net_eth_get_hw_capabilities(struct net_if *iface)

Return ethernet device hardware capability information.

Parameters:

  • iface – Network interface

Returns:

Hardware capabilities

static inline int net_eth_vlan_enable(struct net_if *iface, uint16_t tag)

Add VLAN tag to the interface.

Parameters:

  • iface – Interface to use.

  • tag – VLAN tag to add

Returns:

0 if ok, <0 if error

static inline int net_eth_vlan_disable(struct net_if *iface, uint16_t tag)

Remove VLAN tag from the interface.

Parameters:

  • iface – Interface to use.

  • tag – VLAN tag to remove

Returns:

0 if ok, <0 if error

static inline uint16_t net_eth_get_vlan_tag(struct net_if *iface)

Return VLAN tag specified to network interface.

Parameters:

  • iface – Network interface.

Returns:

VLAN tag for this interface or NET_VLAN_TAG_UNSPEC if VLAN is not configured for that interface.

static inline struct net_if *net_eth_get_vlan_iface(struct net_if *iface, uint16_t tag)

Return network interface related to this VLAN tag.

Parameters:

  • iface – Master network interface. This is used to get the pointer to ethernet L2 context

  • tag – VLAN tag

Returns:

Network interface related to this tag or NULL if no such interface exists.

static inline bool net_eth_is_vlan_enabled(struct ethernet_context *ctx, struct net_if *iface)

Check if VLAN is enabled for a specific network interface.

Parameters:

  • ctx – Ethernet context

  • iface – Network interface

Returns:

True if VLAN is enabled for this network interface, false if not.

static inline bool net_eth_get_vlan_status(struct net_if *iface)

Get VLAN status for a given network interface (enabled or not).

Parameters:

  • iface – Network interface

Returns:

True if VLAN is enabled for this network interface, false if not.

void net_eth_carrier_on(struct net_if *iface)

Inform ethernet L2 driver that ethernet carrier is detected.

This happens when cable is connected.

Parameters:

  • iface – Network interface

void net_eth_carrier_off(struct net_if *iface)

Inform ethernet L2 driver that ethernet carrier was lost.

This happens when cable is disconnected.

Parameters:

  • iface – Network interface

int net_eth_promisc_mode(struct net_if *iface, bool enable)

Set promiscuous mode either ON or OFF.

Parameters:

  • iface – Network interface

  • enable – on (true) or off (false)

Returns:

0 if mode set or unset was successful, <0 otherwise.

static inline const struct device *net_eth_get_ptp_clock(struct net_if *iface)

Return PTP clock that is tied to this ethernet network interface.

Parameters:

  • iface – Network interface

Returns:

Pointer to PTP clock if found, NULL if not found or if this ethernet interface does not support PTP.

const struct device *net_eth_get_ptp_clock_by_index(int index)

Return PTP clock that is tied to this ethernet network interface index.

Parameters:

  • index – Network interface index

Returns:

Pointer to PTP clock if found, NULL if not found or if this ethernet interface index does not support PTP.

static inline int net_eth_get_ptp_port(struct net_if *iface)

Return PTP port number attached to this interface.

Parameters:

  • iface – Network interface

Returns:

Port number, no such port if < 0

static inline void net_eth_set_ptp_port(struct net_if *iface, int port)

Set PTP port number attached to this interface.

Parameters:

  • iface – Network interface

  • port – Port number to set

static inline bool net_eth_type_is_wifi(struct net_if *iface)

Check if the Ethernet L2 network interface can perform Wi-Fi.

Parameters:

  • iface – Pointer to network interface

Returns:

True if interface supports Wi-Fi, False otherwise.

struct ethernet_qav_param
#include <ethernet.h>

Public Members

int queue_id

ID of the priority queue to use.

enum ethernet_qav_param_type type

Type of Qav parameter.

bool enabled

True if Qav is enabled for queue.

unsigned int delta_bandwidth

Delta Bandwidth (percentage of bandwidth)

unsigned int idle_slope

Idle Slope (bits per second)

unsigned int oper_idle_slope

Oper Idle Slope (bits per second)

unsigned int traffic_class

Traffic class the queue is bound to.

struct ethernet_qbv_param
#include <ethernet.h>

Public Members

int port_id

Port id.

enum ethernet_qbv_param_type type

Type of Qbv parameter.

enum ethernet_qbv_state_type state

What state (Admin/Oper) parameters are these.

bool enabled

True if Qbv is enabled or not.

bool gate_status[NET_TC_TX_COUNT]

True = open, False = closed.

enum ethernet_gate_state_operation operation

GateState operation.

uint32_t time_interval

Time interval ticks (nanoseconds)

uint16_t row

Gate control list row.

uint32_t gate_control_list_len

Number of entries in gate control list.

struct net_ptp_extended_time base_time

Base time.

struct net_ptp_time cycle_time

Cycle time.

uint32_t extension_time

Extension time (nanoseconds)

struct ethernet_qbu_param
#include <ethernet.h>

Public Members

int port_id

Port id.

enum ethernet_qbu_param_type type

Type of Qbu parameter.

uint32_t hold_advance

Hold advance (nanoseconds)

uint32_t release_advance

Release advance (nanoseconds)

enum ethernet_qbu_preempt_status frame_preempt_statuses[NET_TC_TX_COUNT]

sequence of framePreemptionAdminStatus values.

bool enabled

True if Qbu is enabled or not.

Link partner status (from Qbr)

uint8_t additional_fragment_size

Additional fragment size (from Qbr).

The minimum non-final fragment size is (additional_fragment_size + 1) * 64 octets

struct ethernet_filter
#include <ethernet.h>

Public Members

enum ethernet_filter_type type

Type of filter.

struct net_eth_addr mac_address

MAC address to filter.

bool set

Set (true) or unset (false) the filter.

struct ethernet_txtime_param
#include <ethernet.h>

Public Members

enum ethernet_txtime_param_type type

Type of TXTIME parameter.

int queue_id

Queue number for configuring TXTIME.

bool enable_txtime

Enable or disable TXTIME per queue.

struct ethernet_api
#include <ethernet.h>

Public Members

struct net_if_api iface_api

The net_if_api must be placed in first position in this struct so that we are compatible with network interface API.

int (*start)(const struct device *dev)

Start the device.

int (*stop)(const struct device *dev)

Stop the device.

enum ethernet_hw_caps (*get_capabilities)(const struct device *dev)

Get the device capabilities.

int (*set_config)(const struct device *dev, enum ethernet_config_type type, const struct ethernet_config *config)

Set specific hardware configuration.

int (*get_config)(const struct device *dev, enum ethernet_config_type type, struct ethernet_config *config)

Get hardware specific configuration.

int (*send)(const struct device *dev, struct net_pkt *pkt)

Send a network packet.

struct ethernet_context
#include <ethernet.h>

Ethernet L2 context that is needed for VLAN.

Public Members

atomic_t flags

Flags representing ethernet state, which are accessed from multiple threads.

struct k_work carrier_work

Carrier ON/OFF handler worker.

This is used to create network interface UP/DOWN event when ethernet L2 driver notices carrier ON/OFF situation. We must not create another network management event from inside management handler thus we use worker thread to trigger the UP/DOWN event.

struct net_if *iface

Network interface.

enum net_l2_flags ethernet_l2_flags

This tells what L2 features does ethernet support.

bool is_net_carrier_up

Is network carrier up.

bool is_init

Is this context already initialized.

enum ethernet_if_types eth_if_type

Types of Ethernet network interfaces.

group ethernet_mii

Ethernet MII (media independent interface) functions.

Defines

MII_BMCR

Basic Mode Control Register.

MII_BMSR

Basic Mode Status Register.

MII_PHYID1R

PHY ID 1 Register.

MII_PHYID2R

PHY ID 2 Register.

MII_ANAR

Auto-Negotiation Advertisement Register.

MII_ANLPAR

Auto-Negotiation Link Partner Ability Reg.

MII_ANER

Auto-Negotiation Expansion Register.

MII_ANNPTR

Auto-Negotiation Next Page Transmit Register.

MII_ANLPRNPR

Auto-Negotiation Link Partner Received Next Page Reg.

MII_1KTCR

1000BASE-T Control Register

MII_1KSTSR

1000BASE-T Status Register

MII_MMD_ACR

MMD Access Control Register.

MII_MMD_AADR

MMD Access Address Data Register.

MII_ESTAT

Extended Status Register.

MII_BMCR_RESET

PHY reset.

MII_BMCR_LOOPBACK

enable loopback mode

MII_BMCR_SPEED_LSB

10=1000Mbps 01=100Mbps; 00=10Mbps

MII_BMCR_AUTONEG_ENABLE

Auto-Negotiation enable.

MII_BMCR_POWER_DOWN

power down mode

MII_BMCR_ISOLATE

isolate electrically PHY from MII

MII_BMCR_AUTONEG_RESTART

restart auto-negotiation

MII_BMCR_DUPLEX_MODE

full duplex mode

MII_BMCR_SPEED_MSB

10=1000Mbps 01=100Mbps; 00=10Mbps

MII_BMCR_SPEED_MASK

Link Speed Field.

MII_BMCR_SPEED_10

select speed 10 Mb/s

MII_BMCR_SPEED_100

select speed 100 Mb/s

MII_BMCR_SPEED_1000

select speed 1000 Mb/s

MII_BMSR_100BASE_T4

100BASE-T4 capable

MII_BMSR_100BASE_X_FULL

100BASE-X full duplex capable

MII_BMSR_100BASE_X_HALF

100BASE-X half duplex capable

MII_BMSR_10_FULL

10 Mb/s full duplex capable

MII_BMSR_10_HALF

10 Mb/s half duplex capable

MII_BMSR_100BASE_T2_FULL

100BASE-T2 full duplex capable

MII_BMSR_100BASE_T2_HALF

100BASE-T2 half duplex capable

MII_BMSR_EXTEND_STATUS

extend status information in reg 15

MII_BMSR_MF_PREAMB_SUPPR

PHY accepts management frames with preamble suppressed.

MII_BMSR_AUTONEG_COMPLETE

Auto-negotiation process completed.

MII_BMSR_REMOTE_FAULT

remote fault detected

MII_BMSR_AUTONEG_ABILITY

PHY is able to perform Auto-Negotiation.

link is up

MII_BMSR_JABBER_DETECT

jabber condition detected

MII_BMSR_EXTEND_CAPAB

extended register capabilities

MII_ADVERTISE_NEXT_PAGE

next page

MII_ADVERTISE_LPACK

link partner acknowledge response

MII_ADVERTISE_REMOTE_FAULT

remote fault

MII_ADVERTISE_ASYM_PAUSE

try for asymmetric pause

MII_ADVERTISE_PAUSE

try for pause

MII_ADVERTISE_100BASE_T4

try for 100BASE-T4 support

MII_ADVERTISE_100_FULL

try for 100BASE-X full duplex support

MII_ADVERTISE_100_HALF

try for 100BASE-X support

MII_ADVERTISE_10_FULL

try for 10 Mb/s full duplex support

MII_ADVERTISE_10_HALF

try for 10 Mb/s half duplex support

MII_ADVERTISE_SEL_MASK

Selector Field.

MII_ADVERTISE_SEL_IEEE_802_3
MII_ADVERTISE_1000_FULL

try for 1000BASE-T full duplex support

MII_ADVERTISE_1000_HALF

try for 1000BASE-T half duplex support

MII_ADVERTISE_ALL
MII_ESTAT_1000BASE_X_FULL

1000BASE-X full-duplex capable

MII_ESTAT_1000BASE_X_HALF

1000BASE-X half-duplex capable

MII_ESTAT_1000BASE_T_FULL

1000BASE-T full-duplex capable

MII_ESTAT_1000BASE_T_HALF

1000BASE-T half-duplex capable