Wiznet makers

The cover image of this article was generated by Gemini.

1. Executive Summary

Through the latest mainline update (PR #100919) of Zephyr RTOS, the WIZnet W5500 driver now supports Zephyr's standard MAC address configuration method.

The core of this patch is the replacement of non-standard implementation methods with Zephyr's recommended Standard APIs (net_eth_mac_*), thereby enhancing driver compatibility and maintenance convenience.

• GitHub PR: https://github.com/zephyrproject-rtos/zephyr/pull/100919
• Status: Merged (Applied to Mainline)

2. Background: The Pain Point

Managing unique MAC addresses is essential during the mass production of industrial IoT devices. However, the existing W5500 driver in the Zephyr environment had the following limitations:

1. Required modifying the driver source code to hardcode MAC addresses.
2. Relied on non-standard APIs or required separate manual configuration to input addresses.

These issues made it tedious to perform automated MAC address provisioning on factory production lines.

3. Technical Breakdown

With PR #100919, the W5500 driver has adopted the 'Standard Ethernet MAC Configuration API' defined by Zephyr OS.

3.1. Introduction of Standard Configuration Macros (Device Tree Integration)

The initialization logic in the source code (drivers/ethernet/eth_w5500.c) has been changed as follows:

/* Before: Using non-standard APIs or hardcoding */
// (Removed) gen_random_mac(...);
// (Removed) DT_INST_PROP(0, local_mac_address);

/* After: Calling Zephyr Standard API */
// Linking with Zephyr's standard configuration structure
.mac_cfg = NET_ETH_MAC_DT_INST_CONFIG_INIT(0),

// Loading MAC address via Standard API at boot
(void)net_eth_mac_load(&config->mac_cfg, ctx->mac_addr);

[Key Analysis]

• NET_ETH_MAC_DT_INST_CONFIG_INIT: Automatically parses MAC address information defined in the Zephyr Device Tree (.dts) file.
• net_eth_mac_load: Safely retrieves the MAC address from kernel-managed standard storage (OTP, config files, etc.) and applies it to the W5500 registers.

3.2. Runtime Configuration Support

The ability to change the W5500's MAC address via the standard API (net_mgmt) during application runtime has been standardized.

/* drivers/ethernet/eth_w5500.c - w5500_set_config function */
case ETHERNET_CONFIG_TYPE_MAC_ADDRESS:
    // Immediately applying the input MAC address to W5500 hardware register (SHAR)
    w5500_spi_write(dev, W5500_SHAR, ctx->mac_addr, ...);
    break;

4. FAQ: Technical Implementation Questions

Q1. The gen_random_mac()(random MAC generation) function in the existing code has been removed. What happens if I don't configure a MAC address now?

From now on, the Zephyr OS Network Stack (L2 Layer) takes over that role, not the driver. If there is no valid MAC address in the Device Tree, the OS will automatically assign a random address and pass it to the driver, depending on the Zephyr kernel configuration (e.g., CONFIG_NET_L2_ETHERNET_LOG_LEVEL_DBG). The function hasn't disappeared; it has been delegated to the OS standard function.

Q2. How should I configure it in the Device Tree (.dts) file now?

Instead of the separate properties used in the past, you can now use the Zephyr standard property local-mac-address. (Example)

&spi1 {
    w5500: w5500@0 {
        compatible = "wiznet,w5500";
        local-mac-address = [00 08 DC 00 00 01]; /* Standard property available */
        ...
    };
};

Q3. Can I change the MAC address while the firmware is running (Runtime)?

Yes, it is possible. With this update, the w5500_set_config function now supports the standard interface. At the application level, calling the net_mgmt() API to send the NET_REQUEST_ETHERNET_SET_MAC_ADDRESS command will immediately update the W5500 internal register (SHAR) value.

Q4. Do I need to modify a lot of code to apply this update?

No. Application code does not need to be modified. However, if your project previously involved directly modifying the W5500 driver internals to hardcode MAC addresses, we recommend migrating by removing that part and adding the configuration to the Device Tree (.dts) file.