[doc] Updates to reflect current recommended setup and flows

SUMMARY.md

@@ -5,11 +5,11 @@
 - [Getting started](doc/guide/getting-started.md)
   - [Reloading the RP2040](doc/guide/rp2040-update.md)
   - [Reloading the FPGA Image](doc/guide/fpga-update.md)
-  - [Software Toolchain Setup](doc/guide/toolchain-setup.md)
   - [Building Examples](doc/guide/building-examples.md)
 
 - [Developer Guide](doc/dev/developing.md)
   - [Programming Sonata Software](doc/dev/sw-programming.md)
+  - [Software Toolchain Setup](doc/dev/toolchain-setup.md)
   - [Reference Manual for Sonata Core](doc/dev/ref-manual.md)
       - [Ibex](doc/ip/ibex.md)
       - [Debug module](doc/ip/dm.md)

doc/dev/fpga-development.md

@@ -14,7 +14,7 @@ The Sonata bitstream is generated using Vivado.
 
 ## Bitstream
 
-To build the bitstream, make sure to [build the software](../guide/building-examples.md) to create the correct SRAM image.
+To build the bitstream, make sure to [build the baremetal software](../guide/building-examples.md#baremetal-examples) to create the correct SRAM image.
 Then run this command:
 
 ```sh

doc/guide/toolchain-setup.md → doc/dev/toolchain-setup.md

@@ -1,19 +1,13 @@
 # Setting up the Toolchain for Software Development
 
+This is **only for advanced users** who wish to build their own toolchain.
+
 All the special CHERIoT goodness comes with its own compiler that understands how to use it. For this reason you'll need to build a
 special toolchain from source. Luckily, it should be easy if you follow our simple instructions.
 
 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*.
 
-## 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

doc/guide/building-examples.md

@@ -46,6 +46,11 @@ Select "Serial" as "Connection type", put the COM port in the "Serial line" text
 This is **only for advanced users**.
 If you want to build the baremetal examples in the Sonata repo you can follow these instructions.
 
+First [setup a toolchain](../dev/toolchain-setup.md).
+Note none of the current Nix environments have exactly the correct set of dependencies to build the baremetal examples.
+This will change but for the time being you either need to alter a Nix environment (either add cmake to the sonata-software environment or the CHERIoT toolchain to the sonata-system environment) or setup a toolchain outside Nix.
+
+
 ### Additional Toolchain Setup
 
 Besides the compiler, there are a few more features the example code depends on.

doc/guide/fpga-update.md

@@ -1,5 +1,10 @@
 # Reloading the FPGA Image
 
+*We have seen some issues with the standard FPGA loading flow using the RP2040.
+Until these are fixed we recommend using a special version of the RP2040 firmware that has the FPGA's bitstream pre-built into it.
+This is named `tmp_rpi_rp2_part1_v0.2.uf2` in the [current release](https://github.com/lowRISC/sonata-system/releases/tag/v0.2).
+When using that firmware you do not need to follow the instructions below.*
+
 The first thing you should do before building the firmware is to get the latest version of the FPGA image, called the "bitstream". This contains the configuration
 for the microcontroller core & peripherals. The "release version" of the bitstream *must* match the
 configuration you use to build the software, as if the bitstream is a different version than what

doc/guide/getting-started.md

@@ -6,16 +6,16 @@ default setups.
 
 > The Sonata board is a prototype board and is under active development.
 > This documentation is in the process of being updated.
-> We will be improving the getting started guide soon to allow for an easier way with developing against the boards.
+> Some parts of the documentation may be out of date or otherwise confusing because of this.
+> This getting started material and the documentation in the [sonata-software](https://www.github.com/lowrisc/sonata-software) repository provides the best material for new users to focus on.
 
 ## Getting Started Steps
 
 To get started with your Sonata board, there are three steps you'll need to do. First, head to
 the [Sonata System Release Page](https://github.com/lowRISC/sonata-system/releases/) where you'll find the latest releases.
 
-0. [Program the RP2040 With the Latest](rp2040-update.md) firmware to get any bug fixes by entering bootloader mode & dragging the `rpi_rp2_v0.XX.uf2`.
-1. [Get the latest FPGA image](fpga-update.md) that corresponds with the software you are building. This requires you to just drag the new `.bit` file onto the SONATA drive that comes up when you plug in the board to your computer.
-2. [Install the software toolchain](toolchain-setup.md).
+1. [Program the RP2040 With the latest](rp2040-update.md) firmware to get any bug fixes by entering bootloader mode & dragging the `rpi_rp2_v0.XX.uf2`.
+2. [Get the latest FPGA image](fpga-update.md) that corresponds with the software you are building. This requires you to just drag the new `.bit` file onto the SONATA drive that comes up when you plug in the board to your computer.
 3. [Build the example code](building-examples.md) and download to the soft-core you loaded in step 1.
 
 Follow along each of the following sections to complete these tasks.

doc/guide/rp2040-update.md

@@ -1,5 +1,10 @@
 # Reloading the RP2040 USB Controller
 
+*We have seen some issues with the standard FPGA loading flow using the RP2040.
+Until these are fixed we recommend using a special version of the RP2040 firmware that has the FPGA's bitstream pre-built into it.
+This is named `tmp_rpi_rp2_part1_v0.2.uf2` in the [current release](https://github.com/lowRISC/sonata-system/releases/tag/v0.2).
+This will be used in place of the `rpi_rp2_v0.X.uf2` file referred to below.*
+
 Before plugging in your Sonata board, hold down the SW9 labelled "RP2040 Boot", and while holding this button plug your board into your laptop using the Main USB.
 
 A drive called RPI-RP2 should pop up on your computer and drag `rpi_rp2_v0.X.uf2` into it.
@@ -9,4 +14,4 @@ This drive should automatically dismount once the file is transferred and remoun
 
 Currently the RP2040 firmware is available from the [Sonata Systems](https://github.com/lowRISC/sonata-system/releases) releases, which ensures your RP2040 firmware matches the Sonata FPGA and firmware expectations.
 
-The source & latest release for the RP2040 are also found on the [Sonata RP2040 repo](https://github.com/newaetech/sonata-rp2040/releases).
+The source & latest release for the RP2040 are also found on the [Sonata RP2040 repo](https://github.com/newaetech/sonata-rp2040/releases).