Merge branch 'feature/idf_qemu_ext' into 'master'

feat(tools): add 'idf.py qemu' extension

Closes IDFGH-817

See merge request espressif/esp-idf!26034

docs/conf_common.py

@@ -147,6 +147,8 @@ ANA_CMPR_DOCS = ['api-reference/peripherals/ana_cmpr.rst']
 
 SPI_SLAVE_HD_DOCS = ['api-reference/peripherals/spi_slave_hd.rst']
 
+QEMU_DOCS = ['api-guides/tools/qemu.rst']
+
 ESP32_DOCS = ['api-reference/system/himem.rst',
               'api-guides/romconsole.rst',
               'api-reference/system/ipc.rst',
@@ -155,7 +157,7 @@ ESP32_DOCS = ['api-reference/system/himem.rst',
               'api-reference/peripherals/dac.rst',
               'api-reference/peripherals/sd_pullup_requirements.rst',
               'hw-reference/esp32/**',
-              'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS
+              'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS + QEMU_DOCS
 
 ESP32S2_DOCS = ['hw-reference/esp32s2/**',
                 'api-guides/usb-console.rst',
@@ -173,7 +175,7 @@ ESP32S3_DOCS = ['hw-reference/esp32s3/**',
 
 # No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below.
 ESP32C3_DOCS = ['hw-reference/esp32c3/**',
-                'api-guides/RF_calibration.rst']
+                'api-guides/RF_calibration.rst'] + QEMU_DOCS
 
 ESP32C2_DOCS = ['api-guides/RF_calibration.rst']
 

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

@@ -11,3 +11,4 @@ Tools
    idf-component-manager
    idf-clang-tidy
    idf-tools
+   :esp32 or esp32c3: qemu

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

@@ -0,0 +1,64 @@
+QEMU Emulator
+=============
+
+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 `documentation <https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/README.md>`_.
+
+:doc:`idf.py<idf-py>` allows for running and debugging applications in QEMU. This is a convenient way to test applications without having to flash them to real hardware.
+
+Prerequisites
+-------------
+
+To use QEMU with ``idf.py`` you first need to install the above-mentioned fork of QEMU. ESP-IDF provides pre-built binaries for x86_64 Linux. If you are using this platform, you can install the pre-built binaries with the following command:
+
+.. code-block:: console
+
+    python $IDF_PATH/tools/idf_tools.py install qemu-xtensa qemu-riscv
+
+After installing QEMU, make sure it is added to PATH by running ``. ./export.sh`` in the IDF directory.
+
+If you are using a different platform, you need to build QEMU from source. Refer to official QEMU documentation for instructions.
+
+Usage
+-----
+
+To run an IDF application in QEMU, use the following command:
+
+.. code-block:: console
+
+    idf.py qemu monitor
+
+This command builds the application, starts QEMU and opens :doc:`IDF monitor <idf-monitor>`, connecting it to the emulated UART port. You can see the console output of the application and interact with it. IDF Monitor also provides automatic decoding of panic backtraces and UART core dumps.
+
+To debug an application in QEMU, use the following command:
+
+.. code-block:: console
+
+    idf.py qemu gdb
+
+This command builds the application, starts QEMU with the GDB server enabled, and opens an interactive GDB session. You can use GDB to debug the application as if it was running on real hardware.
+
+To see console output while debugging in QEMU, use two terminals.
+
+* In the first terminal, run:
+
+  .. code-block:: console
+
+    idf.py qemu --gdb monitor
+
+  This command starts QEMU and IDF Monitor, and tells QEMU to wait for a GDB connection.
+
+* In the second terminal, run:
+
+  .. code-block:: console
+
+    idf.py gdb
+
+  This command starts an interactive GDB sessions and connects it to QEMU. You can now debug the application, and the console output will be visible in the first terminal.
+
+It is also possible to run QEMU without the IDF Monitor:
+
+.. code-block:: console
+
+    idf.py qemu
+
+In this case, the IDF Monitor is not used, and you can interact with QEMU process directly. To switch between the emulated UART console and QEMU console ("QEMU monitor"), use Ctrl-A shortcut. For example, to exit QEMU, press Ctrl-A, then type ``q`` and press Enter. You can use the QEMU console to enter commands, such as for inspecting registers and memory.

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

@@ -11,3 +11,4 @@
    idf-component-manager
    idf-clang-tidy
    idf-tools
+   :esp32 or esp32c3: qemu

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

@@ -0,0 +1 @@
+.. include:: ../../../en/api-guides/tools/qemu.rst