Update Darjeeling

docs/opentitan/darjeeling.md

@@ -27,6 +27,7 @@ Please check out `hw/opentitan/ot_ref.log`
 * OTP controller
   * read and write features are supported, Present scrambling is supported w/ digest checks,
     ECC bits are ignored
+* [RISC-V Debug Module](jtag-dm.md) and Pulp Debug Module
 * SPI data flash (from QEMU upstream w/ fixes)
 * SPI Host controller
   * HW bus config is ignored (SPI mode, speed, ...)

docs/opentitan/devproxy.md

@@ -182,7 +182,7 @@ Only initiated by the application.
 +---------------+---------------+---------------+---------------+
 ```
 
-The current version for this documentation is v0.12.
+The current version for this documentation is v0.13.
 
 Note that semantic versionning does not apply for v0 series.
 
@@ -211,7 +211,7 @@ driven from the Application over the communication link.
 +---------------+---------------+---------------+---------------+
 |0 1 2 3 4 5 6 7 8 9 A B C D E F 0 1 2 3 4 5 6 7 8 9 A B C D E F|
 +---------------+---------------+---------------+---------------+
-|             'ed'              |            0..4*4N            |
+|             'ed'              |            0..4*7N            |
 +---------------+---------------+---------------+---------------+
 |                              UID                            |0|
 +---------------+---------------+---------------+---------------+
@@ -222,8 +222,10 @@ driven from the Application over the communication link.
 |                           Word Count                          |
 +---------------+---------------+---------------+---------------+
 |                                                               |
+|                                                               |
 |                           Identifier                          |
 |                                                               |
+|                                                               |
 +---------------+---------------+---------------+---------------+
 |            Offset             |         Device        |   -   |
 +---------------+---------------+---------------+---------------+
@@ -232,8 +234,10 @@ driven from the Application over the communication link.
 |                           Word Count                          |
 +---------------+---------------+---------------+---------------+
 |                                                               |
+|                                                               |
 |                           Identifier                          |
 |                                                               |
+|                                                               |
 +---------------+---------------+---------------+---------------+
 |                             ....                              |
 +---------------+---------------+---------------+---------------+
@@ -244,11 +248,13 @@ driven from the Application over the communication link.
 |                           Word Count                          |
 +---------------+---------------+---------------+---------------+
 |                                                               |
+|                                                               |
 |                           Identifier                          |
 |                                                               |
+|                                                               |
 +---------------+---------------+---------------+---------------+
 ```
-Reponse contains 0 up to N devices, each device is described with a 20-byte entry, where:
+Reponse contains 0 up to N devices, each device is described with a 28-byte entry, where:
 
 * `Device` is a unique device identifier that should be used to select the device for all further
    requests to the device.
@@ -258,7 +264,7 @@ Reponse contains 0 up to N devices, each device is described with a 20-byte entr
    only if b0 is zero.
 * `WordCount` is the count of 32-bit slots for a memory-type device
 * `Base Address` is the base address of the device in the address space as seen from the local CPU.
-* `Identifier` is an arbitrary 8-character string that describes the device.
+* `Identifier` is an arbitrary 16-character string that describes the device.
 
 The count of device entries can be retrieved from the `LENGTH` field.
 
@@ -338,7 +344,7 @@ Reponse contains 0 up to N devices, each device is described with a 28-byte entr
   commands.
 * `Start Address` is the lowest valid address in the address space.
 * `Size` is the size (in bytes) of the address space
-* `Identifier` is an arbitrary 16-character string that describes the device.
+* `Identifier` is an arbitrary 16-character string that describes the memory space.
 
 The count of address spaces can be retrieved from the `LENGTH` field.
 

docs/opentitan/gpio.md

@@ -1,19 +1,33 @@
 # OpenTitan GPIO
 
+## Foreword
+
+There are two variations of the GPIO device: one for EarlGrey, one for Darjeeling variants.
+
+In the following document, `OTMACHINE` should be defined as `eg` for EarlGrey machine or as `dj`
+for Darjeeling one.
+
 ## Initial configuration
 
-It is possible to configure initial values of the GPIO input pins:
+It is possible to configure initial values of the GPIO pins:
+
+OpenTitan GPIO driver accept global options:
 
-OpenTitan GPIO driver accept a global option:
+- `ot-gpio-$OTMACHINE.in` defines the input values of the GPIO port as a 32-bit value
+- `ot-gpio-$OTMACHINE.out` defines the output values of the GPIO port as a 32-bit value
+- `ot-gpio-$OTMACHINE.oe` defines the output enable of the GPIO port as a 32-bit value
 
-- `ot-gpio.in` that defines the input values of the GPIO port as a 32-bit value
+All values default to zero, that is all GPIOs as input/hi-z, read 0.
 
 ### Example
 
 ```
--global ot-gpio.in=0x00ffff00
+-global ot-gpio-dj.in=0x00ffff00 -global ot-gpio-dj.oe=0x1 -global ot-gpio-dj.out=0x1
 ```
 
+Note: If there were several GPIO instances in a machine, these configurations would apply to all
+GPIO instances.
+
 ## Character Device
 
 OpenTitan GPIO driver can be connected to any CharDev device to expose as a very simple ASCII data
@@ -24,7 +38,7 @@ This CharDev device can be used to stimulate the GPIO and perform unit tests.
 To connect the GPIO to its optional characted device, use the following QEMU option
 
 ```
--chardev type,id=gpio -global ot-gpio.chardev=gpio
+-chardev type,id=gpio -global ot-gpio-$OTMACHINE.chardev=gpio
 ```
 
 where type is one of the supported QEMU chardev type, such as
@@ -63,12 +77,17 @@ The hex value represents the 32-bit GPIO values.
 
 A type describes the meaning of the hex value. Supported types are:
 
+* `C` clear/reset host (at QEMU start up)
 * `D` direction, _i.e._ Output Enable in OpenTitan terminology (QEMU -> host)
 * `I` input GPIO values (host -> QEMU)
+* `M` mask GPIO input values, i.e. non connected input pins (host -> QEMU)
 * `O` output GPIO values (QEMU -> host)
+* `P` output GPIO pull up/down values (QEMU -> host)
 * `Q` query input (QEMU -> host). QEMU may emit this frame, so that the host replies with a new
-  `I` frame (hexvalue of `Q` is ignored)
+  input `I` frame (hexvalue of `Q` is ignored)
 * `R` repeat (host -> QEMU). The host may ask QEMU to repeat the last `D` and `O` frames
+* `Z` output pull up/down GPIO HiZ values (QEMU -> host). 1 means HiZ, 0 means
+  pull up/down values apply.
 
 Frames are only emitted whenever the state of either peer (QEMU, host) change. QEMU should emit `D`
 and `O` frames whenever the GPIO configuration or output values are updated. The host should emit
@@ -88,9 +107,14 @@ the QEMU machine over a serial port (a USB CDC VCP in this case).
 To connect to the NeoTrellis board, use a configuration such as:
 
 ```
--chardev serial,id=gpio,path=/dev/ttyACM1 -global ot-gpio.chardev=gpio
+-chardev serial,id=gpio,path=$SERIALDEV -global ot-gpio-$OTMACHINE.chardev=gpio
 ```
 
-where /dev/ttyACM1 is the data serial port of the Neotreillis board.
+where `SERIALDEV` is the data serial port of the Neotreillis board, _e.g._ `/dev/ttyACM1`
 
 Note: the first serial port of the board is reserved to its debug console.
+
+### Testing
+
+See the [gpiodev.py](gpiodev.md) script.
+

docs/opentitan/gpiodev.md

@@ -0,0 +1,78 @@
+# `gpiodev.py`
+
+`gpiodev.py` acts as a GPIO CharDev backend to record and verify GPIO updates.
+
+It can be used to run regression tests and verify that the guest emits a predefined sequence of
+GPIO updates.
+
+## Usage
+
+````text
+usage: gpiodev.py [-h] [-p PORT] [-c CHECK] [-r RECORD] [-e END] [-q] [-s] [-t] [-v] [-d]
+
+GPIO device tiny simulator.
+
+options:
+  -h, --help            show this help message and exit
+  -p PORT, --port PORT  remote host TCP port (defaults to 8007)
+  -c CHECK, --check CHECK
+                        input file to check command sequence
+  -r RECORD, --record RECORD
+                        output file to record command sequence
+  -e END, --end END     emit the specified value to trigger remote exit on last received command
+  -q, --quit-on-error   exit on first error
+  -s, --single          run once: terminate once first remote disconnects
+  -t, --log-time        emit time in log messages
+  -v, --verbose         increase verbosity
+  -d, --debug           enable debug mode
+````
+
+### Arguments
+
+* `-d` only useful to debug the script, reports any Python traceback to the standard error stream.
+
+* `-p` specify an alternative TCP port to listen for incoming QEMU CharDev socket requests
+
+* `-c` specify a pre-recorded GPIO backend text file - which only contains ASCII characters and
+  compare that incoming GPIO requests against the recorded data
+
+* `-r` specify a file to record incoming GPIO requests
+
+* `-e` emit a pre-defined GPIO input command - sent to the QEMU GPIO CharDev backend - that may be
+  recognized by the QEMU guest code as a special marker to end a test sequence. Requires the _check_
+  option for detecting the last expected GPIO request.
+
+* `-q` close the QEMU socket connection on first error or mismatched GPIO request when used with
+  the _check_ option.
+
+* `-s` quite the script on the first QEMU socket disconnection. Default is to listen for a new QEMU
+  CharDev socket connection, restarting from a fresh state.
+
+* `-t` add time to log messages
+
+* `-v` can be repeated to increase verbosity of the script, mostly for debug purpose.
+
+### Exit Status
+
+This script returns 0 if no error has been detected, or 1 if an error has been detected or the
+GPIO command stream has not been validated against the check file if any.
+
+### Examples
+
+With the following examples:
+
+`-chardev socket,id=gpio,host=localhost,port=8007 -global ot-gpio-$OTMACHINE.chardev=gpio` has been
+added to the QEMU command line to connect the GPIO backend to the incoming socket opened from the
+script. See the [GPIO documentation](gpio.md) for details and the role of the `OTMACHINE`
+environment variable.
+
+* Record a GPIO request sequence
+  ````sh
+  ./scripts/opentitan/gpiodev.py -vv -r gpio.txt -s
+  ````
+
+* Check a GPIO request sequence against a previously record one, then triggers a VM guest app
+  triggered termination by setting GPIO 31 to a high level.
+  ````sh
+  ./scripts/opentitan/gpiodev.py -vv -c gpio.txt -s -e 0x8000_0000
+  ````

docs/opentitan/jtag-dm.md

@@ -0,0 +1,120 @@
+# JTAG and RISC-V Debug Module support for OpenTitan
+
+RISC-V Debug Module is implemented as an alternative to the default QEMU GDB server.
+
+It can be used when low-level features are required, such as prototyping JTAG manufacturing and
+provisioning software development, or emulating JTAG Debug Authentication.
+
+This initial implementation of the RISC-V Debug Module and Pulp DM supports the following features:
+
+- Ibex core debugging (RV32 only); not tested with multiple harts
+- system bus memory access: read and write guest memory
+- guest code debugging
+- single stepping
+- HW breakpoints
+- HW watchpoints
+
+## Communicating with RISC-V DM through a JTAG connection
+
+In QEMU machines for OpenTitan, any Debug Module can register on the Debug Transport Module, which
+dispatches requests to Debug Module depending on the received DMI address.
+
+See also [JTAG mailbox](jtagmbx.md) and [Life Controller](lc_ctrl_dmi.md) for other Debug Modules.
+
+```
++----------------+
+| Host (OpenOCD) |
++----------------+
+      |
+      | TCP connection ("bitbang mode")
+      |
++-----|-----------------------------------------------------------------------------------+
+|     |                                                                             QEMU  |
+|     v                                              +---------+                          |
+| +-------------+     +-----+     +-----------+      | PULP-DM |         +------+         |
+| | JTAG server |---->| DTM |---->| RISC-V DM |<---->+ ------- +<=======>| Hart |         |
+| +-------------+     +-----+     +-----------+      | ROM/RAM |    ||   +------+         |
+|                                      ||            +---------+    ||                    |
+|                                      ||                           ||   +--------------+ |
+|                                       ================================>| I/O, RAM, ...| |
+|                                                                        +--------------+ |
++-----------------------------------------------------------------------------------------+
+```
+
+### Remote bitbang protocol
+
+The JTAG server supports the Remote Bitbang Protocol which is compatible with other tools such as
+Spike and [OpenOCD](https://github.com/riscv/riscv-openocd).
+
+QEMU should be started with an option such as `-jtag tcp::3335` so that the JTAG server is
+instantiated and listens for incoming connection on TCP port 3335.
+
+#### Remote termination feature
+
+The remote Remote Bitbang Protocol supports a "_quit_" feature which enables the remote client to
+trigger the end of execution of the QEMU VM. This feature can be useful to run automated tests for
+example.
+
+It is nevertheless possible to disable this feature and ignore the remote exit request so that
+multiple JTAG sessions can be run without terminating the QEMU VM.
+
+To disable this feature, use the `quit` option: `-jtag tcp::3335,quit=off`.
+
+#### macOS
+
+If you want to avoid the boring pop-up window from macOS
+```
+Do you want the application “qemu-system-riscv32” to accept incoming network connections?
+```
+restrict the listening interfaces to the localhost with `-jtag tcp:localhost:3335` as QEMU defaults
+to listening on all interfaces, _i.e._ 0.0.0.0
+
+#### Implementation
+
+* JTAG server is implemented with `jtag/jtag_bitbang.c`
+* DTM is implemented with `hw/riscv/dtm.c`
+* RISC-V DM is implemented with `hw/riscv/dm.c`
+* Pulp-DM is implemented with `hw/misc/pulp_rv_dm.c`
+
+See also other supported DM modules on OpenTitan:
+
+* [JTAG mailbox DMI](jtagmbx.md)
+* [LifeCycle DMI](lc_ctrl_dmi.md)
+
+## Communicating with JTAG server using OpenOCD
+
+OpenOCD running on a host can connect to the embedded JTAG server, using a configuration script such
+as
+
+```tcl
+adapter driver remote_bitbang
+remote_bitbang host localhost
+remote_bitbang port 3335
+
+transport select jtag
+
+set _CHIPNAME riscv
+# part 1, ver 0, lowRISC; actual TAP id depends on the QEMU machine
+set _CPUTAPID 0x00011cdf
+
+jtag newtap $_CHIPNAME cpu -irlen 5 -expected-id $_CPUTAPID
+
+# Hart debug base also depends on the QEMU machine
+set DM_BASE 0x00
+
+target create $_CHIPNAME riscv -chain-position $_TARGETNAME rtos hwthread -dbgbase $DM_BASE
+```
+
+## Connecting GDB to OpenOCD
+
+In another terminal, `riscv{32,64}-unknown-elf-gdb` can be used to connect to OpenOCD:
+
+```
+# 64-bit version support 32-bit targets
+riscv64-unknown-elf-gdb
+```
+
+A basic `$HOME/.gdbinit` as the following should connect GDB to the running OpenOCD instance:
+```
+target remote :3333
+```

docs/opentitan/jtagmbx.md

@@ -5,7 +5,7 @@ system side (requester) is connected to a Debug Tile Link bus.
 
 ## Communicating with the JTAG Mailbox through a JTAG connection
 
-In QEMU, a bridge between the Debug Module Interface (DMI) and the JTAG Mailbox is implemented
+In QEMU, a bridge between the Debug Transport Module (DTM) and the JTAG Mailbox is implemented
 as Debug Module bridge.
 
 ```
@@ -18,7 +18,7 @@ as Debug Module bridge.
 +-----|-----------------------------------------------------------------------------------+
 |     v                                                                                   |
 | +-------------+     +-----+     +----------+         +---------+         +------+       |
-| | JTAG server |---->| DMI |---->| ot_dm_tl |====D====|S> MBX <H|====P====| Hart |       |
+| | JTAG server |---->| DTM |---->| ot_dm_tl |====D====|S> MBX <H|====P====| Hart |       |
 | +-------------+     +-----+     +----------+         +---------+         +------+       |
 |                                                                                     QEMU|
 +-----------------------------------------------------------------------------------------+
@@ -136,7 +136,7 @@ no RISC-V DM module is connected to the DMI device, _i.e._
 +-----|-----------------------------------------------------------------------------------+
 |     v                                                                                   |
 | +-------------+     +-----+     +----------+         +---------+         +------+       |
-| | JTAG server |---->| DMI |-+-->| ot_dm_tl |====D====|S> MBX <H|===++=P==| Hart |       |
+| | JTAG server |---->| DTM |-+-->| ot_dm_tl |====D====|S> MBX <H|===++=P==| Hart |       |
 | +-------------+     +-----+ |   +----------+         +---------+   ||    +------+       |
 |                             |                                      ||                   |
 |                             |   +----+     +-------- +             ||                   |