mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-15 08:30:02 +00:00
94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# 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
|
|
|
|
## Dependencies
|
|
There's some Python scripts to help deal with firmware signing. Ensure the following python packages are available in your environment: `pycryptodome` (signing - PEM read), `cryptography` (signing - x509 read), `pynacl` (signing - ed25519 signatures). If you plan on doing USB firmware updates, you'll also need `progressbar2` (updates), `pyusb` (updates).
|
|
|
|
## 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.
|