Merge branch 'feature/add_option_to_provide_flash_file_for_qemu' into 'master'

feat(tools): Added option to specify flash image in "idf.py qemu"

See merge request espressif/esp-idf!34031

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

@@ -150,8 +150,23 @@ By default, the values of eFuses are read from and written to the ``qemu_efuse.b
     idf.py qemu --efuse-file my_efuse.bin efuse-burn {IDF_TARGET_CRYPT_CNT} 1
     idf.py qemu --efuse-file my_efuse.bin monitor
 
+Specifying Flash Image
+~~~~~~~~~~~~~~~~~~~~~~
+
+By default, QEMU uses the ``qemu_flash.bin`` file in the build directory as the flash image. This file is generated based on the information available about the project from the ``flash_args`` file present in the build directory. If you want to use a different flash image file, you can specify it using the ``--flash-file`` option. For example,
+
+.. code-block:: console
+
+    idf.py qemu --flash-file my_flash.bin monitor
+
+
+The provided flash image must meet the following requirements for proper emulation:
+
+- The flash file size matches the value specified by :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
+- The flash file includes all required binaries, such as the bootloader, partition table, and application firmware, placed at their respective memory offsets.
+
+
 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/zh_CN/api-guides/tools/qemu.rst

@@ -150,8 +150,23 @@ QEMU 支持 eFuse 的仿真，可用来测试安全启动和 flash 加密等与
     idf.py qemu --efuse-file my_efuse.bin efuse-burn {IDF_TARGET_CRYPT_CNT} 1
     idf.py qemu --efuse-file my_efuse.bin monitor
 
+指定 flash 映像
+~~~~~~~~~~~~~~~
+
+默认情况下，QEMU 使用构建目录中的 ``qemu_flash.bin`` 文件作为 flash 映像。该文件是根据构建目录中 ``flash_args`` 文件提供的项目信息生成的。如果想使用其他 flash 映像，可通过 ``--flash-file`` 选项进行指定。例如:
+
+.. code-block:: console
+
+    idf.py qemu --flash-file my_flash.bin monitor
+
+
+所提供的 flash 映像必须满足以下要求，以确保正确模拟：
+
+- flash 文件大小与项目配置中 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` 的指定值相同。
+- flash 文件包括所有必需的二进制文件，如引导加载程序、分区表和应用程序固件，这些文件位于各自的内存偏移量处。
+
+
 模拟安全启动
 ~~~~~~~~~~~~~
 
 QEMU 支持模拟安全启动 v2 机制。请保持 :ref:`CONFIG_SECURE_BOOT_FLASH_BOOTLOADER_DEFAULT` 处于启用状态，将签名的引导加载程序镜像嵌入到 QEMU 的镜像文件中。
-

tools/idf_py_actions/qemu_ext.py

@@ -213,7 +213,7 @@ def action_extensions(base_actions: Dict, project_path: str) -> Dict:
             project_desc = json.load(f)
         return project_desc
 
-    def qemu(action: str, ctx: Context, args: PropertyDict, qemu_extra_args: str, gdb: bool, graphics: bool, efuse_file: str) -> None:
+    def qemu(action: str, ctx: Context, args: PropertyDict, qemu_extra_args: str, gdb: bool, graphics: bool, efuse_file: str, flash_file: str) -> None:
         project_desc = _get_project_desc(args, ctx)
 
         # Determine the target and check if we have the necessary QEMU binary
@@ -230,11 +230,21 @@ def action_extensions(base_actions: Dict, project_path: str) -> Dict:
 
         # Generate flash image and efuse image
         flash_size = get_sdkconfig_value(project_desc['config_file'], 'CONFIG_ESPTOOLPY_FLASHSIZE')
-        bin_path = os.path.join(args.build_dir, 'qemu_flash.bin')
-        yellow_print(f'Generating flash image: {bin_path}')
-        subprocess.check_call([
-            sys.executable, '-m', 'esptool', f'--chip={target}', 'merge_bin', f'--output={bin_path}',
-            f'--fill-flash-size={flash_size}', '@flash_args'], cwd=args.build_dir)
+
+        if flash_file:
+            bin_path = flash_file
+            try:
+                open(bin_path, 'rb').close()
+                yellow_print(f'Using provided flash image: {bin_path}')
+            except FileNotFoundError:
+                red_print(f'The provided flash image file \"{bin_path}\" could not be found')
+                raise SystemExit(1)
+        else:
+            bin_path = os.path.join(args.build_dir, 'qemu_flash.bin')
+            yellow_print(f'Generating flash image: {bin_path}')
+            subprocess.check_call([
+                sys.executable, '-m', 'esptool', f'--chip={target}', 'merge_bin', f'--output={bin_path}',
+                f'--fill-flash-size={flash_size}', '@flash_args'], cwd=args.build_dir)
 
         if efuse_file:
             efuse_bin_path = efuse_file
@@ -251,12 +261,18 @@ def action_extensions(base_actions: Dict, project_path: str) -> Dict:
         # Prepare QEMU launch arguments
         qemu_args = [qemu_target_info.qemu_prog]
         qemu_args += qemu_target_info.qemu_args.split(' ')
+        # When boot mode is specified, the flash image is not required.
+        if not options.boot_mode:
+            qemu_args += [
+                '-drive', f'file={bin_path},if=mtd,format=raw',
+            ]
+
         qemu_args += [
-            '-drive', f'file={bin_path},if=mtd,format=raw',
             '-drive', f'file={efuse_bin_path},if=none,format=raw,id=efuse',
             '-global', f'driver={qemu_target_info.efuse_device},property=drive,value=efuse',
             '-global', f'driver=timer.{target}.timg,property=wdt_disable,value=true',
         ]
+
         if '-nic' not in qemu_extra_args:
             qemu_args += ['-nic', 'user,model=open_eth']
 
@@ -339,6 +355,13 @@ def action_extensions(base_actions: Dict, project_path: str) -> Dict:
                                  'in build directory is used.'),
                         'is_flag': False,
                         'default': '',
+                    },
+                    {
+                        'names': ['--flash-file'],
+                        'help': ('File used as the qemu flash image. If not specified, qemu_flash.bin file '
+                                 'in build directory is used.'),
+                        'is_flag': False,
+                        'default': '',
                     }
                 ]
             }