This repository contains crates for supporting the use of Rust in seL4 userspace. So far, this includes:
rustc
target specifications for seL4 userspace (JSON and docs)The ./hacking directory contains scripts for developing and testing these crates using Nix and, optionally, Docker.
This work is funded by the seL4 Foundation.
https://sel4.github.io/rust-sel4/
This project builds upon seL4 and the seL4 Microkit. In particular, this project works with at least the following versions of those related projects:
cd6d3b8c25d49be2b100b0608cf0613483a6fffa
(version 13.0.0, on github.com/seL4/seL4:master)0cdbffec9cf6b4c7c9c57971cbee5a24a70c8fd0
(on github.com/seL4/seL4:microkit)1ccdfcb3b224533c965fd6508de3dd56657f959c
(version 1.3.0, on github.com/seL4/microkit:main)sel4
: Straightforward, pure-Rust bindings to the seL4 API.sel4-sys
: Raw bindings to the seL4 API, generated from the libsel4 headers
and interface definition files. This crate is not intended to be used directly by application
code, but rather serves as a basis for the sel4
crate's implementation.sel4-config
: Macros and constants corresponding to the seL4 kernel
configuration. Can be used by all targets (i.e. in all of: application code, build scripts, and
build-time tools).sel4-platform-info
: Constants corresponding to the contents of
platform_info.h
. Can be used by all targets, on configurations where this file exists..sel4-sync
: Synchronization constructs using seL4 IPC. Currently only
supports notification-based mutexes.sel4-logging
: Log
implementation for the log
crate.sel4-externally-shared
: Abstractions for interacting with
data in shared memory.sel4-shared-ring-buffer
: Implementation of shared data
structures used in the seL4 Device Driver Framework.sel4-async-*
: Crates for leveraging async Rust in seL4 userspace.sel4-root-task
: A runtime for root tasks that supports thread-local
storage and unwinding, and provides a global allocator.sel4-microkit
: A runtime for seL4
Microkit protection domains, including an implementation of
libmicrokit and abstractions for IPC.sel4-capdl-initializer
: A
CapDL-based system initializer.sel4-kernel-loader
: A loader for the seL4 kernel, similar in
purpose to elfloader.The best way to learn how to integrate these crates into your project is to check out the concrete examples of their use listed above.
These crates are not yet hosted on crates.io. Use them either as Git or path Cargo dependencies.
Some of these crates depend, at build time, on external components and configuration. In all cases,
information for locating these dependencies is passed to the dependant crates via environment
variables which are interpreted by build.rs
scripts. Here is a list of environment variables and
the crates which use them:
sel4-config
and sel4-sys
, whose dependants include sel4
, sel4-root-task
, sel4-microkit
,
and many more, use $SEL4_INCLUDE_DIRS
(defaulting to $SEL4_PREFIX/libsel4/include
if
$SEL4_PREFIX
is set) which must contain a colon-separated list of include paths for the libsel4
headers. See the the sel4
crate's rustdoc for more information.sel4-platform-info
, whose dependants include sel4-kernel-loader
, uses $SEL4_PLATFORM_INFO
(defaulting to $SEL4_PREFIX/support/platform_gen.yaml
if $SEL4_PREFIX
is set) which must
contain the path of the platform_gen.yaml
file from the seL4 kernel build system.sel4-kernel-loader
uses $SEL4_KERNEL
(defaulting to $SEL4_PREFIX/bin/kernel.elf
if
$SEL4_PREFIX
is set) which must contain the path of the seL4 kernel (as an ELF executable).The only requirements for building and running the tests in this repository are Linux, Make, rustup, and Nix. This repository contains scripts for setting up a Docker container with a suitable development environment in case you aren't on Linux or don't want to install Nix.
First, clone this repository:
git clone https://github.com/seL4/rust-sel4
cd rust-sel4
If you are using Docker, build, run, and enter a Docker container for development. This container
mounts this repository's top-level at /work
.
cd hacking/docker && make run && make exec
At this repository's top-level directory, build and simulate a simple seL4-based system with a root task written in Rust (this will take a few minutes):
make example # use 'ctrl-a x' to exit the simulation
Build and run all of this repository's automated tests:
make run-tests