[ot] docs/opentitan: update Earlgrey doc, create Darjeeling doc

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)
 

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=<filename>,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=<filename>` 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=<filename>,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.

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
 

docs/opentitan/gpio.md

@@ -1,4 +1,4 @@
-# OT GPIO
+# OpenTitan GPIO
 
 ## Initial configuration
 

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

docs/opentitan/spi_device.md

@@ -1,4 +1,4 @@
-# SPI Device support
+# OpenTitan SPI Device support
 
 ## Supported modes