Xous SDK (pinned for betrusted transpilation)
Find a file
bunnie 49e526f60b
simplify erased key reporting on debug
this reduces the amount of prints for a key range being
erased so if the debug flags are on boot isn't delayed
while the debug prints. instead, a total tally of the
erased keys for a key range is printed.
2025-12-19 01:12:57 +08:00
.cargo
.github/workflows extend CI coverage to include pull requests targeting main 2025-11-17 17:37:10 +08:00
.vscode
api commit for version bump 2025-12-16 02:02:37 +08:00
apps commit for version bump 2025-12-16 02:02:37 +08:00
apps-baosec fix hosted mode 2025-11-30 21:56:32 +08:00
apps-dabao commit for version bump 2025-12-16 02:02:37 +08:00
bao1x-boot move the backup region check below IRQ handler setup 2025-12-18 03:56:18 +08:00
baremetal update two spots where the /2 on perclk was missed 2025-12-18 02:22:02 +08:00
devkey
docs add API calls for debugging kernel under baochip targets 2025-12-09 16:19:04 +08:00
emulation
imports commit for version bump 2025-12-16 02:02:37 +08:00
kernel commit for version bump 2025-12-16 02:02:37 +08:00
libs simplify erased key reporting on debug 2025-12-19 01:12:57 +08:00
LICENSES Move license file to top level so github can detect it 2023-11-16 20:59:16 -08:00
loader make the init check on erase secret pass-forward more narrowly scope 2025-12-18 03:57:04 +08:00
locales
planning commit for version bump 2025-12-16 02:02:37 +08:00
precursors
services quite down a debug statement 2025-12-18 02:21:20 +08:00
signing bump pins on the signing crate 2025-12-18 02:21:38 +08:00
svd2repl
svd2utra
tools remove the developer function from the function code list 2025-12-19 01:09:44 +08:00
tools-bao update readme to reflect changes to monitor flags 2025-11-06 14:53:09 +09:00
utralib fix UTRA to include some missing peripheral ranges 2025-11-25 19:05:05 +08:00
xous-ipc commit for version bump 2025-12-16 02:02:37 +08:00
xous-rs commit for version bump 2025-12-16 02:02:37 +08:00
xtask bump the pins on the verifiers - forgot to do this earlier 2025-12-18 02:20:22 +08:00
.gitattributes
.gitignore ignore binary objects not meant to be checked in 2025-12-11 02:14:41 +08:00
analyze-bloat.sh
API.md
baosign.ps1 update target on signer script 2025-12-18 02:23:32 +08:00
Cargo.lock add version bump so we're no longer patched 2025-12-16 02:13:02 +08:00
Cargo.toml add version bump so we're no longer patched 2025-12-16 02:13:02 +08:00
CODE_OF_CONDUCT.md initial commit 2020-03-10 12:13:05 +08:00
CONTRIBUTING.md
FORMATTING.md
LICENSE
publish.py
README-baochip.md add notes on how to update boot1 on a dabao 2025-11-27 23:31:41 +08:00
README-precursor.md
README.md incidental readme improvements 2025-11-25 19:06:16 +08:00
RELEASE-v0.8.md
RELEASE-v0.9.md
rustfmt.toml

Xous Core

Xous is a microkernel operating system written in pure Rust, built for high-assurance applications.

Key features:

  • Hardware memory protection
    • Virtual memory via MMU
    • Each process has an isolated address space
  • std support in stable Rust (tier-3 Rust target)
  • Asynchronous message passing
  • Minimal code base
  • Targeted at high-assurance embedded applications

The Xous Book covers the architecture and structure of the kernel.

The wiki is a community resource that answers many FAQ.

The Baochip README is the starting point for Baochip users. vscode users may wish to install the baochip extension to help manage build & test cycles.

The Precursor README is the starting point for Precursor users.

Xous is a mono-repo project. It contains the kernel, libraries, applications, and tools necessary to build full device images. Here is a brief description of the more important directories:

  • api: "Secular" API libraries - minimal-dependency, common-core APIs used by core Xous services
  • apps: Precursor applications
  • apps-dabao: Dabao applications
  • apps-baosec: Baosec applications
  • bao1x-boot: Bao1x secure boot chain
  • baremetal: Baremetal target - runs after the boot chain, for developers that don't want Xous but can still use Xous' no-std features
  • emulation: Renode scripts used to emulate Xous
  • imports: Vendored-in libraries that had to be forked for Xous compatibility
  • kernel: core memory manager, irq manager, and syscall implementations.
  • libs: Device driver libraries. The common thread is that none of these code bases contain a main.rs, just a lib.rs.
  • loader: Sets up virtual memory space and boots the kernel
  • locales: Tools for handling internationalization
  • signing: Scripts for generating signed images
  • services: Xous programs that support Xous apps. Middleware, if you will.
  • svd2utra: A program for converting SVD chip descriptions in XML to the UTRA "header file" format
  • tools: Programs used to construct a final boot image. Also the home of various diagnostic and test utilities.
  • utralib: The Unambigous Thin Register Abtraction. The core hardware interface for Xous.
  • xous-ipc: Inter-process communication convenience APIs for Xous
  • xous-rs: API files for the kernel. Where the syscall interfaces live.
  • xtask: The build system manager for Xous.

Dependencies

Install the latest Rust or run rustup update to update your Rust installation prior to building. Xous development assumes a recent version of Rust.

Build Commands

  • Precursor: cargo xtask app-image
  • Dabao: cargo xtask dabao
  • Baosec: cargo xtask baosec
  • Baochip baremetal: cargo xtask baremetal-bao1x

Additional apps to be bundled into images can be specified as extra arguments on the command line, e.g. cargo xtask dabao helloworld will generate a Dabao image that includes helloworld in the detached-app section. Features, app-features, loader-features, and so forth can also be passed as command line arguments; run cargo xtask on its own for more help.

Emulation

  • cargo xtask run will bring up an emulated Precursor
  • cargo xtask baosec-emu will bring up an emulated Baosec
  • cargo xtask renode-image will build an image suitable for Renode emulation of a Precursor target. Start renode by running renode emulation/xous-release.resc

Building Documentation

A flag of --feature doc-deps must be passed when running cargo doc, like this:

cargo doc --no-deps --feature doc-deps

doc-deps is a dummy hardware target that satisfies the requirement of a "board" when building documentation.

Local-vs-crates.io Verification

xtask does a check every build to ensure that any crates.io dependencies are synchronized with the contents of the monorepo. It protects against the scenario where you edited a crate that exists in the Xous repo, but the build system ignores the local edits because it's fetching an old version from crates.io.

Developers working on published crates should patch them in the root Cargo.toml file and bypass the check with --no-verify.

Acknowledgement

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