Merge branch 'feature/ver-4.2' into 'master'

global: bump version to 4.2

See merge request espressif/esp-idf!7335

components/esp32/Kconfig

@@ -303,7 +303,7 @@ menu "ESP32-specific"
         default ESP32_UNIVERSAL_MAC_ADDRESSES_FOUR
         help
             Configure the number of universally administered (by IEEE) MAC addresses.
-            During initialisation, MAC addresses for each network interface are generated or derived from a
+            During initialization, MAC addresses for each network interface are generated or derived from a
             single base MAC address.
             If the number of universal MAC addresses is four, all four interfaces (WiFi station, WiFi softap,
             Bluetooth and Ethernet) receive a universally administered MAC address. These are generated
@@ -319,8 +319,15 @@ menu "ESP32-specific"
 
         config ESP32_UNIVERSAL_MAC_ADDRESSES_TWO
             bool "Two"
+            select ESP_MAC_ADDR_UNIVERSE_WIFI_STA
+            select ESP_MAC_ADDR_UNIVERSE_BT
+
         config ESP32_UNIVERSAL_MAC_ADDRESSES_FOUR
             bool "Four"
+            select ESP_MAC_ADDR_UNIVERSE_WIFI_STA
+            select ESP_MAC_ADDR_UNIVERSE_WIFI_AP
+            select ESP_MAC_ADDR_UNIVERSE_BT
+            select ESP_MAC_ADDR_UNIVERSE_ETH
     endchoice
 
     config ESP32_UNIVERSAL_MAC_ADDRESSES

components/esp32s2beta/Kconfig

@@ -264,33 +264,34 @@ menu "ESP32S2-specific"
 
     choice ESP32S2_UNIVERSAL_MAC_ADDRESSES
         bool "Number of universally administered (by IEEE) MAC address"
-        default ESP32S2_UNIVERSAL_MAC_ADDRESSES_FOUR
+        default ESP32S2_UNIVERSAL_MAC_ADDRESSES_TWO
         help
             Configure the number of universally administered (by IEEE) MAC addresses.
-            During initialisation, MAC addresses for each network interface are generated or derived from a
+            During initialization, MAC addresses for each network interface are generated or derived from a
             single base MAC address.
-            If the number of universal MAC addresses is four, all four interfaces (WiFi station, WiFi softap,
-            Bluetooth and Ethernet) receive a universally administered MAC address. These are generated
-            sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address.
-            If the number of universal MAC addresses is two, only two interfaces (WiFi station and Bluetooth)
-            receive a universally administered MAC address. These are generated sequentially by adding 0
-            and 1 (respectively) to the base MAC address. The remaining two interfaces (WiFi softap and Ethernet)
-            receive local MAC addresses. These are derived from the universal WiFi station and Bluetooth MAC
-            addresses, respectively.
+            If the number of universal MAC addresses is Two, all interfaces (WiFi station, WiFi softap) receive a
+            universally administered MAC address. They are generated sequentially by adding 0, and 1 (respectively)
+            to the final octet of the base MAC address. If the number of universal MAC addresses is one,
+            only WiFi station receives a universally administered MAC address.
+            It's generated by adding 0 to the base MAC address.
+            The WiFi softap receives local MAC addresses. It's derived from the universal WiFi station MAC addresses.
             When using the default (Espressif-assigned) base MAC address, either setting can be used. When using
             a custom universal MAC address range, the correct setting will depend on the allocation of MAC
-            addresses in this range (either 2 or 4 per device.)
+            addresses in this range (either 1 or 2 per device.)
 
+        config ESP32S2_UNIVERSAL_MAC_ADDRESSES_ONE
+            bool "One"
+            select ESP_MAC_ADDR_UNIVERSE_WIFI_STA
         config ESP32S2_UNIVERSAL_MAC_ADDRESSES_TWO
             bool "Two"
-        config ESP32S2_UNIVERSAL_MAC_ADDRESSES_FOUR
-            bool "Four"
+            select ESP_MAC_ADDR_UNIVERSE_WIFI_STA
+            select ESP_MAC_ADDR_UNIVERSE_WIFI_AP
     endchoice
 
     config ESP32S2_UNIVERSAL_MAC_ADDRESSES
         int
+        default 1 if ESP32S2_UNIVERSAL_MAC_ADDRESSES_ONE
         default 2 if ESP32S2_UNIVERSAL_MAC_ADDRESSES_TWO
-        default 4 if ESP32S2_UNIVERSAL_MAC_ADDRESSES_FOUR
 
     config ESP32S2_ULP_COPROC_ENABLED
         bool "Enable Ultra Low Power (ULP) Coprocessor"

components/esp_common/Kconfig

@@ -238,4 +238,16 @@ menu "Common ESP-related"
             Debug stubs are used by OpenOCD to execute pre-compiled onboard code
             which does some useful debugging stuff, e.g. GCOV data dump.
 
+    config ESP_MAC_ADDR_UNIVERSE_WIFI_STA
+        bool
+
+    config ESP_MAC_ADDR_UNIVERSE_WIFI_AP
+        bool
+
+    config ESP_MAC_ADDR_UNIVERSE_BT
+        bool
+
+    config ESP_MAC_ADDR_UNIVERSE_ETH
+        bool
+
 endmenu # Common ESP-related

components/esp_common/include/esp_idf_version.h

@@ -21,7 +21,7 @@ extern "C" {
 /** Major version number (X.x.x) */
 #define ESP_IDF_VERSION_MAJOR   4
 /** Minor version number (x.X.x) */
-#define ESP_IDF_VERSION_MINOR   1
+#define ESP_IDF_VERSION_MINOR   2
 /** Patch version number (x.x.X) */
 #define ESP_IDF_VERSION_PATCH   0
 

components/esp_common/src/mac_addr.c

@@ -1,3 +1,16 @@
+// Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
 #include <string.h>
 #include "sdkconfig.h"
 #include "esp_system.h"
@@ -37,7 +50,7 @@ esp_err_t esp_base_mac_addr_get(uint8_t *mac)
     uint8_t null_mac[6] = {0};
 
     if (memcmp(base_mac_addr, null_mac, 6) == 0) {
-        ESP_LOGI(TAG, "Base MAC address is not set, read default base MAC address from BLK0 of EFUSE");
+        ESP_LOGI(TAG, "Base MAC address is not set");
         return ESP_ERR_INVALID_MAC;
     }
 
@@ -137,12 +150,11 @@ esp_err_t esp_read_mac(uint8_t* mac, esp_mac_type_t type)
         return ESP_ERR_INVALID_ARG;
     }
 
-    _Static_assert(UNIVERSAL_MAC_ADDR_NUM == FOUR_UNIVERSAL_MAC_ADDR \
-            || UNIVERSAL_MAC_ADDR_NUM == TWO_UNIVERSAL_MAC_ADDR, \
-            "incorrect NUM_MAC_ADDRESS_FROM_EFUSE value");
-
+    // if base mac address is not set, read one from EFUSE and then write back
     if (esp_base_mac_addr_get(efuse_mac) != ESP_OK) {
+        ESP_LOGI(TAG, "read default base MAC address from EFUSE");
         esp_efuse_mac_get_default(efuse_mac);
+        esp_base_mac_addr_set(efuse_mac);
     }
 
     switch (type) {
@@ -150,39 +162,35 @@ esp_err_t esp_read_mac(uint8_t* mac, esp_mac_type_t type)
         memcpy(mac, efuse_mac, 6);
         break;
     case ESP_MAC_WIFI_SOFTAP:
-        if (UNIVERSAL_MAC_ADDR_NUM == FOUR_UNIVERSAL_MAC_ADDR) {
-            memcpy(mac, efuse_mac, 6);
-            mac[5] += 1;
-        }
-        else if (UNIVERSAL_MAC_ADDR_NUM == TWO_UNIVERSAL_MAC_ADDR) {
-            esp_derive_local_mac(mac, efuse_mac);
-        }
+#if CONFIG_ESP_MAC_ADDR_UNIVERSE_WIFI_AP
+        memcpy(mac, efuse_mac, 6);
+        mac[5] += 1;
+#else
+        esp_derive_local_mac(mac, efuse_mac);
+#endif
         break;
     case ESP_MAC_BT:
         memcpy(mac, efuse_mac, 6);
-        if (UNIVERSAL_MAC_ADDR_NUM == FOUR_UNIVERSAL_MAC_ADDR) {
-            mac[5] += 2;
-        }
-        else if (UNIVERSAL_MAC_ADDR_NUM == TWO_UNIVERSAL_MAC_ADDR) {
-            mac[5] += 1;
-        }
+#if CONFIG_ESP_MAC_ADDR_UNIVERSE_BT
+        mac[5] += 2;
+#else
+        mac[5] += 1;
+#endif
         break;
     case ESP_MAC_ETH:
-        if (UNIVERSAL_MAC_ADDR_NUM == FOUR_UNIVERSAL_MAC_ADDR) {
-            memcpy(mac, efuse_mac, 6);
-            mac[5] += 3;
-        }
-        else if (UNIVERSAL_MAC_ADDR_NUM == TWO_UNIVERSAL_MAC_ADDR) {
-            efuse_mac[5] += 1;
-            esp_derive_local_mac(mac, efuse_mac);
-        }
+#if CONFIG_ESP_MAC_ADDR_UNIVERSE_ETH
+        memcpy(mac, efuse_mac, 6);
+        mac[5] += 3;
+#else
+        efuse_mac[5] += 1;
+        esp_derive_local_mac(mac, efuse_mac);
+#endif
         break;
     default:
-        ESP_LOGW(TAG, "incorrect mac type");
+        ESP_LOGE(TAG, "unsupported mac type");
         break;
     }
 
     return ESP_OK;
 }
 
-

components/esp_netif/include/esp_netif.h

@@ -613,6 +613,22 @@ esp_err_t esp_netif_create_ip6_linklocal(esp_netif_t *esp_netif);
  */
 esp_err_t esp_netif_get_ip6_linklocal(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6);
 
+/**
+ * @brief  Get interface global IPv6 address
+ *
+ * If the specified interface is up and a preferred global IPv6 address
+ * has been created for the interface, return a copy of it.
+ *
+ * @param[in]  esp_netif Handle to esp-netif instance
+ * @param[out] if_ip6 IPv6 information will be returned in this argument if successful.
+ *
+ * @return
+ *      - ESP_OK
+ *      - ESP_FAIL If interface is down, does not have a global IPv6 address,
+ *        or the global IPv6 address is not a preferred address.
+ */
+esp_err_t esp_netif_get_ip6_global(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6);
+
 /**
  * @brief Sets IPv4 address to the specified octets
  *

components/esp_netif/loopback/esp_netif_loopback.c

@@ -412,6 +412,11 @@ esp_err_t esp_netif_get_ip6_linklocal(esp_netif_t *esp_netif, esp_ip6_addr_t *if
     return ESP_ERR_NOT_SUPPORTED;
 }
 
+esp_err_t esp_netif_get_ip6_global(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6)
+{
+    return ESP_ERR_NOT_SUPPORTED;
+}
+
 esp_netif_flags_t esp_netif_get_flags(esp_netif_t *esp_netif)
 {
     return esp_netif->flags;

components/esp_netif/lwip/esp_netif_lwip.c

@@ -1396,6 +1396,29 @@ esp_err_t esp_netif_get_ip6_linklocal(esp_netif_t *esp_netif, esp_ip6_addr_t *if
     return ESP_OK;
 }
 
+esp_err_t esp_netif_get_ip6_global(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6)
+{
+    ESP_LOGD(TAG, "%s esp-netif:%p", __func__, esp_netif);
+
+    if (esp_netif == NULL || if_ip6 == NULL) {
+        return ESP_ERR_ESP_NETIF_INVALID_PARAMS;
+    }
+
+    int i;
+    struct netif *p_netif = esp_netif->lwip_netif;
+
+    if (p_netif != NULL && netif_is_up(p_netif)) {
+        for (i = 1; i < LWIP_IPV6_NUM_ADDRESSES; i++) {
+            if (ip6_addr_ispreferred(netif_ip6_addr_state(p_netif, i))) {
+                memcpy(if_ip6, &p_netif->ip6_addr[i], sizeof(ip6_addr_t));
+                return ESP_OK;
+            }
+        }
+    }
+    
+    return ESP_FAIL;
+}
+
 esp_netif_flags_t esp_netif_get_flags(esp_netif_t *esp_netif)
 {
     return esp_netif->flags;

components/tcpip_adapter/include/tcpip_adapter.h

@@ -60,6 +60,15 @@ esp_err_t tcpip_adapter_get_ip_info(tcpip_adapter_if_t tcpip_if, tcpip_adapter_i
  */
 esp_err_t tcpip_adapter_get_ip6_linklocal(tcpip_adapter_if_t tcpip_if, ip6_addr_t *if_ip6);
 
+/**
+ * @brief Translates to esp_netif_get_ip6_global
+ *
+ * @param tcpip_if  Interface type corresponding to appropriate instance of esp-netif
+ * @param if_ip6 See esp_netif_get_ip6_global
+ * @return See esp_netif_get_ip6_global
+ */
+esp_err_t tcpip_adapter_get_ip6_global(tcpip_adapter_if_t tcpip_if, ip6_addr_t *if_ip6);
+
 /**
  * @brief`Translates to esp_netif_dhcpc_get_status
  * @param tcpip_if Interface type corresponding to appropriate instance of esp-netif

components/tcpip_adapter/tcpip_adapter_compat.c

@@ -200,6 +200,11 @@ esp_err_t tcpip_adapter_get_ip6_linklocal(tcpip_adapter_if_t tcpip_if, ip6_addr_
     return esp_netif_get_ip6_linklocal(netif_from_if(tcpip_if), (esp_ip6_addr_t*)if_ip6);
 }
 
+esp_err_t tcpip_adapter_get_ip6_global(tcpip_adapter_if_t tcpip_if, ip6_addr_t *if_ip6)
+{
+    return esp_netif_get_ip6_global(netif_from_if(tcpip_if), (esp_ip6_addr_t*)if_ip6);
+}
+
 esp_err_t tcpip_adapter_dhcpc_get_status(tcpip_adapter_if_t tcpip_if, tcpip_adapter_dhcp_status_t *status)
 {
     return esp_netif_dhcpc_get_status(netif_from_if(tcpip_if), status);

docs/en/api-reference/system/system.rst

@@ -34,9 +34,11 @@ When Wi-Fi or Bluetooth are enabled, numbers returned by hardware random number
 MAC Address
 -----------
 
-These APIs allow querying and customizing MAC addresses used by Wi-Fi, Bluetooth, and Ethernet drivers.
+These APIs allow querying and customizing MAC addresses for different network interfaces that supported (e.g. Wi-Fi, Bluetooth, Ethernet).
 
-ESP32 has up to 4 network interfaces: Wi-Fi station, Wi-Fi AP, Ethernet, and Bluetooth. Each of these interfaces needs to have a MAC address assigned to it. In ESP-IDF these addresses are calculated from *Base MAC address*. Base MAC address can be initialized with factory-programmed value from EFUSE, or with a user-defined value. In addition to setting the base MAC address, applications can specify the way in which MAC addresses are allocated to devices. See `Number of universally administered MAC address`_ section for more details.
+In ESP-IDF these addresses are calculated from *Base MAC address*. Base MAC address can be initialized with factory-programmed value from internal eFuse, or with a user-defined value. In addition to setting the base MAC address, applications can specify the way in which MAC addresses are allocated to devices. See `Number of universally administered MAC address`_ section for more details.
+
+For ESP32:
 
 +---------------+--------------------------------+----------------------------------+
 | Interface     | MAC address                    | MAC address                      |
@@ -52,20 +54,32 @@ ESP32 has up to 4 network interfaces: Wi-Fi station, Wi-Fi AP, Ethernet, and Blu
 |               |                                | first octet randomized           |
 +---------------+--------------------------------+----------------------------------+
 
+For ESP32-S2:
+
++---------------+--------------------------------+----------------------------------+
+| Interface     | MAC address                    | MAC address                      |
+|               | (2 universally administered)   | (1 universally administered)     |
++===============+================================+==================================+
+| Wi-Fi Station | base_mac                       | base_mac                         |
++---------------+--------------------------------+----------------------------------+
+| Wi-Fi SoftAP  | base_mac, +1 to the last octet | base_mac, first octet randomized |
++---------------+--------------------------------+----------------------------------+
 
 Base MAC address
 ^^^^^^^^^^^^^^^^
 
-Wi-Fi, Bluetooth, and Ethernet drivers use :cpp:func:`esp_read_mac` function to get MAC address for a specific interface.
+To fetch MAC address for a specific interface (e.g. Wi-Fi, Bluetooth, Ethernet), you can simply use :cpp:func:`esp_read_mac` function.
 
-By default, this function will use MAC address factory programmed in BLK0 of EFUSE as the base MAC address. MAC addresses of each interface will be calculated according to the table above.
+By default, this function takes the eFuse value burned at a pre-defined block (e.g. BLK0 for ESP32, BLK1 for ESP32-S2) as the base MAC address. Per-interface MAC addresses will be calculated according to the table above.
 
-Applications which don't use MAC address factory programmed into BLK0 of EFUSE can modify base MAC address used by :cpp:func:`esp_read_mac` using a call to :cpp:func:`esp_base_mac_addr_set`. Custom value of MAC address can come from application defined storage, such as Flash, NVS, etc. Note that the call to :cpp:func:`esp_base_mac_addr_set` needs to happen before network protocol stacks are initialized, for example, early in ``app_main``.
+Applications who want to customize base MAC address (not the one provided by Espressif) should call :cpp:func:`esp_base_mac_addr_set` before :cpp:func:`esp_read_mac`. The customized MAC address can be stored in any supported storage device (e.g. Flash, NVS, etc).
 
-Custom MAC address in BLK3 of EFUSE
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Note that, calls to :cpp:func:`esp_base_mac_addr_set` should take place before the initialization of network stack, for example, early in ``app_main``.
 
-To facilitate usage of custom MAC addresses, ESP-IDF provides :cpp:func:`esp_efuse_mac_get_custom` function, which loads MAC address from BLK3 of EFUSE. This function assumes that custom MAC address is stored in BLK3 of EFUSE (EFUSE_BLK3_RDATA0,  EFUSE_BLK3_RDATA1, EFUSE_BLK3_RDATA2, EFUSE_BLK3_RDATA3, EFUSE_BLK3_RDATA4, EFUSE_BLK3_RDATA5 registers) in the following format:
+Custom MAC address in eFuse
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To facilitate the usage of custom MAC addresses, ESP-IDF provides :cpp:func:`esp_efuse_mac_get_custom` function, which loads MAC address from internal pre-defined eFuse block (e.g. BLK3 for ESP32). This function assumes that custom MAC address is stored in the following format:
 
 +-----------------+-----------+---------------+------------------------------+
 | Field           | # of bits | Range of bits | Notes                        |
@@ -85,13 +99,13 @@ Once MAC address has been obtained using :cpp:func:`esp_efuse_mac_get_custom`, c
 Number of universally administered MAC address
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Serveral MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (Wi-Fi/BT/Ethernet). The final octet of each universally administered MAC address increases by one. Only the first one of them (which is called base MAC address) is stored in EFUSE or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address.
+Several MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (Wi-Fi/BT/Ethernet). The final octet of each universally administered MAC address increases by one. Only the first one of them (which is called base MAC address) is stored in eFuse or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address.
 
 If the universally administered MAC addresses are not enough for all of the networking interfaces, locally administered MAC addresses which are derived from universally administered MAC addresses are assigned to the rest of networking interfaces. 
 
 See `this article <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_ for the definition of local and universally administered MAC addresses.
 
-The number of universally administered MAC address can be configured using :ref:`CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES`.
+The number of universally administered MAC address can be configured using :ref:`CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES` for ESP32.
 
 If the number of universal MAC addresses is two, only two interfaces (Wi-Fi Station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (Wi-Fi SoftAP and Ethernet) receive local MAC addresses. These are derived from the universal Wi-Fi station and Bluetooth MAC addresses, respectively.
 
@@ -99,6 +113,10 @@ If the number of universal MAC addresses is four, all four interfaces (Wi-Fi Sta
 
 When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.)
 
+.. todo::
+
+   Add illustration for ESP32-S2 when multi-target doc feature is ready.
+
 Chip version
 ------------
 

docs/en/contribute/style-guide.rst

@@ -194,7 +194,7 @@ The same rules as for C apply. Where they are not enough, apply the following ru
 
 File Naming
 ^^^^^^^^^^^^
-C++ Header files have the extension ``.h``. C++ source files have the extension ``.cpp``, which is important for the compiler to distiguish them from normal C source files.
+C++ Header files have the extension ``.hpp``. C++ source files have the extension ``.cpp``. The latter is important for the compiler to distiguish them from normal C source files.
 
 Naming
 ^^^^^^
@@ -202,11 +202,39 @@ Naming
 * **Class and struct** names shall be written in ``CamelCase`` with a capital letter as beginning. Member variables and methods shall be in ``snake_case``.
 * **Namespaces** shall be in lower ``snake_case``.
 * **Templates** are specified in the line above the function declaration.
+* Interfaces in terms of Object-Oriented Programming shall be named without the suffix ``...Interface``. Later, this makes it easier to extract interfaces from normal classes and vice versa without making a breaking change.
 
 Member Order in Classes
 ^^^^^^^^^^^^^^^^^^^^^^^
+In order of precedence:
 
-First put the public members, then the protected, then private ones. Omit public, protected or private sections without any members.
+* First put the public members, then the protected, then private ones. Omit public, protected or private sections without any members.
+* First put constructors/destructors, then member functions, then member variables.
+
+For example:
+
+::
+
+    class ForExample {
+    public:
+        // first constructors, then default constructor, then destructor
+        ForExample(double example_factor_arg);
+        ForExample();
+        ~ForExample();
+
+        // then remaining pubic methods
+        set_example_factor(double example_factor_arg);
+
+        // then public member variables
+        uint32_t public_data_member;
+
+    private:
+        // first private methods
+        void internal_method();
+
+        // then private member variables
+        double example_factor;
+    };
 
 Spacing
 ^^^^^^^

make/version.mk

@@ -1,3 +1,3 @@
 IDF_VERSION_MAJOR := 4
-IDF_VERSION_MINOR := 1
+IDF_VERSION_MINOR := 2
 IDF_VERSION_PATCH := 0

tools/cmake/version.cmake

@@ -1,3 +1,3 @@
 set(IDF_VERSION_MAJOR 4)
-set(IDF_VERSION_MINOR 1)
+set(IDF_VERSION_MINOR 2)
 set(IDF_VERSION_PATCH 0)