From 2e55ecd6dcf98fdb280fc90e4e806396c9325d8f Mon Sep 17 00:00:00 2001 From: Greg Chadwick Date: Wed, 16 Oct 2024 13:05:47 +0100 Subject: [PATCH] Tweak the getting started guide. - Add an explicit link to the sonata-system documentation on setting up the actual board - Specifically check out a v0.4 release branch rather than top of main - Emphasise use of FPGA over the simulator for getting started --- doc/getting-started.md | 15 +++++++-- doc/guide/running-software.md | 62 +++++++++++++++++------------------ 2 files changed, 43 insertions(+), 34 deletions(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 9960189..8194b64 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -1,7 +1,6 @@ # 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 [info@lowrisc.org](mailto:info@lowrisc.org). The Sonata software build environment can be setup under Windows, macOS and Linux. @@ -9,6 +8,11 @@ The Sonata software build environment can be setup under Windows, macOS and Linu 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. diff --git a/doc/guide/running-software.md b/doc/guide/running-software.md index 6b46dd1..3c0a63f 100644 --- a/doc/guide/running-software.md +++ b/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 Ctrl+C 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 Ctrl+C 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 +```