Merge branch 'feat/eth_mac_filter' into 'master'

feat(esp_eth): added option to set MAC filter for mcast

Closes IDF-12503 and IDFGH-14897

See merge request espressif/esp-idf!36944

Author: kostaond

components/esp_eth/include/esp_eth_driver.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -175,6 +175,9 @@ typedef enum {
     ETH_CMD_S_PHY_LOOPBACK,           /*!< Set PHY loopback */
     ETH_CMD_READ_PHY_REG,             /*!< Read PHY register */
     ETH_CMD_WRITE_PHY_REG,            /*!< Write PHY register */
+    ETH_CMD_S_ALL_MULTICAST,          /*!< Set receive all multicast */
+    ETH_CMD_ADD_MAC_FILTER,           /*!< Add MAC filter */
+    ETH_CMD_DEL_MAC_FILTER,           /*!< Delete MAC filter */
 
     ETH_CMD_CUSTOM_MAC_CMDS = ETH_CMD_CUSTOM_MAC_CMDS_OFFSET, // Offset for start of MAC custom commands
     ETH_CMD_CUSTOM_PHY_CMDS = ETH_CMD_CUSTOM_PHY_CMDS_OFFSET, // Offset for start of PHY custom commands
@@ -380,6 +383,9 @@ esp_err_t esp_eth_transmit_ctrl_vargs(esp_eth_handle_t hdl, void *ctrl, uint32_t
 *                            Preconditions: Ethernet driver needs to be stopped and auto-negotiation disabled.
 * @li @c ETH_CMD_G_DUPLEX_MODE gets current Ethernet link duplex mode.  @c data argument is pointer to memory of eth_duplex_t datatype to which the duplex mode is to be stored.
 * @li @c ETH_CMD_S_PHY_LOOPBACK sets/resets PHY to/from loopback mode. @c data argument is pointer to memory of bool datatype from which the configuration option is read.
+* @li @c ETH_CMD_S_ALL_MULTICAST sets/resets Ethernet interface to/from receive all multicast mode. @c data argument is pointer to memory of bool datatype from which the configuration option is read.
+* @li @c ETH_CMD_ADD_MAC_FILTER adds a MAC address to the MAC filter. @c data argument is pointer to MAC address buffer with expected size of 6 bytes.
+* @li @c ETH_CMD_DEL_MAC_FILTER deletes a MAC address from the MAC filter. @c data argument is pointer to MAC address buffer with expected size of 6 bytes.
 *
 * @li Note that additional control commands may be available for specific MAC or PHY chips. Please consult specific MAC or PHY documentation or driver code.
 */

components/esp_eth/include/esp_eth_mac.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -231,6 +231,30 @@ struct esp_eth_mac_s {
     */
     esp_err_t (*get_addr)(esp_eth_mac_t *mac, uint8_t *addr);
 
+    /**
+     * @brief Add Destination address MAC filter
+     *
+     * @param[in] mac: Ethernet MAC instance
+     * @param[in] addr: MAC address
+     *
+     * @return
+     *      - ESP_OK: add MAC filter successfully
+     *      - ESP_FAIL: add MAC filter failed because some error occurred
+     */
+    esp_err_t (*add_mac_filter)(esp_eth_mac_t *mac, uint8_t *addr);
+
+    /**
+     * @brief Remove Destination address MAC filter
+     *
+     * @param[in] mac: Ethernet MAC instance
+     * @param[in] addr: MAC address
+     *
+     * @return
+     *      - ESP_OK: remove MAC filter successfully
+     *      - ESP_FAIL: remove MAC filter failed because some error occurred
+     */
+    esp_err_t (*rm_mac_filter)(esp_eth_mac_t *mac, uint8_t *addr);
+
     /**
     * @brief Set speed of MAC
     *
@@ -286,6 +310,18 @@ struct esp_eth_mac_s {
     */
     esp_err_t (*set_promiscuous)(esp_eth_mac_t *mac, bool enable);
 
+    /**
+     * @brief Set receive all multicast
+     *
+     * @param[in] mac: Ethernet MAC instance
+     * @param[in] enable: set true to enable receive all multicast; set false to disable receive all multicast
+     *
+     * @return
+     *      - ESP_OK: set receive all multicast successfully
+     *      - ESP_FAIL: set receive all multicast failed because some error occurred
+     */
+    esp_err_t (*set_all_multicast)(esp_eth_mac_t *mac, bool enable);
+
     /**
     * @brief Enable flow control on MAC layer or not
     *

components/esp_eth/src/esp_eth.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -483,6 +483,11 @@ esp_err_t esp_eth_ioctl(esp_eth_handle_t hdl, esp_eth_io_cmd_t cmd, void *data)
         ESP_GOTO_ON_FALSE(data, ESP_ERR_INVALID_ARG, err, TAG, "can't set promiscuous to null");
         ESP_GOTO_ON_ERROR(mac->set_promiscuous(mac, *(bool *)data), err, TAG, "set promiscuous mode failed");
         break;
+    case ETH_CMD_S_ALL_MULTICAST:
+        ESP_GOTO_ON_FALSE(data, ESP_ERR_INVALID_ARG, err, TAG, "can't set all multicast to null");
+        ESP_GOTO_ON_FALSE(mac->set_all_multicast != NULL, ESP_ERR_NOT_SUPPORTED, err, TAG, "set receive all multicast not supported");
+        ESP_GOTO_ON_ERROR(mac->set_all_multicast(mac, *(bool *)data), err, TAG, "set all multicast mode failed");
+        break;
     case ETH_CMD_S_FLOW_CTRL:
         ESP_GOTO_ON_FALSE(data, ESP_ERR_INVALID_ARG, err, TAG, "can't set flow ctrl to null");
         ESP_GOTO_ON_ERROR(mac->enable_flow_ctrl(mac, *(bool *)data), err, TAG, "enable mac flow control failed");
@@ -523,6 +528,18 @@ esp_err_t esp_eth_ioctl(esp_eth_handle_t hdl, esp_eth_io_cmd_t cmd, void *data)
                           phy_addr, phy_w_data->reg_addr, *(phy_w_data->reg_value_p)), err, TAG, "failed to write PHY register");
         }
         break;
+    case ETH_CMD_ADD_MAC_FILTER: {
+        ESP_GOTO_ON_FALSE(data, ESP_ERR_INVALID_ARG, err, TAG, "can't set mac addr to null");
+        ESP_GOTO_ON_FALSE(mac->add_mac_filter != NULL, ESP_ERR_NOT_SUPPORTED, err, TAG, "add mac address to filter not supported");
+        ESP_GOTO_ON_ERROR(mac->add_mac_filter(mac, (uint8_t *)data), err, TAG, "add mac address to filter failed");
+        }
+        break;
+    case ETH_CMD_DEL_MAC_FILTER: {
+        ESP_GOTO_ON_FALSE(data, ESP_ERR_INVALID_ARG, err, TAG, "can't set mac addr to null");
+        ESP_GOTO_ON_FALSE(mac->rm_mac_filter != NULL, ESP_ERR_NOT_SUPPORTED, err, TAG, "remove mac address from filter not supported");
+        ESP_GOTO_ON_ERROR(mac->rm_mac_filter(mac, (uint8_t *)data), err, TAG, "remove mac address from filter failed");
+        }
+        break;
     default:
         if (phy->custom_ioctl != NULL && cmd >= ETH_CMD_CUSTOM_PHY_CMDS) {
             ret = phy->custom_ioctl(phy, cmd, data);

components/esp_eth/src/esp_eth_netif_glue.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -46,9 +46,23 @@ static void eth_l2_free(void *h, void* buffer)
     free(buffer);
 }
 
+static esp_err_t eth_set_mac_filter(void *h, const uint8_t *eth_mac, size_t mac_len, bool add)
+{
+    esp_eth_handle_t *eth_handle = (esp_eth_handle_t *)h;
+    ESP_RETURN_ON_FALSE(mac_len == ETH_ADDR_LEN, ESP_ERR_INVALID_ARG, TAG, "invalid MAC length");
+    ESP_LOGD(TAG, "%s filter MAC: %02x:%02x:%02x:%02x:%02x:%02x", add ? "Add" : "Del", eth_mac[0], eth_mac[1],
+             eth_mac[2], eth_mac[3], eth_mac[4], eth_mac[5]);
+    if (add) {
+        ESP_RETURN_ON_ERROR(esp_eth_ioctl(eth_handle, ETH_CMD_ADD_MAC_FILTER, (void *)eth_mac), TAG, "failed to add mac filter");
+    } else {
+        ESP_RETURN_ON_ERROR(esp_eth_ioctl(eth_handle, ETH_CMD_DEL_MAC_FILTER, (void *)eth_mac), TAG, "failed to delete mac filter");
+    }
+    return ESP_OK;
+}
+
 static esp_err_t esp_eth_post_attach(esp_netif_t *esp_netif, void *args)
 {
-    uint8_t eth_mac[6];
+    uint8_t eth_mac[ETH_ADDR_LEN];
     esp_eth_netif_glue_t *netif_glue = (esp_eth_netif_glue_t *)args;
     netif_glue->base.netif = esp_netif;
 
@@ -58,7 +72,8 @@ static esp_err_t esp_eth_post_attach(esp_netif_t *esp_netif, void *args)
     esp_netif_driver_ifconfig_t driver_ifconfig = {
         .handle =  netif_glue->eth_driver,
         .transmit = esp_eth_transmit,
-        .driver_free_rx_buffer = eth_l2_free
+        .driver_free_rx_buffer = eth_l2_free,
+        .driver_set_mac_filter = eth_set_mac_filter
     };
 
     ESP_ERROR_CHECK(esp_netif_set_driver_config(esp_netif, &driver_ifconfig));

components/esp_eth/src/mac/esp_eth_mac_esp.c

@@ -47,6 +47,8 @@ static const char *TAG = "esp.emac";
 #define RMII_10M_SPEED_RX_TX_CLK_DIV    (19)
 #define RMII_100M_SPEED_RX_TX_CLK_DIV   (1)
 
+#define EMAC_MULTI_REG_MUTEX_TIMEOUT_MS (100)
+
 #if CONFIG_IDF_TARGET_ESP32P4
 // ESP32P4 EMAC interface clock configuration is shared among other modules in registers
 #define EMAC_IF_RCC_ATOMIC() PERIPH_RCC_ATOMIC()
@@ -70,6 +72,7 @@ typedef struct {
     bool flow_ctrl_enabled; // indicates whether the user want to do flow control
     bool do_flow_ctrl;  // indicates whether we need to do software flow control
     bool use_pll;  // Only use (A/M)PLL in EMAC_DATA_INTERFACE_RMII && EMAC_CLK_OUT
+    SemaphoreHandle_t multi_reg_mutex; // lock for multiple register access
 #ifdef CONFIG_PM_ENABLE
     esp_pm_lock_handle_t pm_lock;
 #endif
@@ -89,6 +92,16 @@ static void emac_esp_free_driver_obj(emac_esp32_t *emac);
 static esp_err_t emac_esp32_start(esp_eth_mac_t *mac);
 static esp_err_t emac_esp32_stop(esp_eth_mac_t *mac);
 
+static esp_err_t emac_esp32_lock_multi_reg(emac_esp32_t *emac)
+{
+    return xSemaphoreTake(emac->multi_reg_mutex, pdMS_TO_TICKS(EMAC_MULTI_REG_MUTEX_TIMEOUT_MS)) == pdTRUE ? ESP_OK : ESP_ERR_TIMEOUT;
+}
+
+static esp_err_t emac_esp32_unlock_multi_reg(emac_esp32_t *emac)
+{
+    return xSemaphoreGive(emac->multi_reg_mutex) == pdTRUE ? ESP_OK : ESP_FAIL;
+}
+
 static esp_err_t emac_esp32_set_mediator(esp_eth_mac_t *mac, esp_eth_mediator_t *eth)
 {
     esp_err_t ret = ESP_OK;
@@ -167,6 +180,28 @@ static esp_err_t emac_esp32_get_addr(esp_eth_mac_t *mac, uint8_t *addr)
     return ret;
 }
 
+static esp_err_t emac_esp32_add_mac_filter(esp_eth_mac_t *mac, uint8_t *addr)
+{
+    esp_err_t ret = ESP_OK;
+    emac_esp32_t *emac = __containerof(mac, emac_esp32_t, parent);
+    ESP_RETURN_ON_ERROR(emac_esp32_lock_multi_reg(emac), TAG, "failed to lock multiple register access");
+    ESP_GOTO_ON_ERROR(emac_hal_add_addr_da_filter_auto(&emac->hal, addr), err, TAG, "failed to add MAC filter");
+err:
+    emac_esp32_unlock_multi_reg(emac);
+    return ret;
+}
+
+static esp_err_t emac_esp32_rm_mac_filter(esp_eth_mac_t *mac, uint8_t *addr)
+{
+    esp_err_t ret = ESP_OK;
+    emac_esp32_t *emac = __containerof(mac, emac_esp32_t, parent);
+    ESP_RETURN_ON_ERROR(emac_esp32_lock_multi_reg(emac), TAG, "failed to lock multiple register access");
+    ESP_GOTO_ON_ERROR(emac_hal_rm_addr_da_filter_auto(&emac->hal, addr), err, TAG, "failed to remove MAC filter");
+err:
+    emac_esp32_unlock_multi_reg(emac);
+    return ret;
+}
+
 static esp_err_t emac_esp32_set_link(esp_eth_mac_t *mac, eth_link_t link)
 {
     esp_err_t ret = ESP_OK;
@@ -233,6 +268,13 @@ static esp_err_t emac_esp32_set_promiscuous(esp_eth_mac_t *mac, bool enable)
     return ESP_OK;
 }
 
+static esp_err_t emac_esp32_set_all_multicast(esp_eth_mac_t *mac, bool enable)
+{
+    emac_esp32_t *emac = __containerof(mac, emac_esp32_t, parent);
+    emac_hal_pass_all_multicast_enable(&emac->hal, enable);
+    return ESP_OK;
+}
+
 static esp_err_t emac_esp32_enable_flow_ctrl(esp_eth_mac_t *mac, bool enable)
 {
     emac_esp32_t *emac = __containerof(mac, emac_esp32_t, parent);
@@ -631,6 +673,10 @@ static void emac_esp_free_driver_obj(emac_esp32_t *emac)
         }
 #endif // CONFIG_IDF_TARGET_ESP32
 
+        if (emac->multi_reg_mutex) {
+            vSemaphoreDelete(emac->multi_reg_mutex);
+        }
+
 #ifdef CONFIG_PM_ENABLE
         if (emac->pm_lock) {
             esp_pm_lock_delete(emac->pm_lock);
@@ -660,6 +706,10 @@ static esp_err_t emac_esp_alloc_driver_obj(const eth_mac_config_t *config, emac_
 #ifdef CONFIG_PM_ENABLE
     ESP_GOTO_ON_ERROR(esp_pm_lock_create(ESP_PM_APB_FREQ_MAX, 0, "emac_esp32", &emac->pm_lock), err, TAG, "create pm lock failed");
 #endif
+
+    emac->multi_reg_mutex = xSemaphoreCreateMutex();
+    ESP_GOTO_ON_FALSE(emac->multi_reg_mutex, ESP_ERR_NO_MEM, err, TAG, "failed to create multiple register access mutex");
+
     /* create rx task */
     BaseType_t core_num = tskNO_AFFINITY;
     if (config->flags & ETH_MAC_FLAG_PIN_TO_CORE) {
@@ -805,10 +855,13 @@ esp_eth_mac_t *esp_eth_mac_new_esp32(const eth_esp32_emac_config_t *esp32_config
     emac->parent.read_phy_reg = emac_esp32_read_phy_reg;
     emac->parent.set_addr = emac_esp32_set_addr;
     emac->parent.get_addr = emac_esp32_get_addr;
+    emac->parent.add_mac_filter = emac_esp32_add_mac_filter;
+    emac->parent.rm_mac_filter = emac_esp32_rm_mac_filter;
     emac->parent.set_speed = emac_esp32_set_speed;
     emac->parent.set_duplex = emac_esp32_set_duplex;
     emac->parent.set_link = emac_esp32_set_link;
     emac->parent.set_promiscuous = emac_esp32_set_promiscuous;
+    emac->parent.set_all_multicast = emac_esp32_set_all_multicast;
     emac->parent.set_peer_pause_ability = emac_esp32_set_peer_pause_ability;
     emac->parent.enable_flow_ctrl = emac_esp32_enable_flow_ctrl;
     emac->parent.transmit = emac_esp32_transmit;