helps to save the file

README-precursor.md

@@ -0,0 +1,112 @@
+# Getting started with Precursor
+
+## Quickstart using Hosted Mode
+
+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
+cargo xtask run
+```
+
+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.
+
+### Hosted Mode UI navigation
+
+| Precursor           | Host        |
+| ------------------- | ----------- |
+| D-pad middle button | Home        |
+| D-pad up            | up arrow    |
+| D-pad down          | down arrow  |
+| D-pad left          | left arrow  |
+| D-pad right         | right arrow |
+
+
+## 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.
+
+Due to a breaking change in Renode, this codebase is only compatible with Renode equal to or later than `1.15.2.7965 （e6e79aad-202408180425)`
+
+[Download Renode](https://renode.io/#downloads) and ensure it is in your path.
+For now, you need to [download the nightly build](https://dl.antmicro.com/projects/renode/builds/),
+until `DecodedOperation` is included in the release.
+
+Then, build Xous:
+
+```sh
+cargo xtask renode-image
+```
+
+This will compile everything in `release` mode for RISC-V, compile the tools
+require to package it all up, then create an image file.
+
+Finally, run Renode and specify the `xous-release.resc` REnode SCript:
+
+```sh
+renode emulation/xous-release.resc
+```
+
+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.
+
+The [UTRA](./utralib/README.md) abstracts the details of the register
+locations, by wrapping them in logical names that don't change.
+For Precursor, the SVD files are tracked inside `utralib/precursor/soc-<gitref>.svd`.
+Since each soc.svd can potentially change with a git reference, a gitref
+is coded into the filename by convention.
+
+Generally, one can create an image for hardware using the following command:
+
+```sh
+cargo xtask app-image-xip
+```
+
+And it will pull from the default soc.svd configuration.
+
+The currently selected config is set by the constant `PRECURSOR_SOC_VERSION`
+in [xtask/src/main.rs](./xtask/src/main.rs); it is one of the first constants
+near the top.
+
+If you have built your own custom soc.svd file, the most convenient way to update
+to this is to simply replace the file referenced in the default with yours,
+and then run `cargo build` inside the `utralib` directory (not in the Xous
+root -- the `build` command must happen inside the directory to force a
+regeneration of the generated UTRA bindings). This will likely result
+in a complaint when you run `xtask` that your local tree does not match what
+is checked into `git`; if you are building from your own configuration,
+that is correct, and thus you should add `--no-verify` to your `xtask` command
+to suppress the check.
+
+Note that adding a full extra custom gitrev is more involved, it involves
+editing the [utralib/Cargo.toml](./utralib/Cargo.toml) and [utralib/build.rs](./utralib/build.rs)
+to reference your new artifact as a brand new feature flag.
+
+The resulting images are in your target directory (typically `target/riscv32imac-unknown-xous-elf/release/`)
+with the names `xous.img` (for the kernel) and `loader.bin` (for its bootloader). The corresponding
+gateware is in `precursors/soc_csr-<gitref>.bin`. These can be written to your
+device by following the [update guide](https://github.com/betrusted-io/betrusted-wiki/wiki/Updating-Your-Device).