From 0538f8a1dbff188d4f1f6a3cba70611dd24dfa07 Mon Sep 17 00:00:00 2001 From: Nick Spinale Date: Thu, 25 Jan 2024 10:42:25 +0000 Subject: [PATCH] Update CapDL initializer docs Signed-off-by: Nick Spinale --- crates/sel4-capdl-initializer/README.md | 91 +++++++++++++++---------- 1 file changed, 54 insertions(+), 37 deletions(-) diff --git a/crates/sel4-capdl-initializer/README.md b/crates/sel4-capdl-initializer/README.md index 15052cbf6..5002c536b 100644 --- a/crates/sel4-capdl-initializer/README.md +++ b/crates/sel4-capdl-initializer/README.md @@ -7,25 +7,52 @@ # CapDL-based system initializer This document assumes familiarity with the upstream -[`capdl-loader-app`](https://docs.sel4.systems/projects/capdl/c-loader-app.html). +[`capdl-loader-app`](https://github.com/seL4/capdl/tree/master/capdl-loader-app). -## `capdl-initializer` +## `sel4-capdl-initializer` -`capdl-initializer` is simlar in purpose to the upstream -[`capdl-loader-app`](https://docs.sel4.systems/projects/capdl/c-loader-app.html). The main practical -difference is how it fits into a build system, allowing for different approaches to distribution and -integration. `capdl-loader-app` is a C program built using CMake and depends on the system CapDL -spec at link-time. `capdl-initializer` itself is just the initializer without the spec, and thus -does not depend on the spec at build time. Instead, it is accompanied by a CLI component called -`capdl-initializer-add-spec` which is used to append the spec to the `capdl-initializer` ELF image -in a seperate preparation phase. +The `sel4-capdl-initializer` crate is simlar in purpose to the upstream +[`capdl-loader-app`](https://github.com/seL4/capdl/tree/master/capdl-loader-app). The main practical +difference is how it fits into downstream build systems, allowing for different approaches to +distribution and integration. `capdl-loader-app` is a C program built using CMake and depends on the +system CapDL spec at link-time. The `sel4-capdl-initializer` crate itself is just the initializer +without the spec, and thus does not depend on the spec at build time. Instead, it is accompanied by +a CLI component called `sel4-capdl-initializer-add-spec` which is used to append the spec to the +`sel4-capdl-initializer` ELF image in a seperate preparation phase. -`capdl-initializer` depends on the `libsel4` headers. These are provided in the same way as +`sel4-capdl-initializer` depends on the `libsel4` headers. These are provided in the same way as they are for the `sel4-config` crate and its dependants (i.e. via `SEL4_PREFIX` or `SEL4_INCLUDE_DIRS`). -Here is an example of how to build and use this crate. First, independantly of the application, -build the initializer and accompanying CLI tool: +Here is an example of how to build and use this crate, from the root directory of this repository. +First, independantly of the application, build the initializer: + +```bash +SEL4_PREFIX=$my_sel4_prefix \ + cargo build \ + -Z build-std=core,alloc,compiler_builtins \ + -Z build-std-features=compiler-builtins-mem \ + --target aarch64-sel4-minimal \ + --release \ + -p sel4-capdl-initializer +``` + +Later, prepare the initializer by adding the CapDL spec. `sel4-capdl-initializer-add-spec` takes a +CapDL spec in JSON format. [This branch](https://github.com/coliasgroup/capdl/tree/coliasgroup) of +the parse-capDL tool is capable of translating a `.cdl` file to JSON. + +```bash +parse-capDL --object-sizes=$my_object_sizes --json=spec.json $my_capdl_spec + +cargo run -p sel4-capdl-initializer-add-spec -- \ + -e target/aarch64-sel4-minimal/release/sel4-capdl-initializer.elf \ + -f spec.json \ + -d $my_fill_dir \ + -o app.elf +``` + +There are other ways to acquire and build this code. For example, one could use `cargo install` +without having to clone this repository: ```bash url="https://github.com/seL4/rust-sel4" @@ -37,51 +64,41 @@ SEL4_PREFIX=$my_sel4_prefix \ -Z build-std=core,alloc,compiler_builtins \ -Z build-std-features=compiler-builtins-mem \ --target aarch64-sel4-minimal \ + --release \ --root $my_project_local_cargo_root \ --git $url \ - capdl-initializer + sel4-capdl-initializer cargo install \ --root $my_project_local_cargo_root \ --git $url \ - capdl-initializer-add-spec -``` + sel4-capdl-initializer-add-spec -Later, prepare the initializer by adding the CapDL spec. `capdl-initializer-add-spec` takes a CapDL -spec in JSON format. [This branch](https://github.com/coliasgroup/capdl/tree/coliasgroup) of the -parse-capDL tool is capable of translating a `.cdl` file to JSON. - -```bash parse-capDL --object-sizes=$my_object_sizes --json=spec.json $my_capdl_spec -$my_project_local_cargo_root/bin/capdl-initializer-add-spec \ - -e $my_project_local_cargo_root/bin/capdl-initializer \ +$my_project_local_cargo_root/bin/sel4-capdl-initializer-add-spec \ + -e $my_project_local_cargo_root/bin/sel4-capdl-initializer \ -f spec.json \ -d $my_fill_dir \ -o app.efl ``` -## `capdl-initializer-with-embedded-spec` +## `sel4-capdl-initializer-with-embedded-spec` -`capdl-initializer-with-embedded-spec` shares most of its code with `capdl-initializer`, but is -built more like the upsream `capdl-loader-app`. The resulting root-task memory footprint is smaller -than that of `capdl-initializer`, but building it is more complex. Instead of building the binary -independantly of the spec and then adding the spec later, the spec is provided to its `build.rs` -script at compile time via environment variables. +`sel4-capdl-initializer-with-embedded-spec` shares most of its code with `sel4-capdl-initializer`, +but is built more like the upsream `sel4-capdl-loader-app`. The resulting root-task memory footprint +is smaller than that of `sel4-capdl-initializer`, but building it is more complex. Instead of +building the binary independantly of the spec and then adding the spec later, the spec is provided +to its `build.rs` script at compile time via environment variables. ```bash -url="https://github.com/seL4/rust-sel4" - -RUST_TARGET_PATH=$my_rust_target_path \ SEL4_PREFIX=$my_sel4_prefix \ CAPDL_SPEC_FILE=spec.json \ CAPDL_FILL_DIR=$my_fill_dir \ - cargo install \ - -Z unstable-options \ + cargo build \ -Z build-std=core,alloc,compiler_builtins \ -Z build-std-features=compiler-builtins-mem \ --target aarch64-sel4-minimal \ - --root $my_project_local_cargo_root \ - --git $url \ - capdl-initializer-with-embedded-spec + --release \ + -p sel4-capdl-initializer-with-embedded-spec ```