The Xous microkernel
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
bunnie f2e1a89f13
Merge pull request #343 from eupn/patch-1
4 days ago
.cargo leaves some breadcrumbs to revisit lto issues and alternative loaders 3 months ago
.github/workflows bump minimum toolchain requirement 8 months ago
.vscode usb-device-xous: implement primitive for apps-based block devices 2 months ago
LICENSES creating LICENSES directory 2 years ago
api bump versions for kernel interface changes 1 week ago
apps WIP: #334 7 days ago
devkey beginnings of image signing 2 years ago
docs loader: move the kernel stack to kernel region 1 month ago
emulation emulation: ticktimer: fix higher bits of ticktimer 2 months ago
imports bump versions for kernel interface changes 1 week ago
kernel bump versions for kernel interface changes 1 week ago
libs bump versions for kernel interface changes 1 week ago
loader cleanup a warning when debug is not turned on 1 week ago
locales Completes the tool 5 months ago
precursors match latest soc_csr candidate 1 week ago
services fix #337 7 days ago
svd2repl Revert "renode: remove custom LiteX_Timer_32" 2 months ago
svd2utra bump versions to cleanup sync issue 2 weeks ago
tools fix alignment edge case (take 2) 4 days ago
utralib commit lockfiles and verifiers 2 weeks ago
xous-ipc bump versions for kernel interface changes 1 week ago
xous-rs bump versions for kernel interface changes 1 week ago
xtask prep for transition to XIP for app-images 7 days ago
.gitattributes Completes the tool 5 months ago
.gitignore v2p table shouldn't be in the index 3 months ago xous: remove `xous::xous_main` macro 10 months ago initial commit 3 years ago CONTRIBUTRING: Update license link 11 months ago
Cargo.lock remove implementations from the set 1 week ago
Cargo.toml remove implementations from the set 1 week ago add dpad hosted mode mapping 1 week ago clean up release notes 2 years ago bump release notes 7 days ago refactor paths to use xpack instead of sifive toolchain 1 month ago remove implementations from the set 1 week ago
rustfmt.toml finalize formatting run 2 years ago

Xous Core

Core files for the Xous microkernel operating system.

You might find this wiki handy, as well as the Xous Book.

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


  • Xous requires its own Rust target, riscv32imac-unknown-xous-elf. If you run cargo xtask from the command line, you should be prompted to install the target automatically if it does not already exist.
  • You may need to remove the target/ directory before building, if rustc continues to behave like it can't find the xous target even after it is installed.
  • If you plan on doing USB firmware updates, you'll need progressbar2 (updates) and pyusb (updates). Note that pyusb has name space conflicts with similarly named packages, so if updates aren't working you may need to create a venv or uninstall conflicting packages.
  • If you are doing development on the digital signatures with the Python helper scripts, you will need: pycryptodome (signing - PEM read), cryptography (signing - x509 read), pynacl (signing - ed25519 signatures) (most users won't need this).
  • Some system packages are needed, which can be installed with sudo apt install libssl-dev libxkbcommon-dev or similar
  • If you receive an error about feature resolver is required, try installing a newer version of rustc and cargo via rustup Verification

By default the xtask resolver runs a check to confirm that your local files match the ones referenced in For a handful of core crates, the build preferentially runs from what is on, so local changes have no effect until they are pushed as an update to an existing crate. If you see an error complaining about local source files not being published, make sure you have the correct patches in place in your top level Cargo.toml file, and bypass the check with --no-verify.

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 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:

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 as the preferred emulator, because it is easy to extend the hardware peripherals without recompiling the entire emulator.

Download Renode and ensure it is in your path. For now, you need to download the nightly build, until DecodedOperation is included in the release.

Then, build Xous:

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:

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 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:

cargo xtask app-image

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/; 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 and utralib/ 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.


This project is funded through the NGI0 PET Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825310.

NLnet foundation logo NGI0 logo