doc: connectivity: networking: Add MAC address configuration page

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));
+   }

drivers/ethernet/eth.h

@@ -43,38 +43,4 @@ static inline void gen_random_mac(uint8_t *mac_addr, uint8_t b0, uint8_t b1, uin
 	sys_rand_get(&mac_addr[3], 3U);
 }
 
-static inline int net_eth_mac_load(const struct net_eth_mac_config *cfg, uint8_t *mac_addr)
-{
-	if (cfg == NULL || cfg->type == NET_ETH_MAC_DEFAULT) {
-		return -ENODATA;
-	}
-
-	/* Copy the static part */
-	memcpy(mac_addr, cfg->addr, cfg->addr_len);
-
-	if (cfg->type == NET_ETH_MAC_RANDOM) {
-		sys_rand_get(&mac_addr[cfg->addr_len], NET_ETH_ADDR_LEN - cfg->addr_len);
-
-		/* Clear group bit, multicast (I/G) */
-		mac_addr[0] &= ~0x01;
-		/* Set MAC address locally administered, unicast (LAA) */
-		mac_addr[0] |= 0x02;
-
-		return 0;
-	}
-
-#if defined(CONFIG_NVMEM)
-	if (cfg->type == NET_ETH_MAC_NVMEM) {
-		return nvmem_cell_read(&cfg->cell, &mac_addr[cfg->addr_len], 0,
-				       NET_ETH_ADDR_LEN - cfg->addr_len);
-	}
-#endif
-
-	if (cfg->type == NET_ETH_MAC_STATIC) {
-		return 0;
-	}
-
-	return -ENODATA;
-}
-
 #endif /* ZEPHYR_DRIVERS_ETHERNET_ETH_H_ */

include/zephyr/net/ethernet.h

@@ -25,6 +25,7 @@
 #include <zephyr/net/net_if.h>
 #include <zephyr/net/ethernet_vlan.h>
 #include <zephyr/net/ptp_time.h>
+#include <zephyr/random/random.h>
 
 #if defined(CONFIG_NET_DSA_DEPRECATED)
 #include <zephyr/net/dsa.h>
@@ -1328,6 +1329,54 @@ struct net_eth_mac_config {
 #endif
 };
 
+/**
+ * @brief Load a MAC address from a MAC address configuration structure with the specified type.
+ *
+ * In the case of a randomized MAC address, the universal vs local (U/L) bit is set to a
+ * locally administered address (LAA) and the unicast vs multicast (I/G) bit is cleared to make it
+ * a unicast address.
+ *
+ * @param cfg The MAC address configuration.
+ * @param mac_addr The resulting MAC address buffer, needs a size of @ref NET_ETH_ADDR_LEN bytes.
+ *
+ * @retval -ENODATA No MAC address configuration data is loaded.
+ * @retval <0 Negative errno code if failure.
+ * @retval 0 If successful.
+ */
+static inline int net_eth_mac_load(const struct net_eth_mac_config *cfg, uint8_t *mac_addr)
+{
+	if (cfg == NULL || cfg->type == NET_ETH_MAC_DEFAULT) {
+		return -ENODATA;
+	}
+
+	/* Copy the static part */
+	memcpy(mac_addr, cfg->addr, cfg->addr_len);
+
+	if (cfg->type == NET_ETH_MAC_RANDOM) {
+		sys_rand_get(&mac_addr[cfg->addr_len], NET_ETH_ADDR_LEN - cfg->addr_len);
+
+		/* Clear group bit, multicast (I/G) */
+		mac_addr[0] &= ~0x01;
+		/* Set MAC address locally administered, unicast (LAA) */
+		mac_addr[0] |= 0x02;
+
+		return 0;
+	}
+
+#if defined(CONFIG_NVMEM)
+	if (cfg->type == NET_ETH_MAC_NVMEM) {
+		return nvmem_cell_read(&cfg->cell, &mac_addr[cfg->addr_len], 0,
+				       NET_ETH_ADDR_LEN - cfg->addr_len);
+	}
+#endif
+
+	if (cfg->type == NET_ETH_MAC_STATIC) {
+		return 0;
+	}
+
+	return -ENODATA;
+}
+
 /** @cond INTERNAL_HIDDEN */
 
 #if defined(CONFIG_NVMEM) || defined(__DOXYGEN__)