This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

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_name, drv_name, init_fn, pm_control_fn, data, cfg, prio, api, mtu)

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

Parameters

  • dev_name – Network device name.

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

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

  • pm_control_fn – Pointer to pm_control function. Can be NULL if not implemented.

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

  • cfg – 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_control_fn, data, cfg, 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_control_fn – Pointer to pm_control function. Can be NULL if not implemented.

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

  • cfg – 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_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_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 gPTP port number attached to this interface.

Parameters

  • iface – Network interface

Returns

Port number, no such port if < 0

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

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_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_ALL