Tweak the getting started guide.

doc/getting-started.md

@@ -1,14 +1,18 @@
 # Getting started guide
 
-This guide tells you how to prepare your environment before working with Sonata.
-The guide is especially useful to follow in advance of organized workshops or events so any issues can be sorted in advance of the day.
+This guide tells you how to get started with the Sonata board.
 If you have any issues in following this guide please contact the Sunburst Team at [[email protected]](mailto:[email protected]).
 
 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.
 
+You will also need to setup the Sonata board itself with the latest release.
+Read the [updating the sonata system guide](https://lowrisc.github.io/sonata-system/doc/guide/updating-system.html) for instructions on how to do this.
+You only need to follow the first two steps listed there.
+The 'Building examples' step requires the environment setup detailed below.
+
 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).
 
@@ -105,11 +109,14 @@ Nix can and will build everything from source if it can't find a cached version,
 
 Clone the sonata software repository, *making sure to recursively clone submodules as well*, then navigate into it.
 ```sh
-git clone --recurse-submodule \
+git clone --branch v0.4 \
+	 --recurse-submodule \
     https://github.com/lowRISC/sonata-software.git
 cd sonata-software
 ```
 
+Note a particular branch is specified, this must match your release, the release notes will tell you which branch you should use.
+
 Enter the nix development development environment if you haven't already.
 *Note that because we are in the repository we don't need to provide any arguments to `nix develop`.*
 ```sh
@@ -243,6 +250,8 @@ warning: ./cheriot-rtos/sdk/xmake.lua:116: unknown language value 'c2x', it may
 warning: add -v for getting more warnings ..
 ```
 
+With a successful software build you can now try [running software](./guide/running-software.md)
+
 ### Debug logs
 
 If you want debug logs from the RTOS, configure your build with the following additional options.

doc/guide/running-software.md

@@ -1,36 +1,7 @@
 # Running Sonata Software
 
-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 need to enter the environment that includes the simulator:
-
-```sh
-nix develop .#env-with-sim
-```
-
-[getting started guide]: ../getting-started.md
-
-This will pull the simulator into your path as `sonata-simulator`.
-There's a convenience script, `scripts/run_sim.sh`, for calling 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.
-
-```sh
-./scripts/run_sim.sh build/cheriot/cheriot/release/sonata_simple_demo
-```
-
-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:
-
-```sh
-tail -f uart0.log
-```
+You can either run software [on the sonata FPGA board](#running-on-the-sonata-fpga) or [in the sonata simulator](#running-in-the-simulator).
+We recommend you focus on the FPGA as you get started and return to the simulator if you think you would find it useful later.
 
 ## Running on the Sonata FPGA
 
@@ -70,3 +41,32 @@ bootloader: Loading software from flash...
 bootloader: Booting into program, hopefully.
 Led Walk Raw: Look pretty LEDs!
 ```
+
+## 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 need to enter the environment that includes the simulator:
+
+```sh
+nix develop .#env-with-sim
+```
+
+[getting started guide]: ../getting-started.md
+
+This will pull the simulator into your path as `sonata-simulator`.
+There's a convenience script, `scripts/run_sim.sh`, for calling 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.
+
+```sh
+./scripts/run_sim.sh build/cheriot/cheriot/release/sonata_simple_demo
+```
+
+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:
+
+```sh
+tail -f uart0.log
+```