README: rewrite to document xtask

The `xtask` command has come a long way, and is the preferred method of
building this repositry. Document the fun ways it can be used.

Signed-off-by: Sean Cross <sean@xobs.io>

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`