2 releases
Uses old Rust 2015
0.5.2 | Oct 22, 2018 |
---|---|
0.5.1 | Sep 21, 2018 |
#1838 in Development tools
22KB
306 lines
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
-
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 includelibsel4-sys
as a dependency to buildcargo 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 https://github.com/maindotrs/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 thefel4-config
crate. Additionally, theRUST_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 = "0.5"
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
Please see the LICENSE file for more details
Dependencies
~0–2.4MB
~50K SLoC