Skip to content

Home

Jump to bottom
Ivan Grokhotkov edited this page Feb 20, 2021 · 17 revisions

About this repository

This repository contains a fork of QEMU with patches for Espressif chips support. We hope that these patches will eventually be mature enough to become part of upstream QEMU project.

At the moment, Espressif does not provide support for QEMU. We appreciate issue reports, but keep in mind that our response may be delayed. We will likely not be able to help with issues which require extensive troubleshooting or don't have a straightforward way to reproduce them. We will also likely not be able to help with particular use cases which aren't supported yet (e.g. due to missing emulation of some peripherals).

The main branch of this repository is esp-develop. This branch will often be rebased on top of the upstream master branch, and force-pushed. If you wish to submit a non-trivial PR, please open an issue first so that we can avoid making conflicting changes.

Disclaimer

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

Usage

The rest of this page provides some ESP-specific instructions for running QEMU. Refer to the official documentation for general QEMU usage questions: https://www.qemu.org/documentation/.

Prerequisites

Check QEMU documentation regarding build prerequisites.

In addition, make sure that libgcrypt is installed (libgcrypt-devel on Ubuntu, libgcrypt on Arch, libgcrypt on macOS Homebrew).

Configure

./configure --target-list=xtensa-softmmu \
    --enable-gcrypt \
    --enable-debug --enable-sanitizers \
    --disable-strip --disable-user \
    --disable-capstone --disable-vnc \
    --disable-sdl --disable-gtk

(feel free to add more --disable options, to reduce the first compilation time)

Build

ninja -C build

A program build/qemu-system-xtensa should be built.

Build test app

Build an ESP-IDF application, setting CONFIG_ESPTOOLPY_FLASHMODE_DOUT=y in sdkconfig. The default mode, DIO, does not fully work yet (although it may work if you aren't using spi_flash operations).

Create a flash image, combining the bootloader, partition table, and the application. One option is to use this script (make-flash-img.sh):

#!/usr/bin/env bash
set -e
arg_projname=$1
arg_flashimg=$2

if [ -z "$1" -o -z "$2" ]; then
    echo "Usage: make-flash-img.sh app_name flash_img_file"
    exit 1
fi

dd if=/dev/zero bs=1024 count=4096 of=${arg_flashimg}
dd if=build/bootloader/bootloader.bin bs=1 seek=$((0x1000)) of=${arg_flashimg} conv=notrunc
dd if=build/partition_table/partition-table.bin bs=1 seek=$((0x8000)) of=${arg_flashimg} conv=notrunc
dd if=build/${arg_projname}.bin bs=1 seek=$((0x10000)) of=${arg_flashimg} conv=notrunc

Note: it is also possible to use esptool.py to "flash" the application into Qemu, but Qemu needs to be started with correct strapping mode. See below.

Run QEMU

Start QEMU without attaching GDB:

build/qemu-system-xtensa -nographic \
    -machine esp32 \
    -drive file=flash_image.bin,if=mtd,format=raw

Start QEMU with GDB server, waiting for connection:

build/qemu-system-xtensa -nographic -s -S \
    -machine esp32 \
    -drive file=flash_image.bin,if=mtd,format=raw

To connect using GDB, use the following:

xtensa-esp32-elf-gdb build/app-name.elf \
    -ex "target remote :1234" \
    -ex "monitor system_reset" \
    -ex "tb app_main" -ex "c"

(or put the same commands into a gdbinit script)

Hardware crypto support

Starting from IDF 4.1, the following hardware crypto features are enabled by default: AES, SHA, RSA.

At the time of writing, only the SHA and RSA engines are implemented in QEMU.

You can disable the missing hardware crypto features in menuconfig (under Component config, mbedTLS).

Enabling Ethernet support

This needs an IDF branch with Opencores Ethernet MAC driver support.

  • When running protocols examples, enable CONFIG_EXAMPLE_CONNECT_ETHERNET and CONFIG_EXAMPLE_USE_OPENETH.
  • When running a custom app, enable CONFIG_ETH_USE_OPENETH and initialize the Ethernet driver as it is done in examples/common_components/protocol_examples_common/connect.c (look for esp_eth_mac_new_openeth).

When starting QEMU, use open_eth network device.

User mode networking

For example, to start networking in user mode (TCP/UDP only, emulated device is behind NAT), add the following option to the QEMU command line:

-nic user,model=open_eth

Some ESP project (specifically running TCP listeners) might need port forwarding to be set up:

-nic user,model=open_eth,id=lo0,hostfwd=tcp:127.0.0.1:PORT_HOST-:PORT_GUEST

E.g. asio-echo-server sets up a server on 2222 by default, so hostfwd=tcp:127.0.0.1:2222-:2222 enables to nc localhost 2222 from host machine.

Bridge/tap networking

TODO: add instructions for running QEMU network in tap mode.

Specifying bootstrapping mode

Add extra argument to the command line to specify the desired strapping mode:

-global driver=esp32.gpio,property=strap_mode,value=0x0f

This sets the value of GPIO_STRAP register.

  • Use 0x12 for flash boot mode (default)
  • Use 0x0f for UART-only download mode (since the SDIO part is not implemented)

Specifying eFuse storage

Add extra arguments to the command line:

-drive file=qemu_efuse.bin,if=none,format=raw,id=efuse
-global driver=nvram.esp32.efuse,property=drive,value=efuse

The first argument creates creates a block device backed by qemu_efuse.bin file, with identifier efuse. The second line configures nvram.esp32.efuse device to use this block device for storage.

The file must be created prior to starting qemu:

dd if=/dev/zero bs=1 count=124 of=/tmp/qemu_efuse.bin

124 bytes is the total size of ESP32 eFuse blocks.

Disabling the watchdogs

By default, Timer Group watchdog timers are emulated, and TG0 WDT is enabled at reset. It is sometimes useful to disable these watchdog timers. This can be done by adding the following to the command line:

-global driver=timer.esp32.timg,property=wdt_disable,value=true

This disables emulation of TG watchdog timers. Even if the application configures them, they will not fire.

RTC watchdog timer is not emulated yet, so doesn't need to be disabled.

Using esptool.py and espefuse.py to interact with Qemu

  1. Start Qemu:

    build/qemu-system-xtensa -nographic \
    -machine esp32 \
    -drive file=flash_image.bin,if=mtd,format=raw \
    -global driver=esp32.gpio,property=strap_mode,value=0x0f \
    -drive file=qemu_efuse.bin,if=none,format=raw,id=efuse \
    -global driver=nvram.esp32.efuse,property=drive,value=efuse \
    -serial tcp::5555,server,nowait

    The final line redirects the emulated UART to TCP port 5555 (Qemu acts as a server).

    Type q and press Enter at any time to quit.

  2. Run esptool.py:

    esptool.py -p socket://localhost:5555 flash_id

    Flashing with idf.py also works:

    export ESPPORT=socket://localhost:5555
idf.py flash

  3. Or, run espefuse.py:

    espefuse.py --port socket://localhost:5555 --do-not-confirm burn_custom_mac 00:11:22:33:44:55

Note: esptool can not reset the emulated chip using the RTS signal, because the state of RTS is not transmitted over TCP to Qemu. To reset the emulated chip, run system_reset command in Qemu console (started at step 1).

Specifying ROM ELF file

If -kernel and -bios arguments are not given, ESP32 (rev. 3) ROM code will be loaded. This ROM code binary is included in the repository. To specify the ROM code ELF file to load, pass the filename with a -bios <filename> argument.

Clone this wiki locally