diff --git a/README.md b/README.md index a62db034a9f6..0ccb057b9825 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,19 @@ # QEMU OpenTitan README -[![.github/workflows/build_test.yaml](https://github.com/lowRISC/qemu/actions/workflows/build_test.yaml/badge.svg?branch=ot-darjeeling-8.0.2)](https://github.com/lowRISC/qemu/actions/workflows/build_test.yaml) +[![.github/workflows/build_test.yaml](https://github.com/lowRISC/qemu/actions/workflows/build_test.yaml/badge.svg?branch=ot-darjeeling-8.2.0)](https://github.com/lowRISC/qemu/actions/workflows/build_test.yaml) QEMU is a generic and open source machine & userspace emulator and virtualizer. QEMU is capable of emulating a complete machine in software without any need for hardware virtualization support. By using dynamic translation, it achieves very good performance. -This branch contains a fork of QEMU 8.0.2 dedicated to support lowRISC Ibex platforms: - * OpenTitan Darjeeling with FPGA "Bergen Board" CW310 memory map. - -See [ot_ref.log](hw/opentitan/ot_ref.log) for OpenTitan reference. +This branch contains a fork of QEMU 8.2.0 dedicated to support lowRISC Ibex platforms: + * [OpenTitan](https://opentitan.org) [Darjeeling](docs/opentitan/darjeeling.md) with FPGA "Bergen Board" + CW310 memory map. + * [OpenTitan](https://opentitan.org) [EarlGrey](docs/opentitan/earlgrey.md) with FPGA "Bergen Board" + CW310 memory map, no longer under active QEMU development. + * [lowRISC](https://github.com/lowRISC/ibex-demo-system) [IbexDemo](ibexdemo.md) with Digilent Arty7 + board memory map. See [installation instructions](docs/opentitan/index.md) diff --git a/docs/opentitan/darjeeling.md b/docs/opentitan/darjeeling.md new file mode 100644 index 000000000000..4efc81aaf493 --- /dev/null +++ b/docs/opentitan/darjeeling.md @@ -0,0 +1,257 @@ +# Darjeeling CW310 + +## Supported version + +Please check out `hw/opentitan/ot_ref.log` + +## Supported features + +* ePMP +* Zbr ISA extension (crc32 instructions) + +## Supported devices + +### Near feature-complete devices + +* AES + * missing side-loading +* AON Timer +* CSRNG +* EDN +* HMAC +* JTAG (compatible with OpenOCD/Spike "remote bitbang" protocol) +* Mailbox + * [JTAG mailbox](jtagmbx.md) can be accessed through JTAG using a DM-TL bridge +* OTBN + * missing side-loading +* OTP controller + * read and write features are supported, Present scrambling is supported w/ digest checks, + ECC bits are ignored +* SPI data flash (from QEMU upstream w/ fixes) +* SPI Host controller + * HW bus config is ignored (SPI mode, speed, ...) +* Timer +* UART + * missing RX timeout, break support + * bitrate is not paced vs. selected baurate + +### Partially implemented devices + +Devices in this group implement subset(s) of the real HW. + +* DMA + * Only memory-to-memory transfers (inc. hashing) are supported, Handshake modes are not supported +* Flash controller + * read-only features only +* Entropy Src + * test/health features are not supported +* [GPIO](gpio.md) + * A CharDev backend can be used to get GPIO outputs and update GPIO inputs, +* KMAC + * Side loading is not supported +* Lifecycle controller + * Escalation is not supported +* Power Manager + * Fast FSM is partially supported, Slow FSM is bypassed + * Interactions with other devices (such as the Reset Manager) are limited +* [ROM controller](rom_ctrl.md) +* SoC Proxy only supports IRQ routing/gating + +### Sparsely implemented devices + +In this group, device CSRs are supported (w/ partial or full access control & masking) but only some +features are implemented. + +* AST + * entropy source only (from host source) +* Clock Manager + * Clock hints only +* Ibex wrapper + * random source (connected to CSR), FPGA version, virtual remapper, fetch enable can be controlled + from Power Manager +* Reset Manager + * HW and SW reset requests are supported +* SRAM controller + * Supported as dummy SRAM memories + +### Dummy devices + +Devices in this group are mostly implemented with a RAM backend or real CSRs but do not implement +any useful feature (only allow guest test code to execute as expected). + +* Alert controller +* Key manager +* Pinmux +* Sensor + +### Additional devices + +* [DevProxy](devproxy.md) is a CharDev-enabled component that can be remotely controlled to enable + communication with the system-side buses of the mailboxes and DMA devices. A Python library is + available as `scripts/opentitan/devproxy.py` and provide an API to remote drive the devproxy + communication interface. + +## Running the virtual machine + +### Arbitrary application + +````sh +qemu-system-riscv32 -M ot-darjeeling,no_epmp_cfg=true -display none -serial mon:stdio \ + -global ot-ibex_wrapper-dj.lc-ignore=on -kernel hello.elf +```` +See the section "Useful execution options" for documentation about the `no_epmp_cfg` and +`ot-ibex_wrapper-dj.lc-ignore=on` option. + +### Boot sequence ROM, ROM_EXT, BLO + +````sh +qemu-system-riscv32 -M ot-darjeeling -display none -serial mon:stdio \ + -object ot-rom-img,id=rom,file=rom_with_fake_keys_fpga_cw310.elf,digest=fake \ + -drive if=pflash,file=otp-rma.raw,format=raw \ + -drive if=mtd,bus=1,file=flash.raw,format=raw +```` + +where `otp-rma.raw` contains the RMA OTP image and `flash.raw` contains the signed binary file of the +ROM_EXT and the BL0. See [`otptool.py`](otptool.md) and [`flashgen.py`](flashgen.md) tools to +generate the `.raw` image files. + +See [`rom_ctrl.md`](rom_ctrl.md) for information on ROM option. + +## Tools + +See [`tools.md`](tools.md) + +## Useful execution options + +### vCPU + +* `-icount 6` reduces the execution speed of the vCPU (Ibex core) to 1GHz >> 6, _i.e._ ~15MHz, + which should roughly match the expected speed of the Ibex core running on the CW310 FPGA, which + is set to 10 MHz. This option is very useful/mandatory to run many OpenTitan tests that rely on + time or CPU cycle to validate features. Using `-icount` option slows down execution speed though, + so it is not recommended to use it when the main goal is to develop SW to run on the virtual + machine. + +* `no_epmp_cfg=true` can be appended to the machine option switch, _i.e._ + `-M ot-darjeeeling,no_epmp_cfg=true` to disable the initial ePMP configuration, which can be very + useful to execute arbitrary code on the Ibex core without requiring an OT ROM image to boot up. + +* `-global ot-ibex_wrapper-dj.lc-ignore=on` should be used whenever no OTP image is provided, or if + the current LifeCycle state stored in the OTP image does not allow the Ibex core to fetch data. + This switch forces the Ibex core to execute whatever the LifeCycle broadcasted signal, which + departs from the HW behavior but maybe helpful to run the machine without a full OTP set up. The + alternative to allow the Ibex core to execute guest code is to provide a valid OTP image with one + of the expected LifeCycle state, such as TestUnlock*, Dev, Prod or RMA. + +* `-cpu lowrisc-ibex,x-zbr=false` can be used to force disable the Zbr experimental-and-deprecated + RISC-V bitmap extension for CRC32 extension. + +### AES + +* `-global ot-aes.fast-mode=false` can be used to better emulate AES HW IP, as some OT tests expect + the Ibex core to execute while the HW is performing AES rounds. Without this option, the virtual + HW may only give back execution to the vCPU once the AES operation is complete, which make those + OT tests to fail. Disabling fast mode better emulates the HW to the expense of higher AES latency + and throughput. + +### Display + + * `-display none` can be used to prevent QEMU to open a semi-graphical windows as the default + console, and use the current shell instead. + +### Flash + +* `-drive if=mtd,bus=1,file=,format=raw` should be used to specify a path to a QEMU RAW + image file used as the OpenTitan internal flash controller image. This _RAW_ file should have + been generated with the [`flashgen.py`](flashgen.md) tool. + + Note: for now, bus 1 is assigned to the internal controller with the embedded flash storage. See + also SPI Host section. + +### OTBN + +* `-global ot-otbn.logfile=` dumps executed instructions on OTBN core into the specified + filename. Beware that is even further slows down execution speed, which could likely result into + guest application on the Ibex core to time out. + +### OTP + +* `-drive if=pflash,file=otp.raw,format=raw` should be used to specify a path to a QEMU RAW image + file used as the OpenTitan OTP image. This _RAW_ file should have been generated with the + [`otptool.py`](otptool.md) tool. + +### SPI Host + +* `-drive if=mtd,bus=0,file=,format=raw` should be used to specify a path to a QEMU RAW + image file used as the ISSP IS25WP128 SPI data flash backend file. This _RAW_ file should have + been created with the qemu-img tool. There is no dedicated tool to populate this image file for + now. + + ````sh + qemu-img create -f raw spi.raw 16M + ```` + + For now, bus 0 is assigned to the SPI Host controller with an external flash storage. See also + Flash controller section. + +### UART + +* `-serial mon:stdio`, used as the first `-serial` option, redirects the virtual UART0 to the + current console/shell. + +* `-chardev socket,id=serial1,host=localhost,port=8001,server=on,wait=off` and + `-serial chardev:serial1` can be used to redirect UART1 (in this example) to a TCP socket. These + options are not specific to OpenTitan emulation, but are useful to communicate over a UART. + Note that QEMU offers many `chardev` backends, please check QEMU documentation for details. + +## Useful debugging options + +### Device log traces + +Most OpenTitan virtual devices can emit log traces. To select which traces should be logged, a plain +text file can be used along with QEMU `-trace` option. + +To populate this file, the easiest way is to dump all available traces and filter them with a +pattern, for example to get all OpenTitan trace messages: + +````sh +qemu-system-riscv32 -trace help | grep -E '^ot_' > ot_trace.log +qemu-system-riscv32 -trace events=ot_trace.log -D qemu.log ... +```` + +* It is *highly* recommended to use the `-D` option switch when any `-trace` or `-d` (see below) is +selected, to avoid saturating the standard output stream with traces and redirect them into the +specified log file. + +### QEMU log traces + +QEMU provides another way of logging execution of the virtual machine using the `-d` option. Those +log messages are not tied to a specific device but rather to QEMU features. `-d help` can be used +to enumerate these log features, however the most useful ones are enumerated here: + + * `unimp` reports log messages for unimplemented features, _e.g._ when the vCPU attempts to + read from or write into a memory mapped device that has not been implemented. + * `guest_errors` reports log messages of invalid guest software requests, _e.g._ attempts to + perform an invalid configuration. + * `int` reports all interruptions *and* exceptions handled by the vCPU. It may be quite verbose + but also very useful to track down an invalid memory or I/O access for example. This is the + first option to use if the virtual machine seems to stall on start up. + * `in_asm` reports the decoded vCPU instructions that are translated by the QEMU TCG, _i.e._ here + the RISC-V instructions. Note that transcoded instructions are cached and handled by blocks, + so the flow of transcoded instruction do not exactly reflect the stream of the executed guest + instruction, e.g. may only appear once in a loop. Use the next log option, `exec`, to get + more detailed but also much more verbose log traces. + * `exec` reports the vCPU execution stream. + +Those options should be combined with a comma separator, _e.g._ `-d unimp,guest_errors,int` + +`in_asm` option may be able to report the name of the guest executed function, as long as the guest +application symbols have been loaded. This is the case when the `-kernel` option is used to load +an ELF non-stripped file. Unfortunately, this feature is not available for guest applications that +are loaded from a raw binary file (`.bin`, `.signed.bin`, ...). However the +[`flashgen.py`](flashgen.md) script implements a workaround for this feature, please refer to this +script for more details. + +Finally, a Rust demangler has been added to QEMU, which enables the QEMU integrated dissambler to +emit the demangled names of the Rust symbols for Rust-written guest applications rather than their +mangled versions as stored in the ELF file. diff --git a/docs/opentitan/earlgrey.md b/docs/opentitan/earlgrey.md index 20fcb1d54de7..f0a38ba9ea45 100644 --- a/docs/opentitan/earlgrey.md +++ b/docs/opentitan/earlgrey.md @@ -2,7 +2,7 @@ ## Supported version -Please check out `hw/opentitan/ot_ref.log` +EarlGrey 2.5.2-RC0 ## Supported features @@ -16,6 +16,7 @@ Please check out `hw/opentitan/ot_ref.log` * AES * missing side-loading * AON Timer +* CSRNG * EDN * HMAC * OTBN @@ -36,12 +37,14 @@ Devices in this group implement subset(s) of the real HW. * read-only features only * OTP controller * read-only features only, ECC is ignored - * Entropy Src - * SHA3 is not implemented (entropy is forwarded/repacked from AST) * test/health features are not supported -* CSRNG * AES CTR not supported (uses xoroshiro128++ reseeded from entropy src) +* [GPIO](gpio.md) + * A CharDev backend can be used to get GPIO outputs and update GPIO inputs, +* KMAC + * Side loading is not supported +* [ROM controller](rom_ctrl.md) ### Sparsely implemented devices @@ -55,7 +58,10 @@ features are implemented. * Ibex wrapper * random source (connected to CSR), FPGA version, virtual remapper * Lifecycle controller - * forward LC state from OTP + * only forwards LC state from OTP +* Power Manager + * Fast FSM is partially supported, Slow FSM is bypassed + * Interactions with other devices (such as the Reset Manager) are limited ### Dummy devices @@ -86,34 +92,19 @@ See the section "Useful execution options" for documentation about the `no_epmp_ ````sh qemu-system-riscv32 -M ot-earlgrey -display none -serial mon:stdio \ -object ot-rom-img,id=rom,file=rom_with_fake_keys_fpga_cw310.elf,digest=fake \ - -drive if=pflash,file=otp.raw,format=raw \ + -drive if=pflash,file=otp-rma.raw,format=raw \ -drive if=mtd,bus=1,file=flash.raw,format=raw ```` -where `otp.raw` contains the RMA OTP image and `flash.raw` contains the signed binary file of the +where `otp-rma.raw` contains the RMA OTP image and `flash.raw` contains the signed binary file of the ROM_EXT and the BL0. See [`otptool.py`](otptool.md) and [`flashgen.py`](flashgen.md) tools to generate the `.raw` image files. See [`rom_ctrl.md`](rom_ctrl.md) for information on ROM option. -## Available tools - -Launching a QEMU VM with the right option switches may rapidly become complex due to the number -of options and the available features. Several helper tools are provided in the `scripts/opentitan` -directory to help with these tasks. - -* [`otptool.py`](otptool.md) can be used to generate an OTP image from a OTP VMEM file and can be - used to decode (some of the) encoded data in the OTP image. -* [`flashgen.py`](flashgen.md) can be used to generate a flash image with either a ROM_EXT and BL0 - signed files, or a single OpenTitan signed test files. -* `otboot.sh` is a wrapper script to build image files and execute a ROM/ROM_EXT/BL0 execution - session. -* `otrun.sh` is a wrapper script to build image files and execute an OpenTitan test. -* `ottests.sh` is a wrapper script to execute many OpenTitan tests and report a list of successes - and failures. -* [`checkregs.py`](checkregs.md) is an internal tool design to check the discrepancies between - OpenTitan generated register definition files and their QEMU counterparts. It is only useful to - develop the machine itself. +## Tools + +See [`tools.md`](tools.md) ## Useful execution options diff --git a/docs/opentitan/gpio.md b/docs/opentitan/gpio.md index 6af10238e3e8..1b789d5c9def 100644 --- a/docs/opentitan/gpio.md +++ b/docs/opentitan/gpio.md @@ -1,4 +1,4 @@ -# OT GPIO +# OpenTitan GPIO ## Initial configuration diff --git a/docs/opentitan/index.md b/docs/opentitan/index.md index 51b5e8798bff..c2d598945b11 100644 --- a/docs/opentitan/index.md +++ b/docs/opentitan/index.md @@ -24,6 +24,10 @@ ninja qemu-img * `--enable-gtk` should be used on Linux hosts * `--enable-cocoa` should be used on macOS hosts +* `--extra-cflags=-Wno-deprecated-declarations` and + `--extra-ldflags=-Wl,-no_warn_duplicate_libraries` may be required to build on recent relases of + macOS (QEMU issues which are not related to the OpenTitan port) + ### Useful build options * `--enable-debug` @@ -32,4 +36,5 @@ ninja qemu-img ## Supported platforms * [IbexDemo](ibexdemo.md) built for Digilent Arty7 board + * [Darjeeling](darjeeling.md) build for CW310 "Bergen" board * [EarlGrey](earlgrey.md) build for CW310 "Bergen" board diff --git a/docs/opentitan/spi_device.md b/docs/opentitan/spi_device.md index b62a157c149b..12dd09f14822 100644 --- a/docs/opentitan/spi_device.md +++ b/docs/opentitan/spi_device.md @@ -1,4 +1,4 @@ -# SPI Device support +# OpenTitan SPI Device support ## Supported modes diff --git a/docs/opentitan/tools.md b/docs/opentitan/tools.md new file mode 100644 index 000000000000..e9a3e3e6ab0a --- /dev/null +++ b/docs/opentitan/tools.md @@ -0,0 +1,52 @@ +# OpenTitan QEMU tools + +All the OpenTitan tools and associated files are stored in the `scripts/opentitan` directory. + +## Execution wrappers + +Launching a QEMU VM with the right option switches may rapidly become complex due to the number +of options and the available features. Several helper tools are provided in the `scripts/opentitan` +directory to help with these tasks. + +* [`pyot.py`](pyot.md) can be used to run unit tests and OpenTitan tests +* `otboot.sh` is a wrapper script to build image files and execute a ROM/ROM_EXT/BL0 execution + session. +* `otrun.sh` is a wrapper script to build image files and execute an OpenTitan test. +* `ottests.sh` is a wrapper script to execute many OpenTitan tests and report a list of successes + and failures. + +## Companion file management + +* [`otptool.py`](otptool.md) can be used to generate an OTP image from a OTP VMEM file and can be + used to decode (some of the) encoded data in the OTP image. +* [`flashgen.py`](flashgen.md) can be used to generate a flash image with either a ROM_EXT and BL0 + signed files, or a single OpenTitan signed test files. +* `swexit.py` is a tiny Python script to generate the simplest RISC-V executable (with no need for + a RISC-V toolchain) that is used to ensure the QEMU OpenTitan machine can start up and quit. + +## Development + +* [`checkregs.py`](checkregs.md) is an internal tool design to check the discrepancies between + OpenTitan generated register definition files and their QEMU counterparts. It is only useful to + develop the machine itself. +* `devproxy.py` is a Python module that provides an API to remote drive the [DevProxy](devproxy.md) + communication interface. +* [`gdbreplay.py`](gdbreplay.md) is a basic GDB server that can be used to replay Ibex execution + stream from a QEMU execution trace. +* `mbbdef.py`] is a simple Python tool to extract multi-bit bool definition from OpenTitan' HJSON + configuration file +* `ot-format.sh` is a simple shell wrapper to run clang-format (code formatter) on OpenTitan files +* `ot-tidy.sh` is a simple shell wrapper to run clang-tidy (C linter) on OpenTitan files +* `present.py` implements the Present 128-bit scrambler/descrambler used in OTP image files for + HW digest verification. +* `treillis/` directory contains the test application to test the [GPIO](gpio.md) device. + +## Configuration files + +* `darjeeling-ocd.cfg` is a sample configuration file for OpenOCD to connect to the JTAG interface +* `clang-format.yml` is the configuration file for clang-format used for all OpenTitan and Ibex + source files +* `clang-tidy.yml` is the configuration file for clang-tidy used for all OpenTitan and Ibex source + files +* `.flake8` is the configuration file for the Python Flake8 linter for OT tools +* `.pylintrc` is the configuration file for the Python PyLint linter for OT tools