Ethernet

---

This chapter describes common information and instructions of Ethernet on IoT Yocto, such as command to configure DHCP or static IP and so on.

But Ethernet on different platforms may have some platform-specific instructions or test results. For example, you will get different throughput on different platforms.

---

Important

In releases v21.3 to v23.0, IoT Yocto uses systemd-networkd to manage network settings in the Yocto Linux, including MAC addresses. However, starting from version v23.1 and in subsequent versions, IoT Yocto will disable systemd-networkd by default. Instead, it will set NetworkManager as the default networking management tool, aligning with modern management methods used in Linux distributions such as Ubuntu.

Change the MAC Address

Note

Current IoT Yocto does not support changing permanent MAC address with ethtool.

Change MAC Address in U-Boot and Pass It to Linux

IoT Yocto supports storing the MAC address in the U-Boot environment variable ethaddr and passing it to Linux. The aliases node for assigning ethernet0 = ð will help to acquire the value stored in U-Boot environment variable ethaddr. There are three methods to modify the MAC address of the onboard eth0. These methods may also deal with MAC address issues for mass production.

1. Developer can use genio-flash to flash the MAC address of eth0 to U-Boot environment partition.

   Note

   To use this feature, genio-tools version greater than 1.3 is necessary. To upgrade genio-tools to the latest version, you can use the command pip install --upgrade genio-tools.

   You can do so by adding a line to set the ethaddr variable in the plain text file u-boot-initial-env. Take Genio 700-EVK as an example:

   boot_conf=#conf-mediatek_genio-700-evk.dtb#conf-gpu-mali.dtbo#conf-video.dtbo
   list_dtbo= gpu-mali.dtbo video.dtbo
   storage=mmc
   storage_dev=0
   boot_scripts=fitImage
   boot_targets=embedded
   ethaddr=00:11:22:33:44:55
   

   Save the file and run genio-flash. The flash tool converts the u-boot-initial-env file into binary representations and update the mmc0boot1 partition.

   In the example above we use the Media Access Control (MAC) address 00:11:22:33:44:55. You should update this to reflect the allocated MAC addresses for each board before launching the genio-flash program. Developer could also use a single line command to set MAC address with -e ethaddr=XX:XX:XX:XX:XX:XX parameter.

   genio-flash -e ethaddr=00:11:22:33:44:55 bootloaders mmc0boot1
   

2. Developer can use fw_setenv to modify MAC address under Linux shell in IoT Yocto.

   fw_setenv ethaddr 00:11:22:33:44:55
   

3. If a developer attempts to modify the ethaddr in the U-Boot prompt, it might fail because ethaddr is a vendor-specific environment variable. However, if you still wish to modify it in the U-Boot prompt, you can enable the CONFIG_ENV_OVERWRITE setting in the defconfig file for your project. After making this change, you will need to rebuild and replace the fip.bin file. This process allows the environment variables to be overwritten, thus enabling the modification of ethaddr. However, please don’t enable this setting in mass production for better security approaches.

   setenv ethaddr 00:11:22:33:44:55
   saveenv
   

4. Some platforms do not support Ethernet driver in U-Boot yet. Instead, they use a USB Remote Network Driver Interface Specification (RNDIS) gadget as the Ethernet device. If ethaddr is not pre-configured, the MAC address will default to de:ad:be:ef:00:01. Consequently, this MAC address will be passed to Linux. To use a different MAC address, set ethaddr in U-Boot or use the genio-flash tool with the command.

   Platforms do not support Ethernet driver in U-Boot yet:

   • Genio 350-EVK

5. Some platforms support the Ethernet driver in U-Boot. However, it will not function by default without a configured MAC address. To use Ethernet in U-Boot, the developer must set the ethaddr parameter. If ethaddr is not set, Linux will not be able to retrieve it from U-Boot and will use a default MAC address.

   Important

   The onboard Ethernet on some platforms requires ethaddr to probe correctly, otherwise a mtk_power_domain error will appear.

6. If you want to use USB Remote Network Driver Interface Specification (RNDIS) Gadget Ethernet and you have enabled the onboard Ethernet driver, you must set both variables in the u-boot configuration:

   • ethaddr for onboard Ethernet

   • eth1addr for USB RNDIS Gadget Ethernet

Note

It is recommended to always configure the -e ethaddr parameter during flashing.

Using CONFIG_NET_RANDOM_ETHADDR may consume available DHCP IP addresses on the network.

Using Random MAC Address

If you wish to use a random MAC address, you can configure CONFIG_NET_RANDOM_ETHADDR=y in the U-Boot defconfig for the Genio 1200-EVK platform. This will ensure that U-Boot assigns a random MAC address at each boot if ethaddr is not configured.

Note

The USB RNDIS gadget does not support CONFIG_NET_RANDOM_ETHADDR. Random MAC address cannot work on these platforms using USB RNDIS gadget in U-Boot.

Summary of the Ethernet Driver for Genio Boards

		Genio 350-EVK	Genio 1200-EVK	Genio 700-EVK	Genio 510-EVK	Genio 720-EVK	Genio 520-EVK
U-Boot	USB RNDIS Gadget Ethernet	Supported	Supported	Supported	Supported	N/A	N/A
	On Board Ethernet	N/A	DWMAC	DWMAC	DWMAC	DWMAC	DWMAC
Linux	USB RNDIS Gadget Ethernet	Supported	DWMAC	Supported	Supported	Supported	Supported
	On Board Ethernet	STAR	DWMAC	DWMAC	DWMAC	DWMAC	DWMAC

Change MAC Address in Linux with systemd-networkd

Note

This approach is considered legacy for IoT Yocto releases v21.3 to v23.0. Starting from version v23.1, this method will no longer enabled by default because IoT Yocto has set NetworkManager as the default networking management tool.

IoT Yocto v21.3 and later release uses systemd to manage network settings in Linux OS, including MAC addresses. By default, systemd generates a temporary MAC address for the Ethernet interface with following steps:

• First, systemd generates a unique machine-id and store it in /etc/machine-id during boot up after whole image has been flashed.

• Then, systemd uses this machine-id to calculate a unique MAC address.

• After that, the unique MAC address will be applied to Ethernet driver. This is a kind of temporary MAC address which is calculated each time during system boot up.

To change the temporary MAC address and store it in the file system, please follow these steps:

• Create a file /etc/systemd/network/20-end0.network. systemd will use the setting in this file to override the generated address.

• Edit the configuration file and insert the following configurations:

  [Match]
  Name=end0
  
  [Link]
  MACAddress=16:55:61:43:11:22
  

  Note

  This approach is considered legacy for IoT Yocto releases v21.3 to v23.0. Starting from version v23.1, this method will no longer work because IoT Yocto has set NetworkManager as the default networking management tool.

Please replace the example MAC address 16:55:61:43:11:22 to the MAC address that you needed.

Important

Starting from IoT Yocto release v25.0, the Ethernet interface name has been changed from eth0 to end0 in the Linux OS. This change is due to the adoption of Predictable Network Interface Names (PNIN) implemented by Systemd and Udev in modern Linux systems. While some configurations maintain backward compatibility allowing the use of both eth0 and end0, certain configurations specifically require the use of end0 as the interface name.

You can verify this interface renaming in the dmesg output:

dwmac-mediatek 1101a000.ethernet end0: renamed from eth0

Throughout this document, eth0 will be replaced with end0 where applicable for Linux OS operations.

Systemd-Networkd vs NetworkManager

A Linux system with both systemd-networkd and NetworkManager installed would have two different network management services. NetworkManager is a more widely used and user-friendly service for managing network connections. On the other hand, systemd-networkd is a system daemon that manages network connections in the background and is typically used in headless servers or devices without a graphical user interface.

However, it is recommended to only use one service at a time to avoid conflicts and ensure proper network configuration.

• The rity-bringup-image meta layer only has systemd-networkd.

• The rity-demo-image meta layer has both systemd-networkd and NetworkManager installed.

Systemd-Networkd

Enable or Disable Systemd-Networkd

If you want to use another network management service, it’s good to know how to enable and disable the systemd-networkd service. You need to stop systemd-networkd prior to disable it.

systemctl stop systemd-networkd
systemctl disable systemd-networkd

If you want to switch back systemd-networkd, simply enable and then start the service.

systemctl enable systemd-networkd
systemctl start systemd-networkd

Configure Static IP with systemd-networkd

The system enables Dynamic Host Configuration Protocol (DHCP) by default with systemd-networkd. If static IP is required, use /etc/systemd/network/20-end0.network to modify connection setting. For example, set IP 192.168.0.1 and netmask 255.255.255.0 with default gateway 192.168.0.254 to interface end0. After that, reload systemd-networkd via systemctl.

[Match]
Name=end0

[Network]
Address=192.168.0.1/24
Gateway=192.168.0.254
DNS=8.8.8.8

NetworkManager

Enable or Disable NetworkManager

If you want to use another network management service, it’s good to know how to enable and disable the NetworkManager service. You need to stop NetworkManager prior to disable it.

systemctl stop NetworkManager
systemctl disable NetworkManager

If you want to switch back NetworkManager, simply enable and then start the service.

systemctl enable NetworkManager
systemctl start NetworkManager

Check the Status of NetworkManager

Use systemctl to check if the NetworkManager is still running.

systemctl status NetworkManager

Check the output line which contains Active: for the status of NetworkManager. For example, the output shows NetworkManager is running.

active (running)

The other output show the service has been stopped.

inactive (dead)

The system stores the NetworkManager service configuration in /etc/systemd/system/multi-user.target.wants/NetworkManager.service. You can check this file if any customization is required for this service.

Control Network Settings via NetworkManager

Note

We will usually suggest customer to disable systemd-networkd before configuring NetworkManager. Other service like avahi-daemon or dhcpcd will also affect network configurations.

The system enables NetworkManager by default. systemd registers this service as NetworkManager.service (also known as NetworkManager). Use the Network Manager Command Line Interface (nmcli) tool to control NetworkManager. User could use nmcli to check connections managed by NetworkManager.

nmcli -p connection show

You should see the following output if you’ve never touched network setting.

======================================
  NetworkManager connection profiles
======================================
NAME                UUID                                  TYPE      DEVICE
------------------------------------------------------------------------------->
Wired connection 1  4080d986-b3c7-3601-a837-3ca6ee6b2ab2  ethernet  end0

Control Network Settings via Tool NMCLI

nmcli is the tool for configuring and controlling each network interface managed by NetworkManager. nmcli can enable or disable the network while keeps NetworkManager alive. You can set the following commands to enable or disable networking controlled by NetworkManager. All interfaces managed by NetworkManager are deactivated when networking is disabled. For more detail, you can check the online manual of nmcli: https://developer-old.gnome.org/NetworkManager/stable/nmcli.html

nmcli networking off
nmcli networking on

Configure Static IP with NetworkManager

NetworkManager enables Dynamic Host Configuration Protocol (DHCP) by default. To configure a static IP address, use nmcli to modify the connection settings. For example, set IP 192.168.0.1 and netmask 255.255.255.0 with default gateway 192.168.0.254 to "Wired connection 1" (end0). After that, reload NetworkManager via systemctl.

nmcli con mod "Wired connection 1" ip4 "192.168.0.1/24" gw4 192.168.0.254
systemctl reload NetworkManager

Use ip a to check if the static IP has been applied.

ip a

2: end0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 92:b2:7c:21:08:2d brd ff:ff:ff:ff:ff:ff
    inet 192.168.0.1/24 brd 192.168.0.255 scope global noprefixroute end0
        valid_lft forever preferred_lft forever
    inet6 fe80::3154:c53:c5e5:6d6f/64 scope link noprefixroute
        valid_lft forever preferred_lft forever

Check the new configuration has been stored in file /etc/NetworkManager/system-connections/Wired connection 1.nmconnection

cat /etc/NetworkManager/system-connections/Wired\ connection\ 1.nmconnection

It should show the new IP value is assigned to variable address1.

[ipv4]
    address1=192.168.0.1/24,192.168.0.1

Avoiding Wrong Network Settings Affected by Other Modules

Note

If you have activated dhcpcd on the system (for example, when configuring the board as a wireless router), configure the static IP for end0 in /etc/dhcpcd.conf. Please run systemctl restart dhcpcd after new configuration has been applied.

interface end0
static ip_address = 192.168.0.1/24
static router = 192.168.0.254
static domain_name_server = 8.8.8.8

Note

If avahi-daemon is activate on the system, disable end0 from avahi-daemon. Add the following line in /etc/avahi/avahi-daemon.conf

deny-interfaces=end0

Please run systemctl reload avahi-daemon after new configuration has been applied.

Time-Sensitive Networking (TSN)

Time-Sensitive Networking (TSN) is a set of standards that the Time-Sensitive Networking task group of the Institute of Electrical and Electronics Engineers (IEEE) 802.1 working group developed. These standards provide deterministic real-time communication over Ethernet. TSN uses time synchronization to schedule traffic and eliminate collisions on the network. This ensures timely and reliable communication between all devices on a TSN network.

To use TSN, your devices must support the TSN standards and be configured to use them. This typically involves setting up your devices to synchronize their clocks with a network-wide time source, configuring the network’s schedule, and setting up the network’s Quality of Service (QoS) settings to prioritize time-sensitive traffic.

IoT Yocto supports TSN on the Genio 510, Genio 700 and Genio 1200 series. This means that devices built with these platforms can be part of a TSN network and take advantage of the benefits that TSN provides. To use TSN on a device built with the MediaTek Genio platform, you would typically need to use the platform’s software tools to configure the device’s network settings and enable TSN.

Meta layer meta-mediatek-tsn in IoT Yocto supports most of the TSN software components you need. Kernel configurations are enabled in file src/meta-mediatek-bsp/recipes-kernel/linux/linux-mtk/tsn.cfg in IoT Yocto source code. These features are enabled by default with rity-demo-image.

Note

For the testing procedures and user guide for the TSN feature, please refer to Genio 700/1200 TSN Evaluation Guide for details.

Wake on LAN (WoL)

Important

Wake-on-LAN will affect the precision of Time-Sensitive Networking (TSN) feature. If you want to use the TSN feature, you should not use WoL.

Wake-on-LAN (WoL) is a networking standard that enables network messages to turn on or wake up computers from a low-power state. This feature is particularly useful for remote management and control of devices, allowing administrators to power on devices without physical access.

IoT Yocto provides Wake-on-LAN support for the Genio 510, Genio 700 and Genio 1200 series. Network messages can wake up devices built with these platforms from a low-power state. To use Wake-on-LAN on a device built with the MediaTek Genio platform, you would typically need to use ethtool to configure the device’s network settings and enable Wake-on-LAN. The platforms currently support two methods for awakening: via a “magic packet” or a “unicast packet”.

Magic Packet

In this mode, the system sends a specially designed “magic packet” over the network. You can broadcast the magic packet across the entire network, and it will wake up any computer that has WoL enabled and matches the target MAC address. This mode helps you wake up specific computers on the network.

On Genio EVK, to use Magic Packet mode with ethtool, you can use the following command:

ethtool -s end0 wol g
echo mem > /sys/power/state

In this command, end0 is the name of your network interface, and g enables Wake-on-LAN using magic packet. The second command suspends the system.

On remote PC, for Windows users, you can use tools like WakeMeOnLan and WakeOnLanX to send a magic packet to wake up a device.

For Linux users, you can use the wakeonlan or etherwake tool, which can be installed with the following command:

sudo apt-get install wakeonlan
wakeonlan 00:11:22:33:44:55

sudo apt-get install etherwake
etherwake -i end0 00:11:22:33:44:55

Unicast Packet

In this mode, the system sends a unicast packet directly to a specific computer on the network. Unlike broadcasting a magic packet to all computers, unicast targets a single specific destination. This mode helps you wake up specific computers without network-wide broadcasts.

To enable Wake-on-LAN in unicast mode, you can use the following command:

ethtool -s end0 wol u
echo mem > /sys/power/state

In the first command, end0 is the name of your network interface, and u enables Wake-on-LAN using magic packet. The second command suspends the system.

The following commands are an example to wake up EVK from a remote Linux PC via ping as the unicast packet:

First refresh ARP records on remote PC.

sudo arp -i enp0s31f6 -s 192.168.1.2 00:11:22:33:44:55
arp -a

ARP has been refreshed.

? (192.168.1.2) at 00:11:22:33:44:55 [ether] PERM on enp0s31f6
...

Now send the unicast packet via ping.

ping 192.168.1.2

You’ll see the EVK will resume.

PING 192.168.1.2 (192.168.1.2) 56(84) bytes of data.
64 bytes from 192.168.1.2: icmp_seq=8 ttl=64 time=0.707 ms

Note

Remember, the Address Resolution Protocol (ARP) has a limited lifetime. When using ping as an unicast packet to wake up EVK, if a device can’t be awakened after a long time, it’s normal. You might need to refresh ARP records on the remote PC. User may send unicast packets using a packet sending instrument, instead of using the ping method, or use other tools that can send unicast packets. When constructing a unicast packet, the destination MAC address needs to be the MAC address of the platform to be awakened.

Reference Boards

Ethernet on different platforms may have some platform-specific instructions or test results. For example, you will get different benchmark results on different platforms. Please find more details about difference of Ethernet on each platform:

• Genio 350-EVK Ethernet.

• Genio 510/700-EVK Ethernet.

• Genio 1200-EVK Ethernet.

• Genio 520/720-EVK Ethernet.