alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

newlib: update newlib nano documentation for C6

Browse Source 
C6 ROM has the the full IO formatting functions included.
This commit is contained in:
Marius Vikhammer 2023-02-02 17:24:31 +08:00
parent 990c6f58a6
commit 65a4058e8c
19 changed files with 68 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
components/esp_rom/esp32/Kconfig.soc_caps.in
View File

@ -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

1
components/esp_rom/esp32/esp_rom_caps.h
View File

@ -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

4
components/esp_rom/esp32c2/Kconfig.soc_caps.in
View File

@ -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

1
components/esp_rom/esp32c2/esp_rom_caps.h
View File

@ -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

4
components/esp_rom/esp32c3/Kconfig.soc_caps.in
View File

@ -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

1
components/esp_rom/esp32c3/esp_rom_caps.h
View File

@ -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

4
components/esp_rom/esp32c6/Kconfig.soc_caps.in
View File

@ -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

3
components/esp_rom/esp32c6/esp_rom_caps.h
View File

@ -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)

4
components/esp_rom/esp32h2/Kconfig.soc_caps.in
View File

@ -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

1
components/esp_rom/esp32h2/esp_rom_caps.h
View File

@ -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

4
components/esp_rom/esp32h4/Kconfig.soc_caps.in
View File

@ -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

1
components/esp_rom/esp32h4/esp_rom_caps.h
View File

@ -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

4
components/esp_rom/esp32s2/Kconfig.soc_caps.in
View File

@ -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

1
components/esp_rom/esp32s2/esp_rom_caps.h
View File

@ -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

4
components/esp_rom/esp32s3/Kconfig.soc_caps.in
View File

@ -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

1
components/esp_rom/esp32s3/esp_rom_caps.h
View File

@ -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

15
components/newlib/Kconfig
View File

@ -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.

13
components/newlib/test/test_newlib.c
View File

@ -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]")

13
docs/en/api-guides/performance/size.rst
View File

@ -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`_.