# Xous Core

Core files for the Xous microkernel operating system.

You might find this [collection of Xous documentation](https://github.com/betrusted-io/betrusted-wiki/wiki) handy.

This repository contains everything necessary to build the Xous kernel
from source.  It consists of the following projects:

* **kernel**: core memory manager, irq manager, and syscallhandler
* **loader**: initial loader used to start the kernel
* **tools**: programs used to construct a final boot image
* **docs**: documentation on various aspects of Xous
* **emulation**: Renode scripts used to emulate Xous
* **xous-rs**: userspace library

## 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.

## 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
rustup target add riscv32imac-unknown-none-elf
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.

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.