From 1453f6ec84c34e1e1b5d0858cba95250ccaccf5c Mon Sep 17 00:00:00 2001 From: Alex Jones Date: Fri, 10 Apr 2026 23:32:42 +0100 Subject: [PATCH 1/5] [doc] Fix WaveDrom mdbook preprocessor shebang not finding Nix Python Fix execution environment for the WaveDrom mdbook preprocessor by explicitly providing Python 3 as a native build input and invoking the preprocessor via the mdBook command configuration, avoiding reliance on the `/usr/bin/env` shebang resolution that seemed to not be working with Nix. Signed-off-by: Alex Jones --- book.toml | 2 +- flake.nix | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/book.toml b/book.toml index f595c034a..f8fb9982f 100644 --- a/book.toml +++ b/book.toml @@ -26,7 +26,7 @@ additional-css = [ ] [preprocessor.wavejson] -command = "./util/mdbook_wavejson.py" +command = "python3 ./util/mdbook_wavejson.py" [preprocessor.replace] after = ["links"] diff --git a/flake.nix b/flake.nix index 9f81d0cbd..65601d9d2 100644 --- a/flake.nix +++ b/flake.nix @@ -84,6 +84,7 @@ sonata-documentation = lrDoc.buildMdbookSite { version = ""; pname = "sonata-documentation"; + nativeBuildInputs = [pkgs.python311]; src = fileset.toSource { root = ./.; fileset = fileset.unions [ From 051d98530b9aff4f9f5c301587ab44b7dd7c7876 Mon Sep 17 00:00:00 2001 From: Alex Jones Date: Fri, 10 Apr 2026 23:29:03 +0100 Subject: [PATCH 2/5] [doc] Fix WaveDrom DOM rendering race condition with mdBook Ensure that WaveDrom DOM manipulation runs after mdBook mutations complete by switching from window load to `DomContentLoaded`. Should hopefully prevent partial DOM rewriting which is the likely cause of the issues in rendering. Issues likely appeared at a certain point as a newer version of mdBook was pulled in that has some different DOM mutation behaviour. Signed-off-by: Alex Jones --- util/mdbook/wavejson/wavejson.js | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/util/mdbook/wavejson/wavejson.js b/util/mdbook/wavejson/wavejson.js index 35c91d8b6..424f29243 100644 --- a/util/mdbook/wavejson/wavejson.js +++ b/util/mdbook/wavejson/wavejson.js @@ -1,4 +1,11 @@ // Copyright lowRISC contributors. // Licensed under the Apache License, Version 2.0, see LICENSE for details. // SPDX-License-Identifier: Apache-2.0 -window.addEventListener('load', WaveDrom.ProcessAll) + +// WaveDrom must run after mdBook has finished all DOM mutations. Using `window.load` +// is unreliable because content might still be re-written at that time, causing +// WaveDROM to see a partially mutated DOM and fail. It seems likely that newer +// mdBook versions have somehow implemented heavier / longer DOM manipulation. +document.addEventListener("DOMContentLoaded", () => + requestAnimationFrame(() => WaveDrom.ProcessAll()) +); From 03803f719fc8d31a7f98461e38339951c761edf8 Mon Sep 17 00:00:00 2001 From: Alex Jones Date: Fri, 10 Apr 2026 23:47:17 +0100 Subject: [PATCH 3/5] [doc] Minor I2C/UART doc updates to point to the locked OT revision Make sure that the linked documentation actually reflects the state of the registers, even if it isn't on the rendered OpenTitan site. Also make a couple of grammatical fixes and correct a typo. Signed-off-by: Alex Jones --- doc/ip/i2c.md | 10 ++++++---- doc/ip/uart.md | 5 +++-- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/ip/i2c.md b/doc/ip/i2c.md index cc4c51ddf..98f5aadc2 100644 --- a/doc/ip/i2c.md +++ b/doc/ip/i2c.md @@ -1,13 +1,15 @@ # Inter-integrated circuit (I2C) host -For the I2C block in Sonata, we use the [OpenTitan IP](https://opentitan.org/book/hw/ip/i2c/index.html). -We hardcode this block to be in host mode, so you can ignore the target functionality, including register `ovrd`, `val`, `target_id`, `acqdata` and `txdata`. -Other than those you can find the [register definitions here](https://opentitan.org/book/hw/ip/i2c/doc/registers.html). +For the I2C block in Sonata, we use the OpenTitan IP. +The version of the IP that is vendored in has documentation that you can find [here](https://github.com/lowRISC/opentitan/tree/a78922f14a8cc20c7ee569f322a04626f2ac6127/hw/ip/i2c/doc). +Another useful reference is the [existing driver](https://github.com/microsoft/cheriot-rtos/blob/main/sdk/include/platform/sunburst/platform-i2c.hh) for this block in the CHERIoT RTOS repository. +We hardcode this block to be in host mode, so you can ignore the target functionality, including the following registers: `ovrd`, `val`, `target_id`, `acqdata` and `txdata`. +Other than those, you can find the [register definitions here](https://github.com/lowRISC/opentitan/blob/a78922f14a8cc20c7ee569f322a04626f2ac6127/hw/ip/i2c/doc/registers.md). The registers `0x00` - `0x10` are also not accessible. The control register is just hardwired to be in host mode. For Sonata, we include two I2C blocks. -The registers of the second I2C block can be accessed with and additional `0x1000` offset. +The registers of the second I2C block can be accessed with an additional `0x1000` offset. These can be connected to any of these I2C targets: - Two for the QWIIC connectors. - One for the mikroBUS. diff --git a/doc/ip/uart.md b/doc/ip/uart.md index 902512131..fcc10b4c2 100644 --- a/doc/ip/uart.md +++ b/doc/ip/uart.md @@ -1,7 +1,8 @@ # Universal asynchronous receiver/transmitter (UART) -The Sonata system uses [the OpenTitan UART](https://opentitan.org/book/hw/ip/uart/index.html). -You can find [the register definitions here](https://opentitan.org/book/hw/ip/uart/doc/registers.html). +The Sonata system uses the OpenTitan UART. +The version of the IP that is vendored in has documentation that you can find [here](https://github.com/lowRISC/opentitan/tree/a78922f14a8cc20c7ee569f322a04626f2ac6127/hw/ip/uart/doc). +You can find [the register definitions here](https://github.com/lowRISC/opentitan/blob/a78922f14a8cc20c7ee569f322a04626f2ac6127/hw/ip/uart/doc/registers.md). There are multiple UART instances in Sonata to connect to any of the following targets: - USB From c30b994d15e5472ab368a6aa9f1f38f433d74fd6 Mon Sep 17 00:00:00 2001 From: Alex Jones Date: Sat, 11 Apr 2026 00:07:42 +0100 Subject: [PATCH 4/5] [doc] Update PLIC interrupt mapping These were out of date for the newer releases which combined multiple interrupt sources into a single shared interrupt line per block/instance, and which also added more interrupt sources (GPIO, USB device, hardware revoker). Signed-off-by: Alex Jones --- doc/ip/plic.md | 52 ++++++++++++++++++++++---------------------------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/doc/ip/plic.md b/doc/ip/plic.md index e01d2e239..ae55e12ca 100644 --- a/doc/ip/plic.md +++ b/doc/ip/plic.md @@ -7,33 +7,27 @@ Not all of these registers are mapped, most importantly we only have one core, s The following table shows the current list of interrupts that are fed through the PLIC. For more detailed descriptions of what each interrupt means, please refer to the documentation of each individual hardware IP block. -More interrupts may be added to this table in the future. - -| Number | Block | Interrupt description | -|--------|-----------|-----------------------| -| 0 | None | Tied to zero -| 1, 9 | UART 0, 1 | Transmit watermark -| 2, 10 | UART 0, 1 | Receive watermark -| 3, 11 | UART 0, 1 | Transmit empty -| 4, 12 | UART 0, 1 | Receive overflow -| 5, 13 | UART 0, 1 | Receive frame error -| 6, 14 | UART 0, 1 | Receive break error -| 7, 15 | UART 0, 1 | Receive timeout -| 8, 16 | UART 0, 1 | Receive parity error -| 17, 32 | I2C 0, 1 | Format FIFO threshold -| 18, 33 | I2C 0, 1 | Receive FIFO threshold -| 19, 34 | I2C 0, 1 | Acquire FIFO threshold -| 20, 35 | I2C 0, 1 | Receive FIFO overflow -| 21, 36 | I2C 0, 1 | Received NACK -| 22, 37 | I2C 0, 1 | SCL interference -| 23, 38 | I2C 0, 1 | SDA interference -| 24, 39 | I2C 0, 1 | Stretch timeout -| 25, 40 | I2C 0, 1 | SDA unstable -| 26, 41 | I2C 0, 1 | Command complete -| 27, 42 | I2C 0, 1 | Transmit stretch -| 28, 43 | I2C 0, 1 | Transmit threshold -| 29, 44 | I2C 0, 1 | Acquire FIFO full -| 30, 45 | I2C 0, 1 | Unexpected stop -| 31, 46 | I2C 0, 1 | Host timeout -| 47 | Ethernet | Interrupt from external SPI ethernet chip (KSZ8851SNLI-TR). Check the interrupt status register for details. +For most blocks, interrupts are multiplexed - all hardware interrupt sources are presented as a single interrupt to the PLIC. +The relevant software `INTR_STATE` registers should be queried by software to determine the interrupt cause. +| Number | Block | Interrupt description | +|--------|------------|-----------------------| +| 0 | None | Tied to zero +| 1 | Revoker | Hardware revoker sweep complete +| 2 | Ethernet | Interrupt from external SPI ethernet chip (KSZ8851SNLI-TR) +| 3 | USB Dev | Shared USB Device interrupt +| 4 | GPIO | Shared GPIO interrupt +| 5-7 | None | Reserved +| 8 | UART 0 | Shared interrupt for UART0 +| 9 | UART 1 | Shared interrupt for UART1 +| 10 | UART 2 | Shared interrupt for UART2 +| 11-15 | None | Reserved +| 16 | I2C 0 | Shared interrupt for I2C0 +| 17 | I2C 1 | Shared interrupt for I2C1 +| 18-23 | None | Reserved +| 24 | SPI LCD | Shared interrupt for the LCD SPI +| 25 | SPI Ethmac | Shared interrupt for the Ethernet SPI +| 26 | SPI 0 | Shared interrupt for SPI0 +| 27 | SPI 1 | Shared interrupt for SPI1 +| 28 | SPI 2 | Shared interrupt for SPI2 +| 29-31 | None | Reserved From 996dbe7d9eea2d4c229902c017faa6c28f9227dc Mon Sep 17 00:00:00 2001 From: Alex Jones Date: Mon, 13 Apr 2026 11:13:18 +0100 Subject: [PATCH 5/5] [doc] Fix outdated SPI interrupt note SPI interrupts have been implemented in HW for a while, these docs are just out of date. Signed-off-by: Alex Jones --- doc/ip/spi.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/ip/spi.md b/doc/ip/spi.md index a3d7bae17..7ff1f5ad8 100644 --- a/doc/ip/spi.md +++ b/doc/ip/spi.md @@ -34,8 +34,6 @@ To begin an SPI transaction write to the [`START`](#start) register. Bytes do not need to be immediately available in the transmit FIFO nor space available in the receive FIFO to begin the transaction. The SPI block will only run the clock when its able to proceed. -**Note Interrupts are not yet implemented** - ## Register Table