doc: connectivity: networking: Add MAC address configuration page

Add a page with information on how ethernet drivers can be assigned a MAC
address, using the MAC address configuration mechanism.

Signed-off-by: Pieter De Gendt <[email protected]>

Author: pdgendt

doc/connectivity/networking/api/ethernet.rst

@@ -10,6 +10,7 @@ Ethernet
 .. toctree::
    :maxdepth: 1
 
+   mac_config.rst
    vlan.rst
    lldp.rst
    8021Qav.rst
@@ -29,6 +30,7 @@ Zephyr supports following Ethernet features:
 * Promiscuous mode
 * TX and RX checksum offloading
 * MAC address filtering
+* :ref:`MAC address configuration <mac_address_config>`
 * :ref:`Virtual LANs <vlan_interface>`
 * :ref:`Priority queues <traffic-class-support>`
 * :ref:`IEEE 802.1AS (gPTP) <gptp_interface>`

doc/connectivity/networking/api/mac_config.rst

@@ -0,0 +1,147 @@
+.. _mac_address_config:
+
+MAC Address Configuration
+*************************
+
+Ethernet drivers can delegate most MAC address handling during initialization to
+:c:struct:`net_eth_mac_config` and :c:func:`net_eth_mac_load`. The structure
+is typically stored in the driver configuration and initialized with
+:c:macro:`NET_ETH_MAC_DT_CONFIG_INIT` or :c:macro:`NET_ETH_MAC_DT_INST_CONFIG_INIT`,
+which translate the devicetree properties into one of the following behaviors:
+
+* :c:enumerator:`NET_ETH_MAC_STATIC` – use the full ``local-mac-address`` property.
+* :c:enumerator:`NET_ETH_MAC_RANDOM` – generate a random locally administered MAC address,
+  optionally using the bytes provided in ``zephyr,mac-address-prefix`` as the first octets.
+* :c:enumerator:`NET_ETH_MAC_NVMEM` – read the remaining bytes from the ``"mac-address"``
+  :ref:`NVMEM<nvmem>` cell, again optionally prefixed by ``zephyr,mac-address-prefix``.
+* :c:enumerator:`NET_ETH_MAC_DEFAULT` – fall back to the driver's default logic (for
+  example, a factory-programmed MAC address stored in peripheral registers).
+
+Driver integration
+==================
+
+Embed the :c:struct:`net_eth_mac_config` structure inside the driver's configuration
+and a static buffer inside the driver's data:
+
+.. code-block:: c
+
+   struct my_eth_config {
+       struct net_eth_mac_config mac_cfg;
+       /* more config fields */
+   };
+
+   struct my_eth_data {
+       uint8_t mac_addr[NET_ETH_ADDR_LEN];
+       /* more data fields */
+   };
+
+   static const struct my_eth_config my_eth_config_0 = {
+       .mac_cfg = NET_ETH_MAC_DT_INST_CONFIG_INIT(0),
+   };
+   static struct my_eth_data my_eth_data_0;
+
+During initialization, call :c:func:`net_eth_mac_load` before registering
+the address with the network interface. The helper copies any statically provided
+bytes, fills the remaining octets, and performs the necessary validation.
+Drivers can still fall back to SoC-specific storage when no configuration was provided:
+
+.. code-block:: c
+
+   static int my_eth_init(const struct device *dev)
+   {
+       const struct my_eth_config *cfg = dev->config;
+       struct my_eth_data *data = dev->data;
+       int ret;
+
+       ret = net_eth_mac_load(&cfg->mac_cfg, data->mac_addr);
+       if (ret == -ENODATA) {
+           ret = my_eth_hw_read_mac(dev, data->mac_addr);
+       }
+
+       return ret;
+   }
+
+   static void my_eth_iface_init(struct net_if *iface)
+   {
+       const struct device *dev = net_if_get_device(iface);
+       struct my_eth_data *data = dev->data;
+
+       net_if_set_link_addr(iface, data->mac_addr, sizeof(data->mac_addr), NET_LINK_ETHERNET);
+   }
+
+Devicetree examples
+===================
+
+The examples below show how to pick a MAC address configuration for an ethernet controller node
+such as ``&eth0``.
+
+Static MAC address
+------------------
+
+.. code-block:: devicetree
+
+   &eth0 {
+       local-mac-address = [00 11 22 33 44 55];
+   };
+
+Random MAC address with prefix
+------------------------------
+
+.. code-block:: devicetree
+
+   &eth0 {
+       zephyr,mac-address-prefix = [00 04 25];
+       zephyr,random-mac-address;
+   };
+
+NVMEM-provided MAC address with prefix
+--------------------------------------
+
+.. code-block:: devicetree
+
+   &eth0 {
+       zephyr,mac-address-prefix = [00 12 34];
+       nvmem-cells = <&macaddr_cell>;
+       nvmem-cell-names = "mac-address";
+   };
+
+   &eeprom0 {
+       nvmem-layout {
+           compatible = "fixed-layout";
+           #address-cells = <1>;
+           #size-cells = <1>;
+
+           macaddr_cell: cell@0 {
+               reg = <0x0 0x6>;
+               #nvmem-cell-cells = <0>;
+           };
+       };
+   };
+
+When no MAC-related properties are present, :c:func:`net_eth_mac_load` returns ``-ENODATA`` and
+the driver is expected to use its existing mechanism (for example, reading the hardware registers or
+using a build-time constant).
+
+Changing the MAC address at runtime
+===================================
+
+Applications that need to set MAC addresses dynamically (for example to adopt an address obtained
+from a management interface) need to enable the networking management API with
+:kconfig:option:`CONFIG_NET_MGMT` and use :c:macro:`net_mgmt` with
+:c:macro:`NET_REQUEST_ETHERNET_SET_MAC_ADDRESS`.
+The request internally calls the driver's :c:func:`ethernet_api.set_config` implementation.
+
+.. code-block:: c
+
+   static int app_set_mac_address(const struct device *dev)
+   {
+       struct net_if *iface = net_if_lookup_by_dev(dev);
+       struct ethernet_req_params params = {
+           .mac_address = { { 0x02, 0x00, 0x5E, 0x01, 0x02, 0x03 } },
+       };
+
+       /* Make sure the iface is down */
+
+       return net_mgmt(NET_REQUEST_ETHERNET_SET_MAC_ADDRESS, iface,
+                       &params, sizeof(params));
+   }