From a58a07ecfe294a015f79145941e3cb89e39963ff Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Tue, 8 Oct 2024 19:50:09 +0530 Subject: [PATCH 1/2] feat(tools): Added option to specify flash image in "idf.py qemu" --- docs/en/api-guides/tools/qemu.rst | 15 +++++++++++++ tools/idf_py_actions/qemu_ext.py | 37 +++++++++++++++++++++++++------ 2 files changed, 45 insertions(+), 7 deletions(-) diff --git a/docs/en/api-guides/tools/qemu.rst b/docs/en/api-guides/tools/qemu.rst index 3160bab91b..43c1be5fb1 100644 --- a/docs/en/api-guides/tools/qemu.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~ diff --git a/tools/idf_py_actions/qemu_ext.py b/tools/idf_py_actions/qemu_ext.py index 685e9c8363..ad46a07dde 100644 --- a/tools/idf_py_actions/qemu_ext.py +++ b/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': '', } ] } From 53b57e21fbe06fad4559395ab712387667a4d861 Mon Sep 17 00:00:00 2001 From: renpeiying Date: Mon, 21 Oct 2024 14:59:16 +0800 Subject: [PATCH 2/2] docs: Update CN translation for qemu.rst --- docs/en/api-guides/tools/qemu.rst | 2 +- docs/zh_CN/api-guides/tools/qemu.rst | 17 ++++++++++++++++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/en/api-guides/tools/qemu.rst b/docs/en/api-guides/tools/qemu.rst index 43c1be5fb1..f88766a4a3 100644 --- a/docs/en/api-guides/tools/qemu.rst +++ b/docs/en/api-guides/tools/qemu.rst @@ -165,8 +165,8 @@ The provided flash image must meet the following requirements for proper emulati - 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. - diff --git a/docs/zh_CN/api-guides/tools/qemu.rst b/docs/zh_CN/api-guides/tools/qemu.rst index 87ba8729a2..3d4465f700 100644 --- a/docs/zh_CN/api-guides/tools/qemu.rst +++ b/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 的镜像文件中。 -