From 65a4058e8c5494e3751851889e4d69a36a24988c Mon Sep 17 00:00:00 2001
From: Marius Vikhammer <marius.vikhammer@espressif.com>
Date: Thu, 2 Feb 2023 17:24:31 +0800
Subject: [PATCH] newlib: update newlib nano documentation for C6

C6 ROM has the the full IO formatting functions included.
---
 components/esp_rom/esp32/Kconfig.soc_caps.in   |  4 ++++
 components/esp_rom/esp32/esp_rom_caps.h        |  1 +
 components/esp_rom/esp32c2/Kconfig.soc_caps.in |  4 ++++
 components/esp_rom/esp32c2/esp_rom_caps.h      |  1 +
 components/esp_rom/esp32c3/Kconfig.soc_caps.in |  4 ++++
 components/esp_rom/esp32c3/esp_rom_caps.h      |  1 +
 components/esp_rom/esp32c6/Kconfig.soc_caps.in |  4 ++++
 components/esp_rom/esp32c6/esp_rom_caps.h      |  3 ++-
 components/esp_rom/esp32h2/Kconfig.soc_caps.in |  4 ++++
 components/esp_rom/esp32h2/esp_rom_caps.h      |  1 +
 components/esp_rom/esp32h4/Kconfig.soc_caps.in |  4 ++++
 components/esp_rom/esp32h4/esp_rom_caps.h      |  1 +
 components/esp_rom/esp32s2/Kconfig.soc_caps.in |  4 ++++
 components/esp_rom/esp32s2/esp_rom_caps.h      |  1 +
 components/esp_rom/esp32s3/Kconfig.soc_caps.in |  4 ++++
 components/esp_rom/esp32s3/esp_rom_caps.h      |  1 +
 components/newlib/Kconfig                      | 15 ++++++++++-----
 components/newlib/test/test_newlib.c           | 13 +++++++------
 docs/en/api-guides/performance/size.rst        | 13 ++++++++++---
 19 files changed, 68 insertions(+), 15 deletions(-)

diff --git a/components/esp_rom/esp32/Kconfig.soc_caps.in b/components/esp_rom/esp32/Kconfig.soc_caps.in
index 86fdf8cab2..c53676fa51 100644
--- a/components/esp_rom/esp32/Kconfig.soc_caps.in
+++ b/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
diff --git a/components/esp_rom/esp32/esp_rom_caps.h b/components/esp_rom/esp32/esp_rom_caps.h
index a0e23d79aa..e9473e4f23 100644
--- a/components/esp_rom/esp32/esp_rom_caps.h
+++ b/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
diff --git a/components/esp_rom/esp32c2/Kconfig.soc_caps.in b/components/esp_rom/esp32c2/Kconfig.soc_caps.in
index 295c811d1c..1160680f5e 100644
--- a/components/esp_rom/esp32c2/Kconfig.soc_caps.in
+++ b/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
diff --git a/components/esp_rom/esp32c2/esp_rom_caps.h b/components/esp_rom/esp32c2/esp_rom_caps.h
index 39db7a94f6..302f85b320 100644
--- a/components/esp_rom/esp32c2/esp_rom_caps.h
+++ b/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
diff --git a/components/esp_rom/esp32c3/Kconfig.soc_caps.in b/components/esp_rom/esp32c3/Kconfig.soc_caps.in
index ed88d6d9f3..1c3af487c5 100644
--- a/components/esp_rom/esp32c3/Kconfig.soc_caps.in
+++ b/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
diff --git a/components/esp_rom/esp32c3/esp_rom_caps.h b/components/esp_rom/esp32c3/esp_rom_caps.h
index cb1c9bd983..ab81bb0fd0 100644
--- a/components/esp_rom/esp32c3/esp_rom_caps.h
+++ b/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
diff --git a/components/esp_rom/esp32c6/Kconfig.soc_caps.in b/components/esp_rom/esp32c6/Kconfig.soc_caps.in
index 0414f5df3f..10f70c6d8d 100644
--- a/components/esp_rom/esp32c6/Kconfig.soc_caps.in
+++ b/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
diff --git a/components/esp_rom/esp32c6/esp_rom_caps.h b/components/esp_rom/esp32c6/esp_rom_caps.h
index 16c1404435..6fed38d523 100644
--- a/components/esp_rom/esp32c6/esp_rom_caps.h
+++ b/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)
diff --git a/components/esp_rom/esp32h2/Kconfig.soc_caps.in b/components/esp_rom/esp32h2/Kconfig.soc_caps.in
index ab763d79c9..8695360d3e 100644
--- a/components/esp_rom/esp32h2/Kconfig.soc_caps.in
+++ b/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
diff --git a/components/esp_rom/esp32h2/esp_rom_caps.h b/components/esp_rom/esp32h2/esp_rom_caps.h
index 19bb4d9318..311834e4b9 100644
--- a/components/esp_rom/esp32h2/esp_rom_caps.h
+++ b/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
diff --git a/components/esp_rom/esp32h4/Kconfig.soc_caps.in b/components/esp_rom/esp32h4/Kconfig.soc_caps.in
index cc5c4ed447..4fe0f15e6d 100644
--- a/components/esp_rom/esp32h4/Kconfig.soc_caps.in
+++ b/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
diff --git a/components/esp_rom/esp32h4/esp_rom_caps.h b/components/esp_rom/esp32h4/esp_rom_caps.h
index 191bd002cd..32f210e3e4 100644
--- a/components/esp_rom/esp32h4/esp_rom_caps.h
+++ b/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
diff --git a/components/esp_rom/esp32s2/Kconfig.soc_caps.in b/components/esp_rom/esp32s2/Kconfig.soc_caps.in
index 67570aee00..6abec76432 100644
--- a/components/esp_rom/esp32s2/Kconfig.soc_caps.in
+++ b/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
diff --git a/components/esp_rom/esp32s2/esp_rom_caps.h b/components/esp_rom/esp32s2/esp_rom_caps.h
index be891dcc44..4e01c0d44f 100644
--- a/components/esp_rom/esp32s2/esp_rom_caps.h
+++ b/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
diff --git a/components/esp_rom/esp32s3/Kconfig.soc_caps.in b/components/esp_rom/esp32s3/Kconfig.soc_caps.in
index 6a468a7f5f..14684fe262 100644
--- a/components/esp_rom/esp32s3/Kconfig.soc_caps.in
+++ b/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
diff --git a/components/esp_rom/esp32s3/esp_rom_caps.h b/components/esp_rom/esp32s3/esp_rom_caps.h
index 6ec111305b..c716de7613 100644
--- a/components/esp_rom/esp32s3/esp_rom_caps.h
+++ b/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
diff --git a/components/newlib/Kconfig b/components/newlib/Kconfig
index 9e6cefdc27..43f28bc953 100644
--- a/components/newlib/Kconfig
+++ b/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.
diff --git a/components/newlib/test/test_newlib.c b/components/newlib/test/test_newlib.c
index 90e546fcef..6c1160ea16 100644
--- a/components/newlib/test/test_newlib.c
+++ b/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]")
diff --git a/docs/en/api-guides/performance/size.rst b/docs/en/api-guides/performance/size.rst
index 603f72ac6f..18ce30b4b7 100644
--- a/docs/en/api-guides/performance/size.rst
+++ b/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
 
-The exact difference in binary size depends on which features the firmware uses, but 25 KB ~ 50 KB is typical.
+    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.
 
-Enabling Nano formatting also reduces the stack usage of each function that calls printf() or another string formatting function, see :ref:`optimize-stack-sizes`.
+    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
+
+    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 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`_.