Merge branch 'feature/qemu_doc_guide_updates' into 'master'

docs: misc updates to qemu guide, now enabled for ESP32-S3

See merge request espressif/esp-idf!33854

.gitlab/CODEOWNERS

@@ -159,6 +159,7 @@
 /components/xtensa/                   @esp-idf-codeowners/system
 
 /docs/                                      @esp-idf-codeowners/docs
+/docs/docs_not_updated/                     @esp-idf-codeowners/all-maintainers
 /docs/**/api-guides/tools/                  @esp-idf-codeowners/tools
 /docs/en/api-guides/core_dump.rst           @esp-idf-codeowners/debugging
 /docs/en/api-guides/jtag-debugging/         @esp-idf-codeowners/debugging

docs/conf_common.py

@@ -218,7 +218,7 @@
                 'api-reference/peripherals/touch_pad.rst',
                 'api-reference/peripherals/sd_pullup_requirements.rst',
                 'api-guides/RF_calibration.rst',
-                'api-guides/phy.rst'] + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS
+                'api-guides/phy.rst'] + USB_OTG_DFU_DOCS + USB_OTG_CONSOLE_DOCS + QEMU_DOCS
 
 # No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below.
 ESP32C3_DOCS = ['hw-reference/esp32c3/**',
@@ -379,13 +379,20 @@
 
 idf_build_system = {'doxygen_component_info': True, 'component_info_ignore_file': Path(os.environ['IDF_PATH']) / 'docs' / 'component_info_ignore_file.txt'}
 
+# Please update following list to enable Qemu doc guide (and cross references) for a new target
+QEMU_TARGETS = ['esp32', 'esp32c3', 'esp32s3']
+
 
 # Callback function for user setup that needs be done after `config-init`-event
 # config.idf_target is not available at the initial config stage
 def conf_setup(app, config):
     config.add_warnings_content = 'This document is not updated for {} yet, so some of the content may not be correct.'.format(config.idf_target.upper())
 
     add_warnings_file = '{}/../docs_not_updated/{}.txt'.format(app.confdir, config.idf_target)
+
+    if config.idf_target in QEMU_TARGETS:
+        app.tags.add('TARGET_SUPPORT_QEMU')
+
     try:
         with open(add_warnings_file) as warning_file:
             config.add_warnings_pages = warning_file.read().splitlines()

docs/en/api-guides/bootloader.rst

@@ -6,7 +6,7 @@ Bootloader
 The ESP-IDF Software Bootloader performs the following functions:
 
 1. Minimal initial configuration of internal modules;
-2. Initialize :doc:`/security/flash-encryption` and/or :doc:`Secure </security/secure-boot-v2>` features, if configured;
+2. Initialize :doc:`/security/flash-encryption` and/or :doc:`Secure Boot </security/secure-boot-v2>` features, if configured;
 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.
 

docs/en/api-guides/tools/index.rst

@@ -12,4 +12,4 @@ Tools
    idf-clang-tidy
    idf-tools
    idf-size
-   :esp32 or esp32c3: qemu
+   :TARGET_SUPPORT_QEMU: qemu

docs/en/api-guides/tools/qemu.rst

@@ -1,6 +1,8 @@
 QEMU Emulator
 =============
 
+{IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"}
+
 :link_to_translation:`zh_CN:[中文]`
 
 Espressif maintains a `fork <https://github.com/espressif/qemu>`_ of the QEMU emulator with support for {IDF_TARGET_NAME}. This fork implements emulation of the CPU, memory, and several peripherals of {IDF_TARGET_NAME}. For more information about QEMU for {IDF_TARGET_NAME}, see the `QEMU README documentation <https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/README.md>`_.
@@ -119,13 +121,37 @@ QEMU supports emulation of eFuses. This can be a convenient way to test security
 
 You can use :doc:`idf.py<idf-py>` eFuse-related commands to program eFuses. When you run any of these commands together with ``qemu`` command, the eFuses are programmed in QEMU, and the ``qemu_efuse.bin`` file is updated. For example,
 
+.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
+
+    .. code-block:: console
+
+        idf.py qemu efuse-burn {IDF_TARGET_CRYPT_CNT} 1
+        idf.py qemu efuse-burn-key flash_encryption my_flash_encryption_key.bin
+
+.. only:: SOC_FLASH_ENCRYPTION_XTS_AES
+
+    .. code-block:: console
+
+        idf.py qemu efuse-burn {IDF_TARGET_CRYPT_CNT} 1
+        idf.py qemu efuse-burn-key BLOCK my_flash_encryption_key.bin KEYPURPOSE
+
+    For details regarding the ``BLOCK`` and ``KEYPURPOSE``, please refer to the :doc:`../../security/flash-encryption` guide.
+
+To dump the eFuse summary, please use the following command:
+
 .. code-block:: console
 
-    idf.py qemu efuse-burn FLASH_CRYPT_CNT 1
+    idf.py qemu efuse-summary
 
 By default, the values of eFuses are read from and written to the ``qemu_efuse.bin`` file in the build directory. You can specify a different file using the ``--efuse-file`` option. For example,
 
 .. code-block:: console
 
-    idf.py qemu --efuse-file my_efuse.bin efuse-burn FLASH_CRYPT_CNT 1
+    idf.py qemu --efuse-file my_efuse.bin efuse-burn {IDF_TARGET_CRYPT_CNT} 1
     idf.py qemu --efuse-file my_efuse.bin monitor
+
+Emulating Secure Boot
+~~~~~~~~~~~~~~~~~~~~~
+
+QEMU supports emulation of secure boot v2 scheme. Please keep :ref:`CONFIG_SECURE_BOOT_FLASH_BOOTLOADER_DEFAULT` enabled to include signed bootloader image into the QEMU image artifact.
+

docs/en/security/security-features-enablement-workflows.rst

@@ -18,6 +18,11 @@ When enabling security features on ESP32 SoCs, it is recommended that power supp
 
 This guide describes a set of workflows to enable security features on the device with the assistance of an external host machine. These workflows are broken down into various stages, with each stage generating signing/encryption keys on the host machine. This allows for greater chances of recovery in case of power or other failures. Furthermore, these workflows expedites the overall provisioning process via the use of the host machine (e.g., encrypting firmware on the host is quicker than on the device).
 
+.. only:: TARGET_SUPPORT_QEMU
+
+   .. important::
+
+      It is possible to try out the security features for {IDF_TARGET_NAME} target SoC under :doc:`../api-guides/tools/qemu` virtually. Once the security workflow is established, you can then proceed to the real hardware.
 
 Goals
 -----

docs/en/security/security.rst

@@ -13,6 +13,12 @@ This guide provides an overview of the overall security features available in va
 
     In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
 
+.. only:: TARGET_SUPPORT_QEMU
+
+   .. important::
+
+      It is possible to try out the security features for {IDF_TARGET_NAME} target SoC under :doc:`../api-guides/tools/qemu` virtually. Once the security workflow is established, you can then proceed to the real hardware.
+
 Goals
 -----
 

docs/zh_CN/api-guides/bootloader.rst

@@ -6,7 +6,7 @@
 ESP-IDF 软件引导加载程序 (Bootloader) 主要执行以下任务：
 
 1. 内部模块的最小化初始配置；
-2. 如果配置了 :doc:`/security/flash-encryption` 和/或 :doc:`Secure </security/secure-boot-v2>`，则对其进行初始化。
+2. 如果配置了 :doc:`/security/flash-encryption` 和/或 :doc:`Secure Boot </security/secure-boot-v2>`，则对其进行初始化。
 3. 根据分区表和 ota_data（如果存在）选择需要引导的应用程序 (app) 分区；
 4. 将此应用程序镜像加载到 RAM（IRAM 和 DRAM）中，最后把控制权转交给此应用程序。
 

docs/zh_CN/api-guides/tools/index.rst

@@ -12,4 +12,4 @@
    idf-clang-tidy
    idf-tools
    idf-size
-   :esp32 or esp32c3: qemu
+   :TARGET_SUPPORT_QEMU: qemu

docs/zh_CN/api-guides/tools/qemu.rst

@@ -1,6 +1,8 @@
 QEMU 模拟器
 ===========
 
+{IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"}
+
 :link_to_translation:`en:[English]`
 
 乐鑫维护了一个 QEMU 模拟器的 `分支 <https://github.com/espressif/qemu>`_，支持 {IDF_TARGET_NAME}。这个分支实现了对 {IDF_TARGET_NAME} 的 CPU、内存和多个外设的模拟。更多有关 {IDF_TARGET_NAME} 的 QEMU 的信息，请参阅 `QEMU README 文档 <https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/README.md>`_。
@@ -119,13 +121,37 @@ QEMU 支持 eFuse 的仿真，可用来测试安全启动和 flash 加密等与
 
 使用 :doc:`idf.py<idf-py>` eFuse 相关命令来编程 eFuse。当这些命令与 ``qemu`` 命令一起运行时，eFuse 会在 QEMU 中编程，并且 ``qemu_efuse.bin`` 文件会更新。例如，
 
+.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES
+
+    .. code-block:: console
+
+        idf.py qemu efuse-burn {IDF_TARGET_CRYPT_CNT} 1
+        idf.py qemu efuse-burn-key flash_encryption my_flash_encryption_key.bin
+
+.. only:: SOC_FLASH_ENCRYPTION_XTS_AES
+
+    .. code-block:: console
+
+        idf.py qemu efuse-burn {IDF_TARGET_CRYPT_CNT} 1
+        idf.py qemu efuse-burn-key BLOCK my_flash_encryption_key.bin KEYPURPOSE
+
+    有关 ``BLOCK`` 和 ``KEYPURPOSE`` 的详细信息，请参阅 :doc:`../../security/flash-encryption` 指南。
+
+如需导出 eFuse 概要，使用以下命令：
+
 .. code-block:: console
 
-    idf.py qemu efuse-burn FLASH_CRYPT_CNT 1
+    idf.py qemu efuse-summary
 
 默认情况下，eFuse 的值从编译文件夹里的 ``qemu_efuse.bin`` 文件中读取和写入。也可以使用 ``--efuse-file`` 选项指定不同的文件。例如，
 
 .. code-block:: console
 
-    idf.py qemu --efuse-file my_efuse.bin efuse-burn FLASH_CRYPT_CNT 1
+    idf.py qemu --efuse-file my_efuse.bin efuse-burn {IDF_TARGET_CRYPT_CNT} 1
     idf.py qemu --efuse-file my_efuse.bin monitor
+
+模拟安全启动
+~~~~~~~~~~~~~
+
+QEMU 支持模拟安全启动 v2 机制。请保持 :ref:`CONFIG_SECURE_BOOT_FLASH_BOOTLOADER_DEFAULT` 处于启用状态，将签名的引导加载程序镜像嵌入到 QEMU 的镜像文件中。
+

docs/zh_CN/security/security-features-enablement-workflows.rst

@@ -18,6 +18,11 @@
 
 这份指南介绍了一系列工作流程，从而在外部主机的协助下启用设备的安全功能。这些工作流程分为多个阶段，每个阶段都会在主机上生成签名/加密密钥，从而在发生电力或其他故障时，提高恢复几率。此外，在主机的协助下，这些流程将加快整体配置过程（例如，在主机上加密固件要比在设备上加密更快）。
 
+.. only:: TARGET_SUPPORT_QEMU
+
+   .. important::
+
+      可以在 :doc:`../api-guides/tools/qemu` 中虚拟测试 {IDF_TARGET_NAME} 目标芯片的安全功能。安全工作流程建立后，便可在真实硬件上继续操作。
 
 目标
 ----

docs/zh_CN/security/security.rst

@@ -13,6 +13,12 @@
 
     在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure.py <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。
 
+.. only:: TARGET_SUPPORT_QEMU
+
+   .. important::
+
+      可以在 :doc:`../api-guides/tools/qemu` 中虚拟测试 {IDF_TARGET_NAME} 目标芯片的安全功能。安全工作流程建立后，便可在真实硬件上继续操作。
+
 目标
 ----