.. include:: /keyword.rst

========
Ethernet
========

.. contents:: Sections
    :local:
    :depth: 2

.. toctree::
    :hidden:

    Genio 350-EVK <ethernet-350-evk>
    Genio 510/700-EVK <ethernet-700-evk>
    Genio 520/720-EVK <ethernet-720-evk>
    Genio 1200-EVK <ethernet-1200-evk>

--------------------------------

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 = &eth;`` 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 |G700-EVK| as an example:

    .. code-block:: ini
        :emphasize-lines: 7

        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.

    .. prompt:: bash

        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|.

    .. prompt:: bash

        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.

    .. prompt:: bash =>

        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:

    - |G350-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 |G1200-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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    +--------+-------------------------+----------+-----------+----------+----------+----------+----------+
    |        |                         ||G350-EVK|||G1200-EVK|||G700-EVK|||G510-EVK|||G720-EVK|||G520-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:

    .. code:: text

        [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.

   .. prompt:: bash

        systemctl stop systemd-networkd
        systemctl disable systemd-networkd

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

   .. prompt:: bash

        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``.

    .. code:: text

        [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.

   .. prompt:: bash

        systemctl stop NetworkManager
        systemctl disable NetworkManager

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

   .. prompt:: bash

        systemctl enable NetworkManager
        systemctl start NetworkManager

Check the Status of NetworkManager
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use ``systemctl`` to check if the ``NetworkManager`` is still running.

   .. prompt:: bash

        systemctl status NetworkManager

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

   .. code:: text

        active (running)

The other output show the service has been stopped.

   .. code:: text

        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``.

   .. prompt:: bash

        nmcli -p connection show

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

   .. code:: text

     ======================================
       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

   .. prompt:: bash

        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``.

   .. prompt:: bash

        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.

   .. prompt:: bash

        ip a

   .. code:: text

        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``

   .. prompt:: bash

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

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

   .. code:: text

        [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.

       .. code:: text

            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``

       .. code:: text

            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
    :download:`Genio 700/1200 TSN Evaluation Guide </sw/yocto/app-dev/ethernet/MTK_Genio 700 &1200_TSN_Evaluation_Guide_v1.6.pdf>` 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:

   .. prompt:: bash

        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 <https://www.nirsoft.net/utils/wake_on_lan.html>`_ and
`WakeOnLanX <https://wakeonlanx.com/wake-on-lan-with-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:

   .. prompt:: bash

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

   .. prompt:: bash

        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:

   .. prompt:: bash

        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.

    .. prompt:: bash

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

ARP has been refreshed.

    .. prompt:: text

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

Now send the unicast packet via ``ping``.

    .. prompt:: bash

        ping 192.168.1.2

You'll see the EVK will resume.

    .. prompt:: text

        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:

- :doc:`Genio 350-EVK Ethernet </sw/yocto/app-dev/ethernet/ethernet-350-evk>`.
- :doc:`Genio 510/700-EVK Ethernet </sw/yocto/app-dev/ethernet/ethernet-700-evk>`.
- :doc:`Genio 1200-EVK Ethernet </sw/yocto/app-dev/ethernet/ethernet-1200-evk>`.
- :doc:`Genio 520/720-EVK Ethernet </sw/yocto/app-dev/ethernet/ethernet-720-evk>`.