Review wording of new documentation

README.md

@@ -20,8 +20,8 @@ The [`lowrisc/cheriot-rtos`][], included in this repository as a submodule, is a
 
 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.
-- [`CHERIoT-Platform/llvm-project`][]: The CHERIoT toolchain.
+- [`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 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][].
 
@@ -41,4 +41,5 @@ For hardware documentation, see the [Sonata system book][].
 
 ## License
 
-Unless otherwise noted, everything in the repository is covered by the [Apache License](https://www.apache.org/licenses/LICENSE-2.0.html), Version 2.0. See the [LICENSE](https://github.com/lowRISC/sonata-software/blob/main/LICENSE) file for more information on licensing.
+Unless otherwise noted, everything in the repository is covered by the [Apache License](https://www.apache.org/licenses/LICENSE-2.0.html), Version 2.0.
+See the [LICENSE](https://github.com/lowRISC/sonata-software/blob/main/LICENSE) file for more information on licensing.

doc/exploring-cheriot-rtos.md

@@ -1,6 +1,6 @@
 # Exploring CHERIoT RTOS
 ## CHERIoT RTOS Orientation
-All the software in this repository runs on the CHERIoT RTOS, which is pulled into this repository as a submodule at [`cheriot-rtos`].
+All the software in this repository runs on the CHERIoT RTOS, which is pulled in at the root of this repository as a submodule named [`cheriot-rtos`].
 The [CHERIoT Programmer's Guide] contains most of what a programmer would need to know to use the RTOS.
 
 [`cheriot-rtos`]: ../cheriot-rtos
@@ -29,14 +29,14 @@ For examples of using these rules, look at a root `xmake.lua` file, such as [`ex
 ## Building an upstream CHERIoT RTOS example
 
 The examples in [`cheriot-rtos/examples`](../cheriot-rtos/examples) provide a nice tour of the different ways compartments can interact.
-These can be built by pointing xmake to the example one wants to build, as shown below.
+These can be built by pointing xmake to the example one wants to build, as shown below:
 
 ```sh
 # Run from the root of the sonata-software repository
 xmake -P cheriot-rtos/examples/05.sealing/
 ```
 
-### Where's my UF2
+### Where's my UF2?
 
 If you've followed the '[running software on the FPGA]' guide, you'll expect UF2 files as part of the build artefacts but these aren't automatically created in the [`cheriot-rtos`][] repository.
 Thankfully, this repository includes a `./scripts/elf-to-uf2.sh` script that converts an ELF into a firmware a UF2 file.

doc/getting-started.md

@@ -1,18 +1,22 @@
 # CHES CHERIoT Workshop Preparation
 
-In advance of the CHES Affiliated Sunburst Workshop, it's essential you prepare your environment so any issues can be sorted in advance of the day. If you have any issues in following this guide please contact the Sunburst Team on [[email protected]](mailto:[email protected]).
+In advance of the CHES Affiliated Sunburst Workshop, it's essential you prepare your environment so any issues can be sorted in advance of the day.
+If you have any issues in following this guide please contact the Sunburst Team on [[email protected]](mailto:[email protected]).
 
-The Sonata software build environment can be setup under Windows, OSX and Linux.
+The Sonata software build environment can be setup under Windows, macOS and Linux.
 
-We use a tool called [Nix](https://nixos.org/) to manage the build environment on all platforms. You will install it but don't need to know anything about it to follow these instructions.
+We use a tool called [Nix](https://nixos.org/) to manage the build environment on all platforms.
+You will install it but don't need to know anything about it to follow these instructions.
 
-Only Windows requires specific instructions, Nix handles everything you need on Linux and OSX. So if you're not using Windows jump straight to 'Installing Nix'.
+Only Windows requires specific instructions, Nix handles everything you need on Linux and macOS.
+So if you're not using Windows jump straight to [Installing Nix](#installing-nix).
 
 ## Windows Specific Setup
 
 To obtain a Linux environment on Windows, you can choose to start a virtual machine or use Windows Subsystem for Linux (WSL).
 
-Microsoft provides a detailed guide on how to install WSL: https://learn.microsoft.com/en-us/windows/wsl/install. For latest systems this would just be a single command:
+Microsoft provides [a detailed guide on how to install WSL](https://learn.microsoft.com/en-us/windows/wsl/install).
+For latest systems this would just be a single command:
 ```bat
 wsl --install
 ```
@@ -21,14 +25,16 @@ You might need to enable virtualisation in the BIOS if it's not enabled by defau
 If you are running the command without admin privileges, user account control (UAC) popups will appear a few times asking to allow changes to be made to the device.
 Click "yes" to approve.
 
-After the command's completion, it should say that Ubuntu is installed. Reboot your machine to make these changes effective.
+After the command's completion, it should say that Ubuntu is installed.
+Reboot your machine for the changes to take effect.
 
 After rebooting, Ubuntu should be available in your start menu.
-Click it to start. For the first time, it would prompt you to select a Unix username and password.
+Click it to start.
+For the first time, it prompts you to select a Unix username and password.
 Follow the Linux (Ubuntu) steps for the rest of this guide.
 
 > ℹ️ If you have installed your WSL a long time ago, systemd may not have been enabled by default.
-> It is recommended to use enable systemd.
+> It is recommended to enable systemd.
 > See https://learn.microsoft.com/en-us/windows/wsl/systemd.
 
 ## Installing Nix
@@ -40,38 +46,37 @@ We recommend installing Nix with the Determinate Systems' [`nix-installer`](http
 curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
 ```
 
-For more indepth instructions, follow the guide on [the zero to nix site](https://zero-to-nix.com/start/install).
+For more in-depth instructions, follow the guide on [the zero to nix site](https://zero-to-nix.com/start/install).
 
-*If you've downloaded nix through another method, make sure the experimental features ["flakes"](https://nixos.wiki/wiki/Flakes) and ["nix-command"](https://nixos.wiki/wiki/Nix_command) are enabled.*
+*If you've downloaded Nix through another method, make sure the experimental features ["flakes"](https://nixos.wiki/wiki/Flakes) and ["nix-command"](https://nixos.wiki/wiki/Nix_command) are enabled.*
 
 *To use Nix from the terminal you'll need to open up a new terminal for it to be added to your path.*
 
 ### Setup Cache
 
-To make use of the lowRISC cache so you don't have to rebuild binaries yourself, you'll need to make sure you're a trusted user.
-To do this, you will need to add your user to the trusted users in `/etc/nix/nix.conf`, e.g. `trusted-users = root username`. *You can also add all users from a certain group instead of a single user by using an `@` symbol before the group name, e.g. `@sudo` or `@wheel`.*
+To make use of the lowRISC Nix cache, so you don't have to rebuild binaries yourself, you'll need to make sure you're a trusted user.
+To do this, you will need to add your user to the trusted users in `/etc/nix/nix.conf`, e.g. `trusted-users = root username`.
+*You can also add all users from a certain group instead of a single user by using an `@` symbol before the group name, e.g. `@sudo` or `@wheel`.*
 
 > ℹ️ For Ubuntu users (including WSL users), this means adding this line to the `/etc/nix/nix.conf`:
 > ```
 > trusted-users = root @sudo
 > ```
-> 
+>
 > You'll need to restart the nix-daemon afterwards for the change to be picked up.
 > ```sh
 > sudo systemctl restart nix-daemon
 > ```
 
-
-> ℹ️ For OSX users, this means adding this line to the `/etc/nix/nix.conf`:
+> ℹ️ For macOS users, this means adding this line to the `/etc/nix/nix.conf`:
 > ```
 > trusted-users = root @admin
 > ```
-> 
+>
 > You then need to restart your Mac for the changes to take effect.
 
 ## Enter the CHERIoT development environment
 
-
 Running the following will put you in a shell environment with all the applications needed to build the CHERIoT RTOS.
 
 ```sh
@@ -81,7 +86,8 @@ nix develop github:lowRISC/sonata-software
 exit
 ```
 
-These applications are layered on top of your usual environment. You can see what was added with `echo $PATH`.
+These applications are layered on top of your usual environment.
+You can see what was added with `echo $PATH`.
 
 ```
 do you want to allow configuration setting 'extra-substituters' to be set to 'https://nix-cache.lowrisc.org/public/' (y/N)? y
@@ -91,8 +97,8 @@ do you want to permanently mark this value as trusted (y/N)? y
 warning: ignoring untrusted substituter 'https://nix-cache.lowrisc.org/public/', you are not a trusted user.
 ```
 
-If you see the warning that substituter is ignored, cancel the process with Ctrl+C and check to see that [trusted-users is setup properly](#setup-cache). Nix can and will build everything from source if it can't find a cached version, so letting it continue will cause LLVM-Cheriot to be built from scratch on your machine.
-
+If you see the warning that substituter is ignored, cancel the process with Ctrl+C and check to see that [trusted-users is setup properly](#setup-cache).
+Nix can and will build everything from source if it can't find a cached version, so letting it continue will cause LLVM-Cheriot to be built from scratch on your machine.
 
 ## Your first build
 
@@ -125,7 +131,8 @@ Wrote 147968 bytes to build/cheriot/cheriot/release/sonata_simple_demo.uf2
 
 (Note output size may differ)
 
-If you have got a successful build, congratulations! Your environment is ready to go for Sonata software development. Get in touch with Greg Chadwick on [[email protected]](mailto:[email protected]) if you have any issues.
+If you have got a successful build, congratulations! Your environment is ready to go for Sonata software development.
+Get in touch with lowRISC on [[email protected]](mailto:[email protected]) if you have any issues.
 
 For reference the full output (from a build run on a Linux machine) looks like:
 

doc/guide/running-software.md

@@ -1,12 +1,12 @@
 # Running Sonata Software
 
-One can either run software [on the sonata FPGA board](#running-on-the-sonata-fpga)
+You can either run software [on the sonata FPGA board](#running-on-the-sonata-fpga)
 or [in the sonata simulator](#running-in-the-simulator).
 
 ## Running in the simulator
 
 In the [getting started guide][], you entered the default environment with `nix develop`.
-Because you now want to use the simulator, you will want to enter the environment that includes the simulator with the following.
+Because you now want to use the simulator, you need to enter the environment that includes the simulator:
 
 ```sh
 nix develop .#env-with-sim
@@ -16,7 +16,7 @@ nix develop .#env-with-sim
 
 This will pull the simulator into your path as `sonata-simulator`.
 There's a convenience script, `scripts/run_sim.sh`, for calling the simulator.
-One simply points the script to a built ELF file and it will run the firmware in the simulator.
+You simply point the script to a built ELF file and it will run the firmware in the simulator.
 *The ELF file is the build artefact with the same name as the firmware image and no extension.*
 Note, the simulator will never terminate, so you will have to <kbd>Ctrl</kbd>+<kbd>C</kbd> to terminate the simulator.
 
@@ -26,7 +26,7 @@ Note, the simulator will never terminate, so you will have to <kbd>Ctrl</kbd>+<k
 
 UART output can be seen in the `uart0.log` file, which should appear in the directory the simulator was run from.
 This can be observed using `tail -f` which will monitor the file and output as soon as something is written to the UART.
-Note with the simulator running in the foreground this will need to be run in another terminal
+Note with the simulator running in the foreground this will need to be run in another terminal:
 
 ```sh
 tail -f uart0.log
@@ -37,20 +37,28 @@ tail -f uart0.log
 Any builds of software in this repository will also produce a UF2 file containing the built firmware.
 When the Sonata FPGA is plugged into the computer, it should show up as a drive called 'SONATA'.
 On my computer, it can be found at `/run/media/$USER/SONATA`.
-One just needs to copy the built UF2 file onto this drive for it to be loaded and run.
+You can copy the built UF2 file into this drive for the firmware to be loaded and run.
 
 ```sh
 cp build/cheriot/cheriot/release/sonata_simple_demo.uf2 "/run/media/$USER/SONATA/"
-sync # This `sync` command is rarely necessary
+sync # This `sync` command is rarely necessary.
 ```
 
-To see the UART console logs, attach to `/dev/ttyUSB2` at a Baud of 921,600 with your favourite terminal.
+*On Windows it's likely easier to use the file explorer to copy the UF2 to the `SONATA` drive.*
+*Look for the Linux section below `This PC`.*
+
+To see the UART console logs, attach to `/dev/ttyUSB2` at a Baud rate of 921,600 with your favourite terminal.
 
 ```sh
 picocom /dev/ttyUSB2 -b 921600 --imap lfcrlf
 ```
 
+*On Windows, we recommend to use [PuTTY](https://www.putty.org/) to connect to serial ports.*
+*Select "Serial" as "Connection type", put the COM port in the "Serial line" text field, and set "Speed" to 921600.*
+*To find out what serial ports are available, you can open Device Manager and all connected serial ports are listed under "Ports (COM & LPT)" section.*
+
 When running the `sonata_simple_demo.uf2`, you should see the following console output as well as some flashing LEDs and LCD activity.
+This UART output only gets printed once, so you may need to press the reset button (SW5) to see the output if you attach your console after programming.
 
 ```
 bootloader: Loading software from flash...

exercises/README.md

@@ -16,4 +16,4 @@ xmake -P exercises
 
 ## Exercises
 
-Currently, there is one exercise: [Hardware Access Control](./hardware_access_control/README.md)
+Currently, there is one exercise: [Hardware Access Control](./hardware_access_control/)

exercises/hardware_access_control/README.md

@@ -8,7 +8,7 @@ If you haven't already, pop yourself up to the '[building the exercises][]' sect
 
 [Building the Exercises]: ../README.md#building-the-exercises
 
-This exercise we utilise the compartmentalisation available in CHERIoT RTOS to control access to a hardware peripheral: the very security critical LEDs.
+In this exercise we utilise the compartmentalisation available in CHERIoT RTOS to control access to a hardware peripheral: the LEDs.
 
 For this exercise, when the [`xmake.lua`][] build file is mentioned `exercises/hardware_access_control/xmake.lua` is being referred to.
 
@@ -98,7 +98,6 @@ hardware_access_control/part_2/led_walk_dynamic.cc:34 Assertion failure in start
 Failed to toggle an LED
 ```
 
-
 ## Part 3
 
 This is great and all, but how do we stop a compartment bypassing `gpio_access` and using `MMIO_CAPABILITY` directly?
@@ -112,7 +111,7 @@ To automate checking this report, we can use `cheriot-audit` which should alread
 You do this with a language called [Rego][], but don't worry you won't have to learn it for this exercise.
 There are some pre-written rules in the [`gpio_access.rego`] module.
 Let's first look at `only_gpio_access_has_access`.
-It uses `mmio_allow_list` from `cheriot-audit`'s included compartment package to check only the `gpio_access` compartment has access to the GPIO MMIOs.
+It uses `mmio_allow_list` from the compartment package included in `cheriot-audit` to check that only the `gpio_access` compartment has access to the GPIO MMIOs.
 If we run this on the part 2 firmware image's JSON report, it will return true.
 However, when run against the part 1 firmware image's report it will return false, because the `blinky_raw` and `led_walk_raw` are not in the allow list.
 
@@ -147,7 +146,7 @@ check_gpio_access whitelisted_compartments_only \
 The above should return true as both compartments are in the allow list.
 Try removing one of the compartments from the allow list given to `compartment_allow_list` in [`gpio_access.rego`][] and check the result of the above command is no longer true.
 
-One can browse the other functions available as part of the `cheriot-audit`'s included compartment package in [`cheriot-audit`'s readme][compartment package].
+One can browse the other functions available as part of the compartment package in [`cheriot-audit`'s readme][compartment package].
 
 [compartment package]: https://github.com/CHERIoT-Platform/cheriot-audit/blob/main/README.md#the-compartment-package
 

scripts/run_sim.sh

@@ -2,5 +2,5 @@
 # Copyright lowRISC Contributors.
 # SPDX-License-Identifier: Apache-2.0
 
-sonata_simulator -E $SONATA_SIM_BOOT_STUB -E $1
+sonata-simulator -E $SONATA_SIM_BOOT_STUB -E $1