diff --git a/components/esp_hw_support/port/esp32/Kconfig.rtc b/components/esp_hw_support/port/esp32/Kconfig.rtc index a2dd64dfb6..117edae8ae 100644 --- a/components/esp_hw_support/port/esp32/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32/Kconfig.rtc @@ -22,7 +22,7 @@ choice RTC_CLK_SRC the internal 150kHz oscillator. It does not require external components. config RTC_CLK_SRC_INT_RC - bool "Internal 150kHz RC oscillator" + bool "Internal 150 kHz RC oscillator" config RTC_CLK_SRC_EXT_CRYS bool "External 32kHz crystal" select ESP_SYSTEM_RTC_EXT_XTAL diff --git a/components/esp_hw_support/port/esp32c6/Kconfig.rtc b/components/esp_hw_support/port/esp32c6/Kconfig.rtc index 297ffc1c4a..e58391029c 100644 --- a/components/esp_hw_support/port/esp32c6/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32c6/Kconfig.rtc @@ -5,7 +5,7 @@ choice RTC_CLK_SRC Choose which clock is used as RTC clock source. config RTC_CLK_SRC_INT_RC - bool "Internal 136kHz RC oscillator" + bool "Internal 150 kHz RC oscillator" config RTC_CLK_SRC_EXT_CRYS bool "External 32kHz crystal" select ESP_SYSTEM_RTC_EXT_XTAL diff --git a/components/esp_hw_support/port/esp32h2/Kconfig.rtc b/components/esp_hw_support/port/esp32h2/Kconfig.rtc index 297ffc1c4a..e58391029c 100644 --- a/components/esp_hw_support/port/esp32h2/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32h2/Kconfig.rtc @@ -5,7 +5,7 @@ choice RTC_CLK_SRC Choose which clock is used as RTC clock source. config RTC_CLK_SRC_INT_RC - bool "Internal 136kHz RC oscillator" + bool "Internal 150 kHz RC oscillator" config RTC_CLK_SRC_EXT_CRYS bool "External 32kHz crystal" select ESP_SYSTEM_RTC_EXT_XTAL diff --git a/components/esp_hw_support/port/esp32p4/Kconfig.rtc b/components/esp_hw_support/port/esp32p4/Kconfig.rtc index 70c41dbe23..0ca1162422 100644 --- a/components/esp_hw_support/port/esp32p4/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32p4/Kconfig.rtc @@ -7,7 +7,7 @@ choice RTC_CLK_SRC Choose which clock is used as RTC clock source. config RTC_CLK_SRC_INT_RC - bool "Internal 136kHz RC oscillator" + bool "Internal 150 kHz RC oscillator" config RTC_CLK_SRC_EXT_CRYS bool "External 32kHz crystal" select ESP_SYSTEM_RTC_EXT_XTAL diff --git a/docs/conf_common.py b/docs/conf_common.py index 9cab72ef59..1fe98a04bb 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -68,7 +68,8 @@ WIFI_DOCS = ['api-guides/wifi.rst', 'api-reference/network/esp_wifi.rst', 'api-reference/network/esp_dpp.rst', 'api-reference/provisioning/provisioning.rst', - 'api-reference/provisioning/wifi_provisioning.rst'] + 'api-reference/provisioning/wifi_provisioning.rst', + 'migration-guides/release-5.x/5.2/wifi.rst'] NAN_DOCS = ['api-reference/network/esp_nan.rst'] diff --git a/docs/docs_not_updated/esp32p4.txt b/docs/docs_not_updated/esp32p4.txt index d71d8a999c..3f457a2bf1 100644 --- a/docs/docs_not_updated/esp32p4.txt +++ b/docs/docs_not_updated/esp32p4.txt @@ -27,40 +27,24 @@ api-guides/tools/idf-monitor.rst api-guides/tools/idf-tools-notes.inc api-guides/tools/idf-docker-image.rst api-guides/tools/index.rst -api-guides/startup.rst -api-guides/hlinterrupts.rst api-guides/RF_calibration.rst -api-guides/unit-tests.rst api-guides/deep-sleep-stub.rst api-guides/lwip.rst api-guides/coexist.rst api-guides/flash_psram_config.rst api-guides/usb-serial-jtag-console.rst -api-guides/linker-script-generation.rst api-guides/wifi.rst api-guides/usb-otg-console.rst api-guides/wireshark-user-guide.rst -api-guides/bootloader.rst api-guides/esp-wifi-mesh.rst -api-guides/cplusplus.rst api-guides/SYSVIEW_FreeRTOS.txt -api-guides/build-system.rst api-guides/core_dump.rst -api-guides/inc/linux-host-requirements.rst api-guides/dfu.rst api-guides/current-consumption-measurement-modules.rst -api-guides/reproducible-builds.rst -api-guides/hardware-abstraction.rst api-guides/wifi-security.rst api-guides/host-apps.rst api-guides/index.rst api-guides/openthread.rst -api-guides/fatal-errors.rst -api-guides/memory-types.rst -api-guides/general-notes.rst -conf.py -api-reference/api-conventions.rst -api-reference/template.rst api-reference/provisioning/protocomm.rst api-reference/provisioning/provisioning.rst api-reference/provisioning/index.rst @@ -111,7 +95,6 @@ api-reference/peripherals/dedic_gpio.rst api-reference/peripherals/sd_pullup_requirements.rst api-reference/peripherals/index.rst api-reference/peripherals/uart.rst -api-reference/kconfig.rst api-reference/network/esp_openthread.rst api-reference/network/esp_eth.rst api-reference/network/esp_netif_driver.rst @@ -127,33 +110,16 @@ api-reference/system/sleep_modes.rst api-reference/system/ota.rst api-reference/system/app_trace.rst api-reference/system/ulp_macros.rst -api-reference/system/perfmon.rst api-reference/system/ulp-lp-core.rst api-reference/system/ulp.rst -api-reference/system/esp_function_with_shared_stack.rst api-reference/system/ulp_instruction_set.rst api-reference/system/random.rst -api-reference/system/esp_event.rst -api-reference/system/system_time.rst -api-reference/system/log.rst -api-reference/system/soc_caps.rst -api-reference/system/internal-unstable.rst -api-reference/system/app_image_format.rst -api-reference/system/himem.rst api-reference/system/power_management.rst -api-reference/system/mem_alloc.rst api-reference/system/misc_system_api.rst -api-reference/system/bootloader_image_format.rst api-reference/system/inc/power_management_esp32p4.rst -api-reference/system/heap_debug.rst api-reference/system/esp_https_ota.rst api-reference/system/ulp-risc-v.rst -api-reference/system/esp_err.rst -api-reference/system/console.rst api-reference/system/intr_alloc.rst -api-reference/system/index.rst -api-reference/system/pthread.rst -api-reference/error-codes.rst api-reference/index.rst api-reference/protocols/icmp_echo.rst api-reference/protocols/esp_serial_slave_link.rst @@ -175,11 +141,6 @@ security/flash-encryption.rst security/security.rst security/esp32p4_log.inc security/index.rst -migration-guides/release-5.x/5.2/protocols.rst -migration-guides/release-5.x/5.2/index.rst -migration-guides/release-5.x/5.2/peripherals.rst -migration-guides/index.rst -_templates/layout.html get-started/establish-serial-connection.rst get-started/linux-macos-setup.rst get-started/linux-macos-start-project.rst diff --git a/docs/en/api-guides/bootloader.rst b/docs/en/api-guides/bootloader.rst index 86d3061d4f..a28a74ac36 100644 --- a/docs/en/api-guides/bootloader.rst +++ b/docs/en/api-guides/bootloader.rst @@ -3,8 +3,6 @@ Bootloader :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"} - The ESP-IDF Software Bootloader performs the following functions: 1. Minimal initial configuration of internal modules; @@ -12,7 +10,7 @@ The ESP-IDF Software Bootloader performs the following functions: 3. Select the application partition to boot, based on the partition table and ota_data (if any); 4. Load this image to RAM (IRAM & DRAM) and transfer management to the image that was just loaded. -Bootloader is located at the address {IDF_TARGET_BOOTLOADER_OFFSET} in the flash. +Bootloader is located at the address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} in the flash. For a full description of the startup process including the ESP-IDF bootloader, see :doc:`startup`. @@ -95,10 +93,10 @@ In addition, the following configuration options control the reset condition: .. only:: SOC_RTC_FAST_MEM_SUPPORTED If an application needs to know if the factory reset has occurred, users can call the function :cpp:func:`bootloader_common_get_rtc_retain_mem_factory_reset_state`. - + - If the status is read as true, the function will return the status, indicating that the factory reset has occurred. The function then resets the status to false for subsequent factory reset judgement. - If the status is read as false, the function will return the status, indicating that the factory reset has not occurred, or the memory where this status is stored is invalid. - + Note that this feature reserves some RTC FAST memory (the same size as the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` feature). .. only:: not SOC_RTC_FAST_MEM_SUPPORTED diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index 7a7b18580a..ee23dd1567 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -282,7 +282,7 @@ The GDB prompt can be used to inspect CPU registers, local and static variables, RTC Watchdog Timeout -------------------- -{IDF_TARGET_RTCWDT_RTC_RESET:default="Not updated", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS"} +{IDF_TARGET_RTCWDT_RTC_RESET:default="Not updated", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS", esp32p4="LP_WDT_SYS"} The RTC watchdog is used in the startup code to keep track of execution time and it also helps to prevent a lock-up caused by an unstable power source. It is enabled by default (see :ref:`CONFIG_BOOTLOADER_WDT_ENABLE`). If the execution time is exceeded, the RTC watchdog will restart the system. In this case, the ROM bootloader will print a message with the ``RTC Watchdog Timeout`` reason for the reboot. diff --git a/docs/en/api-guides/linker-script-generation.rst b/docs/en/api-guides/linker-script-generation.rst index 1104101ef5..40e1d9d2b5 100644 --- a/docs/en/api-guides/linker-script-generation.rst +++ b/docs/en/api-guides/linker-script-generation.rst @@ -603,14 +603,3 @@ Then the corresponding excerpt from the generated linker script will be as follo Rule generated from the default scheme entry ``iram -> iram0_text``. Since the default scheme specifies an ``iram -> iram0_text`` entry, it too is placed wherever ``iram0_text`` is referenced by a marker. Since it is a rule generated from the default scheme, it comes first among all other rules collected under the same target name. The linker script template currently used is :component_file:`esp_system/ld/{IDF_TARGET_PATH_NAME}/sections.ld.in`; the generated output script ``sections.ld`` is put under its build directory. - -.. _ldgen-migrate-lf-grammar : - -Migrate to ESP-IDF v5.0 Linker Script Fragment Files Grammar -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The old grammar supported in ESP-IDF v3.x would be dropped in ESP-IDF v5.0. Here are a few notes on how to migrate properly: - -1. Now indentation is enforced and improperly indented fragment files would generate a runtime parse exception. This was not enforced in the old version but previous documentation and examples demonstrate properly indented grammar. -2. Migrate the old condition entry to the ``if...elif...else`` structure for conditionals. You can refer to the :ref:`earlier chapter ` for detailed grammar. -3. mapping fragments now requires a name like other fragment types. diff --git a/docs/en/api-guides/memory-types.rst b/docs/en/api-guides/memory-types.rst index f2ae0dc9d5..d56d6264ab 100644 --- a/docs/en/api-guides/memory-types.rst +++ b/docs/en/api-guides/memory-types.rst @@ -184,6 +184,14 @@ The ``DRAM_ATTR`` attribute can be used to force constants from DROM into the :r Remaining RTC FAST memory is added to the heap unless the option :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access. +.. only:: SOC_MEM_TCM_SUPPORTED + + TCM (Tightly-Coupled Memory) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + TCM is memory placed near the CPU, accessible at CPU frequency without passing through a cache. Even though on average, it may not surpass the efficiency or speed of cached memory, it does provide predictable and consistent access times. TCM can be useful for time-critical routines where having a deterministic access speed is important. + + DMA-Capable Requirement ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-guides/startup.rst b/docs/en/api-guides/startup.rst index db0903e19d..e0276986ea 100644 --- a/docs/en/api-guides/startup.rst +++ b/docs/en/api-guides/startup.rst @@ -3,13 +3,11 @@ Application Startup Flow :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"} - This note explains various steps which happen before ``app_main`` function of an ESP-IDF application is called. The high level view of startup process is as follows: -1. :ref:`first-stage-bootloader` in ROM loads second-stage bootloader image to RAM (IRAM & DRAM) from flash offset {IDF_TARGET_BOOTLOADER_OFFSET}. +1. :ref:`first-stage-bootloader` in ROM loads second-stage bootloader image to RAM (IRAM & DRAM) from flash offset {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}. 2. :ref:`second-stage-bootloader` loads partition table and main app image from flash. Main app incorporates both RAM segments and read-only segments mapped via flash cache. @@ -46,15 +44,19 @@ Startup code called from the reset vector determines the boot mode by checking ` .. only:: esp32 - Second stage bootloader binary image is loaded from flash starting at address 0x1000. If :doc:`/security/secure-boot-v1` is in use then the first 4 kB sector of flash is used to store secure boot IV and digest of the bootloader image. Otherwise, this sector is unused. + Second stage bootloader binary image is loaded from flash starting at address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}. If :doc:`/security/secure-boot-v1` is in use then the first 4 kB sector of flash is used to store secure boot IV and digest of the bootloader image. Otherwise, this sector is unused. .. only:: esp32s2 - Second stage bootloader binary image is loaded from flash starting at address 0x1000. The 4 kB sector of flash before this address is unused. + Second stage bootloader binary image is loaded from flash starting at address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}. The 4 kB sector of flash before this address is unused. -.. only:: not (esp32 or esp32s2) +.. only:: esp32p4 - Second stage bootloader binary image is loaded from the start of flash at offset 0x0. + Second stage bootloader binary image is loaded from flash starting at address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}. The 8 kB sector of flash before this address is reserved for the key manager for use with flash encryption (AES-XTS). + +.. only:: not (esp32 or esp32s2 or esp32p4) + + Second stage bootloader binary image is loaded from the start of flash at offset {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}. .. TODO: describe application binary image format, describe optional flash configuration commands. @@ -63,11 +65,11 @@ Startup code called from the reset vector determines the boot mode by checking ` Second Stage Bootloader ^^^^^^^^^^^^^^^^^^^^^^^ -In ESP-IDF, the binary image which resides at offset {IDF_TARGET_BOOTLOADER_OFFSET} in flash is the second stage bootloader. Second stage bootloader source code is available in :idf:`components/bootloader` directory of ESP-IDF. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place. +In ESP-IDF, the binary image which resides at offset {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} in flash is the second stage bootloader. Second stage bootloader source code is available in :idf:`components/bootloader` directory of ESP-IDF. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place. When the first stage bootloader is finished checking and loading the second stage bootloader, it jumps to the second stage bootloader entry point found in the binary image header. -Second stage bootloader reads the partition table found by default at offset 0x8000 (:ref:`configurable value `). See :doc:`partition tables ` documentation for more information. The bootloader finds factory and OTA app partitions. If OTA app partitions are found in the partition table, the bootloader consults the ``otadata`` partition to determine which one should be booted. See :doc:`/api-reference/system/ota` for more information. +Second stage bootloader reads the partition table found by default at offset {IDF_TARGET_CONFIG_PARTITION_TABLE_OFFSET} (:ref:`configurable value `). See :doc:`partition tables ` documentation for more information. The bootloader finds factory and OTA app partitions. If OTA app partitions are found in the partition table, the bootloader consults the ``otadata`` partition to determine which one should be booted. See :doc:`/api-reference/system/ota` for more information. For a full description of the configuration options available for the ESP-IDF bootloader, see :doc:`bootloader`. @@ -76,7 +78,7 @@ For the selected partition, second stage bootloader reads the binary image from - For segments with load addresses in internal :ref:`iram` or :ref:`dram`, the contents are copied from flash to the load address. - For segments which have load addresses in :ref:`drom` or :ref:`irom` regions, the flash MMU is configured to provide the correct mapping from the flash to the load address. -.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES +.. only:: esp32 Note that the second stage bootloader configures flash MMU for both PRO and APP CPUs, but it only enables flash MMU for PRO CPU. Reason for this is that second stage bootloader code is loaded into the memory region used by APP CPU cache. The duty of enabling cache for APP CPU is passed on to the application. @@ -112,7 +114,7 @@ This port-layer initialization function initializes the basic C Runtime Environm - Finish configuring the MMU cache. :SOC_SPIRAM_SUPPORTED: - Enable PSRAM if configured. - Set the CPU clocks to the frequencies configured for the project. - :CONFIG_ESP_SYSTEM_MEMPROT_FEATURE: - Initialize memory protection if configured. + :SOC_MEMPROT_SUPPORTED: - Initialize memory protection if configured. :esp32: - Reconfigure the main SPI flash based on the app header settings (necessary for compatibility with bootloader versions before ESP-IDF V4.0, see :ref:`bootloader-compatibility`). :SOC_HP_CPU_HAS_MULTIPLE_CORES: - If the app is configured to run on multiple cores, start the other core and wait for it to initialize as well (inside the similar "port layer" initialization function ``call_start_cpu1``). @@ -175,4 +177,4 @@ Unlike normal FreeRTOS tasks (or embedded C ``main`` functions), the ``app_main` The ``start_cpu_other_cores_default`` function does some core-specific system initialization and then waits for the PRO CPU to start the FreeRTOS scheduler, at which point it executes ``esp_startup_start_app_other_cores`` which is another weak-linked function defaulting to ``esp_startup_start_app_other_cores_default``. - By default ``esp_startup_start_app_other_cores_default`` does nothing but spin in a busy-waiting loop until the scheduler of the PRO CPU triggers an interrupt to start the RTOS scheduler on the APP CPU. \ No newline at end of file + By default ``esp_startup_start_app_other_cores_default`` does nothing but spin in a busy-waiting loop until the scheduler of the PRO CPU triggers an interrupt to start the RTOS scheduler on the APP CPU. diff --git a/docs/en/api-guides/unit-tests.rst b/docs/en/api-guides/unit-tests.rst index 84cc5e1000..de436d226c 100644 --- a/docs/en/api-guides/unit-tests.rst +++ b/docs/en/api-guides/unit-tests.rst @@ -185,6 +185,11 @@ Use menuconfig to set the serial port for flashing. For more information, see :i Running Unit Tests ------------------ +.. note:: + + We also provide the pytest-based framework `pytest-embedded `_ to help make running unit-tests more convenient and efficient. If you need to run tests in CI or run multiple tests in a row we recommend checking out this project. For more information see `Pytest-embedded Docs `_ and :doc:`/contribute/esp-idf-tests-with-pytest`. + + After flashing reset the {IDF_TARGET_NAME} and it will boot the unit test app. When unit test app is idle, press "Enter" will make it print test menu with all available tests:: diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 2d8f0182e1..7bfb9296d3 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -31,7 +31,10 @@ For more details on these internal memory types, see :ref:`memory-layout`. All DRAM memory is single-byte accessible, thus all DRAM heaps possess the ``MALLOC_CAP_8BIT`` capability. Users can call ``heap_caps_get_free_size(MALLOC_CAP_8BIT)`` to get the free size of all DRAM heaps. -If ran out of ``MALLOC_CAP_8BIT``, the users can use ``MALLOC_CAP_IRAM_8BIT`` instead. In that case, IRAM can still be used as a "reserve" pool of internal memory if the users only access it in a 32-bit aligned manner, or if they enable ``CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY)``. +.. only:: esp32 + + If ran out of ``MALLOC_CAP_8BIT``, the users can use ``MALLOC_CAP_IRAM_8BIT`` instead. In that case, IRAM can still be used as a "reserve" pool of internal memory if the users only access it in a 32-bit aligned manner, or if they enable ``CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY)``. + When calling ``malloc()``, the ESP-IDF ``malloc()`` internally calls ``heap_caps_malloc_default(size)``. This will allocate memory with the capability ``MALLOC_CAP_DEFAULT``, which is byte-addressable. @@ -122,11 +125,11 @@ Memory allocated with ``MALLOC_CAP_32BIT`` can **only** be accessed via 32-bit r External SPI Memory ^^^^^^^^^^^^^^^^^^^ - When :doc:`external RAM ` is enabled, external SPI RAM under 4 MiB in size can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on the configuration. See :ref:`external_ram_config` for more details. + When :doc:`external RAM ` is enabled, external SPI RAM can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on the configuration. See :ref:`external_ram_config` for more details. .. only:: esp32 - To use the region above the 4 MiB limit, you can use the :doc:`himem API `. + On ESP32 only external SPI RAM under 4 MiB in size can be allocated this way. To use the region above the 4 MiB limit, you can use the :doc:`himem API `. Thread Safety ------------- diff --git a/docs/en/api-reference/system/misc_system_api.rst b/docs/en/api-reference/system/misc_system_api.rst index 1d6ab962bb..68fe3d2015 100644 --- a/docs/en/api-reference/system/misc_system_api.rst +++ b/docs/en/api-reference/system/misc_system_api.rst @@ -4,7 +4,7 @@ Miscellaneous System APIs :link_to_translation:`zh_CN:[中文]` {IDF_TARGET_BASE_MAC_BLOCK: default="BLK1", esp32="BLK0"} -{IDF_TARGET_CPU_RESET_DES: default="the CPU is reset", esp32="both CPUs are reset", esp32s3="both CPUs are reset"} +{IDF_TARGET_CPU_RESET_DES: default="the CPU is reset", esp32="both CPUs are reset", esp32s3="both CPUs are reset", esp32p4="both CPUs are reset"} Software Reset -------------- @@ -90,8 +90,8 @@ In ESP-IDF, the MAC addresses for the various network interfaces are calculated .. only:: not SOC_EMAC_SUPPORTED - .. note:: - + .. note:: + Although {IDF_TARGET_NAME} has no integrated Ethernet MAC, it is still possible to calculate an Ethernet MAC address. However, this MAC address can only be used with an external ethernet interface such as an SPI-Ethernet device. See :doc:`/api-reference/network/esp_eth`. Custom Interface MAC diff --git a/docs/en/api-reference/system/system_time.rst b/docs/en/api-reference/system/system_time.rst index be1f5b2edc..f959f1c42c 100644 --- a/docs/en/api-reference/system/system_time.rst +++ b/docs/en/api-reference/system/system_time.rst @@ -3,12 +3,12 @@ System Time :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_RTC_CLK_FRE:default="Not updated", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz", esp32h2="150 kHz"} -{IDF_TARGET_INT_OSC_FRE:default="Not updated", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz", esp32c6="20 MHz"} +{IDF_TARGET_RTC_CLK_FRE:default="Not updated", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz", esp32h2="150 kHz", esp32p4="150 kHz"} +{IDF_TARGET_INT_OSC_FRE:default="Not updated", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz"} {IDF_TARGET_INT_OSC_FRE_DIVIDED:default="Not updated", esp32="about 33 kHz", esp32s2="about 33 kHz", esp32s3="about 68 kHz", esp32c3="about 68 kHz", esp32c2="about 68 kHz"} -{IDF_TARGET_EXT_CRYSTAL_PIN:default="Not updated", esp32="32K_XP and 32K_XN", esp32s2="XTAL_32K_P and XTAL_32K_N", esp32s3="XTAL_32K_P and XTAL_32K_N", esp32c3="XTAL_32K_P and XTAL_32K_N", esp32c6="XTAL_32K_P and XTAL_32K_N", esp32h2="XTAL_32K_P and XTAL_32K_N"} -{IDF_TARGET_EXT_OSC_PIN:default="Not updated", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P"} -{IDF_TARGET_HARDWARE_DESIGN_URL:default="Not updated",esp32="`ESP32 Hardware Design Guidelines `_", esp32s2="`ESP32-S2 Hardware Design Guidelines `_", esp32s3="`ESP32-S3 Hardware Design Guidelines `_", esp32c3="`ESP32-C3 Hardware Design Guidelines `_", esp32c6="`ESP32-C6 Hardware Design Guidelines `_", esp32c2="`ESP8684 Hardware Design Guidelines `_", esp32h2="`ESP32-H2 Hardware Design Guidelines `_"} +{IDF_TARGET_EXT_CRYSTAL_PIN:default="Not updated", esp32="32K_XP and 32K_XN", esp32s2="XTAL_32K_P and XTAL_32K_N", esp32s3="XTAL_32K_P and XTAL_32K_N", esp32c3="XTAL_32K_P and XTAL_32K_N", esp32c6="XTAL_32K_P and XTAL_32K_N", esp32h2="XTAL_32K_P and XTAL_32K_N", esp32p4="XTAL_32K_P and XTAL_32K_N"} +{IDF_TARGET_EXT_OSC_PIN:default="Not updated", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P", esp32h2="XTAL_32K_P", esp32p4="XTAL_32K_P"} +{IDF_TARGET_HARDWARE_DESIGN_URL:default="Not updated",esp32="`ESP32 Hardware Design Guidelines `_", esp32s2="`ESP32-S2 Hardware Design Guidelines `_", esp32s3="`ESP32-S3 Hardware Design Guidelines `_", esp32c3="`ESP32-C3 Hardware Design Guidelines `_", esp32c6="`ESP32-C6 Hardware Design Guidelines `_", esp32c2="`ESP8684 Hardware Design Guidelines `_", esp32h2="`ESP32-H2 Hardware Design Guidelines `_", esp32p4="`ESP32-P4 Hardware Design Guidelines `_"} Overview @@ -45,9 +45,9 @@ The RTC timer has the following clock sources: - ``External 32 kHz oscillator at {IDF_TARGET_EXT_OSC_PIN} pin``: Allows using 32 kHz clock generated by an external circuit. The external clock signal must be connected to the {IDF_TARGET_EXT_OSC_PIN} pin. The amplitude should be less than 1.2 V for sine wave signal and less than 1 V for square wave signal. Common mode voltage should be in the range of 0.1 < Vcm < 0.5xVamp, where Vamp stands for signal amplitude. In this case, the {IDF_TARGET_EXT_OSC_PIN} pin cannot be used as a GPIO pin. - :not esp32c6 and not esp32h2: - ``Internal {IDF_TARGET_INT_OSC_FRE} oscillator, divided by 256 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``: Provides better frequency stability than the ``Internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator`` at the expense of a higher (by 5 μA) Deep-sleep current consumption. It also does not require external components. + :not esp32c6 and not esp32h2 and not esp32p4: - ``Internal {IDF_TARGET_INT_OSC_FRE} oscillator, divided by 256 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``: Provides better frequency stability than the ``Internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator`` at the expense of a higher (by 5 μA) Deep-sleep current consumption. It also does not require external components. - :esp32c6 or esp32h2: - ``Internal 32 kHz RC oscillator`` + :esp32c6 or esp32h2 or esp32p4: - ``Internal 32 kHz RC oscillator`` The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_RTC_CLK_SRC` in project configuration. diff --git a/docs/en/migration-guides/release-5.x/5.0/build-system.rst b/docs/en/migration-guides/release-5.x/5.0/build-system.rst index 76ee545434..19b80e0378 100644 --- a/docs/en/migration-guides/release-5.x/5.0/build-system.rst +++ b/docs/en/migration-guides/release-5.x/5.0/build-system.rst @@ -9,7 +9,12 @@ ESP-IDF v5.0 no longer supports GNU make-based projects. Please follow the :ref: Update Fragment File Grammar ---------------------------- -Please follow the :ref:`migrate linker script fragment files grammar ` chapter for migrating v3.x grammar to the new one. +The former grammar, supported in ESP-IDF v3.x, was dropped in ESP-IDF v5.0. Here are a few notes on how to migrate properly: + +1. Indentation is now enforced: improperly indented fragment files generate a runtime parse exception. Although the former version did not enforce this, the previous documentation and examples demonstrated properly indented grammar. +2. Migrate the old condition entry to the ``if...elif...else`` structure for conditionals. You can refer to the :ref:`ldgen-conditional-placements` for detailed grammar. +3. Mapping fragments now requires a name like other fragment types. + Specify Component Requirements Explicitly ----------------------------------------- diff --git a/docs/en/migration-guides/release-5.x/5.2/index.rst b/docs/en/migration-guides/release-5.x/5.2/index.rst index 79168d8665..eea59de043 100644 --- a/docs/en/migration-guides/release-5.x/5.2/index.rst +++ b/docs/en/migration-guides/release-5.x/5.2/index.rst @@ -11,4 +11,4 @@ Migration from 5.1 to 5.2 protocols storage system - wifi + :SOC_WIFI_SUPPORTED: wifi diff --git a/docs/zh_CN/api-guides/bootloader.rst b/docs/zh_CN/api-guides/bootloader.rst index f068ff4f26..468249fb0a 100644 --- a/docs/zh_CN/api-guides/bootloader.rst +++ b/docs/zh_CN/api-guides/bootloader.rst @@ -3,8 +3,6 @@ :link_to_translation:`en:[English]` -{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"} - ESP-IDF 软件引导加载程序 (Bootloader) 主要执行以下任务： 1. 内部模块的最小化初始配置； @@ -12,7 +10,7 @@ ESP-IDF 软件引导加载程序 (Bootloader) 主要执行以下任务： 3. 根据分区表和 ota_data（如果存在）选择需要引导的应用程序 (app) 分区； 4. 将此应用程序镜像加载到 RAM（IRAM 和 DRAM）中，最后把控制权转交给此应用程序。 -引导加载程序位于 flash 的 {IDF_TARGET_BOOTLOADER_OFFSET} 偏移地址处。 +引导加载程序位于 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 偏移地址处。 关于启动过程以及 ESP-IDF 引导加载程序的更多信息，请参考 :doc:`startup`。 @@ -95,7 +93,7 @@ ROM 中的 :ref:`first-stage-bootloader` 从 flash 中读取 :ref:`second-stage- .. only:: SOC_RTC_FAST_MEM_SUPPORTED 如果应用程序需要知道设备是否触发了出厂重置，可以通过调用 :cpp:func:`bootloader_common_get_rtc_retain_mem_factory_reset_state` 函数来确定： - + - 如果读取到设备出厂重置状态为 true，会返回状态 true，说明设备已经触发出厂重置。此后会重置状态为 false，以便后续的出厂重置触发判断。 - 如果读取到设备出厂重置状态为 false，会返回状态 false，说明设备并未触发出厂重置，或者保存此状态的内存区域已失效。 diff --git a/docs/zh_CN/api-guides/fatal-errors.rst b/docs/zh_CN/api-guides/fatal-errors.rst index 6c0ed6b919..64bc91cd58 100644 --- a/docs/zh_CN/api-guides/fatal-errors.rst +++ b/docs/zh_CN/api-guides/fatal-errors.rst @@ -282,7 +282,7 @@ GDB Stub RTC 看门狗超时 ---------------- -{IDF_TARGET_RTCWDT_RTC_RESET:default="Not updated", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS"} +{IDF_TARGET_RTCWDT_RTC_RESET:default="Not updated", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS", esp32p4="LP_WDT_SYS"} RTC 看门狗在启动代码中用于跟踪执行时间，也有助于防止由于电源不稳定引起的锁定。RTC 看门狗默认启用，参见 :ref:`CONFIG_BOOTLOADER_WDT_ENABLE`。如果执行时间超时，RTC 看门狗将自动重启系统。此时，ROM 引导加载程序将打印消息 ``RTC Watchdog Timeout`` 说明重启原因。 diff --git a/docs/zh_CN/api-guides/linker-script-generation.rst b/docs/zh_CN/api-guides/linker-script-generation.rst index 9887ba56a2..3fc4deb434 100644 --- a/docs/zh_CN/api-guides/linker-script-generation.rst +++ b/docs/zh_CN/api-guides/linker-script-generation.rst @@ -603,14 +603,3 @@ 这是根据默认协议条目 ``iram -> iram0_text`` 生成的规则。默认协议指定了 ``iram -> iram0_text`` 条目，因此生成的规则同样也放在被 ``iram0_text`` 标记的地方。由于该规则是根据默认协议生成的，因此在同一目标下收集的所有规则下排在第一位。 目前使用的链接器脚本模板是 :component_file:`esp_system/ld/{IDF_TARGET_PATH_NAME}/sections.ld.in`，生成的脚本存放在构建目录下。 - -.. _ldgen-migrate-lf-grammar : - -将链接器脚本片段文件语法迁移至 ESP-IDF v5.0 适应版本 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -ESP-IDF v5.0 中将不再支持 ESP-IDF v3.x 中链接器脚本片段文件的旧式语法。在迁移的过程中需注意以下几点： - -- 必须缩进，缩进不当的文件会产生解析异常；旧版本不强制缩进，但之前的文档和示例均遵循了正确的缩进语法 -- 条件改用 ``if...elif...else`` 结构，可以参照 :ref:`之前的章节` -- 映射片段和其他片段类型一样，需有名称 diff --git a/docs/zh_CN/api-guides/memory-types.rst b/docs/zh_CN/api-guides/memory-types.rst index 4262cd1e1e..234584ac50 100644 --- a/docs/zh_CN/api-guides/memory-types.rst +++ b/docs/zh_CN/api-guides/memory-types.rst @@ -184,6 +184,14 @@ DROM（数据存储在 flash 中） 除非禁用 :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` 选项，否则剩余的 RTC FAST memory 会被添加到堆中。该部分内存可以和 :ref:`DRAM` 互换使用，但是访问速度稍慢一点。 +.. only:: SOC_MEM_TCM_SUPPORTED + + 紧密耦合内存 (TCM) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + TCM 是靠近 CPU 放置的内存，支持在 CPU 频率下直接访问，无需通过 cache。虽然在一般情况下，TCM 的效率或速度相较 cache 偏低，但是访问 TCM 所需的时间是可以预测且始终一致的。具有稳定的访问速度对于时间关键型例程来说十分重要，因此 TCM 对于此类例程而言非常有用。 + + 具备 DMA 功能 ^^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-guides/startup.rst b/docs/zh_CN/api-guides/startup.rst index 54e58bc3b8..29db52f7f4 100644 --- a/docs/zh_CN/api-guides/startup.rst +++ b/docs/zh_CN/api-guides/startup.rst @@ -3,13 +3,11 @@ :link_to_translation:`en:[English]` -{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000"} - 本文将会介绍 {IDF_TARGET_NAME} 从上电到运行 ``app_main`` 函数中间所经历的步骤（即启动流程）。 宏观上，该启动流程可以分为如下 3 个步骤： -1. :ref:`first-stage-bootloader` 被固化在了 {IDF_TARGET_NAME} 内部的 ROM 中，它会从 flash 的 {IDF_TARGET_BOOTLOADER_OFFSET} 偏移地址处加载二级引导程序至 RAM (IRAM & DRAM) 中。 +1. :ref:`first-stage-bootloader` 被固化在了 {IDF_TARGET_NAME} 内部的 ROM 中，它会从 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 偏移地址处加载二级引导程序至 RAM (IRAM & DRAM) 中。 2. :ref:`second-stage-bootloader` 从 flash 中加载分区表和主程序镜像至内存中，主程序中包含了 RAM 段和通过 flash 高速缓存映射的只读段。 @@ -46,15 +44,19 @@ .. only:: esp32 - 二级引导程序二进制镜像会从 flash 的 ``0x1000`` 偏移地址处加载。如果正在使用 :doc:`/security/secure-boot-v1`，则 flash 的第一个 4 kB 扇区用于存储安全启动 IV 以及引导程序镜像的摘要，否则不使用该扇区。 + 二级引导程序二进制镜像会从 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 偏移地址处加载。如果正在使用 :doc:`/security/secure-boot-v1`，则 flash 的第一个 4 kB 扇区用于存储安全启动 IV 以及引导程序镜像的摘要，否则不使用该扇区。 .. only:: esp32s2 - 二级引导程序二进制镜像会从 flash 的 ``0x1000`` 偏移地址处加载。该地址前面的 flash 4 kB 扇区未使用。 + 二级引导程序二进制镜像会从 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 偏移地址处加载。该地址前面的 flash 4 kB 扇区未使用。 - .. only:: not (esp32 or esp32s2) +.. only:: esp32p4 - 二级引导程序二进制镜像会从 flash 的 `` 0x0`` 偏移地址处加载。 + 二级引导程序二进制镜像会从 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 偏移地址处加载。该地址前面的 flash 8 kB 扇区将为密钥管理器保留，用于与 flash 加密 (AES-XTS) 相关的操作。 + + .. only:: not (esp32 or esp32s2 or esp32p4) + + 二级引导程序二进制镜像会从 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 偏移地址处加载。 .. TODO: describe application binary image format, describe optional flash configuration commands. @@ -63,11 +65,11 @@ 二级引导程序 ~~~~~~~~~~~~ -在 ESP-IDF 中，存放在 flash 的 {IDF_TARGET_BOOTLOADER_OFFSET} 偏移地址处的二进制镜像就是二级引导程序。二级引导程序的源码可以在 ESP-IDF 的 :idf:`components/bootloader` 目录下找到。ESP-IDF 使用二级引导程序可以增加 flash 分区的灵活性（使用分区表），并且方便实现 flash 加密，安全引导和空中升级 (OTA) 等功能。 +在 ESP-IDF 中，存放在 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 偏移地址处的二进制镜像就是二级引导程序。二级引导程序的源码可以在 ESP-IDF 的 :idf:`components/bootloader` 目录下找到。ESP-IDF 使用二级引导程序可以增加 flash 分区的灵活性（使用分区表），并且方便实现 flash 加密，安全引导和空中升级 (OTA) 等功能。 当一级引导程序校验并加载完二级引导程序后，它会从二进制镜像的头部找到二级引导程序的入口点，并跳转过去运行。 -二级引导程序默认从 flash 的 ``0x8000`` 偏移地址处（:ref:`可配置的值 `）读取分区表。请参考 :doc:`分区表 ` 获取详细信息。引导程序会寻找工厂分区和 OTA 应用程序分区。如果在分区表中找到了 OTA 应用程序分区，引导程序将查询 ``otadata`` 分区以确定应引导哪个分区。更多信息请参考 :doc:`/api-reference/system/ota`。 +二级引导程序默认从 flash 的 {IDF_TARGET_CONFIG_PARTITION_TABLE_OFFSET} 偏移地址处（:ref:`可配置的值 `）读取分区表。请参考 :doc:`分区表 ` 获取详细信息。引导程序会寻找工厂分区和 OTA 应用程序分区。如果在分区表中找到了 OTA 应用程序分区，引导程序将查询 ``otadata`` 分区以确定应引导哪个分区。更多信息请参考 :doc:`/api-reference/system/ota`。 关于 ESP-IDF 引导程序可用的配置选项，请参考 :doc:`bootloader`。 @@ -76,7 +78,7 @@ - 对于在内部 :ref:`iram` 或 :ref:`dram` 中具有加载地址的段，将把数据从 flash 复制到它们的加载地址处。 - 对于一些加载地址位于 :ref:`drom` 或 :ref:`irom` 区域的段，通过配置 flash MMU，可为从 flash 到加载地址提供正确的映射。 -.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES +.. only:: esp32 请注意，二级引导程序同时为 PRO CPU 和 APP CPU 配置 flash MMU，但仅使能 PRO CPU 的 flash MMU。原因是二级引导程序代码已加载到 APP CPU 的高速缓存使用的内存区域中。因此使能 APP CPU 高速缓存的任务就交给了应用程序。 @@ -112,7 +114,7 @@ ESP-IDF 应用程序的入口是 :idf_file:`components/esp_system/port/cpu_start - 完成 MMU 高速缓存配置。 :SOC_SPIRAM_SUPPORTED: - 如果配置了 PSRAM，则使能 PSRAM。 - 将 CPU 时钟设置为项目配置的频率。 - :CONFIG_ESP_SYSTEM_MEMPROT_FEATURE: - 如果配置了内存保护，则初始化内存保护。 + :SOC_MEMPROT_SUPPORTED: - 如果配置了内存保护，则初始化内存保护。 :esp32: - 根据应用程序头部设置重新配置主 SPI flash，这是为了与 ESP-IDF V4.0 之前的引导程序版本兼容，请参考 :ref:`bootloader-compatibility`。 :SOC_HP_CPU_HAS_MULTIPLE_CORES: - 如果应用程序被配置为在多个内核上运行，则启动另一个内核并等待其初始化（在类似的“端口层”初始化函数 ``call_start_cpu1`` 内）。 @@ -175,4 +177,4 @@ ESP-IDF 应用程序的入口是 :idf_file:`components/esp_system/port/cpu_start ``start_cpu_other_cores_default`` 函数做了一些与内核相关的系统初始化，然后等待 PRO CPU 启动 FreeRTOS 的调度器，启动完成后，它会执行 ``esp_startup_start_app_other_cores`` 函数，这是另一个默认为 ``esp_startup_start_app_other_cores_default`` 的弱链接函数。 - 默认情况下，``esp_startup_start_app_other_cores_default`` 只会自旋，直到 PRO CPU 上的调度器触发中断，以启动 APP CPU 上的 RTOS 调度器。 \ No newline at end of file + 默认情况下，``esp_startup_start_app_other_cores_default`` 只会自旋，直到 PRO CPU 上的调度器触发中断，以启动 APP CPU 上的 RTOS 调度器。 diff --git a/docs/zh_CN/api-guides/unit-tests.rst b/docs/zh_CN/api-guides/unit-tests.rst index 9ef5113fda..11011e3c80 100644 --- a/docs/zh_CN/api-guides/unit-tests.rst +++ b/docs/zh_CN/api-guides/unit-tests.rst @@ -185,6 +185,11 @@ DUT2 (slave) 终端:: 运行单元测试 -------------- +.. note:: + + 我们还提供基于 pytest 的框架 `pytest-embedded `_，以便更方便、高效地运行单元测试。如需在 CI 中运行测试或连续运行多个测试，不妨尝试这一框架。了解更多信息，请查看 `pytest-embedded 文档 `_ 和 :doc:`/contribute/esp-idf-tests-with-pytest`。 + + 烧写完成后重启 {IDF_TARGET_NAME}， 它将启动单元测试程序。 当单元测试应用程序空闲时，输入回车键，它会打印出测试菜单，其中包含所有的测试项目:: diff --git a/docs/zh_CN/api-reference/system/mem_alloc.rst b/docs/zh_CN/api-reference/system/mem_alloc.rst index b723cc6f36..5158750ae5 100644 --- a/docs/zh_CN/api-reference/system/mem_alloc.rst +++ b/docs/zh_CN/api-reference/system/mem_alloc.rst @@ -31,7 +31,10 @@ ESP-IDF 应用程序使用常见的计算机架构模式：由程序控制流动 所有的 DRAM 内存都可以单字节访问，因此所有的 DRAM 堆都具有 ``MALLOC_CAP_8BIT`` 属性。要获取所有 DRAM 堆的剩余空间大小，请调用 ``heap_caps_get_free_size(MALLOC_CAP_8BIT)``。 -如果占用了所有的 ``MALLOC_CAP_8BIT`` 堆空间，则可以用 ``MALLOC_CAP_IRAM_8BIT`` 代替。此时，若只以 32 位对齐的方式访问 IRAM 内存，或者启用了 ``CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY``，则仍然可以将 IRAM 用作内部内存的“储备池”。 +.. only:: esp32 + + 如果占用了所有的 ``MALLOC_CAP_8BIT`` 堆空间，则可以用 ``MALLOC_CAP_IRAM_8BIT`` 代替。此时，若只以 32 位对齐的方式访问 IRAM 内存，或者启用了 ``CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY``，则仍然可以将 IRAM 用作内部内存的“储备池”。 + 调用 ``malloc()`` 时，ESP-IDF ``malloc()`` 内部调用 ``heap_caps_malloc_default(size)``，使用属性 ``MALLOC_CAP_DEFAULT`` 分配内存。该属性可实现字节寻址功能，即存储空间的最小编址单位为字节。 @@ -122,11 +125,11 @@ DMA 存储器 外部 SPI 内存 ^^^^^^^^^^^^^^^^^^^ - 当启用 :doc:`片外 RAM ` 时，可以根据配置调用标准 ``malloc`` 或通过 ``heap_caps_malloc(MALLOC_CAP_SPIRAM)`` 分配小于 4 MiB 的外部 SPI RAM，详情请参阅 :ref:`external_ram_config`。 + 当启用 :doc:`片外 RAM ` 时，可以根据配置调用标准 ``malloc`` 或通过 ``heap_caps_malloc(MALLOC_CAP_SPIRAM)`` 分配外部 SPI RAM，详情请参阅 :ref:`external_ram_config`。 .. only:: esp32 - 要使用超过 4 MiB 限制的区域，可以使用 :doc:`himem API`。 + 在 ESP32 上，只有不超过 4 MiB 的外部 SPI RAM 可以通过上述方式分配。要使用超过 4 MiB 限制的区域，可以使用 :doc:`himem API`。 线程安全性 ------------- diff --git a/docs/zh_CN/api-reference/system/misc_system_api.rst b/docs/zh_CN/api-reference/system/misc_system_api.rst index 4ac8cab888..22757cc686 100644 --- a/docs/zh_CN/api-reference/system/misc_system_api.rst +++ b/docs/zh_CN/api-reference/system/misc_system_api.rst @@ -4,7 +4,7 @@ :link_to_translation:`en:[English]` {IDF_TARGET_BASE_MAC_BLOCK: default="BLK1", esp32="BLK0"} -{IDF_TARGET_CPU_RESET_DES: default="CPU 复位", esp32="两个 CPU 均复位", esp32s3="两个 CPU 均复位"} +{IDF_TARGET_CPU_RESET_DES: default="CPU 复位", esp32="两个 CPU 均复位", esp32s3="两个 CPU 均复位", esp32p4="两个 CPU 均复位"} 软件复位 ------------ diff --git a/docs/zh_CN/api-reference/system/system_time.rst b/docs/zh_CN/api-reference/system/system_time.rst index 6bd7e2aa72..f14dc18861 100644 --- a/docs/zh_CN/api-reference/system/system_time.rst +++ b/docs/zh_CN/api-reference/system/system_time.rst @@ -3,12 +3,12 @@ :link_to_translation:`en:[English]` -{IDF_TARGET_RTC_CLK_FRE:default="未更新", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz", esp32h2="150 kHz"} -{IDF_TARGET_INT_OSC_FRE:default="未更新", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz", esp32c6="20 MHz"} +{IDF_TARGET_RTC_CLK_FRE:default="未更新", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz", esp32h2="150 kHz", esp32p4="150 kHz"} +{IDF_TARGET_INT_OSC_FRE:default="未更新", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz"} {IDF_TARGET_INT_OSC_FRE_DIVIDED:default="未更新", esp32="约 33 kHz", esp32s2="约 33 kHz", esp32s3="约 68 kHz", esp32c3="约 68 kHz", esp32c2="约 68 kHz"} -{IDF_TARGET_EXT_CRYSTAL_PIN:default="未更新", esp32="32K_XP 和 32K_XN", esp32s2="XTAL_32K_P 和 XTAL_32K_N", esp32s3="XTAL_32K_P 和 XTAL_32K_N", esp32c3="XTAL_32K_P 和 XTAL_32K_N", esp32c6="XTAL_32K_P 和 XTAL_32K_N", esp32h2="XTAL_32K_P 和 XTAL_32K_N"} -{IDF_TARGET_EXT_OSC_PIN:default="未更新", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P"} -{IDF_TARGET_HARDWARE_DESIGN_URL:default="未更新", esp32="`ESP32 硬件设计指南 `_", esp32s2="`ESP32-S2 硬件设计指南 `_", esp32s3="`ESP32-S3 硬件设计指南 `_", esp32c3="`ESP32-C3 硬件设计指南 `_", esp32c2="`ESP8684 硬件设计指南 `_", esp32c6="`ESP32-C6 硬件设计指南 `_", esp32h2="`ESP32-H2 硬件设计指南 `_"} +{IDF_TARGET_EXT_CRYSTAL_PIN:default="未更新", esp32="32K_XP 和 32K_XN", esp32s2="XTAL_32K_P 和 XTAL_32K_N", esp32s3="XTAL_32K_P 和 XTAL_32K_N", esp32c3="XTAL_32K_P 和 XTAL_32K_N", esp32c6="XTAL_32K_P 和 XTAL_32K_N", esp32h2="XTAL_32K_P 和 XTAL_32K_N", esp32p4="XTAL_32K_P 和 XTAL_32K_N"} +{IDF_TARGET_EXT_OSC_PIN:default="未更新", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P", esp32h2="XTAL_32K_P", esp32p4="XTAL_32K_P"} +{IDF_TARGET_HARDWARE_DESIGN_URL:default="未更新", esp32="`ESP32 硬件设计指南 `_", esp32s2="`ESP32-S2 硬件设计指南 `_", esp32s3="`ESP32-S3 硬件设计指南 `_", esp32c3="`ESP32-C3 硬件设计指南 `_", esp32c2="`ESP8684 硬件设计指南 `_", esp32c6="`ESP32-C6 硬件设计指南 `_", esp32h2="`ESP32-H2 硬件设计指南 `_", esp32p4="`ESP32-P4 硬件设计指南 `_"} 概述 @@ -45,9 +45,9 @@ RTC 定时器有以下时钟源： - ``管脚 {IDF_TARGET_EXT_OSC_PIN} 外置 32 kHz 振荡器``：允许使用由外部电路产生的 32 kHz 时钟。外部时钟信号必须连接到管脚 {IDF_TARGET_EXT_OSC_PIN}。正弦波信号的振幅应小于 1.2 V，方波信号的振幅应小于 1 V。正常模式下，电压范围应为 0.1 < Vcm < 0.5 xVamp，其中 Vamp 代表信号振幅。使用此时钟源时，管脚 {IDF_TARGET_EXT_OSC_PIN} 无法用作 GPIO 管脚。 - :not esp32c6 and not esp32h2: - ``内置 {IDF_TARGET_INT_OSC_FRE} 振荡器的 256 分频时钟 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``：频率稳定性优于 ``内置 {IDF_TARGET_RTC_CLK_FRE} RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。 + :not esp32c6 and not esp32h2 and not esp32p4: - ``内置 {IDF_TARGET_INT_OSC_FRE} 振荡器的 256 分频时钟 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``：频率稳定性优于 ``内置 {IDF_TARGET_RTC_CLK_FRE} RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。 - :esp32c6 or esp32h2: - ``内置 32 kHz RC 振荡器`` + :esp32c6 or esp32h2 or esp32p4: - ``内置 32 kHz RC 振荡器`` 时钟源的选择取决于系统时间精度要求和睡眠模式下的功耗要求。要修改 RTC 时钟源，请在项目配置中设置 :ref:`CONFIG_RTC_CLK_SRC`。 diff --git a/docs/zh_CN/migration-guides/release-5.x/5.0/build-system.rst b/docs/zh_CN/migration-guides/release-5.x/5.0/build-system.rst index d762e25332..43ee713096 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.0/build-system.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.0/build-system.rst @@ -9,7 +9,12 @@ ESP-IDF v5.0 已不再支持基于 Make 的工程，请参考 :ref:`从 ESP-IDF 更新片段文件语法 ---------------------------- -请参考 :ref:`将链接器脚本片段文件语法迁移至 ESP-IDF v5.0 适应版本 ` 对 v3.x 的语法进行更新。 +ESP-IDF v5.0 中将不再支持 ESP-IDF v3.x 中链接器脚本片段文件的旧式语法。在迁移的过程中需注意以下几点： + +- 必须缩进，缩进不当的文件会产生解析异常；旧版本不强制缩进，但之前的文档和示例均遵循了正确的缩进语法。 +- 条件改用 ``if...elif...else`` 结构，可以参照 :ref:`之前的章节`。 +- 映射片段和其他片段类型一样，需有名称。 + 明确指定组件依赖 ----------------------------------------- diff --git a/docs/zh_CN/migration-guides/release-5.x/5.2/index.rst b/docs/zh_CN/migration-guides/release-5.x/5.2/index.rst index 239b91a7ca..e0b3a2f93f 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.2/index.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.2/index.rst @@ -11,4 +11,4 @@ protocols storage system - wifi + :SOC_WIFI_SUPPORTED: wifi