From a843db8f75b51fb929bc3ec8d0a75730f646f34c Mon Sep 17 00:00:00 2001 From: Marno van der Maas Date: Tue, 17 Mar 2026 15:17:18 +0000 Subject: [PATCH] [doc] Move reference info to the end This stops people in a workshop from getting stuck reading reference documentation when this is not necessary for doing the exercises. --- README.md | 21 ++++----------------- SUMMARY.md | 9 +++++---- doc/reference/README.md | 25 +++++++++++++++++++++++++ 3 files changed, 34 insertions(+), 21 deletions(-) create mode 100644 doc/reference/README.md diff --git a/README.md b/README.md index 636b1b4..cf89b1b 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ This repository contains software, build flows and examples for the [Sonata Syst For a guide on how to get up and running on building software for the sonata board see the [getting started guide][]. After you are all set up, take a look at the [exercises][]. -[sonata system]: https://github.com/lowRISC/sonata-system -[sonata pcb]: https://github.com/newaetech/sonata-pcb +[Sonata System]: https://github.com/lowRISC/sonata-system +[Sonata PCB]: https://github.com/newaetech/sonata-pcb [getting started guide]: ./doc/getting-started.md [exercises]: ./exercises/README.md @@ -15,25 +15,12 @@ You are in the [`sonata-software`][] repository. This repository wraps the [`cheriot-rtos`][], which is included in this repository as a submodule. [`cheriot-rtos`][] contains the CHERIoT software stack as well as drivers for using the Sonata board; it is well documented by the [CHERIoT Programmer's Guide][]. -Other repositories of note: -- [`sonata-system`][]: holds the Sonata system RTL and bootloader which come together to generate the bitstream. -- [`sonata-rp2040`][]: The firmware that is running on the Sonata's RP2040 microcontroller and emulates the 'SONATA' drive when you plug it into your computer. -- [`CHERIoT-Platform/llvm-project`][]: The CHERIoT LLVM compiler toolchain. -- [`cheriot-audit`][]: A tool to explore and verify the relationships between CHERIoT RTOS components. -- [`CHERIoT-Platform/book`][]: The source of the [CHERIoT Programmer's Guide][]. - -For hardware documentation, see the [Sonata system book][]. +You do not need this to do the exercises but if you would like more detailed documentation about the hardware, see the [Sonata System book][]. [`sonata-software`]: https://github.com/lowRISC/sonata-software [`cheriot-rtos`]: https://github.com/CHERIoT-Platform/cheriot-rtos -[`sonata-system`]: https://github.com/lowRISC/sonata-system -[`sonata-rp2040`]: https://github.com/newaetech/sonata-rp2040 -[`CHERIoT-Platform/llvm-project`]: https://github.com/CHERIoT-Platform/llvm-project -[`cheriot-audit`]: https://github.com/CHERIoT-Platform/cheriot-audit -[`CHERIoT-Platform/book`]: https://github.com/CHERIoT-Platform/book [CHERIoT Programmer's Guide]: https://cheriot.org/book/ -[Sonata system book]: https://lowrisc.org/sonata-system/ - +[Sonata System book]: https://lowrisc.org/sonata-system/ ## License diff --git a/SUMMARY.md b/SUMMARY.md index 032bcfd..18448e6 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -8,11 +8,12 @@ SPDX-License-Identifier: Apache-2.0 - [Getting started](./doc/getting-started.md) - [Running Sonata software](./doc/guide/running-software.md) - - [Using Sonata IO](./doc/guide/sonata-io.md) - -- [Exploring the CHERIoT RTOS](./doc/exploring-cheriot-rtos.md) -- [Auditing firmware](./doc/auditing-firmware.md) - [Exercises](./exercises/README.md) - [Hardware access control exercise](./exercises/hardware_access_control/README.md) - [Firmware auditing exercise](./exercises/firmware_auditing/README.md) + +- [Reference](./doc/reference/README.md) + - [Using Sonata IO](./doc/guide/sonata-io.md) + - [Exploring the CHERIoT RTOS](./doc/exploring-cheriot-rtos.md) + - [Auditing firmware](./doc/auditing-firmware.md) diff --git a/doc/reference/README.md b/doc/reference/README.md new file mode 100644 index 0000000..03f19eb --- /dev/null +++ b/doc/reference/README.md @@ -0,0 +1,25 @@ +# Reference + +The rest of this book is reference and background information. +This information is not necessary to do the exercises, but is still useful for the broader context. + +You may also want to look at the other documentation available for Sonata and CHERIoT in general: +- [`sonata-system`][]: holds the Sonata System RTL and bootloader which come together to generate the bitstream. +This repository also has a rendered [Sonata System book][]. +- [`sonata-rp2040`][]: The firmware that is running on the Sonata's RP2040 microcontroller and emulates the 'SONATA' drive when you plug it into your computer. +- [`sonata-pcb`][]: The printed circuit board design for Sonata. +- [`cheriot-rtos`][]: The CHERIoT software stack as well as drivers for the Sonata board. +- [`CHERIoT-Platform/llvm-project`][]: The CHERIoT LLVM compiler toolchain. +- [`cheriot-audit`][]: A tool to explore and verify the relationships between CHERIoT RTOS components. +- [`CHERIoT-Platform/book`][]: The source of the [CHERIoT Programmer's Guide][]. + +[`sonata-software`]: https://github.com/lowRISC/sonata-software +[`cheriot-rtos`]: https://github.com/CHERIoT-Platform/cheriot-rtos +[`sonata-system`]: https://github.com/lowRISC/sonata-system +[`sonata-rp2040`]: https://github.com/newaetech/sonata-rp2040 +[`CHERIoT-Platform/llvm-project`]: https://github.com/CHERIoT-Platform/llvm-project +[`cheriot-audit`]: https://github.com/CHERIoT-Platform/cheriot-audit +[`CHERIoT-Platform/book`]: https://github.com/CHERIoT-Platform/book +[CHERIoT Programmer's Guide]: https://cheriot.org/book/ +[Sonata System book]: https://lowrisc.org/sonata-system/ +[`sonata-pcb`]: https://github.com/newaetech/sonata-pcb