# 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 - [Microkernel](./kernel) architecture - System [services](./services) live in userland - Targeted at high-assurance embedded applications The [Xous Book](https://betrusted.io/xous-book/) covers the architecture and structure of the kernel. The [wiki](https://github.com/betrusted-io/betrusted-wiki/wiki) is a community resource that answers many FAQ. The [Baochip README](./README-baochip.md) 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](./README-precursor.md) 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](./utralib/README.md). 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](https://rust-lang.org/tools/install/) 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](https://renode.io/#downloads) 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