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

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

@@ -150,6 +150,21 @@ 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
 ~~~~~~~~~~~~~~~~~~~~~
 

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': '',
                     }
                 ]
             }