Add more example build stuff

doc/guide/building-examples.md

@@ -1,9 +1,28 @@
 # Building Examples
 
-You will need a copy of [CHERIoT RTOS](https://github.com/microsoft/cheriot-rtos/tree/main) for this section:
+The following contains some simple examples you can build for the Sonata board. Once you've got these builds working, you can easily add more features to the example code.
+
+## Additional Toolchain Setup
+
+### SRecord Tools
+
+The makefile assumes srecord tools, which you can install with:
+
+```bash
+sudo apt install srecord
+```
+
+### CHERIoT RTOS SDK Installation
+
+You will need a copy of [CHERIoT RTOS](https://github.com/microsoft/cheriot-rtos/tree/main) for this section.
+
+On Windows you may need to set `git config --global core.symlinks true` *before* cloning the repository.
+
+Clone the repository somewhere, *not* into the root of the `sonata-system` directory, but at the same level as `sonata-system`:
 
 ```sh
-git clone https://github.com/microsoft/cheriot-rtos.git
+cd ..
+git clone --recurse https://github.com/microsoft/cheriot-rtos.git
 ```
 
 **IMPORTANT**: Set these two environmental variables. The first should point to the llvm build you did in the previous part,
@@ -14,10 +33,13 @@ export CHERIOT_LLVM_ROOT=/path/to/cheriot-llvm/bin
 export CHERIOT_RTOS_SDK=/path/to/cheriot-rtos/sdk
 ```
 
+> WARNING: The path to `/path/to/cheriot-llvm/bin` should point to the *build* directory you created, not just the root checked out `cheriot-llvm` directory.
+> The path will look something like: `~/llvm-tools/cheriot-llvm/builds/cheriot-llvm/bin`
+
 The following assume you have run the `source .venv/bin/activate` command in the terminal you are using, and you are
 currently at the root directory of your local `sonata-system` git repository.
 
-## Capability sanity check
+## Example #1: Capability sanity check
 
 ### Building Example
 
@@ -27,14 +49,23 @@ make
 popd
 ```
 
-This should produce XXXXXX
+This should produce `boot.bin` and `boot.elf` which we can program with OpenOCD into the target.
+Other output files generated can be used with the FPGA splicing option (which integrates the code into the bitstream).
 
 > HINT: If you don't have the environmental variables defined, you can also pass the paths to the make command itself:
 > `make CHERIOT_LLVM_ROOT=/path/to/cheriot-llvm/bin CHERIOT_RTOS_SDK=/path/to/cheriot-rtos/sdk`
 
 ### Programming Software
 
->TODO FINISH THIS
+The following will use OpenOCD to program the code you just compiled:
+
+```bash
+
+```
+> TODO - what is OpenOCD command & what else is needed?
+
+
+> TODO - the following should live somewhere else, move it there:
 
 There are four ways of programming the software: