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:

10, 100 and 1000 Mbit/sec links
Auto negotiation
Half/full duplex
Promiscuous mode
TX and RX checksum offloading
MAC address filtering
Virtual LANs
Priority queues
IEEE 802.1AS (gPTP)
IEEE 802.1Qav (credit based shaping)
LLDP (Link Layer Discovery Protocol)

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 

Related code samples

Inter-VM Shared Memory (ivshmem) Ethernet: Communicate with another "cell" in the Jailhouse hypervisor using IVSHMEM Ethernet.
Packet socket: Use raw packet sockets over Ethernet.
UDP sender using SO_TXTIME: Control the transmission time of a packet using SO_TXTIME socket option.

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.

enumerator ETHERNET_LINK_10BASE_T = BIT(4): 10 Mbits link supported

enumerator ETHERNET_LINK_100BASE_T = BIT(5): 100 Mbits link supported

enumerator ETHERNET_LINK_1000BASE_T = BIT(6): 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.

enumerator ETHERNET_TXINJECTION_MODE = BIT(20): TX-Injection 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.

int net_eth_txinjection_mode(struct net_if *iface, bool enable)

Set TX-Injection 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_t1s_param

#include <ethernet.h>

Public Members

enum ethernet_t1s_param_type type: Type of T1S parameter.

bool enable: T1S PLCA enabled.

uint8_t node_id: T1S PLCA node id range: 0 to 254.

uint8_t node_count: T1S PLCA node count range: 1 to 255.

uint8_t burst_count: T1S PLCA burst count range: 0x0 to 0xFF.

uint8_t burst_timer: T1S PLCA burst timer.

uint8_t to_timer: T1S PLCA TO value.

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.

bool link_partner_status: 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.

MII_BMSR_LINK_STATUS: 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

Ethernet

Overview

API Reference

Overview 

API Reference 