From 79950e478343f3653657d65e2302d245890e40f9 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Tue, 20 Jan 2026 20:35:58 +0800 Subject: [PATCH] docs(esp32s31): add support for building docs for esp32s31 --- .gitlab/ci/docs.yml | 2 +- .../test_apps/crypto/main/CMakeLists.txt | 2 +- .../esp_hw_support/port/esp32s31/Kconfig.mac | 38 ++++ .../esp32s31/include/soc/Kconfig.soc_caps.in | 8 + .../soc/esp32s31/include/soc/adc_channel.h | 6 + .../soc/esp32s31/include/soc/soc_caps.h | 5 + docs/conf_common.py | 5 + docs/doxygen/Doxyfile_esp32s31 | 1 + docs/en/api-guides/host-apps.rst | 2 +- .../en/api-guides/jtag-debugging/esp32s31.inc | 172 ++++++++++++++++++ docs/en/api-reference/peripherals/gptimer.rst | 6 +- .../system/inc/espefuse_summary_ESP32-S31.rst | 3 + .../inc/espefuse_summary_ESP32-S31_dump.rst | 3 + .../system/inc/power_management_esp32s31.rst | 3 + .../system/inc/revisions_ESP32-S31.rst | 3 + .../system/inc/show-efuse-table_ESP32-S31.rst | 3 + docs/en/get-started/esp32s31_output_log.inc | 30 +++ .../release-6.x/6.0/peripherals.rst | 66 +++---- docs/en/security/esp32s31_log.inc | 131 +++++++++++++ docs/zh_CN/api-guides/host-apps.rst | 2 +- .../api-guides/jtag-debugging/esp32s31.inc | 172 ++++++++++++++++++ .../api-reference/peripherals/gptimer.rst | 6 +- .../system/inc/espefuse_summary_ESP32-S31.rst | 3 + .../inc/espefuse_summary_ESP32-S31_dump.rst | 3 + .../system/inc/power_management_esp32s31.rst | 3 + .../system/inc/revisions_ESP32-S31.rst | 3 + .../system/inc/show-efuse-table_ESP32-S31.rst | 3 + .../zh_CN/get-started/esp32s31_output_log.inc | 30 +++ .../release-6.x/6.0/peripherals.rst | 66 +++---- docs/zh_CN/security/esp32s31_log.inc | 131 +++++++++++++ 30 files changed, 837 insertions(+), 74 deletions(-) create mode 100644 components/esp_hw_support/port/esp32s31/Kconfig.mac create mode 100644 components/soc/esp32s31/include/soc/adc_channel.h create mode 100644 docs/doxygen/Doxyfile_esp32s31 create mode 100644 docs/en/api-guides/jtag-debugging/esp32s31.inc create mode 100644 docs/en/api-reference/system/inc/espefuse_summary_ESP32-S31.rst create mode 100644 docs/en/api-reference/system/inc/espefuse_summary_ESP32-S31_dump.rst create mode 100644 docs/en/api-reference/system/inc/power_management_esp32s31.rst create mode 100644 docs/en/api-reference/system/inc/revisions_ESP32-S31.rst create mode 100644 docs/en/api-reference/system/inc/show-efuse-table_ESP32-S31.rst create mode 100644 docs/en/get-started/esp32s31_output_log.inc create mode 100644 docs/en/security/esp32s31_log.inc create mode 100644 docs/zh_CN/api-guides/jtag-debugging/esp32s31.inc create mode 100644 docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-S31.rst create mode 100644 docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-S31_dump.rst create mode 100644 docs/zh_CN/api-reference/system/inc/power_management_esp32s31.rst create mode 100644 docs/zh_CN/api-reference/system/inc/revisions_ESP32-S31.rst create mode 100644 docs/zh_CN/api-reference/system/inc/show-efuse-table_ESP32-S31.rst create mode 100644 docs/zh_CN/get-started/esp32s31_output_log.inc create mode 100644 docs/zh_CN/security/esp32s31_log.inc diff --git a/.gitlab/ci/docs.yml b/.gitlab/ci/docs.yml index 5c49d0797a..8640c22b01 100644 --- a/.gitlab/ci/docs.yml +++ b/.gitlab/ci/docs.yml @@ -95,7 +95,7 @@ check_docs_lang_sync: parallel: matrix: - DOCLANG: ["en", "zh_CN"] - DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32c61", "esp32c5", "esp32h2", "esp32h4", "esp32h21", "esp32p4"] + DOCTGT: ["esp32", "esp32s2", "esp32s3", "esp32s31", "esp32c3", "esp32c2", "esp32c6", "esp32c61", "esp32c5", "esp32h2", "esp32h4", "esp32h21", "esp32p4"] check_docs_gh_links: image: $ESP_IDF_DOC_ENV_IMAGE diff --git a/components/esp_hal_security/test_apps/crypto/main/CMakeLists.txt b/components/esp_hal_security/test_apps/crypto/main/CMakeLists.txt index 86bc4be2c7..be2f094f42 100644 --- a/components/esp_hal_security/test_apps/crypto/main/CMakeLists.txt +++ b/components/esp_hal_security/test_apps/crypto/main/CMakeLists.txt @@ -72,7 +72,7 @@ if(CONFIG_SOC_SHA_SUPPORTED) endif() endif() -if(CONFIG_SOC_FLASH_ENCRYPTION_XTS_AES) +if(CONFIG_SOC_FLASH_ENCRYPTION_XTS_AES AND CONFIG_CRYPTO_TEST_APP_ENABLE_XTS_AES_TESTS) list(APPEND srcs "xts_aes/test_xts_aes.c") endif() diff --git a/components/esp_hw_support/port/esp32s31/Kconfig.mac b/components/esp_hw_support/port/esp32s31/Kconfig.mac new file mode 100644 index 0000000000..4bf383285f --- /dev/null +++ b/components/esp_hw_support/port/esp32s31/Kconfig.mac @@ -0,0 +1,38 @@ +choice ESP32S31_UNIVERSAL_MAC_ADDRESSES + bool "Number of universally administered (by IEEE) MAC address" + default ESP32S31_UNIVERSAL_MAC_ADDRESSES_FOUR + help + Configure the number of universally administered (by IEEE) MAC addresses. + 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. + 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.) + + config ESP32S31_UNIVERSAL_MAC_ADDRESSES_TWO + bool "Two" + select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_TWO + select ESP_MAC_ADDR_UNIVERSE_WIFI_STA + select ESP_MAC_ADDR_UNIVERSE_BT + + config ESP32S31_UNIVERSAL_MAC_ADDRESSES_FOUR + bool "Four" + select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_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 ESP32S31_UNIVERSAL_MAC_ADDRESSES + int + default 2 if ESP32S31_UNIVERSAL_MAC_ADDRESSES_TWO + default 4 if ESP32S31_UNIVERSAL_MAC_ADDRESSES_FOUR diff --git a/components/soc/esp32s31/include/soc/Kconfig.soc_caps.in b/components/soc/esp32s31/include/soc/Kconfig.soc_caps.in index 6581166a88..9112ca11c5 100644 --- a/components/soc/esp32s31/include/soc/Kconfig.soc_caps.in +++ b/components/soc/esp32s31/include/soc/Kconfig.soc_caps.in @@ -243,6 +243,10 @@ config SOC_SDM_SUPPORT_SLEEP_RETENTION bool default y +config SOC_LEDC_CHANNEL_NUM + int + default 6 + config SOC_MMU_PERIPH_NUM int default 2 @@ -367,6 +371,10 @@ config SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS int default 3 +config SOC_FLASH_ENCRYPTION_XTS_AES + bool + default y + config SOC_FLASH_ENCRYPTED_XTS_AES_BLOCK_MAX int default 64 diff --git a/components/soc/esp32s31/include/soc/adc_channel.h b/components/soc/esp32s31/include/soc/adc_channel.h new file mode 100644 index 0000000000..9dbd2ba2b7 --- /dev/null +++ b/components/soc/esp32s31/include/soc/adc_channel.h @@ -0,0 +1,6 @@ +/* + * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 OR MIT + */ +#pragma once diff --git a/components/soc/esp32s31/include/soc/soc_caps.h b/components/soc/esp32s31/include/soc/soc_caps.h index eebff8be56..b4d7e6b620 100644 --- a/components/soc/esp32s31/include/soc/soc_caps.h +++ b/components/soc/esp32s31/include/soc/soc_caps.h @@ -193,6 +193,10 @@ /*-------------------------- Sigma Delta Modulator CAPS -----------------*/ #define SOC_SDM_SUPPORT_SLEEP_RETENTION 1 +/*-------------------------- LEDC CAPS ---------------------------------------*/ +// TODO: [ESP32S31] IDF-14709 +#define SOC_LEDC_CHANNEL_NUM (6) + /*-------------------------- MMU CAPS ----------------------------------------*/ // TODO: [ESP32S31] IDF-14669 #define SOC_MMU_PERIPH_NUM (2U) @@ -256,6 +260,7 @@ /*-------------------------- Flash Encryption CAPS----------------------------*/ // TODO: [ESP32S31] IDF-14628 +#define SOC_FLASH_ENCRYPTION_XTS_AES 1 #define SOC_FLASH_ENCRYPTED_XTS_AES_BLOCK_MAX (64) /*-------------------------- UART CAPS ---------------------------------------*/ diff --git a/docs/conf_common.py b/docs/conf_common.py index d9e4e7910e..437e6a6714 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -331,6 +331,10 @@ ESP32H4_DOCS = [ 'api-guides/phy.rst', ] +ESP32S31_DOCS = [ + 'api-reference/system/ipc.rst', +] + ESP32P4_DOCS = [ 'api-reference/system/ipc.rst', 'api-reference/peripherals/cap_touch_sens.rst', @@ -410,6 +414,7 @@ conditional_include_dict = { 'esp32c61': ESP32C61_DOCS, 'esp32h2': ESP32H2_DOCS, 'esp32h4': ESP32H4_DOCS, + 'esp32s31': ESP32S31_DOCS, 'esp32p4': ESP32P4_DOCS, } diff --git a/docs/doxygen/Doxyfile_esp32s31 b/docs/doxygen/Doxyfile_esp32s31 new file mode 100644 index 0000000000..910f295a01 --- /dev/null +++ b/docs/doxygen/Doxyfile_esp32s31 @@ -0,0 +1 @@ +INPUT += \ diff --git a/docs/en/api-guides/host-apps.rst b/docs/en/api-guides/host-apps.rst index 53b6f21a0a..c1c5eec4b7 100644 --- a/docs/en/api-guides/host-apps.rst +++ b/docs/en/api-guides/host-apps.rst @@ -56,7 +56,7 @@ Since these limitations are not very practical, in particular for testing and de Note furthermore that if you use the ESP-IDF FreeRTOS mock component (``tools/mocks/freertos``), these limitations do not apply. But that mock component will not do any scheduling, either. -.. only:: not esp32p4 and not esp32h4 +.. only:: not esp32p4 and not esp32h4 and not esp32s31 .. note:: diff --git a/docs/en/api-guides/jtag-debugging/esp32s31.inc b/docs/en/api-guides/jtag-debugging/esp32s31.inc new file mode 100644 index 0000000000..bc8005c638 --- /dev/null +++ b/docs/en/api-guides/jtag-debugging/esp32s31.inc @@ -0,0 +1,172 @@ +.. This file gets included from other .rst files in this folder. +.. It contains target-specific snippets. +.. Comments and '---' lines act as delimiters. +.. +.. This is necessary mainly because RST doesn't support substitutions +.. (defined in RST, not in Python) inside code blocks. If that is ever implemented, +.. These code blocks can be moved back to the main .rst files, with target-specific +.. file names being replaced by substitutions. + + +.. run-openocd + +:: + + openocd -f board/esp32s31-builtin.cfg + +.. |run-openocd-device-name| replace:: ESP32-S31 + +--- + +.. run-openocd-output + +:: + + user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s31-builtin.cfg + Open On-Chip Debugger v0.10.0-esp32-20210902 (2021-10-05-23:44) + Licensed under GNU GPL v2 + For bug reports, read + https://openocd.org/doc/doxygen/bugs.html + debug_level: 2 + + Info : only one transport option; autoselect 'jtag' + Warn : Transport "jtag" was already selected + Info : Listening on port 6666 for tcl connections + Info : Listening on port 4444 for telnet connections + Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255 + Info : clock speed 40000 kHz + Info : JTAG tap: esp32s31.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + Info : JTAG tap: esp32s31.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + Info : esp32s31.cpu0: Debug controller was reset. + Info : esp32s31.cpu0: Core was reset. + Info : esp32s31.cpu1: Debug controller was reset. + Info : esp32s31.cpu1: Core was reset. + Info : Listening on port 3333 for gdb connections + +.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s31-builtin.cfg`` + +--- + +.. run-openocd-upload + +:: + + openocd -f board/esp32s31-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit" + +--- + +.. run-openocd-src-linux + +.. code-block:: bash + + src/openocd -f board/esp32s31-builtin.cfg + +--- + +.. run-openocd-src-win + +.. code-block:: batch + + src\openocd -f board/esp32s31-builtin.cfg + +--- + +.. idf-py-openocd-default-cfg + +.. |idf-py-def-cfg| replace:: ``-f board/esp32s31-builtin.cfg`` + +--- + +.. run-openocd-appimage-offset + +:: + + openocd -f board/esp32s31-builtin.cfg -c "init; halt; esp appimage_offset 0x210000" + +--- + +.. openocd-cfg-files + +.. list-table:: OpenOCD configuration files for ESP32-S31 + :widths: 25 75 + :header-rows: 1 + + * - Name + - Description + * - ``board/esp32s31-builtin.cfg`` + - Board configuration file for ESP32-S31 for debugging via builtin USB JTAG, includes target and adapter configuration. + * - ``board/esp32s31-ftdi.cfg`` + - Board configuration file for ESP32-S31 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration. + * - ``target/esp32s31.cfg`` + - ESP32-S31 target configuration file. Can be used together with one of the ``interface/`` configuration files. + * - ``interface/ftdi/esp_usb_jtag.cfg`` + - JTAG adapter configuration file for ESP32-S31 builtin USB JTAG. + * - ``interface/ftdi/esp_ftdi.cfg`` + - JTAG adapter configuration file for ESP-Prog debug adapter board. + +--- + +.. openocd-target-specific-config-vars + +--- + +--- + +.. jtag-pins + +.. list-table:: ESP32-S31 pins and JTAG signals + :widths: 25 75 + :header-rows: 1 + + * - ESP32-S31 Pin + - JTAG Signal + * - MTDO / GPIO40 + - TDO + * - MTDI / GPIO41 + - TDI + * - MTCK / GPIO39 + - TCK + * - MTMS / GPIO42 + - TMS + +.. |jtag-sel-gpio| replace:: GPIO3 +.. |jtag-gpio-list| replace:: GPIO39-GPIO42 + +--- + +.. run-openocd-d3 + +:: + + openocd -l openocd_log.txt -d3 -f board/esp32s31-builtin.cfg + +--- + +.. run-openocd-d3-tee + +:: + + openocd -d3 -f board/esp32s31-builtin.cfg 2>&1 | tee openocd.log + +--- + +.. run-gdb-remotelog + +:: + + xtensa-esp32s31-elf-gdb -ex "set remotelogfile gdb_log.txt" + +--- + +.. devkit-defs + +.. |devkit-name| replace:: ESP32-S31 +.. |devkit-name-with-link| replace:: :doc:`ESP32-S31 <../../hw-reference/index>` + +--- + +.. devkit-hw-config + +* Out of the box, ESP32-S31 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position. + +--- diff --git a/docs/en/api-reference/peripherals/gptimer.rst b/docs/en/api-reference/peripherals/gptimer.rst index 5140abe02b..5ddb93d6e4 100644 --- a/docs/en/api-reference/peripherals/gptimer.rst +++ b/docs/en/api-reference/peripherals/gptimer.rst @@ -296,7 +296,7 @@ The GPTimer driver supports dynamically updating the alarm value in the interrup // Start the timer ESP_ERROR_CHECK(gptimer_start(gptimer)); -.. only:: SOC_TIMER_SUPPORT_ETM +.. only:: SOC_TIMER_SUPPORT_ETM and SOC_ETM_SUPPORTED .. _gptimer-etm-event-and-task: @@ -393,7 +393,7 @@ Application Examples - :example:`peripherals/timer_group/gptimer` demonstrates how to use the general-purpose timer APIs on ESP SOC chips to generate periodic alarm events and trigger different alarm actions. - :example:`peripherals/timer_group/wiegand_interface` uses two timers (one in one-shot alarm mode and the other in periodic alarm mode) to trigger interrupts and change the GPIO output state in the alarm event callback function, simulating the output waveform of the Wiegand protocol. - :SOC_TIMER_SUPPORT_ETM: - :example:`peripherals/timer_group/gptimer_capture_hc_sr04` demonstrates how to use the general-purpose timer and Event Task Matrix (ETM) to accurately capture timestamps of ultrasonic sensor events and convert them into distance information. + :SOC_TIMER_SUPPORT_ETM and SOC_ETM_SUPPORTED: - :example:`peripherals/timer_group/gptimer_capture_hc_sr04` demonstrates how to use the general-purpose timer and Event Task Matrix (ETM) to accurately capture timestamps of ultrasonic sensor events and convert them into distance information. API Reference ============= @@ -416,6 +416,6 @@ GPTimer HAL Types GPTimer ETM APIs ---------------- -.. only:: SOC_TIMER_SUPPORT_ETM +.. only:: SOC_TIMER_SUPPORT_ETM and SOC_ETM_SUPPORTED .. include-build-file:: inc/gptimer_etm.inc diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S31.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S31.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S31.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S31_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S31_dump.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S31_dump.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/en/api-reference/system/inc/power_management_esp32s31.rst b/docs/en/api-reference/system/inc/power_management_esp32s31.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/en/api-reference/system/inc/power_management_esp32s31.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/en/api-reference/system/inc/revisions_ESP32-S31.rst b/docs/en/api-reference/system/inc/revisions_ESP32-S31.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/en/api-reference/system/inc/revisions_ESP32-S31.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/en/api-reference/system/inc/show-efuse-table_ESP32-S31.rst b/docs/en/api-reference/system/inc/show-efuse-table_ESP32-S31.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/en/api-reference/system/inc/show-efuse-table_ESP32-S31.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/en/get-started/esp32s31_output_log.inc b/docs/en/get-started/esp32s31_output_log.inc new file mode 100644 index 0000000000..99c9825c3f --- /dev/null +++ b/docs/en/get-started/esp32s31_output_log.inc @@ -0,0 +1,30 @@ +.. output_log + +.. code-block:: none + + ... + esptool --chip esp32s31 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin + esptool v5.0.2 + Connected to ESP32-S31 on /dev/ttyUSB0: + Chip type: ESP32-S31 (revision v0.0) + Features: Wi-Fi, BT 5 (LE), IEEE802.15.4, Dual Core, 240MHz, Embedded PSRAM + Crystal frequency: 40MHz + MAC: f4:12:fa:87:c6:dc + + Stub flasher running. + Changing baud rate to 460800... + Changed. + + Configuring flash size... + Flash will be erased from 0x00000000 to 0x00005fff... + Flash will be erased from 0x00008000 to 0x00008fff... + Flash will be erased from 0x00010000 to 0x00037fff... + SHA digest in image updated. + Wrote 21280 bytes (13578 compressed) at 0x00000000 in 0.6 seconds (298.1 kbit/s). + Hash of data verified. + Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (315.1 kbit/s). + Hash of data verified. + Wrote 161744 bytes (90141 compressed) at 0x00010000 in 2.5 seconds (513.7 kbit/s). + Hash of data verified. + + Hard resetting via RTS pin... diff --git a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst index 65a7634469..672368cd12 100644 --- a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst @@ -148,54 +148,56 @@ UART - ``soc/uart_channel.h`` header file has been removed. All UART GPIO lookup macros can be found in ``soc/uart_pins.h``. For example, ``UART_NUM_0_TXD_DIRECT_GPIO_NUM`` is equivalent to ``U0TXD_GPIO_NUM``. -I2C ---- +.. only:: SOC_I2C_SUPPORTED -Legacy I2C Driver End-of-Life -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + I2C + --- -.. warning:: + Legacy I2C Driver End-of-Life + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The legacy I2C driver (``driver/i2c.h``) has been marked as **End-of-Life (EOL)** in ESP-IDF v6.0 and is scheduled for **removal in v7.0**. + .. warning:: - - ESP-IDF will not provide updates, bug fixes, or security patches for the legacy driver timely. - - Users are strongly recommended to migrate to the new I2C drivers: ``driver/i2c_master.h`` and ``driver/i2c_slave.h``. - - To temporarily suppress the compile-time warning, enable ``Component config`` > ``Legacy Driver Configurations`` > ``Legacy I2C Driver Configurations`` > ``Suppress legacy driver deprecated warning`` in menuconfig. + The legacy I2C driver (``driver/i2c.h``) has been marked as **End-of-Life (EOL)** in ESP-IDF v6.0 and is scheduled for **removal in v7.0**. -The new I2C drivers provide improved slave and master functionality. For details, please refer to the :ref:`I2C Migration Guide ` and the :doc:`I2C Driver Programming Guide <../../../api-reference/peripherals/i2c>`. + - ESP-IDF will not provide updates, bug fixes, or security patches for the legacy driver timely. + - Users are strongly recommended to migrate to the new I2C drivers: ``driver/i2c_master.h`` and ``driver/i2c_slave.h``. + - To temporarily suppress the compile-time warning, enable ``Component config`` > ``Legacy Driver Configurations`` > ``Legacy I2C Driver Configurations`` > ``Suppress legacy driver deprecated warning`` in menuconfig. -I2C Slave Driver Updates -~~~~~~~~~~~~~~~~~~~~~~~~~ + The new I2C drivers provide improved slave and master functionality. For details, please refer to the :ref:`I2C Migration Guide ` and the :doc:`I2C Driver Programming Guide <../../../api-reference/peripherals/i2c>`. -The I2C slave driver has been redesigned in v5.4. In the current version, the old I2C slave driver has been removed. + I2C Slave Driver Updates + ~~~~~~~~~~~~~~~~~~~~~~~~~ -Major Changes in Concepts -^^^^^^^^^^^^^^^^^^^^^^^^^ + The I2C slave driver has been redesigned in v5.4. In the current version, the old I2C slave driver has been removed. -- Previously, the I2C slave driver performed active read and write operations. In the new version, these operations are handled passively via callbacks triggered by master events, aligning with standard I2C slave behavior. + Major Changes in Concepts + ^^^^^^^^^^^^^^^^^^^^^^^^^ -Major Changes in Usage -^^^^^^^^^^^^^^^^^^^^^^ + - Previously, the I2C slave driver performed active read and write operations. In the new version, these operations are handled passively via callbacks triggered by master events, aligning with standard I2C slave behavior. -- ``i2c_slave_receive`` has been removed. In the new driver, data reception is handled via callbacks. -- ``i2c_slave_transmit`` has been replaced by ``i2c_slave_write``. -- ``i2c_slave_write_ram`` has been removed. -- ``i2c_slave_read_ram`` has been removed. + Major Changes in Usage + ^^^^^^^^^^^^^^^^^^^^^^ -I2C Master Driver Updates -~~~~~~~~~~~~~~~~~~~~~~~~~~ + - ``i2c_slave_receive`` has been removed. In the new driver, data reception is handled via callbacks. + - ``i2c_slave_transmit`` has been replaced by ``i2c_slave_write``. + - ``i2c_slave_write_ram`` has been removed. + - ``i2c_slave_read_ram`` has been removed. -The I2C master driver also has some changes in its API definitions. + I2C Master Driver Updates + ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Major Changes in Usage -^^^^^^^^^^^^^^^^^^^^^^ + The I2C master driver also has some changes in its API definitions. -Following functions now will return ``ESP_ERR_INVALID_RESPONSE`` instead of ``ESP_ERR_INVALID_STATE`` when NACK from the bus is detected: + Major Changes in Usage + ^^^^^^^^^^^^^^^^^^^^^^ -- ``i2c_master_transmit`` -- ``i2c_master_multi_buffer_transmit`` -- ``i2c_master_transmit_receive`` -- ``i2c_master_execute_defined_operations`` + Following functions now will return ``ESP_ERR_INVALID_RESPONSE`` instead of ``ESP_ERR_INVALID_STATE`` when NACK from the bus is detected: + + - ``i2c_master_transmit`` + - ``i2c_master_multi_buffer_transmit`` + - ``i2c_master_transmit_receive`` + - ``i2c_master_execute_defined_operations`` Legacy Timer Group Driver is Removed ------------------------------------ diff --git a/docs/en/security/esp32s31_log.inc b/docs/en/security/esp32s31_log.inc new file mode 100644 index 0000000000..984eb9675d --- /dev/null +++ b/docs/en/security/esp32s31_log.inc @@ -0,0 +1,131 @@ + +.. first_boot_enc + +.. code-block:: none + + ESP-ROM:esp32s31-20210327 + Build:Mar 27 2021 + rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT) + SPIWP:0xee + mode:DIO, clock div:1 + load:0x3fcd0270,len:0x2598 + load:0x403b6000,len:0x878 + load:0x403ba000,len:0x3dd4 + entry 0x403b61c0 + I (27) boot: ESP-IDF v4.4-dev-2003-g72fdecc1b7-dirty 2nd stage bootloader + I (28) boot: compile time 14:15:37 + I (28) boot: chip revision: 0 + I (32) boot.esp32s31: SPI Speed : 80MHz + I (36) boot.esp32s31: SPI Mode : DIO + I (41) boot.esp32s31: SPI Flash Size : 2MB + I (46) boot: Enabling RNG early entropy source... + I (58) boot: Partition Table: + I (62) boot: ## Label Usage Type ST Offset Length + I (69) boot: 0 nvs WiFi data 01 02 0000a000 00006000 + I (76) boot: 1 storage Unknown data 01 ff 00010000 00001000 + I (84) boot: 2 factory factory app 00 00 00020000 00100000 + I (91) boot: 3 nvs_key NVS keys 01 04 00120000 00001000 + I (99) boot: End of partition table + I (103) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048) map + I (117) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204) load + I (122) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260) load + I (134) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304) map + I (156) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392) load + I (162) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16) load + I (167) boot: Loaded app from partition at offset 0x20000 + I (168) boot: Checking flash encryption... + I (173) efuse: Batch mode of writing fields is enabled + I (179) flash_encrypt: Generating new flash encryption key... + I (188) efuse: Writing EFUSE_BLK_KEY0 with purpose 4 + W (194) flash_encrypt: Not disabling UART bootloader encryption + I (197) flash_encrypt: Disable UART bootloader cache... + I (203) flash_encrypt: Disable JTAG... + I (212) efuse: Batch mode. Prepared fields are committed + I (214) esp_image: segment 0: paddr=00000020 vaddr=3fcd0270 size=02598h ( 9624) + I (223) esp_image: segment 1: paddr=000025c0 vaddr=403b6000 size=00878h ( 2168) + I (230) esp_image: segment 2: paddr=00002e40 vaddr=403ba000 size=03dd4h ( 15828) + I (534) flash_encrypt: bootloader encrypted successfully + I (578) flash_encrypt: partition table encrypted and loaded successfully + I (578) flash_encrypt: Encrypting partition 1 at offset 0x10000 (length 0x1000)... + I (628) flash_encrypt: Done encrypting + I (629) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048) map + I (636) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204) + I (640) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260) + I (651) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304) map + I (675) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392) + I (679) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16) + I (680) flash_encrypt: Encrypting partition 2 at offset 0x20000 (length 0x100000)... + I (11571) flash_encrypt: Done encrypting + I (11571) flash_encrypt: Encrypting partition 3 at offset 0x120000 (length 0x1000)... + I (11617) flash_encrypt: Done encrypting + I (11618) flash_encrypt: Flash encryption completed + I (11623) boot: Resetting with flash encryption enabled... + +------ + +.. already_en_enc + +.. code-block:: none + + ESP-ROM:esp32s31-20210327 + Build:Mar 27 2021 + rst:0x3 (RTC_SW_SYS_RST),boot:0x8 (SPI_FAST_FLASH_BOOT) + Saved PC:0x403bb1d6 + SPIWP:0xee + mode:DIO, clock div:1 + load:0x3fcd0270,len:0x2598 + load:0x403b6000,len:0x878 + load:0x403ba000,len:0x3dd4 + entry 0x403b61c0 + I (35) boot: ESP-IDF v4.4-dev-2003-g72fdecc1b7-dirty 2nd stage bootloader + I (35) boot: compile time 14:15:37 + I (35) boot: chip revision: 0 + I (39) boot.esp32s31: SPI Speed : 80MHz + I (44) boot.esp32s31: SPI Mode : DIO + I (48) boot.esp32s31: SPI Flash Size : 2MB + I (53) boot: Enabling RNG early entropy source... + I (65) boot: Partition Table: + I (69) boot: ## Label Usage Type ST Offset Length + I (76) boot: 0 nvs WiFi data 01 02 0000a000 00006000 + I (84) boot: 1 storage Unknown data 01 ff 00010000 00001000 + I (91) boot: 2 factory factory app 00 00 00020000 00100000 + I (99) boot: 3 nvs_key NVS keys 01 04 00120000 00001000 + I (106) boot: End of partition table + I (110) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048) map + I (126) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204) load + I (129) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260) load + I (141) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304) map + I (166) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392) load + I (172) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16) load + I (177) boot: Loaded app from partition at offset 0x20000 + I (178) boot: Checking flash encryption... + I (183) flash_encrypt: flash encryption is enabled (1 plaintext flashes left) + I (190) boot: Disabling RNG early entropy source... + I (214) cpu_start: Pro cpu up. + I (214) cpu_start: Starting app cpu, entry point is 0x40374fa8 + I (0) cpu_start: App cpu up. + I (228) cpu_start: Pro cpu start user code + I (228) cpu_start: cpu freq: 160000000 + I (228) cpu_start: Application information: + I (231) cpu_start: Project name: flash_encryption + I (237) cpu_start: App version: v4.4-dev-2003-g72fdecc1b7-dirty + I (244) cpu_start: Compile time: Jul 12 2021 14:15:34 + I (250) cpu_start: ELF file SHA256: a7e6343c6a1c2215... + I (256) cpu_start: ESP-IDF: v4.4-dev-2003-g72fdecc1b7-dirty + I (263) heap_init: Initializing. RAM available for dynamic allocation: + I (270) heap_init: At 3FC92810 len 0004D7F0 (309 KiB): D/IRAM + I (277) heap_init: At 3FCE0000 len 0000EE34 (59 KiB): STACK/DRAM + I (283) heap_init: At 3FCF0000 len 00008000 (32 KiB): DRAM + I (290) spi_flash: detected chip: generic + I (294) spi_flash: flash io: dio + W (298) spi_flash: Detected size(8192k) larger than the size in the binary image header(2048k). Using the size in the binary image header. + I (311) flash_encrypt: Flash encryption mode is DEVELOPMENT (not secure) + I (318) cpu_start: Starting scheduler on PRO CPU. + I (0) cpu_start: Starting scheduler on APP CPU. + + Example to check Flash Encryption status + This is esp32s31 chip with 2 CPU core(s), WiFi/BLE/IEEE802.15.4, silicon revision 0, 2MB external flash + FLASH_CRYPT_CNT eFuse value is 1 + Flash encryption feature is enabled in DEVELOPMENT mode + +------ diff --git a/docs/zh_CN/api-guides/host-apps.rst b/docs/zh_CN/api-guides/host-apps.rst index dd71e4d43e..c37a308d45 100644 --- a/docs/zh_CN/api-guides/host-apps.rst +++ b/docs/zh_CN/api-guides/host-apps.rst @@ -56,7 +56,7 @@ ESP-IDF 已支持使用 `FreeRTOS POSIX/Linux 模拟器 &1 | tee openocd.log + +--- + +.. run-gdb-remotelog + +:: + + xtensa-esp32s31-elf-gdb -ex "set remotelogfile gdb_log.txt" + +--- + +.. devkit-defs + +.. |devkit-name| replace:: ESP32-S31 +.. |devkit-name-with-link| replace:: :doc:`ESP32-S31 <../../hw-reference/index>` + +--- + +.. devkit-hw-config + +* Out of the box, ESP32-S31 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position. + +--- diff --git a/docs/zh_CN/api-reference/peripherals/gptimer.rst b/docs/zh_CN/api-reference/peripherals/gptimer.rst index 0a75387258..b295686e80 100644 --- a/docs/zh_CN/api-reference/peripherals/gptimer.rst +++ b/docs/zh_CN/api-reference/peripherals/gptimer.rst @@ -296,7 +296,7 @@ GPTimer 驱动支持在中断回调函数中调用 :cpp:func:`gptimer_set_alarm_ // 启动定时器 ESP_ERROR_CHECK(gptimer_start(gptimer)); -.. only:: SOC_TIMER_SUPPORT_ETM +.. only:: SOC_TIMER_SUPPORT_ETM and SOC_ETM_SUPPORTED .. _gptimer-etm-event-and-task: @@ -393,7 +393,7 @@ GPTimer 驱动支持在中断回调函数中调用 :cpp:func:`gptimer_set_alarm_ - :example:`peripherals/timer_group/gptimer` 演示了如何在 ESP 芯片上使用通用定时器 API 生成周期性警报事件，触发不同的警报动作。 - :example:`peripherals/timer_group/wiegand_interface` 使用两个定时器（一个在单次警报模式下，另一个在周期警报模式下），触发中断并在警报事件的回调函数中改变 GPIO 的输出状态，从而模拟出了 Wiegand 协议的输出波形。 - :SOC_TIMER_SUPPORT_ETM: - :example:`peripherals/timer_group/gptimer_capture_hc_sr04` 展示了如何使用通用定时器和事件任务矩阵(ETM)来精确捕获超声波传感器事件的时间戳，并据此换算成距离信息。 + :SOC_TIMER_SUPPORT_ETM and SOC_ETM_SUPPORTED: - :example:`peripherals/timer_group/gptimer_capture_hc_sr04` 展示了如何使用通用定时器和事件任务矩阵(ETM)来精确捕获超声波传感器事件的时间戳，并据此换算成距离信息。 API 参考 ======== @@ -413,7 +413,7 @@ GPTimer HAL 类型 .. include-build-file:: inc/timer_types.inc -.. only:: SOC_TIMER_SUPPORT_ETM +.. only:: SOC_TIMER_SUPPORT_ETM and SOC_ETM_SUPPORTED GPTimer ETM API --------------- diff --git a/docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-S31.rst b/docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-S31.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-S31.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-S31_dump.rst b/docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-S31_dump.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/zh_CN/api-reference/system/inc/espefuse_summary_ESP32-S31_dump.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/zh_CN/api-reference/system/inc/power_management_esp32s31.rst b/docs/zh_CN/api-reference/system/inc/power_management_esp32s31.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/zh_CN/api-reference/system/inc/power_management_esp32s31.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/zh_CN/api-reference/system/inc/revisions_ESP32-S31.rst b/docs/zh_CN/api-reference/system/inc/revisions_ESP32-S31.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/zh_CN/api-reference/system/inc/revisions_ESP32-S31.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/zh_CN/api-reference/system/inc/show-efuse-table_ESP32-S31.rst b/docs/zh_CN/api-reference/system/inc/show-efuse-table_ESP32-S31.rst new file mode 100644 index 0000000000..94c835a6e4 --- /dev/null +++ b/docs/zh_CN/api-reference/system/inc/show-efuse-table_ESP32-S31.rst @@ -0,0 +1,3 @@ +.. note:: + + To be updated. diff --git a/docs/zh_CN/get-started/esp32s31_output_log.inc b/docs/zh_CN/get-started/esp32s31_output_log.inc new file mode 100644 index 0000000000..99c9825c3f --- /dev/null +++ b/docs/zh_CN/get-started/esp32s31_output_log.inc @@ -0,0 +1,30 @@ +.. output_log + +.. code-block:: none + + ... + esptool --chip esp32s31 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin + esptool v5.0.2 + Connected to ESP32-S31 on /dev/ttyUSB0: + Chip type: ESP32-S31 (revision v0.0) + Features: Wi-Fi, BT 5 (LE), IEEE802.15.4, Dual Core, 240MHz, Embedded PSRAM + Crystal frequency: 40MHz + MAC: f4:12:fa:87:c6:dc + + Stub flasher running. + Changing baud rate to 460800... + Changed. + + Configuring flash size... + Flash will be erased from 0x00000000 to 0x00005fff... + Flash will be erased from 0x00008000 to 0x00008fff... + Flash will be erased from 0x00010000 to 0x00037fff... + SHA digest in image updated. + Wrote 21280 bytes (13578 compressed) at 0x00000000 in 0.6 seconds (298.1 kbit/s). + Hash of data verified. + Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (315.1 kbit/s). + Hash of data verified. + Wrote 161744 bytes (90141 compressed) at 0x00010000 in 2.5 seconds (513.7 kbit/s). + Hash of data verified. + + Hard resetting via RTS pin... diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst index 1616812998..6278c89d00 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst @@ -148,54 +148,56 @@ UART - ``soc/uart_channel.h`` 头文件已被移除。所有 UART GPIO 查找宏都可以在 ``soc/uart_pins.h`` 中找到。例如，``UART_NUM_0_TXD_DIRECT_GPIO_NUM`` 等同于 ``U0TXD_GPIO_NUM``。 -I2C ---- +.. only:: SOC_I2C_SUPPORTED -旧版 I2C 驱动生命周期终止 -~~~~~~~~~~~~~~~~~~~~~~~~~~ + I2C + --- -.. warning:: + 旧版 I2C 驱动生命周期终止 + ~~~~~~~~~~~~~~~~~~~~~~~~~~ - 旧版 I2C 驱动（``driver/i2c.h``）已在 ESP-IDF v6.0 中被标记为 **生命周期终止（End-of-Life, EOL）**，并计划在 **v7.0 中彻底移除**。 + .. warning:: - - ESP-IDF 将不再为旧版驱动提供及时的更新、错误修复或安全补丁。 - - 强烈建议用户尽快迁移到新版 I2C 驱动：``driver/i2c_master.h`` 和 ``driver/i2c_slave.h``。 - - 如需暂时抑制编译警告，可在 menuconfig 中启用 ``Component config`` > ``Legacy Driver Configurations`` > ``Legacy I2C Driver Configurations`` > ``Suppress legacy driver deprecated warning``。 + 旧版 I2C 驱动（``driver/i2c.h``）已在 ESP-IDF v6.0 中被标记为 **生命周期终止（End-of-Life, EOL）**，并计划在 **v7.0 中彻底移除**。 -新版 I2C 驱动主要改进了从机和主机的使用方式，详细内容请参考 :ref:`I2C 迁移指南 ` 和 :doc:`I2C 驱动编程指南 <../../../api-reference/peripherals/i2c>`。 + - ESP-IDF 将不再为旧版驱动提供及时的更新、错误修复或安全补丁。 + - 强烈建议用户尽快迁移到新版 I2C 驱动：``driver/i2c_master.h`` 和 ``driver/i2c_slave.h``。 + - 如需暂时抑制编译警告，可在 menuconfig 中启用 ``Component config`` > ``Legacy Driver Configurations`` > ``Legacy I2C Driver Configurations`` > ``Suppress legacy driver deprecated warning``。 -I2C 从机驱动更新 -~~~~~~~~~~~~~~~~~~ + 新版 I2C 驱动主要改进了从机和主机的使用方式，详细内容请参考 :ref:`I2C 迁移指南 ` 和 :doc:`I2C 驱动编程指南 <../../../api-reference/peripherals/i2c>`。 -I2C 从机驱动在 v5.4 上已经被重新设计。在当前版本上，旧的 I2C 从机驱动已经被移除。 + I2C 从机驱动更新 + ~~~~~~~~~~~~~~~~~~ -主要概念更新 -^^^^^^^^^^^^ + I2C 从机驱动在 v5.4 上已经被重新设计。在当前版本上，旧的 I2C 从机驱动已经被移除。 -- 旧版本的 I2C 从机驱动是主动读写，这不符合 I2C 从机的一般用法。在新版的 I2C 从机中，I2C 的读写通过主机驱动产生的事件以触发回调被动完成。 + 主要概念更新 + ^^^^^^^^^^^^ -主要用法更新 -^^^^^^^^^^^^ + - 旧版本的 I2C 从机驱动是主动读写，这不符合 I2C 从机的一般用法。在新版的 I2C 从机中，I2C 的读写通过主机驱动产生的事件以触发回调被动完成。 -- ``i2c_slave_receive`` 被移除，在新驱动中使用回调接收数据。 -- ``i2c_slave_transmit`` 已被 ``i2c_slave_write`` 取代。 -- ``i2c_slave_write_ram`` 被移除。 -- ``i2c_slave_read_ram`` 被移除。 + 主要用法更新 + ^^^^^^^^^^^^ -I2C 主机驱动更新 -~~~~~~~~~~~~~~~~~~ + - ``i2c_slave_receive`` 被移除，在新驱动中使用回调接收数据。 + - ``i2c_slave_transmit`` 已被 ``i2c_slave_write`` 取代。 + - ``i2c_slave_write_ram`` 被移除。 + - ``i2c_slave_read_ram`` 被移除。 -I2C 主机驱动的 API 也有一些用法上的改动。 + I2C 主机驱动更新 + ~~~~~~~~~~~~~~~~~~ -主要用法更新 -^^^^^^^^^^^^ + I2C 主机驱动的 API 也有一些用法上的改动。 -当主机在 I2C 总线上检测到 NACK，以下的函数目前会返回 ``ESP_ERR_INVALID_RESPONSE``，而不是像之前一样返回 ``ESP_ERR_INVALID_STATE``： + 主要用法更新 + ^^^^^^^^^^^^ -- ``i2c_master_transmit`` -- ``i2c_master_multi_buffer_transmit`` -- ``i2c_master_transmit_receive`` -- ``i2c_master_execute_defined_operations`` + 当主机在 I2C 总线上检测到 NACK，以下的函数目前会返回 ``ESP_ERR_INVALID_RESPONSE``，而不是像之前一样返回 ``ESP_ERR_INVALID_STATE``： + + - ``i2c_master_transmit`` + - ``i2c_master_multi_buffer_transmit`` + - ``i2c_master_transmit_receive`` + - ``i2c_master_execute_defined_operations`` 旧版定时器组驱动被移除 ---------------------- diff --git a/docs/zh_CN/security/esp32s31_log.inc b/docs/zh_CN/security/esp32s31_log.inc new file mode 100644 index 0000000000..984eb9675d --- /dev/null +++ b/docs/zh_CN/security/esp32s31_log.inc @@ -0,0 +1,131 @@ + +.. first_boot_enc + +.. code-block:: none + + ESP-ROM:esp32s31-20210327 + Build:Mar 27 2021 + rst:0x1 (POWERON),boot:0x8 (SPI_FAST_FLASH_BOOT) + SPIWP:0xee + mode:DIO, clock div:1 + load:0x3fcd0270,len:0x2598 + load:0x403b6000,len:0x878 + load:0x403ba000,len:0x3dd4 + entry 0x403b61c0 + I (27) boot: ESP-IDF v4.4-dev-2003-g72fdecc1b7-dirty 2nd stage bootloader + I (28) boot: compile time 14:15:37 + I (28) boot: chip revision: 0 + I (32) boot.esp32s31: SPI Speed : 80MHz + I (36) boot.esp32s31: SPI Mode : DIO + I (41) boot.esp32s31: SPI Flash Size : 2MB + I (46) boot: Enabling RNG early entropy source... + I (58) boot: Partition Table: + I (62) boot: ## Label Usage Type ST Offset Length + I (69) boot: 0 nvs WiFi data 01 02 0000a000 00006000 + I (76) boot: 1 storage Unknown data 01 ff 00010000 00001000 + I (84) boot: 2 factory factory app 00 00 00020000 00100000 + I (91) boot: 3 nvs_key NVS keys 01 04 00120000 00001000 + I (99) boot: End of partition table + I (103) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048) map + I (117) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204) load + I (122) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260) load + I (134) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304) map + I (156) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392) load + I (162) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16) load + I (167) boot: Loaded app from partition at offset 0x20000 + I (168) boot: Checking flash encryption... + I (173) efuse: Batch mode of writing fields is enabled + I (179) flash_encrypt: Generating new flash encryption key... + I (188) efuse: Writing EFUSE_BLK_KEY0 with purpose 4 + W (194) flash_encrypt: Not disabling UART bootloader encryption + I (197) flash_encrypt: Disable UART bootloader cache... + I (203) flash_encrypt: Disable JTAG... + I (212) efuse: Batch mode. Prepared fields are committed + I (214) esp_image: segment 0: paddr=00000020 vaddr=3fcd0270 size=02598h ( 9624) + I (223) esp_image: segment 1: paddr=000025c0 vaddr=403b6000 size=00878h ( 2168) + I (230) esp_image: segment 2: paddr=00002e40 vaddr=403ba000 size=03dd4h ( 15828) + I (534) flash_encrypt: bootloader encrypted successfully + I (578) flash_encrypt: partition table encrypted and loaded successfully + I (578) flash_encrypt: Encrypting partition 1 at offset 0x10000 (length 0x1000)... + I (628) flash_encrypt: Done encrypting + I (629) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048) map + I (636) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204) + I (640) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260) + I (651) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304) map + I (675) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392) + I (679) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16) + I (680) flash_encrypt: Encrypting partition 2 at offset 0x20000 (length 0x100000)... + I (11571) flash_encrypt: Done encrypting + I (11571) flash_encrypt: Encrypting partition 3 at offset 0x120000 (length 0x1000)... + I (11617) flash_encrypt: Done encrypting + I (11618) flash_encrypt: Flash encryption completed + I (11623) boot: Resetting with flash encryption enabled... + +------ + +.. already_en_enc + +.. code-block:: none + + ESP-ROM:esp32s31-20210327 + Build:Mar 27 2021 + rst:0x3 (RTC_SW_SYS_RST),boot:0x8 (SPI_FAST_FLASH_BOOT) + Saved PC:0x403bb1d6 + SPIWP:0xee + mode:DIO, clock div:1 + load:0x3fcd0270,len:0x2598 + load:0x403b6000,len:0x878 + load:0x403ba000,len:0x3dd4 + entry 0x403b61c0 + I (35) boot: ESP-IDF v4.4-dev-2003-g72fdecc1b7-dirty 2nd stage bootloader + I (35) boot: compile time 14:15:37 + I (35) boot: chip revision: 0 + I (39) boot.esp32s31: SPI Speed : 80MHz + I (44) boot.esp32s31: SPI Mode : DIO + I (48) boot.esp32s31: SPI Flash Size : 2MB + I (53) boot: Enabling RNG early entropy source... + I (65) boot: Partition Table: + I (69) boot: ## Label Usage Type ST Offset Length + I (76) boot: 0 nvs WiFi data 01 02 0000a000 00006000 + I (84) boot: 1 storage Unknown data 01 ff 00010000 00001000 + I (91) boot: 2 factory factory app 00 00 00020000 00100000 + I (99) boot: 3 nvs_key NVS keys 01 04 00120000 00001000 + I (106) boot: End of partition table + I (110) esp_image: segment 0: paddr=00020020 vaddr=3c020020 size=08118h ( 33048) map + I (126) esp_image: segment 1: paddr=00028140 vaddr=3fc8fa30 size=023f4h ( 9204) load + I (129) esp_image: segment 2: paddr=0002a53c vaddr=40374000 size=05adch ( 23260) load + I (141) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=1a710h (108304) map + I (166) esp_image: segment 4: paddr=0004a738 vaddr=40379adc size=05f48h ( 24392) load + I (172) esp_image: segment 5: paddr=00050688 vaddr=600fe000 size=00010h ( 16) load + I (177) boot: Loaded app from partition at offset 0x20000 + I (178) boot: Checking flash encryption... + I (183) flash_encrypt: flash encryption is enabled (1 plaintext flashes left) + I (190) boot: Disabling RNG early entropy source... + I (214) cpu_start: Pro cpu up. + I (214) cpu_start: Starting app cpu, entry point is 0x40374fa8 + I (0) cpu_start: App cpu up. + I (228) cpu_start: Pro cpu start user code + I (228) cpu_start: cpu freq: 160000000 + I (228) cpu_start: Application information: + I (231) cpu_start: Project name: flash_encryption + I (237) cpu_start: App version: v4.4-dev-2003-g72fdecc1b7-dirty + I (244) cpu_start: Compile time: Jul 12 2021 14:15:34 + I (250) cpu_start: ELF file SHA256: a7e6343c6a1c2215... + I (256) cpu_start: ESP-IDF: v4.4-dev-2003-g72fdecc1b7-dirty + I (263) heap_init: Initializing. RAM available for dynamic allocation: + I (270) heap_init: At 3FC92810 len 0004D7F0 (309 KiB): D/IRAM + I (277) heap_init: At 3FCE0000 len 0000EE34 (59 KiB): STACK/DRAM + I (283) heap_init: At 3FCF0000 len 00008000 (32 KiB): DRAM + I (290) spi_flash: detected chip: generic + I (294) spi_flash: flash io: dio + W (298) spi_flash: Detected size(8192k) larger than the size in the binary image header(2048k). Using the size in the binary image header. + I (311) flash_encrypt: Flash encryption mode is DEVELOPMENT (not secure) + I (318) cpu_start: Starting scheduler on PRO CPU. + I (0) cpu_start: Starting scheduler on APP CPU. + + Example to check Flash Encryption status + This is esp32s31 chip with 2 CPU core(s), WiFi/BLE/IEEE802.15.4, silicon revision 0, 2MB external flash + FLASH_CRYPT_CNT eFuse value is 1 + Flash encryption feature is enabled in DEVELOPMENT mode + +------