Doc updates

SUMMARY.md

@@ -8,7 +8,6 @@
   - [Building Examples](doc/guide/building-examples.md)
 
 - [Developer Guide](doc/dev/developing.md)
-  - [Debugger Support](doc/dev/sw-debug.md)
   - [Programming Sonata Software](doc/dev/sw-programming.md)
   - [Reference Manual for Sonata Core](doc/dev/ref-manual.md)
       - [Ibex](doc/ip/ibex.md)
@@ -20,21 +19,12 @@
       - [SPI host](doc/ip/spi.md)
       - [USB device](doc/ip/usb.md)
       - [HyperRAM](doc/ip/ram.md)
-      - [DMA](doc/ip/dma.md)
-      - [ADC](doc/ip/adc.md)
       - [PWM](doc/ip/pwm.md)
       - [PLIC](doc/ip/plic.md)
-      - [Pinmux](doc/ip/pinmux.md)
   - [FPGA Development](doc/dev/fpga-development.md)
       - [FPGA Programming](doc/dev/fpga-programming.md)
   - [Simulation Environment](doc/dev/simulation.md)
   - [Building Documentation](doc/dev/building-doc.md)
 
 - [Sonata Board](doc/architecture/board.md)
-  - [DIP Switch Settings]()
-  - [Updating Firmware]()
-  - [Building RP2040 Firmware]()
-  - [Schematics]()
-
-
 

doc/architecture/board.md

@@ -80,4 +80,25 @@ This includes the entire design sources, available currently in Altium, with a K
 
 ## Schematic Link
 
-You can find a [direct link to the schematics](https://github.com/newaetech/sonata-pcb/blob/main/sonata-schematics-r08.pdf) for your reading pleasure.
+You can find a [direct link to the schematics](https://github.com/newaetech/sonata-pcb/blob/main/sonata-schematics-r08.pdf) for your reading pleasure.
+
+## Default DIP switch settings
+
+We recommend the following default state for the dipswitches:
+- On the front:
+    - SW3 "Bitstream": 2
+    - SW7 "SW App": 1
+    - SW4 "US[0-7]": all set to off
+    - SW6 : all set to off
+- On the back:
+    - SW1 : all set to on
+    - SW2 : 1-6 set to on and 7-8 set to off
+
+## RP2040 firmware
+
+You can build new RP2040 firmware (or find release UF2 files) from the [Sonata RP2040 repository](https://github.com/newaetech/sonata-rp2040).
+
+With that UF2 file you can now update your firmware by holding down SW9, labelled "RP2040 Boot".
+While holding this button plug your Sonata board in using the main USB.
+A drive called `RPI-RP2` should now appear which you can drag the UF2 file onto.
+

doc/dev/fpga-development.md

@@ -1,5 +1,8 @@
 # FPGA development
 
+This page is only for if you want to make changes to the RTL of the bitstream.
+In most cases you can just use the standard bitstream published in the [releases](https://github.com/lowRISC/sonata-system/releases).
+
 ## Dependencies
 
 - [Vivado](https://www.xilinx.com/support/download.html)
@@ -13,13 +16,14 @@ The Sonata bitstream is generated using Vivado.
 
 To build the bitstream, make sure to [build the software](../guide/building-examples.md) to create the correct SRAM image.
 Then run this command:
+
 ```sh
 fusesoc --cores-root=. run --target=synth --setup --build lowrisc:sonata:system
 ```
 
-
-### Programming the Bitstream
+You can also manually set the initial value of the SRAM, for example:
 
 ```sh
-openFPGALoader -c ft4232 build/lowrisc_sonata_system_0/synth-vivado/lowrisc_sonata_system_0.bit
+fusesoc --cores-root=. run --target=synth --setup --build lowrisc:sonata:system --SRAMInitFile=$PWD/sw/cheri/build/tests/uart_check.vmem
 ```
+

doc/guide/building-examples.md

@@ -2,19 +2,47 @@
 
 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
+## Using our template
+
+Please go to the [Sonata software repository](https://github.com/lowRISC/sonata-software) and build a full application from there.
+Inside your setup you should simply be able to build it like this:
+
+```sh
+git clone --recurse-submodule \
+    https://github.com/lowRISC/sonata-software.git
+cd sonata-software
+xmake config --board=sonata
+xmake build
+```
+
+After running this you should see the build run to completion and report success, the critical lines indicating a successful build are (note output size may differ):
+
+```sh
+Converted to uf2, output size: 74752, start address: 0x101000
+Wrote 74752 bytes to build/cheriot/cheriot/release/sonata_simple_demo.uf2
+[100%]: build ok, spent 6.827s
+```
+
+You can drag and drop this UF2 file into the `SONATA` drive to program the firmware.
+
+## Baremetal examples
+
+This is only for advanced users.
+If you want to build the baremetal examples in the Sonata repo you can follow these instructions.
+
+### Additional Toolchain Setup
 
 Besides the compiler, there are a few more features the example code depends on:
 
-### SRecord Tools
+#### SRecord Tools
 
 The makefile assumes srecord tools, which you can install with:
 
 ```bash
 sudo apt install srecord
 ```
 
-### CHERIoT RTOS SDK Installation
+#### CHERIoT RTOS SDK Installation
 
 You will need a copy of [CHERIoT RTOS](https://github.com/microsoft/cheriot-rtos/tree/main) for this section.
 
@@ -41,7 +69,7 @@ export CHERIOT_RTOS_SDK=/path/to/cheriot-rtos/sdk
 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.
 
-## Building All Examples
+### Building Baremetal Examples
 
 > TODO: We should tell them where to get the SW. And especially point out it must match
 > the bitstream version again (all downloaded at one point).
@@ -72,4 +100,4 @@ You can load software onto the FPGA over USB (JTAG) using:
 ./util/mem_helper.sh load_program -e sw/cheri/build/tests/spi_test
 ```
 There are actually four different ways of loading the program - we normally use JTAG for development, but you can also
-program it into the serial flash device on the board. See the page [Programming the Sonata Software](../dev/sw-programming.md).
+program it into the serial flash device on the board. See the page [Programming the Sonata Software](../dev/sw-programming.md).

doc/guide/fpga-update.md

@@ -24,15 +24,11 @@ The LEDs besides the switch show the current image selected as well for confirma
 In case you have trouble with the board, you can quickly switch to Slot 1 to confirm the LCD, LEDs, and similar are all functioning correctly. However there is no problem
 to overwrite any of the slots, the default image can easily be copied back if you want later.
 
-> TODO - do we want to recommend a different slot?
-
 ## Drag & Drop Programming
 
-> TODO: Where is this bitstream located? Assume it's built by CI, or do we have a release version?
-
 To program the Sonata bitstream:
 
-1. Download `lowrisc_sonata_system_0.bit` from THEBESTURL.COM/lowrisc_sonata_system_0.bit
+1. Download the bitstream from [our releases](https://github.com/lowRISC/sonata-system/releases)
 2. Select slot 2 using switch SW3 (`Bitstream`)
 3. Plug in Sonata board. You should see a SONATA drive (see troubleshooting section if unsure).
 4. Drag the updated `.bit` file and wait for the copy to complete (on Linux note the copy command may return immediately, so you need to wait until it's done.)

doc/guide/toolchain-setup.md

@@ -6,7 +6,15 @@ special toolchain from source. Luckily, it should be easy if you follow our simp
 If building on Windows, the following instructions have also been confirmed to work with WSL2 with the exception of `edalize` and `fusesoc`,
 which *are not required for software development*.
 
-## Sonata Setup
+## Nix Setup
+
+We recommend using Nix for your setup.
+You can find instructions on how to do this in the [Sonata software repository](https://github.com/lowRISC/sonata-software).
+This also includes a GitHub Codespaces that sets a whole environment up for you in the browser.
+
+## Manual Setup
+
+### Sonata Setup
 
 ```sh
 git clone https://github.com/lowRISC/sonata-system
@@ -31,7 +39,7 @@ cd sonata-system
 source .venv/bin/activate
 ```
 
-## Building Toolchain
+### Building Toolchain
 
 To build the toolchain, you'll need: