Configuration

MAC address

Mainline U-Boot based systems

On mainline U-Boot based firmware, the MAC address will be generated at boot time, based on the unique serial number stored in the SID efuse device. It will be the same on every boot, and should be rather unique, within the limits of the hashing algorithm.

To trigger the routine, the DTB passed on to the kernel (which can also be U-Boot's own DT) must have an ethernet0 alias in the /aliases DT node:

   aliases {
       ethernet0 = &emac;
       ethernet1 = &rtl8189etv;
   };

Mainline DTs should already have this alias. Up to 4 MAC addresses will be assigned, if needed. The code will insert a local-mac-address and mac-address property into the DT node that the alias points to. This standard DT property will then be picked up by any OS automatically.

Despite the alias having the name ethernet, this works and is needed for WiFi devices in the same way.

Aside from making sure that the DT has the alias, there is no user intervention necessary, and a unique and stable MAC address should be assigned out of the box.

Legacy systems

By default both EMAC and GMAC use random MAC addresses that change with each reboot, but this can be fixed.

The Bash script below will generate a unicast, locally administered, random MAC address. The first octet has bit 0 unset for unicast and bit 1 set for local administration so will be either X2, X6, Xa or Xe:

printf "%02x" $((RANDOM%256 & 254 | 2));hexdump -n 5 -e '""5/1 ":%02x""\n"' /dev/urandom

This MAC address can be loaded on each boot using one of the methods below to give a static MAC address.

For alternative sources of MAC addresses the FAQ 14.2.14. Where Can I Get a Valid MAC Address from? at the U-Boot website may help.

Through script.bin

the Allwinner way, adding the value to your script.bin

[dynamic]
MAC = "XXXXXXXXXXXX"

U-boot

the bootloader to append mac_addr=XX:XX:XX:XX:XX:XX

Through ifconfig

ifconfig eth0 hw ether XX:XX:XX:XX:XX:XX

Hardware

In contrast to combined network chips used in the modern PC world, embedded SoCs split the network adapter functionality into two components:

a MAC device, fully integrated into the SoC, which deals with the actual packet handling and is driven by DMA and interrupts. It is also responsible for the timing. Its output is typically using one of multiple variants of the MII interface, which connects it to:

a PHY chip, commonly found as an extra chip on the board. This converts the logic levels of the *MII interface into the electrical domain of the Ethernet cable, and deals with the properties of the physical layer, like link and collision detection. Some Allwinner SoCs (like H3, H5, H6, H616) contain a 100MBit/s Ethernet PHY on the same package, this is commonly used on cheap boards to save the cost of the extra PHY component.

EMAC

Allwinner's A10, A20 and F20 SoCs include a MAC unit called EMAC, but it's usable on very few devices, most notably the Mele A1000, A2000 and A100 HTPC and the Cubieboard. Due to driver similarities it's believed to be based on DM9000.

Mainline Kernel driver

The EMAC driver can be found under "Ethernet driver support", "Allwinner devices", "Allwinner A10 EMAC support". It was merged for kernel 3.11.

GMAC

Allwinner's A20, A31/A31s and the A80 contain a MAC unit called GMAC ("Gigabit MAC"). The controller supports MII and RGMII modes. On the A20 it is pin compatible with the EMAC in MII mode. Also on A20 the manufacturer of the device in question can decide whether to use EMAC or GMAC. The controller is an early version of the Synopsys DWMAC (DesignWare MAC), with some hardware specific glue.

The SoC's GMAC is always combined with an external PHY, in most cases a RTL8211E/CL (the Lamobo R1 uses the Broadcom BCM53125 switch IC instead). Important: In this special mode the RTL8211 chip is just used as PHY and only responsible for layer 1 operations, since everything else happens inside the SoC's GMAC (therefore no RealTek drivers are needed and some functionality differs, e.g. no WoL possible).

For reliable Gigabit networking (1000Mbit operation), several sunxi devices require an important tweak that adjusts the relative timing of the clock and data signals to the PHY, in order to compensate for differing trace lengths on the PCB (details). Among others, this includes Banana Pi/Pro, Cubietruck, Lamobo R1, pcDuino3 Nano and Orange Pi/Mini. Recent mainline U-Boot uses CONFIG_GMAC_TX_DELAY to initialize these devices accordingly. If a necessary GMAC TX delay isn't set, then GBit Ethernet operation might be unreliable or won't work at all. 10/100 Mbit/sec negotiation is unaffected, so misconfigured devices could actually work (faster) when connected to a Fast Ethernet port instead of a GBit Ethernet port.

Mainline Kernel driver

DWMAC is supported by the stmmac driver ("Ethernet driver support", "STMicroelectronics devices", "STMicroelectronics 10/100/1000 Ethernet driver", "STMMAC Platform bus support"). Platform glue for sunxi was merged in 3.14. Device tree patches for supported A20 devices were merged in 3.15.

sun8i EMAC

Ethernet in the A83T/H3/A64 and later SoCs is handled by the newer Sun8i_emac MAC. It is another variant of the Designware MAC, with a changed register interface, and is handled in Linux by the sun8i_emac driver, part of the stmmac driver framework:

   -> Device Drivers
     -> Network device support
       -> Ethernet driver support
         -> STMicroelectronics devices
           -> STMicroelectronics Multi-Gigabit Ethernet driver
             -> STMMAC Platform bus support (STMMAC_PLATFORM)
               -> Allwinner sun8i GMAC support (DWMAC_SUN8I)

Phyceivers

Broadcom BCM53125

The Broadcom BCM53125 is an integrated 7-port Gbit Ethernet switch IC that can be configured to act as a PHY on one port interconnecting the SoC with all wired Ethernet ports. It works with OpenWrt's b53-mdio driver, and the capability to route packets between different ports is based on VLANs and assigning them to virtual interfaces. At least the implementation on the Lamobo R1 suffers from less possible throughput compared to A20's GMAC working together with RTL8211 as PHY.

ICplus IP101A

The ICplus IP101A is a RMII 10/100 Ethernet PHY.

ICplus IP101GA

The ICplus IP101GA is a RMII 10/100 Ethernet PHY.

Microchip LAN8710A

Micrel KSZ9031

The KSZ9031 is a gigabit ethernet PHY.

It may require adjusting RX or TX delays, depending on PCB wiring of each board. According to git commit notes for the linux driver, TX delay can be 0 - 1.38ns and RX delay can be 0 - 2.58ns.

The PHY is used on newer revisions of the Olimex Lime2, where the board makers found a TX_DELAY=4 in u-boot suitable.

Realtek RTL8201CP

The Realtek RTL8201CP is a MII mode 10/100 Ethernet PHY. It is very very common and supported by just about any kernel out there, either with the generic phy driver or the realtek one.

Oliver broke his PHY and ended up replacing it with another one. Here are some pictures.

Realtek RTL8211E

The Realtek RTL8211E is a RGMII 10/100/1000 Ethernet PHY, which is gigabit capable. It is commonly paired with GMAC for gigabit speeds. Generic PHY support is enough to make it work.

Realtek RTL8211CL

The RTL8211 is known to have trouble connecting to certain types of devices. The problem is caused by an instable PLL when configured as master. A fix has been applied to u-boot. http://lists.denx.de/pipermail/u-boot/2016-March/249734.html