libsel4-sys

Overview

Builds the sel4 kernel and generates Rust bindings around it, as configured by a feL4 manifest.

This library provides thin Rust bindings around the seL4 codebase; more idiomatic Rust wrappers for the enclosed functionality will be supplied in other crates.

Intended for use in projects managed by cargo-fel4, see that repository for introductory materials.

Getting Started

Dependencies

libsel4-sys uses git submodules to make seL4 related code available locally. Building the seL4 code requires several system dependencies to be installed. The few Rust dependencies are managed by Cargo.toml, so Cargo is necessary, as well as Xargo for cross-compilation. Rustup is the recommended Rust toolchain manager.

• rust (nightly)
• xargo (for cross-compiling)
• gcc/g++ cross compilers (for ARM targets)
• cmake (for seL4's build)
• ninja-build (for seL4's build)
• python (for seL4's build)
• xmlint (for seL4's build)

Building

This project is intended to be built in the context of the cargo fel4 command, which manages the piping of key environment variables relevant to the downstream project.

• Install Rust Nightly

  # Download the rustup install script
  wget https://static.rust-lang.org/rustup/rustup-init.sh
  
  # Install rustup
  chmod +x rustup-init.sh
  sh rustup-init.sh
  
  rustup install nightly

• Install xargo

  # Xargo requires rust-src component
  rustup component add --toolchain nightly rust-src
  
  # Install Xargo
  cargo +nightly install xargo

• Install the gnu cross compilers

  # Used by the armv7-sel4-fel4 target
  sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
  
  # Used by the aarch64-sel4-fel4 target
  sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

• Install Python, pip, and a sel4-specific pip package.

  # Install python and pip, if you don't have them already
  sudo apt-get install python-pip
  
  pip install sel4-deps

• Install cmake

  CMake version 3.7.2 or greater is required. Binary releases are available from cmake.org.

  An example workflow for a recent binary installation on Ubuntu can be found on StackExchange's askUbuntu.

  Alternately, you can use Python's pip tool to install the latest cmake.

  sudo pip install --upgrade cmake

• Install ninja-build Ninja version 1.7.1 or greater is required or greater is required due to the seL4 build system. Binary releases are available from github.

  Ubuntu users can typically install ninja using apt-get.

  sudo apt-get install ninja-build

• xmlint

  The underlying seL4 build system requires xmlint.

  sudo apt-get install libxml2-utils

• Install cargo-fel4 using the directions from that repository.

• Use cargo-fel4 to create a new feL4 project, which will automatically include libsel4-sys as a dependency to build

  cargo fel4 new demo_project
  cd demo_project
  cargo fel4 build

• Manual builds are available as an alternative to using cargo-fel4, though are not recommended for general use.

• Clone the libsel4-sys repository

  git clone git@github.com:PolySync/libsel4-sys.git
  cd libsel4-sys

• Pull in seL4 related dependencies to the local filesystem

  git submodule update --init

• Manual builds require that the FEL4_MANIFEST_PATH environment variable is set and includes a path pointing to a fel4.toml file, as specified by the fel4-config crate. Additionally, the RUST_TARGET_PATH must be supplied, pointing to the directory that contains the Rust target specification JSON files relevant for the desired build target.

  RUST_TARGET_PATH=$PWD/test_configs FEL4_MANIFEST_PATH=$PWD/test_configs/fel4.toml xargo rustc --target x86_64-sel4-fel4 -vv

Installation

libsel4-sys may be included in your Rust project by including it in your Cargo.toml.

• In the relevant [dependencies] section:

  libsel4-sys = { git = "https://github.com/PolySync/libsel4-sys.git", branch = "master" }

Usage

The generated bindings should be treated as relatively ephemeral and dynamic compared to most Rust libraries. The output is context-specific to the target (e.g. "armv7-sel4-fel4") and the set of configuration flags derived from the input feL4 manifest file.

See the Rust docs for a surface-level overview of the raw APIs exposed.

RUST_TARGET_PATH=$PWD/test_configs FEL4_MANIFEST_PATH=$PWD/test_configs/fel4.toml xargo doc --target x86_64-sel4-fel4 -vv

Examples

• Creating a seL4_CapRights_t instance

  extern crate libsel4_sys;
  use libsel4_sys::{seL4_Word, seL4_CapRights_new};
  let cap_rights = unsafe { seL4_CapRights_new(0 as seL4_Word, 1 as seL4_Word, 0 as seL4_Word); };

Tests

Currently, all testing is done one level up, in the cargo-fel4 repo, which has the capability to auto-generate the appropriate test runner code and exercise the resultant artifacts.

Building

See the cargo-fel4 repository for its build and installation.

Running

Once cargo-fel4 and the libsel4-sys dependencies are installed, you should be able to run:

cargo fel4 new tests
cd tests
cargo fel4 test build
cargo fel4 test simulate

License

© 2018, PolySync Technologies, Inc.

• Jon Lamb email
• Zack Pierce email
• Dan Pittman email

Please see the LICENSE file for more details