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
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
-
NET_ETH_ADDR_LEN
Ethernet MAC address length.
-
NET_ETH_MINIMAL_FRAME_SIZE
Minimum Ethernet frame size.
-
NET_ETH_MTU
Ethernet MTU size.
-
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_INIT_INSTANCE(dev_id, name, instance, init_fn, pm, data, config, prio, api, mtu)
Create multiple Ethernet network interfaces and bind them to network devices.
If your network device needs more than one instance of a network interface, use this macro below and provide a different instance suffix each time (0, 1, 2, … or a, b, c … whatever works for you)
- Parameters:
dev_id – Network device id.
name – The name this instance of the driver exposes to the system.
instance – Instance 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_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_TX_CHKSUM_OFFLOAD = BIT(0)
-
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.
-
enumerator L2_ETH_IF_TYPE_ETHERNET
-
enum ethernet_checksum_support
Protocols that are supported by checksum offloading.
Values:
-
enumerator ETHERNET_CHECKSUM_SUPPORT_NONE = NET_IF_CHECKSUM_NONE_BIT
Device does not support any L3/L4 checksum offloading.
-
enumerator ETHERNET_CHECKSUM_SUPPORT_IPV4_HEADER = NET_IF_CHECKSUM_IPV4_HEADER_BIT
Device supports checksum offloading for the IPv4 header.
-
enumerator ETHERNET_CHECKSUM_SUPPORT_IPV4_ICMP = NET_IF_CHECKSUM_IPV4_ICMP_BIT
Device supports checksum offloading for ICMPv4 payload (implies IPv4 header)
-
enumerator ETHERNET_CHECKSUM_SUPPORT_IPV6_HEADER = NET_IF_CHECKSUM_IPV6_HEADER_BIT
Device supports checksum offloading for the IPv6 header.
-
enumerator ETHERNET_CHECKSUM_SUPPORT_IPV6_ICMP = NET_IF_CHECKSUM_IPV6_ICMP_BIT
Device supports checksum offloading for ICMPv6 payload (implies IPv6 header)
-
enumerator ETHERNET_CHECKSUM_SUPPORT_TCP = NET_IF_CHECKSUM_TCP_BIT
Device supports TCP checksum offloading for all supported IP protocols.
-
enumerator ETHERNET_CHECKSUM_SUPPORT_UDP = NET_IF_CHECKSUM_UDP_BIT
Device supports UDP checksum offloading for all supported IP protocols.
-
enumerator ETHERNET_CHECKSUM_SUPPORT_NONE = NET_IF_CHECKSUM_NONE_BIT
Functions
-
static inline bool net_eth_is_addr_broadcast(struct net_eth_addr *addr)
Check if the Ethernet MAC address is a broadcast address.
- Parameters:
addr – A valid pointer to a Ethernet MAC address.
- Returns:
true if address is a broadcast address, false if not
-
static inline bool net_eth_is_addr_all_zeroes(struct net_eth_addr *addr)
Check if the Ethernet MAC address is a all zeroes address.
- Parameters:
addr – A valid pointer to an Ethernet MAC address.
- Returns:
true if address is an all zeroes address, false if not
-
static inline bool net_eth_is_addr_unspecified(struct net_eth_addr *addr)
Check if the Ethernet MAC address is unspecified.
- Parameters:
addr – A valid pointer to a Ethernet MAC address.
- Returns:
true if address is unspecified, false if not
-
static inline bool net_eth_is_addr_multicast(struct net_eth_addr *addr)
Check if the Ethernet MAC address is a multicast address.
- Parameters:
addr – A valid pointer to a Ethernet MAC address.
- Returns:
true if address is a multicast address, false if not
-
static inline bool net_eth_is_addr_group(struct net_eth_addr *addr)
Check if the Ethernet MAC address is a group address.
- Parameters:
addr – A valid pointer to a Ethernet MAC address.
- Returns:
true if address is a group address, false if not
-
static inline bool net_eth_is_addr_valid(struct net_eth_addr *addr)
Check if the Ethernet MAC address is valid.
- Parameters:
addr – A valid pointer to a Ethernet MAC address.
- Returns:
true if address is valid, false if not
-
static inline bool net_eth_is_addr_lldp_multicast(struct net_eth_addr *addr)
Check if the Ethernet MAC address is a LLDP multicast address.
- Parameters:
addr – A valid pointer to a Ethernet MAC address.
- Returns:
true if address is a LLDP multicast address, false if not
-
static inline bool net_eth_is_addr_ptp_multicast(struct net_eth_addr *addr)
Check if the Ethernet MAC address is a PTP multicast address.
- Parameters:
addr – A valid pointer to a Ethernet MAC address.
- Returns:
true if address is a PTP multicast address, false if not
-
const struct net_eth_addr *net_eth_broadcast_addr(void)
Return Ethernet broadcast address.
- Returns:
Ethernet broadcast address.
-
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_get_hw_config(struct net_if *iface, enum ethernet_config_type type, struct ethernet_config *config)
Return ethernet device hardware configuration information.
- Parameters:
iface – Network interface
type – configuration type
config – Ethernet configuration
- Returns:
0 if ok, <0 if error
-
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.
Note that the interface parameter must be the VLAN interface, and not the Ethernet one.
- Parameters:
iface – VLAN 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 – Main network interface (not the VLAN one).
tag – VLAN tag
- Returns:
Network interface related to this tag or NULL if no such interface exists.
-
static inline struct net_if *net_eth_get_vlan_main(struct net_if *iface)
Return main network interface that is attached to this VLAN tag.
- Parameters:
iface – VLAN network interface. This is used to get the pointer to ethernet L2 context
- 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 there are any VLAN interfaces enabled to this specific Ethernet network interface.
Note that the iface must be the actual Ethernet interface and not the virtual VLAN interface.
- Parameters:
ctx – Ethernet context
iface – Ethernet network interface
- Returns:
True if there are enabled VLANs 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.
-
static inline bool net_eth_is_vlan_interface(struct net_if *iface)
Check if the given interface is a VLAN interface.
- Parameters:
iface – Network interface
- Returns:
True if this network interface is VLAN one, 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.
-
int net_eth_mac_filter(struct net_if *iface, struct net_eth_addr *mac, enum ethernet_filter_type type, bool enable)
Set or unset HW filtering for MAC address
mac
.- Parameters:
iface – Network interface
mac – Pointer to an ethernet MAC address
type – Filter type, either source or destination
enable – Set (true) or unset (false)
- Returns:
0 if filter 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
-
struct net_eth_addr
- #include <ethernet.h>
Ethernet address.
Public Members
-
uint8_t addr[6U]
Buffer storing the address.
-
uint8_t addr[6U]
-
struct ethernet_t1s_param
- #include <ethernet.h>
Ethernet T1S specific parameters.
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_t1s_param.[anonymous].[anonymous] plca
PLCA is the Physical Layer (PHY) Collision Avoidance technique employed with multidrop 10Base-T1S standard.
The PLCA parameters are described in standard [1] as registers in memory map 4 (MMS = 4) (point 9.6).
IDVER (PLCA ID Version) CTRL0 (PLCA Control 0) CTRL1 (PLCA Control 1) STATUS (PLCA Status) TOTMR (PLCA TO Control) BURST (PLCA Burst Control)
Those registers are implemented by each OA TC6 compliant vendor (like for e.g. LAN865x - e.g. [2]).
Documents: [1] - “OPEN Alliance 10BASE-T1x MAC-PHY Serial
Interface” (ver. 1.1) [2] - “DS60001734C” - LAN865x data sheet
-
enum ethernet_t1s_param_type type
-
struct ethernet_qav_param
- #include <ethernet.h>
Ethernet Qav specific parameters.
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.
-
int queue_id
-
struct ethernet_qbv_param
- #include <ethernet.h>
Ethernet Qbv specific parameters.
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.
-
struct ethernet_qbv_param.[anonymous].[anonymous] gate_control
Gate control information.
-
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)
-
int port_id
-
struct ethernet_qbu_param
- #include <ethernet.h>
Ethernet Qbu specific parameters.
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
-
int port_id
-
struct ethernet_filter
- #include <ethernet.h>
Ethernet filter description.
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.
-
enum ethernet_filter_type type
-
struct ethernet_txtime_param
- #include <ethernet.h>
Ethernet TXTIME specific parameters.
-
struct ethernet_api
- #include <ethernet.h>
Ethernet L2 API operations.
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)
Collect optional ethernet specific statistics.
This pointer should be set by driver if statistics needs to be collected for that driver. Start 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)
The IP stack will call this function when a VLAN tag is enabled or disabled.
If enable is set to true, then the VLAN tag was added, if it is false then the tag was removed. The driver can utilize this information if needed. Return ptp_clock device that is tied to this ethernet device Send a network packet
-
struct net_if_api iface_api
-
struct ethernet_lldp
- #include <ethernet.h>
Ethernet LLDP specific parameters.
Public Members
-
sys_snode_t node
Used for track timers.
-
const struct net_lldpdu *lldpdu
LLDP Data Unit mandatory TLVs for the interface.
-
const uint8_t *optional_du
LLDP Data Unit optional TLVs for the interface.
-
size_t optional_len
Length of the optional Data Unit TLVs.
-
int64_t tx_timer_start
LLDP TX timer start time.
-
uint32_t tx_timer_timeout
LLDP TX timeout.
-
net_lldp_recv_cb_t cb
LLDP RX callback function.
-
sys_snode_t node
-
NET_ETH_ADDR_LEN
- 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 Mask.
-
MII_ADVERTISE_SEL_IEEE_802_3
Selector Field.
-
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
Advertise all speeds.
-
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
-
MII_BMCR