diff --git a/README.md b/README.md index 0dde3e898..78a2f501a 100644 --- a/README.md +++ b/README.md @@ -12,62 +12,78 @@ from source. It consists of the following projects: * **emulation**: Renode scripts used to emulate Xous * **xous-rs**: userspace library -## Generating an image +## Quickstart using Hosted Mode -You can build all Xous packages by running: +You can try out Xous in a "hosted mode" wherein programs are compiled +for your native platform and are run locally as processes within your +current operating system. System calls are replaced with network calls +to a kernel that simply shuffles messages around. + +Xous uses the [xtask](https://github.com/matklad/cargo-xtask/) convention, +where various complex build commands are stored under `cargo xtask`. +This allows for us to create arbitrarily complex build sequences +without resorting to `make` (which is platform-dependent), +`sh` (which requires a lot of external tooling), or another build +system. + +To build a set of sample programs and run them all using the +kernel for communication, clone this repository and run: ```sh -$ rustup target add riscv32imac-unknown-none-elf -$ cargo build --target riscv32imac-unknown-none-elf -$ cd kernel -$ cargo build -p kernel --target riscv32imac-unknown-none-elf -$ cd .. -$ cd loader -$ cargo build -p loader --target riscv32imac-unknown-none-elf -$ cd .. +cargo xtask run ``` -This will compile all runtime packages for `riscv32imac-unknown-none-elf`. -Note that the kernel and loader must currently be built separately, due -to the fact that they have custom linker scripts. +This will build several servers and a "shell" program to control them +all. Most notably, a `graphics-server` will appear and kernel messages +will begin scrolling in your terminal. -These need to be packaged into a loadable binary. You can generate such -a binary by running the following: +## Quickstart using an emulator + +Xous uses [Renode](https://renode.io/) as the preferred emulator, because +it is easy to extend the hardware peripherals without recompiling the +entire emulator. + +[Download Renode](https://renode.io/#downloads) and ensure it is in your path. +Then, build Xous: ```sh -$ cargo run -p tools --bin create-image -- \ - --csv emulation/csr.csv \ - --kernel kernel/target/riscv32imac-unknown-none-elf/debug/kernel \ - --init target/riscv32imac-unknown-none-elf/debug/shell \ - target/args.bin +rustup target add riscv32imac-unknown-none-elf +cargo xtask renode-image ``` -## Targeting Real Hardware +This will compile everything in `release` mode for RISC-V, compile the tools +require to package it all up, then create an image file. -The following files need manual adjustment: - -* emulation/csr.csv should map to the csr.csv of the final SoC -* examples/graphics-server/src/backend/betrusted.rs needs a correct address for the "control" data structure (based on csr.csv) -* kernel/src/debug.rs:7 needs a correct UART base, based on csr.csv -* loader/src/debug.rs:31 needs a correct UART base, based on csr.csv -* kernel/src/main.rs:67 needs a corret UART base, based on csr.csv - -Create the loader.bin from the .elf. `objcopy` adds several hundred megabytes of zero at the end of `loader.bin` so just -take the first 64kiB, which is the exact size allocated for it anyways in hardware. The final loadable image is created by -`cat`ing the loader and the kernel together. +Finally, run Renode and specify the `xous-release.resc` REnode SCript: +```sh +renode emulation/xous-release.resc ``` -riscv64-unknown-elf-objcopy loader/target/riscv32imac-unknown-none-elf/release/loader -O binary loader_raw.bin -dd if=loader_raw.bin of=loader.bin bs=1024 count=64 -cat loader.bin target/args.bin > xous.img + +Renode will start emulation automatically, and will run the same set of programs +as in "Hosted mode". + +## Generating a hardware image + +To build for real hardware, you must specify an `.svd` file. This +file is generated by the SoC build process and describes a single +Betrusted core. These addresses will change as hardware is modified, +so if you distribute a modified Betrusted core, you should be sure +to distribute the `.svd` file. + +An example file may be found under `svd2utra/`, but this is probably +out of date and won't work with your device. + +Pass this `.svd` file to the `hw-image` `xtask` command: + +```sh +cargo xtask hw-image svd2utra/examples/soc.svd ``` +This will compile all runtime packages for `riscv32imac-unknown-none-elf`, and +will generate a release image under the `target/` directory, which will be printed +on the output. + The image should be written to location 0x2050_0000 (SPI ROM offset 0x50_0000), using the `provision-xous.sh` script inside [betrusted-scripts](https://github.com/betrusted-io/betrusted-scripts/blob/master/provision-xous.sh) running on a Betrusted provisioning harness, that is a Raspberry Pi 4 with the appropriate debug hat attached, and the Precursor hardware plugged into the debug hat. You can also check out the `dvt-hardware` branch for the WIP integration of all the above commands. - -## Try It Out on a Desktop - -Clone this repository, and run - -`cargo xtask run` diff --git a/emulation/boot.resc b/emulation/xous-release.resc similarity index 100% rename from emulation/boot.resc rename to emulation/xous-release.resc