Documentation for QEMU is confusing, inaccurate and insufficient.

[Joebeazelman]

The documentation for QEMU RGB Panel is confusing and insufficient. First, under the Build and Run section, the user is instructed to build the project, but it doesn't specify type of image it will build. Will it build for the actual device or QEMU? There are no instructions for running the image. Instead, you're linked to a very general QEMU readme, which begins by instructing the user on how to build QEMU. It doesn't specify a link to the git repository containing the source to build. It becomes a detective game to discover it. After an hour or so of dead ends trying to build it, I found a prebuilt binary which was never mentioned in the documentation, resulting wasted effort.

Second, halfway down the QEMU docs page there are instructions on how to run the image. The example command-lines given are very generalized and unclear whether they will work for the built image. I couldn't get the image to execute due to an invalid binary format. It would be enormously helpful if the examples were specific instead of generalized.

Third, after many hours spent trying to get the example to run, I discovered QEMU was already installed and could be run by running idf.py qemu with the correct parameters. Unfortunately, the QEMU RGB Panel example disables the QEMU display by default.

This is why many users don't bother to read the documentation. They are often poorly written, leading to confusion, and frustration. Many developers often don't value writing decent documentation.

[valkuc]

@igrr Hello. I had some time to play with QEMU emulating ESP32-C3 chip and firmware built with SDK v5.3. What I have found:

1. The idf.py qemu command does not pass -icount 3 parameter to QEMU. Is this a bug or this param is not required anymore?
2. OTA updates. You have to stop and start QEMU after each OTA update, otherwise, after software restart (via esp_restart()), the newly flashed firmware will not boot failing with different panic causes. Some of them:

assert failed: esp_mmu_map_init esp_mmu_map.c:211 (hw_mem_regions[i].region_size % CONFIG_MMU_PAGE_SIZE == 0)

assert failed: s_prepare_reserved_regions memory_layout_utils.c:102 (reserved[i].start <= reserved[i].end)

Probably this is somehow related to MTD device caching in QEMU, i'm not sure, but i spent several hours to understand if the problem is in my firmware or not. So I think this point is worth mentioning in the documentation.

3. Firmware will not work in QEMU if flash configured to work in QIO mode (CONFIG_ESPTOOLPY_FLASHMODE_QIO=y). It will produce

I (19339) qio_mode: Enabling default flash chip QIO
E (19341) qio_mode: Failed to set QIE bit, not enabling QIO mode

and later will panic with

I (9512) spi_flash: detected chip: gd
I (9513) spi_flash: flash io: qio

assert failed: __esp_system_init_fn_init_flash startup_funcs.c:95 (flash_ret == ESP_OK)

I guess this is worth mentioning in the documentation too.

[igrr]

@Joebeazelman Thanks for reporting the issues with the documentation you encountered. For IDF users, we have added QEMU documentation here: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/qemu.html. It contains instructions on running IDF apps in QEMU, as well as enabling graphics support.

We'll still keep the generic instructions in this repo since QEMU can also be used for applications not built with ESP-IDF (e.g. Zephyr or NuttX applications.)

@valkuc To answer your questions:

1. I think this parameter is not required. I don't see any harm using it, though. I guess we can update the docs to not include this parameter and direct users to the official QEMU documentation.
2. Sounds like a bug in our ESP32-C3 emulation in QEMU, would you mind opening an issue about it in https://github.com/espressif/qemu/issues/, with some instructions on how to reproduce this?
3. This seems like an existing issue, nvs_flash_init returns ESP_ERR_NVS_NOT_INITIALIZED (QEMU-171) qemu#88. We'll take a look if we can prioritize this.

[Joebeazelman]

I just discovered the ESP32-s3 isn't supported QEMU. Can I retarget my ESP32-s3 project to another compatible SoC supported by QEMU without making extensive modifications? I understand there are linkage and pin differences.

[igrr]

@Joebeazelman Yes, in addition to building your project for the ESP32-S3 target you can also build it for ESP32. IDF multi_config example can be one way how to conveniently build the project for two chip targets side by side.
Then, run the project on the ESP32 when testing in QEMU.

Typically, if you aren't using anything very low level and if you aren't using peripherals which don't exist on another chip, the project should be portable between chip targets without extensive modifications.