Merge branch 'feature/c6_newlib_nano' into 'master'

newlib: update newlib nano documentation for C6

See merge request espressif/esp-idf!22219

components/esp_rom/esp32/Kconfig.soc_caps.in

@@ -26,3 +26,7 @@ config ESP_ROM_HAS_UART_BUF_SWITCH
 config ESP_ROM_NEEDS_SWSETUP_WORKAROUND
     bool
     default y
+
+config ESP_ROM_HAS_NEWLIB_NANO_FORMAT
+    bool
+    default y

components/esp_rom/esp32/esp_rom_caps.h

@@ -12,3 +12,4 @@
 #define ESP_ROM_HAS_JPEG_DECODE         (1) // ROM has JPEG decode library
 #define ESP_ROM_HAS_UART_BUF_SWITCH     (1) // ROM has exported the uart buffer switch function
 #define ESP_ROM_NEEDS_SWSETUP_WORKAROUND    (1) // ROM uses 32-bit time_t. A workaround is required to prevent printf functions from crashing
+#define ESP_ROM_HAS_NEWLIB_NANO_FORMAT  (1) // ROM has the newlib nano version of formatting functions

components/esp_rom/esp32c2/Kconfig.soc_caps.in

@@ -50,3 +50,7 @@ config ESP_ROM_HAS_LAYOUT_TABLE
 config ESP_ROM_HAS_SPI_FLASH
     bool
     default y
+
+config ESP_ROM_HAS_NEWLIB_NANO_FORMAT
+    bool
+    default y

components/esp_rom/esp32c2/esp_rom_caps.h

@@ -18,3 +18,4 @@
 #define ESP_ROM_TLSF_CHECK_PATCH            (1) // ROM does not contain the patch of tlsf_check()
 #define ESP_ROM_HAS_LAYOUT_TABLE            (1) // ROM has the layout table
 #define ESP_ROM_HAS_SPI_FLASH               (1) // ROM has the implementation of SPI Flash driver
+#define ESP_ROM_HAS_NEWLIB_NANO_FORMAT      (1) // ROM has the newlib nano version of formatting functions

components/esp_rom/esp32c3/Kconfig.soc_caps.in

@@ -54,3 +54,7 @@ config ESP_ROM_HAS_SPI_FLASH
 config ESP_ROM_HAS_ETS_PRINTF_BUG
     bool
     default y
+
+config ESP_ROM_HAS_NEWLIB_NANO_FORMAT
+    bool
+    default y

components/esp_rom/esp32c3/esp_rom_caps.h

@@ -19,3 +19,4 @@
 #define ESP_ROM_HAS_LAYOUT_TABLE            (1) // ROM has the layout table
 #define ESP_ROM_HAS_SPI_FLASH               (1) // ROM has the implementation of SPI Flash driver
 #define ESP_ROM_HAS_ETS_PRINTF_BUG          (1) // ROM has ets_printf bug when disable the ROM log either by eFuse or RTC storage register
+#define ESP_ROM_HAS_NEWLIB_NANO_FORMAT      (1) // ROM has the newlib nano version of formatting functions

components/esp_rom/esp32c6/Kconfig.soc_caps.in

@@ -58,3 +58,7 @@ config ESP_ROM_HAS_SPI_FLASH
 config ESP_ROM_HAS_REGI2C_BUG
     bool
     default y
+
+config ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT
+    bool
+    default y

components/esp_rom/esp32c6/esp_rom_caps.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -20,3 +20,4 @@
 #define ESP_ROM_HAS_LAYOUT_TABLE            (1) // ROM has the layout table
 #define ESP_ROM_HAS_SPI_FLASH               (1) // ROM has the implementation of SPI Flash driver
 #define ESP_ROM_HAS_REGI2C_BUG              (1) // ROM has the regi2c bug
+#define ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT    (1) // ROM has the newlib normal/full version of formatting functions (as opposed to the nano versions)

components/esp_rom/esp32h2/Kconfig.soc_caps.in

@@ -50,3 +50,7 @@ config ESP_ROM_HAS_SPI_FLASH
 config ESP_ROM_WITHOUT_REGI2C
     bool
     default y
+
+config ESP_ROM_HAS_NEWLIB_NANO_FORMAT
+    bool
+    default y

components/esp_rom/esp32h2/esp_rom_caps.h

@@ -18,3 +18,4 @@
 #define ESP_ROM_HAS_LAYOUT_TABLE            (1) // ROM has the layout table
 #define ESP_ROM_HAS_SPI_FLASH               (1) // ROM has the implementation of SPI Flash driver
 #define ESP_ROM_WITHOUT_REGI2C              (1) // ROM has no regi2c APIs
+#define ESP_ROM_HAS_NEWLIB_NANO_FORMAT      (1) // ROM has the newlib nano versions of formatting functions

components/esp_rom/esp32h4/Kconfig.soc_caps.in

@@ -46,3 +46,7 @@ config ESP_ROM_HAS_LAYOUT_TABLE
 config ESP_ROM_HAS_ETS_PRINTF_BUG
     bool
     default y
+
+config ESP_ROM_HAS_NEWLIB_NANO_FORMAT
+    bool
+    default y

components/esp_rom/esp32h4/esp_rom_caps.h

@@ -17,3 +17,4 @@
 #define ESP_ROM_GET_CLK_FREQ                (1) // Get clk frequency with rom function `ets_get_cpu_frequency`
 #define ESP_ROM_HAS_LAYOUT_TABLE            (1) // ROM has the layout table
 #define ESP_ROM_HAS_ETS_PRINTF_BUG          (1) // ROM has ets_printf bug when disable the ROM log either by eFuse or RTC storage register
+#define ESP_ROM_HAS_NEWLIB_NANO_FORMAT      (1) // ROM has the newlib nano version of formatting functions

components/esp_rom/esp32s2/Kconfig.soc_caps.in

@@ -22,3 +22,7 @@ config ESP_ROM_NEEDS_SWSETUP_WORKAROUND
 config ESP_ROM_HAS_REGI2C_BUG
     bool
     default y
+
+config ESP_ROM_HAS_NEWLIB_NANO_FORMAT
+    bool
+    default y

components/esp_rom/esp32s2/esp_rom_caps.h

@@ -11,3 +11,4 @@
 #define ESP_ROM_HAS_UART_BUF_SWITCH         (1) // ROM has exported the uart buffer switch function
 #define ESP_ROM_NEEDS_SWSETUP_WORKAROUND    (1) // ROM uses 32-bit time_t. A workaround is required to prevent printf functions from crashing
 #define ESP_ROM_HAS_REGI2C_BUG              (1) // ROM has the regi2c bug
+#define ESP_ROM_HAS_NEWLIB_NANO_FORMAT      (1) // ROM has the newlib nano version of formatting functions

components/esp_rom/esp32s3/Kconfig.soc_caps.in

@@ -58,3 +58,7 @@ config ESP_ROM_HAS_SPI_FLASH
 config ESP_ROM_HAS_ETS_PRINTF_BUG
     bool
     default y
+
+config ESP_ROM_HAS_NEWLIB_NANO_FORMAT
+    bool
+    default y

components/esp_rom/esp32s3/esp_rom_caps.h

@@ -20,3 +20,4 @@
 #define ESP_ROM_HAS_LAYOUT_TABLE            (1) // ROM has the layout table
 #define ESP_ROM_HAS_SPI_FLASH               (1) // ROM has the implementation of SPI Flash driver
 #define ESP_ROM_HAS_ETS_PRINTF_BUG          (1) // ROM has ets_printf bug when disable the ROM log either by eFuse or RTC storage register
+#define ESP_ROM_HAS_NEWLIB_NANO_FORMAT      (1) // ROM has the newlib nano version of formatting functions

components/newlib/Kconfig

@@ -52,7 +52,7 @@ menu "Newlib"
         bool "Enable 'nano' formatting options for printf/scanf family"
         default y if IDF_TARGET_ESP32C2
         help
-            ESP32 ROM contains parts of newlib C library, including printf/scanf family
+            In most chips the ROM contains parts of newlib C library, including printf/scanf family
             of functions. These functions have been compiled with so-called "nano"
             formatting option. This option doesn't support 64-bit integer formats and C99
             features, such as positional arguments.
@@ -61,10 +61,15 @@ menu "Newlib"
             search for '--enable-newlib-nano-formatted-io':
             https://sourceware.org/newlib/README
 
-            If this option is enabled, build system will use functions available in
-            ROM, reducing the application binary size. Functions available in ROM run
-            faster than functions which run from flash. Functions available in ROM can
-            also run when flash instruction cache is disabled.
+            If this option is enabled and the ROM contains functions from newlib-nano, the build system
+            will use functions available in ROM, reducing the application binary size.
+            Functions available in ROM run faster than functions which run from flash. Functions available
+            in ROM can also run when flash instruction cache is disabled.
+
+            Some chips (e.g. ESP32-C6) has the full formatting versions of printf/scanf in ROM instead of
+            the nano versions and in this building with newlib nano might actually increase the size of
+            the binary. Which functions are present in ROM can be seen from ROM caps:
+            ESP_ROM_HAS_NEWLIB_NANO_FORMAT and ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT.
 
             If you need 64-bit integer formatting support or C99 features, keep this
             option disabled.

components/newlib/test/test_newlib.c

@@ -14,6 +14,7 @@
 #include "unity.h"
 #include "sdkconfig.h"
 #include "soc/soc.h"
+#include "esp_rom_caps.h"
 
 TEST_CASE("test ctype functions", "[newlib]")
 {
@@ -122,7 +123,7 @@ TEST_CASE("test asctime", "[newlib]")
     TEST_ASSERT_EQUAL_STRING(buf, time_str);
 }
 
-#if !TEMPORARY_DISABLED_FOR_TARGETS(ESP32C6, ESP32H2)
+#if !TEMPORARY_DISABLED_FOR_TARGETS(ESP32H2)
 static bool fn_in_rom(void *fn)
 {
     const int fnaddr = (int)fn;
@@ -132,17 +133,17 @@ static bool fn_in_rom(void *fn)
 
 TEST_CASE("check if ROM or Flash is used for functions", "[newlib]")
 {
-#if CONFIG_NEWLIB_NANO_FORMAT
+#if CONFIG_NEWLIB_NANO_FORMAT || ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT
     TEST_ASSERT(fn_in_rom(vfprintf));
 #else
     TEST_ASSERT_FALSE(fn_in_rom(vfprintf));
-#endif // CONFIG_NEWLIB_NANO_FORMAT
+#endif // CONFIG_NEWLIB_NANO_FORMAT || ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT
 
-#if CONFIG_NEWLIB_NANO_FORMAT && (CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32C2 || CONFIG_IDF_TARGET_ESP32H4)
+#if (CONFIG_NEWLIB_NANO_FORMAT && (CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32C2 || CONFIG_IDF_TARGET_ESP32H4)) || ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT
     TEST_ASSERT(fn_in_rom(sscanf));
 #else
     TEST_ASSERT_FALSE(fn_in_rom(sscanf));
-#endif // CONFIG_NEWLIB_NANO_FORMAT && CONFIG_IDF_TARGET_x
+#endif // (CONFIG_NEWLIB_NANO_FORMAT && CONFIG_IDF_TARGET_x) || ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT
 
 #if defined(CONFIG_IDF_TARGET_ESP32) && !defined(CONFIG_SPIRAM)
     TEST_ASSERT(fn_in_rom(atoi));
@@ -158,7 +159,7 @@ TEST_CASE("check if ROM or Flash is used for functions", "[newlib]")
     TEST_ASSERT_FALSE(fn_in_rom(strtol));
 #endif // defined(CONFIG_IDF_TARGET_ESP32) && !defined(CONFIG_SPIRAM)
 }
-#endif //!TEMPORARY_DISABLED_FOR_TARGETS(ESP32C6, ESP32H2)
+#endif //!TEMPORARY_DISABLED_FOR_TARGETS(ESP32H2)
 
 #ifndef CONFIG_NEWLIB_NANO_FORMAT
 TEST_CASE("test 64bit int formats", "[newlib]")

docs/en/api-guides/performance/size.rst

@@ -352,6 +352,7 @@ lwIP IPv6
 
       IPv6 is required by some components such as ``coap`` and :doc:`/api-reference/protocols/asio`, These components will not be available if IPV6 is disabled.
 
+
 .. _newlib-nano-formatting:
 
 Newlib nano formatting
@@ -359,11 +360,17 @@ Newlib nano formatting
 
 By default, ESP-IDF uses newlib "full" formating for I/O (printf, scanf, etc.)
 
-Enabling the config option :ref:`CONFIG_NEWLIB_NANO_FORMAT` will switch newlib to the "nano" formatting mode. This both smaller in code size and a large part of the implementation is compiled into the {IDF_TARGET_NAME} ROM, so it doesn't need to be included in the binary at all.
+.. only:: CONFIG_ESP_ROM_HAS_NEWLIB_NANO_FORMAT
+
+    Enabling the config option :ref:`CONFIG_NEWLIB_NANO_FORMAT` will switch newlib to the "nano" formatting mode. This both smaller in code size and a large part of the implementation is compiled into the {IDF_TARGET_NAME} ROM, so it doesn't need to be included in the binary at all.
+
+    The exact difference in binary size depends on which features the firmware uses, but 25 KB ~ 50 KB is typical.
+
+.. only:: CONFIG_ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT
 
-The exact difference in binary size depends on which features the firmware uses, but 25 KB ~ 50 KB is typical.
+    Disabling the config option :ref:`CONFIG_NEWLIB_NANO_FORMAT` will switch newlib to the "full" formatting mode. This will reduce the binary size, as {IDF_TARGET_NAME} has the full formatting version of the functions in ROM,  so it doesn't need to be included in the binary at all.
 
-Enabling Nano formatting also reduces the stack usage of each function that calls printf() or another string formatting function, see :ref:`optimize-stack-sizes`.
+Enabling Nano formatting reduces the stack usage of each function that calls printf() or another string formatting function, see :ref:`optimize-stack-sizes`.
 
 "Nano" formatting doesn't support 64-bit integers, or C99 formatting features. For a full list of restrictions, search for ``--enable-newlib-nano-formatted-io`` in the `Newlib README file`_.