diff --git a/.bundle/config b/.bundle/config deleted file mode 100644 index 9bc01b4c325..00000000000 --- a/.bundle/config +++ /dev/null @@ -1,3 +0,0 @@ ---- -BUNDLE_PATH: "vendor/bundle" -BUNDLE_DISABLE_SHARED_GEMS: "true" diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index f6c980ae47b..00000000000 --- a/.gitattributes +++ /dev/null @@ -1,4 +0,0 @@ -# Copyright 2025 Proofcraft Pty Ltd -# SPDX-License-Identifier: BSD-2-Clause - -*.pdf binary diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index 6b165d67e99..00000000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,70 +0,0 @@ -# Copyright 2020, Data61, CSIRO (ABN 41 687 119 230) -# -# SPDX-License-Identifier: BSD-2-Clause - -# Build and deploy the site - -name: Build - -on: - push: - branches: - - master - pull_request: - schedule: - - cron: '7 3 * * *' - workflow_dispatch: - -jobs: - build: - name: Site - runs-on: ubuntu-24.04 - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - submodules: true - - uses: actions/setup-python@v5 - with: - python-version: 3.9 - - uses: ruby/setup-ruby@v1 - with: - bundler-cache: true - - run: pip3 install -U camkes-deps - - run: sudo apt-get install doxygen - - run: make build JEKYLL_ENV=production - - run: tar -cvf site.tar _site/ - - uses: actions/upload-artifact@v4 - with: - name: site - path: site.tar - - deploy: - if: ${{ github.repository_owner == 'seL4' && - (github.event_name == 'push' || github.event_name == 'schedule' || - github.event_name == 'workflow_dispatch') }} - needs: build - name: 'Deploy' - runs-on: ubuntu-24.04 - steps: - - uses: actions/checkout@v4 - with: - ref: gh-pages - token: ${{ secrets.GH_TOKEN }} - # for removing files, we need to start fresh; this does not remove dot-files - - run: rm -rf * - - uses: actions/download-artifact@v4 - with: - name: site - - run: tar -xvf site.tar - - run: cp -a _site/* . - - run: rm -rf site.tar _site - # recreate CNAME file for GitHub; not included in generated site - - run: echo docs.sel4.systems > CNAME - # add/remove everything - - run: git add -A . - - run: git diff --cached - - run: git config user.name "CI" - - run: git config user.email ci@sel4.systems - - run: git commit -m "auto-deployed" - - run: git push diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml deleted file mode 100644 index 7e30f0708a9..00000000000 --- a/.github/workflows/pr.yml +++ /dev/null @@ -1,14 +0,0 @@ -# Copyright 2025, Proofcraft Pty Ltd -# -# SPDX-License-Identifier: BSD-2-Clause - -# Actions to run on pull requests - -name: PR - -on: [pull_request, workflow_dispatch] - -jobs: - pr-checks: - name: Checks - uses: seL4/ci-actions/.github/workflows/pr.yml@master diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml deleted file mode 100644 index 6e8feee1241..00000000000 --- a/.github/workflows/push.yml +++ /dev/null @@ -1,18 +0,0 @@ -# Copyright 2020, Data61, CSIRO (ABN 41 687 119 230) -# -# SPDX-License-Identifier: BSD-2-Clause - -# Actions to run on Push and Pull Request -name: CI - -on: - push: - branches: - - master - pull_request: - workflow_dispatch: - -jobs: - checks: - name: Checks - uses: seL4/ci-actions/.github/workflows/push.yml@master diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 360f7e848fc..00000000000 --- a/.gitignore +++ /dev/null @@ -1,18 +0,0 @@ -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. -# SPDX-License-Identifier: BSD-2-Clause - -_data/generated.yml -_site/ -_preview/ -.sass-cache/ -_repos/ -projects/virtualization/docs/api/ -.jekyll-cache/ -.npm_deps -vendor/ -node_modules/ -_processed/microkit-tutorial/ -_processed/tutes/ -_processed/rust/ -_data/microkit_tutorial.yml -_data/microkit_platforms.yml diff --git a/.linkcheck-ignore.yml b/.linkcheck-ignore.yml deleted file mode 100644 index 317544f5d60..00000000000 --- a/.linkcheck-ignore.yml +++ /dev/null @@ -1,15 +0,0 @@ -# Copyright 2025 Proofcraft Pty Ltd -# SPDX-License-Identifier: BSD-2-Clause - -# Ignore all files that are part of the website itself, they will get their own -# link check. Only put admin files such as README.md into the standard PR check. -files: - - vendor - - "_.*/.*" - - ".*html" - - ".*/.*/.*md" - - getting-started.md - - Resources.md - - releases.md - -urls: diff --git a/.reuse/dep5 b/.reuse/dep5 deleted file mode 100644 index 1c8f0dc65b8..00000000000 --- a/.reuse/dep5 +++ /dev/null @@ -1,66 +0,0 @@ -Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ -Upstream-Name: seL4 docs site -Upstream-Contact: seL4 team -Source: https://docs.sel4.systems - -# Sample paragraph, commented out: -# -# Files: src/* -# Copyright: $YEAR $NAME <$CONTACT> -# License: ... - -Files: Gemfile.lock - .ruby-version - .bundle/config - Hardware/HiKey/*.patch - Hardware/CEI_TK1_SOM/CANBoard/Tegra_CANboard_tofab_v1.zip -Copyright: 2020 seL4 Project a Series of LF Projects, LLC. -License: BSD-2-Clause - -Files: _plugins/breadcrumbs.rb -Copyright: 2016 No -License: MIT - -Files: Hardware/CEI_TK1_SOM/*.jpg - Hardware/CEI_TK1_SOM/CANBoard/*.jpg - Hardware/CEI_TK1_SOM/DaughterBoard/*.jpg - projects/buildsystem/old/menuconfig.png - projects/camkes/visual-camkes/*.png - projects/hardware_hacks/level-converter/levelconverter-small.jpg - Hardware/VMware/vmware-serial.png - Hardware/CEI_TK1_SOM/LogicPro8/*.png - Hardware/CEI_TK1_SOM/LogicPro8/*.PNG - Hardware/CEI_TK1_SOM/LogicPro8/*.JPG - Hardware/CEI_TK1_SOM/CANBoard/silk.png - Hardware/CEI_TK1_SOM/tk1-som_pinmux_V2.4.xlsm - Hardware/CEI_TK1_SOM/DaughterBoard/tegra_daughterboard_bom3.xls - Hardware/CEI_TK1_SOM/CEI_TK1_SOM_customer_pinmux_v11.xlsm - Hardware/CEI_TK1_SOM/CANBoard/CanBoardBOMDraft1.xlsx - Hardware/CEI_TK1_SOM/CANBoard/Can_board_pins.png - Hardware/CEI_TK1_SOM/CANBoard/canboard_v3.pdf - Hardware/CEI_TK1_SOM/DaughterBoard/daughterboard_bottom - Hardware/CEI_TK1_SOM/DaughterBoard/daughterboard_r3a_schematic.pdf - Hardware/CEI_TK1_SOM/DaughterBoard/daughterboard_top - Hardware/CEI_TK1_SOM/DaughterBoard/tk1_render_3.PNG - CMA34DBMC/CMA34CRD-thumb.jpg - Hardware/Star64/dip_switch.png -License: CC-BY-SA-4.0 -Copyright: 2020 seL4 Project a Series of LF Projects, LLC. - -Files: _icons/*.svg -Copyright: Tailwind Labs -License: MIT - -Files: package-lock.json package.json -License: BSD-2-Clause -Copyright: 2025 Proofcraft Pty Ltd - -Files: - projects/microkit/manual/2.0.1/assets/microkit_flow.pdf - projects/microkit/manual/2.0.1/assets/microkit_flow.svg - projects/microkit/manual/2.0.1/microkit_user_manual.pdf - projects/microkit/manual/2.1.0/assets/microkit_flow.pdf - projects/microkit/manual/2.1.0/assets/microkit_flow.svg - projects/microkit/manual/2.1.0/microkit_user_manual.pdf -License: CC-BY-SA-4.0 -Copyright: 2021 Breakaway Consulting Pty. Ltd. diff --git a/.ruby-version b/.ruby-version deleted file mode 100644 index bea438e9ade..00000000000 --- a/.ruby-version +++ /dev/null @@ -1 +0,0 @@ -3.3.1 diff --git a/.stylefilter b/.stylefilter deleted file mode 100644 index 2f4dadf0809..00000000000 --- a/.stylefilter +++ /dev/null @@ -1,8 +0,0 @@ -# -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. -# -# SPDX-License-Identifier: BSD-2-Clause -# - -# 3rd-party file -*Hardware/CEI_TK1_SOM/L4TCan/mcp251x.c diff --git a/404.html b/404.html new file mode 100644 index 00000000000..111fd949612 --- /dev/null +++ b/404.html @@ -0,0 +1,551 @@ + + + + + + + | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/ApiDoc.html b/ApiDoc.html new file mode 100644 index 00000000000..db8e8c47aee --- /dev/null +++ b/ApiDoc.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/BenchmarkingGuide.html b/BenchmarkingGuide.html new file mode 100644 index 00000000000..d747a0f1bd5 --- /dev/null +++ b/BenchmarkingGuide.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/CAmkES/Terminology.html b/CAmkES/Terminology.html new file mode 100644 index 00000000000..eb437e0aa76 --- /dev/null +++ b/CAmkES/Terminology.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/CAmkES/index.html b/CAmkES/index.html new file mode 100644 index 00000000000..0486b84aaac --- /dev/null +++ b/CAmkES/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/CAmkESCLI.html b/CAmkESCLI.html new file mode 100644 index 00000000000..eabbf186f18 --- /dev/null +++ b/CAmkESCLI.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/CAmkESDifferences.html b/CAmkESDifferences.html new file mode 100644 index 00000000000..df1e8804bad --- /dev/null +++ b/CAmkESDifferences.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/CAmkESInternals.html b/CAmkESInternals.html new file mode 100644 index 00000000000..825aace8152 --- /dev/null +++ b/CAmkESInternals.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/CAmkESNext.html b/CAmkESNext.html new file mode 100644 index 00000000000..0c0880a9f5e --- /dev/null +++ b/CAmkESNext.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/CMA34DBMC/index.html b/CMA34DBMC/index.html new file mode 100644 index 00000000000..db98fe701cc --- /dev/null +++ b/CMA34DBMC/index.html @@ -0,0 +1,580 @@ + + + + + + + CMA34D | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

CMA34D

+ +

The CMA34D is an embedded i7 board. It needs 12V and 5V supplies. It +does not have a BMC (Base Management Controller) so cannot be controlled +remotely.

+ +

We used a Stellaris Connected Launchpad +connected to an RS232 level converter and a 2-way relay module, together with a +suitable power supply.

+ +

Photo of CMA34CRD setup

+ +

In the picture, the CMA34D is at the left, with the TTL-to-RS232 +converter above it. The Launchpad is in the middle, with the relay board +above it, partially obscured by the wiring harness. The power supply is +on the right. All is mounted on a cheap polyethylene breadboard that has +been covered in aluminium tape to provide a ground plane; all the boards +and cables are mounted on 20mm standoffs.

+ +

Software for the launchpad is available at +https://github.com/data61/echronos-lwip Use the master branch, and the +project is at +packages/machine-tm4c1294-launchpad/projects/embedded_pc_testbed_src

+ +

The relays are connected to pins PK6 and PK7 on the launchpad; the UART +to pin PA0 (Rx) and PA1 (Tx). You’ll need to swap the wires to the level +converter (so Rx from the launcpad connects to Tx on the level +converter, and vice versa); and make sure jumpers J4 and J5 are set to +UART.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/CMA34DBMC/index.md b/CMA34DBMC/index.md deleted file mode 100644 index 1788553b03a..00000000000 --- a/CMA34DBMC/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -archive: true -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# CMA34D - -The CMA34D is an embedded i7 board. It needs 12V and 5V supplies. It -does not have a BMC (Base Management Controller) so cannot be controlled -remotely. - -We used a [Stellaris Connected Launchpad](http://www.ti.com/tool/ek-tm4c1294xl) -connected to an RS232 level converter and a 2-way relay module, together with a -suitable power supply. - -Photo of CMA34CRD setup - -In the picture, the CMA34D is at the left, with the TTL-to-RS232 -converter above it. The Launchpad is in the middle, with the relay board -above it, partially obscured by the wiring harness. The power supply is -on the right. All is mounted on a cheap polyethylene breadboard that has -been covered in aluminium tape to provide a ground plane; all the boards -and cables are mounted on 20mm standoffs. - -Software for the launchpad is available at - Use the master branch, and the -project is at -packages/machine-tm4c1294-launchpad/projects/embedded_pc_testbed_src - -The relays are connected to pins PK6 and PK7 on the launchpad; the UART -to pin PA0 (Rx) and PA1 (Tx). You'll need to swap the wires to the level -converter (so Rx from the launcpad connects to Tx on the level -converter, and vice versa); and make sure jumpers J4 and J5 are set to -`UART`. diff --git a/CNAME b/CNAME new file mode 100644 index 00000000000..d1e511ba5a5 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +docs.sel4.systems diff --git a/CapDL.html b/CapDL.html new file mode 100644 index 00000000000..ffaaae1aff5 --- /dev/null +++ b/CapDL.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/DebuggingGuide.html b/DebuggingGuide.html new file mode 100644 index 00000000000..e34cd92e379 --- /dev/null +++ b/DebuggingGuide.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/DebuggingUserspace.html b/DebuggingUserspace.html new file mode 100644 index 00000000000..5e74b83234a --- /dev/null +++ b/DebuggingUserspace.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Developing/Building/Incorporating.html b/Developing/Building/Incorporating.html new file mode 100644 index 00000000000..da6f3f19d40 --- /dev/null +++ b/Developing/Building/Incorporating.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Developing/Building/OldBuildSystem.html b/Developing/Building/OldBuildSystem.html new file mode 100644 index 00000000000..7b984498caa --- /dev/null +++ b/Developing/Building/OldBuildSystem.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Developing/Building/Using.html b/Developing/Building/Using.html new file mode 100644 index 00000000000..44bcd52b97f --- /dev/null +++ b/Developing/Building/Using.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Developing/Building/index.html b/Developing/Building/index.html new file mode 100644 index 00000000000..e3ba4c163d0 --- /dev/null +++ b/Developing/Building/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Developing/Building/seL4Standalone.html b/Developing/Building/seL4Standalone.html new file mode 100644 index 00000000000..893e7e796df --- /dev/null +++ b/Developing/Building/seL4Standalone.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Docker.html b/Docker.html new file mode 100644 index 00000000000..288baa60342 --- /dev/null +++ b/Docker.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/DocsContributing.html b/DocsContributing.html new file mode 100644 index 00000000000..14ddee6188a --- /dev/null +++ b/DocsContributing.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Gemfile b/Gemfile deleted file mode 100644 index b7d7a7cb08c..00000000000 --- a/Gemfile +++ /dev/null @@ -1,40 +0,0 @@ -source "https://rubygems.org" - -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. -# SPDX-License-Identifier: BSD-2-Clause - -# Hello! This is where you manage which Jekyll version is used to run. -# When you want to use a different version, change it below, save the -# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: -# -# bundle exec jekyll serve -# -# This will help ensure the proper Jekyll version is running. -# Happy Jekylling! -gem "jekyll" - -# Other dependencies -gem "html-proofer", "~>4" - -# Ruby 3.3 warns about these being moved out of std lib and recommends adding -# them here: -gem "base64" -gem "csv" -gem "bigdecimal" - -# If you have any plugins, put them here! -# Look here for supported github plugins: https://pages.github.com/versions/ -group :jekyll_plugins do - gem "jekyll-titles-from-headings" - gem "jekyll-relative-links" - gem "jekyll-optional-front-matter" - gem "jekyll-sitemap" - gem 'jekyll-toc' - gem 'jekyll-redirect-from' - gem 'jekyll-remote-theme' - gem "jekyll-postcss-v2" - gem "jekyll-inline-svg" -end - -# Windows does not include zoneinfo files, so bundle the tzinfo-data gem -gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby] diff --git a/Gemfile.lock b/Gemfile.lock deleted file mode 100644 index 5edac3de150..00000000000 --- a/Gemfile.lock +++ /dev/null @@ -1,206 +0,0 @@ -GEM - remote: https://rubygems.org/ - specs: - addressable (2.8.8) - public_suffix (>= 2.0.2, < 8.0) - base64 (0.3.0) - bigdecimal (4.0.1) - colorator (1.1.0) - concurrent-ruby (1.3.6) - csv (3.3.5) - em-websocket (0.5.3) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0) - ethon (0.18.0) - ffi (>= 1.15.0) - logger - eventmachine (1.2.7) - ffi (1.17.3-aarch64-linux-gnu) - ffi (1.17.3-aarch64-linux-musl) - ffi (1.17.3-arm-linux-gnu) - ffi (1.17.3-arm-linux-musl) - ffi (1.17.3-arm64-darwin) - ffi (1.17.3-x86_64-darwin) - ffi (1.17.3-x86_64-linux-gnu) - ffi (1.17.3-x86_64-linux-musl) - forwardable-extended (2.6.0) - google-protobuf (4.33.4) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-aarch64-linux-gnu) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-aarch64-linux-musl) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-arm64-darwin) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-x86_64-darwin) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-x86_64-linux-gnu) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-x86_64-linux-musl) - bigdecimal - rake (>= 13) - html-proofer (4.4.3) - addressable (~> 2.3) - mercenary (~> 0.3) - nokogiri (~> 1.13) - parallel (~> 1.10) - rainbow (~> 3.0) - typhoeus (~> 1.3) - yell (~> 2.0) - zeitwerk (~> 2.5) - http_parser.rb (0.8.1) - i18n (1.14.8) - concurrent-ruby (~> 1.0) - jekyll (4.4.1) - addressable (~> 2.4) - base64 (~> 0.2) - colorator (~> 1.0) - csv (~> 3.0) - em-websocket (~> 0.5) - i18n (~> 1.0) - jekyll-sass-converter (>= 2.0, < 4.0) - jekyll-watch (~> 2.0) - json (~> 2.6) - kramdown (~> 2.3, >= 2.3.1) - kramdown-parser-gfm (~> 1.0) - liquid (~> 4.0) - mercenary (~> 0.3, >= 0.3.6) - pathutil (~> 0.9) - rouge (>= 3.0, < 5.0) - safe_yaml (~> 1.0) - terminal-table (>= 1.8, < 4.0) - webrick (~> 1.7) - jekyll-inline-svg (1.1.5) - jekyll (>= 3.3, < 5.0) - svg_optimizer (~> 0.3.0) - jekyll-optional-front-matter (0.3.2) - jekyll (>= 3.0, < 5.0) - jekyll-postcss-v2 (1.0.2) - jekyll-redirect-from (0.16.0) - jekyll (>= 3.3, < 5.0) - jekyll-relative-links (0.7.0) - jekyll (>= 3.3, < 5.0) - jekyll-remote-theme (0.4.3) - addressable (~> 2.0) - jekyll (>= 3.5, < 5.0) - jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) - rubyzip (>= 1.3.0, < 3.0) - jekyll-sass-converter (3.0.0) - sass-embedded (~> 1.54) - jekyll-sitemap (1.4.0) - jekyll (>= 3.7, < 5.0) - jekyll-titles-from-headings (0.5.3) - jekyll (>= 3.3, < 5.0) - jekyll-toc (0.19.0) - jekyll (>= 3.9) - nokogiri (~> 1.12) - jekyll-watch (2.2.1) - listen (~> 3.0) - json (2.18.0) - kramdown (2.5.1) - rexml (>= 3.3.9) - kramdown-parser-gfm (1.1.0) - kramdown (~> 2.0) - liquid (4.0.4) - listen (3.10.0) - logger - rb-fsevent (~> 0.10, >= 0.10.3) - rb-inotify (~> 0.9, >= 0.9.10) - logger (1.7.0) - mercenary (0.4.0) - nokogiri (1.19.0-aarch64-linux-gnu) - racc (~> 1.4) - nokogiri (1.19.0-aarch64-linux-musl) - racc (~> 1.4) - nokogiri (1.19.0-arm-linux-gnu) - racc (~> 1.4) - nokogiri (1.19.0-arm-linux-musl) - racc (~> 1.4) - nokogiri (1.19.0-arm64-darwin) - racc (~> 1.4) - nokogiri (1.19.0-x86_64-darwin) - racc (~> 1.4) - nokogiri (1.19.0-x86_64-linux-gnu) - racc (~> 1.4) - nokogiri (1.19.0-x86_64-linux-musl) - racc (~> 1.4) - parallel (1.27.0) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - public_suffix (7.0.2) - racc (1.8.1) - rainbow (3.1.1) - rake (13.3.1) - rb-fsevent (0.11.2) - rb-inotify (0.11.1) - ffi (~> 1.0) - rexml (3.4.4) - rouge (4.7.0) - rubyzip (2.4.1) - safe_yaml (1.0.5) - sass-embedded (1.97.2-aarch64-linux-gnu) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-aarch64-linux-musl) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-arm-linux-gnueabihf) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-arm-linux-musleabihf) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-arm64-darwin) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-x86_64-darwin) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-x86_64-linux-gnu) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-x86_64-linux-musl) - google-protobuf (~> 4.31) - svg_optimizer (0.3.0) - nokogiri - terminal-table (3.0.2) - unicode-display_width (>= 1.1.1, < 3) - typhoeus (1.4.1) - ethon (>= 0.9.0) - unicode-display_width (2.6.0) - webrick (1.9.2) - yell (2.2.2) - zeitwerk (2.7.4) - -PLATFORMS - aarch64-linux - aarch64-linux-gnu - aarch64-linux-musl - arm-linux-gnu - arm-linux-gnueabihf - arm-linux-musl - arm-linux-musleabihf - arm64-darwin - x86_64-darwin - x86_64-linux - x86_64-linux-gnu - x86_64-linux-musl - -DEPENDENCIES - base64 - bigdecimal - csv - html-proofer (~> 4) - jekyll - jekyll-inline-svg - jekyll-optional-front-matter - jekyll-postcss-v2 - jekyll-redirect-from - jekyll-relative-links - jekyll-remote-theme - jekyll-sitemap - jekyll-titles-from-headings - jekyll-toc - tzinfo-data - -BUNDLED WITH - 2.5.9 diff --git a/Hardware/BeagleBoard.html b/Hardware/BeagleBoard.html new file mode 100644 index 00000000000..e32208e96af --- /dev/null +++ b/Hardware/BeagleBoard.html @@ -0,0 +1,818 @@ + + + + + + + seL4 on the BeagleBoard | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 on the BeagleBoard

+ +

This page documents booting seL4 on the +Beagleboard, Omap 3530

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform BeagleBoard
Architecture ARMv7A
System-on-chip OMAP3
CPU Cortex-A8
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + +
Proof configsARM
seL4 CMake platform nameomap3
Contributed by Data61
Maintained by seL4 Foundation
+ +

See also Tim Newsham’s +post +on the mailing list for his experience with running seL4 on this board.

+ +

Preparing your SD card

+ +

Prologue

+ +

These instructions are for later versions of the Beagleboard. Before the Xm, +U-Boot and MLO were held in flash.

+ +

The first stage boot loader expects to find the TI X-loader in the root of a FAT +filesystem, on the first partition of the SD card with the name MLO.

+ +

MLO expects to find a file named u-boot.bin in the root directory of the SD +card.

+ +

Setting up Minicom

+ +

Plug the board in. seL4 userspace currently does no power management — you will +probably need a 5V power source, and not rely on powering the board over USB

+ +

If you do not have minicom installed:

+ +
sudo apt-get install minicom
+
+ +

If you are connecting via a USB serial adapter:

+ +
sudo minicom -s ttyUSB0
+
+ +

And if you were connecting via a real serial port:

+ +
sudo minicom -s ttyS0
+
+ +

In either case, this will take you to a configuration menu.

+ +
    +
  1. Choose Serial Port Setup
    2. +
  2. Set A: Serial Device to /dev/ttyUSB0 or /dev/ttyS0 depending on +which serial device you want to use.
    3. +
  3. Set F: Hardware Flow Control to No
    4. +
  4. Set speed to 115200 and eight bit no parity.
    5. +
  5. Save setup as ttyUSB0 or ttyS0
    6. +
  6. Exit Minicom
    7. +
+ +

You can now connect to the !BeagleBoard using Minicom:

+ +
minicom ttyUSB0
+
+ +

Or:

+ +
minicom ttyS0
+
+ +

Permissions

+ +

If you get permissions errors you need to add yourself to the +appropriate group. Find out which group on your machine has access to +the serial ports (on Debian, it’s usually dialout):

+ +
$ ls -l /dev/ttyUSB0
+crw-rw---- 1 root dialout 188, 0 Aug 11 09:43 /dev/ttyUSB0
+
+ +

Then add yourself to the right group:

+ +
sudo usermod -G dialout -a your_login_name
+
+ +

U-Boot

+ +

Now minicom should connect to what it thinks is a “modem”, and then give you a +good old console to work with. You are now in the bootloader, U-Boot, of the +BeagleBoard. You can type commands here and it’ll display the results.

+ +

Some quick useful commands:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
helpdisplay list of commands
printenvlists defined environment variables
mmc initinitialise MMC (to read the the SD card)
mmcinfodisplay current SD card info
fatls mmc 0display list of files on SD card 0
fatloadload script/image into some RAM address to be run
runrun scripts
bootelfboot into en ELF image
+ +

dfu-util

+ +

An alternative is to use dfu-util with the standard U-Boot to transfer the +image to the board.

+ +

The address that the file downloads to is controlled by the loadaddr +environment variable in U-Boot. You can either download an ELF file, and then +run bootelf on the U-Boot command-line, or download a U-Boot image file +(created with mkimage) and use bootm to run it. You may need to take care +that the ELF sections or image regions do not overlap with the location of the +ELF/image itself, or loaded to non-existent memory address (0x81000000 works +fine, but 0x90000000 won’t work on the original Beagle Board since there’s no +RAM there).

+ +
dfu-util -D sel4test-image-arm
+
+ +

Running seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=omap3 -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Which after a few minutes should give you:

+ +

Now, the ELF image we boot into is the sel4test-driver-image-arm-omap3 file. +Copy that file onto the sdcard (the boot loader will be able to load images into +RAM from a FAT image: there is no need to do an image copy). If your SD card is +not formatted, just format it using FAT32. Plug the SD card back into the +BeagleBoard and reset the board by pressing the S2 (reset) button.

+ +

To run the image

+ +
mmc init
+mmcinfo
+fatload mmc 0 ${loadaddr} sel4test-driver-image-arm-omap3
+bootelf ${loadaddr}
+
+ +

where loadaddr is some address, in this example defined as an environment +variable.

+ +
+
+ + Note +
+
+ +

By default, the image produced is relocated to run at address 0x82000000. +If you want to change the address, you need to modify the file +projects/tools/elfloader-tool/gen_boot_image.sh (look for the omap3 case). For +the Beaglebone Black Rev A5, RAM is from address 0x80000000 - 0x9FFFFFFF.

+ +
+
+ +

Depending on the uBoot version present on the Beaglebone, the bootelf command +might not be present. You can use the go command instead. E.g.:

+ +
mmc init
+mmcinfo
+fatload mmc 0 0x82000000 sel4test-driver-image-arm-omap3
+go 0x82000000
+
+ +

After this you should start seeing output from seL4test.

+ +

Tip: if you don’t remember the name of the images on your SD card, you can use:

+ +
fatls mmc 0
+
+ +

to see what is on the SD card.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/BeagleBoard.md b/Hardware/BeagleBoard.md deleted file mode 100644 index b5bbf3b58d7..00000000000 --- a/Hardware/BeagleBoard.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -arm_hardware: true -cmake_plat: omap3 -xcompiler_arg: -DAARCH32=1 -platform: BeagleBoard -arch: ARMv7A -virtualization: false -iommu: false -soc: OMAP3 -cpu: Cortex-A8 -verification: [ARM] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4 on the BeagleBoard - -This page documents booting seL4 on the -[Beagleboard](http://beagleboard.org/beagleboard), Omap 3530 - -{% include hw-info.html %} - -See also [Tim Newsham's -post](https://lists.sel4.systems/hyperkitty/list/devel@sel4.systems/message/AHWTG4D3W6OYF4QPUILMBTU4COP4KH4A/) -on the mailing list for his experience with running seL4 on this board. - -## Preparing your SD card - -### Prologue - -These instructions are for later versions of the Beagleboard. Before the Xm, -U-Boot and MLO were held in flash. - -The first stage boot loader expects to find the TI X-loader in the root of a FAT -filesystem, on the first partition of the SD card with the name MLO. - -MLO expects to find a file named u-boot.bin in the root directory of the SD -card. - -## Setting up Minicom - -Plug the board in. seL4 userspace currently does no power management — you will -probably need a 5V power source, and not rely on powering the board over USB - -If you do not have minicom installed: - -```bash -sudo apt-get install minicom -``` - -If you are connecting via a USB serial adapter: - -```bash -sudo minicom -s ttyUSB0 -``` - -And if you were connecting via a **real** serial port: - -```bash -sudo minicom -s ttyS0 -``` - -In either case, this will take you to a configuration menu. - -1. Choose Serial Port Setup -2. Set A: Serial Device to `/dev/ttyUSB0` or `/dev/ttyS0` depending on - which serial device you want to use. -3. Set F: Hardware Flow Control to No -4. Set speed to `115200` and eight bit no parity. -5. Save setup as `ttyUSB0` or `ttyS0` -6. Exit Minicom - -You can now connect to the !BeagleBoard using Minicom: - -```bash -minicom ttyUSB0 -``` - -Or: - -```bash -minicom ttyS0 -``` - -### Permissions - -If you get permissions errors you need to add yourself to the -appropriate group. Find out which group on your machine has access to -the serial ports (on Debian, it's usually `dialout`): - -```bash -$ ls -l /dev/ttyUSB0 -crw-rw---- 1 root dialout 188, 0 Aug 11 09:43 /dev/ttyUSB0 -``` - -Then add yourself to the right group: - -```bash -sudo usermod -G dialout -a your_login_name -``` - -### U-Boot - -Now minicom should connect to what it thinks is a "modem", and then give you a -good old console to work with. You are now in the bootloader, U-Boot, of the -BeagleBoard. You can type commands here and it'll display the results. - -Some quick useful commands: - -|Command|Description| -|-|-| -|help |display list of commands | -|printenv|lists defined environment variables | -|mmc init |initialise MMC (to read the the SD card) | -|mmcinfo |display current SD card info | -|fatls mmc 0 |display list of files on SD card 0 | -|fatload |load script/image into some RAM address to be run | -|run |run scripts | -|bootelf |boot into en ELF image | - - -### dfu-util - -An alternative is to use `dfu-util` with the standard U-Boot to transfer the -image to the board. - -The address that the file downloads to is controlled by the `loadaddr` -environment variable in U-Boot. You can either download an ELF file, and then -run `bootelf` on the U-Boot command-line, or download a U-Boot image file -(created with `mkimage`) and use `bootm` to run it. You may need to take care -that the ELF sections or image regions do not overlap with the location of the -ELF/image itself, or loaded to non-existent memory address (0x81000000 works -fine, but 0x90000000 won't work on the original Beagle Board since there's no -RAM there). - -```none -dfu-util -D sel4test-image-arm -``` - -## Running seL4test - -{% include sel4test.md %} - -Which after a few minutes should give you: - -Now, the ELF image we boot into is the `sel4test-driver-image-arm-omap3` file. -Copy that file onto the sdcard (the boot loader will be able to load images into -RAM from a FAT image: there is no need to do an image copy). If your SD card is -not formatted, just format it using FAT32. Plug the SD card back into the -BeagleBoard and reset the board by pressing the `S2` (reset) button. - -### To run the image - -```uboot -mmc init -mmcinfo -fatload mmc 0 ${loadaddr} sel4test-driver-image-arm-omap3 -bootelf ${loadaddr} -``` - -where `loadaddr` is some address, in this example defined as an environment -variable. - -{% include note.html %} -By default, the image produced is relocated to run at address 0x82000000. -If you want to change the address, you need to modify the file -`projects/tools/elfloader-tool/gen_boot_image.sh` (look for the omap3 case). For -the Beaglebone Black Rev A5, RAM is from address 0x80000000 - 0x9FFFFFFF. -{% include endnote.html %} - -Depending on the uBoot version present on the Beaglebone, the `bootelf` command -might not be present. You can use the `go` command instead. E.g.: - -```uboot -mmc init -mmcinfo -fatload mmc 0 0x82000000 sel4test-driver-image-arm-omap3 -go 0x82000000 -``` - -After this you should start seeing output from seL4test. - -Tip: if you don't remember the name of the images on your SD card, you can use: - -```uboot -fatls mmc 0 -``` - -to see what is on the SD card. diff --git a/Hardware/Beaglebone.html b/Hardware/Beaglebone.html new file mode 100644 index 00000000000..dca97256895 --- /dev/null +++ b/Hardware/Beaglebone.html @@ -0,0 +1,703 @@ + + + + + + + BeagleBone Black / Blue | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

BeagleBone Black / Blue

+ +

This page contains info about building seL4 on +BeagleBone Black and +BeagleBone Blue.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform BeagleBone Black / Blue
Architecture ARMv7A
System-on-chip AM335x
CPU Cortex-A8
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + +
Proof configsARM
seL4 CMake platform nameam335x-boneblack
Contributed by Community
Maintained by seL4 Foundation
+ +

Building for the BeagleBone Black / Blue

+ +

These instructions were written by Tim Newsham. The BeagleBone is +a community-supported port.

+ +

Requirements

+ +

We suggest using the arm-linux-gnueabi- cross-compilers. Use +the instructions on getting a toolchain.

+ +

Building

+ +

seL4test

+ +

For BeagleBone Blue, substitute am335x-boneblack with am335x-boneblue.

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=am335x-boneblack -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Booting on the BeagleBone Black / Blue

+ +

Hardware Requirements (BeagleBone Black)

+ + + +

Hardware Requirements (BeagleBone Blue)

+ +
    +
  • Power supply (12V DC, 2S LiPo battery or microUSB)
    • +
  • Serial adapter (Connect to UT0 header)
    • +
  • microSD card for file booting or microUSB cable for network boot
    • +
+ +

Interacting with U-Boot

+ +

Connect a serial adapter between your development box and the BeagleBone. Use +a serial program such as picocom or screen to connect to the serial port:

+ +
picocom /dev/ttyUSB0 -b 115200
+
+ +

Power on the device and hit space a few times to interrupt the normal boot +process and get a U-Boot prompt.

+ +

Booting from microSD card

+ +

To boot from a microSD card, copy the sel4test-driver-image-arm-am335x file +to a FAT32 partition the microSD card and insert the card in the BeagleBone.

+ +

At the U-Boot prompt, enter the following to load and run the image:

+ +
fatload mmc 0 ${loadaddr} sel4test-driver-image-arm-am335x
+bootm ${loadaddr}
+
+ +

Booting from TFTP

+ +

To boot over Ethernet, configure your DHCP server to provide a DHCP lease and +to specify the sel4test image as the boot file. +Configure a TFTP server to serve the sel4test-driver-image-arm-am335x file.

+ +

For BeagleBone Black, plug in an Ethernet cable. For BeagleBone Blue, make sure +a microUSB cable is plugged in and connected to a computer running a DHCP +server. Then, at the U-Boot prompt enter:

+ +
dhcp
+bootm ${loadaddr}
+
+ +

To load an alternate image from the TFTP server at 1.2.3.4, use:

+ +
dhcp ${loadaddr} 1.2.3.4:refos-image-arm-am335x
+bootm ${loadaddr}
+
+ +

Other resources

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/Beaglebone.md b/Hardware/Beaglebone.md deleted file mode 100644 index 77cb3ee2bb0..00000000000 --- a/Hardware/Beaglebone.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -arm_hardware: true -cmake_plat: am335x-boneblack -xcompiler_arg: -DAARCH32=1 -platform: BeagleBone Black / Blue -arch: ARMv7A -virtualization: false -iommu: false -soc: AM335x -cpu: Cortex-A8 -verification: [ARM] -Contrib: Community -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# BeagleBone Black / Blue - -This page contains info about building seL4 on -[BeagleBone Black](https://beagleboard.org/black) and -[BeagleBone Blue](https://beagleboard.org/blue). - -{% include hw-info.html %} - -## Building for the BeagleBone Black / Blue - -These instructions were written by Tim Newsham. The BeagleBone is -a community-supported port. - -### Requirements - -We suggest using the `arm-linux-gnueabi-` cross-compilers. Use -[the instructions on getting a toolchain](../projects/buildsystem/host-dependencies.html). - -### Building - -#### seL4test - -For BeagleBone Blue, substitute `am335x-boneblack` with `am335x-boneblue`. - -{% include sel4test.md %} - -## Booting on the BeagleBone Black / Blue - -### Hardware Requirements (BeagleBone Black) - -* Power supply (5V DC or miniUSB cable) -* Serial adapter -* microSD card for file booting or Ethernet cable for network boot - -### Hardware Requirements (BeagleBone Blue) - -* Power supply (12V DC, 2S LiPo battery or microUSB) -* Serial adapter (Connect to UT0 header) -* microSD card for file booting or microUSB cable for network boot - -### Interacting with U-Boot - -Connect a serial adapter between your development box and the BeagleBone. Use -a serial program such as `picocom` or `screen` to connect to the serial port: - -```sh -picocom /dev/ttyUSB0 -b 115200 -``` - -Power on the device and hit space a few times to interrupt the normal boot -process and get a U-Boot prompt. - -#### Booting from microSD card - -To boot from a microSD card, copy the `sel4test-driver-image-arm-am335x` file -to a FAT32 partition the microSD card and insert the card in the BeagleBone. - -At the U-Boot prompt, enter the following to load and run the image: - -```none -fatload mmc 0 ${loadaddr} sel4test-driver-image-arm-am335x -bootm ${loadaddr} -``` - -#### Booting from TFTP - -To boot over Ethernet, configure your DHCP server to provide a DHCP lease and -to specify the `sel4test` image as the boot file. -Configure a TFTP server to serve the `sel4test-driver-image-arm-am335x` file. - -For BeagleBone Black, plug in an Ethernet cable. For BeagleBone Blue, make sure -a microUSB cable is plugged in and connected to a computer running a DHCP -server. Then, at the U-Boot prompt enter: - -```none -dhcp -bootm ${loadaddr} -``` - -To load an alternate image from the TFTP server at 1.2.3.4, use: - -```none -dhcp ${loadaddr} 1.2.3.4:refos-image-arm-am335x -bootm ${loadaddr} -``` - -## Other resources - -* [Supporting the UART1 interface with CAmkES](http://julien.gunnm.org/geek/sel4/beaglebone%20black/2016/06/15/beaglebone-black-sel4-uart1/) diff --git a/Hardware/CEI_TK1_SOM/CANBoard/index.html b/Hardware/CEI_TK1_SOM/CANBoard/index.html new file mode 100644 index 00000000000..bcea7de561e --- /dev/null +++ b/Hardware/CEI_TK1_SOM/CANBoard/index.html @@ -0,0 +1,851 @@ + + + + + + + The CAN Daughterboard | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

The CAN Daughterboard

+ +

The CAN Daughterboard is an open-hardware +CAN/SPI/I2C/Serial board designed by the Trustworthy Systems group, +that can be mounted below the power supply module of +the TK1-SOM. It provides two CAN buses implemented with MCP2515 +(on the TK1-SOM’s SPI bus) and voltage conversion for the two serial +ports.

+ +

Top of board +Bottom of board +Side view of mounted stack

+ +

Mounting

+

The board attaches to the bottom of a TK1-SOM via the +expansion connector. No further work should be needed to enumerate the +device given a kernel supporting GPIO chipselects.

+ +

Note the unpopulated standoff holes on the rightmost image above — it +is possible to fit a standoff of the same type already installed in the +TK1-SOM to stabilize the ‘tower’ making it easier to work with.

+ +

The part numbers of the standoffs between the CAN daughterboard and TK1 +is the same as is already used between the CPU & GPU board. Order codes:

+ +
    +
  • STANDOFF - HEX M2.5 x 16MM ALUMINUM M-F (M2111-2545-AL) + between pcb standoff
    • +
  • SCREW - M2.5 x 5 MM SS PAN HEAD PHILIPS (92000A103) bottom + pcb screw
    • +
+ +

Using Linux with this daughterboard for CAN

+

(hello world & testing) See Using CAN on L4T through an MCP251X

+ +

Pinout detail

+

The font on the silkscreen indicating pins is +difficult to see once the tower is assembled (wasn’t enough space on the +top) - See this picture (view taken from bottom):

+ +

Silk Screen

+ +

Warning - UART Level Converter:

+ +
    +
  • If using the level converter on the board, and if you are +getting junk from your 3V3 serial cable, read this:
    • +
  • Unfortunately there is an issue with these level converter +chips, in some impedance situations the rise time is much worse +than indicated on the datasheet. Basically, with some serial +cables the converter will garble signals at a high baud rate +(> 57600).
    • +
  • This can be circumvented by changing your u-boot and extlinux to +use a slower baud rate. 9600 is very safe, anything up to about +57600 should be fine — start slow and work up.
    • +
+ +

If you need the faster baud rates (or don’t want to change the default +settings), use a 1V8 USB-TTL cable and plug it straight into the +TK1 as usual. This will be fixed in a future revision.

+ +

TK1 SOC Connections

+ +

Useful for writing drivers - this is a list of +which pins on the board correspond to which SOC pins:

+ +
+
+ + Note +
+
+ +

All I2C signals operate at 3V3 on their 0.1” headers, except +I2C_CAM which is selectable from 1V8<->3V3 in software.

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PINBALLPERIPHERAL ID
I2C_CAM_SCLAF8I2C3_CLK
I2C_CAM_SDAAG8I2C3_DAT
I2C_TK1_SCLY2I2C2_CLK
I2C_TK1_SDAAA2I2C2_DAT
I2C_LOCAL_SCLP6I2C1_CLK
I2C_LOCAL_SDAM6I2C1_DAT
+ +

All SPI signals out of the TK1 are at 1V8, but are translated to 3V3 by +the board (the 0.1” header operates at 3V3)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PINBALLPERIPHERAL ID
SPI_CLKAG15SPI1A_SCK
SPI_MISOAL18SPI1A_DIN
SPI_CSNAL16SPI1A_CS0
SPI_MOSIAK17SPI1A_DOUT
+ +

All UART signals out of the TK1 are at 1V8, but are translated to 3V3 by +the board. Note that UART signals will only be present on the board +outputs if the uart is actually jumpered to the converter!

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PINBALLPERIPHERAL ID
J8_RTSnV5UD3_RTS
J8_CTSnV9UD3_CTS
J8_TXDV4UD3_TXD
J8_RXDU4UD3_RXD
J2000_RXDL0UART2_RTS_N
J2000_TXDM8UART2_CTS_N
J2000_CTSnM1UART2_TXD
J2000_RTSnP4UART2_RXD
+ +

Note that TXD (1V8) is translated to TXD (3V3). NOT TXD (1V8) <-> +RXD (1V8). This means that the jumper from the TK1-SOM should go from +it’s TX to RX on the daughterboard for a standard ftdi pinout to work.

+ +

Note that GPIOs aren’t actually brought out by the board but they are +used by the CAN controller (diagram below).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PINBALLPERIPHERAL ID
TK1_GPIO0AF29GPIO3_PS.05
TK1_GPIO1AA26GPIO3_PT.00
TK1_GPIO2AC30GPIO3_PS.06
TK1_GPIO3AA31GPIO3_PS.02
TK1_GPIO4V28GPIO3_PS.03
TK1_GPIO5W31GPIO3_PR.00
TK1_GPIO6AB31GPIO3_PR.06
TK1_GPIO7Y27GPIO3_PS.04
+ +

CAN Controller (MCP25625) GPIO Usage:

+

MCP25625 pinout

+ +

Construction Information

+ + + + + + + + + + + + + + + + + + + + +
Schematiccanboard_v3.pdf
PCB Sources Repositoryhttps://bitbucket.csiro.au/projects/OH/repos/tk1som-can-daughterboard
Gerber Files (in repo also)Tegra_CANboard_tofab_v1.zip
BOM (in repo also)CanBoardBOMDraft1.xlsx
+ +

Construction notes

+

Components R6, R14, R19, R23 should NOT be +mounted. R6 and R19 are pull-up resistors that were found to cause +signal integrity issues, the other 2 resistors when mounted will supply +5v to the CAN lines and are optional.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/CEI_TK1_SOM/CANBoard/index.md b/Hardware/CEI_TK1_SOM/CANBoard/index.md deleted file mode 100644 index ce901f4c4df..00000000000 --- a/Hardware/CEI_TK1_SOM/CANBoard/index.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# The CAN Daughterboard - -The CAN Daughterboard is an open-hardware -**CAN/SPI/I2C/Serial board** designed by the Trustworthy Systems group, -that can be mounted below the power supply module of -the TK1-SOM. It provides **two CAN buses** implemented with MCP2515 -(on the TK1-SOM's SPI bus) and voltage conversion for the two serial -ports. - -Top of board -Bottom of board -Side view of mounted stack - -## Mounting - The board attaches to the bottom of a TK1-SOM via the -expansion connector. No further work should be needed to enumerate the -device given a kernel supporting GPIO chipselects. - -Note the unpopulated standoff holes on the rightmost image above --- it -is possible to fit a standoff of the same type already installed in the -TK1-SOM to stabilize the 'tower' making it easier to work with. - -The part numbers of the standoffs between the CAN daughterboard and TK1 -is the same as is already used between the CPU & GPU board. Order codes: - -+ **STANDOFF** - HEX M2.5 x 16MM ALUMINUM M-F (M2111-2545-AL) - between pcb standoff -+ **SCREW** - M2.5 x 5 MM SS PAN HEAD PHILIPS (92000A103) bottom - pcb screw - -## Using Linux with this daughterboard for CAN -(**hello world & testing**) See [Using CAN on L4T through an MCP251X](../L4TCan) - -## Pinout detail - The font on the silkscreen indicating pins is -difficult to see once the tower is assembled (wasn't enough space on the -top) - See this picture (view taken from **bottom**): - -![Silk Screen](silk.png) - -### Warning - UART Level Converter: - - -- If using the level converter on the board, and if you are - getting **junk from your 3V3 serial cable**, read this: -- Unfortunately there is an issue with these level converter - chips, in some impedance situations the rise time is much worse - than indicated on the datasheet. Basically, with some serial - cables the converter will garble signals at a high baud rate - (> 57600). -- This can be circumvented by changing your u-boot and extlinux to - use a slower baud rate. 9600 is very safe, anything up to about - 57600 should be fine --- start slow and work up. - -If you need the faster baud rates (or don't want to change the default -settings), **use a 1V8 USB-TTL cable** and plug it straight into the -TK1 as usual. This will be fixed in a future revision. - -## TK1 SOC Connections - -Useful for writing drivers - this is a list of -which pins on the board correspond to which SOC pins: - -{% include note.html %} -All I2C signals operate at 3V3 on their 0.1" headers, except -I2C_CAM which is selectable from 1V8<->3V3 in software. -{% include endnote.html %} - -| PIN | BALL | PERIPHERAL ID | -|--------------|---------|------------------| -|I2C_CAM_SCL |AF8 |I2C3_CLK | -|I2C_CAM_SDA |AG8 |I2C3_DAT | -|I2C_TK1_SCL |Y2 |I2C2_CLK | -|I2C_TK1_SDA |AA2 |I2C2_DAT | -|I2C_LOCAL_SCL |P6 |I2C1_CLK | -|I2C_LOCAL_SDA |M6 |I2C1_DAT | - -All SPI signals out of the TK1 are at 1V8, but are translated to 3V3 by -the board (the 0.1" header operates at 3V3) - -| PIN | BALL | PERIPHERAL ID | -|---------|---------|------------------| -|SPI_CLK |AG15 |SPI1A_SCK | -|SPI_MISO |AL18 |SPI1A_DIN | -|SPI_CSN |AL16 |SPI1A_CS0 | -|SPI_MOSI |AK17 |SPI1A_DOUT | - -All UART signals out of the TK1 are at 1V8, but are translated to 3V3 by -the board. Note that UART signals will only be present on the board -outputs if the uart is actually jumpered to the converter! - -| PIN | BALL | PERIPHERAL ID | -|-----------|---------|------------------| -|J8_RTSn |V5 |UD3_RTS | -|J8_CTSn |V9 |UD3_CTS | -|J8_TXD |V4 |UD3_TXD | -|J8_RXD |U4 |UD3_RXD | -|J2000_RXD |L0 |UART2_RTS_N | -|J2000_TXD |M8 |UART2_CTS_N | -|J2000_CTSn |M1 |UART2_TXD | -|J2000_RTSn |P4 |UART2_RXD | - -Note that TXD (1V8) is translated to TXD (3V3). NOT TXD (1V8) <-> -RXD (1V8). This means that the jumper from the TK1-SOM should go from -it's TX to RX on the daughterboard for a standard ftdi pinout to work. - -Note that GPIOs aren't actually brought out by the board but they are -used by the CAN controller (diagram below). - -| PIN | BALL | PERIPHERAL ID | -|----------|--------|------------------| -|TK1_GPIO0 |AF29 |GPIO3_PS.05 | -|TK1_GPIO1 |AA26 |GPIO3_PT.00 | -|TK1_GPIO2 |AC30 |GPIO3_PS.06 | -|TK1_GPIO3 |AA31 |GPIO3_PS.02 | -|TK1_GPIO4 |V28 |GPIO3_PS.03 | -|TK1_GPIO5 |W31 |GPIO3_PR.00 | -|TK1_GPIO6 |AB31 |GPIO3_PR.06 | -|TK1_GPIO7 |Y27 |GPIO3_PS.04 | - - - -### CAN Controller (MCP25625) GPIO Usage: -MCP25625 pinout - -## Construction Information - -|Schematic |[canboard_v3.pdf](canboard_v3.pdf) | -|PCB Sources Repository |https://bitbucket.csiro.au/projects/OH/repos/tk1som-can-daughterboard| -|Gerber Files (in repo also)|[Tegra_CANboard_tofab_v1.zip](Tegra_CANboard_tofab_v1.zip) | -|BOM (in repo also) |[CanBoardBOMDraft1.xlsx](CanBoardBOMDraft1.xlsx) | - -## Construction notes - Components **R6, R14, R19, R23 should NOT be -mounted**. R6 and R19 are pull-up resistors that were found to cause -signal integrity issues, the other 2 resistors when mounted will supply -5v to the CAN lines and are optional. diff --git a/Hardware/CEI_TK1_SOM/DaughterBoard/index.html b/Hardware/CEI_TK1_SOM/DaughterBoard/index.html new file mode 100644 index 00000000000..a17c50539b8 --- /dev/null +++ b/Hardware/CEI_TK1_SOM/DaughterBoard/index.html @@ -0,0 +1,904 @@ + + + + + + + The TK1-SOM Daughterboard | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

The TK1-SOM Daughterboard

+ +

The TK1-SOM Daughterboard is an +open-hardware daughterboard designed by the Trustworthy Systems group +that can be mounted to the TK1-SOM. It provides CAN +buses, serial,sensors, power management, PWM +outputs and other features that allow the TK1-SOM to be used as a +flight controller for a quadcopter.

+ +

Warning

+ +
    +
  • Don’t plug in or unplug things from the daughterboard while it + is turned on, especially the radio. The current transient will + sometimes kill U13 (TPS563200 5V regulator). If only 1 of the + LEDs above the white molex connector is lit, it is because U13 + is dead.
    • +
+ +

Rough overview (top)

+ +

Top of board

+ +

Rough overview (bottom)

+ +

Bottom of board

+ +

With TK1

+

Daughterboard with TK1

+ +

Technical documentation

+ + + +

Connecting the Daughterboard

+

Going from a TK1-SOM, a pixhawk/IRIS +and a daughterboard to a functioning system requires:

+ + + +

Mounting the TK1 to the daughterboard

+

Before mounting the +TK1-SOM to the daughterboard, you will have to disassemble the TK1-SOM. +This will involve:

+ +
    +
  • Removing the fan screw
    • +
  • Unscrewing the standoffs
    • +
  • Separating the 2 module ‘halves’
    • +
  • Removing the fan connector
    • +
+ +

This must be done with care as it is easy to damage the TK1. Your goal +is this:

+ +

TK1 disassembled

+ +

Now you can start attaching the TK1 to the daughterboard. It’s easy to +identify which half goes where by looking at the connectors on the +bottom, or the overview at the top of this page.

+ +

Firmly press both of the TK1 halves into their sockets. Try to use +unpopulated parts of the PCB as ‘finger positions’ to avoid damaging +components or connectors.

+ +
+
+ + Note +
+
+ +

Standoffs can optionally be added in this step for extra support +(the friction fit supplied by the TK1 connectors should be more than +sufficient in most cases). Each module has a single standoff point for +an M2.5 screw, bolt, and standoff:

+ +

Standoff fitted

+ +

The end result should look like the image under With TK1 near the top of this page

+ +
+
+ +

Jumpering the UART level translators

+

For the daughterboard to do +any level translation, it needs to be connected to the TK1’s UARTs. We +achieve this by jumpering the TK1’s UARTs to the ‘UART TK1’ connector on +the daughterboard. (See ‘rough overview’, top view)

+ +

The pinout of the TK1’s UARTS is the same as the pinout of the +daughterboard’s UART inputs. Observe:

+ +

UART 1 on TK1

+ +

UART 2 on TK1

+ +

UARTs on daughterboard

+ +

The pinout of the TK1 UARTS is:

+ + + + + + + + + + + + + + + + + + + + +
PIN 1RX
PIN 2TX
PIN 3CTS-L
PIN 4RTS-L
+ +

Since we aren’t using flow control, you only need to connect pin 1 (TK1) +to pin 1 (daughterboard), and pin 2 - pin 2 for both UARTS. You should +end up with:

+ +

UARTs jumpered

+ +

Note: On this board, UART1 is connected to the RADIO output, the +FTDI port, and the activity LEDs. UART2 is connected to the GPS output. +It is possible to swap these at the TK1 input side without consequence +(this would put the kernel dump through the GPS output, and UART2 +through telemetry). Additionally, one can disconnect these jumpers and +use an ‘ordinary’ 1V8 converter for debugging (See +debugging & grounds below).

+ +

Jumpering the RESET button

+

It’s difficult to access the TK1’s +reset button when it is mounted, so there is a secondary reset button on +the daughterboard that can optionally be used. First, you must solder a +pin to the hole next to the reset switch on the TK1 (as RESET isn’t +brought out on any of its connectors):

+ +

Reset pin soldered to the TK1

+ +

From here, you want to jumper this pin to the ‘RESET’ pin on the +daughterboard (This is the pin just to the right of the grey switch):

+ +

Reset button and pin on daughterboard

+ +

Your end result is:

+ +

Reset pin jumpered

+ +
+
+ + Note +
+
+ +

As this reset switch is just a momentary short to ground, it is +very easy to make your own reset switch that may be larger or more +conveniently mounted elsewhere on the quadcopter. Essentially you just +need a momentary switch between the TK1 pin and ground - the signal is +debounced etc on the TK1.

+ +
+
+ +

Attaching the pixhawk power cable

+

–(The pixhawk power cable is +how the daughterboard delivers power to the pixhawk. Note that this is +very different to the previous daughterboards - we do not use the IRIS’ +power output (that would normally go into the pixhawk) for +anything.)–OUTDATED DUE TO POSSIBLE RAIL INTERACTION

+ +

The pixhawk should be connected to the IRIS power supply as it would be +in a vanilla configuration, to avoid any interaction with the +daughterboard’s rails. Do NOT connect anything to the daughterboard’s +‘Power out to Pixhawk’ connector.

+ +

Attaching the CAN bus cable

+

The CAN1 connector we are using +(labelled ‘PRIMARY CAN CONNECTOR’ on ‘Rough overview - Top’ at the top +of this page) is directly connected to the CAN port on the pixhawk. +Connect one end of the 4-pin DF13 connector to the pixhawk, and the +other to the daughterboard:

+ +

CAN connector on daughterboard

+ +

The left arrow points to the connector. The right arrow points to the +endpoint selection jumper. If the endpoint selection jumper is closed, +CAN1 will be terminated as an endpoint. In our situation, the pixhawk +and the daughterboard are endpoints, so the jumper should be closed for +CAN1.

+ +

Note that the connectors on the bottom and the top of the board are +connected in parallel so that the board can be used in more complex +network topologies, i.e the 2 left connectors are CAN1, and the 2 right +connectors are CAN2.

+ +

Attaching the telemetry cable

+

The telemetry connector to be +connected to the 3DR RADIO has a ‘RADIO’ label, and it is next to the +GPS connector - see ‘Rough Overview - Bottom’, above.

+ +

To connect it, find the 3DR RADIO cable inside the IRIS and just plug it +in:

+ +

3DR Radio connected to daughterboard

+ +

Connecting the power harness

+

The power harness is how the +daughterboard supplies power to the TK1-SOM, and also how it intercepts +power from the IRIS’ batteries (if it is running on batteries). This is +the power harness:

+ +

The power harness

+ +

To connect it, plug in the molex connector under the daughterboard, and +then plug into the TK1-SOM’s barrel jack. Do NOT plug this into the +‘+12V IN’ barrel jack on the side of the daughterboard. This is what you +want:

+ +

The power harness plugged in

+ +

Connecting the battery OR external PSU

+

There are 2 ways of +powering up the daughterboard and pixhawk:

+ +
    +
  • 1: Using the TK1-SOM’s ordinary power supply (for testing)
    • +
  • 2: Using the LIPO battery on the quadcopter (for demoing)
    • +
+ +

The only difference from a functional point of view is that option 1 +will only power the pixhawk, daughterboard, and TK1-SOM; not the rest of +the quadcopter. The LIPO will do the same, but also provide power for +the rotors etc.

+ +

Note that in both cases the power harness must be connected to supply +the TK1-SOM with power. If the TK1 power supply is used, the yellow +battery connectors should be unplugged.

+ +

In any case, for option 1: simply plug in the TK1 power supply to the +‘+12V IN’ jack (See ‘Rough overview’ - Top):

+ +

Powered with ordinary TK1 PSU

+ +

The TK1 and daughterboard will all turn on. (And the pixhawk if it is +connected unlike the above picture)

+ +

For option 2: Connect one end of the power harness to the main IRIS +power input:

+ +

Connecting to IRIS internal main power connector

+ +

and the other end to the battery: (Follow ordinary 3DR procedures before +doing this as it will turn everything on)

+ +

Connecting the battery

+ +

Similarly, everything should turn on as pictured.

+ +

Everything connected

+

Slightly more close-up photo of everything +connected and turned on: +Everything connected

+ +

Debugging output and finding grounds

+

To use an ‘ordinary’ 1V8 +converter and debug things, you will likely want to:

+ +
    +
  • Connect the 1V8 converter to the primary UART on the TK1 (on + the top) for kernel messages
    • +
  • Swap UART1 with UART2 into the daughterboard, making the secondary + UART go through telemetry. (i.e connect UART2 (TK1) to + UART1 (Daughterboard) to get the secondary UART through telem)
    • +
+ +

Our 1V8 converters have the following pinout:

+ +

Everything connected

+ +

You want to connect TX (converter) to RX on the TK1, and RX (converter) +to TX on the TK1. You also need to connect a ground, which you can find +all along the bottom row of the servo connector:

+ +

Everything connected

+ +

(The entire bottom row is connected to ground)

+ +

Errata

+ +

Technical errata for R3A, to be fixed next revision

+ +
    +
  • The ‘power out to pixhawk’ connection on the daughterboard + should not be used as it may cause a rail collision.
    • +
  • All I2C lines CLK and DAT lines are reversed due to an error in + the schematic supplied to us by CEI; this has been modwired to + the correct connection on some boards.
    • +
  • U8 (LSM303D, one of the many inertial sensors) is not mounted + due to a footprint error.
    • +
  • D10 & D11 CAN Reset diodes are not mounted on some boards. This + has been tested OK, the diodes are just to improve CAN chip + reset times - but we aren’t actually using the CAN reset line.
    • +
  • R35 & R45 to supply power through the CAN ports –(ARE)– ARE + NOT mounted, and should never be to avoid rail collisions.
    • +
  • The LV cutout circuitry does not work. Since the IRIS battery is + disconnected when not in use anyway, this should not be a + huge issue. UPDATE: Reason is footprint error with TLV431 chip, + swapping A/K fixes issue.
    • +
  • On schematic sheet 5, the ‘Do not populate’ remarks indicate the + wrong designators. They should indicate R35 & R45.
    • +
  • R40 & R49 pull-ups on the SPI CSN line are not mounted. These + were found to cause signal integrity issues. Additionally, the + silkscreen for R51 and R49 is swapped on the PCB.
    • +
  • R57 - R72 (Current limiting resistors for D12-D27), a value of + 560 ohm was used instead of 10K ohm to increase + their brightness.
    • +
+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/CEI_TK1_SOM/DaughterBoard/index.md b/Hardware/CEI_TK1_SOM/DaughterBoard/index.md deleted file mode 100644 index d0a68f9960a..00000000000 --- a/Hardware/CEI_TK1_SOM/DaughterBoard/index.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# The TK1-SOM Daughterboard - -The TK1-SOM Daughterboard is an -open-hardware daughterboard designed by the Trustworthy Systems group -that can be mounted to the TK1-SOM. It provides **CAN -buses**, **serial**,**sensors**, **power management**, **PWM -outputs** and other features that allow the TK1-SOM to be used as a -flight controller for a quadcopter. - -### Warning - - -- Don't plug in or unplug things from the daughterboard while it - is turned on, especially the radio. The current transient will - sometimes kill U13 (TPS563200 5V regulator). If only 1 of the - LEDs above the white molex connector is lit, it is because U13 - is dead. - -### Rough overview (top) - -Top of -board - -### Rough overview (bottom) - -Bottom of board - -### With TK1 -Daughterboard -with TK1 - -## Technical documentation - - -- [Schematic PDF](daughterboard_r3a_schematic.pdf) (See '[Technical errata for R3A](#errata)' - for changes) -- Bill of Materials: - [tegra_daughterboard_bom3.xls](tegra_daughterboard_bom3.xls) -- Project repository: - [Altium files](https://bitbucket.csiro.au/projects/OH/repos/tk1som-quadcopter-daughterboard) - -## Connecting the Daughterboard - Going from a TK1-SOM, a pixhawk/IRIS -and a daughterboard to a functioning system requires: - -- [Technical documentation](#technical-documentation) -- [Connecting the Daughterboard](#connecting-the-daughterboard) - - [Mounting the TK1 to the daughterboard](#mounting-the-tk1-to-the-daughterboard) - - [Jumpering the UART level translators](#jumpering-the-uart-level-translators) - - [Jumpering the RESET button](#jumpering-the-reset-button) - - [Attaching the pixhawk power cable](#attaching-the-pixhawk-power-cable) - - [Attaching the CAN bus cable](#attaching-the-can-bus-cable) - - [Attaching the telemetry cable](#attaching-the-telemetry-cable) - - [Connecting the power harness](#connecting-the-power-harness) - - [Connecting the battery OR external PSU](#connecting-the-battery-or-external-psu) - - [Everything connected](#everything-connected) - - [Debugging output and finding grounds](#debugging-output-and-finding-grounds) -- [Errata](#errata) - - [Technical errata for R3A, to be fixed next revision](#technical-errata-for-r3a-to-be-fixed-next-revision) - -### Mounting the TK1 to the daughterboard - Before mounting the -TK1-SOM to the daughterboard, you will have to disassemble the TK1-SOM. -This will involve: - -- Removing the fan screw -- Unscrewing the standoffs -- Separating the 2 module 'halves' -- Removing the fan connector - -This must be done with care as it is easy to damage the TK1. Your goal -is this: - -TK1 disassembled - -Now you can start attaching the TK1 to the daughterboard. It's easy to -identify which half goes where by looking at the connectors on the -bottom, or the overview at the top of this page. - -Firmly press both of the TK1 halves into their sockets. Try to use -unpopulated parts of the PCB as 'finger positions' to avoid damaging -components or connectors. - -{% include note.html %} -Standoffs can optionally be added in this step for extra support -(the friction fit supplied by the TK1 connectors should be more than -sufficient in most cases). Each module has a single standoff point for -an M2.5 screw, bolt, and standoff: - -Standoff fitted - -The end result should look like the image under [With TK1](#with-tk1) near the top of this page -{% include endnote.html %} - -### Jumpering the UART level translators - For the daughterboard to do -any level translation, it needs to be connected to the TK1's UARTs. We -achieve this by jumpering the TK1's UARTs to the 'UART TK1' connector on -the daughterboard. (See 'rough overview', top view) - -The pinout of the TK1's UARTS is the same as the pinout of the -daughterboard's UART inputs. Observe: - -UART 1 on TK1 - -UART 2 on TK1 - -UARTs on daughterboard - -The pinout of the TK1 UARTS is: - -|PIN 1 |RX | -|PIN 2 |TX | -|PIN 3 |CTS-L | -|PIN 4 |RTS-L | - -Since we aren't using flow control, you only need to connect pin 1 (TK1) -to pin 1 (daughterboard), and pin 2 - pin 2 for both UARTS. You should -end up with: - -UARTs jumpered - -**Note**: On this board, UART1 is connected to the RADIO output, the -FTDI port, and the activity LEDs. UART2 is connected to the GPS output. -It is possible to swap these at the TK1 input side without consequence -(this would put the kernel dump through the GPS output, and UART2 -through telemetry). Additionally, one can disconnect these jumpers and -use an 'ordinary' 1V8 converter for debugging (See -[debugging & grounds](#debugging-output-and-finding-grounds) below). - -### Jumpering the RESET button - It's difficult to access the TK1's -reset button when it is mounted, so there is a secondary reset button on -the daughterboard that can optionally be used. First, you must solder a -pin to the hole next to the reset switch on the TK1 (as RESET isn't -brought out on any of its connectors): - -Reset pin soldered to the -TK1 - -From here, you want to jumper this pin to the 'RESET' pin on the -daughterboard (This is the pin just to the right of the grey switch): - -Reset button and pin on -daughterboard - -Your end result is: - -Reset pin jumpered - -{% include note.html %} -As this reset switch is just a momentary short to ground, it is -very easy to make your own reset switch that may be larger or more -conveniently mounted elsewhere on the quadcopter. Essentially you just -need a momentary switch between the TK1 pin and ground - the signal is -debounced etc on the TK1. -{% include endnote.html %} - -### Attaching the pixhawk power cable - --(The pixhawk power cable is -how the daughterboard delivers power to the pixhawk. Note that this is -very different to the previous daughterboards - we do not use the IRIS' -power output (that would normally go into the pixhawk) for -anything.)--OUTDATED DUE TO POSSIBLE RAIL INTERACTION - -The pixhawk should be connected to the IRIS power supply as it would be -in a vanilla configuration, to avoid any interaction with the -daughterboard's rails. Do NOT connect anything to the daughterboard's -'Power out to Pixhawk' connector. - -### Attaching the CAN bus cable - The CAN1 connector we are using -(labelled 'PRIMARY CAN CONNECTOR' on 'Rough overview - Top' at the top -of this page) is directly connected to the CAN port on the pixhawk. -Connect one end of the 4-pin DF13 connector to the pixhawk, and the -other to the daughterboard: - -CAN connector on daughterboard - -The left arrow points to the connector. The right arrow points to the -endpoint selection jumper. If the endpoint selection jumper is closed, -CAN1 will be terminated as an endpoint. In our situation, the pixhawk -and the daughterboard are endpoints, so the jumper should be closed for -CAN1. - -Note that the connectors on the bottom and the top of the board are -connected in parallel so that the board can be used in more complex -network topologies, i.e the 2 left connectors are CAN1, and the 2 right -connectors are CAN2. - -### Attaching the telemetry cable - The telemetry connector to be -connected to the 3DR RADIO has a 'RADIO' label, and it is next to the -GPS connector - see 'Rough Overview - Bottom', above. - -To connect it, find the 3DR RADIO cable inside the IRIS and just plug it -in: - -3DR Radio connected to -daughterboard - -### Connecting the power harness - The power harness is how the -daughterboard supplies power to the TK1-SOM, and also how it intercepts -power from the IRIS' batteries (if it is running on batteries). This is -the power harness: - -The power harness - -To connect it, plug in the molex connector under the daughterboard, and -then plug into the TK1-SOM's barrel jack. Do NOT plug this into the -'+12V IN' barrel jack on the side of the daughterboard. This is what you -want: - -The power harness plugged in - -### Connecting the battery OR external PSU - There are 2 ways of -powering up the daughterboard and pixhawk: - -- 1: Using the TK1-SOM's ordinary power supply (for testing) -- 2: Using the LIPO battery on the quadcopter (for demoing) - -The only difference from a functional point of view is that option 1 -will only power the pixhawk, daughterboard, and TK1-SOM; not the rest of -the quadcopter. The LIPO will do the same, but also provide power for -the rotors etc. - -Note that in both cases the power harness must be connected to supply -the TK1-SOM with power. If the TK1 power supply is used, the yellow -battery connectors should be unplugged. - -In any case, for option 1: simply plug in the TK1 power supply to the -'+12V IN' jack (See 'Rough overview' - Top): - -Powered with ordinary TK1 -PSU - -The TK1 and daughterboard will all turn on. (And the pixhawk if it is -connected unlike the above picture) - -For option 2: Connect one end of the power harness to the main IRIS -power input: - -Connecting to IRIS internal main -power connector - -and the other end to the battery: (Follow ordinary 3DR procedures before -doing this as it will turn everything on) - -Connecting the battery - -Similarly, everything should turn on as pictured. - -### Everything connected - Slightly more close-up photo of everything -connected and turned on: -Everything -connected - -### Debugging output and finding grounds - To use an 'ordinary' 1V8 -converter and debug things, you will likely want to: - -- Connect the 1V8 converter to the primary UART on the TK1 (on - the top) for kernel messages -- Swap UART1 with UART2 into the daughterboard, making the secondary - UART go through telemetry. (i.e connect UART2 (TK1) to - UART1 (Daughterboard) to get the secondary UART through telem) - -Our 1V8 converters have the following pinout: - -Everything connected - -You want to connect TX (converter) to RX on the TK1, and RX (converter) -to TX on the TK1. You also need to connect a ground, which you can find -all along the bottom row of the servo connector: - -Everything connected - -(The entire bottom row is connected to ground) - -## Errata - -### Technical errata for R3A, to be fixed next revision - - -- The 'power out to pixhawk' connection on the daughterboard - should not be used as it may cause a rail collision. -- All I2C lines CLK and DAT lines are reversed due to an error in - the schematic supplied to us by CEI; this has been modwired to - the correct connection on some boards. -- U8 (LSM303D, one of the many inertial sensors) is not mounted - due to a footprint error. -- D10 & D11 CAN Reset diodes are not mounted on some boards. This - has been tested OK, the diodes are just to improve CAN chip - reset times - but we aren't actually using the CAN reset line. -- R35 & R45 to supply power through the CAN ports --(ARE)-- ARE - NOT mounted, and should never be to avoid rail collisions. -- The LV cutout circuitry does not work. Since the IRIS battery is - disconnected when not in use anyway, this should not be a - huge issue. UPDATE: Reason is footprint error with TLV431 chip, - swapping A/K fixes issue. -- On schematic sheet 5, the 'Do not populate' remarks indicate the - wrong designators. They should indicate R35 & R45. -- R40 & R49 pull-ups on the SPI CSN line are not mounted. These - were found to cause signal integrity issues. Additionally, the - silkscreen for R51 and R49 is swapped on the PCB. -- R57 - R72 (Current limiting resistors for D12-D27), a value of - 560 ohm was used instead of 10K ohm to increase - their brightness. - - diff --git a/Hardware/CEI_TK1_SOM/L4TCan/index.html b/Hardware/CEI_TK1_SOM/L4TCan/index.html new file mode 100644 index 00000000000..b3e145553bd --- /dev/null +++ b/Hardware/CEI_TK1_SOM/L4TCan/index.html @@ -0,0 +1,853 @@ + + + + + + + Using CAN on L4T through an MCP251X | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Using CAN on L4T through an MCP251X

+ +

Front view of TK1-Tower +Bottom view of TK1-Tower

+ +

Before running L4TCAN: Jumper HW-based chipselect to the GPIO chipselect

+

Because L4T with CAN doesn’t use GPIO chipselect (yet), +it’s necessary to connect the hardware CSN line to the GPIO used for +chipselect.

+ +

Note that the GPIO dts sets the GPIO used for chipselect to high +impedance so bad things don’t happen.

+ +

CSN is indicated on the SPI expansion header. Can node #1 on the CAN +daughterboard uses TK1_GPIO2, so it’s necessary to connect these 2 +pins:

+ +

Jumper hw-based chipselect to GPIO chipselect

+ +

(From right-to-left on the TK1 GPIO header we have GPIO0, GPIO1, GPIO2)

+ +
+
+ + Note +
+
+ +

On the seL4 side, this may not be necessary as it will be able to +use GPIO-based chipselects.

+ +
+
+ +
+
+ + Note +
+
+ +

Justification for GPIO chipselects is that we have 2 CAN nodes +and only 1 HW chipselect, so had to do it this way.

+ +
+
+ +

Option 1. Use our Linux image

+

Grab the image at tk1_can.img.gz (md5). Make sure to verify against the +md5sum in the same folder once you’ve got it.

+ +

Set up the TK1 as usual - connect the UART as well as the recovery USB +port next to the ethernet jack. Stop u-boot from booting and issue the +command:

+ +
ums 0 mmc 0
+
+

This will allow you to see the TK1’s filesystem on +your host pc. On your host PC, list your devices:

+ +
$ lsblk
+
+

You should see a 14.7GB-ish device with a few +partitions - this is the TK1. (Make sure it is by mounting the largest +partition and looking at the rootfs [making sure to unmount again +before next step!])

+ +

We’re ready to image the TK1. Issue the following command, making +ABSOLUTELY sure that your of=/dev/sdX line is correct so you don’t +accidentally destroy data on your machine. Also, you want /dev/sdX (the +device), NOT /dev/sdX3 (partitions) etc.

+
gunzip -c tk1_can.img.gz | sudo dd of=/dev/<your TK1 device> conv=sync bs=4K status=progress
+
+

This takes ~1.5Hr on my machine to +complete. If dd throws a strange error to do with the ‘status=progress’ +command, you may be using an old version of dd, it’s fine to omit this +command however you will not see a progress bar.

+ +

Once this is complete, exit the ums command in u-boot and attempt to +boot. As long as the can board CS is jumpered to GPIO2, everything +should work.

+ +

You may see some lines after boot like:

+ +
rt5639 0-001c: Failed to set private addr: -121
+
+ +

This is normal, +and everything should work regardless (internet connectivity works fine +on our system). We’ll be looking into the reason for these errors in the +future.

+ +

See bottom of this page for ‘hello-world’-type examples.

+ +

Option 2: compile your own Linux

+

The instructions from here on go +from a vanilla TK1-SOM L4T configuration to one which can support CAN +using the daughterboard.

+ +

Getting native Linux CAN drivers to work on the TK1-SOM requires a bit +of hackery, procedure outlined here.

+ +

Before going ahead with this, follow the TK1-SOM custom kernel +procedure, make sure you can build it and flash to the board

+ +

Add device tree support for MCP251X to L4T & perform driver hacks

+

The kernel that is included in L4T does not support device tree +binding for the mcp251X, so you have to modify the kernel driver.

+ +

Easiest way to do that is to just use mine: (Works with latest L4T from +colorado. Don’t use the upstream NVIDIA L4T)

+ +

Get it here: mcp251x.c

+ +

You want to replace the file in drivers/net/can/mcp251x.c

+ +
+
+ + Note +
+
+ +

This is NOT the same as the file in mainline kernel, it has a hack +that fixes a problem I had with the device tree not recognising clock +nodes.

+ +

This means that this file will only work with an MCP251X that has a +20MHz crystal!

+ +
+
+ +

I’ve also added a lot of debugging information to the driver so that +dmesg is a bit more helpful.

+ +

Look at device tree documentation

+

Device tree documentation does +not exist in the source code as mcp support has been hacked in. Here’s +the docs from mainline:

+ +

.

+

+-   Microchip MCP251X stand-alone CAN controller device tree bindings
+
+Required properties:
+
+- compatible: Should be one of the following:
+      -   "microchip,mcp2510" for MCP2510.
+
+      - "microchip,mcp2515" for MCP2515.
+- reg: SPI chip select.
+- clocks: The clock feeding the CAN controller.
+- interrupt-parent: The parent interrupt controller.
+- interrupts: Should contain IRQ line for the CAN controller.
+
+Optional properties:
+
+- vdd-supply: Regulator that powers the CAN controller.
+- xceiver-supply: Regulator that powers the CAN transceiver.
+
+Example:
+
+  can0: <can@1> {
+
+      compatible = "microchip,mcp2515";
+      reg = <1>;
+      clocks = <&clk24m>;
+      interrupt-parent = <&gpio4>;
+      interrupts = <13 0x2>;
+      vdd-supply = <&reg5v0>;
+      xceiver-supply = <&reg5v0>;
+  };
+
+ +

Modify the device tree

+

Replace the existing .dts files with +tegra124-tk1-som-pm375-000-c00-00.dts

+ +

You also need to remap some GPIOs, swap out the GPIO device tree with +tegra124-tk1-som-gpio-default.dtsi

+ +

Kernel Build Configuration

+

Using make menuconfig, enable CAN and +MCP251X modules. Make sure your .config contains:

+
CONFIG_CAN=m
+CONFIG_CAN_RAW=m
+CONFIG_CAN_BCM=m
+CONFIG_CAN_GW=m
+CONFIG_CAN_VCAN=m
+CONFIG_CAN_DEV=m
+CONFIG_CAN_CALC_BITTIMING=y
+CONFIG_CAN_MCP251X=m
+
+

In addition to +the ‘normal’ tk1-som kernel build settings given by Colorado in their +readme.

+ +

It is up to you whether you would like to leave user-mode SPI drivers in +there or not, they simply won’t load as the CAN dts removes the +user-space SPI device.

+ +

Once we figure out how to do GPIO-muxed chipselect on the TK1SOM +(working on it) it will be possible to use more than one CAN node & +user-space SPI at the same time.

+ +

Enable hardware-based chipselect #0

+

There is a strange old +touch-driver hanging around that needs to be disabled for you to be able +to use hardware CS on the TK1-SOM’s SPI line.

+ +

Originally I pulled it out of the TK1-SOM’s SPI driver, but it turns out +you can disable it in extlinux.conf, which is much simpler.

+ +

in /boot/extlinux/extlinux.conf on your rootfs, find the touch_id=0@0 +line, and change it to touch_id=3@3

+ +

Load everything onto the board

+

You could do something like this:

+ +

update_kernel.sh

+
#!/bin/bash
+
+L4T_DIR=/home/seb/TK1_SOM_2GB_Flashing/Linux_for_Tegra
+SOM_DIR=/mnt/TK1SOM
+
+sudo cp $L4T_DIR/sources/kernel/arch/arm/boot/zImage
+$SOM_DIR/boot/zImage sudo cp
+$L4T_DIR/sources/kernel/arch/arm/boot/dts/tegra124-tk1-som-pm375-000-c00-00.dtb
+$SOM_DIR/boot/tegra124-tk1-som-pm375-000-c00-00.dtb
+
+ +

rebuild.sh - assumes u-boot running umc 0 mmc 0 at <tk1>

+
    make
+
+    make modules
+
+    mount /dev/<tk1> /mnt/TK1SOM
+
+    ./update_kernel.sh
+
+    make modules_install INSTALL_MOD_PATH=/mnt/TK1SOM
+
+    umount /dev/sdb1
+
+ +

Hello, world

+ +

When you boot up Linux login as: ubuntu password ubuntu.

+ +

Then:

+
dmesg | grep mcp # See if the driver loaded properly
+
+[ 618.718288] mcp251x spi0.0: entered mcp251x_can_probe
+[ 618.718296] mcp251x spi0.0: v2
+[ 618.718332] mcp251x spi0.0: got clock
+[ 618.718336] mcp251x spi0.0: finished clock configuration, freq: 20000000
+[ 618.718353] mcp251x spi0.0: allocated CAN device
+[ 618.718358] mcp251x spi0.0: clock prepared for enable
+[ 618.729737] mcp251x spi0.0: configured can netdev
+[ 618.729741] mcp251x spi0.0: power & transceiver regulator pointers OK
+[ 618.729745] mcp251x spi0.0: enabled power
+[ 618.729749] mcp251x spi0.0: about to enable DMA (if required)
+[ 618.729754] mcp251x spi0.0: finished allocating DMA & non-DMA buffers
+[ 618.729757] mcp251x spi0.0: netdev set
+[ 618.729799] mcp251x spi0.0: configured SPI bus
+[ 618.740194] mcp251x spi0.0: CANSTAT 0x80 CANCTRL 0x07
+[ 618.740198] mcp251x spi0.0: successful hardware probe
+[ 618.740795] mcp251x spi0.0: probed
+[ 628.973815] mcp251x spi0.0: CNF: 0x00 0xbf 0x02
+
+ls /sys/class/net # See if the can device is available and what it's called
+can0 dummy0 eth0 ip6tnl0 lo rmnetctl sit0
+
+sudo ip link set can0 up type can bitrate 500000 # Bring it up
+ifconfig                                         # Take a look...
+can0      Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
+          UP RUNNING NOARP MTU:16 Metric:1
+          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
+          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
+          collisions:0 txqueuelen:10{
+          RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
+
+eth0      Link encap:Ethernet HWaddr 00:50:c2:72:00:59
+          inet addr:10.13.1.223 Bcast:10.13.1.255 Mask:255.255.254.0
+          inet6 addr: 2402:1800:4000:1:250:c2ff:fe72:59/64 Scope:Global
+          inet6 addr: fe80::250:c2ff:fe72:59/64 Scope:Link
+------------------------------------------------------------------------
+
+sudo apt-get install can-utils # (make sure to enable universe repository & update)
+cansend can0 5A1#11.22.33.44.55.66.77.88 # Send a packet
+candump can0 # Dump packets
+
+ +

Loopback mode test

+
ip link set can0 type can bitrate 500000 loopback on
+ifconfig can0 up
+candump any,0:0,#FFFFFFFF #In terminal 1
+cansend can0 123#dead     #In terminal 2
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/CEI_TK1_SOM/L4TCan/index.md b/Hardware/CEI_TK1_SOM/L4TCan/index.md deleted file mode 100644 index 24fd33fba21..00000000000 --- a/Hardware/CEI_TK1_SOM/L4TCan/index.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Using CAN on L4T through an MCP251X - -Front view of TK1-Tower -Bottom view of TK1-Tower - -## Before running L4TCAN: Jumper HW-based chipselect to the GPIO chipselect -Because L4T with CAN doesn't use GPIO chipselect (yet), -it's necessary to connect the hardware CSN line to the GPIO used for -chipselect. - -Note that the GPIO dts sets the GPIO used for chipselect to high -impedance so bad things don't happen. - -CSN is indicated on the SPI expansion header. Can node #1 on the CAN -daughterboard uses TK1_GPIO2, so it's necessary to connect these 2 -pins: - -Jumper hw-based chipselect to GPIO chipselect - -(From right-to-left on the TK1 GPIO header we have GPIO0, GPIO1, GPIO2) - -{% include note.html %} -On the seL4 side, this may not be necessary as it will be able to -use GPIO-based chipselects. -{% include endnote.html %} - -{% include note.html %} -Justification for GPIO chipselects is that we have 2 CAN nodes -and only 1 HW chipselect, so had to do it this way. -{% include endnote.html %} - -## Option 1. Use our Linux image -Grab the image at [tk1_can.img.gz] ([md5]). Make sure to verify against the -md5sum in the same folder once you've got it. - -[md5]: https://trustworthy.systems/Downloads/tk1_can/checksum.txt -[tk1_can.img.gz]: https://trustworthy.systems/Downloads/tk1_can/tk1_can.img.gz - -Set up the TK1 as usual - connect the UART as well as the recovery USB -port next to the ethernet jack. Stop u-boot from booting and issue the -command: - -``` -ums 0 mmc 0 -``` -This will allow you to see the TK1's filesystem on -your host pc. On your host PC, list your devices: - -``` -$ lsblk -``` -You should see a 14.7GB-ish device with a few -partitions - this is the TK1. (Make sure it is by mounting the largest -partition and looking at the rootfs [making sure to unmount again -before next step!]) - -We're ready to image the TK1. Issue the following command, making -ABSOLUTELY sure that your of=/dev/sdX line is correct so you don't -accidentally destroy data on your machine. Also, you want /dev/sdX (the -device), NOT /dev/sdX3 (partitions) etc. -``` -gunzip -c tk1_can.img.gz | sudo dd of=/dev/ conv=sync bs=4K status=progress -``` -This takes \~1.5Hr on my machine to -complete. If dd throws a strange error to do with the 'status=progress' -command, you may be using an old version of dd, it's fine to omit this -command however you will not see a progress bar. - -Once this is complete, exit the ums command in u-boot and attempt to -boot. As long as the can board CS is jumpered to GPIO2, everything -should work. - -You may see some lines after boot like: - -``` -rt5639 0-001c: Failed to set private addr: -121 -``` - -This is normal, -and everything should work regardless (internet connectivity works fine -on our system). We'll be looking into the reason for these errors in the -future. - -See bottom of this page for 'hello-world'-type examples. - -## Option 2: compile your own Linux - The instructions from here on go -from a vanilla TK1-SOM L4T configuration to one which can support CAN -using the daughterboard. - -Getting native Linux CAN drivers to work on the TK1-SOM requires a bit -of hackery, procedure outlined here. - -Before going ahead with this, follow the TK1-SOM custom kernel -procedure, make sure you can build it and flash to the board - -### Add device tree support for MCP251X to L4T & perform driver hacks -The kernel that is included in L4T does not support device tree -binding for the mcp251X, so you have to modify the kernel driver. - -Easiest way to do that is to just use mine: (Works with latest L4T from -colorado. Don't use the upstream NVIDIA L4T) - -Get it here: [mcp251x.c](mcp251x.c) - -You want to replace the file in drivers/net/can/mcp251x.c - -{% include note.html %} -This is NOT the same as the file in mainline kernel, it has a hack -that fixes a problem I had with the device tree not recognising clock -nodes. - -This means that this file will only work with an MCP251X that has a -20MHz crystal! -{% include endnote.html %} - -I've also added a lot of debugging information to the driver so that -dmesg is a bit more helpful. - -### Look at device tree documentation - Device tree documentation does -not exist in the source code as mcp support has been hacked in. Here's -the docs from mainline: - - . -``` - -- Microchip MCP251X stand-alone CAN controller device tree bindings - -Required properties: - -- compatible: Should be one of the following: - - "microchip,mcp2510" for MCP2510. - - - "microchip,mcp2515" for MCP2515. -- reg: SPI chip select. -- clocks: The clock feeding the CAN controller. -- interrupt-parent: The parent interrupt controller. -- interrupts: Should contain IRQ line for the CAN controller. - -Optional properties: - -- vdd-supply: Regulator that powers the CAN controller. -- xceiver-supply: Regulator that powers the CAN transceiver. - -Example: - - can0: { - - compatible = "microchip,mcp2515"; - reg = <1>; - clocks = <&clk24m>; - interrupt-parent = <&gpio4>; - interrupts = <13 0x2>; - vdd-supply = <®5v0>; - xceiver-supply = <®5v0>; - }; -``` - -### Modify the device tree - Replace the existing .dts files with -[tegra124-tk1-som-pm375-000-c00-00.dts](tegra124-tk1-som-pm375-000-c00-00.dts) - -You also need to remap some GPIOs, swap out the GPIO device tree with -[tegra124-tk1-som-gpio-default.dtsi](tegra124-tk1-som-gpio-default.dtsi) - -### Kernel Build Configuration - Using make menuconfig, enable CAN and -MCP251X modules. Make sure your .config contains: -``` -CONFIG_CAN=m -CONFIG_CAN_RAW=m -CONFIG_CAN_BCM=m -CONFIG_CAN_GW=m -CONFIG_CAN_VCAN=m -CONFIG_CAN_DEV=m -CONFIG_CAN_CALC_BITTIMING=y -CONFIG_CAN_MCP251X=m -``` -In addition to -the 'normal' tk1-som kernel build settings given by Colorado in their -readme. - -It is up to you whether you would like to leave user-mode SPI drivers in -there or not, they simply won't load as the CAN dts removes the -user-space SPI device. - -Once we figure out how to do GPIO-muxed chipselect on the TK1SOM -(working on it) it will be possible to use more than one CAN node & -user-space SPI at the same time. - -### Enable hardware-based chipselect #0 - There is a strange old -touch-driver hanging around that needs to be disabled for you to be able -to use hardware CS on the TK1-SOM's SPI line. - -Originally I pulled it out of the TK1-SOM's SPI driver, but it turns out -you can disable it in extlinux.conf, which is much simpler. - -in /boot/extlinux/extlinux.conf on your rootfs, find the touch_id=0@0 -line, and change it to touch_id=3@3 - -### Load everything onto the board - You could do something like this: - -update_kernel.sh -```bash -#!/bin/bash - -L4T_DIR=/home/seb/TK1_SOM_2GB_Flashing/Linux_for_Tegra -SOM_DIR=/mnt/TK1SOM - -sudo cp $L4T_DIR/sources/kernel/arch/arm/boot/zImage -$SOM_DIR/boot/zImage sudo cp -$L4T_DIR/sources/kernel/arch/arm/boot/dts/tegra124-tk1-som-pm375-000-c00-00.dtb -$SOM_DIR/boot/tegra124-tk1-som-pm375-000-c00-00.dtb -``` - -rebuild.sh - assumes u-boot running `umc 0 mmc 0` at `` -``` - make - - make modules - - mount /dev/ /mnt/TK1SOM - - ./update_kernel.sh - - make modules_install INSTALL_MOD_PATH=/mnt/TK1SOM - - umount /dev/sdb1 -``` - -# Hello, world - - -When you boot up Linux login as: ubuntu password ubuntu. - -Then: -``` -dmesg | grep mcp # See if the driver loaded properly - -[ 618.718288] mcp251x spi0.0: entered mcp251x_can_probe -[ 618.718296] mcp251x spi0.0: v2 -[ 618.718332] mcp251x spi0.0: got clock -[ 618.718336] mcp251x spi0.0: finished clock configuration, freq: 20000000 -[ 618.718353] mcp251x spi0.0: allocated CAN device -[ 618.718358] mcp251x spi0.0: clock prepared for enable -[ 618.729737] mcp251x spi0.0: configured can netdev -[ 618.729741] mcp251x spi0.0: power & transceiver regulator pointers OK -[ 618.729745] mcp251x spi0.0: enabled power -[ 618.729749] mcp251x spi0.0: about to enable DMA (if required) -[ 618.729754] mcp251x spi0.0: finished allocating DMA & non-DMA buffers -[ 618.729757] mcp251x spi0.0: netdev set -[ 618.729799] mcp251x spi0.0: configured SPI bus -[ 618.740194] mcp251x spi0.0: CANSTAT 0x80 CANCTRL 0x07 -[ 618.740198] mcp251x spi0.0: successful hardware probe -[ 618.740795] mcp251x spi0.0: probed -[ 628.973815] mcp251x spi0.0: CNF: 0x00 0xbf 0x02 - -ls /sys/class/net # See if the can device is available and what it's called -can0 dummy0 eth0 ip6tnl0 lo rmnetctl sit0 - -sudo ip link set can0 up type can bitrate 500000 # Bring it up -ifconfig # Take a look... -can0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 - UP RUNNING NOARP MTU:16 Metric:1 - RX packets:0 errors:0 dropped:0 overruns:0 frame:0 - TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 - collisions:0 txqueuelen:10{ - RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) - -eth0 Link encap:Ethernet HWaddr 00:50:c2:72:00:59 - inet addr:10.13.1.223 Bcast:10.13.1.255 Mask:255.255.254.0 - inet6 addr: 2402:1800:4000:1:250:c2ff:fe72:59/64 Scope:Global - inet6 addr: fe80::250:c2ff:fe72:59/64 Scope:Link ------------------------------------------------------------------------- - -sudo apt-get install can-utils # (make sure to enable universe repository & update) -cansend can0 5A1#11.22.33.44.55.66.77.88 # Send a packet -candump can0 # Dump packets -``` - -# Loopback mode test -``` -ip link set can0 type can bitrate 500000 loopback on -ifconfig can0 up -candump any,0:0,#FFFFFFFF #In terminal 1 -cansend can0 123#dead #In terminal 2 -``` diff --git a/Hardware/CEI_TK1_SOM/LogicPro8/index.html b/Hardware/CEI_TK1_SOM/LogicPro8/index.html new file mode 100644 index 00000000000..1f9abbb172d --- /dev/null +++ b/Hardware/CEI_TK1_SOM/LogicPro8/index.html @@ -0,0 +1,668 @@ + + + + + + + Using the Saleae Logic Pro 8 to debug a CAN bus | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Using the Saleae Logic Pro 8 to debug a CAN bus

+ +

Introduction

+ +

This page is a quick write up of how we used a logic analyzer to help +solve a message loss issue when using a CAN bus. We had two TK1-SOMs +connected together on a CAN bus. One of them runs Linux natively and the +other runs an seL4 CAmkES application that receives CAN frames and then +prints them out. We found that although the CAmkES application could +correctly receive and reply to individual CAN frames, when frames were +being received at the maximum rate of the bus the CAmkES application +would only print out the first, last and occasionally a frame in the +middle. Read more about CAN +here, and +here is the Saleae Logic Pro 8 +site. Information about the TK1-SOM daughter board that we use is +here.

+ +

Photo of CAN connected between two TK1-SOMs

+ +

Setup

+ +

Each of the TK1-SOMs have a daughter board with a MCP25625 +CAN controller on them that can communicate with the processor over SPI. +When a controller receives a CAN message it notifies the processor by +interrupting it over a GPIO line. The processor then reads the CAN +message out of the controller over SPI. We can use the LogicPro8 to +probe the CAN bus, the SPI bus and also the GPIO pin that the interrupt +is received on to get a feel for what is going on.

+ +

Photo of Saleae connected to TK1-SOM

+ +

Connecting to the CAN bus

+ +

Schematic of daughter board

+ +

On our daughter board (schematic above), our CAN bus pins are CAN1H, +CAN1L and GND. The Logic pro only needs to be plugged into CAN1L and GND +in order to decode CAN frames. We connect Channel 0 of the Logic pro as +shown: (Note that the schematic above shows the bottom of the daughter +board. So the order of the pins in the photo is reversed)

+ +

Closeup photo of Saleae connected to TK1-SOm

+ +

Saleae provides the Logic +software which is used to collect and analyse data.

+ +

Screenshot of Logic software

+ +

We configure Logic to collect at a rate of 50MS/s on channel 0 with +3.3+V

+ +

Screenshot of Logic software: Collection bitrate setting menu

+ +

We add CAN as an analyser for Channel 0 and set the bitrate to 125000 +which is what our TK1s are configured to use.

+ +

Screenshot of Logic software: Analyser setting menu +Screenshot of Logic software: Analyser setting menu, sample bitrate setting

+ +

We press start and then send one CAN message from the Linux TK1 to the +seL4 TK1.

+
Native Linux:
+ubuntu@tegra-ubuntu:\~$ cansend can0 5A1#11.22.33.44.55.66.77.88
+
+seL4: Recv: error(0), id(5a1), data(11, 22, 33, 44, 55, 66, 77, 88)
+
+

In Logic we see that we measured the CAN message being transmitted over +the bus. On the side under Decoded protocols Logic reports the fields of +the message that was sent.

+ +

Screenshot of Logic software: CAN Sample result

+ +

Connecting to SPI

+ +

We now connect to the SPI bus. To do this we need to measure the CLK, +MOSI and MISO. (These pins can be found at the bottom of the schematic). +We connect the probe to them as follows:

+ +

Photo of attaching Saleae to SPI bus

+ +

In Logic we add the new channels and configure a SPI analyser for them.

+ +

Screenshot of Logic software: SPI Analyser setting menu

+ +

After running the scan again while sending a CAN message we now see the +CAN frame sent on the bus followed by a few SPI transactions between the +Processor and CAN controller.

+ +

Screenshot of Logic software: SPI Sample result

+ +

Zooming in on a single SPI transaction we see that the CAN driver send +0x03, 0x2C and the CAN controller respond with 0x01. This corresponds to +Read register 0x2C (Interrupt flag register) and the register value +being returned as 0x01 (Message received). Under decoded protocols you +can see both CAN messages and SPI messages that were sent.

+ +

Screenshot of Logic software: SPI Sample result, Zoomed in

+ +

GPIO Interrupt line

+ +

We finally connect the probe to the +interrupt line. The daughter board configures the CAN controller to +interrupt over GPIO3 which is exposed as Pin 4 on pinout J5 as described +in the +TK1-SOM Reference guide. This is at the back of the TK1 relative to our +setup and we connect the probe as shown:

+ +

Photo of attaching Saleae to GPIO interrupt

+ +

We capture a message being sent again and now we can see the CAN message +being sent, the controller interrupting the GPIO line and then the +processor responding to the interrupt with SPI transactions. Eventually +the interrupt line is reset once the processor has read out the received +CAN message from the CAN controller.

+ +

Screenshot of Logic software: GPIO Sample result

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/CEI_TK1_SOM/LogicPro8/index.md b/Hardware/CEI_TK1_SOM/LogicPro8/index.md deleted file mode 100644 index 24b503d6c1f..00000000000 --- a/Hardware/CEI_TK1_SOM/LogicPro8/index.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -archive: true -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Using the Saleae Logic Pro 8 to debug a CAN bus - -## Introduction - -This page is a quick write up of how we used a logic analyzer to help -solve a message loss issue when using a CAN bus. We had two TK1-SOMs -connected together on a CAN bus. One of them runs Linux natively and the -other runs an seL4 CAmkES application that receives CAN frames and then -prints them out. We found that although the CAmkES application could -correctly receive and reply to individual CAN frames, when frames were -being received at the maximum rate of the bus the CAmkES application -would only print out the first, last and occasionally a frame in the -middle. Read more about CAN -[here](https://en.wikipedia.org/wiki/CAN_bus), and -[here](https://www.saleae.com/index) is the Saleae Logic Pro 8 -site. Information about the TK1-SOM daughter board that we use is -[here](https://bitbucket.csiro.au/projects/OH/repos/tk1som-can-daughterboard/browse). - -Photo of CAN connected between two TK1-SOMs - -## Setup - -Each of the TK1-SOMs have a daughter board with a MCP25625 -CAN controller on them that can communicate with the processor over SPI. -When a controller receives a CAN message it notifies the processor by -interrupting it over a GPIO line. The processor then reads the CAN -message out of the controller over SPI. We can use the LogicPro8 to -probe the CAN bus, the SPI bus and also the GPIO pin that the interrupt -is received on to get a feel for what is going on. - -Photo of Saleae connected to TK1-SOM - -### Connecting to the CAN bus - -Schematic of daughter board - -On our daughter board (schematic above), our CAN bus pins are CAN1H, -CAN1L and GND. The Logic pro only needs to be plugged into CAN1L and GND -in order to decode CAN frames. We connect Channel 0 of the Logic pro as -shown: (Note that the schematic above shows the bottom of the daughter -board. So the order of the pins in the photo is reversed) - -Closeup photo of Saleae connected to TK1-SOm - -Saleae provides the [Logic](https://www.saleae.com/downloads) -software which is used to collect and analyse data. - -Screenshot of Logic software - -We configure Logic to collect at a rate of 50MS/s on channel 0 with -3.3+V - -Screenshot of Logic software: Collection bitrate setting menu - -We add CAN as an analyser for Channel 0 and set the bitrate to 125000 -which is what our TK1s are configured to use. - -Screenshot of Logic software: Analyser setting menu -Screenshot of Logic software: Analyser setting menu, sample bitrate setting - -We press start and then send one CAN message from the Linux TK1 to the -seL4 TK1. -``` -Native Linux: -ubuntu@tegra-ubuntu:\~$ cansend can0 5A1#11.22.33.44.55.66.77.88 - -seL4: Recv: error(0), id(5a1), data(11, 22, 33, 44, 55, 66, 77, 88) -``` -In Logic we see that we measured the CAN message being transmitted over -the bus. On the side under Decoded protocols Logic reports the fields of -the message that was sent. - -Screenshot of Logic software: CAN Sample result - -### Connecting to SPI - -We now connect to the SPI bus. To do this we need to measure the CLK, -MOSI and MISO. (These pins can be found at the bottom of the schematic). -We connect the probe to them as follows: - -Photo of attaching Saleae to SPI bus - -In Logic we add the new channels and configure a SPI analyser for them. - -Screenshot of Logic software: SPI Analyser setting menu - -After running the scan again while sending a CAN message we now see the -CAN frame sent on the bus followed by a few SPI transactions between the -Processor and CAN controller. - -Screenshot of Logic software: SPI Sample result - -Zooming in on a single SPI transaction we see that the CAN driver send -0x03, 0x2C and the CAN controller respond with 0x01. This corresponds to -Read register 0x2C (Interrupt flag register) and the register value -being returned as 0x01 (Message received). Under decoded protocols you -can see both CAN messages and SPI messages that were sent. - -Screenshot of Logic software: SPI Sample result, Zoomed in - -### GPIO Interrupt line - -We finally connect the probe to the -interrupt line. The daughter board configures the CAN controller to -interrupt over GPIO3 which is exposed as Pin 4 on pinout J5 as described -in the -[TK1-SOM Reference guide](https://coloradoengineering.com/wp-content/uploads/2021/04/Reference-Guide_FINAL-4.pdf). This is at the back of the TK1 relative to our -setup and we connect the probe as shown: - -Photo of attaching Saleae to GPIO interrupt - -We capture a message being sent again and now we can see the CAN message -being sent, the controller interrupting the GPIO line and then the -processor responding to the interrupt with SPI transactions. Eventually -the interrupt line is reset once the processor has read out the received -CAN message from the CAN controller. - -Screenshot of Logic software: GPIO Sample result diff --git a/Hardware/CEI_TK1_SOM/Tk1SomMods/index.html b/Hardware/CEI_TK1_SOM/Tk1SomMods/index.html new file mode 100644 index 00000000000..6eb96eab726 --- /dev/null +++ b/Hardware/CEI_TK1_SOM/Tk1SomMods/index.html @@ -0,0 +1,634 @@ + + + + + + + TK1-SOM Hardware Modifications | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

TK1-SOM Hardware Modifications

+ +

Adding a second UART connector

+ +

The issue

+ +
+
+ + Note +
+
+ +

If you are using our IO-Daughterboard, this is unnecessary; +instead a straight-line passthrough jumper is used to hook up to level +converters on the daughterboard.

+ +
+
+ +

The TK1-SOM has a secondary UART connection, however it’s a bit of a +pain to get to as a normal jumper won’t fit sandwiched between the +boards (below left), and you can’t get to the connection from the top +because of the fan & heatsink (below right).

+ +

jumper +heatsink

+ +

What it looks like

+ +

Viewed from the bottom of the CPU board, the secondary UART is the 4 +unpopulated pins just under the ethernet jack pins (see below):

+ +

connector

+ +

Right-angle connectors?

+ +

Initially I looked at normal right-angle +0.1” headers, but they don’t fit in either direction!

+ +

clearance +short

+ +

Above left: you can’t connect a jack as there is no clearance to the +mezzanine connector. Above right: the pins will likely short with the +ethernet jack pins.

+ +

Solution: modify a dual-row header..

+ +

A normal dual-row 0.1” header looks like this:

+ +

normal header

+ +

But we only need it for clearance - which we can do by just taking out +the bottom 2 rows of pins:

+ +

bend pin +pull pin

+ +

(It’s easiest to use pliers to push the pins out a little bit, bend +them, and then pull them all the way out)

+ +

Eventually, you end up with this (Only the top row left):

+ +

single row header

+ +

Now you can solder the pins on (make sure the pins are directed toward +the ethernet jack so there’s enough clearance!)

+ +

attached header

+ +

Make sure not to use too much heat in this step, there are a few 0201 +components nearby which can easily come off just because of the nearby +heat. Also be sure to keep the iron angled away from the connectors as +it is quite easy to accidentally melt them.

+ +

Once done, put the TK1-SOM back together and you have some easily +accessible UART pins:

+ +

final

+ +

The pinout & levels are described in the TK1-SOM reference guide - this +connector is called J2000. (Pin 1 is the square pad)

+ +

Note the 1V8 logic levels!

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/CEI_TK1_SOM/Tk1SomMods/index.md b/Hardware/CEI_TK1_SOM/Tk1SomMods/index.md deleted file mode 100644 index 2140d8513fa..00000000000 --- a/Hardware/CEI_TK1_SOM/Tk1SomMods/index.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# TK1-SOM Hardware Modifications - -## Adding a second UART connector - -### The issue - -{% include note.html %} -If you are using our [IO-Daughterboard](../DaughterBoard/), this is unnecessary; -instead a straight-line passthrough jumper is used to hook up to level -converters on the daughterboard. -{% include endnote.html %} - -The TK1-SOM has a secondary UART connection, however it's a bit of a -pain to get to as a normal jumper won't fit sandwiched between the -boards (below left), and you can't get to the connection from the top -because of the fan & heatsink (below right). - -jumper -heatsink - -### What it looks like - -Viewed from the bottom of the CPU board, the secondary UART is the 4 -unpopulated pins just under the ethernet jack pins (see below): - -connector - -### Right-angle connectors? - -Initially I looked at normal right-angle -0.1" headers, but they don't fit in either direction! - -clearance -short - -Above left: you can't connect a jack as there is no clearance to the -mezzanine connector. Above right: the pins will likely short with the -ethernet jack pins. - -### Solution: modify a dual-row header.. - - -A normal dual-row 0.1" header looks like this: - -normal -header - -But we only need it for clearance - which we can do by just taking out -the bottom 2 rows of pins: - -bend -pin -pull -pin - -(It's easiest to use pliers to push the pins out a little bit, bend -them, and then pull them all the way out) - -Eventually, you end up with this (Only the top row left): - -single row -header - -Now you can solder the pins on (make sure the pins are directed toward -the ethernet jack so there's enough clearance!) - -attached -header - -Make sure not to use too much heat in this step, there are a few 0201 -components nearby which can easily come off just because of the nearby -heat. Also be sure to keep the iron angled away from the connectors as -it is quite easy to accidentally melt them. - -Once done, put the TK1-SOM back together and you have some easily -accessible UART pins: - -final - -The pinout & levels are described in the TK1-SOM reference guide - this -connector is called J2000. (Pin 1 is the square pad) - -Note the 1V8 logic levels! diff --git a/Hardware/CEI_TK1_SOM/index.html b/Hardware/CEI_TK1_SOM/index.html new file mode 100644 index 00000000000..186ffc0fecb --- /dev/null +++ b/Hardware/CEI_TK1_SOM/index.html @@ -0,0 +1,810 @@ + + + + + + + TK1 som | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

TK1 som

+ +

The TK1-SOM from Colorado +engineering is a small +form-factor system based on the NVIDIA Tegra K1.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform TK1-SOM
Architecture ARMv7A
System-on-chip NVIDIA Tegra K1
CPU Cortex-A15
seL4 virtualisation support + +
seL4 SMMU support + +
Proofs + +
Proof configsARM_HYP
seL4 CMake platform nametk1
Contributed by Data61
Maintained by seL4 Foundation
+ +

Hardware modifications and Daughterboards

+ +

Adding some missing connectors makes this board a +bit easier to use.

+ +

We have also developed 2 daughterboards for the TK1-SOM

+ + + +

U-Boot

+ +

Upstream U-Boot now supports this board.

+ +

Follow the instructions for the Jetson TK1, however:

+ + + +

As with the Jetson with this u-boot, set the +environment variable bootm_boot_mode to nonsec In this boot mode, the +standard Linux kernel will not boot: recompile with CONFIG_ARM_PSCI on +and CONFIG_CPU_IDLE off.

+ +

The Pinmux spreadsheet, for use with +https://github.com/NVIDIA/tegra-pinmux-scripts is +here.

+ +

The original pinmux spreadsheet from Colorado is +here

+ +

Accessing the MMC

+

Attach a USB cable +between the TK1-SOM’s OTG port and your host, then on the U-Boot console +type ums mmc 0.

+ +

A spinning wheel will appear on the console, and the entire MMC will be +presented as a USB storage device to your host. In the default +partitioning (as it comes from Colorado Engineering) partition 1 on the +device is the UBUNTU root partition.

+ +

The instructions for booting from SD +are also valid for booting from MMC.

+ +

Serial Connection

+

The serial port is at 1V8 levels on J8, as +follows: (pin one is farthest from the ground hole)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PinFunctionDirection
1RxIn
2TxOut
3CTSIn
4RTSOut
+ +

There is no ground connection. There is however an unpopulated hole next +to J8 that is connected to Ground. Alternatively one can use pin 1 of J5 +on the bottom (PSU) board as a ground connection. The pins are +unlabelled; pin 1 is the one in the middle of the board, under the gap +between J5 and J7 on the GPU/processor board. It’s easiest to connect to +this if you unscrew and take the thing apart. Please do this at a +static-controlled workstation!

+ +

If you need 1V8 as a reference (VDIO on some FTDI connectors), it’s +available on the JTAG connector at pin 1. Pin one is the top right pin +if the ethernet port is to your left. It is marked with a dot on the +silk-screen.

+ +

Speed 115200 8bits no parity; the default Linux image has login ubuntu, +password ubuntu.

+ +

Peripherals

+

We have an open-hardware CAN and I2C board available, +see CAN-Board

+ +

DFU: Loading kernels over USB

+

You can load seL4 kernels over USB using dfu-util. (you can also use fastboot, +but to boot a kernel over fastboot means making the ELF file produced +from the build system look like an ANDROID Linux kernel).

+ +

On the u-boot console do:

+
setenv dfu_alt_info "kernel ram $loadaddr 0x1000000"
+saveenv
+
+

once.

+ +

Then to boot, on the u-boot console do:

+
dfu 0 ram 0
+
+

and on your host:

+ +
    +
  • install dfu-util (one time only: apt-get install dfu-util)
    • +
  • +

    connect to the TK1-SOM using a USB connector to the on-the-go + port

    +
    • +
  • +

    run dfu-util (you may need to run this with sudo)

    + + 
    dfu-util --device 0955:701a -a kernel -D sel4test-driver-image-arm-tk1 .
+dfu-util --device 0955:701a -e
+
    + +

    (if the -e option isn’t supported you +can add -R to the above command or ignore it and manually Ctrl-C out +of dfu in u-boot on the TK1-SOM)

    +
    • +
+ +

This will load the sel4test-driver-image-arm-tk1 file onto the TK1-SOM +at address $loadaddr. You can then run it in uboot with

+ +
bootefi $loadaddr
+
+ +

If you want, you can automate all this with:

+ +
setenv bootcmd_dfu "dfu 0 ram 0; bootefi $loadaddr" saveenv
+
+ +

then just

+ +
run bootcmd_dfu
+
+ +

If you ‘‘always’’ want to do this you can do

+ +
setenv bootcmd "run bootcmd_dfu"
+
+ +

Booting from a USB storage device

+ +

You can boot from a USB storage device, by plugging it into the blue +port (on the power supply board). Patches are pending upstream to enable +the other port too. Use a FAT32 or ext2 partition on the storage; put +your image on it. You can either use a syslinux-style menu, or can boot +directly.

+
usb start
+fatload usb 0:1 ${loadaddr} sel4test-image-arm
+bootelf ${loadaddr}
+
+ +

Using L4T from CEI

+ +

CEI provides modifications to L4T and instructions for getting it +running on the TK1-SOM. Unfortunately these seem to only be available on +a private FTP site, so you’ll have to contact CEI for access to those.

+ +

Once you have access, follow the instructions in the README.txt.

+ +

If you have a recent distribution and use the instructions from +Colorado, you will end up with an unbootable system — the format of +the ext4 filesystem, created by the flash.sh script has features that +the u-boot and kernel cannot understand. The simple change is to build +an ext3 filesystem instead.

+ +

Do:

+ +
sudo env ROOTFS_TYPE=ext3 ./flash.sh -L bootloader/ardbeg/u-boot.bin tk1-som mmcblk0p1
+
+

instead of using the instructions in the Colorado-provided +README.txt

+ +

Alternatively we have a customised image that we use: more information +at L4TCan.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/CEI_TK1_SOM/index.md b/Hardware/CEI_TK1_SOM/index.md deleted file mode 100644 index ae341656a78..00000000000 --- a/Hardware/CEI_TK1_SOM/index.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -arm_hardware: true -cmake_plat: tk1 -xcompiler_arg: -DAARCH32=1 -platform: TK1-SOM -arch: ARMv7A -virtualization: true -iommu: true -soc: NVIDIA Tegra K1 -cpu: Cortex-A15 -verification: [ARM_HYP] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -# TK1 som - -The [TK1-SOM from Colorado -engineering](https://coloradoengineering.com/products/tk1-som-2gb/) is a small -form-factor system based on the NVIDIA Tegra K1. - -{% include hw-info.html %} - -## Hardware modifications and Daughterboards - - -[Adding some missing connectors](Tk1SomMods/) makes this board a -bit easier to use. - -We have also developed 2 daughterboards for the TK1-SOM - -- a [CAN daughterboard](CANBoard/), that adds two CAN - controllers on the SPI bus -- an [I/O daughterboard](DaughterBoard/) that adds CAN - controllers, various sensors and power management - -## U-Boot - -Upstream U-Boot now supports this board. - -Follow the instructions for the [Jetson TK1](../jetsontk1.html#flash-u-boot), however: - -- use - as the URL for repo -- don't apply the patch to increase the console buffer size -- use cei-tk1-som (instead of jetson-tk1) as the board ID - -As with the [Jetson](../jetsontk1.html) with this u-boot, set the -environment variable bootm_boot_mode to nonsec In this boot mode, the -standard Linux kernel will not boot: recompile with CONFIG_ARM_PSCI on -and CONFIG_CPU_IDLE off. - -The Pinmux spreadsheet, for use with - is -[here.](CEI_TK1_SOM_customer_pinmux_v11.xlsm) - -The original pinmux spreadsheet from Colorado is -[here](tk1-som_pinmux_V2.4.xlsm) - -## Accessing the MMC -Attach a USB cable -between the TK1-SOM's OTG port and your host, then on the U-Boot console -type `ums mmc 0`. - -A spinning wheel will appear on the console, and the entire MMC will be -presented as a USB storage device to your host. In the default -partitioning (as it comes from Colorado Engineering) partition 1 on the -device is the UBUNTU root partition. - -The [instructions for booting from SD](../GeneralARM.html#booting-from-sd-card) -are also valid for booting from MMC. - -## Serial Connection - The serial port is at 1V8 levels on J8, as -follows: (pin one is farthest from the ground hole) - -|Pin|Function|Direction| -|-|-|-| -|1 |Rx |In | -|2 |Tx |Out | -|3 |CTS |In | -|4 |RTS |Out | - -There is no ground connection. There is however an unpopulated hole next -to J8 that is connected to Ground. Alternatively one can use pin 1 of J5 -on the bottom (PSU) board as a ground connection. The pins are -unlabelled; pin 1 is the one in the middle of the board, under the gap -between J5 and J7 on the GPU/processor board. It's easiest to connect to -this if you unscrew and take the thing apart. Please do this at a -static-controlled workstation! - -If you need 1V8 as a reference (VDIO on some FTDI connectors), it's -available on the JTAG connector at pin 1. Pin one is the top right pin -if the ethernet port is to your left. It is marked with a dot on the -silk-screen. - -Speed 115200 8bits no parity; the default Linux image has login ubuntu, -password ubuntu. - -## Peripherals - We have an open-hardware CAN and I2C board available, -see [CAN-Board](CANBoard) - -## DFU: Loading kernels over USB -You can load seL4 kernels over USB using dfu-util. (you can also use fastboot, -but to boot a kernel over fastboot means making the ELF file produced -from the build system look like an ANDROID Linux kernel). - -On the u-boot console do: -``` -setenv dfu_alt_info "kernel ram $loadaddr 0x1000000" -saveenv -``` -once. - -Then to boot, on the u-boot console do: -``` -dfu 0 ram 0 -``` -and on your host: - -- install dfu-util (one time only: apt-get install dfu-util) -- connect to the TK1-SOM using a USB connector to the on-the-go - port - -- run dfu-util (you may need to run this with sudo) - - dfu-util --device 0955:701a -a kernel -D sel4test-driver-image-arm-tk1 . - dfu-util --device 0955:701a -e - - (if the -e option isn't supported you - can add -R to the above command or ignore it and manually Ctrl-C out - of dfu in u-boot on the TK1-SOM) - - -This will load the `sel4test-driver-image-arm-tk1` file onto the TK1-SOM -at address `$loadaddr`. You can then run it in uboot with - - bootefi $loadaddr - -If you want, you can automate all this with: - - setenv bootcmd_dfu "dfu 0 ram 0; bootefi $loadaddr" saveenv - -then just - - run bootcmd_dfu - -If you ''always'' want to do this you can do - - setenv bootcmd "run bootcmd_dfu" - -# Booting from a USB storage device - -You can boot from a USB storage device, by plugging it into the blue -port (on the power supply board). Patches are pending upstream to enable -the other port too. Use a FAT32 or ext2 partition on the storage; put -your image on it. You can either use a syslinux-style menu, or can boot -directly. -``` -usb start -fatload usb 0:1 ${loadaddr} sel4test-image-arm -bootelf ${loadaddr} -``` - -# Using L4T from CEI - - -CEI provides modifications to L4T and instructions for getting it -running on the TK1-SOM. Unfortunately these seem to only be available on -a private FTP site, so you'll have to contact CEI for access to those. - -Once you have access, follow the instructions in the README.txt. - -If you have a recent distribution and use the instructions from -Colorado, you will end up with an unbootable system --- the format of -the ext4 filesystem, created by the flash.sh script has features that -the u-boot and kernel cannot understand. The simple change is to build -an ext3 filesystem instead. - -Do: - - -``` -sudo env ROOTFS_TYPE=ext3 ./flash.sh -L bootloader/ardbeg/u-boot.bin tk1-som mmcblk0p1 -``` -instead of using the instructions in the Colorado-provided -README.txt - -Alternatively we have a customised image that we use: more information -at [L4TCan](L4TCan). diff --git a/Hardware/GeneralARM.html b/Hardware/GeneralARM.html new file mode 100644 index 00000000000..98f78744000 --- /dev/null +++ b/Hardware/GeneralARM.html @@ -0,0 +1,647 @@ + + + + + + + Loading seL4 onto ARM Hardware | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Loading seL4 onto ARM Hardware

+ +

The ARM platform has many ways to boot into an operating system. Typically there +is some low-level ROM code (very specific to each device) that turns on RAM, and +turns on enough clocks to be able to load a second-stage bootloader which does +the work. Some do this in several stages, to enable Trust Zone, HYP-mode etc.

+ +

The main bootloaders after the ROM are U-Boot, UEFI, Loki (for Samsung devices) +and simpleboot. Most of these provide Fastboot over USB to allow software +loading.

+ +

On UEFI for arm: http://blog.hansenpartnership.com/efitools-for-arm-released/ On U-Boot for arm: http://www.denx.de/wiki/U-Boot

+ +

Load from U-Boot, from SD card or flash, or using Fastboot or TFTP. Most +applications have two parts: treat the “kernel” part as a kernel, and the +“application” part like an initial root disk. If there is only one part to an +image (e.g., seL4test for some platforms) treat it like a kernel.

+ +

Detailed instructions differ from board to board. See the Supported +Platforms page for links to board-specific instructions.

+ +

Fastboot

+ +

Most ARM platforms other than the Beagle Boards that seL4 can use support +booting via Fastboot.

+ +

To boot via Fastboot, you need to convert the image file produced by the seL4 +build system into a U-Boot image.

+ +
mkimage -A arm -a 0x48000000 -e 0x48000000 -C none -A arm -T kernel -O qnx -d INPUT_FILE OUTPUT_FILE
+
+ +

The reason we choose -O qnx is because we exploit the fact that, like seL4, +QNX expects to be ELF-loaded. The alternative is to convert our ELF file into a +binary file using objcopy. The address to use varies from board to board. +Unless you change the load address, use these:

+ + + + + + + + + + + + + + + + + + + + + + +
PlatformAddress
Arndale, Odroid-X, Odroid-XU0x48000000
Sabre Lite0x30000000
Panda, Panda ES0x80000000
+ +

When you have your image, put the board into Fastboot mode (interrupt U-Boot, +and type “fastboot”), then do:

+ +
fastboot boot OUTPUT_FILE
+
+ +

Booting from SD card

+ +

Pull out the SD card from your board, and put it into an SD card reader attached +to your build host. Mount the (MS-DOS) filesystem on the first partition on the +SD card and copy your image to it. Unmount the filesystem, and put the card back +into your board. Reset the board (by power cycling, or pressing the reset +button). To run the image:

+ +
mmc init
+mmcinfo
+fatload mmc 0 ${loadaddr} sel4test-image-arm
+bootelf ${loadaddr}
+
+ +

You can use

+ +
fatls mmc 0
+
+ +

to see what is there. Most U-Boot implementations define a suitable loadaddr +in their environment.

+ +

TFTP booting

+ +

Setting up a DHCP and TFTP server are out of scope for this document. Once you +have done that, however, and installed a TFTP-enabled U-Boot on your board if it +doesn’t already have one.

+ +

You can then power up the device and stop U-Boot’s auto boot feature if +enabled by pressing a key, and do:

+ +
dhcp file address
+bootelf address
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/GeneralARM.md b/Hardware/GeneralARM.md deleted file mode 100644 index 197de01a800..00000000000 --- a/Hardware/GeneralARM.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Loading seL4 onto ARM Hardware - -The ARM platform has many ways to boot into an operating system. Typically there -is some low-level ROM code (very specific to each device) that turns on RAM, and -turns on enough clocks to be able to load a second-stage bootloader which does -the work. Some do this in several stages, to enable Trust Zone, HYP-mode etc. - -The main bootloaders after the ROM are U-Boot, UEFI, Loki (for Samsung devices) -and simpleboot. Most of these provide Fastboot over USB to allow software -loading. - - On UEFI for arm: [http://blog.hansenpartnership.com/efitools-for-arm-released/](http://blog.hansenpartnership.com/efitools-for-arm-released/) On U-Boot for arm: [http://www.denx.de/wiki/U-Boot](http://www.denx.de/wiki/U-Boot) - -Load from U-Boot, from SD card or flash, or using Fastboot or TFTP. Most -applications have two parts: treat the "kernel" part as a kernel, and the -"application" part like an initial root disk. If there is only one part to an -image (e.g., seL4test for some platforms) treat it like a kernel. - -Detailed instructions differ from board to board. See the [Supported -Platforms](index.html) page for links to board-specific instructions. - -## Fastboot - -Most ARM platforms other than the Beagle Boards that seL4 can use support -booting via Fastboot. - -To boot via Fastboot, you need to convert the image file produced by the seL4 -build system into a U-Boot image. - -```bash -mkimage -A arm -a 0x48000000 -e 0x48000000 -C none -A arm -T kernel -O qnx -d INPUT_FILE OUTPUT_FILE -``` - -The reason we choose `-O qnx` is because we exploit the fact that, like seL4, -QNX expects to be ELF-loaded. The alternative is to convert our ELF file into a -binary file using `objcopy`. The address to use varies from board to board. -Unless you change the load address, use these: - -| **Platform** | **Address** | -| :------------ | :----------| -| Arndale, Odroid-X, Odroid-XU | 0x48000000| -| Sabre Lite |0x30000000| -| Panda, Panda ES | 0x80000000| - -When you have your image, put the board into Fastboot mode (interrupt U-Boot, -and type "fastboot"), then do: - -```fastboot -fastboot boot OUTPUT_FILE -``` - -## Booting from SD card - -Pull out the SD card from your board, and put it into an SD card reader attached -to your build host. Mount the (MS-DOS) filesystem on the first partition on the -SD card and copy your image to it. Unmount the filesystem, and put the card back -into your board. Reset the board (by power cycling, or pressing the reset -button). To run the image: - -``` -mmc init -mmcinfo -fatload mmc 0 ${loadaddr} sel4test-image-arm -bootelf ${loadaddr} -``` - -You can use - -``` -fatls mmc 0 -``` - -to see what is there. Most U-Boot implementations define a suitable `loadaddr` -in their environment. - -## TFTP booting - -Setting up a DHCP and TFTP server are out of scope for this document. Once you -have done that, however, and installed a TFTP-enabled U-Boot on your board if it -doesn't already have one. - -You can then power up the device and stop U-Boot's auto boot feature if -enabled by pressing a key, and do: - -``` -dhcp file address -bootelf address -``` diff --git a/Hardware/HiKey/index.html b/Hardware/HiKey/index.html new file mode 100644 index 00000000000..c6446cd6d62 --- /dev/null +++ b/Hardware/HiKey/index.html @@ -0,0 +1,890 @@ + + + + + + + HiKey | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

HiKey

+ +
+
+ + Important +
+
+ +

This board is no longer supported by seL4.

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform HiKey
Architecture ARMv8A
System-on-chip Kirin 620
CPU Cortex-A53
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform namehikey
Contributed by Data61
+ +

Pre-Requisites

+ + + +

Getting Started

+ +

The Hikey board is based around the HiSilicon Kirin +620 +eight-core ARM Cortex-A53 64-bit !SoC running at 1.2GHz. Toe start using 32-bit +seL4 follow the below instructions. They will walk you step by step beginning +from the source files and ultimately running an image.

+ +

1. Creating a directory

+ +
mkdir hikey-flash
+cd hikey-flash
+
+ +

2. Custom toolchains

+ +

The cross-toolchains GCC 4.9 for Aarch64 and +gnueabihf are required to flash the Hikey. If versions of GCC 5, or +higher, are installed the following steps must be taken as GCC5 is not +backwards compatible. Otherwise skip to the next Section.

+ +

The necessary files are:

+ +
    +
  • GCC 4.9 cross-toolchain for + Aarch64 (gcc-linaro-4.9-2016.02-x86_64_aarch64-linux-gnu.tar.xz)
    • +
  • GCC 4.9 cross-toolchain for + gnueabihf (gcc-linaro-4.9-2016.02-x86_64_arm-linux-gnueabihf.tar.xz)
    • +
+ +

The files are obtainable from the +following links:

+ + + +
#Run the following commands to use GCC 4.9 only in this directory mkdir
+arm-tc arm64-tc tar --strip-components=1 -C ${PWD}/arm-tc -xf ~/Downloads gcc-linaro-4.9-2016.02-x86_64_aarch64-linux-gnu.tar.xz
+tar --strip-components=1 -C ${PWD}/arm64-tc -xf ~/Downloads/gcc-linaro-4.9-2016.02-x86_64_arm-linux-gnueabihf.tar.xz
+export PATH="${PWD}/arm-tc/bin:${PWD}/arm64-tc/bin:$PATH"
+
+# To check that GCC 4.9 is used aarch64-linux-gnu-gcc --version
+arm-linux-gnueabihf-gcc --version
+
+ +

3. Obtaining the source files

+ +
git clone -b hikey --depth 1 https://github.com/96boards/edk2.git linaro-edk2
+git clone -b hikey --depth 1 https://github.com/96boards-hikey/arm-trusted-firmware.git
+git clone -b hikey --depth 1 https://github.com/96boards/LinaroPkg.git
+git clone --depth 1 https://github.com/96boards/l-loader.git
+git clone git://git.linaro.org/uefi/uefi-tools.git
+
+ +

4. Changing console to UART0

+ +
gedit LinaroPkg/platforms.config
+
+# Uncomment the following lines
+BUILDFLAGS=-DSERIAL_BASE=0xF8015000
+ATF_BUILDFLAGS=CONSOLE_BASE=PL011_UART0_BASE CRASH_CONSOLE_BASE=PL011_UART0_BASE
+
+ +

5. Patching the UEFI for the Hikey

+ +

Obtain the patch from edk2.patch and follow the below steps.

+ +
cd linaro-edk2
+patch -p1 < ~/Downloads/edk2.patch
+# Then return to the main directory hikey-flash
+
+ +

6.Modifying the firmware

+ +

If settings are required +to be changed while in EL3 then the file in +arm-trusted-firmware/bl1/bl1_main.c can be modified. To disable the +prefetcher obtain the patch file from +bl1_main.patch and follow the below steps.

+ +
cd arm-trusted-firmware/bl1
+patch -p5 < ~/Downloads/bl1_main.patch
+# Then return to the main directory hikey-flash
+
+ +

7. Modifying the UEFI

+ +

If settings are required to +be changed while in EL2 then the file in +linaro-edk2/MdeModulePkg/Application/noboot/efi-stub.S can be modified. +To disable the prefetcher obtain the patch file from +efi-stub.patch follow the below steps.

+ +
 cd
+linaro-edk2/MdeModulePkg/Application/noboot patch -p7 <
+~/Downloads/efi-stub.patch # Then return to the main directory
+hikey-flash
+
+ +

8. Building the UEFI for the Hikey

+ +
export AARCH64_TOOLCHAIN=GCC49
+export EDK2_DIR=${PWD}/linaro-edk2
+export UEFI_TOOLS_DIR=${PWD}/uefi-tools
+
+cd ${EDK2_DIR}
+${UEFI_TOOLS_DIR}/uefi-build.sh -c ../LinaroPkg/platforms.config -b RELEASE -a ../arm-trusted-firmware hikey
+
+cd ../l-loader
+ln -s ${EDK2_DIR}/Build/HiKey/RELEASE_GCC49/FV/bl1.bin
+ln -s ${EDK2_DIR}/Build/HiKey/RELEASE_GCC49/FV/fip.bin
+
+# If the DEBUG version of the build is require run the below commands instead
+cd ${EDK2_DIR}
+${UEFI_TOOLS_DIR}/uefi-build.sh -c ../LinaroPkg/platforms.config -b DEBUG -a ../arm-trusted-firmware hikey
+
+cd ../l-loader
+ln -s ${EDK2_DIR}/Build/HiKey/DEBUG_GCC49/FV/bl1.bin
+ln -s ${EDK2_DIR}/Build/HiKey/DEBUG_GCC49/FV/fip.bin
+# End
+
+arm-linux-gnueabihf-gcc -c -o start.o start.S
+arm-linux-gnueabihf-gcc -c -o debug.o debug.S
+arm-linux-gnueabihf-ld -Bstatic -Tl-loader.lds -Ttext 0xf9800800 start.o debug.o -o loader
+arm-linux-gnueabihf-objcopy -O binary loader temp
+python gen_loader.py -o l-loader.bin --img_loader=temp --img_bl1=bl1.bin
+sudo PTABLE=linux-4g bash -x generate_ptable.sh
+python gen_loader.py -o ptable-linux.img --img_prm_ptable=prm_ptable.img
+
+ +

9. Boot Image

+ +
+
+ + Note +
+
+ +

96boards does no longer seem to provide the release binary below.

+ +
+
+ +

Obtain the boot image from +https://builds.96boards.org/releases/hikey/linaro/debian/latest/boot-fat.uefi.img.gz +and follow the below commands.

+ +
gunzip *.img.gz
+
+mkdir -p boot-fat
+sudo mount -o loop,rw,sync boot-fat.uefi.img boot-fat
+
+sudo rm boot-fat/EFI/BOOT/fastboot.efi
+sudo cp ../linaro-edk2/Build/HiKey/RELEASE_GCC49/AARCH64/AndroidFastbootApp.efi boot-fat/EFI/BOOT/fastboot.efi
+sudo cp ../linaro-edk2/Build/HiKey/RELEASE_GCC49/AARCH64/noboot.efi boot-fat/EFI/BOOT/
+
+sudo umount boot-fat
+
+ +

10. Minicom

+ +

Install and configure minicom. Two terminals are required for the commands. If +minicom is already installed and configured skip the next Section.

+ +
# In the first terminal
+cd /dev/
+ls
+# Note the ttyUSBX that is observed
+
+# In the second terminal
+sudo apt-get install minicom
+sudo minicom -s
+
+ +
    +
  1. Use the arrow keys to scroll down to Serial port setup and press +enter
    2. +
  2. Press ‘a’ to start editing the Serial Device
    3. +
  3. Rename the serial device to /dev/ttyUSBX where X is the observed +number
    4. +
  4. Press ‘esc’ twice and select Save setup as dfl
    5. +
+ +

11. Flash the firmware

+ +
    +
  1. Turn off the power to the board if it is on.
    2. +
  2. Connect UART0 to a USB port if it is not connected already.
    3. +
  3. Connect the Hikey board with a USB to micro USB cable.
    4. +
  4. Connect pins 1&2 (AUTO PWR) and 3&4 (BOOT SEL) on the +J15 header. The pins are silk screened onto the PCB, otherwise +see page the Hikey user manual.
    5. +
  5. Obtain the Hikey flash recovery tool from +https://raw.githubusercontent.com/96boards/burn-boot/master/hisi-idt.py
    6. +
  6. Turn the power on the to Hikey
    7. +
  7. Three terminals are then required for the following commands
    8. +
+ +
# In the first terminal
+ls
+# Note the next ttyUSBY that is observed, in addition to the current ttyUSBX
+
+# In the third terminal
+sudo python ~/Downloads/hisi-idt.py --img1=l-loader.bin -d /dev/ttyUSBY
+wget https://builds.96boards.org/releases/hikey/linaro/binaries/latest/nvme.img
+sudo fastboot flash ptable ptable-linux.img
+sudo fastboot flash fastboot fip.bin
+sudo fastboot flash nvme nvme.img
+sudo fastboot flash boot boot-fat.uefi.img
+# The debug prints are displayed in the second terminal
+
+# Then power off the Hikey
+
+ +

12. Build your first seL4 system

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=hikey -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

The Hikey also supports AArch32 mode. If you choose to build the AArch32 kernel, +please be sure to pass -DAARCH32=1 instead of -DAARCH64=1.

+ +

13. Booting the Hikey

+ +
    +
  1. Remove the connection for pins 3&4 on the J15 header and connect +pins 5&6 instead.
    2. +
  2. Power the Hikey
    3. +
  3. Run the desired image. The command below is an example.
    4. +
+ +
# In the third terminal
+fastboot boot images/sel4test-driver-image-arm-hikey -c mode=32bit
+
+ +

14. Modifications to firmware or UEFI

+ +
    +
  • If the firmware is modified the whole process from and including + Section 9 onward must be done.
    • +
  • If the UEFI loader is modified then only Section 9 and from + Section 11 onward need to be completed
    • +
+ +

Other instructions can be viewed here: https://github.com/96boards/documentation/wiki/HiKeyUEFI#run-fastboot-from-uefi

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/HiKey/index.md b/Hardware/HiKey/index.md deleted file mode 100644 index 95df759e375..00000000000 --- a/Hardware/HiKey/index.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -arm_hardware: true -archive: true -cmake_plat: hikey -xcompiler_arg: -DAARCH64=1 -platform: HiKey -arch: ARMv8A -virtualization: true -iommu: false -soc: Kirin 620 -cpu: Cortex-A53 -verification: [AARCH64] -Contrib: Data61 -Maintained: false -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# HiKey - -{% include hw-info.html %} - -## Pre-Requisites - - -- One HiKey Board. See - [Hikey 96Board](http://www.96boards.org/products/ce/hikey/) -- Fully working development environment. See - the [set up instructions](../../projects/buildsystem/host-dependencies.html) page. - -## Getting Started - -The Hikey board is based around the [HiSilicon Kirin -620](https://github.com/96boards/documentation/blob/master/consumer/hikey/hikey620/hardware-docs/Hi6220V100_Multi-Mode_Application_Processor_Function_Description.pdf) -eight-core ARM Cortex-A53 64-bit !SoC running at 1.2GHz. Toe start using 32-bit -seL4 follow the below instructions. They will walk you step by step beginning -from the source files and ultimately running an image. - -## 1. Creating a directory - -```bash -mkdir hikey-flash -cd hikey-flash -``` - -## 2. Custom toolchains - -The cross-toolchains GCC 4.9 for Aarch64 and -gnueabihf are required to flash the Hikey. If versions of GCC 5, or -higher, are installed the following steps must be taken as GCC5 is not -backwards compatible. Otherwise skip to the next Section. - -The necessary files are: - -- GCC 4.9 cross-toolchain for - Aarch64 (gcc-linaro-4.9-2016.02-x86_64_aarch64-linux-gnu.tar.xz) -- GCC 4.9 cross-toolchain for - gnueabihf (gcc-linaro-4.9-2016.02-x86_64_arm-linux-gnueabihf.tar.xz) - -The files are obtainable from the -following links: - -- -- - -```bash -#Run the following commands to use GCC 4.9 only in this directory mkdir -arm-tc arm64-tc tar --strip-components=1 -C ${PWD}/arm-tc -xf ~/Downloads gcc-linaro-4.9-2016.02-x86_64_aarch64-linux-gnu.tar.xz -tar --strip-components=1 -C ${PWD}/arm64-tc -xf ~/Downloads/gcc-linaro-4.9-2016.02-x86_64_arm-linux-gnueabihf.tar.xz -export PATH="${PWD}/arm-tc/bin:${PWD}/arm64-tc/bin:$PATH" - -# To check that GCC 4.9 is used aarch64-linux-gnu-gcc --version -arm-linux-gnueabihf-gcc --version -``` - -## 3. Obtaining the source files - -```bash -git clone -b hikey --depth 1 https://github.com/96boards/edk2.git linaro-edk2 -git clone -b hikey --depth 1 https://github.com/96boards-hikey/arm-trusted-firmware.git -git clone -b hikey --depth 1 https://github.com/96boards/LinaroPkg.git -git clone --depth 1 https://github.com/96boards/l-loader.git -git clone git://git.linaro.org/uefi/uefi-tools.git -``` - -## 4. Changing console to UART0 - -```bash -gedit LinaroPkg/platforms.config - -# Uncomment the following lines -BUILDFLAGS=-DSERIAL_BASE=0xF8015000 -ATF_BUILDFLAGS=CONSOLE_BASE=PL011_UART0_BASE CRASH_CONSOLE_BASE=PL011_UART0_BASE -``` - -## 5. Patching the UEFI for the Hikey - -Obtain the patch from [edk2.patch](edk2.patch) and follow the below steps. - -```bash -cd linaro-edk2 -patch -p1 < ~/Downloads/edk2.patch -# Then return to the main directory hikey-flash -``` - -## 6.Modifying the firmware - -If settings are required -to be changed while in EL3 then the file in -arm-trusted-firmware/bl1/bl1_main.c can be modified. To disable the -prefetcher obtain the patch file from -[bl1_main.patch](bl1_main.patch) and follow the below steps. - -```bash -cd arm-trusted-firmware/bl1 -patch -p5 < ~/Downloads/bl1_main.patch -# Then return to the main directory hikey-flash -``` - -## 7. Modifying the UEFI - -If settings are required to -be changed while in EL2 then the file in -linaro-edk2/MdeModulePkg/Application/noboot/efi-stub.S can be modified. -To disable the prefetcher obtain the patch file from -[efi-stub.patch](efi-stub.patch) follow the below steps. - -```bash - cd -linaro-edk2/MdeModulePkg/Application/noboot patch -p7 < -~/Downloads/efi-stub.patch # Then return to the main directory -hikey-flash -``` - -## 8. Building the UEFI for the Hikey - -```bash -export AARCH64_TOOLCHAIN=GCC49 -export EDK2_DIR=${PWD}/linaro-edk2 -export UEFI_TOOLS_DIR=${PWD}/uefi-tools - -cd ${EDK2_DIR} -${UEFI_TOOLS_DIR}/uefi-build.sh -c ../LinaroPkg/platforms.config -b RELEASE -a ../arm-trusted-firmware hikey - -cd ../l-loader -ln -s ${EDK2_DIR}/Build/HiKey/RELEASE_GCC49/FV/bl1.bin -ln -s ${EDK2_DIR}/Build/HiKey/RELEASE_GCC49/FV/fip.bin - -# If the DEBUG version of the build is require run the below commands instead -cd ${EDK2_DIR} -${UEFI_TOOLS_DIR}/uefi-build.sh -c ../LinaroPkg/platforms.config -b DEBUG -a ../arm-trusted-firmware hikey - -cd ../l-loader -ln -s ${EDK2_DIR}/Build/HiKey/DEBUG_GCC49/FV/bl1.bin -ln -s ${EDK2_DIR}/Build/HiKey/DEBUG_GCC49/FV/fip.bin -# End - -arm-linux-gnueabihf-gcc -c -o start.o start.S -arm-linux-gnueabihf-gcc -c -o debug.o debug.S -arm-linux-gnueabihf-ld -Bstatic -Tl-loader.lds -Ttext 0xf9800800 start.o debug.o -o loader -arm-linux-gnueabihf-objcopy -O binary loader temp -python gen_loader.py -o l-loader.bin --img_loader=temp --img_bl1=bl1.bin -sudo PTABLE=linux-4g bash -x generate_ptable.sh -python gen_loader.py -o ptable-linux.img --img_prm_ptable=prm_ptable.img -``` - -## 9. Boot Image - -{% include note.html %} -96boards does no longer seem to provide the release binary below. -{% include endnote.html %} - -Obtain the boot image from -`https://builds.96boards.org/releases/hikey/linaro/debian/latest/boot-fat.uefi.img.gz` -and follow the below commands. - -```bash -gunzip *.img.gz - -mkdir -p boot-fat -sudo mount -o loop,rw,sync boot-fat.uefi.img boot-fat - -sudo rm boot-fat/EFI/BOOT/fastboot.efi -sudo cp ../linaro-edk2/Build/HiKey/RELEASE_GCC49/AARCH64/AndroidFastbootApp.efi boot-fat/EFI/BOOT/fastboot.efi -sudo cp ../linaro-edk2/Build/HiKey/RELEASE_GCC49/AARCH64/noboot.efi boot-fat/EFI/BOOT/ - -sudo umount boot-fat -``` - -## 10. Minicom - -Install and configure minicom. Two terminals are required for the commands. If -minicom is already installed and configured skip the next Section. - -```bash -# In the first terminal -cd /dev/ -ls -# Note the ttyUSBX that is observed - -# In the second terminal -sudo apt-get install minicom -sudo minicom -s -``` - - 1. Use the arrow keys to scroll down to Serial port setup and press - enter - 2. Press 'a' to start editing the Serial Device - 3. Rename the serial device to /dev/ttyUSBX where X is the observed - number - 4. Press 'esc' twice and select Save setup as dfl - -## 11. Flash the firmware - - 1. Turn off the power to the board if it is on. - 2. Connect UART0 to a USB port if it is not connected already. - 3. Connect the Hikey board with a USB to micro USB cable. - 4. Connect pins 1&2 (AUTO PWR) and 3&4 (BOOT SEL) on the - J15 header. The pins are silk screened onto the PCB, otherwise - see page the [Hikey user manual](https://www.96boards.org/documentation/consumer/hikey/hikey620/hardware-docs/hardware-user-manual.md.html#board-overview). - 5. Obtain the Hikey flash recovery tool from - - 6. Turn the power on the to Hikey - 7. Three terminals are then required for the following commands - -```bash -# In the first terminal -ls -# Note the next ttyUSBY that is observed, in addition to the current ttyUSBX - -# In the third terminal -sudo python ~/Downloads/hisi-idt.py --img1=l-loader.bin -d /dev/ttyUSBY -wget https://builds.96boards.org/releases/hikey/linaro/binaries/latest/nvme.img -sudo fastboot flash ptable ptable-linux.img -sudo fastboot flash fastboot fip.bin -sudo fastboot flash nvme nvme.img -sudo fastboot flash boot boot-fat.uefi.img -# The debug prints are displayed in the second terminal - -# Then power off the Hikey -``` - -## 12. Build your first seL4 system - -{% include sel4test.md %} - -The Hikey also supports AArch32 mode. If you choose to build the AArch32 kernel, -please be sure to pass `-DAARCH32=1` instead of `-DAARCH64=1`. - -## 13. Booting the Hikey - - -1. Remove the connection for pins 3&4 on the J15 header and connect - pins 5&6 instead. -2. Power the Hikey -3. Run the desired image. The command below is an example. - -```bash -# In the third terminal -fastboot boot images/sel4test-driver-image-arm-hikey -c mode=32bit -``` - -## 14. Modifications to firmware or UEFI - - -- If the firmware is modified the whole process from and including - Section 9 onward must be done. -- If the UEFI loader is modified then only Section 9 and from - Section 11 onward need to be completed - -Other instructions can be viewed here: diff --git a/Hardware/IA32.html b/Hardware/IA32.html new file mode 100644 index 00000000000..e2cbfdb2c78 --- /dev/null +++ b/Hardware/IA32.html @@ -0,0 +1,687 @@ + + + + + + + PC99 (32-bit) | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

PC99 (32-bit)

+ +

seL4 runs on 32-bit ia32 and 64-bit x64 machines, on QEMU and on hardware.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform PC99
Simulation platform yes
Architecture x86
seL4 virtualisation support + +
seL4 IOMMU (VT-d) support + +
Proofs + – +
Proof configs–
seL4 CMake platform nameia32
Contributed by Data61
Maintained by seL4 Foundation
+ +

Simulation

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=ia32 
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+# This platform is a simulation target. This script should work to run the
+# generated image if you also use -DSIMULATION=1 for init-build above:
+./simulate
+
+
+

If you plan to use the ./simulate script, please be sure to add the +-DSIMULATION=1 argument when running cmake.

+ +

Generated binaries can be found in the images/ directory.

+ +

Real Hardware

+ +

When running on real hardware console output will be over serial. You will need +to plug a serial cable into your machine to see any output.

+ +

The build system produces a multiboot compliant image for x86; a grub2 +stanza is here, but we usually boot via PXE for convenience.

+ +
menuentry "Load seL4 VM" --class os {
+    load_video
+    insmod gzio
+    insmod part_msdos
+    insmod ext2
+    set root='(hd0,msdos2)'
+    multiboot /boot/sel4kernel
+    module /boot/sel4rootserver
+}
+
+ +

Booting via PXEBOOT using +syslinux PXELINUX requires setting up a tftp and dhcp server on the network +that the machine you want to boot is connected to. The +syslinux +site has a download for pxelinux which we load over PXEBOOT +that then can load seL4. The configuration for pxelinux.cfg/default is +provided below.

+ +
label seL4
+        kernel mboot.32
+        append kernel-ia32-pc99 --- apps-ia32-pc99
+
+ +

Booting off USB with syslinux

+ +

Use syslinux to create a bootable USB stick as follows.

+ +

Assuming your USB flash drive is at /dev/sdb with a FAT partition at +/dev/sdb1:

+ +
install-mbr /dev/sdb
+syslinux --install /dev/sdb1
+mount /dev/sdb1 /mnt
+cp images/sel4test-driver-image-ia32-pc99 /mnt/rootserver
+cp images/kernel-ia32-pc99 /mnt/sel4kernel
+cat > /mnt/syslinux.cfg <<EOF
+SERIAL 0 115200
+DEFAULT seL4test
+LABEL seL4test
+    kernel mboot.c32
+    append sel4kernel --- rootserver
+EOF
+cp /usr/lib/syslinux/modules/bios/mboot.c32 /mnt
+cp /usr/lib/syslinux/modules/bios/libcom32.c32 /mnt
+umount /mnt
+
+ +

Use fdisk to make sure the first partition is bootable.

+ +

And you’re done. Output will come on the serial port

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/IA32.md b/Hardware/IA32.md deleted file mode 100644 index 49d849a46ab..00000000000 --- a/Hardware/IA32.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -cmake_plat: ia32 -simulation_target: true -simulation_only: false -arch: x86 -platform: PC99 -virtualization: true -iommu: true -verification: [] -Contrib: "Data61" -Maintained: "seL4 Foundation" -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# PC99 (32-bit) - -{% include pc99.md %} diff --git a/Hardware/IF6410.html b/Hardware/IF6410.html new file mode 100644 index 00000000000..6b264b108f2 --- /dev/null +++ b/Hardware/IF6410.html @@ -0,0 +1,674 @@ + + + + + + + Inforce IFC6410 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Inforce IFC6410

+ +
+
+ + Important +
+
+ +

This board is no longer supported by seL4.

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Inforce IFC6410
Architecture ARMv7A
System-on-chip Snapdragon S4 Pro APQ8064
CPU Krait (Cortex-A15 like)
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
Contributed by Data61
+ +

This page contains info on building seL4 for the Inforce IFC6410 development +board, running a Qualcomm Krait processor that is like an A15. Krait is a +Qualcomm reimplementation of ARMv7A.

+ +

Building for the Inforce IFC6410

+ +

To use default build config, use inforce_ configurations.

+ +

To make a bootable image you will need the Android bootimg tool. On +Debian, do

+ +
apt-get install android-mkbootimg
+
+ +

Then when you have built your app, you can create a boot image with these +commands, substituting the name of your output file for +sel4test-driver-image-arm-apq8064:

+ +
> ramdisk
+objcopy -O binary sel4test-driver-image-arm-apq8064 sel4test-driver-image-arm-apq8064.bin
+mkbootimg --kernel sel4test-driver-image-arm-apq8064.bin --ramdisk ramdisk --base "0x82000000" --output boot.img
+
+ +

Serial Console

+ +

The serial port on the Inforce is at RS232 voltage levels. Connect to a +normal serial port, then use minicom or screen to talk to it, at 115200 +baud, no parity, eight bits.

+ +

Booting seL4

+ +

Force the board to boot into Fastboot mode by shorting pins 26 and 30 on the +large header — see This blog +post +for details.

+ +

You will see something like this on the serial port:

+ +
Android Bootloader - UART_DM Initialized!!!
+[0] welcome to lk
+
+[10] platform_init()
+[10] target_init()
+[130] USB init ept @ 0x88f4e000
+[170] fastboot_init()
+[170] udc_start()
+[300] -- reset --
+[300] -- portchange --
+[470] fastboot: processing commands
+
+ +

You can then do:

+ +
fastboot boot boot.img
+
+ +

and should then see the output from your app.

+ +

Caveats

+ +

The timer driver is not complete, which means that two of the tests in seL4test +will fail.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/IF6410.md b/Hardware/IF6410.md deleted file mode 100644 index 723dd0f1253..00000000000 --- a/Hardware/IF6410.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -archive: true -arm_hardware: true -xcompiler_arg: -DAARCH32=1 -platform: Inforce IFC6410 -arch: ARMv7A -virtualization: false -iommu: false -soc: Snapdragon S4 Pro APQ8064 -cpu: Krait (Cortex-A15 like) -verification: [] -Contrib: Data61 -Maintained: false -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Inforce IFC6410 - -{% include hw-info.html %} - -This page contains info on building seL4 for the Inforce IFC6410 development -board, running a Qualcomm Krait processor that is like an A15. Krait is a -Qualcomm reimplementation of ARMv7A. - -## Building for the Inforce IFC6410 - -To use default build config, use `inforce_` configurations. - -To make a bootable image you will need the Android bootimg tool. On -Debian, do - -```bash -apt-get install android-mkbootimg -``` - -Then when you have built your app, you can create a boot image with these -commands, substituting the name of your output file for -`sel4test-driver-image-arm-apq8064`: - - -```bash -> ramdisk -objcopy -O binary sel4test-driver-image-arm-apq8064 sel4test-driver-image-arm-apq8064.bin -mkbootimg --kernel sel4test-driver-image-arm-apq8064.bin --ramdisk ramdisk --base "0x82000000" --output boot.img -``` - -## Serial Console - -The serial port on the Inforce is at RS232 voltage levels. Connect to a -normal serial port, then use minicom or screen to talk to it, at 115200 -baud, no parity, eight bits. - -## Booting seL4 - -Force the board to boot into Fastboot mode by shorting pins 26 and 30 on the -large header — see [This blog -post](https://web.archive.org/web/20150526213626/http://mydragonboard.org/2013/forcing-ifc6410-into-fastboot) -for details. - -You will see something like this on the serial port: - -```none -Android Bootloader - UART_DM Initialized!!! -[0] welcome to lk - -[10] platform_init() -[10] target_init() -[130] USB init ept @ 0x88f4e000 -[170] fastboot_init() -[170] udc_start() -[300] -- reset -- -[300] -- portchange -- -[470] fastboot: processing commands -``` - -You can then do: - -```none -fastboot boot boot.img -``` - -and should then see the output from your app. - -## Caveats - -The timer driver is not complete, which means that two of the tests in seL4test -will fail. diff --git a/Hardware/JetsonTX2.html b/Hardware/JetsonTX2.html new file mode 100644 index 00000000000..1c5786f15d6 --- /dev/null +++ b/Hardware/JetsonTX2.html @@ -0,0 +1,634 @@ + + + + + + + Jetson TX2 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Jetson TX2

+ +

The Jetson TX2 is an embedded system-on-module +(SOM) developed by NVIDIA.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform TX2
Architecture ARMv8A, AArch64 only
System-on-chip NVIDIA Tegra X2
CPU Cortex-A57 Quad, Dual NVIDIA Denver
seL4 virtualisation support + +
seL4 SMMU support + +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nametx2
Contributed by Data61
Maintained by seL4 Foundation
+ +

The seL4 kernel has a limited port to the TX2 which supports the SoM +only in 64-bit mode.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=tx2 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Booting via PXE

+ +

A U-Boot uImage will be created by the seL4 build system. This can be booted +by U-Boot using PXE.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/JetsonTX2.md b/Hardware/JetsonTX2.md deleted file mode 100644 index e35aef87ddc..00000000000 --- a/Hardware/JetsonTX2.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -arm_hardware: true -cmake_plat: tx2 -xcompiler_arg: -DAARCH64=1 -platform: TX2 -arch: ARMv8A, AArch64 only -virtualization: true -iommu: true -soc: NVIDIA Tegra X2 -cpu: Cortex-A57 Quad, Dual NVIDIA Denver -verification: [AARCH64] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Jetson TX2 - -The [Jetson TX2](https://elinux.org/Jetson_TX2) is an embedded system-on-module -(SOM) developed by NVIDIA. - -{% include hw-info.html %} - -The seL4 kernel has a limited port to the TX2 which supports the SoM -only in 64-bit mode. - -## Building seL4test - -{% include sel4test.md %} - -## Booting via PXE - -A U-Boot uImage will be created by the seL4 build system. This can be booted -by U-Boot using PXE. diff --git a/Hardware/Kzm.html b/Hardware/Kzm.html new file mode 100644 index 00000000000..244195e77a8 --- /dev/null +++ b/Hardware/Kzm.html @@ -0,0 +1,558 @@ + + + + + + + KZM (Deprecated seL4 platform) | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

KZM (Deprecated seL4 platform)

+ +

seL4 previously supported the KZM-ARM11-01 until version 12.1.0, which can also be simulated in qemu. +Support for this platform has since been removed

+ +

The KZM is deprecated, ARMv11 Hardware which was used for the original seL4 verification. The latest +verification platform is the SabreLite.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/Kzm.md b/Hardware/Kzm.md deleted file mode 100644 index dbd653fd8a1..00000000000 --- a/Hardware/Kzm.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -archive: true -simulation_target: true -simulation_only: false -cmake_plat: kzm -xcompiler_arg: -DAARCH32=1 -platform: KZM -arch: ARMv6A -virtualization: false -iommu: false -soc: i.MX31 -cpu: ARM1136J -verification: [] -Contrib: Data61 -Maintained: false -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -# KZM (Deprecated seL4 platform) - -**seL4 previously supported the KZM-ARM11-01 until version 12.1.0, which can also be simulated in qemu.** -**Support for this platform has since been removed** - -The KZM is deprecated, ARMv11 Hardware which was used for the original seL4 verification. The latest -verification platform is the [SabreLite](sabreLite.html). diff --git a/Hardware/MaaXBoard.html b/Hardware/MaaXBoard.html new file mode 100644 index 00000000000..501e8996ea8 --- /dev/null +++ b/Hardware/MaaXBoard.html @@ -0,0 +1,623 @@ + + + + + + + Avnet MaaXBoard | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Avnet MaaXBoard

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Avnet MaaXBoard
Architecture ARMv8A
System-on-chip i.MX8MQ
CPU Cortex-A53 Quad 1.5 GHz
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform namemaaxboard
Contributed by Capgemini Engineering"
Maintained by Capgemini Engineering"
+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=maaxboard -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Also -DAARCH32=1 is available.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/MaaXBoard.md b/Hardware/MaaXBoard.md deleted file mode 100644 index bc0be3c41f6..00000000000 --- a/Hardware/MaaXBoard.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -arm_hardware: true -cmake_plat: maaxboard -xcompiler_arg: -DAARCH64=1 -platform: Avnet MaaXBoard -arch: ARMv8A -virtualization: true -iommu: false -soc: i.MX8MQ -cpu: Cortex-A53 Quad 1.5 GHz -verification: [AARCH64] -Contrib: 'Capgemini Engineering"' -Maintained: 'Capgemini Engineering"' -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2022 seL4 Project a Series of LF Projects, LLC. ---- - -# Avnet MaaXBoard - -{% include hw-info.html %} - -## Building seL4test - -{% include sel4test.md %} -Also `-DAARCH32=1` is available. diff --git a/Hardware/OdroidC2.html b/Hardware/OdroidC2.html new file mode 100644 index 00000000000..9f6513866a3 --- /dev/null +++ b/Hardware/OdroidC2.html @@ -0,0 +1,644 @@ + + + + + + + Odroid-C2 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Odroid-C2

+ +

The Odroid-C2 is a single board +computer based on the Amlogic S905 System-on-Chip.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Odroid-C2
Architecture ARMv8A, AArch64
System-on-chip Amlogic S905
CPU Cortex-A53
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nameodroidc2
Contributed by Data61
Maintained by seL4 Foundation
+ +

Only 64-bit mode is supported both with and without SMP. Hypervisor +support has not been tested.

+ +

U-Boot

+ +

The default U-Boot will allocate DMA regions that can corrupt seL4 +kernel memory. +Mainline U-Boot can be used instead on this board. +Some Linux distributions include mainline U-Boot binaries compiled for +this board, or you can compile U-Boot yourself.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=odroidc2 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Booting via TFTP

+ +

Make sure you’ve set up a TFTP server to serve the seL4 image.

+ +
dhcp
+tftp 0x20000000 <YOUR_TFTP_SERVER_IP_ADDRESS>:sel4test-driver-image-arm-odroidc2
+go 0x20000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/OdroidC2.md b/Hardware/OdroidC2.md deleted file mode 100644 index cc54445a677..00000000000 --- a/Hardware/OdroidC2.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -arm_hardware: true -cmake_plat: odroidc2 -xcompiler_arg: -DAARCH64=1 -platform: Odroid-C2 -arch: ARMv8A, AArch64 -virtualization: true -iommu: false -soc: Amlogic S905 -cpu: Cortex-A53 -verification: [AARCH64] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Odroid-C2 - -The [Odroid-C2](https://wiki.odroid.com/odroid-c2/odroid-c2) is a single board -computer based on the Amlogic S905 System-on-Chip. - -{% include hw-info.html %} - -Only 64-bit mode is supported both with and without SMP. Hypervisor -support has not been tested. - -## U-Boot - -The default U-Boot will allocate DMA regions that can corrupt seL4 -kernel memory. -Mainline U-Boot can be used instead on this board. -Some Linux distributions include mainline U-Boot binaries compiled for -this board, or you can compile U-Boot yourself. - -## Building seL4test - -{% include sel4test.md %} - -## Booting via TFTP - -Make sure you've set up a TFTP server to serve the seL4 image. - -``` -dhcp -tftp 0x20000000 :sel4test-driver-image-arm-odroidc2 -go 0x20000000 -``` diff --git a/Hardware/OdroidC4.html b/Hardware/OdroidC4.html new file mode 100644 index 00000000000..d5a55e4887e --- /dev/null +++ b/Hardware/OdroidC4.html @@ -0,0 +1,635 @@ + + + + + + + Odroid-C4 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Odroid-C4

+ +

The Odroid-C4 is a single board +computer based on the Amlogic S905X3 System-on-Chip.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Odroid-C4
Architecture ARMv8A, AArch64
System-on-chip Amlogic S905X3
CPU Cortex-A55
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nameodroidc4
Contributed by Data61
Maintained by seL4 Foundation
+ +

Note that only 64-bit mode is supported.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=odroidc4 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Booting via TFTP

+ +

Make sure you’ve set up a TFTP server to serve the seL4 image.

+ +
dhcp
+tftp 0x20000000 <YOUR_TFTP_SERVER_IP_ADDRESS>:sel4test-driver-image-arm-odroidc4
+go 0x20000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/OdroidC4.md b/Hardware/OdroidC4.md deleted file mode 100644 index 8f52b04460c..00000000000 --- a/Hardware/OdroidC4.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -arm_hardware: true -cmake_plat: odroidc4 -xcompiler_arg: -DAARCH64=1 -platform: Odroid-C4 -arch: ARMv8A, AArch64 -virtualization: true -iommu: false -soc: Amlogic S905X3 -cpu: Cortex-A55 -verification: [AARCH64] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Odroid-C4 - -The [Odroid-C4](https://wiki.odroid.com/odroid-c4/odroid-c4) is a single board -computer based on the Amlogic S905X3 System-on-Chip. - -{% include hw-info.html %} - -Note that only 64-bit mode is supported. - -## Building seL4test - -{% include sel4test.md %} - -## Booting via TFTP - -Make sure you've set up a TFTP server to serve the seL4 image. - -``` -dhcp -tftp 0x20000000 :sel4test-driver-image-arm-odroidc4 -go 0x20000000 -``` diff --git a/Hardware/OdroidXU.html b/Hardware/OdroidXU.html new file mode 100644 index 00000000000..c08bae7dbed --- /dev/null +++ b/Hardware/OdroidXU.html @@ -0,0 +1,653 @@ + + + + + + + seL4 on the Odroid XU | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 on the Odroid XU

+ +

This page provides info on the +Odroid-XU +Exynos 5 board

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform OdroidXU
Architecture ARMv7A
System-on-chip Exynos5
CPU Cortex-A15
seL4 virtualisation support + +
seL4 SMMU support + limited support +
Proofs + +
Proof configsARM, ARM_HYP
seL4 CMake platform nameexynos5410
Contributed by Data61
Maintained by seL4 Foundation
+ +

seL4 assumes that one boots in HYP mode. To do this, one needs a new +signed bootloader.

+ +

Follow the instructions +on the HardKernel Forum to get and flash the firmware

+ +

The standard U-Boot will allow booting via Fastboot or by putting the +bootable ELF file onto an SD card or the eMMC chip.

+ +

Run seL4test using fastboot

+ +

Get and build sel4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=exynos5410 -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Put seL4test onto the board

+ +

Boot the Odroid, with serial cable +attached, and a terminal emulator attached to the serial port.

+ +

Interrupt U-Boot’s autoboot by hitting SPACE

+ +

Enter Fastboot mode by typing fastboot

+ +

On the host,

+ +
mkimage -A arm -a 0x48000000 -e 0x48000000 -C none -A arm -T kernel -O qnx -d images/sel4test-driver-image-arm-exynos5 image
+fastboot boot image
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/OdroidXU.md b/Hardware/OdroidXU.md deleted file mode 100644 index 1e27b4f25f2..00000000000 --- a/Hardware/OdroidXU.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -arm_hardware: true -cmake_plat: exynos5410 -xcompiler_arg: -DAARCH32=1 -platform: OdroidXU -arch: ARMv7A -virtualization: true -iommu: limited -soc: Exynos5 -cpu: Cortex-A15 -verification: [ARM, ARM_HYP] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4 on the Odroid XU - -This page provides info on the -[Odroid-XU](https://www.hardkernel.com/shop/odroid-xu/) -Exynos 5 board - -{% include hw-info.html %} - -seL4 assumes that one boots in HYP mode. To do this, one needs a new -signed bootloader. - -Follow the instructions -[on the HardKernel Forum](http://forum.odroid.com/viewtopic.php?f=64&t=2778&sid=be659cc75c16e1ecf436075e3c548003&start=60#p33805) to get and flash the firmware - -The standard U-Boot will allow booting via Fastboot or by putting the -bootable ELF file onto an SD card or the eMMC chip. - -## Run seL4test using fastboot - -### Get and build sel4test - -{% include sel4test.md %} - -### Put seL4test onto the board - -Boot the Odroid, with serial cable -attached, and a terminal emulator attached to the serial port. - -Interrupt U-Boot's autoboot by hitting SPACE - -Enter Fastboot mode by typing fastboot - -On the host, - -```bash -mkimage -A arm -a 0x48000000 -e 0x48000000 -C none -A arm -T kernel -O qnx -d images/sel4test-driver-image-arm-exynos5 image -fastboot boot image -``` diff --git a/Hardware/OdroidXU4.html b/Hardware/OdroidXU4.html new file mode 100644 index 00000000000..6072f136338 --- /dev/null +++ b/Hardware/OdroidXU4.html @@ -0,0 +1,628 @@ + + + + + + + seL4 on the Odroid XU4 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 on the Odroid XU4

+ +

This page provides info on the +Odroid-XU4 +Exynos 5 board

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform OdroidXU4
Architecture ARMv7A
System-on-chip Exynos5
CPU Cortex-A15
seL4 virtualisation support + +
seL4 SMMU support + limited support +
Proofs + +
Proof configsARM, ARM_HYP
seL4 CMake platform nameexynos5422
Contributed by Data61
Maintained by seL4 Foundation
+ +

Get and build sel4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=exynos5422 -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/OdroidXU4.md b/Hardware/OdroidXU4.md deleted file mode 100644 index 75a8d3c76ea..00000000000 --- a/Hardware/OdroidXU4.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -arm_hardware: true -cmake_plat: exynos5422 -xcompiler_arg: -DAARCH32=1 -platform: OdroidXU4 -arch: ARMv7A -virtualization: true -iommu: limited -soc: Exynos5 -cpu: Cortex-A15 -verification: [ARM, ARM_HYP] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4 on the Odroid XU4 - -This page provides info on the -[Odroid-XU4](https://www.hardkernel.com/shop/odroid-xu4-special-price/) -Exynos 5 board - -{% include hw-info.html %} - -## Get and build sel4test - -{% include sel4test.md %} diff --git a/Hardware/RISCV.html b/Hardware/RISCV.html new file mode 100644 index 00000000000..89080377e00 --- /dev/null +++ b/Hardware/RISCV.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Hardware/Rpi3.html b/Hardware/Rpi3.html new file mode 100644 index 00000000000..5af1ed19f65 --- /dev/null +++ b/Hardware/Rpi3.html @@ -0,0 +1,850 @@ + + + + + + + Raspberry PI 3 Model B and Model B+ | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Raspberry PI 3 Model B and Model B+

+ +
+
+ + Note +
+
+ +

This is an experimental port and is not guaranteed to work. We recommend +using the Raspberry PI4B instead.

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Raspberry Pi 3-b
Architecture ARMv8A
System-on-chip BCM2837
CPU Cortex-A53
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsARM
seL4 CMake platform namebcm2837
Contributed by Data61
Maintained by seL4 Foundation
+ +

Hardware

+ +

raspberry-pi-3-b-reduced-schematics.pdf

+ + + + + + + + + + + + + + + + + + + + + +
FeaturePartDatasheet
USB+ETHSMSC LAN9514pdf
SoCBCM2837 
+ +

Serial connection

+ +

Serial TX and RX are located at GPIO pins 14 and 15 respectively (See Hardware +schematic above)

+ +

Reset

+ +

Short the jumper marked “RUN” between the expansion header and USB sockets to +perform a soft reset of the CPU.

+ +

U-Boot

+ +

Right now, the default U-Boot will not successfully boot an seL4 image +on the RPi3, because of cache configuration issues in the seL4 +ELFLoader. This problem can be remedied by having U-boot disable caches +before loading seL4. Unfortunately, the stock upstream U-boot used to +disable caches before loading the kernel image, but as of this patch, +U-boot no longer disables caches.

+ +

In order to obtain a U-boot binary that disables caching, you can either +compile U-Boot from source yourself, or you can +use this prebuilt U-Boot binary image which already works.

+ +

If you choose to build your own U-boot, then clone U-boot from upstream, +then revert commit 995eab8b5b580b67394312b1621c60a71042cd18, and then +build it:

+ +
git clone https://github.com/u-boot/u-boot.git u-boot
+cd u-boot
+git revert 995eab8b5b580b67394312b1621c60a71042cd18
+make CROSS_COMPILE=arm-linux-gnueabi- rpi_3_32b_defconfig
+make CROSS_COMPILE=arm-linux-gnueabi-
+
+ +

This will enable you to get the most up-to-date U-boot which will boot +seL4 on the RPi3 successfully.

+ +
+
+ + Note +
+
+ +

Automatic revert is not going to work if you are using the latest version of +u-boot. You need to manually revert the change by looking at the changeset.

+ +
+
+ +

Building u-boot using configuration rpi_3_3b_defconfig is going to +produce an image that can boot seL4 on the Raspberry PI Model 3B and +3B+. Unfortunately for the 3B+ tftp boot is not going to work using +this version of u-boot (the tftp command will report error +No Ethernet found). +In this case you need to build an image specific for the 3B+. +Unfortunately the provided defconfig file for the 3B+ model +(rpi_3_b_plus_defconfig) doesn’t appear to build correctly.

+ +

In order to use tftp boot on a Raspberry PI Model 3B+, use the +defconfig for the 3B (as described above), then manually change the +CONFIG_DEFAULT_DEVICE_TREE parameter in the .config from:

+ +
CONFIG_DEFAULT_DEVICE_TREE="bcm2837-rpi-3-b"
+
+ +

to:

+ +
CONFIG_DEFAULT_DEVICE_TREE="bcm2837-rpi-3-b-plus"
+
+ +

Now the generated image should be able to use the on-board +Ethernet device for TFTP.

+ +

SD card setup

+ +

The PI boots from the first FAT32 partition on the SD card. Where files are +specified, they should be located in the root directory of this partition.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StageFilenameDescriptionSource
FSBL-Mounts SD and loads SSBLROM
SSBLbootcode.binLoads GPU firmware and boots GPUhttps://github.com/raspberrypi/firmware/tree/master/boot
GPU firmwarestart.elf or recovery.elfLoads CPU bootloader and boots CPUhttps://github.com/raspberrypi/firmware/tree/master/boot
Usually the Linux kernel, but could also be u-bootu-boot.binu-bootYou can either use our prebuilt U-boot which works, or compile your own using the instructions above
 config.txtu-boot parametersAdd enable_uart=1 and kernel=u-boot.bin to the bottom of config.txt
 uboot.envu-boot saved environmentGenerated by u-boot (default environment) bootcmd copied to bootcmd_orig bootcmd and bootdelay removed
+ +

Getting seL4 onto your Raspberry Pi 3

+ +

In this section you should find the two most convenient methods of getting a +kernel image booted on your RPi3 described. All three methods assume that you +have already built a kernel image using one of our projects—such as seL4Test:

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=bcm2837 -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

The two methods described here are using the SD card and TFTP.

+ +

Both methods require you to use an SD card to provide the RPi3 firmware +with a U-boot bootloader it can load. The RPi3 doesn’t store its +bootloader in flash memory, so it looks for the bootloader on the SD +card. Please see the section above for how to prepare your SD Card for +the base set of requirements; you can glance at the table above to see +the files you’ll need and how to obtain them.

+ +

SD Card

+ +

Get a micro-SD card ready by getting the base files copied onto it (See the +previous section).

+ +

Following this, copy your seL4 image (such as an seL4test image), onto +the SD card in its root directory - that’s it. You can now remove the SD +Card from your PC and re-insert it into the RPi3, and power the RPi3 on.

+ +

When the RPi3 boots up, be sure to interrupt the boot process and drop +into the U-boot command prompt. From the U-boot command prompt, type +something the following: fatls mmc 0. If you don’t see your seL4 image +file’s name printed out, then you might need to double-check your steps +so far to make sure you didn’t forget something along the way. If you +see your file listed, then do something like:

+ +
fatload mmc 0 0x10000000 sel4test-driver-image-arm-bcm2837
+bootelf 0x10000000
+
+ +

TFTP

+ +

Be sure you’ve set up the internal SD card with the required files for +U-Boot and the RPi3 firmware (consult the table above). Then make +certain that you’ve started up a TFTP server with your seL4 image being +served by that TFTP server. From there:

+ +
usb start
+dhcp
+tftp 0x10000000 <YOUR_TFTP_SERVER_IP_ADDRESS>:sel4test-driver-image-arm-bcm2837
+bootelf 0x10000000
+
+ +

If you are using a Raspberry PI Model 3B+, make sure you build the +correct u-boot image as described above.

+ +

To use static IP instead of DHCP, use:

+ +
usb start
+setenv ipaddr <RPI_IP_ADDRESS>
+setenv serverip <YOUR_TFTP_SERVER_IP_ADDRESS>
+tftp 0x10000000 sel4test-driver-image-arm-bcm2837
+bootelf 0x10000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/Rpi3.md b/Hardware/Rpi3.md deleted file mode 100644 index a73e40b6da0..00000000000 --- a/Hardware/Rpi3.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -arm_hardware: true -cmake_plat: bcm2837 -xcompiler_arg: -DAARCH32=1 -platform: Raspberry Pi 3-b -arch: ARMv8A -virtualization: true -iommu: false -soc: BCM2837 -cpu: Cortex-A53 -verification: [ARM] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Raspberry PI 3 Model B and Model B+ - -{% include note.html %} -This is an experimental port and is not guaranteed to work. We recommend -using the [Raspberry PI4B](./Rpi4.md) instead. -{% include endnote.html %} - -{% include hw-info.html %} - -## Hardware - -[raspberry-pi-3-b-reduced-schematics.pdf](https://datasheets.raspberrypi.com/rpi3/raspberry-pi-3-b-reduced-schematics.pdf) - -|Feature |Part |Datasheet | -|-|-|-| -|USB+ETH |SMSC LAN9514|[pdf](https://ww1.microchip.com/downloads/aemDocuments/documents/OTH/ProductDocuments/DataSheets/00002306A.pdf)| -|SoC |BCM2837 | | - -## Serial connection - -Serial TX and RX are located at GPIO pins 14 and 15 respectively (See Hardware -schematic above) - -## Reset - -Short the jumper marked "RUN" between the expansion header and USB sockets to -perform a soft reset of the CPU. - -## U-Boot - -Right now, the default U-Boot will not successfully boot an seL4 image -on the RPi3, because of cache configuration issues in the seL4 -ELFLoader. This problem can be remedied by having U-boot disable caches -before loading seL4. Unfortunately, the stock upstream U-boot used to -disable caches before loading the kernel image, but as of [this patch](https://github.com/u-boot/u-boot/commit/995eab8b5b580b67394312b1621c60a71042cd18), -U-boot no longer disables caches. - -In order to obtain a U-boot binary that disables caching, you can either -compile U-Boot from source yourself, or you can -**[use this prebuilt U-Boot binary image which already works](https://sel4.systems/Info/Docs/u-boot-working-rpi3-32bit-v2017.11.bin)**. - -If you choose to build your own U-boot, then clone U-boot from upstream, -then revert commit 995eab8b5b580b67394312b1621c60a71042cd18, and then -build it: - -```bash -git clone https://github.com/u-boot/u-boot.git u-boot -cd u-boot -git revert 995eab8b5b580b67394312b1621c60a71042cd18 -make CROSS_COMPILE=arm-linux-gnueabi- rpi_3_32b_defconfig -make CROSS_COMPILE=arm-linux-gnueabi- -``` - -This will enable you to get the most up-to-date U-boot which will boot -seL4 on the RPi3 successfully. - -{% include note.html %} -Automatic revert is not going to work if you are using the latest version of -u-boot. You need to manually revert the change by looking at the changeset. -{% include endnote.html %} - -Building u-boot using configuration `rpi_3_3b_defconfig` is going to -produce an image that can boot seL4 on the Raspberry PI Model 3B and -3B+. Unfortunately for the 3B+ tftp boot is not going to work using -this version of u-boot (the `tftp` command will report error -`No Ethernet found`). -In this case you need to build an image specific for the 3B+. -Unfortunately the provided defconfig file for the 3B+ model -(`rpi_3_b_plus_defconfig`) doesn't appear to build correctly. - -In order to use tftp boot on a Raspberry PI Model 3B+, use the -defconfig for the 3B (as described above), then manually change the -`CONFIG_DEFAULT_DEVICE_TREE` parameter in the `.config` from: - -```config -CONFIG_DEFAULT_DEVICE_TREE="bcm2837-rpi-3-b" -``` - -to: - -```config -CONFIG_DEFAULT_DEVICE_TREE="bcm2837-rpi-3-b-plus" -``` - -Now the generated image should be able to use the on-board -Ethernet device for TFTP. - - -## SD card setup - -The PI boots from the first FAT32 partition on the SD card. Where files are -specified, they should be located in the root directory of this partition. - -|Stage |Filename |Description |Source| -|-|-|-|-| -|FSBL |- |Mounts SD and loads SSBL |ROM | -|SSBL |bootcode.bin|Loads GPU firmware and boots GPU| | -|GPU firmware |start.elf or recovery.elf |Loads CPU bootloader and boots CPU | | -|Usually the Linux kernel, but could also be u-boot |u-boot.bin |u-boot| You can either [use our prebuilt U-boot which works](https://sel4.systems/Info/Docs/u-boot-working-rpi3-32bit-v2017.11.bin), or compile your own using the instructions above | -||config.txt|u-boot parameters |Add enable_uart=1 and kernel=u-boot.bin to the bottom of config.txt | -||uboot.env |u-boot saved environment |Generated by u-boot (default environment) bootcmd copied to bootcmd_orig bootcmd and bootdelay removed | - -## Getting seL4 onto your Raspberry Pi 3 - -In this section you should find the two most convenient methods of getting a -kernel image booted on your RPi3 described. All three methods assume that you -have already built a kernel image using one of our projects---such as seL4Test: - -{% include sel4test.md %} - -The two methods described here are using the SD card and TFTP. - -Both methods require you to use an SD card to provide the RPi3 firmware -with a U-boot bootloader it can load. The RPi3 doesn't store its -bootloader in flash memory, so it looks for the bootloader on the SD -card. Please see the section above for how to prepare your SD Card for -the base set of requirements; you can glance at the table above to see -the files you'll need and how to obtain them. - -### SD Card - -Get a micro-SD card ready by getting the base files copied onto it (See the -previous section). - -Following this, copy your seL4 image (such as an seL4test image), onto -the SD card in its root directory - that's it. You can now remove the SD -Card from your PC and re-insert it into the RPi3, and power the RPi3 on. - -When the RPi3 boots up, be sure to interrupt the boot process and drop -into the U-boot command prompt. From the U-boot command prompt, type -something the following: fatls mmc 0. If you don't see your seL4 image -file's name printed out, then you might need to double-check your steps -so far to make sure you didn't forget something along the way. If you -see your file listed, then do something like: - -``` -fatload mmc 0 0x10000000 sel4test-driver-image-arm-bcm2837 -bootelf 0x10000000 -``` - -### TFTP - -Be sure you've set up the internal SD card with the required files for -U-Boot and the RPi3 firmware (consult the table above). Then make -certain that you've started up a TFTP server with your seL4 image being -served by that TFTP server. From there: - -``` -usb start -dhcp -tftp 0x10000000 :sel4test-driver-image-arm-bcm2837 -bootelf 0x10000000 -``` - -If you are using a Raspberry PI Model 3B+, make sure you build the -correct u-boot image as described above. - -To use static IP instead of DHCP, use: - -``` -usb start -setenv ipaddr -setenv serverip -tftp 0x10000000 sel4test-driver-image-arm-bcm2837 -bootelf 0x10000000 -``` diff --git a/Hardware/Rpi4.html b/Hardware/Rpi4.html new file mode 100644 index 00000000000..6aabee852f9 --- /dev/null +++ b/Hardware/Rpi4.html @@ -0,0 +1,737 @@ + + + + + + + Raspberry Pi 4 Model B | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Raspberry Pi 4 Model B

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Raspberry Pi 4B
Architecture ARMv8A
System-on-chip BCM2711
CPU Cortex-A72
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform namerpi4
Contributed by Hensoldt and ARM Research IceCap
Maintained by seL4 Foundation
+ +

Serial connection

+ +

Serial TX and RX are located at GPIO pins 14 and 15 respectively.

+ +

U-Boot

+ +

In order to build U-Boot for the Raspberry Pi 4B, run the following commands:

+
git clone https://github.com/u-boot/u-boot.git u-boot
+cd u-boot
+make CROSS_COMPILE=aarch64-linux-gnu- rpi_4_defconfig
+make CROSS_COMPILE=aarch64-linux-gnu-
+
+ +

In the u-boot directory you should now see the U-Boot image u-boot.bin indicating that U-Boot has successfully compiled.

+ +

More information regarding U-Boot support for the Raspberry Pi can be found here.

+ +

SD card setup

+

The RPi4 boots from the first FAT32 partition on the microSD card. Where files are specified, +they should be located in the root directory of this partition.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StageFilenameDescriptionSource
FSBL-Mounts SD and loads SSBLROM
GPU firmwarestart4.elfLoads CPU bootloader and boots CPUhttps://github.com/raspberrypi/firmware/tree/master/boot/start4.elf
Additional GPU firmwarefixup4.datFixes memory locations used in start4.elfhttps://github.com/raspberrypi/firmware/tree/master/boot/fixup4.dat
Usually the Linux kernel, but could also be U-Bootu-boot.binU-Boot binaryCompiled using the instructions above
 config.txtU-Boot parametersAdd arm_64bit=1 and kernel=u-boot.bin to the bottom of config.txt
 uboot.envU-Boot saved environmentGenerated by U-Boot (default environment) bootcmd copied to bootcmd_orig bootcmd and bootdelay removed. This file will not exist when you first setup your SD card.
 bcm2711-rpi-4-b.dtbRPi4 device tree blobhttps://github.com/raspberrypi/firmware/tree/master/boot/bcm2711-rpi-4-b.dtb
 overlays/*Device tree overlayshttps://github.com/raspberrypi/firmware/tree/master/boot/overlays
+ +

Getting seL4 onto your Raspberry Pi 4

+ +

The final step to test that you have setup your RPi4 correctly is to build and run the +seL4test project.

+ +

You will see that the init-build.sh command contains the flag +-DRPI4_MEMORY, this specifies how much RAM exists on the Raspberry Pi that will run +the final seL4 image. Since seL4 needs to know the physical memory layout of the hardware +at build time, and the RPi4 has multiple models with different amounts of RAM, we have to +specify how much RAM the system will have when we build seL4. If -DRPI4_MEMORY is not supplied, +seL4 defaults to expecting 8GB of memory.

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=rpi4 -DAARCH64=1 -DRPI4_MEMORY=<1024,2048,4096,8192>
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Now that we have a bootable image, we can run it on your RPi4. The following instructions describe +how to use a microSD card to boot seL4, using the seL4test image as well as the files mentioned +in the previous section.

+ +

The first step is to copy the seL4 image onto the microSD card to the root directory. After +removing the card from your computer and inserting into your RPi4, you can power on the RPi4.

+ +

Once the RPi4 boots up, you will see something like the following text from U-Boot:

+
Hit any key to stop autoboot:  2
+
+ +

At this point you want to interrupt the U-Boot booting process by pressing any key.

+ +

You will now be in the U-Boot command prompt, type the following command:

+
fatls mmc 0
+
+ +

You should see the seL4test image you just placed on your microSD card.

+ +

From here, you can load and boot the image using:

+
fatload mmc 0 0x10000000 sel4test-driver-image-arm-bcm2711
+go 0x10000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/Rpi4.md b/Hardware/Rpi4.md deleted file mode 100644 index 0e396c07839..00000000000 --- a/Hardware/Rpi4.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -arm_hardware: true -cmake_plat: rpi4 -xcompiler_arg: -DAARCH64=1 -DRPI4_MEMORY=<1024,2048,4096,8192> -platform: Raspberry Pi 4B -arch: ARMv8A -virtualization: true -iommu: false -soc: BCM2711 -cpu: Cortex-A72 -verification: [AARCH64] -Contrib: 'Hensoldt and ARM Research IceCap' -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Raspberry Pi 4 Model B - -{% include hw-info.html %} - -## Serial connection - -Serial TX and RX are located at GPIO pins 14 and 15 respectively. - -## U-Boot - -In order to build U-Boot for the Raspberry Pi 4B, run the following commands: -```bash -git clone https://github.com/u-boot/u-boot.git u-boot -cd u-boot -make CROSS_COMPILE=aarch64-linux-gnu- rpi_4_defconfig -make CROSS_COMPILE=aarch64-linux-gnu- -``` - -In the `u-boot` directory you should now see the U-Boot image `u-boot.bin` indicating that U-Boot has successfully compiled. - -More information regarding U-Boot support for the Raspberry Pi can be found [here](https://u-boot.readthedocs.io/en/latest/board/broadcom/raspberrypi.html). - -## SD card setup -The RPi4 boots from the first FAT32 partition on the microSD card. Where files are specified, -they should be located in the root directory of this partition. - -|Stage |Filename |Description |Source| -|-|-|-|-| -|FSBL |- |Mounts SD and loads SSBL |ROM | -|GPU firmware |start4.elf |Loads CPU bootloader and boots CPU | | -|Additional GPU firmware |fixup4.dat |Fixes memory locations used in start4.elf | | -|Usually the Linux kernel, but could also be U-Boot |u-boot.bin |U-Boot binary| Compiled using the instructions above | -||config.txt|U-Boot parameters |Add `arm_64bit=1` and `kernel=u-boot.bin` to the bottom of `config.txt` | -||uboot.env |U-Boot saved environment |Generated by U-Boot (default environment) bootcmd copied to bootcmd_orig bootcmd and bootdelay removed. This file will not exist when you first setup your SD card. | -||bcm2711-rpi-4-b.dtb | RPi4 device tree blob | | -||overlays/* | Device tree overlays | | - -## Getting seL4 onto your Raspberry Pi 4 - -The final step to test that you have setup your RPi4 correctly is to build and run the -seL4test project. - -You will see that the `init-build.sh` command contains the flag -`-DRPI4_MEMORY`, this specifies how much RAM exists on the Raspberry Pi that will run -the final seL4 image. Since seL4 needs to know the physical memory layout of the hardware -at build time, and the RPi4 has multiple models with different amounts of RAM, we have to -specify how much RAM the system will have when we build seL4. If `-DRPI4_MEMORY` is not supplied, -seL4 defaults to expecting 8GB of memory. - -{% include sel4test.md %} - -Now that we have a bootable image, we can run it on your RPi4. The following instructions describe -how to use a microSD card to boot seL4, using the seL4test image as well as the files mentioned -in the previous section. - -The first step is to copy the seL4 image onto the microSD card to the root directory. After -removing the card from your computer and inserting into your RPi4, you can power on the RPi4. - -Once the RPi4 boots up, you will see something like the following text from U-Boot: -``` -Hit any key to stop autoboot: 2 -``` - -At this point you want to interrupt the U-Boot booting process by pressing any key. - -You will now be in the U-Boot command prompt, type the following command: -``` -fatls mmc 0 -``` - -You should see the seL4test image you just placed on your microSD card. - -From here, you can load and boot the image using: -``` -fatload mmc 0 0x10000000 sel4test-driver-image-arm-bcm2711 -go 0x10000000 -``` diff --git a/Hardware/Star64/index.html b/Hardware/Star64/index.html new file mode 100644 index 00000000000..3dbc6d7fefe --- /dev/null +++ b/Hardware/Star64/index.html @@ -0,0 +1,815 @@ + + + + + + + Pine64 Star64 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Pine64 Star64

+ +

The Star64 is a RISC-V SBC by Pine64 based on the StarFive JH7110 SoC. Check +the Pine64 Wiki for details.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Pine64 Star64
Architecture RV64GBC, RV64IMAC, RV32IMAFBC
System-on-chip StarFive JH7110
CPU U74-MC, E24
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform namestar64
Contributed by Community
Maintained by seL4 Foundation
+ +

The StarFive JH7110 SoC is comprised of the SiFive U74-MC (four 64-bit U74 +cores and one 64-bit S7 core) and one SiFive E24 32-bit core. Note that by +default seL4 is setup to use the U74 cores as neither the S7 or E24 core has +S-Mode, which seL4 requires.

+ +

The Star64 arrives with the following boot process from the SPI flash:

+ +
    +
  1. U-Boot SPL starts
    2. +
  2. OpenSBI starts
    3. +
  3. U-Boot proper starts
    4. +
+ +

From U-Boot proper you can then load and start an seL4 image, see below for details.

+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=star64 -DRISCV64=1 -DUseRiscVOpenSBI=OFF
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Booting via microSD card

+ +
fatload mmc 1 0x60000000 sel4test-driver-image-riscv-star64
+go 0x60000000
+
+ +

Booting via TFTP

+ +

If you have setup a TFTP server, enter the following commands on the U-Boot console +to load an image via the network.

+ +
dhcp
+tftpboot 0x60000000 <YOUR_TFTP_SERVER_IP_ADDRESS>:sel4test-driver-image-riscv-star64
+go 0x60000000
+
+ +

Producing a SD card bootable image

+ +

If you require a custom U-Boot or have other constraints, you may need to create +your own bootable image. The following instructions show how to make a bootable +image for a microSD card that can then be inserted into the Star64. Note that you +will need to change the booting mode via the DIP switch, like so:

+ +

Star64 DIP switch when booting via microSD card

+ +

The boot process of this bootable image is the same as the SPI flash booting +process. Unfortunately, at the time of writing, U-Boot does not support booting +in M-Mode which means U-Boot must be loaded by an SBI in S-Mode.

+ +

Acquiring sources

+ +

At the time of writing, mainline U-Boot does not support the Pine64 Star64, hence +if you want to built it yourself, there is a patch to apply available on a fork of +U-Boot. Note that these instructions are reproduced from here.

+ +
git clone https://github.com/Fishwaldo/u-boot.git --branch Star64
+git clone https://github.com/riscv/opensbi.git
+git clone https://github.com/starfive-tech/soft_3rdpart.git
+
+ +

Compiling U-Boot and U-Boot SPL

+ +
CROSS_COMPILE=<RISCV_TOOLCHAIN> make -C u-boot pine64_star64_defconfig
+CROSS_COMPILE=<RISCV_TOOLCHAIN> make -C u-boot
+
+ +

Compiling OpenSBI

+ +

Now that we have U-Boot, we can make the OpenSBI image that contains U-Boot as the +payload.

+ +
mkdir -p opensbi_build
+make -C $OPENSBI PLATFORM=generic \
+                    CROSS_COMPILE=<RISCV_TOOLCHAIN> \
+                    FW_FDT_PATH=u-boot/arch/riscv/dts/pine64_star64.dtb \
+                    FW_PAYLOAD_PATH=u-boot/u-boot.bin \
+                    PLATFORM_RISCV_XLEN=64 \
+                    PLATFORM_RISCV_ISA=rv64imafdc \
+                    PLATFORM_RISCV_ABI=lp64d \
+                    O=opensbi_build \
+                    FW_TEXT_START=0x40000000 \
+
+ +

Now we need to take the payload and turn it into a Flattened uImage Tree (FIT) for U-Boot SPL +to load.

+ +

First we’ll need an ITS file to describe the FIT:

+ +
/dts-v1/;
+
+/ {
+    description = "U-boot-spl FIT image for JH7110 Pine64 Star64";
+    #address-cells = <2>;
+
+    images {
+        firmware {
+            description = "u-boot";
+            data = /incbin/("opensbi_build/platform/generic/firmware/fw_payload.bin");
+            type = "firmware";
+            arch = "riscv";
+            os = "u-boot";
+            load = <0x0 0x40000000>;
+            entry = <0x0 0x40000000>;
+            compression = "none";
+        };
+    };
+
+    configurations {
+        default = "config-1";
+
+        config-1 {
+            description = "U-boot-spl FIT config for JH7110 Pine64 Star64";
+            firmware = "firmware";
+        };
+    };
+};
+
+ +

Now, invoke the mkimage tool to generate the FIT.

+ +
mkimage -f <ITS_FILE> -A riscv -O u-boot -T firmware opensbi_uboot_fit.img
+
+ +

Add SPL header to U-Boot SPL binary

+ +

First we need to compile a small tool that adds the SPL header to the U-Boot +SPL image.

+ +
cd soft_3rdpart/spl_tool
+make
+
+ +

Now invoke the tool on the U-Boot SPL image:

+ +
spl_tool -c -f u-boot/spl/u-boot-spl.bin
+
+ +

You should now have a file called u-boot-spl.bin.normal.out.

+ +

Generate bootable image

+ +

Lastly, we need to create the bootable image from all of these binaries. For this +the genimage tool is used.

+ +

First, we’ll need the configuration file. Note that you will have to change the +paths to match where you build each binary.

+ +
image sdcard.img {
+    hdimage {
+        gpt = true
+    }
+
+    partition spl {
+        image = "/path/to/u-boot-spl.bin.normal.out"
+        partition-type-uuid = 2E54B353-1271-4842-806F-E436D6AF6985
+        offset = 2M
+        size = 2M
+    }
+
+    partition uboot {
+        image = "/path/to/opensbi_uboot_fit.img"
+        partition-type-uuid = 5B193300-FC78-40CD-8002-E86C45580B47
+        offset = 4M
+        size = 4M
+    }
+}
+
+ +

Now we can pass this configuration, a temporary directory path, and a root +directory path to the genimage tool.

+ +
# genimage expects these directories to exist before invoking it
+mkdir -p temp
+mkdir -p root
+# <INPUT_PATH> represents the top dir from where the genimage tool looks for
+# the image paths in the configuration file
+genimage --config <GENIMAGE_CONFIG> --inputpath <INPUT_PATH> --tmppath temp
+
+ +

The final image will be images/sdcard.img. You can either use the dd utility +or the balenaEtcher program to write the image to +your microSD card.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/Star64/index.md b/Hardware/Star64/index.md deleted file mode 100644 index 786ecdc54fb..00000000000 --- a/Hardware/Star64/index.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: star64 -xcompiler_arg: -DRISCV64=1 -DUseRiscVOpenSBI=OFF -platform: Pine64 Star64 -arch: RV64GBC, RV64IMAC, RV32IMAFBC -virtualization: false -iommu: false -simulation_target: false -verification: [] -Contrib: "Community" -Maintained: "seL4 Foundation" -soc: StarFive JH7110 -cpu: U74-MC, E24 -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Pine64 Star64 - -The Star64 is a RISC-V SBC by Pine64 based on the StarFive JH7110 SoC. Check -the [Pine64 Wiki](https://wiki.pine64.org/wiki/STAR64) for details. - -{% include hw-info.html %} - -The StarFive JH7110 SoC is comprised of the SiFive U74-MC (four 64-bit U74 -cores and one 64-bit S7 core) and one SiFive E24 32-bit core. Note that by -default seL4 is setup to use the U74 cores as neither the S7 or E24 core has -S-Mode, which seL4 requires. - -The Star64 arrives with the following boot process from the SPI flash: - -1. U-Boot SPL starts -2. OpenSBI starts -3. U-Boot proper starts - -From U-Boot proper you can then load and start an seL4 image, see below for details. - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Building seL4test - -{% include sel4test.md %} - -## Booting via microSD card - -```sh -fatload mmc 1 0x60000000 sel4test-driver-image-riscv-star64 -go 0x60000000 -``` - -## Booting via TFTP - -If you have setup a TFTP server, enter the following commands on the U-Boot console -to load an image via the network. - -```sh -dhcp -tftpboot 0x60000000 :sel4test-driver-image-riscv-star64 -go 0x60000000 -``` - -## Producing a SD card bootable image - -If you require a custom U-Boot or have other constraints, you may need to create -your own bootable image. The following instructions show how to make a bootable -image for a microSD card that can then be inserted into the Star64. Note that you -will need to change the booting mode via the DIP switch, like so: - -![Star64 DIP switch when booting via microSD card](dip_switch.png) - -The boot process of this bootable image is the same as the SPI flash booting -process. Unfortunately, at the time of writing, U-Boot does not support booting -in M-Mode which means U-Boot must be loaded by an SBI in S-Mode. - -### Acquiring sources - -At the time of writing, mainline U-Boot does not support the Pine64 Star64, hence -if you want to built it yourself, there is a patch to apply available on a fork of -U-Boot. Note that these instructions are reproduced from [here](https://github.com/Ivan-Velickovic/star64_sdcard). - -```sh -git clone https://github.com/Fishwaldo/u-boot.git --branch Star64 -git clone https://github.com/riscv/opensbi.git -git clone https://github.com/starfive-tech/soft_3rdpart.git -``` - -### Compiling U-Boot and U-Boot SPL - -```sh -CROSS_COMPILE= make -C u-boot pine64_star64_defconfig -CROSS_COMPILE= make -C u-boot -``` - -### Compiling OpenSBI - -Now that we have U-Boot, we can make the OpenSBI image that contains U-Boot as the -payload. - -```sh -mkdir -p opensbi_build -make -C $OPENSBI PLATFORM=generic \ - CROSS_COMPILE= \ - FW_FDT_PATH=u-boot/arch/riscv/dts/pine64_star64.dtb \ - FW_PAYLOAD_PATH=u-boot/u-boot.bin \ - PLATFORM_RISCV_XLEN=64 \ - PLATFORM_RISCV_ISA=rv64imafdc \ - PLATFORM_RISCV_ABI=lp64d \ - O=opensbi_build \ - FW_TEXT_START=0x40000000 \ -``` - -Now we need to take the payload and turn it into a Flattened uImage Tree (FIT) for U-Boot SPL -to load. - -First we'll need an ITS file to describe the FIT: - -```sh -/dts-v1/; - -/ { - description = "U-boot-spl FIT image for JH7110 Pine64 Star64"; - #address-cells = <2>; - - images { - firmware { - description = "u-boot"; - data = /incbin/("opensbi_build/platform/generic/firmware/fw_payload.bin"); - type = "firmware"; - arch = "riscv"; - os = "u-boot"; - load = <0x0 0x40000000>; - entry = <0x0 0x40000000>; - compression = "none"; - }; - }; - - configurations { - default = "config-1"; - - config-1 { - description = "U-boot-spl FIT config for JH7110 Pine64 Star64"; - firmware = "firmware"; - }; - }; -}; -``` - -Now, invoke the `mkimage` tool to generate the FIT. - -```sh -mkimage -f -A riscv -O u-boot -T firmware opensbi_uboot_fit.img -``` - -### Add SPL header to U-Boot SPL binary - -First we need to compile a small tool that adds the SPL header to the U-Boot -SPL image. - -```sh -cd soft_3rdpart/spl_tool -make -``` - -Now invoke the tool on the U-Boot SPL image: - -```sh -spl_tool -c -f u-boot/spl/u-boot-spl.bin -``` - -You should now have a file called `u-boot-spl.bin.normal.out`. - -### Generate bootable image - -Lastly, we need to create the bootable image from all of these binaries. For this -the `genimage` tool is used. - -First, we'll need the configuration file. Note that you will have to change the -paths to match where you build each binary. - -```conf -image sdcard.img { - hdimage { - gpt = true - } - - partition spl { - image = "/path/to/u-boot-spl.bin.normal.out" - partition-type-uuid = 2E54B353-1271-4842-806F-E436D6AF6985 - offset = 2M - size = 2M - } - - partition uboot { - image = "/path/to/opensbi_uboot_fit.img" - partition-type-uuid = 5B193300-FC78-40CD-8002-E86C45580B47 - offset = 4M - size = 4M - } -} -``` - -Now we can pass this configuration, a temporary directory path, and a root -directory path to the genimage tool. - -```sh -# genimage expects these directories to exist before invoking it -mkdir -p temp -mkdir -p root -# represents the top dir from where the genimage tool looks for -# the image paths in the configuration file -genimage --config --inputpath --tmppath temp -``` - -The final image will be `images/sdcard.img`. You can either use the `dd` utility -or the [balenaEtcher](https://www.balena.io/etcher) program to write the image to -your microSD card. diff --git a/Hardware/VMware/index.html b/Hardware/VMware/index.html new file mode 100644 index 00000000000..9cda07bde94 --- /dev/null +++ b/Hardware/VMware/index.html @@ -0,0 +1,690 @@ + + + + + + + seL4 on VMware | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 on VMware

+ +

This is a quick guide on how to run seL4 x86 on VMWare Workstation/Player. +Written based on decently up-to-date versions Workstation 9 & 10 Player 5 & 6 +and for a Linux host machine. May work on Mac host machine, won’t work for +Windows host (although general idea should be similar).

+ +

This guide assumes that your project is all set up and configured to build for +x86. Read the set up +instructions otherwise.

+ +

Setting up a VM

+ +

Both the free non-commercial Player and Workstation run seL4 fine; the +difference with player is that additional setup is required to automate +everything if you use Player. In order to start / stop VMWare from the +command line you need to install VMWare VIX API for Player. Workstation +comes with VIX and Player both installed.

+ +

Once you get VMWare installed and running, go on and create a VM for +seL4 (choose install OS later, and choose “Other” for guest OS type).

+ +

Set Up Serial Port

+ +

After you have a VM, we want to add a serial port so we can see the +stuff we print out. Go machine configuration -> Add device -> +Serial port.

+ +

Make sure this is the only serial port, and it is serial port 0. If you +selected Guest OS type “Ubuntu” or something VMWare may set up a secret +hidden serial port which you can’t edit from the GUI. Choose “Other” for +guest type.

+ +

Virtual Machine Settings

+ +

There are three options for the serial port

+ +
    +
  1. Output to a text file (easiest but output only). The VM +will dump its serial output to a text file when it runs, and you +can simply go less -F <file>.
    2. +
  2. +

    Use physical serial port (best but requires serial cable + +another machine to minicom/picocom off it). Set it to /dev/ttyS0 +or something.

    +
    3. +
  3. Output to a socket (allows input/output but annoying to +set up). You’ll want to apt-get install socat and then run something +like: + 
    #!/bin/bash
+while true; do
+ socat -d -d UNIX-CONNECT:/tmp/vsock,forever PTY:link=/dev/tty99
+done
+
    +

    and + then minicom to /dev/tty99 or + to /dev/pts/<whatever socat decides to use>.

    +
    4. +
+ +

Choose depending on whether you can get a serial cable from your +machine, whether you need output…etc. Easiest is to just use a text +file.

+ +

Install GRUB2

+ +

Once you have a VM, you’ll want to set up the hard disk partitions and +get GRUB2 on the virtual hard disk and its MBR somehow. Easiest way to +do this is simple install some Linux distro that has GRUB2 (Ubuntu +Debian Fedora…etc). If you want to save some hard disk space you can +try +Ubuntu Minimal. Choose to install GRUB to the MBR when installing your OS.

+ +

Alternatively if you feel like extra headaches to save space and time +you can try install GRUB2 manually with grub-install from some Linux +Live CD image.

+ +

Add GRUB2 Option To Run seL4

+ +

Now we want to edit its grub.cfg (usually in /grub2 or /boot/grub +or something like that) somehow and modify it to boot our seL4 kernel + +userland binary.

+ +

Simplest method is to simply use VMWare player to boot into the guest OS +you just installed, and then edit the grub.cfg from the guest OS itself.

+ +

Another method is to use vmware-mount:

+
# Usage: vmware-mount diskPath [partition num] mountPoint
+mkdir /tmp/vmount
+vmware-mount /path/to/your/HD.vmdk /tmp/vmount
+# Now do your editing in /tmp/vmount.
+vmware-mount -d /tmp/vmount
+
+ +

Once you have grub.cfg open in your favourite editor, Add an extra +option to it:

+
menuentry 'seL4' --class fedora --class gnu-linux --class gnu --class os {
+    load_video
+    insmod gzio
+    insmod part_msdos
+    insmod ext2
+    set root='(hd0,msdos1)'
+    search --no-floppy --fs-uuid --set=root <deviceID>
+    echo 'Loading seL4 kernel'
+    multiboot /kernel-image-ia32-pc99
+    echo 'Loading initial module ...'
+    module /sel4-image-ia32-pc99
+}
+
+ +

Of course, change the --set=root <DeviceID> line to your +DeviceID (set the DeviceID from other entries already in your grub.cfg), +and also change the sel4-image-ia32-pc99 to match the name of your +binary image that your Make produces (look in your build logs or in +images/ folder).

+ +

Also may be a good idea to add set default=<seL4 menu index> +to the grub.cfg, so grub is configured to boot seL4.

+ +

Using The VM to run seL4

+ +

Now you have a VM ready, you’ll want to copy your built kernel + +userland binary image over onto its HD, and then start the VM, and +choose the seL4 option in GRUB, and then monitor the serial output. You +will need to repeat this entire above process every time you build & run +seL4. Fortunately I have a script does all of the above in one go (may +need editing of paths here and there to fit where you put things).

+ +

Download seL4vmw.py

+ +

Do It Manually

+ +

First, use vmware-mount to mount the vmdk disk image. Then copy your +newly built kernel and user binaries over. Then, unmount using +vmware -d.

+ +

Then start your VM (either from VMWare Player GUI or using the vmrun +script from VIX API), and choose seL4 boot option. Monitor serial +output. If you’ve set up the seL4 option as the grub default then you +just need to wait for the grub time out.

+ +

If your kernel fails an assert during startup, make sure your kernel +repo is up to date.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/VMware/index.md b/Hardware/VMware/index.md deleted file mode 100644 index c3b8d5f726d..00000000000 --- a/Hardware/VMware/index.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4 on VMware - - -This is a quick guide on how to run seL4 x86 on VMWare Workstation/Player. -Written based on decently up-to-date versions Workstation 9 & 10 Player 5 & 6 -and for a Linux host machine. May work on Mac host machine, won't work for -Windows host (although general idea should be similar). - -This guide assumes that your project is all set up and configured to build for -x86. Read the [set up -instructions](../../projects/buildsystem/host-dependencies.html) otherwise. - -## Setting up a VM - - -Both the free non-commercial Player and Workstation run seL4 fine; the -difference with player is that additional setup is required to automate -everything if you use Player. In order to start / stop VMWare from the -command line you need to install VMWare VIX API for Player. Workstation -comes with VIX and Player both installed. - -Once you get VMWare installed and running, go on and create a VM for -seL4 (choose install OS later, and choose "Other" for guest OS type). - -### Set Up Serial Port - - -After you have a VM, we want to add a serial port so we can see the -stuff we print out. Go machine configuration -> Add device -> -Serial port. - -Make sure this is the only serial port, and it is serial port 0. If you -selected Guest OS type "Ubuntu" or something VMWare may set up a secret -hidden serial port which you can't edit from the GUI. Choose "Other" for -guest type. - -Virtual Machine Settings - -There are three options for the serial port - -1. **Output to a text file** (easiest but output only). The VM - will dump its serial output to a text file when it runs, and you - can simply go `less -F `. -2. **Use physical serial port** (best but requires serial cable + - another machine to minicom/picocom off it). Set it to /dev/ttyS0 - or something. - -3. **Output to a socket** (allows input/output but annoying to -set up). You'll want to apt-get install socat and then run something -like: -```bash -#!/bin/bash -while true; do - socat -d -d UNIX-CONNECT:/tmp/vsock,forever PTY:link=/dev/tty99 -done -``` -and - then minicom to `/dev/tty99` or - to `/dev/pts/`. - -Choose depending on whether you can get a serial cable from your -machine, whether you need output...etc. Easiest is to just use a text -file. - -### Install GRUB2 - - -Once you have a VM, you'll want to set up the hard disk partitions and -get GRUB2 on the virtual hard disk and its MBR somehow. Easiest way to -do this is simple install some Linux distro that has GRUB2 (Ubuntu -Debian Fedora...etc). If you want to save some hard disk space you can -try -[Ubuntu Minimal](https://help.ubuntu.com/community/Installation/MinimalCD). Choose to install GRUB to the MBR when installing your OS. - -Alternatively if you feel like extra headaches to save space and time -you can try install GRUB2 manually with grub-install from some Linux -Live CD image. - -### Add GRUB2 Option To Run seL4 - - -Now we want to edit its **grub.cfg** (usually in /grub2 or /boot/grub -or something like that) somehow and modify it to boot our seL4 kernel + -userland binary. - -Simplest method is to simply use VMWare player to boot into the guest OS -you just installed, and then edit the grub.cfg from the guest OS itself. - -Another method is to use **vmware-mount**: -```bash -# Usage: vmware-mount diskPath [partition num] mountPoint -mkdir /tmp/vmount -vmware-mount /path/to/your/HD.vmdk /tmp/vmount -# Now do your editing in /tmp/vmount. -vmware-mount -d /tmp/vmount -``` - -Once you have grub.cfg open in your favourite editor, Add an extra -option to it: -``` -menuentry 'seL4' --class fedora --class gnu-linux --class gnu --class os { - load_video - insmod gzio - insmod part_msdos - insmod ext2 - set root='(hd0,msdos1)' - search --no-floppy --fs-uuid --set=root - echo 'Loading seL4 kernel' - multiboot /kernel-image-ia32-pc99 - echo 'Loading initial module ...' - module /sel4-image-ia32-pc99 -} -``` - -Of course, change the `--set=root ` line to your -DeviceID (set the DeviceID from other entries already in your grub.cfg), -and also change the `sel4-image-ia32-pc99` to match the name of your -binary image that your Make produces (look in your build logs or in -`images/` folder). - -Also may be a good idea to add `set default=` -to the grub.cfg, so grub is configured to boot seL4. - -## Using The VM to run seL4 - - -Now you have a VM ready, you'll want to copy your built kernel + -userland binary image over onto its HD, and then start the VM, and -choose the seL4 option in GRUB, and then monitor the serial output. You -will need to repeat this entire above process every time you build & run -seL4. Fortunately I have a script does all of the above in one go (may -need editing of paths here and there to fit where you put things). - -[Download seL4vmw.py](seL4vmw.py) - -### Do It Manually - - -First, use vmware-mount to mount the vmdk disk image. Then copy your -newly built kernel and user binaries over. Then, unmount using -vmware -d. - -Then start your VM (either from VMWare Player GUI or using the vmrun -script from VIX API), and choose seL4 boot option. Monitor serial -output. If you've set up the seL4 option as the grub default then you -just need to wait for the grub time out. - -If your kernel fails an assert during startup, make sure your kernel -repo is up to date. diff --git a/Hardware/X64.html b/Hardware/X64.html new file mode 100644 index 00000000000..3fe7dea0317 --- /dev/null +++ b/Hardware/X64.html @@ -0,0 +1,689 @@ + + + + + + + PC99 (64-bit) | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

PC99 (64-bit)

+ +

seL4 runs on 32-bit ia32 and 64-bit x64 machines, on QEMU and on hardware.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform PC99
Simulation platform yes
Architecture x64
seL4 virtualisation support + +
seL4 IOMMU (VT-d) support + +
Proofs + +
Proof configsX64
seL4 CMake platform namex86_64
Contributed by Data61
Maintained by seL4 Foundation
+ +

Simulation

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=x86_64 
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+# This platform is a simulation target. This script should work to run the
+# generated image if you also use -DSIMULATION=1 for init-build above:
+./simulate
+
+
+

If you plan to use the ./simulate script, please be sure to add the +-DSIMULATION=1 argument when running cmake.

+ +

Generated binaries can be found in the images/ directory.

+ +

Real Hardware

+ +

When running on real hardware console output will be over serial. You will need +to plug a serial cable into your machine to see any output.

+ +

The build system produces a multiboot compliant image for x86; a grub2 +stanza is here, but we usually boot via PXE for convenience.

+ +
menuentry "Load seL4 VM" --class os {
+    load_video
+    insmod gzio
+    insmod part_msdos
+    insmod ext2
+    set root='(hd0,msdos2)'
+    multiboot /boot/sel4kernel
+    module /boot/sel4rootserver
+}
+
+ +

Booting via PXEBOOT using +syslinux PXELINUX requires setting up a tftp and dhcp server on the network +that the machine you want to boot is connected to. The +syslinux +site has a download for pxelinux which we load over PXEBOOT +that then can load seL4. The configuration for pxelinux.cfg/default is +provided below.

+ +
label seL4
+        kernel mboot.32
+        append kernel-x86_64-pc99 --- apps-x86_64-pc99
+
+ +

Booting off USB with syslinux

+ +

Use syslinux to create a bootable USB stick as follows.

+ +

Assuming your USB flash drive is at /dev/sdb with a FAT partition at +/dev/sdb1:

+ +
install-mbr /dev/sdb
+syslinux --install /dev/sdb1
+mount /dev/sdb1 /mnt
+cp images/sel4test-driver-image-x86_64-pc99 /mnt/rootserver
+cp images/kernel-x86_64-pc99 /mnt/sel4kernel
+cat > /mnt/syslinux.cfg <<EOF
+SERIAL 0 115200
+DEFAULT seL4test
+LABEL seL4test
+    kernel mboot.c32
+    append sel4kernel --- rootserver
+EOF
+cp /usr/lib/syslinux/modules/bios/mboot.c32 /mnt
+cp /usr/lib/syslinux/modules/bios/libcom32.c32 /mnt
+umount /mnt
+
+ +

Use fdisk to make sure the first partition is bootable.

+ +

And you’re done. Output will come on the serial port

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/X64.md b/Hardware/X64.md deleted file mode 100644 index 35be04dc6da..00000000000 --- a/Hardware/X64.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -cmake_plat: x86_64 -simulation_target: true -simulation_only: false -arch: x64 -platform: PC99 -virtualization: true -iommu: true -verification: [X64] -Contrib: "Data61" -Maintained: "seL4 Foundation" -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# PC99 (64-bit) - -{% include pc99.md %} diff --git a/Hardware/ZC706.html b/Hardware/ZC706.html new file mode 100644 index 00000000000..04cbfad05d4 --- /dev/null +++ b/Hardware/ZC706.html @@ -0,0 +1,699 @@ + + + + + + + Zynq7000 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Zynq7000

+ +

This board is a Zynq-7000 ZC706 Evaluation Kit, Rev 1.2

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Zynq-7000 ZC706 Evaluation Kit
Simulation platform yes
Architecture ARMv7A
System-on-chip Zynq7000
CPU Cortex-A9
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + +
Proof configsARM
seL4 CMake platform namezynq7000
Contributed by Data61
Maintained by seL4 Foundation
+ +

Xilinx maintains online material, including designs and documentation.

+ +

Building

+ +

seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=zynq7000 -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+# This platform is a simulation target. This script should work to run the
+# generated image if you also use -DSIMULATION=1 for init-build above:
+./simulate
+
+
+

If you plan to use the ./simulate script, please be sure to add the +-DSIMULATION=1 argument when running cmake.

+ +

Generated binaries can be found in the images/ directory.

+ +

Development environment

+ +

Vivado SDK

+ +

Bitstream generation (ie FPGA code compiler) is not supported for ZC706 when using a free license. Other features may still work

+ +

The Vivado SDK provides many features:

+ +
    +
  • first stage boot loader and boot image generation
    • +
  • FPGA logic design
    • +
  • ARM software design
    • +
  • Support libraries
    • +
  • JTAG connectivity and debugging
    • +
+ +

Download it here (Requires a free Xilinx account).

+ +

After the download completes, extract and/or run the install program. You should run as root to install cable drivers, otherwise, they can be installed independently later.

+ +

When provided with install options, select “Vivado Design Edition” because the WebPack install does not support the ZC706 board. Ensure the Software Development Kit (SDK) is selected as an install candidate

+ +

When installation competes, the License Manager window will open. Choose “obtain license” from the tree on the left, select “Get Free Licenses” and click “Connect Now”. You will be navigated to the Xilinx login page in order to register for a license. Select the free webpack license and a license file will be mailed to you. While still in the License Manager, click “Load License” from the tree on the left and click the “Copy License” button. Select the license file that you received via email and click “Open”. Once you have configured your license, close the window and wait for the install to finish.

+ +

The last step is to install the cable drivers as follows:

+ +
uname -a | grep "x86_64" && LIN=lin64 || LIN=lin
+cd /opt/Xilinx/SDK/2014.4/data/xicom/cable_drivers/$LIN/install_script/install_drivers
+sudo ./install_drivers
+
+ +

JTAG

+ +

http://wiki.gentoo.org/wiki/Xilinx_USB_JTAG_Programmers

+ +

You will need

+ +
    +
  • xmd (shipped with vivado but can possibly be obtained as a package on its own)
    • +
  • digilent USB drivers
    • +
+ +
    +
  1. +

    create a xmd.ini script within the directory that you intend to run xmd from.

    + + 
      # Connect to the board
+  connect arm hw
+  # program the fpga with the provided bitstream
+  fpga -f system_wrapper.bit
+  # The processor needs to be initialised (Clocks, MIO, etc), but these depend on the bitstream! ps7_init.tcl was generated with the bitstream. Load and execute this script to configure the processor.
+  source ps7_init.tcl
+  ps7_init
+  ps7_post_config
+  # Download your elf file (Could also be done from GDB)
+  dow bootimg.elf
+  # To run the elf file directly from XMD, uncomment the following lines
+  # run
+  # exit
+
    +
    2. +
  2. Run XMD. XMD will not terminate; leave it open.
    3. +
  3. Next run GDB. Any arm-*-gdb should work.
    4. +
  4. Enter “target extended-remote localhost:1234” to connect to the GDB server that was started by XMD or the hw_server
    5. +
  5. “c” to start the program!
    6. +
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/ZC706.md b/Hardware/ZC706.md deleted file mode 100644 index 0402c107d09..00000000000 --- a/Hardware/ZC706.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -cmake_plat: zynq7000 -xcompiler_arg: -DAARCH32=1 -arm_hardware: true -defconfig: zynq7000_debug_xml_defconfig -simulation_target: true -simulation_only: false -platform: Zynq-7000 ZC706 Evaluation Kit -arch: ARMv7A -virtualization: false -iommu: false -soc: Zynq7000 -cpu: Cortex-A9 -verification: [ARM] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Zynq7000 - -This board is a Zynq-7000 ZC706 Evaluation Kit, Rev 1.2 - -{% include hw-info.html %} - -Xilinx maintains [online material](https://www.amd.com/en/products/adaptive-socs-and-fpgas/evaluation-boards/ek-z7-zc706-g.html), including designs and documentation. - -## Building - -### seL4test - -{% include sel4test.md %} - - -## Development environment - -### Vivado SDK - -Bitstream generation (ie FPGA code compiler) is not supported for ZC706 when using a free license. Other features may still work - -The Vivado SDK provides many features: - -- first stage boot loader and boot image generation -- FPGA logic design -- ARM software design -- Support libraries -- JTAG connectivity and debugging - -Download it [here](http://www.xilinx.com/support/download.html) (Requires a free Xilinx account). - -After the download completes, extract and/or run the install program. You should run as root to install cable drivers, otherwise, they can be installed independently later. - -When provided with install options, select "Vivado Design Edition" because the WebPack install does not support the ZC706 board. Ensure the Software Development Kit (SDK) is selected as an install candidate - -When installation competes, the License Manager window will open. Choose "obtain license" from the tree on the left, select "Get Free Licenses" and click "Connect Now". You will be navigated to the Xilinx login page in order to register for a license. Select the free webpack license and a license file will be mailed to you. While still in the License Manager, click "Load License" from the tree on the left and click the "Copy License" button. Select the license file that you received via email and click "Open". Once you have configured your license, close the window and wait for the install to finish. - -The last step is to install the cable drivers as follows: - -```bash -uname -a | grep "x86_64" && LIN=lin64 || LIN=lin -cd /opt/Xilinx/SDK/2014.4/data/xicom/cable_drivers/$LIN/install_script/install_drivers -sudo ./install_drivers -``` - -### JTAG - -[http://wiki.gentoo.org/wiki/Xilinx_USB_JTAG_Programmers](http://wiki.gentoo.org/wiki/Xilinx_USB_JTAG_Programmers) - -You will need - -- xmd (shipped with vivado but can possibly be obtained as a package on its own) -- digilent USB drivers - -1. create a xmd.ini script within the directory that you intend to run xmd from. - - ```bash - # Connect to the board - connect arm hw - # program the fpga with the provided bitstream - fpga -f system_wrapper.bit - # The processor needs to be initialised (Clocks, MIO, etc), but these depend on the bitstream! ps7_init.tcl was generated with the bitstream. Load and execute this script to configure the processor. - source ps7_init.tcl - ps7_init - ps7_post_config - # Download your elf file (Could also be done from GDB) - dow bootimg.elf - # To run the elf file directly from XMD, uncomment the following lines - # run - # exit - ``` - -2. Run XMD. XMD will not terminate; leave it open. -3. Next run GDB. Any arm-*-gdb should work. -4. Enter "target extended-remote localhost:1234" to connect to the GDB server that was started by XMD or the hw_server -5. "c" to start the program! diff --git a/Hardware/ZCU102.html b/Hardware/ZCU102.html new file mode 100644 index 00000000000..f17ad3bf098 --- /dev/null +++ b/Hardware/ZCU102.html @@ -0,0 +1,785 @@ + + + + + + + Zynq ZCU102 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Zynq ZCU102

+ +

The board is Zynq UltraScale MPSoC ZCU102 Eval Kit, Rev 1.1 +The port also works on the ZCU106 evaluation kit.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Zynq ZCU102 Evaluation Kit
Architecture ARMv8A
System-on-chip Zynq UltraScale+ MPSoC
CPU Cortex-A53
seL4 virtualisation support + +
seL4 SMMU support + +
Proofs + +
Proof configsARM, AARCH64
seL4 CMake platform namezcu102
Contributed by DornerWorks
Maintained by DornerWorks
+ +

Xilinx maintains online material, including designs and documentation.

+ +

Building

+ +

seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=zcu102 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

The ZCU102 also supports AArch32 mode. If you choose to build the AArch32 kernel, +please be sure to pass -DAARCH32=1 instead of -DAARCH64=1.

+ +

ARM Trusted Firmware (ATF)

+ +
git clone https://github.com/Xilinx/arm-trusted-firmware.git
+cd arm-trusted-firmware
+make PLAT=zynqmp RESET_TO_BL31=1 CROSS_COMPILE=aarch64-linux-gnu-
+
+ +

Generated ELF file can be found at build/zynqmp/release/bl31/bl31.elf.

+ +

U-Boot

+ +
git clone https://github.com/Xilinx/u-boot-xlnx.git
+cd u-boot-xlnx
+make xilinx_zynqmp_virt_defconfig
+# Use "make menuconfig" to open the configuration interface, change the value
+in "Default Device Tree" to "zynqmp-zcu102-rev1.0"
+make CROSS_COMPILE=aarch64-linux-gnu-
+
+ +

If you use gcc > 10, apply the following patch before compiling:

+ +
diff --git a/scripts/dtc/dtc-lexer.l b/scripts/dtc/dtc-lexer.l
+index fd825ebba6..24af549977 100644
+--- a/scripts/dtc/dtc-lexer.l
++++ b/scripts/dtc/dtc-lexer.l
+@@ -38,7 +38,6 @@ LINECOMMENT	"//".*\n
+ #include "srcpos.h"
+ #include "dtc-parser.tab.h"
+
+-YYLTYPE yylloc;
+ extern bool treesource_error;
+
+ /* CAUTION: this will stop working if we ever use yyless() or yyunput() */
+
+ +

If you choose to use the AArch32 kernel, apply the following patch:

+ +
diff --git a/board/xilinx/zynqmp/zynqmp.c b/board/xilinx/zynqmp/zynqmp.c
+index 52b08c4dbe..c9ebd33d15 100644
+--- a/board/xilinx/zynqmp/zynqmp.c
++++ b/board/xilinx/zynqmp/zynqmp.c
+@@ -358,7 +358,7 @@ unsigned long do_go_exec(ulong (*entry)(int, char * const []), int argc,
+     smp_kick_all_cpus();
+     dcache_disable();
+     armv8_switch_to_el1(0x0, 0, 0, 0, (unsigned long)entry,
+-                        ES_TO_AARCH64);
++                        ES_TO_AARCH32);
+   } else {
+     printf("FAIL: current EL is not above EL1\n");
+     ret = EINVAL;
+
+ +

Generated ELF file is u-boot.elf.

+ +

Upstream U-Boot also works; instructions are here

+ +

Development Environment

+ +

Install Vivado SDK or Vitis Software Platform from Xilinx here +(Requires a free Xilinx account). The following instructions are based on Vivado SDK v2019.1

+ +

First stage boot load (FSBL)

+ +

Open Vivado SDK, create a new application project.

+ +
    +
  • OS platform: standalone
    • +
  • Hardware Platform: ZCU102_hw_platform
    • +
  • Processor: psu_cortexa53_0
    • +
  • Language: C
    • +
  • Compiler: 64-bit
    • +
  • Hypervisor Guest: No
    • +
  • Template: Zynq MP FSBL
    • +
+ +

Generated ELF file is in Debug directory

+ +

PMU firmware

+ +

Open Vivado SDK, create a new application project.

+ +
    +
  • OS platform: standalone
    • +
  • Hardware Platform: ZCU102_hw_platform
    • +
  • Processor: psu_pmu_0
    • +
  • Language: C
    • +
+ +

Generated ELF file is in Debug directory

+ +

Booting via JTAG

+ +

Set DIP switch (SW6) to JTAG boot (on, on, on, on).

+ +

Start the Xilinx debug tool (shipped with Vivado SDK):

+ +
xsct -nodisp
+
+ +

Upload files to the board using XSCT prompt:

+ +
connect
+targets -set -filter {name =~ "PSU"}
+mwr 0xffca0038 0x1ff
+targets -set -filter {name =~ "MicroBlaze*"}
+dow pmufw.elf
+con
+target -set -filter {name =~ "Cortex-A53 #0*"}
+rst -processor
+dow fsbl.elf
+con
+dow bl31.elf
+con
+dow u-boot.elf
+con
+# Load the seL4 image in ELF format, the file can be found in the sel4test build directory
+dow elfloader/elfloader
+con
+
+ +

Booting via SD Card

+ +

Get an SD card can format it with FAT32.

+ +

Set DIP switch (SW6) to SD boot (off, off, off, on)

+ +

Create a output.bif file with the following content:

+ +
the_ROM_image:
+{
+    [bootloader, destination_cpu = a53-0] fsbl.elf
+    [pmufw_image] pmufw.elf
+    [destination_cpu = a53-0, exception_level = el-3] bl31.elf
+    [destination_cpu = a53-0, exception_level = el-2] u-boot.elf
+}
+
+ +

Generate the bootable binary:

+ +
bootgen -arch zynqmp -image output.bif -w on -o BOOT.bin
+
+ +

Copy BOOT.bin to the SD card

+ +

Insert the SD card into ZCU102 then power on the board, and drop into the U-Boot +prompt. When you’re at the prompt, type the following to load the ELF file generated +from building seL4test:

+ +
fatload mmc 0 0x8000000 sel4test-driver-image-arm-zynqmp
+bootelf 0x8000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/ZCU102.md b/Hardware/ZCU102.md deleted file mode 100644 index 1e774ce4b21..00000000000 --- a/Hardware/ZCU102.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -cmake_plat: zcu102 -xcompiler_arg: -DAARCH64=1 -arm_hardware: true -platform: Zynq ZCU102 Evaluation Kit -arch: ARMv8A -virtualization: true -iommu: true -soc: Zynq UltraScale+ MPSoC -cpu: Cortex-A53 -verification: [ARM, AARCH64] -Contrib: 'DornerWorks' -Maintained: 'DornerWorks' -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Zynq ZCU102 - -The board is Zynq UltraScale MPSoC ZCU102 Eval Kit, Rev 1.1 -The port also works on the [ZCU106](ZCU106.html) evaluation kit. - -{% include hw-info.html %} - -Xilinx maintains [online material](https://www.amd.com/en/products/adaptive-socs-and-fpgas/evaluation-boards/ek-u1-zcu102-g.html), including designs and documentation. - -## Building - -### seL4test - -{% include sel4test.md %} - -The ZCU102 also supports AArch32 mode. If you choose to build the AArch32 kernel, -please be sure to pass `-DAARCH32=1` instead of `-DAARCH64=1`. - -## ARM Trusted Firmware (ATF) - -```bash -git clone https://github.com/Xilinx/arm-trusted-firmware.git -cd arm-trusted-firmware -make PLAT=zynqmp RESET_TO_BL31=1 CROSS_COMPILE=aarch64-linux-gnu- -``` - -Generated ELF file can be found at `build/zynqmp/release/bl31/bl31.elf`. - -## U-Boot - -```bash -git clone https://github.com/Xilinx/u-boot-xlnx.git -cd u-boot-xlnx -make xilinx_zynqmp_virt_defconfig -# Use "make menuconfig" to open the configuration interface, change the value -in "Default Device Tree" to "zynqmp-zcu102-rev1.0" -make CROSS_COMPILE=aarch64-linux-gnu- -``` - -If you use gcc > 10, apply the following patch before compiling: - -```patch -diff --git a/scripts/dtc/dtc-lexer.l b/scripts/dtc/dtc-lexer.l -index fd825ebba6..24af549977 100644 ---- a/scripts/dtc/dtc-lexer.l -+++ b/scripts/dtc/dtc-lexer.l -@@ -38,7 +38,6 @@ LINECOMMENT "//".*\n - #include "srcpos.h" - #include "dtc-parser.tab.h" - --YYLTYPE yylloc; - extern bool treesource_error; - - /* CAUTION: this will stop working if we ever use yyless() or yyunput() */ -``` - -If you choose to use the AArch32 kernel, apply the following patch: - -```patch -diff --git a/board/xilinx/zynqmp/zynqmp.c b/board/xilinx/zynqmp/zynqmp.c -index 52b08c4dbe..c9ebd33d15 100644 ---- a/board/xilinx/zynqmp/zynqmp.c -+++ b/board/xilinx/zynqmp/zynqmp.c -@@ -358,7 +358,7 @@ unsigned long do_go_exec(ulong (*entry)(int, char * const []), int argc, - smp_kick_all_cpus(); - dcache_disable(); - armv8_switch_to_el1(0x0, 0, 0, 0, (unsigned long)entry, -- ES_TO_AARCH64); -+ ES_TO_AARCH32); - } else { - printf("FAIL: current EL is not above EL1\n"); - ret = EINVAL; -``` - -Generated ELF file is `u-boot.elf`. - -Upstream U-Boot also works; instructions are [here](https://u-boot.readthedocs.io/en/stable/board/xilinx/zynqmp.html) - -## Development Environment - -Install Vivado SDK or Vitis Software Platform from Xilinx [here](http://www.xilinx.com/support/download.html) -(Requires a free Xilinx account). The following instructions are based on Vivado SDK v2019.1 - -### First stage boot load (FSBL) - -Open Vivado SDK, create a new application project. - -- OS platform: standalone -- Hardware Platform: ZCU102_hw_platform -- Processor: psu_cortexa53_0 -- Language: C -- Compiler: 64-bit -- Hypervisor Guest: No -- Template: Zynq MP FSBL - -Generated ELF file is in `Debug` directory - -### PMU firmware - -Open Vivado SDK, create a new application project. - -- OS platform: standalone -- Hardware Platform: ZCU102_hw_platform -- Processor: psu_pmu_0 -- Language: C - -Generated ELF file is in `Debug` directory - -## Booting via JTAG - -Set DIP switch (SW6) to JTAG boot (on, on, on, on). - -Start the Xilinx debug tool (shipped with Vivado SDK): - -```bash -xsct -nodisp -``` - -Upload files to the board using XSCT prompt: - -```tcl -connect -targets -set -filter {name =~ "PSU"} -mwr 0xffca0038 0x1ff -targets -set -filter {name =~ "MicroBlaze*"} -dow pmufw.elf -con -target -set -filter {name =~ "Cortex-A53 #0*"} -rst -processor -dow fsbl.elf -con -dow bl31.elf -con -dow u-boot.elf -con -# Load the seL4 image in ELF format, the file can be found in the sel4test build directory -dow elfloader/elfloader -con -``` - -## Booting via SD Card - -Get an SD card can format it with FAT32. - -Set DIP switch (SW6) to SD boot (off, off, off, on) - -Create a output.bif file with the following content: - -```bif -the_ROM_image: -{ - [bootloader, destination_cpu = a53-0] fsbl.elf - [pmufw_image] pmufw.elf - [destination_cpu = a53-0, exception_level = el-3] bl31.elf - [destination_cpu = a53-0, exception_level = el-2] u-boot.elf -} -``` - -Generate the bootable binary: - -```bash -bootgen -arch zynqmp -image output.bif -w on -o BOOT.bin -``` - -Copy BOOT.bin to the SD card - -Insert the SD card into ZCU102 then power on the board, and drop into the U-Boot -prompt. When you're at the prompt, type the following to load the ELF file generated -from building seL4test: - -```bash -fatload mmc 0 0x8000000 sel4test-driver-image-arm-zynqmp -bootelf 0x8000000 -``` diff --git a/Hardware/ZCU106.html b/Hardware/ZCU106.html new file mode 100644 index 00000000000..67fb15ce37d --- /dev/null +++ b/Hardware/ZCU106.html @@ -0,0 +1,785 @@ + + + + + + + Zynq ZCU1026 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Zynq ZCU1026

+ +

The board is Zynq UltraScale MPSoC ZCU106 Evaluation Kit. The seL4 implementation +is the same as for the ZCU102

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Zynq ZCU106 Evaluation Kit
Architecture ARMv8A
System-on-chip Zynq UltraScale+ MPSoC
CPU Cortex-A53
seL4 virtualisation support + +
seL4 SMMU support + +
Proofs + +
Proof configsARM, AARCH64
seL4 CMake platform namezcu106
Contributed by DornerWorks
Maintained by DornerWorks
+ +

Xilinx maintains online material, including designs and documentation.

+ +

Building

+ +

seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=zcu106 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

The ZCU102 also supports AArch32 mode. If you choose to build the AArch32 kernel, +please be sure to pass -DAARCH32=1 instead of -DAARCH64=1.

+ +

ARM Trusted Firmware (ATF)

+ +
git clone https://github.com/Xilinx/arm-trusted-firmware.git
+cd arm-trusted-firmware
+make PLAT=zynqmp RESET_TO_BL31=1 CROSS_COMPILE=aarch64-linux-gnu-
+
+ +

Generated ELF file can be found at build/zynqmp/release/bl31/bl31.elf.

+ +

U-Boot

+ +
git clone https://github.com/Xilinx/u-boot-xlnx.git
+cd u-boot-xlnx
+make xilinx_zynqmp_virt_defconfig
+# Use "make menuconfig" to open the configuration interface, change the value
+in "Default Device Tree" to "zynqmp-zcu106-rev1.0"
+make CROSS_COMPILE=aarch64-linux-gnu-
+
+ +

If you use gcc > 10, apply the following patch before compiling:

+ +
diff --git a/scripts/dtc/dtc-lexer.l b/scripts/dtc/dtc-lexer.l
+index fd825ebba6..24af549977 100644
+--- a/scripts/dtc/dtc-lexer.l
++++ b/scripts/dtc/dtc-lexer.l
+@@ -38,7 +38,6 @@ LINECOMMENT	"//".*\n
+ #include "srcpos.h"
+ #include "dtc-parser.tab.h"
+
+-YYLTYPE yylloc;
+ extern bool treesource_error;
+
+ /* CAUTION: this will stop working if we ever use yyless() or yyunput() */
+
+ +

If you choose to use the AArch32 kernel, apply the following patch:

+ +
diff --git a/board/xilinx/zynqmp/zynqmp.c b/board/xilinx/zynqmp/zynqmp.c
+index 52b08c4dbe..c9ebd33d15 100644
+--- a/board/xilinx/zynqmp/zynqmp.c
++++ b/board/xilinx/zynqmp/zynqmp.c
+@@ -358,7 +358,7 @@ unsigned long do_go_exec(ulong (*entry)(int, char * const []), int argc,
+     smp_kick_all_cpus();
+     dcache_disable();
+     armv8_switch_to_el1(0x0, 0, 0, 0, (unsigned long)entry,
+-                        ES_TO_AARCH64);
++                        ES_TO_AARCH32);
+   } else {
+     printf("FAIL: current EL is not above EL1\n");
+     ret = EINVAL;
+
+ +

Generated ELF file is u-boot.elf.

+ +

Upstream U-Boot also works; instructions are here

+ +

Development Environment

+ +

Install Vivado SDK or Vitis Software Platform from Xilinx here +(Requires a free Xilinx account). The following instructions are based on Vivado SDK v2019.1

+ +

First stage boot load (FSBL)

+ +

Open Vivado SDK, create a new application project.

+ +
    +
  • OS platform: standalone
    • +
  • Hardware Platform: ZCU102_hw_platform
    • +
  • Processor: psu_cortexa53_0
    • +
  • Language: C
    • +
  • Compiler: 64-bit
    • +
  • Hypervisor Guest: No
    • +
  • Template: Zynq MP FSBL
    • +
+ +

Generated ELF file is in Debug directory

+ +

PMU firmware

+ +

Open Vivado SDK, create a new application project.

+ +
    +
  • OS platform: standalone
    • +
  • Hardware Platform: ZCU102_hw_platform
    • +
  • Processor: psu_pmu_0
    • +
  • Language: C
    • +
+ +

Generated ELF file is in Debug directory

+ +

Booting via JTAG

+ +

Set DIP switch (SW6) to JTAG boot (on, on, on, on).

+ +

Start the Xilinx debug tool (shipped with Vivado SDK):

+ +
xsct -nodisp
+
+ +

Upload files to the board using XSCT prompt:

+ +
connect
+targets -set -filter {name =~ "PSU"}
+mwr 0xffca0038 0x1ff
+targets -set -filter {name =~ "MicroBlaze*"}
+dow pmufw.elf
+con
+target -set -filter {name =~ "Cortex-A53 #0*"}
+rst -processor
+dow fsbl.elf
+con
+dow bl31.elf
+con
+dow u-boot.elf
+con
+# Load the seL4 image in ELF format, the file can be found in the sel4test build directory
+dow elfloader/elfloader
+con
+
+ +

Booting via SD Card

+ +

Get an SD card can format it with FAT32.

+ +

Set DIP switch (SW6) to SD boot (off, off, off, on)

+ +

Create a output.bif file with the following content:

+ +
the_ROM_image:
+{
+    [bootloader, destination_cpu = a53-0] fsbl.elf
+    [pmufw_image] pmufw.elf
+    [destination_cpu = a53-0, exception_level = el-3] bl31.elf
+    [destination_cpu = a53-0, exception_level = el-2] u-boot.elf
+}
+
+ +

Generate the bootable binary:

+ +
bootgen -arch zynqmp -image output.bif -w on -o BOOT.bin
+
+ +

Copy BOOT.bin to the SD card

+ +

Insert the SD card into ZCU102 then power on the board, and drop into the U-Boot +prompt. When you’re at the prompt, type the following to load the ELF file generated +from building seL4test:

+ +
fatload mmc 0 0x8000000 sel4test-driver-image-arm-zynqmp
+bootelf 0x8000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/ZCU106.md b/Hardware/ZCU106.md deleted file mode 100644 index 4e4d1e6a849..00000000000 --- a/Hardware/ZCU106.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -cmake_plat: zcu106 -xcompiler_arg: -DAARCH64=1 -arm_hardware: true -platform: Zynq ZCU106 Evaluation Kit -arch: ARMv8A -virtualization: true -iommu: true -soc: Zynq UltraScale+ MPSoC -cpu: Cortex-A53 -verification: [ARM, AARCH64] -Contrib: 'DornerWorks' -Maintained: 'DornerWorks' -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Zynq ZCU1026 - -The board is Zynq UltraScale MPSoC ZCU106 Evaluation Kit. The seL4 implementation -is the same as for the [ZCU102](ZCU102.html) - -{% include hw-info.html %} - -Xilinx maintains [online material](https://www.amd.com/en/products/adaptive-socs-and-fpgas/evaluation-boards/zcu106.html), including designs and documentation. - -## Building - -### seL4test - -{% include sel4test.md %} - -The ZCU102 also supports AArch32 mode. If you choose to build the AArch32 kernel, -please be sure to pass `-DAARCH32=1` instead of `-DAARCH64=1`. - -## ARM Trusted Firmware (ATF) - -```bash -git clone https://github.com/Xilinx/arm-trusted-firmware.git -cd arm-trusted-firmware -make PLAT=zynqmp RESET_TO_BL31=1 CROSS_COMPILE=aarch64-linux-gnu- -``` - -Generated ELF file can be found at `build/zynqmp/release/bl31/bl31.elf`. - -## U-Boot - -```bash -git clone https://github.com/Xilinx/u-boot-xlnx.git -cd u-boot-xlnx -make xilinx_zynqmp_virt_defconfig -# Use "make menuconfig" to open the configuration interface, change the value -in "Default Device Tree" to "zynqmp-zcu106-rev1.0" -make CROSS_COMPILE=aarch64-linux-gnu- -``` - -If you use gcc > 10, apply the following patch before compiling: - -```patch -diff --git a/scripts/dtc/dtc-lexer.l b/scripts/dtc/dtc-lexer.l -index fd825ebba6..24af549977 100644 ---- a/scripts/dtc/dtc-lexer.l -+++ b/scripts/dtc/dtc-lexer.l -@@ -38,7 +38,6 @@ LINECOMMENT "//".*\n - #include "srcpos.h" - #include "dtc-parser.tab.h" - --YYLTYPE yylloc; - extern bool treesource_error; - - /* CAUTION: this will stop working if we ever use yyless() or yyunput() */ -``` - -If you choose to use the AArch32 kernel, apply the following patch: - -```patch -diff --git a/board/xilinx/zynqmp/zynqmp.c b/board/xilinx/zynqmp/zynqmp.c -index 52b08c4dbe..c9ebd33d15 100644 ---- a/board/xilinx/zynqmp/zynqmp.c -+++ b/board/xilinx/zynqmp/zynqmp.c -@@ -358,7 +358,7 @@ unsigned long do_go_exec(ulong (*entry)(int, char * const []), int argc, - smp_kick_all_cpus(); - dcache_disable(); - armv8_switch_to_el1(0x0, 0, 0, 0, (unsigned long)entry, -- ES_TO_AARCH64); -+ ES_TO_AARCH32); - } else { - printf("FAIL: current EL is not above EL1\n"); - ret = EINVAL; -``` - -Generated ELF file is `u-boot.elf`. - -Upstream U-Boot also works; instructions are [here](https://u-boot.readthedocs.io/en/stable/board/xilinx/zynqmp.html) - -## Development Environment - -Install Vivado SDK or Vitis Software Platform from Xilinx [here](http://www.xilinx.com/support/download.html) -(Requires a free Xilinx account). The following instructions are based on Vivado SDK v2019.1 - -### First stage boot load (FSBL) - -Open Vivado SDK, create a new application project. - -- OS platform: standalone -- Hardware Platform: ZCU102_hw_platform -- Processor: psu_cortexa53_0 -- Language: C -- Compiler: 64-bit -- Hypervisor Guest: No -- Template: Zynq MP FSBL - -Generated ELF file is in `Debug` directory - -### PMU firmware - -Open Vivado SDK, create a new application project. - -- OS platform: standalone -- Hardware Platform: ZCU102_hw_platform -- Processor: psu_pmu_0 -- Language: C - -Generated ELF file is in `Debug` directory - -## Booting via JTAG - -Set DIP switch (SW6) to JTAG boot (on, on, on, on). - -Start the Xilinx debug tool (shipped with Vivado SDK): - -```bash -xsct -nodisp -``` - -Upload files to the board using XSCT prompt: - -```tcl -connect -targets -set -filter {name =~ "PSU"} -mwr 0xffca0038 0x1ff -targets -set -filter {name =~ "MicroBlaze*"} -dow pmufw.elf -con -target -set -filter {name =~ "Cortex-A53 #0*"} -rst -processor -dow fsbl.elf -con -dow bl31.elf -con -dow u-boot.elf -con -# Load the seL4 image in ELF format, the file can be found in the sel4test build directory -dow elfloader/elfloader -con -``` - -## Booting via SD Card - -Get an SD card can format it with FAT32. - -Set DIP switch (SW6) to SD boot (off, off, off, on) - -Create a output.bif file with the following content: - -```bif -the_ROM_image: -{ - [bootloader, destination_cpu = a53-0] fsbl.elf - [pmufw_image] pmufw.elf - [destination_cpu = a53-0, exception_level = el-3] bl31.elf - [destination_cpu = a53-0, exception_level = el-2] u-boot.elf -} -``` - -Generate the bootable binary: - -```bash -bootgen -arch zynqmp -image output.bif -w on -o BOOT.bin -``` - -Copy BOOT.bin to the SD card - -Insert the SD card into ZCU102 then power on the board, and drop into the U-Boot -prompt. When you're at the prompt, type the following to load the ELF file generated -from building seL4test: - -```bash -fatload mmc 0 0x8000000 sel4test-driver-image-arm-zynqmp -bootelf 0x8000000 -``` diff --git a/Hardware/ariane.html b/Hardware/ariane.html new file mode 100644 index 00000000000..519f93dde63 --- /dev/null +++ b/Hardware/ariane.html @@ -0,0 +1,656 @@ + + + + + + + Ariane | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Ariane

+ +

Ariane is a 6-stage RISC-V CPU. For details, refer to +https://github.com/pulp-platform/ariane

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Ariane
Architecture RV64IMAC
CPU Ariane (CVA6)
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform nameariane
Contributed by Data61
Maintained by Hensoldt Cyber
+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=ariane -DRISCV64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Running seL4test

+

Ariane only provides support for the Genesys 2 +board

+ +
    +
  1. +

    Compile the bitstream from source or download the pre-build bitstream from +here.

    +
    2. +
  2. Prepare the SD card + 
    sudo sgdisk --clear --new=1:2048:67583 --new=2 --typecode=1:3000 --typecode=2:8300 /dev/sdX
+sudo dd if=images/sel4test-driver-image-riscv-ariane of=/dev/sdX1
+
    +

    Note that the “sgdisk” command above also creates a second partition for +Linux rootfs, you could download a pre-build Linux kernel from +here to verify that +the FPGA is working correctly.

    +
    3. +
  3. Booting from the SD card and observing the output from the UART port.
    4. +
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/ariane.md b/Hardware/ariane.md deleted file mode 100644 index 664cdfc1439..00000000000 --- a/Hardware/ariane.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: ariane -xcompiler_arg: -DRISCV64=1 -platform: Ariane -arch: RV64IMAC -virtualization: false -iommu: false -simulation_target: false -verification: [] -Contrib: "Data61" -Maintained: "Hensoldt Cyber" -cpu: Ariane (CVA6) -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Ariane - -Ariane is a 6-stage RISC-V CPU. For details, refer to -[https://github.com/pulp-platform/ariane](https://github.com/pulp-platform/ariane) - -{% include hw-info.html %} - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Building seL4test - -{% include sel4test.md %} - -## Running seL4test -Ariane only provides support for the [Genesys 2 -board](https://reference.digilentinc.com/reference/programmable-logic/genesys-2/reference-manual) - -1. Compile the bitstream from source or download the pre-build bitstream from - [here](https://github.com/pulp-platform/ariane/releases). - -2. Prepare the SD card - ```sh - sudo sgdisk --clear --new=1:2048:67583 --new=2 --typecode=1:3000 --typecode=2:8300 /dev/sdX - sudo dd if=images/sel4test-driver-image-riscv-ariane of=/dev/sdX1 - ``` - Note that the "sgdisk" command above also creates a second partition for - Linux rootfs, you could download a pre-build Linux kernel from - [here](https://github.com/pulp-platform/ariane-sdk/releases) to verify that - the FPGA is working correctly. - -3. Booting from the SD card and observing the output from the UART port. diff --git a/Hardware/arndale.html b/Hardware/arndale.html new file mode 100644 index 00000000000..b1352601c25 --- /dev/null +++ b/Hardware/arndale.html @@ -0,0 +1,752 @@ + + + + + + + Arndale | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Arndale

+ +
+
+ + Important +
+
+ +

This board is no longer supported by seL4.

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Arndale
Architecture ARMv7A
System-on-chip Exynos5
CPU Cortex-A15
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsARM_HYP
seL4 CMake platform nameexynos5250
Contributed by Data61
+ +

Client setup

+ +

Hardware requirements:

+ +
    +
  1. 5V power supply, center +ve
    2. +
+ +

SD card setup

+ +

The offsets depend on which versions of bl1, bl2 and U-Boot you get.

+ +

For BL1 from the Android tree:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyPosition (block)
BL11
BL2 (uboot-module)31 (8k)
u-boot63
!TrustZone719
+ +

Note — U-Boot understands DOS filesystems (and ext2) so uImage, uInitrd +and the DTB could be normal files in a partition, rather than at a fixed +offset on the SD card.

+ +

These offsets are designed for a U-Boot environment like this:

+ +
bootargs=root=/dev/mmcblk1p1 rw rootwait console=ttySAC2,115200n8 init --no-log
+bootcmd=mmc read 40007000 451 2000;mmc read 42000000 2451 20;bootm 40007000 - 42000000
+
+ +

If you have a separate boot partition on your card you could instead +use: (untested as yet)

+ +
kernel=0x40007000
+dtb=42000000
+bootcmd=mmc init; fatload mmc 0:1 ${kernel} uImage; fatload mmc 0:1 ${dtb} dtb; bootm ${kernel} - ${dtb}
+
+ +

U-Boot

+ +

There are at least three versions available, the one in the Android tree (which +should have Fastboot) and the one from Linaro (which understands the USB and +network drivers).

+ +

There’s also http://www.spinics.net/lists/kvm-arm/msg02817.html which +is supposed to enable the virtualisation features. I’m not sure at +present whether the difference is merely configuration or if there are +source differences. U-Boot.

+ +

Inside the Android environment do:

+ +
make ARCH=arm CROSS_COMPILE=arm-eabi-arndale
+sudo dd iflag=dsync oflag=dsync if=u-boot.bin of=/dev/sdb seek=63
+
+ +

seL4 Image file preparation

+ +

In most cases it is okay to simply load the elf file into memory and run +bootelf. However, Fastboot may require that the ELF file be packed into a U-Boot +application image file. Follow the below instructions to create this image.

+ +
sudo apt-get install uboot-mkimage
+INPUT_FILE=images/sel4test-image-arm-exynos4
+OUTPUT_FILE=sel4-uImage
+mkimage -a 0x48000000 -e 0x48000000 -C none -A arm -T kernel -O qnx -d $INPUT_FILE $OUTPUT_FILE
+
+ +

The reason we choose QNX is because we exploit the fact that, like seL4, QNX +expects to be ELF-loaded. The alternative is to convert our ELF file into a +binary file using objcopy.

+ +

Booting

+ +

Building an image

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=exynos5250 -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

tftpboot

+ +

At the U-Boot prompt, type print to see the list of environment variables and +their values. Use the following commands to set any variables that are missing +from the list.

+ +
setenv bootfile filename
+setenv ethaddr 00:40:5c:26:0a:FF
+setenv usbethaddr 00:40:5c:26:0a:FF
+setenv pxefile_addr_r 0x50000000
+
+ +

Now run:

+ +
usb start; dhcp; bootelf; bootm;
+
+ +

References

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/arndale.md b/Hardware/arndale.md deleted file mode 100644 index d0f0a7b10da..00000000000 --- a/Hardware/arndale.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -archive: true -arm_hardware: true -cmake_plat: exynos5250 -xcompiler_arg: -DAARCH32=1 -platform: Arndale -arch: ARMv7A -virtualization: true -iommu: false -soc: Exynos5 -cpu: Cortex-A15 -verification: [ARM_HYP] -Contrib: Data61 -Maintained: false -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Arndale - -{% include hw-info.html %} - -## Client setup - -### Hardware requirements: - -1. 5V power supply, center +ve - -## SD card setup - -The offsets depend on which versions of bl1, bl2 and U-Boot you get. - -For BL1 from the Android tree: - -|Key|Position (block) | -|-|-| -|BL1 |1 | -|BL2 (uboot-module)|31 (8k) | -|u-boot |63 | -|!TrustZone |719 | - -Note — U-Boot understands DOS filesystems (and ext2) so uImage, uInitrd -and the DTB could be normal files in a partition, rather than at a fixed -offset on the SD card. - -These offsets are designed for a U-Boot environment like this: - -```none -bootargs=root=/dev/mmcblk1p1 rw rootwait console=ttySAC2,115200n8 init --no-log -bootcmd=mmc read 40007000 451 2000;mmc read 42000000 2451 20;bootm 40007000 - 42000000 -``` - -If you have a separate boot partition on your card you could instead -use: (untested as yet) - -```none -kernel=0x40007000 -dtb=42000000 -bootcmd=mmc init; fatload mmc 0:1 ${kernel} uImage; fatload mmc 0:1 ${dtb} dtb; bootm ${kernel} - ${dtb} -``` - -### U-Boot - -There are at least three versions available, the one in the Android tree (which -should have Fastboot) and the one from Linaro (which understands the USB and -network drivers). - -There's also which -is supposed to enable the virtualisation features. I'm not sure at -present whether the difference is merely configuration or if there are -source differences. U-Boot. - -Inside the Android environment do: - -```bash -make ARCH=arm CROSS_COMPILE=arm-eabi-arndale -sudo dd iflag=dsync oflag=dsync if=u-boot.bin of=/dev/sdb seek=63 -``` - -## seL4 Image file preparation - -In most cases it is okay to simply load the elf file into memory and run -`bootelf`. However, Fastboot may require that the ELF file be packed into a U-Boot -application image file. Follow the below instructions to create this image. - -```bash -sudo apt-get install uboot-mkimage -INPUT_FILE=images/sel4test-image-arm-exynos4 -OUTPUT_FILE=sel4-uImage -mkimage -a 0x48000000 -e 0x48000000 -C none -A arm -T kernel -O qnx -d $INPUT_FILE $OUTPUT_FILE -``` - -The reason we choose QNX is because we exploit the fact that, like seL4, QNX -expects to be ELF-loaded. The alternative is to convert our ELF file into a -binary file using objcopy. - -## Booting - -### Building an image - -{% include sel4test.md %} - -### tftpboot - -At the U-Boot prompt, type print to see the list of environment variables and -their values. Use the following commands to set any variables that are missing -from the list. - -```none -setenv bootfile filename -setenv ethaddr 00:40:5c:26:0a:FF -setenv usbethaddr 00:40:5c:26:0a:FF -setenv pxefile_addr_r 0x50000000 -``` - -Now run: - -```none -usb start; dhcp; bootelf; bootm; -``` - -## References - -- diff --git a/Hardware/bananapi-f3.html b/Hardware/bananapi-f3.html new file mode 100644 index 00000000000..ddd525313a9 --- /dev/null +++ b/Hardware/bananapi-f3.html @@ -0,0 +1,700 @@ + + + + + + + Banana Pi BPI-F3 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Banana Pi BPI-F3

+ +

The Banana Pi BPI-F3 is an industrial-grade RISC-V single-board computer +from Banana Pi, based on SpacemiT K1 SoC. It has an octa-core RISC-V (8 × X60) +CPU, with integrated 2.0 TOPs AI computing power.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Banana Pi BPI-F3
Architecture RV64GCVB
System-on-chip SpacemiT K1
CPU X60
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform namebananapi-f3
Contributed by Community
Maintained by 10xEngineers
+ +

Details and links to manuals can be found on the Banana Pi product +page.

+ +

The SoC technical reference manual can be found on +SpacemiT website.

+ +

The Banana Pi BPI-F3 arrives with the following boot process:

+ +
    +
  1. Firmware starts
    2. +
  2. OpenSBI starts
    3. +
  3. U-Boot proper starts
    4. +
+ +

From U-Boot proper you can then load and start an seL4 image, see below for details.

+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=bananapi-f3 -DRISCV64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Booting

+ +

There are multiple ways to boot from U-Boot, documented below is booting via TFTP and from +a microSD card.

+ +

Obtaining the DTB

+ +

Since we are using a uImage for the Banana Pi BPI-F3, U-Boot requires a Device Tree Blob (DTB) alongside +the binary image to boot.

+ +

The Device Tree Source (DTS) can be compiled from the seL4 tree with the Device Tree Compiler (dtc):

+
dtc -I dts -O dtb sel4/tools/dts/bananapi-f3.dts > bananapi-f3.dtb
+
+ +

Booting via microSD card

+ +

These instructions expect the microSD card to be paritioned with FAT.

+ +

The microSD card slot registers as device 0 in U-Boot so to see if the device +is recognised run:

+ +
mmc dev 0
+# Check that the card info is expected
+mmc info
+# List partitions
+mmc part
+
+ +

To load and run the image:

+ +
fatload mmc 0:<PARTITION> 0x200000 sel4test-driver-image-riscv-bananapi-f3
+fatload mmc 0:<PARTITION> 0x31000000 bananapi-f3.dtb
+bootm 0x200000 - 0x31000000
+
+ +

Booting via TFTP

+ +

If you have setup a TFTP server, enter the following commands on the U-Boot console +to load an image via the network.

+ +
dhcp
+tftpboot 0x200000 <YOUR_TFTP_SERVER_IP_ADDRESS>:sel4test-driver-image-riscv-bananapi-f3
+tftpboot 0x31000000 <YOUR_TFTP_SERVER_IP_ADDRESS>:bananapi-f3.dtb
+bootm 0x200000 - 0x31000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/bananapi-f3.md b/Hardware/bananapi-f3.md deleted file mode 100644 index dbc2717e23f..00000000000 --- a/Hardware/bananapi-f3.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: bananapi-f3 -xcompiler_arg: -DRISCV64=1 -platform: Banana Pi BPI-F3 -arch: RV64GCVB -virtualization: false -iommu: false -simulation_target: false -verification: [] -Contrib: "Community" -Maintained: "10xEngineers" -soc: SpacemiT K1 -cpu: X60 -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 10xEngineers ---- - -# Banana Pi BPI-F3 - -The Banana Pi BPI-F3 is an industrial-grade RISC-V single-board computer -from Banana Pi, based on SpacemiT K1 SoC. It has an octa-core RISC-V (8 × X60) -CPU, with integrated 2.0 TOPs AI computing power. - -{% include hw-info.html %} - -Details and links to manuals can be found on the [Banana Pi product -page](https://docs.banana-pi.org/en/BPI-F3/BananaPi_BPI-F3). - -The SoC technical reference manual can be found [on -SpacemiT website](https://developer.spacemit.com/documentation?token=GAmMwCrRUiZAo5kXKUQcNNacnwb&type=pdf). - -The Banana Pi BPI-F3 arrives with the following boot process: - -1. Firmware starts -2. OpenSBI starts -3. U-Boot proper starts - -From U-Boot proper you can then load and start an seL4 image, see below for details. - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Building seL4test - -{% include sel4test.md %} - -## Booting - -There are multiple ways to boot from U-Boot, documented below is booting via TFTP and from -a microSD card. - -### Obtaining the DTB {#dtb} - -Since we are using a `uImage` for the Banana Pi BPI-F3, U-Boot requires a Device Tree Blob (DTB) alongside -the binary image to boot. - -The Device Tree Source (DTS) can be compiled from the seL4 tree with the Device Tree Compiler (`dtc`): -```sh -dtc -I dts -O dtb sel4/tools/dts/bananapi-f3.dts > bananapi-f3.dtb -``` - -### Booting via microSD card - -These instructions expect the microSD card to be paritioned with FAT. - -The microSD card slot registers as device `0` in U-Boot so to see if the device -is recognised run: - -```sh -mmc dev 0 -# Check that the card info is expected -mmc info -# List partitions -mmc part -``` - -To load and run the image: - -```sh -fatload mmc 0: 0x200000 sel4test-driver-image-riscv-bananapi-f3 -fatload mmc 0: 0x31000000 bananapi-f3.dtb -bootm 0x200000 - 0x31000000 -``` - -### Booting via TFTP - -If you have setup a TFTP server, enter the following commands on the U-Boot console -to load an image via the network. - -```sh -dhcp -tftpboot 0x200000 :sel4test-driver-image-riscv-bananapi-f3 -tftpboot 0x31000000 :bananapi-f3.dtb -bootm 0x200000 - 0x31000000 -``` diff --git a/Hardware/cheshire.html b/Hardware/cheshire.html new file mode 100644 index 00000000000..27a17c12637 --- /dev/null +++ b/Hardware/cheshire.html @@ -0,0 +1,762 @@ + + + + + + + Cheshire | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Cheshire

+ +

Cheshire is a 6-stage RISC-V CPU. For details, refer to +https://github.com/pulp-platform/cheshire

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Cheshire
Architecture RV64IMAFDC
CPU Cheshire
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform namecheshire
Contributed by UNSW
Maintained by UNSW
+ +

seL4 currently only provides Cheshire support for the Genesys 2 +board.

+ +

Synthesising Cheshire

+ +

Synthesising hardware for the Genesys 2 requires a Vivado Enterprise license. +Unfortunately there are no prebuilt bitstreams available. Vivado 2023.2 is +recommended. Follow the Cheshire Manual +to install dependencies, then:

+ +
    +
  1. +

    Compile the device tree blob:

    + + 
    make sw/boot/cheshire.genesys2.dtb
+
    +
    2. +
  2. +

    Synthesise the bitstream for the Genesys 2 board:

    + + 
    export VIVADO=/path/to/xilinx/bin/vivado
+make chs-xilinx-genesys2
+
    + +

    This will produce a .bit file in target/xilinx/out/cheshire.genesys2.bit.

    +
    3. +
+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building OpenOCD

+ +

OpenOCD needs to be the RISC-V downstream fork. 6f84e90d is a known working commit. +Follow the instructions in the README to find the required dependencies.

+ +
git clone https://github.com/riscv-collab/riscv-openocd.git
+cd riscv-openocd
+./bootstrap
+./configure --disable-werror --enable-jtag_vpi \
+           --enable-remote-bitbang --enable-ftdi \
+           --prefix=/opt/riscv-openocd/ --exec-prefix=/opt/riscv-openocd
+make -j$(nproc)
+sudo make install
+
+ +

Building OpenSBI

+ +

Cheshire needs a custom build of OpenSBI. It is recommended to compile the FW_JUMP +style image. The device tree blob cheshire.genesys2.dtb was build above. You +might need to use rv64imafdc or rv64g depending on your RISC-V toolchain as the ISA.

+ +
git clone https://github.com/pulp-platform/opensbi.git --branch cheshire
+cd opensbi
+make PLATFORM=fpga/cheshire CROSS_COMPILE=<RISCV_TOOLCHAIN> -j$(nproc) \
+     PLATFORM_RISCV_XLEN=64 PLATFORM_RISCV_ISA=rv64imafdc_zicsr_zifencei PLATFORM_RISCV_ABI=lp64 \
+     FW_JUMP=y FW_JUMP_ADDR=0x90000000 FW_FDT_PATH=/path/to/cheshire.genesys2.dtb
+
+ +

You can then find build/platform/fpga/cheshire/firmware/fw_jump.elf.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=cheshire -DRISCV64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Running seL4test

+ +
+
+ + Note +
+
+ +

Whilst it is possible to setup U-Boot off an SD Card as with other platforms, +Cheshire does not have an ethernet peripheral and so images need to be loaded over GDB.

+ +
+
+ +
    +
  1. +

    Program the FPGA using the Vivado Hardware Manager. Open the hardware manager +GUI and choose /path/to/cheshire/target/xilinx/out/cheshire.genesys2.bit as +the bitstream file in the “Program Device” dialog.

    +
    2. +
  2. +

    In a new terminal, connect an OpenOCD session to the board over the JTAG +micro-USB port.

    + + 
    openocd -f /path/to/cheshire/util/openocd.genesys2.tcl
+
    +
    3. +
  3. +

    In another terminal, connect to OpenOCD using GDB from the RISC-V toolchain.

    + + 
    riscv64-unknown-elf-gdb --eval-command "target extended-remote localhost:3333"
+
    +
    4. +
  4. +

    Use GDB to reset the board, then load seL4test and OpenSBI.

    + + 
    # Reset CPU and halt
+(gdb) monitor reset halt
+
+# Load seL4 image (ELF), entry is 0x90000000
+(gdb) restore sel4test-driver-image-riscv-cheshire
+
+# openSBI compiled with FW_JUMP=y FW_JUMP_ADDR=0x90000000 and embedded DTB
+(gdb) set $a0=0
+(gdb) set $a1=0
+(gdb) load fw_jump.elf
+
+# Run OpenSBI which jumps to seL4
+(gdb) c
+
    +
    5. +
+ +

Notes

+ +

If you encounter issues such as OpenOCD failing to connect, you should attempt +to reset the JTAG connection with lsusb. The JTAG device should have a name +similar to Future Technology Devices International, Ltd FT2232C/D/H Dual UART/FIFO IC. +Note the Bus XXX Device YYY next to the device and reset it with

+ +
sudo usbreset XXX/YYY
+
+ +

Loading the probes (.ltx) file in Vivado Hardware Manager it is also possible +to remotely reset the board using Virtual IOs.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/cheshire.md b/Hardware/cheshire.md deleted file mode 100644 index 6aeb52e5ac3..00000000000 --- a/Hardware/cheshire.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: cheshire -xcompiler_arg: -DRISCV64=1 -platform: Cheshire -arch: RV64IMAFDC -virtualization: false -iommu: false -simulation_target: false -verification: [] -Contrib: "UNSW" -Maintained: "UNSW" -cpu: Cheshire -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC. ---- - -# Cheshire - -Cheshire is a 6-stage RISC-V CPU. For details, refer to -[https://github.com/pulp-platform/cheshire](https://github.com/pulp-platform/cheshire) - -{% include hw-info.html %} - -seL4 currently only provides Cheshire support for the [Genesys 2 -board](https://reference.digilentinc.com/reference/programmable-logic/genesys-2/reference-manual). - -## Synthesising Cheshire - -Synthesising hardware for the Genesys 2 requires a Vivado Enterprise license. -Unfortunately there are no prebuilt bitstreams available. Vivado 2023.2 is -recommended. Follow the [Cheshire Manual](https://pulp-platform.github.io/cheshire/tg/xilinx/) -to install dependencies, then: - -1. Compile the device tree blob: - - ```sh - make sw/boot/cheshire.genesys2.dtb - ``` - -2. Synthesise the bitstream for the Genesys 2 board: - - ```sh - export VIVADO=/path/to/xilinx/bin/vivado - make chs-xilinx-genesys2 - ``` - - This will produce a `.bit` file in `target/xilinx/out/cheshire.genesys2.bit`. - - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Building OpenOCD - -OpenOCD needs to be the RISC-V downstream fork. `6f84e90d` is a known working commit. -Follow the instructions in the README to find the required dependencies. - -```sh -git clone https://github.com/riscv-collab/riscv-openocd.git -cd riscv-openocd -./bootstrap -./configure --disable-werror --enable-jtag_vpi \ - --enable-remote-bitbang --enable-ftdi \ - --prefix=/opt/riscv-openocd/ --exec-prefix=/opt/riscv-openocd -make -j$(nproc) -sudo make install -``` - -## Building OpenSBI - -Cheshire needs a custom build of OpenSBI. It is recommended to compile the `FW_JUMP` -style image. The device tree blob `cheshire.genesys2.dtb` was build above. You -might need to use `rv64imafdc` or `rv64g` depending on your RISC-V toolchain as the ISA. - -```sh -git clone https://github.com/pulp-platform/opensbi.git --branch cheshire -cd opensbi -make PLATFORM=fpga/cheshire CROSS_COMPILE= -j$(nproc) \ - PLATFORM_RISCV_XLEN=64 PLATFORM_RISCV_ISA=rv64imafdc_zicsr_zifencei PLATFORM_RISCV_ABI=lp64 \ - FW_JUMP=y FW_JUMP_ADDR=0x90000000 FW_FDT_PATH=/path/to/cheshire.genesys2.dtb -``` - -You can then find `build/platform/fpga/cheshire/firmware/fw_jump.elf`. - -## Building seL4test - -{% include sel4test.md %} - -## Running seL4test - -{% include note.html %} -Whilst it is possible to setup U-Boot off an SD Card as with other platforms, -Cheshire does not have an ethernet peripheral and so images need to be loaded over GDB. -{% include endnote.html %} - -1. Program the FPGA using the Vivado Hardware Manager. Open the hardware manager - GUI and choose `/path/to/cheshire/target/xilinx/out/cheshire.genesys2.bit` as - the bitstream file in the "Program Device" dialog. - -2. In a new terminal, connect an OpenOCD session to the board over the JTAG - micro-USB port. - - ```sh - openocd -f /path/to/cheshire/util/openocd.genesys2.tcl - ``` - -3. In another terminal, connect to OpenOCD using GDB from the RISC-V toolchain. - - ```sh - riscv64-unknown-elf-gdb --eval-command "target extended-remote localhost:3333" - ``` - -4. Use GDB to reset the board, then load seL4test and OpenSBI. - - ```gdb - # Reset CPU and halt - (gdb) monitor reset halt - - # Load seL4 image (ELF), entry is 0x90000000 - (gdb) restore sel4test-driver-image-riscv-cheshire - - # openSBI compiled with FW_JUMP=y FW_JUMP_ADDR=0x90000000 and embedded DTB - (gdb) set $a0=0 - (gdb) set $a1=0 - (gdb) load fw_jump.elf - - # Run OpenSBI which jumps to seL4 - (gdb) c - ``` - -## Notes - -If you encounter issues such as OpenOCD failing to connect, you should attempt -to reset the JTAG connection with `lsusb`. The JTAG device should have a name -similar to `Future Technology Devices International, Ltd FT2232C/D/H Dual UART/FIFO IC`. -Note the `Bus XXX Device YYY` next to the device and reset it with - -```sh -sudo usbreset XXX/YYY -``` - -Loading the probes (`.ltx`) file in Vivado Hardware Manager it is also possible -to remotely reset the board using [Virtual IOs](https://pulp-platform.github.io/cheshire/tg/xilinx/#virtual-ios). diff --git a/Hardware/hifive-p550.html b/Hardware/hifive-p550.html new file mode 100644 index 00000000000..58475d71010 --- /dev/null +++ b/Hardware/hifive-p550.html @@ -0,0 +1,700 @@ + + + + + + + HiFive Premier P550 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

HiFive Premier P550

+ +

The HiFive Premier P550 is a RISC-V development platform from SiFive based +on the ESWIN EIC7700X SoC. It is a quad-core SoC using the SiFive P550 +CPU.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform HiFive Premier P550
Architecture RV64GC
System-on-chip ESWIN EIC7700X
CPU P550
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform namehifive-p550
Contributed by Community
Maintained by seL4 Foundation
+ +

Details and links to manuals can be found on the SiFive product +page.

+ +

The SoC technical reference manual can be found on +GitHub.

+ +

The HiFive P550 arrives with the following boot process from the SPI flash:

+ +
    +
  1. Firmware starts
    2. +
  2. OpenSBI starts
    3. +
  3. U-Boot proper starts
    4. +
+ +

From U-Boot proper you can then load and start an seL4 image, see below for details.

+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=hifive-p550 -DRISCV64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Booting

+ +

There are multiple ways to boot from U-Boot, documented below is booting via TFTP and from +a microSD card.

+ +

Obtaining the DTB

+ +

Since we are using a uImage for the HiFive P550, U-Boot requires a Device Tree Blob (DTB) alongside +the binary image to boot.

+ +

The Device Tree Source (DTS) can be compiled from the seL4 tree with the Device Tree Compiler (dtc):

+
dtc -I dts -O dtb seL4/tools/dts/hifive-p550.dts > hifive_p550.dtb
+
+ +

Booting via microSD card

+ +

These instructions expect the microSD card to be paritioned with FAT.

+ +

The microSD card slot registers as device 1 in U-Boot so to see if the device +is recognised run:

+ +
mmc dev 1
+# Check that the card info is expected
+mmc info
+# List partitions
+mmc part
+
+ +

To load and run the image:

+ +
fatload mmc 1:<PARTITION> 0x90000000 sel4test-driver-image-riscv-hifive-p550
+fatload mmc 1:<PARTITION> 0xa0000000 hifive_p550.dtb
+bootm 0x90000000 - 0xa0000000
+
+ +

Booting via TFTP

+ +

If you have setup a TFTP server, enter the following commands on the U-Boot console +to load an image via the network.

+ +
dhcp
+tftpboot 0x90000000 <YOUR_TFTP_SERVER_IP_ADDRESS>:sel4test-driver-image-riscv-hifive-p550
+tftpboot 0x90000000 <YOUR_TFTP_SERVER_IP_ADDRESS>:hifive_p550.dtb
+bootm 0x90000000 - 0xa0000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/hifive-p550.md b/Hardware/hifive-p550.md deleted file mode 100644 index d34286803e7..00000000000 --- a/Hardware/hifive-p550.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: hifive-p550 -xcompiler_arg: -DRISCV64=1 -platform: HiFive Premier P550 -arch: RV64GC -virtualization: false -iommu: false -simulation_target: false -verification: [] -Contrib: "Community" -Maintained: "seL4 Foundation" -soc: ESWIN EIC7700X -cpu: P550 -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# HiFive Premier P550 - -The HiFive Premier P550 is a RISC-V development platform from SiFive based -on the ESWIN EIC7700X SoC. It is a quad-core SoC using the SiFive P550 -CPU. - -{% include hw-info.html %} - -Details and links to manuals can be found on the [SiFive product -page](https://www.sifive.com/boards/hifive-premier-p550). - -The SoC technical reference manual can be found [on -GitHub](https://github.com/eswincomputing/EIC7700X-SoC-Technical-Reference-Manual/releases). - -The HiFive P550 arrives with the following boot process from the SPI flash: - -1. Firmware starts -2. OpenSBI starts -3. U-Boot proper starts - -From U-Boot proper you can then load and start an seL4 image, see below for details. - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Building seL4test - -{% include sel4test.md %} - -## Booting - -There are multiple ways to boot from U-Boot, documented below is booting via TFTP and from -a microSD card. - -### Obtaining the DTB {#dtb} - -Since we are using a `uImage` for the HiFive P550, U-Boot requires a Device Tree Blob (DTB) alongside -the binary image to boot. - -The Device Tree Source (DTS) can be compiled from the seL4 tree with the Device Tree Compiler (`dtc`): -```sh -dtc -I dts -O dtb seL4/tools/dts/hifive-p550.dts > hifive_p550.dtb -``` - -### Booting via microSD card - -These instructions expect the microSD card to be paritioned with FAT. - -The microSD card slot registers as device `1` in U-Boot so to see if the device -is recognised run: - -```sh -mmc dev 1 -# Check that the card info is expected -mmc info -# List partitions -mmc part -``` - -To load and run the image: - -```sh -fatload mmc 1: 0x90000000 sel4test-driver-image-riscv-hifive-p550 -fatload mmc 1: 0xa0000000 hifive_p550.dtb -bootm 0x90000000 - 0xa0000000 -``` - -### Booting via TFTP - -If you have setup a TFTP server, enter the following commands on the U-Boot console -to load an image via the network. - -```sh -dhcp -tftpboot 0x90000000 :sel4test-driver-image-riscv-hifive-p550 -tftpboot 0x90000000 :hifive_p550.dtb -bootm 0x90000000 - 0xa0000000 -``` diff --git a/Hardware/hifive.html b/Hardware/hifive.html new file mode 100644 index 00000000000..e1e7330ee56 --- /dev/null +++ b/Hardware/hifive.html @@ -0,0 +1,654 @@ + + + + + + + HiFive Unleashed | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

HiFive Unleashed

+ +

HiFive Unleashed is a RISC-V development board by SiFive. Check +here for details.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform HiFive Unleashed
Architecture RV64IMAC, RV64GC
System-on-chip Freedom U540
CPU U54-MC, E51
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + +
Proof configsRISCV64
seL4 CMake platform namehifive
Contributed by Data61
Maintained by seL4 Foundation
+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=hifive -DRISCV64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Booting via SD card

+ +
    +
  1. +

    Set all DIP switches to 1(towards CPU).

    +
    2. +
  2. Prepare the SD card + 
    sudo sgdisk --clear --new=1:2048:67583 --typecode=1:3000 /dev/sdX
+sudo dd if=images/sel4test-driver-image-riscv-hifive of=/dev/sdX1
+
    +
    3. +
  3. Insert the SD card and connect the micro USB port(J7). +Note that the UART device node is /dev/ttyUSB1
    4. +
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/hifive.md b/Hardware/hifive.md deleted file mode 100644 index 3bb13c5f9d9..00000000000 --- a/Hardware/hifive.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: hifive -xcompiler_arg: -DRISCV64=1 -platform: HiFive Unleashed -arch: RV64IMAC, RV64GC -virtualization: false -iommu: false -simulation_target: false -verification: [RISCV64] -Contrib: "Data61" -Maintained: "seL4 Foundation" -soc: Freedom U540 -cpu: U54-MC, E51 -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# HiFive Unleashed - -HiFive Unleashed is a RISC-V development board by SiFive. Check -[here](https://www.sifive.com/boards/hifive-unleashed) for details. - -{% include hw-info.html %} - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Building seL4test - -{% include sel4test.md %} - -## Booting via SD card - -1. Set all DIP switches to 1(towards CPU). - -2. Prepare the SD card - ```sh - sudo sgdisk --clear --new=1:2048:67583 --typecode=1:3000 /dev/sdX - sudo dd if=images/sel4test-driver-image-riscv-hifive of=/dev/sdX1 - ``` -3. Insert the SD card and connect the micro USB port(J7). - Note that the UART device node is /dev/ttyUSB1 diff --git a/Hardware/imx8mm.html b/Hardware/imx8mm.html new file mode 100644 index 00000000000..1c5dbc05d01 --- /dev/null +++ b/Hardware/imx8mm.html @@ -0,0 +1,622 @@ + + + + + + + i.MX8M Mini | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

i.MX8M Mini

+ +

See also the NXP i.MX8M Mini web page.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform i.MX8M Mini
Architecture ARMv8A
System-on-chip IMX8MM-EVK
CPU Cortex-A53 Quad 1.8 GHz
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + +
Proof configsARM, AARCH64
seL4 CMake platform nameimx8mm-evk
Contributed by Data61
Maintained by seL4 Foundation
+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=imx8mm-evk -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/imx8mm.md b/Hardware/imx8mm.md deleted file mode 100644 index 748b6271e14..00000000000 --- a/Hardware/imx8mm.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -arm_hardware: true -cmake_plat: imx8mm-evk -xcompiler_arg: -DAARCH64=1 -platform: i.MX8M Mini -arch: ARMv8A -virtualization: false -iommu: false -soc: IMX8MM-EVK -cpu: Cortex-A53 Quad 1.8 GHz -verification: [ARM, AARCH64] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# i.MX8M Mini - -See also the NXP [i.MX8M Mini web page](https://www.nxp.com/products/i.MX8MMINI). - -{% include hw-info.html %} - -## Building seL4test - -{% include sel4test.md %} - diff --git a/Hardware/imx8mp.html b/Hardware/imx8mp.html new file mode 100644 index 00000000000..15eef8c0ce8 --- /dev/null +++ b/Hardware/imx8mp.html @@ -0,0 +1,627 @@ + + + + + + + i.MX8M Plus | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

i.MX8M Plus

+ +

See also the NXP i.MX8M Plus product +page.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform i.MX8M Plus
Architecture ARMv8A, AArch64
System-on-chip IMX8MP-EVK
CPU Cortex-A53 Quad 1.8 GHz
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nameimx8mp-evk
Contributed by Data61
Maintained by seL4 Foundation
+ +

The seL4 i.MX8 port currently only supports running the board in AArch64 mode.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=imx8mp-evk -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/imx8mp.md b/Hardware/imx8mp.md deleted file mode 100644 index a56ffb0cd7a..00000000000 --- a/Hardware/imx8mp.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -arm_hardware: true -cmake_plat: imx8mp-evk -xcompiler_arg: -DAARCH64=1 -platform: i.MX8M Plus -arch: ARMv8A, AArch64 -virtualization: true -iommu: false -soc: IMX8MP-EVK -cpu: Cortex-A53 Quad 1.8 GHz -verification: [AARCH64] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# i.MX8M Plus - -See also the NXP [i.MX8M Plus product -page](https://www.nxp.com/design/design-center/development-boards-and-designs/8MPLUSLPD4-EVK). - -{% include hw-info.html %} - -The seL4 i.MX8 port currently only supports running the board in AArch64 mode. - -## Building seL4test - -{% include sel4test.md %} diff --git a/Hardware/imx8mq.html b/Hardware/imx8mq.html new file mode 100644 index 00000000000..57b21096d5d --- /dev/null +++ b/Hardware/imx8mq.html @@ -0,0 +1,628 @@ + + + + + + + i.MX8M Quad | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

i.MX8M Quad

+ +

See also the the NXP i.MX8M Quad fact +sheet.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform i.MX8M Quad
Architecture ARMv8A, AArch64
System-on-chip MCIMX8M-EVKB
CPU Cortex-A53 Quad 1.5 GHz
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nameimx8mq-evk
Contributed by Data61
Maintained by seL4 Foundation
+ +

The seL4 i.MX8M Quad port currently only supports running the board in AArch64 +mode.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=imx8mq-evk -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/imx8mq.md b/Hardware/imx8mq.md deleted file mode 100644 index 83f671d5e3f..00000000000 --- a/Hardware/imx8mq.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -arm_hardware: true -cmake_plat: imx8mq-evk -xcompiler_arg: -DAARCH64=1 -platform: i.MX8M Quad -arch: ARMv8A, AArch64 -virtualization: true -iommu: false -soc: MCIMX8M-EVKB -cpu: Cortex-A53 Quad 1.5 GHz -verification: [AARCH64] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# i.MX8M Quad - -See also the the NXP [i.MX8M Quad fact -sheet](https://www.nxp.com/docs/en/fact-sheet/IMX8MQUADEVKFS.pdf). - -{% include hw-info.html %} - -The seL4 i.MX8M Quad port currently only supports running the board in AArch64 -mode. - -## Building seL4test - -{% include sel4test.md %} - diff --git a/Hardware/imx93.html b/Hardware/imx93.html new file mode 100644 index 00000000000..add7b0ecb5b --- /dev/null +++ b/Hardware/imx93.html @@ -0,0 +1,628 @@ + + + + + + + i.MX93 Evaluation Kit | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

i.MX93 Evaluation Kit

+ +

See also the NXP i.MX93 EVK product +page.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform i.MX93 EVK
Architecture ARMv8A, AArch64
System-on-chip i.MX93
CPU Cortex-A55
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nameimx93
Contributed by Indan Zupančič, Proofcraft
Maintained by seL4 Foundation
+ +

The seL4 i.MX93 port currently only supports running the board in AArch64 +mode.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=imx93 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/imx93.md b/Hardware/imx93.md deleted file mode 100644 index c045006ee5c..00000000000 --- a/Hardware/imx93.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -arm_hardware: true -cmake_plat: imx93 -xcompiler_arg: -DAARCH64=1 -platform: i.MX93 EVK -arch: ARMv8A, AArch64 -virtualization: true -iommu: false -soc: i.MX93 -cpu: Cortex-A55 -verification: [AARCH64] -Contrib: Indan Zupančič, Proofcraft -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. ---- - -# i.MX93 Evaluation Kit - -See also the NXP [i.MX93 EVK product -page](https://www.nxp.com/design/design-center/development-boards-and-designs/i.MX93EVK). - -{% include hw-info.html %} - -The seL4 i.MX93 port currently only supports running the board in AArch64 -mode. - -## Building seL4test - -{% include sel4test.md %} diff --git a/Hardware/index.html b/Hardware/index.html new file mode 100644 index 00000000000..7996a97632a --- /dev/null +++ b/Hardware/index.html @@ -0,0 +1,1342 @@ + + + + + + + Supported platforms | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Supported platforms

+ +

seL4 is available on 3 major hardware architectures, Arm, +RISC-V and x86, for a number of platforms with varying +hardware features.

+ +

The tables below list the platforms for which seL4 is available. For each +platform, the tables list whether specific features are supported (e.g. +Virtualisation, IOMMU/SMMU, etc) and to which degree (where applicable), as +well as the verification status for that platform.

+ +

seL4 is formally verified for specific configurations for a subset of these +platforms. The depth of the proofs and which properties are verified depend on +the platform and are noted in the Verification Status column as follows:

+ +
    +
  • Unverified: this platform is not verified at all and is not scheduled for verification.
    • +
  • Ongoing: this feature is currently undergoing verification.
    • +
  • FC: the functional correctness proofs are complete.
    • +
  • Verified: all proofs for this platform are complete, including functional +correctness, integrity and information flow.
    • +
+ +

More information can be found on the Verified Configurations page.

+ +

Arm

+ +

seL4 has support for select ARMv7 and ARMv8 Platforms. In addition to the page +with general instructions how to run seL4 on Arm, each board +page may have additional instructions for running seL4 on it.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlatformSystem-on-chipCoreVirtualisationSMMUProofsProof config
Avnet MaaXBoardi.MX8MQCortex-A53 Quad 1.5 GHz + + + – + + + AARCH64
BeagleBoardOMAP3Cortex-A8 + – + + – + + + ARM
BeagleBone Black / BlueAM335xCortex-A8 + – + + – + + + ARM
Jetson TK1NVIDIA Tegra K1Cortex-A15 + + + + + + ARM, ARM_HYP
Odroid-C2Amlogic S905Cortex-A53 + + + – + + + AARCH64
Odroid-C4Amlogic S905X3Cortex-A55 + + + – + + + AARCH64
OdroidXUExynos5Cortex-A15 + + + + + + ARM, ARM_HYP
OdroidXU4Exynos5Cortex-A15 + + + + + + ARM, ARM_HYP
QEMU Arm VirtvirtMultiple + + + – + + N/A
ROCKPro64RK3399 hexa-coreCortex-A53 Quad 1.8 GHz + + + – + + + AARCH64
Raspberry Pi 3-bBCM2837Cortex-A53 + + + – + + + ARM
Raspberry Pi 4BBCM2711Cortex-A72 + + + – + + + AARCH64
Rock3bRK3568 quad-coreCortex-A55 Quad 2.0 GHz + + + – + + + AARCH64
Sabre Litei.MX6Cortex-A9 + – + + – + + + ARM
TK1-SOMNVIDIA Tegra K1Cortex-A15 + + + + + + ARM_HYP
TQMa8XQP 1GBi.MX8X Quad PlusCortex-A35 + – + + – + + + AARCH64
TX1NVIDIA Tegra X1Cortex-A57 Quad + + + + + + AARCH64
TX2NVIDIA Tegra X2Cortex-A57 Quad, Dual NVIDIA Denver + + + + + + AARCH64
Ultra96v2 Evaluation KitZynq UltraScale+ MPSoCCortex-A53 + + + + + + AARCH64
Zynq ZCU106 Evaluation KitZynq UltraScale+ MPSoCCortex-A53 + + + + + + ARM, AARCH64
Zynq ZCU102 Evaluation KitZynq UltraScale+ MPSoCCortex-A53 + + + + + + ARM, AARCH64
Zynq-7000 ZC706 Evaluation KitZynq7000Cortex-A9 + – + + – + + + ARM
i.MX8M MiniIMX8MM-EVKCortex-A53 Quad 1.8 GHz + – + + – + + + ARM, AARCH64
i.MX8M PlusIMX8MP-EVKCortex-A53 Quad 1.8 GHz + + + – + + + AARCH64
i.MX8M QuadMCIMX8M-EVKBCortex-A53 Quad 1.5 GHz + + + – + + + AARCH64
i.MX93 EVKi.MX93Cortex-A55 + + + – + + + AARCH64
+
+ +

RISC-V

+ +

We currently provide support for some of the RISC-V platforms. Support for the hypervisor extension is yet to be mainlined.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlatformSystem-on-chipCoreArchProofsProof config
ArianeAriane (CVA6)RV64IMAC + – + –
Banana Pi BPI-F3SpacemiT K1X60RV64GCVB + – + –
CheshireCheshireRV64IMAFDC + – + –
HiFive Premier P550ESWIN EIC7700XP550RV64GC + – + –
HiFive UnleashedFreedom U540U54-MC, E51RV64IMAC, RV64GC + + RISCV64
Microchip PolarFire Icicle KitPolarFire SoC FPGAU54-MC, E51RV64IMAC, RV64GC + – + –
Pine64 Star64StarFive JH7110U74-MC, E24RV64GBC, RV64IMAC, RV32IMAFBC + – + –
QEMU RISC-Vvirtrv32, rv64RV32GC, RV64IMAC + N/A
RocketchipRocketRV64IMAFDC + – + –
RocketchipRocketRV64IMAFDC + – + –
SpikeRV32GC, RV64IMAFDC + – + –
+
+ +

x86

+ +

seL4 supports PC99-style Intel Architecture Platforms.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlatformArchVirtualisationIOMMUProofsProof config
PC99 (32-bit)x86VT-XVT-D--
PC99 (64-bit)x64VT-XVT-DyesX64
+ +

Simulating seL4

+ +

Running seL4 in a simulator is a quick way to test it out and iteratively +develop software. Note that feature support is then limited by the simulator. +See the QEMU Arm and RISCV targets +and the simulation instructions for sel4test +for x86 for how to run seL4 using QEMU. Some hardware platforms support the +SIMULATION=1 option — this will be marked on the respective platform page +and will generally be good enough to run most of the seL4 test suite, but QEMU +usually does not provide enough hardware device implementation to build more +complex systems in the simulated environment.

+ +

Not in the lists above?

+ +

If the platform, architecture, feature that you are after is not listed on this page, +you have several options, listed below. It is important to note however that, as +explained in the guidelines linked below, contributing new ports or features will require +compelling arguments, discussion with the technical community (including through +Request-For-Comments), as well as testing requirements and maintenance/expertise +commitment, to a degree depending on the nature of the contribution.

+ +
    +
  • +

    You can contact one of the seL4 Foundation Endorsed Services +Providers to get commercial +support or professional advice to develop such a port or feature (with the +implications and expectations detailed in our guidelines for contributing +kernel code);

    +
    • +
  • +

    You can check the roadmap for any planned +contributions, from the seL4 Foundation or larger community, such on any new +architecture ports, new large formal verifications, or large or fundamental +new features;

    +
    • +
  • +

    You can contact the seL4 community through one of our communication +channels to ask whether someone is developing +such a port or feature already, or whether there is general interest in discussing +such a new port or feature;

    +
    • +
  • +

    If you are in a position to develop the seL4 port or feature yourself, you +should follow our guidelines for contributing kernel +code, which details the +implications and expectations.

    +
    • +
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/index.md b/Hardware/index.md deleted file mode 100644 index 8c31928184e..00000000000 --- a/Hardware/index.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -wide: true ---- - -# Supported platforms - -seL4 is available on 3 major hardware architectures, [Arm](#arm), -[RISC-V](#risc-v) and [x86](#x86), for a number of platforms with varying -hardware features. - -The tables below list the platforms for which seL4 is available. For each -platform, the tables list whether specific features are supported (e.g. -*Virtualisation*, *IOMMU/SMMU*, etc) and to which degree (where applicable), as -well as the *verification status* for that platform. - -seL4 is formally verified for specific configurations for a subset of these -platforms. The depth of the proofs and which properties are verified depend on -the platform and are noted in the *Verification Status* column as follows: - -* Unverified: this platform is not verified at all and is not scheduled for verification. -* Ongoing: this feature is currently undergoing verification. -* FC: the functional correctness proofs are complete. -* Verified: all proofs for this platform are complete, including functional - correctness, integrity and information flow. - -More information can be found on the [Verified Configurations](../projects/sel4/verified-configurations.md) page. - -## Arm - -seL4 has support for select ARMv7 and ARMv8 Platforms. In addition to the page -with [general instructions how to run seL4 on Arm](GeneralARM.html), each board -page may have additional instructions for running seL4 on it. - -
- - - - - - - - - - - - - -{%- assign sorted = site.pages | sort: 'platform' %} -{%- for page in sorted %} -{%- if page.arm_hardware and page.Maintained -%} -{%- assign status = "" %} -{%- for config in page.verification -%} -{%- assign link = "/projects/sel4/verified-configurations.html#" | append: config | relative_url -%} -{%- assign status = status | append: '' | append: config | append: '' %} -{%- unless forloop.last %} -{%- assign status = status | append: ", " %} -{%- endunless %} -{%- endfor %} - - - - - - - - - -{%- endif %} -{%- endfor %} - -
PlatformSystem-on-chipCoreVirtualisationSMMUProofsProof config
{{ page.platform }}{{ page.soc}}{{ page.cpu }} -{%- if page.virtualization %} - {% svg _icons/check.svg class="inline-icon stroke-3 text-f_green-500 dark:text-logogreen" %} -{%- else %} - – -{%- endif %} - -{%- if page.iommu %} -{%- if page.iommu == "limited" %} -{%- assign color="text-yellow-500" %} -{%- else %} -{%- assign color="text-f_green-500 dark:text-logogreen" %} -{%- endif %} - {% svg _icons/check.svg class="inline-icon stroke-3 {{color}}" %} -{%- else %} - – -{%- endif %} - -{%- if status != "" %} - {% svg _icons/check.svg class="inline-icon stroke-3 text-f_green-500 dark:text-logogreen" %} -{%- elsif page.simulation_only %} -{%- assign status = "N/A" %} -{%- else %} -{%- assign status = "–" %} - – -{%- endif %} - {{status}}
-
- -## RISC-V - -We currently provide support for some of the RISC-V platforms. Support for the hypervisor extension is yet to be mainlined. - -
- - - - - - - - - - - - - -{%- for page in sorted %} -{%- if page.riscv_hardware and page.Maintained -%} -{%- assign status = "" %} -{%- for config in page.verification -%} -{%- assign link = "/projects/sel4/verified-configurations.html#" | append: config | relative_url -%} -{%- assign status = status | append: '' | append: config | append: '' %} -{%- unless forloop.last %} -{%- assign status = status | append: ", " %} -{%- endunless %} -{%- endfor %} - - - - - - - - - -{%- endif %} -{%- endfor %} - -
PlatformSystem-on-chipCoreArchProofsProof config
{{ page.platform }}{{ page.soc}}{{ page.cpu }}{{ page.arch }} -{%- if status != "" %} - {% svg _icons/check.svg class="inline-icon stroke-3 text-f_green-500 dark:text-logogreen" %} -{%- elsif page.simulation_only %} -{%- assign status = "N/A" %} -{%- else %} -{%- assign status = "–" %} - – -{%- endif %} - {{status}}
-
- -## x86 - -seL4 supports PC99-style Intel Architecture Platforms. - -| Platform | Arch | Virtualisation | IOMMU | Proofs | Proof config | -| - | - | - | - | - | - | -| [PC99 (32-bit)](IA32.html) | x86 | VT-X | VT-D | - | - | -| [PC99 (64-bit)](X64.html) | x64 | VT-X | VT-D | yes | [X64] | - -[X64]: {{ '/projects/sel4/verified-configurations.html#X64' | relative_url }} - - -### Simulating seL4 - -Running seL4 in a simulator is a quick way to test it out and iteratively -develop software. Note that feature support is then limited by the simulator. -See the QEMU [Arm](qemu-arm-virt.html) and [RISCV](qemu-riscv-virt.html) targets -and the [simulation instructions for sel4test](../projects/sel4test/) -for x86 for how to run seL4 using QEMU. Some hardware platforms support the -`SIMULATION=1` option --- this will be marked on the respective platform page -and will generally be good enough to run most of the seL4 test suite, but QEMU -usually does not provide enough hardware device implementation to build more -complex systems in the simulated environment. - -### Not in the lists above? - -If the platform, architecture, feature that you are after is not listed on this page, -you have several options, listed below. It is important to note however that, as -explained in the guidelines linked below, contributing new ports or features will require -compelling arguments, discussion with the technical community (including through -Request-For-Comments), as well as testing requirements and maintenance/expertise -commitment, to a degree depending on the nature of the contribution. - - -- You can contact one of the seL4 Foundation [Endorsed Services - Providers](https://sel4.systems/Foundation/Services/) to get commercial - support or professional advice to develop such a port or feature (with the - implications and expectations detailed in our [guidelines for contributing - kernel code](../projects/sel4/kernel-contribution.html)); - -- You can check the [roadmap](https://sel4.systems/roadmap.html) for any planned - contributions, from the seL4 Foundation or larger community, such on any new - architecture ports, new large formal verifications, or large or fundamental - new features; - -- You can contact the seL4 community through one of our [communication - channels](https://sel4.systems/contact/) to ask whether someone is developing - such a port or feature already, or whether there is general interest in discussing - such a new port or feature; - -- If you are in a position to develop the seL4 port or feature yourself, you - should follow our [guidelines for contributing kernel - code](../projects/sel4/kernel-contribution.html), which details the - implications and expectations. diff --git a/Hardware/jetsontk1.html b/Hardware/jetsontk1.html new file mode 100644 index 00000000000..1b9c05be836 --- /dev/null +++ b/Hardware/jetsontk1.html @@ -0,0 +1,751 @@ + + + + + + + Jetson TK1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Jetson TK1

+ +

The Jetson TK1 +is a affordable embedded system developed by NVIDIA.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Jetson TK1
Architecture ARMv7A
System-on-chip NVIDIA Tegra K1
CPU Cortex-A15
seL4 virtualisation support + +
seL4 SMMU support + +
Proofs + +
Proof configsARM, ARM_HYP
seL4 CMake platform nametk1
Contributed by Data61
Maintained by seL4 Foundation
+ +

Pre-Requisites

+ + + +

Getting Started

+ +

To get started, check out the NVIDIA developer +page, make sure your board is +correctly configured and plugged.

+ +

Build your first seL4 system

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=tk1 -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Load the binary

+ +

You need to be able to see output from the serial console on the Tegra. Connect +the serial port to your computer with a serial cable, either a USB->RS232 +converter, or if your computer has a serial port, connect to it.

+ +

Once you have the wires in place, you can connect to the console via +screen (or you can use minicom or another serial console program). In +the following, we assume that the Tegra is connected to /dev/ttyUSB0.

+ +
screen /dev/ttyUSB0 115200
+
+ +

When you start the board, you will see the U-Boot prompt. To load the +binary you need to interact with U-Boot. I personally use a DHCP/TFTP +server to get the binary onto the board. Copy sel4.img onto the tftp +server; if you’ve set up DHCP properly it will pass the server IP to the +board. Otherwise you can specify the IOP address on the command. The +following command will then scan the PCI bus and enable the ethernet, +and then ask to get an address via the DHCP and get sel4.img file from +the TFTP server at 192.168.1.1.

+ +
pci enum dhcp ${loadaddr} 192.168.1.1:sel4.img
+
+ +

Then, let’s start the program.

+ +
bootefi ${loadaddr}
+
+ +

Flash U-Boot

+ +

Warning: This flashing procedure is for the Jetson TK1 by NVIDIA. There +is another TK1 board called the TK1-SOM by Colorado Engineering which +requires a different flashing procedure. Please be sure you’re following +these instructions if you are truly trying to flash a Jetson and +not the TK1-SOM. If you are trying to flash a TK1-SOM, please +use the procedure described here instead.

+ +

The initial version of U-Boot does not provides all necessary +functionality. In particular, it boots the system in secure mode. To run +a virtual machine monitor, the Tegra needs to be booted in nonsecure or +HYP mode. After installing a new u-boot (instructions below) you can +boot in either secure on non-secure mode based on a u-boot environment +variable.

+ +

Do

+ +
setenv bootm_boot_mode nonsec
+saveenv
+
+ +

to boot in nonsecure (HYP) +mode. This also enables kvm if you boot Linux.

+ +

To go back to secure mode booting do

+ +
setenv bootm_boot_mode sec
+saveenv
+
+ +

Getting the sources

+ +
mkdir tegra-u-boot-flasher
+cd tegra-u-boot-flasher
+repo init -u https://github.com/NVIDIA/tegra-uboot-flasher-manifests.git
+repo sync
+
+ +

Building

+ +

To build the sources, build the necessary tools first.

+ +

Install autoconf, pkg-config, flex, bison, libcrypto++-dev and libusb-1.0.0-dev +for your distribution. On Debian or Ubuntu you can do:

+ +
sudo apt-get update
+sudo apt-get install build-essential autoconf pkg-config flex bison libcrypto++-dev libusb-1.0.0-dev gcc-arm-linux-gnueabi
+
+ +

Then do:

+ +
cd scripts
+./build-tools build
+
+ +

Then, in the script directory, build everything.

+ +
./build --socs tegra124 --boards jetson-tk1 build
+
+ +

Flashing

+ +

To flash, attach the Jetson board’s OTG USB port to a USB port on your machine. +Hold down the FORCE RECOVERY button while pressing the RESET button next to it; +release FORCE RECOVERY a second or two after releasing the reset button

+ +

Then issue:

+ +
./tegra-uboot-flasher flash jetson-tk1
+
+ +

The board should now be updated.

+ +

Running Linux with the new U-Boot

+ +

To boot Linux in non-secure mode, build the kernel with the Power-State +Coordination Interface (PSCI) enabled (CONFIG_ARM_PSCI=y, in Kernel Features +menu)and CPU-Idle PM support disabled (CONFIG_CPU_IDLE is not set in CPU Power +Management->CPU Idle). Without these changes the kernel will hang.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/jetsontk1.md b/Hardware/jetsontk1.md deleted file mode 100644 index 58c07d15ba4..00000000000 --- a/Hardware/jetsontk1.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -arm_hardware: true -cmake_plat: tk1 -xcompiler_arg: -DAARCH32=1 -platform: Jetson TK1 -arch: ARMv7A -virtualization: true -iommu: true -soc: NVIDIA Tegra K1 -cpu: Cortex-A15 -verification: [ARM, ARM_HYP] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Jetson TK1 - -The [Jetson TK1](http://www.nvidia.com/object/jetson-tk1-embedded-dev-kit.html) -is a affordable embedded system developed by NVIDIA. - -{% include hw-info.html %} - -## Pre-Requisites - -* One Tegra Board. See [Jetson TK1](http://www.nvidia.com/object/jetson-tk1-embedded-dev-kit.html) -* A working development environment. See the [set up - instructions](../projects/buildsystem/host-dependencies.html). - -## Getting Started - - To get started, check out the [NVIDIA developer -page](https://developer.nvidia.com/embedded-computing), make sure your board is -correctly configured and plugged. - -## Build your first seL4 system - -{% include sel4test.md %} - -## Load the binary - -You need to be able to see output from the serial console on the Tegra. Connect -the serial port to your computer with a serial cable, either a USB->RS232 -converter, or if your computer has a serial port, connect to it. - -Once you have the wires in place, you can connect to the console via -`screen` (or you can use minicom or another serial console program). In -the following, we assume that the Tegra is connected to `/dev/ttyUSB0`. - -```sh -screen /dev/ttyUSB0 115200 -``` - -When you start the board, you will see the U-Boot prompt. To load the -binary you need to interact with U-Boot. I personally use a DHCP/TFTP -server to get the binary onto the board. Copy `sel4.img` onto the tftp -server; if you've set up DHCP properly it will pass the server IP to the -board. Otherwise you can specify the IOP address on the command. The -following command will then scan the PCI bus and enable the ethernet, -and then ask to get an address via the DHCP and get `sel4.img` file from -the TFTP server at `192.168.1.1`. - -```sh -pci enum dhcp ${loadaddr} 192.168.1.1:sel4.img -``` - -Then, let's start the program. - -```sh -bootefi ${loadaddr} -``` - -## Flash U-Boot - - -Warning: This flashing procedure is for the Jetson TK1 by NVIDIA. There -is another TK1 board called the TK1-SOM by Colorado Engineering which -requires a different flashing procedure. Please be sure you're following -these instructions if you are truly trying to flash a **Jetson** and -not the **TK1-SOM**. If you are trying to flash a TK1-SOM, please -[use the procedure described here instead](CEI_TK1_SOM/#u-boot). - -The initial version of U-Boot does not provides all necessary -functionality. In particular, it boots the system in secure mode. To run -a virtual machine monitor, the Tegra needs to be booted in nonsecure or -HYP mode. After installing a new u-boot (instructions below) you can -boot in either secure on non-secure mode based on a u-boot environment -variable. - -Do - -```sh -setenv bootm_boot_mode nonsec -saveenv -``` - -to boot in nonsecure (HYP) -mode. This also enables kvm if you boot Linux. - -To go back to secure mode booting do - -```sh -setenv bootm_boot_mode sec -saveenv -``` - -## Getting the sources - -```bash -mkdir tegra-u-boot-flasher -cd tegra-u-boot-flasher -repo init -u https://github.com/NVIDIA/tegra-uboot-flasher-manifests.git -repo sync -``` - -## Building - -To build the sources, build the necessary tools first. - -Install autoconf, pkg-config, flex, bison, libcrypto++-dev and libusb-1.0.0-dev -for your distribution. On Debian or Ubuntu you can do: - -```sh -sudo apt-get update -sudo apt-get install build-essential autoconf pkg-config flex bison libcrypto++-dev libusb-1.0.0-dev gcc-arm-linux-gnueabi -``` - -Then do: - -```bash -cd scripts -./build-tools build -``` - -Then, in the script directory, build everything. - -```bash -./build --socs tegra124 --boards jetson-tk1 build -``` - -## Flashing - -To flash, attach the Jetson board's OTG USB port to a USB port on your machine. -Hold down the FORCE RECOVERY button while pressing the RESET button next to it; -release FORCE RECOVERY a second or two after releasing the reset button - -Then issue: - -```bash -./tegra-uboot-flasher flash jetson-tk1 -``` - -The board should now be updated. - -## Running Linux with the new U-Boot - -To boot Linux in non-secure mode, build the kernel with the Power-State -Coordination Interface (PSCI) enabled (`CONFIG_ARM_PSCI=y`, in Kernel Features -menu)and CPU-Idle PM support disabled (`CONFIG_CPU_IDLE is not set` in CPU Power -Management->CPU Idle). Without these changes the kernel will hang. diff --git a/Hardware/jetsontx1.html b/Hardware/jetsontx1.html new file mode 100644 index 00000000000..06304f63082 --- /dev/null +++ b/Hardware/jetsontx1.html @@ -0,0 +1,746 @@ + + + + + + + Jetson TX1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Jetson TX1

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform TX1
Architecture ARMv8A, AArch64 only
System-on-chip NVIDIA Tegra X1
CPU Cortex-A57 Quad
seL4 virtualisation support + +
seL4 SMMU support + +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nametx1
Contributed by Data61
Maintained by seL4 Foundation
+ +

The Jetson TX1 is a multimedia and DSP board with a highly +optimized 64-bit memory controller which supports low latency accesses +from the CPU, high bandwidth accesses from the GPU and bounded latency +accesses from real-time devices such as the display.

+ +

It has two multi-core CPU clusters, each with 4 identical cores (One +Cortex-A57 cluster and one Cortex-A53 cluster). Each cluster has its own +L2 cache. Both clusters are ARMv8 compliant platforms. In addition the +Tx1 has an ARM7 shadow Co-processor.

+ +

The seL4 kernel has a limited port to the TX1 which supports the SoC +only in 64-bit mode. SMP, SMMU, Hyp-mode, etc are not supported by the +current port of the seL4 kernel to the TX1.

+ +

The stock TX1 comes with support for booting using DFU, using an SD-card +or by copying the OS you would like to boot onto the internal 15 GiB USB +mass storage that comes with the TX1.

+ +

Unfortunately the stock U-boot that comes with the TX1 does not support +TFTP-boot over the Ethernet port. You can get U-boot to support the +TX1’s Ethernet driver and enable TFTP-boot, but this is beyond the scope +of this article since it entails compiling a custom U-boot and then +flashing it onto the board.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=tx1 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

The TX1 also supports AArch32 mode. If you choose to build the AArch32 kernel, +please be sure to pass -DAARCH32=1 instead of -DAARCH64=1.

+ +

Booting via TFTP

+

Unfortunately the stock U-boot that comes with +the TX1 does not support TFTP because +it does not come with an ethernet driver, but if you so choose, it +seems that it is possible to recomplile u-boot with support for the +ethernet driver, and then flash your custom U-boot onto your TX1. +Instructions on how to do this are not included here.

+ +

Booting via DFU

+ +

To boot via DFU, attach the usb-mini end of a USB cable to the USB-mini +port on the TX1. Then plug in the power supply for the TX1 and power it +on. When the TX1 is powered on, pay attention to the text being printed +out so that you can stop the boot process at the U-boot command prompt. +When you have successfully got to the U-boot command prompt, enter the +following:

+
setenv dfu_alt_info "kernel ram 0x82000000 0x1000000"
+setenv bootcmd_dfu "dfu 0 ram 0; go 0x82000000"
+saveenv
+
+ +

To make U-boot enter its DFU server mode now, just type: +run bootcmd_dfu. U-boot should sit still waiting for a kernel image to +be uploaded. Now you should open up a new terminal on your PC, and type +the following:

+
dfu-util --device 0955:701a -a kernel -D <PATH_TO_YOUR_SEL4_IMAGE>/sel4test-driver-image-arm-tx1
+
+ +

You may need to give dfu-util root privileges. If dfu-util is unable to +find the TX1 device, try unplugging and replugging in the USB mini-cable +that connects your PC to the TX1.

+ +

Booting via SD Card

+ +

Get an SD card and format it with either FAT32, EXT2 or EXT4. Then build +seL4test, or any of the other seL4 projects. The resulting image file +should be placed inside of /images within the build directory. Take that +image file, and copy it to the root folder of the SD card you intend to +use with your TX1.

+ +

Insert this SD card into your TX1 and then power on the TX1, and drop +into the U-boot command prompt. When you’re at the prompt, please type +the following:

+ +

For FAT32:

+
fatload mmc 1 0x82000000 sel4test-driver-image-arm-tx1
+go 0x82000000
+
+ +

For EXT2:

+
ext2load mmc 1 0x82000000 sel4test-driver-image-arm-tx1
+go 0x82000000
+
+ +

For EXT4:

+
ext4load mmc 1 0x82000000 sel4test-driver-image-arm-tx1
+go 0x82000000
+
+ +

Internal 15 GiB USB mass storage

+ +

Booting off the internal USB mass storage is almost the same as booting +off the SD card, but in particular, you should do something along the +lines of:

+ +

Attach a USB mini cable to the mini-USB port on the TX1, and the other +end of the cable to your PC. Then power on the TX1 and drop into the +U-boot command line, and do the following:

+ +
ums mmc 0
+
+ +

Your PC should now show that a new USB mass storage device has been +connected. Copy the seL4 image into the root directory of this mass +storage device, then unmount it and remove it safely. Then go back to +the U-boot command line and press Ctrl+C to exit the mass-storage +server. Then, type the following, depending on the filesystem type that +you formatted the internal mass storage device to (or if you didn’t +personally format it, then whatever filesystem already existed on the +internal mass storage):

+ +

For FAT32:

+
fatload mmc 0 0x82000000 sel4test-driver-image-arm-tx1
+go 0x82000000
+
+ +

For EXT2:

+
ext2load mmc 0 0x82000000 sel4test-driver-image-arm-tx1
+go 0x82000000
+
+ +

For EXT4:

+
ext4load mmc 0 0x82000000 sel4test-driver-image-arm-tx1
+go 0x82000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/jetsontx1.md b/Hardware/jetsontx1.md deleted file mode 100644 index d8dfd091a50..00000000000 --- a/Hardware/jetsontx1.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -arm_hardware: true -cmake_plat: tx1 -xcompiler_arg: -DAARCH64=1 -platform: TX1 -arch: ARMv8A, AArch64 only -virtualization: true -iommu: true -soc: NVIDIA Tegra X1 -cpu: Cortex-A57 Quad -verification: [AARCH64] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Jetson TX1 - -{% include hw-info.html %} - -The Jetson TX1 is a multimedia and DSP board with a highly -optimized 64-bit memory controller which supports low latency accesses -from the CPU, high bandwidth accesses from the GPU and bounded latency -accesses from real-time devices such as the display. - -It has two multi-core CPU clusters, each with 4 identical cores (One -Cortex-A57 cluster and one Cortex-A53 cluster). Each cluster has its own -L2 cache. Both clusters are ARMv8 compliant platforms. In addition the -Tx1 has an ARM7 shadow Co-processor. - -The seL4 kernel has a limited port to the TX1 which supports the SoC -only in 64-bit mode. SMP, SMMU, Hyp-mode, etc are not supported by the -current port of the seL4 kernel to the TX1. - -The stock TX1 comes with support for booting using DFU, using an SD-card -or by copying the OS you would like to boot onto the internal 15 GiB USB -mass storage that comes with the TX1. - -Unfortunately the stock U-boot that comes with the TX1 does not support -TFTP-boot over the Ethernet port. You can get U-boot to support the -TX1's Ethernet driver and enable TFTP-boot, but this is beyond the scope -of this article since it entails compiling a custom U-boot and then -flashing it onto the board. - -## Building seL4test - -{% include sel4test.md %} - -The TX1 also supports AArch32 mode. If you choose to build the AArch32 kernel, -please be sure to pass `-DAARCH32=1` instead of `-DAARCH64=1`. - -## Booting via TFTP - Unfortunately the stock U-boot that comes with -the TX1 does not support TFTP because -[it does not come with an ethernet driver](https://devtalk.nvidia.com/default/topic/962946/tx1-pxe-boot/), but if you so choose, it -seems that it is possible to recomplile u-boot with support for the -ethernet driver, and then flash your custom U-boot onto your TX1. -Instructions on how to do this are not included here. - -## Booting via DFU - -To boot via DFU, attach the usb-mini end of a USB cable to the USB-mini -port on the TX1. Then plug in the power supply for the TX1 and power it -on. When the TX1 is powered on, pay attention to the text being printed -out so that you can stop the boot process at the U-boot command prompt. -When you have successfully got to the U-boot command prompt, enter the -following: -``` -setenv dfu_alt_info "kernel ram 0x82000000 0x1000000" -setenv bootcmd_dfu "dfu 0 ram 0; go 0x82000000" -saveenv -``` - -To make U-boot enter its DFU server mode now, just type: -run bootcmd_dfu. U-boot should sit still waiting for a kernel image to -be uploaded. Now you should open up a new terminal on your PC, and type -the following: -``` -dfu-util --device 0955:701a -a kernel -D /sel4test-driver-image-arm-tx1 -``` - -You may need to give dfu-util root privileges. If dfu-util is unable to -find the TX1 device, try unplugging and replugging in the USB mini-cable -that connects your PC to the TX1. - -## Booting via SD Card - -Get an SD card and format it with either FAT32, EXT2 or EXT4. Then build -seL4test, or any of the other seL4 projects. The resulting image file -should be placed inside of /images within the build directory. Take that -image file, and copy it to the root folder of the SD card you intend to -use with your TX1. - -Insert this SD card into your TX1 and then power on the TX1, and drop -into the U-boot command prompt. When you're at the prompt, please type -the following: - -For FAT32: -``` -fatload mmc 1 0x82000000 sel4test-driver-image-arm-tx1 -go 0x82000000 -``` - -For EXT2: -``` -ext2load mmc 1 0x82000000 sel4test-driver-image-arm-tx1 -go 0x82000000 -``` - -For EXT4: -``` -ext4load mmc 1 0x82000000 sel4test-driver-image-arm-tx1 -go 0x82000000 -``` - -## Internal 15 GiB USB mass storage - -Booting off the internal USB mass storage is almost the same as booting -off the SD card, but in particular, you should do something along the -lines of: - -Attach a USB mini cable to the mini-USB port on the TX1, and the other -end of the cable to your PC. Then power on the TX1 and drop into the -U-boot command line, and do the following: - -``` -ums mmc 0 -``` - -Your PC should now show that a new USB mass storage device has been -connected. Copy the seL4 image into the root directory of this mass -storage device, then unmount it and remove it safely. Then go back to -the U-boot command line and press Ctrl+C to exit the mass-storage -server. Then, type the following, depending on the filesystem type that -you formatted the internal mass storage device to (or if you didn't -personally format it, then whatever filesystem already existed on the -internal mass storage): - -For FAT32: -``` -fatload mmc 0 0x82000000 sel4test-driver-image-arm-tx1 -go 0x82000000 -``` - -For EXT2: -``` -ext2load mmc 0 0x82000000 sel4test-driver-image-arm-tx1 -go 0x82000000 -``` - -For EXT4: -``` -ext4load mmc 0 0x82000000 sel4test-driver-image-arm-tx1 -go 0x82000000 -``` diff --git a/Hardware/odroidx.html b/Hardware/odroidx.html new file mode 100644 index 00000000000..f136497cae6 --- /dev/null +++ b/Hardware/odroidx.html @@ -0,0 +1,759 @@ + + + + + + + Odroid-X | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Odroid-X

+ +
+
+ + Important +
+
+ +

This board is no longer supported by seL4.

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform OdroidX
Architecture ARMv7A
System-on-chip Exynos4412
CPU Cortex-A9
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + +
Proof configsARM
seL4 CMake platform nameexynos4
Contributed by Data61
+ +

 

+ +
+
+ + Note +
+
+ +

This board is discontinued by the manufacturer. The instructions here are +provided to keep existing setups working. See support for other more recent +Odroid boards on Supported platforms.

+ +
+
+ +

Client setup

+ +

Hardware requirements:

+ +
    +
  1. 5V power supply
    2. +
  2. RS232 or USB to UART converter
    3. +
  3. USB OTG cable
    4. +
+ +
+
+ + Note +
+
+ +

The USB-UART converter that is shipped with the board requires a +Linux kernel version > 3.2

+ +
+
+ +

Serial port setup

+ +

Open minicom on /dev/ttyUSB* and set the serial port settings to: 115200N1

+ +
    +
  • 115200bps
    • +
  • parity-none
    • +
  • 1 stop bit
    • +
+ +

udev

+ +

You may also like to set up a udev rule for Fastboot:

+ +
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="0002", MODE="660", GROUP="dialout"
+
+ +

U-Boot

+ +

U-Boot must reside at a magical offset in a special partition of the SD +card. To copy U-Boot and the other boot loaders to the SD card:

+ +
cd sd_fusesudo
+./sd_fusing_4412.sh /dev/sdx
+
+ +

seL4 Image file preparation

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=exynos4 -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

The seL4 image file must be converted +into a U-Boot application file. The first step is to strip the elf file +into a binary file. Next we use mkimage to create the image.

+ +
sudo apt-get install uboot-mkimage
+INPUT_FILE=images/sel4test-image-arm-exynos4
+OUTPUT_FILE=sel4-uImage
+mkimage -a 0x48000000 -e 0x48000000 -C none -A arm -T kernel -O qnx -d $INPUT_FILE $OUTPUT_FILE
+
+ +

The reason we choose QNX is because we exploit the fact that, like seL4, +QNX expects to be ELF-loaded. The alternative is to convert our ELF file +into a binary file using objcopy.

+ +

Booting

+ +

Follow these steps to boot your program:

+ +
    +
  1. Connect the USB cable between the ODROID and the client
    2. +
  2. Connect the UART converter between the ODROID and the client
    3. +
  3. Insert your SD card into the ODROID
    4. +
  4. Connect the 5V power supply
    5. +
  5. Open minicom
    6. +
  6. Hold the power button for 3 seconds
    7. +
  7. In minicom, press a key to stop the auto boot process or hold the +user button on the board during the boot process
    8. +
+ +

To boot using fastboot:

+ +
    +
  1. +

    At the u-boot prompt, type fastboot

    +
    2. +
  2. +

    On the client machine, run sudo fastboot devices to ensure that the device +has been recognised. The device should have the label SMDKEXYNOS-01. +Note that fastboot fails silently if you do not have permissions to access +the device. In that case, try running with sudo.

    +
    3. +
  3. +

    On the client machine, run fastboot boot sel4-uImage

    +
    4. +
+ +

To boot from mmc:

+ +
    +
  1. At the U-Boot prompt type +fatload mmc 0:2 0x42000000 <filename> bootm 0x42000000
    2. +
+ +

References

+ +

https://wiki.postmarketos.org/wiki/Samsung_Exynos_4

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/odroidx.md b/Hardware/odroidx.md deleted file mode 100644 index 087a4b36ec7..00000000000 --- a/Hardware/odroidx.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -archive: true -arm_hardware: true -cmake_plat: exynos4 -xcompiler_arg: -DAARCH32=1 -platform: OdroidX -arch: ARMv7A -virtualization: false -iommu: false -soc: Exynos4412 -cpu: Cortex-A9 -verification: [ARM] -Contrib: Data61 -Maintained: False -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Odroid-X - -{% include hw-info.html %} - -  - -{% include note.html %} -This board is discontinued by the manufacturer. The instructions here are -provided to keep existing setups working. See support for other more recent -Odroid boards on [Supported platforms](./). -{% include endnote.html %} - -## Client setup - -### Hardware requirements: - -1. 5V power supply -1. RS232 or USB to UART converter -1. USB OTG cable - -{% include note.html %} -The USB-UART converter that is shipped with the board requires a -Linux kernel version > 3.2 -{% include endnote.html %} - -### Serial port setup - -Open minicom on `/dev/ttyUSB*` and set the serial port settings to: `115200N1` - -- 115200bps -- parity-none -- 1 stop bit - -### udev - -You may also like to set up a udev rule for Fastboot: - -```none -SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="0002", MODE="660", GROUP="dialout" -``` - -### U-Boot - -U-Boot must reside at a magical offset in a special partition of the SD -card. To copy U-Boot and the other boot loaders to the SD card: - -```bash -cd sd_fusesudo -./sd_fusing_4412.sh /dev/sdx -``` - -## seL4 Image file preparation - -{% include sel4test.md %} - -The seL4 image file must be converted -into a U-Boot application file. The first step is to strip the elf file -into a binary file. Next we use mkimage to create the image. - -```bash -sudo apt-get install uboot-mkimage -INPUT_FILE=images/sel4test-image-arm-exynos4 -OUTPUT_FILE=sel4-uImage -mkimage -a 0x48000000 -e 0x48000000 -C none -A arm -T kernel -O qnx -d $INPUT_FILE $OUTPUT_FILE -``` - -The reason we choose QNX is because we exploit the fact that, like seL4, -QNX expects to be ELF-loaded. The alternative is to convert our ELF file -into a binary file using objcopy. - -## Booting - -Follow these steps to boot your program: - - 1. Connect the USB cable between the ODROID and the client - 2. Connect the UART converter between the ODROID and the client - 3. Insert your SD card into the ODROID - 4. Connect the 5V power supply - 5. Open minicom - 6. Hold the power button for 3 seconds - 7. In minicom, press a key to stop the auto boot process or hold the - user button on the board during the boot process - -To boot using fastboot: - - 1. At the u-boot prompt, type fastboot - - 2. On the client machine, run sudo fastboot devices to ensure that the device - has been recognised. The device should have the label `SMDKEXYNOS-01`. - Note that fastboot fails silently if you do not have permissions to access - the device. In that case, try running with `sudo`. - - 3. On the client machine, run fastboot boot sel4-uImage - -To boot from mmc: - - 1. At the U-Boot prompt type - `fatload mmc 0:2 0x42000000 bootm 0x42000000` - -## References - - diff --git a/Hardware/platforms.json b/Hardware/platforms.json index 949804bf5a6..cf5e90f10a1 100644 --- a/Hardware/platforms.json +++ b/Hardware/platforms.json @@ -1,30 +1,49 @@ ---- -layout: null -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 International ---- - [ [ "Arm", [ -{%- assign sorted = site.pages | sort: 'platform' %} -{%- for page in sorted %} -{%- if page.arm_hardware and page.Maintained %} - "{{ page.platform }}"{% unless forloop.last %},{% endunless %} -{%- endif %} -{%- endfor %} + "Avnet MaaXBoard", + "BeagleBoard", + "BeagleBone Black / Blue", + "Jetson TK1", + "Odroid-C2", + "Odroid-C4", + "OdroidXU", + "OdroidXU4", + "QEMU Arm Virt", + "ROCKPro64", + "Raspberry Pi 3-b", + "Raspberry Pi 4B", + "Rock3b", + "Sabre Lite", + "TK1-SOM", + "TQMa8XQP 1GB", + "TX1", + "TX2", + "Ultra96v2 Evaluation Kit", + "Zynq ZCU106 Evaluation Kit", + "Zynq ZCU102 Evaluation Kit", + "Zynq-7000 ZC706 Evaluation Kit", + "i.MX8M Mini", + "i.MX8M Plus", + "i.MX8M Quad", + "i.MX93 EVK" ] ], [ "RISC-V", [ -{%- assign sorted = site.pages | sort: 'platform' %} -{%- for page in sorted %} -{%- if page.riscv_hardware and page.Maintained %} - "{{ page.platform }}"{% unless forloop.last %},{% endunless %} -{%- endif %} -{%- endfor %} + "Ariane", + "Banana Pi BPI-F3", + "Cheshire", + "HiFive Premier P550", + "HiFive Unleashed", + "Microchip PolarFire Icicle Kit", + "Pine64 Star64", + "QEMU RISC-V", + "Rocketchip", + "Rocketchip", + "Spike", ] ], [ diff --git a/Hardware/polarfire.html b/Hardware/polarfire.html new file mode 100644 index 00000000000..020cf472ce2 --- /dev/null +++ b/Hardware/polarfire.html @@ -0,0 +1,708 @@ + + + + + + + Microchip PolarFire Icicle Kit | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microchip PolarFire Icicle Kit

+ +

Polarfire Icicle Kit is a RISC-V development board by Microchip. Check +here for details.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Microchip PolarFire Icicle Kit
Architecture RV64IMAC, RV64GC
System-on-chip PolarFire SoC FPGA
CPU U54-MC, E51
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform namepolarfire
Contributed by DornerWorks
Maintained by DornerWorks
+ +

Microchip maintains online material, including designs and documentation +here.

+ +

Additional documentation and resources can be found on the polarfire-soc github +here.

+ +

Building

+

seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=polarfire -DSel4testAllowSettingsOverride=True -DElfloaderImage=binary -DKernelVerificationBuild=OFF
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Converting to a u-boot uImage:

+
mkimage -A riscv -O linux -T kernel -C none -a 0x80000000 -e 0x80000000 -n sel4test -d \
+images/sel4test-driver-image-riscv-polarfire images/seL4-uImage
+cp kernel/kernel.dtb images/
+
+ +

Hart Software Services

+ +

Install the SoftConsole software development environment from Microchip +here. +The following instructions are based on SoftConsole v2022.2

+ +
    +
  1. Clone the Hart Software Services + 
    git clone https://github.com/polarfire-soc/hart-software-services
+
    +
    2. +
  2. +

    Open SoftConsole and import a project from the newly cloned hart-software-services repo.

    +
    3. +
  3. Build the project with the project defaults.
    4. +
+ +

hss-payload-generator

+
git clone https://github.com/polarfire-soc/hart-software-services
+cd hart-software-services/tools/hss-payload-generator
+make
+
+ +

This generates a hss-payload-generator ELF.

+ +

U-Boot

+
git clone https://github.com/polarfire-soc/u-boot
+cd u-boot
+CROSS_COMPILE=riscv64-linux-gnu- ARCH=riscv make microchip_mpfs_icicle_defconfig
+CROSS_COMPILE=riscv64-linux-gnu- ARCH=riscv make
+
+ +

This generates a u-boot-dtb.bin binary.

+ +

In order boot u-boot from the HSS, the u-boot-dtb.bin needs to be packaged as an HSS payload using +the hss-payload-generator tool but first a payload configuration yaml file needs to be created:

+ +
#
+# HSS Payload Generator - U-Boot Payload
+#
+
+set-name: 'PolarFire-SoC-HSS::U-Boot'
+
+hart-entry-points: {u54_1: '0x1000200000', u54_2: '0x1000200000', u54_3: '0x1000200000', u54_4: '0x1000200000'}
+
+payloads:
+  u-boot.bin: {exec-addr: '0x1000200000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_s }
+
+
+ +

The payload can then be generated using this yaml file.

+
./hss-payload-generator -c u-boot.yaml uboot-payload.bin
+
+ +

This generates a uboot-payload.bin binary.

+ +

Booting via SD card

+ +

Prepare the SD card

+
sudo sgdisk -Zo --new=1:2048:2099199 --typecode=1:0700 \
+     --new=2:2099200:4196351 --typecode=2:EF02 /dev/sdX
+sudo dd if=images/uboot-payload.bin of=/dev/sdX2
+sudo mkfs.vfat -F16 /dev/sdX1
+sudo mount /dev/sdX1 /mnt
+sudo cp images/seL4-uImage /mnt
+sudo cp images/kernel.dtb /mnt
+
+ +

Insert the SD card into the Icicle Kit then power on the board, and drop into the u-boot +prompt. When you’re at the prompt, type the following:

+
fatload mmc 0 0x1000200000 seL4-uImage
+fatload mmc 0 0x1020200000 kernel.dtb
+bootm 0x1000200000 - 0x1020200000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/polarfire.md b/Hardware/polarfire.md deleted file mode 100644 index 96fa62dfcad..00000000000 --- a/Hardware/polarfire.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: polarfire -xcompiler_arg: -DSel4testAllowSettingsOverride=True -DElfloaderImage=binary -DKernelVerificationBuild=OFF -platform: Microchip PolarFire Icicle Kit -arch: RV64IMAC, RV64GC -virtualization: false -iommu: false -simulation_target: false -verification: [] -Contrib: 'DornerWorks' -Maintained: 'DornerWorks' -soc: PolarFire SoC FPGA -cpu: U54-MC, E51 -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Microchip PolarFire Icicle Kit - -Polarfire Icicle Kit is a RISC-V development board by Microchip. Check -[here](https://www.microchip.com/en-us/development-tool/MPFS-ICICLE-KIT-ES) for details. - -{% include hw-info.html %} - -Microchip maintains online material, including designs and documentation -[here](https://www.microchip.com/en-us/products/fpgas-and-plds/system-on-chip-fpgas/polarfire-soc-fpgas#documentation). - -Additional documentation and resources can be found on the polarfire-soc github -[here](https://github.com/polarfire-soc/). - -## Building -### seL4test - -{% include sel4test.md %} - -Converting to a u-boot uImage: -```bash -mkimage -A riscv -O linux -T kernel -C none -a 0x80000000 -e 0x80000000 -n sel4test -d \ -images/sel4test-driver-image-riscv-polarfire images/seL4-uImage -cp kernel/kernel.dtb images/ -``` - -### Hart Software Services - -Install the SoftConsole software development environment from Microchip -[here](https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/soc-fpga/softconsole). -The following instructions are based on SoftConsole v2022.2 - -1. Clone the Hart Software Services -```bash -git clone https://github.com/polarfire-soc/hart-software-services -``` - -2. Open SoftConsole and import a project from the newly cloned `hart-software-services` repo. - -3. Build the project with the project defaults. - -### hss-payload-generator -```bash -git clone https://github.com/polarfire-soc/hart-software-services -cd hart-software-services/tools/hss-payload-generator -make -``` - -This generates a `hss-payload-generator` ELF. - -### U-Boot -```bash -git clone https://github.com/polarfire-soc/u-boot -cd u-boot -CROSS_COMPILE=riscv64-linux-gnu- ARCH=riscv make microchip_mpfs_icicle_defconfig -CROSS_COMPILE=riscv64-linux-gnu- ARCH=riscv make -``` - -This generates a `u-boot-dtb.bin` binary. - -In order boot u-boot from the HSS, the `u-boot-dtb.bin` needs to be packaged as an HSS payload using -the hss-payload-generator tool but first a payload configuration yaml file needs to be created: - -```yaml -# -# HSS Payload Generator - U-Boot Payload -# - -set-name: 'PolarFire-SoC-HSS::U-Boot' - -hart-entry-points: {u54_1: '0x1000200000', u54_2: '0x1000200000', u54_3: '0x1000200000', u54_4: '0x1000200000'} - -payloads: - u-boot.bin: {exec-addr: '0x1000200000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_s } - -``` - -The payload can then be generated using this yaml file. -```bash -./hss-payload-generator -c u-boot.yaml uboot-payload.bin -``` - -This generates a `uboot-payload.bin` binary. - -## Booting via SD card - -Prepare the SD card -```sh -sudo sgdisk -Zo --new=1:2048:2099199 --typecode=1:0700 \ - --new=2:2099200:4196351 --typecode=2:EF02 /dev/sdX -sudo dd if=images/uboot-payload.bin of=/dev/sdX2 -sudo mkfs.vfat -F16 /dev/sdX1 -sudo mount /dev/sdX1 /mnt -sudo cp images/seL4-uImage /mnt -sudo cp images/kernel.dtb /mnt -``` - -Insert the SD card into the Icicle Kit then power on the board, and drop into the u-boot -prompt. When you're at the prompt, type the following: -```bash -fatload mmc 0 0x1000200000 seL4-uImage -fatload mmc 0 0x1020200000 kernel.dtb -bootm 0x1000200000 - 0x1020200000 -``` diff --git a/Hardware/qemu-arm-virt.html b/Hardware/qemu-arm-virt.html new file mode 100644 index 00000000000..44a0306cbaf --- /dev/null +++ b/Hardware/qemu-arm-virt.html @@ -0,0 +1,636 @@ + + + + + + + QEMU Arm virtual platform | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

QEMU Arm virtual platform

+ +

This is a simulation-only target for running the Arm version of seL4 on the +QEMU simulator with the virt platform.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform QEMU Arm Virt
Simulation platform yes
Architecture ARMv7A, ARMv8A
System-on-chip virt
CPU Multiple
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs +N/A +
Proof configsN/A
seL4 CMake platform nameqemu-arm-virt
Contributed by Data61
Maintained by seL4 Foundation
+ +

Supported Configurations

+ +

The default CPU for simulation on qemu-arm-virt is Cortex A53. If +KernelSel4Arch is set to aarch32 or arm_hyp, the default is Cortex A15.

+ +

Supported values for the optional build parameter ARM_CPU are: cortex-a7, +cortex-a15, cortex-a53, cortex-a57, and cortex-a72.

+ +

Running seL4 test

+ +

See the machine setup instructions for how to install build dependencies.

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=qemu-arm-virt -DSIMULATION=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+./simulate
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/qemu-arm-virt.md b/Hardware/qemu-arm-virt.md deleted file mode 100644 index f34d23cf345..00000000000 --- a/Hardware/qemu-arm-virt.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -arm_hardware: true -simulation_target: true -simulation_only: true -xcompiler_arg: '-DSIMULATION=1' -cmake_plat: qemu-arm-virt -platform: QEMU Arm Virt -arch: ARMv7A, ARMv8A -virtualization: true -iommu: false -soc: virt -cpu: Multiple -verification: [] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. ---- - -# QEMU Arm virtual platform - -This is a simulation-only target for running the Arm version of seL4 on the -[QEMU] simulator with the [virt] platform. - -{% include hw-info.html %} - -## Supported Configurations - -The default CPU for simulation on `qemu-arm-virt` is Cortex A53. If -`KernelSel4Arch` is set to `aarch32` or `arm_hyp`, the default is Cortex A15. - -Supported values for the optional build parameter `ARM_CPU` are: `cortex-a7`, -`cortex-a15`, `cortex-a53`, `cortex-a57`, and `cortex-a72`. - -## Running seL4 test - -See the [machine setup] instructions for how to install build dependencies. - -{% include sel4test.md %} - -[QEMU]: https://www.qemu.org -[virt]: https://www.qemu.org/docs/master/system/arm/virt.html -[machine setup]: {{ '/projects/buildsystem/host-dependencies.html' | relative_url }} diff --git a/Hardware/qemu-riscv-virt.html b/Hardware/qemu-riscv-virt.html new file mode 100644 index 00000000000..3c09fc4161c --- /dev/null +++ b/Hardware/qemu-riscv-virt.html @@ -0,0 +1,630 @@ + + + + + + + QEMU RISC-V virtual platform | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

QEMU RISC-V virtual platform

+ +

This is a simulation-only target for running the RISC-V version of seL4 on the +QEMU simulator with the virt platform.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform QEMU RISC-V
Simulation platform yes
Architecture RV32GC, RV64IMAC
System-on-chip virt
CPU rv32, rv64
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs +N/A +
Proof configsN/A
seL4 CMake platform nameqemu-riscv-virt
Contributed by Data61
Maintained by seL4 Foundation
+ +

Supported Configurations

+ +

The values riscv64 and riscv32 are supported for KernelSel4Arch.

+ +

Running seL4 test

+ +

See the machine setup instructions for how to install build dependencies.

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=qemu-riscv-virt -DSIMULATION=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+./simulate
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/qemu-riscv-virt.md b/Hardware/qemu-riscv-virt.md deleted file mode 100644 index a5f92b8225d..00000000000 --- a/Hardware/qemu-riscv-virt.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -riscv_hardware: true -simulation_target: true -simulation_only: true -xcompiler_arg: '-DSIMULATION=1' -cmake_plat: qemu-riscv-virt -platform: QEMU RISC-V -arch: RV32GC, RV64IMAC -virtualization: false -iommu: false -soc: virt -cpu: rv32, rv64 -verification: [] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. ---- - -# QEMU RISC-V virtual platform - -This is a simulation-only target for running the RISC-V version of seL4 on the -[QEMU] simulator with the [virt] platform. - -{% include hw-info.html %} - -## Supported Configurations - -The values `riscv64` and `riscv32` are supported for `KernelSel4Arch`. - -## Running seL4 test - -See the [machine setup] instructions for how to install build dependencies. - -{% include sel4test.md %} - -[QEMU]: https://www.qemu.org -[virt]: https://www.qemu.org/docs/master/system/riscv/virt.html -[machine setup]: {{ '/projects/buildsystem/host-dependencies.html' | relative_url }} diff --git a/Hardware/rock3b.html b/Hardware/rock3b.html new file mode 100644 index 00000000000..a320eb16891 --- /dev/null +++ b/Hardware/rock3b.html @@ -0,0 +1,718 @@ + + + + + + + Rock3b | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Rock3b

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Rock3b
Architecture ARMv8A, AArch64
System-on-chip RK3568 quad-core
CPU Cortex-A55 Quad 2.0 GHz
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform namerk3568
Contributed by UNSW
Maintained by UNSW
+ +

Obtaining TPL

+ +

Since some parts of the board are proprietary and need custom binaries, Rockchip provides the binaries that you need to download and include in both the TF-A and U-Boot builds. To obtain them simply execute:

+
git clone --depth 1 https://github.com/rockchip-linux/rkbin
+
+ +

Compiling TF-A

+ +

ARM Trusted Firmware-A is necessary for the board to boot up properly. It is responsible for setting up all secure peripherals and pieces of the system that the regular user won’t have access to. +To build it execute:

+
git clone --depth 1 https://github.com/TrustedFirmware-A/trusted-firmware-a.git
+cd trusted-firmware-a
+make realclean
+make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3358
+cd ..
+
+ +

Compiling U-Boot

+ +

In order to build U-Boot for the Rock3b, we need to first download or build the run the following commands:

+
git clone https://github.com/u-boot/u-boot.git u-boot
+cd u-boot
+make CROSS_COMPILE=aarch64-linux-gnu- rock-3b-rk3568_defconfig
+make CROSS_COMPILE=aarch64-linux-gnu- BL31=../trusted-firmware-a/build/rk3568/release/bl31/bl31.elf ROCKCHIP_TPL=../rkbin/bin/rk35/rk3568_ddr_1560MHz_v1.13.bin
+
+ +

In the u-boot directory you should now see the U-Boot image u-boot.bin indicating that U-Boot has successfully compiled.

+ +

More information regarding U-Boot support for the Rock3b can be found here.

+ +

Flashing the U-Boot on the SD-card

+ +

To write an image that boots from a SD card (check your device path!):

+ +
sudo dd if=u-boot.bin of=/dev/<device_path> seek=64
+sync
+
+ +

Flashing the U-Boot on the SPI Flash

+ +

If you want to boot from SPI Flash, you have to put the U-Boot image there first.

+ +

Preparation of the SD-card

+ +

Prepare the SD-card by plugging it into your PC and running:

+ +
DEV=/dev/<your device name>
+
+sudo wipefs -a "$DEV"
+
+# Partition table + partitions (start at 16MiB to avoid overlapping bootloader areas)
+sudo parted -s "$DEV" mklabel gpt
+sudo parted -s "$DEV" mkpart BOOT fat32 16MiB 256MiB
+sudo parted -s "$DEV" mkpart ROOT ext4 256MiB 100%
+
+# Format
+sudo mkfs.vfat -F 32 -n BOOT ${DEV}p1
+sudo mkfs.ext4 -F -L ROOT ${DEV}p2
+
+# Flash the non-SPI image onto SD-card
+sudo dd if=u-boot-rockchip.bin of=/dev/sda seek=64
+
+# Copy the SPI image onto the ext4 partition
+sudo mkdir -p sd/
+sudo mount ${DEV}p2 sd/
+sudo cp u-boot-rockchip-spi.bin sd/
+sync
+sudo umount sd/
+
+ +

Then insert the SD-card into the Rock3b and run following there:

+
mmc list
+# ensure you can see you SD-card here
+sf probe
+# ensure you can see the flash registering itself here
+ls mmc 1:2
+# ensure you can see the u-boot-rockchip-spi.bin here
+
+load mmc 1:2 $kernel_addr_r u-boot-rockchip-spi.bin
+
+sf update $fileaddr 0 $filesize
+
+ +

Poweroff the board, eject the SD-card and observe the board booting from flash.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=rk3568 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Running seL4test

+ +

You have two options of running the seL4test, either run it from the SD-card’s partition or using TFTP. Here the option of running it via TFTP is described.

+ +

This assumes the Ethernet cable connected to the board and having a DHCP and TFTP servers running. When the board boots, enter its console and simply type dhcp to establish the connection and then copy over your image from the TFTP server by running:

+ +
tftp 0x02000000 sel4test-driver-image-arm-rk3568
+go 0x02000000
+
+ +

This will launch seL4tests.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/rock3b.md b/Hardware/rock3b.md deleted file mode 100644 index d32211adbe0..00000000000 --- a/Hardware/rock3b.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -arm_hardware: true -cmake_plat: rk3568 -xcompiler_arg: -DAARCH64=1 -platform: Rock3b -arch: ARMv8A, AArch64 -virtualization: true -iommu: false -soc: RK3568 quad-core -cpu: Cortex-A55 Quad 2.0 GHz -verification: [AARCH64] -Contrib: "UNSW" -Maintained: "UNSW" -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. ---- - -# Rock3b - -{% include hw-info.html %} - -## Obtaining TPL - -Since some parts of the board are proprietary and need custom binaries, Rockchip provides the binaries that you need to download and include in both the TF-A and U-Boot builds. To obtain them simply execute: -```bash -git clone --depth 1 https://github.com/rockchip-linux/rkbin -``` - -## Compiling TF-A - -ARM Trusted Firmware-A is necessary for the board to boot up properly. It is responsible for setting up all secure peripherals and pieces of the system that the regular user won't have access to. -To build it execute: -```bash -git clone --depth 1 https://github.com/TrustedFirmware-A/trusted-firmware-a.git -cd trusted-firmware-a -make realclean -make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3358 -cd .. -``` - -## Compiling U-Boot - -In order to build U-Boot for the Rock3b, we need to first download or build the run the following commands: -```bash -git clone https://github.com/u-boot/u-boot.git u-boot -cd u-boot -make CROSS_COMPILE=aarch64-linux-gnu- rock-3b-rk3568_defconfig -make CROSS_COMPILE=aarch64-linux-gnu- BL31=../trusted-firmware-a/build/rk3568/release/bl31/bl31.elf ROCKCHIP_TPL=../rkbin/bin/rk35/rk3568_ddr_1560MHz_v1.13.bin -``` - -In the `u-boot` directory you should now see the U-Boot image `u-boot.bin` indicating that U-Boot has successfully compiled. - -More information regarding U-Boot support for the Rock3b can be found [here](https://docs.u-boot.org/en/latest/board/rockchip/rockchip.html). - -## Flashing the U-Boot on the SD-card - -To write an image that boots from a SD card (check your device path!): - -```bash -sudo dd if=u-boot.bin of=/dev/ seek=64 -sync -``` - -## Flashing the U-Boot on the SPI Flash - -If you want to boot from SPI Flash, you have to put the U-Boot image there first. - -### Preparation of the SD-card - -Prepare the SD-card by plugging it into your PC and running: - -```bash -DEV=/dev/ - -sudo wipefs -a "$DEV" - -# Partition table + partitions (start at 16MiB to avoid overlapping bootloader areas) -sudo parted -s "$DEV" mklabel gpt -sudo parted -s "$DEV" mkpart BOOT fat32 16MiB 256MiB -sudo parted -s "$DEV" mkpart ROOT ext4 256MiB 100% - -# Format -sudo mkfs.vfat -F 32 -n BOOT ${DEV}p1 -sudo mkfs.ext4 -F -L ROOT ${DEV}p2 - -# Flash the non-SPI image onto SD-card -sudo dd if=u-boot-rockchip.bin of=/dev/sda seek=64 - -# Copy the SPI image onto the ext4 partition -sudo mkdir -p sd/ -sudo mount ${DEV}p2 sd/ -sudo cp u-boot-rockchip-spi.bin sd/ -sync -sudo umount sd/ -``` - -Then insert the SD-card into the Rock3b and run following there: -```bash -mmc list -# ensure you can see you SD-card here -sf probe -# ensure you can see the flash registering itself here -ls mmc 1:2 -# ensure you can see the u-boot-rockchip-spi.bin here - -load mmc 1:2 $kernel_addr_r u-boot-rockchip-spi.bin - -sf update $fileaddr 0 $filesize -``` - -Poweroff the board, eject the SD-card and observe the board booting from flash. - -## Building seL4test - -{% include sel4test.md %} - -## Running seL4test - -You have two options of running the seL4test, either run it from the SD-card's partition or using TFTP. Here the option of running it via TFTP is described. - -This assumes the Ethernet cable connected to the board and having a DHCP and TFTP servers running. When the board boots, enter its console and simply type `dhcp` to establish the connection and then copy over your image from the TFTP server by running: - -```bash -tftp 0x02000000 sel4test-driver-image-arm-rk3568 -go 0x02000000 -``` - -This will launch seL4tests. diff --git a/Hardware/rocketchip-zcu102.html b/Hardware/rocketchip-zcu102.html new file mode 100644 index 00000000000..0a599484fcb --- /dev/null +++ b/Hardware/rocketchip-zcu102.html @@ -0,0 +1,771 @@ + + + + + + + Rocketchip FPGA mapped to Zynq ZCU102 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Rocketchip FPGA mapped to Zynq ZCU102

+ +

This rocketchip implementation will run on the ZCU102 FPGA fabric.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Rocketchip
Architecture RV64IMAFDC
CPU Rocket
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform namerocketchip-zcu102
Contributed by DornerWorks
Maintained by DornerWorks
+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=rocketchip-zcu102 -DRISCV64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Updating OpenSBI

+ +

In order to run on the ZCU102, the OpenSBI platform must be changed from generic. +DornerWorks has forked a version of +OpenSBI from the bao-project that supports the ZCU104 platform, which is nearly identical to the +ZCU102. Perform the following commands in the seL4 codebase to set the OpenSBI target to +rocket-fpga-zcu104.

+ +
cd tools/opensbi
+git remote add dornerworks https://github.com/dornerworks/opensbi/
+git fetch dornerworks
+git checkout dornerworks/bao/rocket
+
+ +

Building the Rocketchip Bitstream

+ +

Setting up the Repo

+ +

The following repository contains patches that will add virtualization support via the h-extensions +to the rocketchip. Clone the repo with the following command

+ +
git clone https://github.com/dornerworks/Vivado-Prebuilts
+git clone https://github.com/dornerworks/bao-demos -b rocket rocketchip-h-extend
+cd rocketchip-h-extend
+
+ +

Export the following variables for the scripts to work correctly. Please note that order is also +important since some of these variables use previous variables in their declaration.

+ +
export PLATFORM=rocket-fpga-zcu104
+export DW_VIVADO_PREBUILTS=/PATH/TO/vivado-prebuilts
+export BAO_DEMOS=/PATH/TO/rocketchip-h-extend
+export BAO_DEMOS_WRKDIR=$BAO_DEMOS/wrkdir
+export BAO_DEMOS_WRKDIR_SRC=$BAO_DEMOS_WRKDIR/srcs
+export BAO_DEMOS_WRKDIR_PLAT=$BAO_DEMOS_WRKDIR/imgs/$PLATFORM
+export BAO_DEMOS_CHIPYARD=$BAO_DEMOS_WRKDIR_SRC/chipyard
+export BAO_DEMOS_ROCKETCHIP=$BAO_DEMOS_CHIPYARD/generators/rocket-chip
+export BAO_DEMOS_VIVADO_SCRIPTS=$BAO_DEMOS/platforms/$PLATFORM/scripts
+export BAO_DEMOS_ROCKET_CONFIG=RocketHypConfig$(echo $PLATFORM | awk '{split($0,A,"-"); print A[length(A)]}')
+export BAO_DEMOS_OPENSBI=$BAO_DEMOS_WRKDIR_SRC/opensbi
+export ARCH=riscv
+export CROSS_COMPILE=riscv64-unknown-elf-
+export VIVADO_CORES=$(nproc)
+
+mkdir -p $BAO_DEMOS_WRKDIR
+mkdir -p $BAO_DEMOS_WRKDIR_SRC
+
+ +

Generate the SoC Design

+ +

With these variables in place use the following commands to generate the rocketchip design with the +h-extensions enabled:

+ +
git clone https://github.com/ucb-bar/chipyard.git $BAO_DEMOS_CHIPYARD
+cd $BAO_DEMOS_CHIPYARD
+git checkout 64632c8
+./scripts/init-submodules-no-riscv-tools.sh
+git apply $BAO_DEMOS/platforms/$PLATFORM/patches/0001-add-rocket-hyp-fpga-support.patch
+git -C generators/boom apply $BAO_DEMOS/platforms/$PLATFORM/patches/0001-boom-add-usehyp-option.patch
+git -C generators/ariane apply $BAO_DEMOS/platforms/$PLATFORM/patches/0001-ariane-add-usehyp-option.patch
+cd $BAO_DEMOS_ROCKETCHIP
+git remote add hyp https://github.com/dornerworks/rocket-chip.git
+git fetch hyp
+git checkout hyp
+
+ +

Next use the following command to build the bootROM:

+ +
make -C $BAO_DEMOS_CHIPYARD/bootromFPGA
+
+ +

Finally, use the following command to generate the verilog before building the design:

+ +
make -C $BAO_DEMOS_CHIPYARD/sims/vcs verilog SUB_PROJECT=rocket \
+    CONFIG=$BAO_DEMOS_ROCKET_CONFIG
+
+ +

Modifying the scripts

+ +

Before building the design, a few lines in the tcl scripts must be modified in order to ensure we +are building for the ZCU102. Change directory to $BAO_DEMOS_VIVADO_SCRIPTS and modify the switch +statement in env.tcl with the following information.

+ +
    zcu102 {
+        set part xczu9eg-ffvb1156-2-e
+        set board_part xilinx.com:zcu102:part0:3.1
+    }
+
+ +

The board declaration must be changed to ZCU102 with the following line:

+ +
set board zcu102
+
+ +

Building the SoC Design

+ +

Vivado can be used with the generated verilog to build the SoC Design. Ensure that Vivado 2020.2 is +on your path and run the following commands:

+ +
vivado -nolog -nojournal -mode batch -source $BAO_DEMOS_VIVADO_SCRIPTS/create_ip.tcl
+vivado -nolog -nojournal -mode batch -source $BAO_DEMOS_VIVADO_SCRIPTS/create_design.tcl
+vivado -nolog -nojournal -mode batch -source $BAO_DEMOS_VIVADO_SCRIPTS/build.tcl
+
+ +

Prebuilt Rocketchip Bitstreams

+ +

DornerWorks has pre-built a version of the rocketchip with and without the h-extensions +available. The bitsteams, along with the corresponding psu_init.tcl scripts, can be found at the +following repo. This repo also contains a script +to flash the rocketchip onto the ZCU102.

+ +

Booting the Rocketchip

+ +

Use the Xilinx xsct tool to flash the ZCU102. Connect the JTAG and UART ports to your computer. If +using VMWare, ensure that USB3.0 is enabled. Set the ZCU102 to boot via JTAG and power on the board.

+ +

Open a screen session for the ZCU102 with the following command:

+ +
screen /dev/ttyUSB1 115200
+
+ +

Next, ensure the generated seL4 image is in the binary format. This will be the case when the +ElfloaderImage CMake variable is set to binary.

+ +

Finally, flash the ZCU102 with the following command:

+ +
xsct  $BAO_DEMOS_VIVADO_SCRIPTS/deploy.tcl /PATH/TO/BINARY/SEL4/IMAGE
+
+ +

Alternatively, if using the prebuilt bitstream provided by DornerWorks, the Vivado-Prebuilts +repository contains a flash_rocket shell script which can be invoked to flash the ZCU102 with the +prebuilt bitstream.

+ +
cd $DW_VIVADO_PREBUILTS
+source flash_rocket.sh /PATH/TO/BINARY/SEL4/IMAGE
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/rocketchip-zcu102.md b/Hardware/rocketchip-zcu102.md deleted file mode 100644 index 4d90174eec6..00000000000 --- a/Hardware/rocketchip-zcu102.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: rocketchip-zcu102 -xcompiler_arg: -DRISCV64=1 -platform: Rocketchip -arch: RV64IMAFDC -virtualization: false -iommu: false -simulation_target: false -verification: [] -Contrib: 'DornerWorks' -Maintained: 'DornerWorks' -cpu: Rocket -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Rocketchip FPGA mapped to Zynq ZCU102 - -This rocketchip implementation will run on the ZCU102 FPGA fabric. - -{% include hw-info.html %} - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Building seL4test - -{% include sel4test.md %} - -### Updating OpenSBI - -In order to run on the ZCU102, the OpenSBI platform must be changed from `generic`. -[DornerWorks](https://github.com/dornerworks/opensbi/tree/bao/rocket) has forked a version of -OpenSBI from the bao-project that supports the ZCU104 platform, which is nearly identical to the -ZCU102. Perform the following commands in the seL4 codebase to set the OpenSBI target to -`rocket-fpga-zcu104`. - -```sh -cd tools/opensbi -git remote add dornerworks https://github.com/dornerworks/opensbi/ -git fetch dornerworks -git checkout dornerworks/bao/rocket -``` - -## Building the Rocketchip Bitstream - -### Setting up the Repo - -The following repository contains patches that will add virtualization support via the h-extensions -to the rocketchip. Clone the repo with the following command - -```sh -git clone https://github.com/dornerworks/Vivado-Prebuilts -git clone https://github.com/dornerworks/bao-demos -b rocket rocketchip-h-extend -cd rocketchip-h-extend -``` - -Export the following variables for the scripts to work correctly. Please note that order is also -important since some of these variables use previous variables in their declaration. - -```sh -export PLATFORM=rocket-fpga-zcu104 -export DW_VIVADO_PREBUILTS=/PATH/TO/vivado-prebuilts -export BAO_DEMOS=/PATH/TO/rocketchip-h-extend -export BAO_DEMOS_WRKDIR=$BAO_DEMOS/wrkdir -export BAO_DEMOS_WRKDIR_SRC=$BAO_DEMOS_WRKDIR/srcs -export BAO_DEMOS_WRKDIR_PLAT=$BAO_DEMOS_WRKDIR/imgs/$PLATFORM -export BAO_DEMOS_CHIPYARD=$BAO_DEMOS_WRKDIR_SRC/chipyard -export BAO_DEMOS_ROCKETCHIP=$BAO_DEMOS_CHIPYARD/generators/rocket-chip -export BAO_DEMOS_VIVADO_SCRIPTS=$BAO_DEMOS/platforms/$PLATFORM/scripts -export BAO_DEMOS_ROCKET_CONFIG=RocketHypConfig$(echo $PLATFORM | awk '{split($0,A,"-"); print A[length(A)]}') -export BAO_DEMOS_OPENSBI=$BAO_DEMOS_WRKDIR_SRC/opensbi -export ARCH=riscv -export CROSS_COMPILE=riscv64-unknown-elf- -export VIVADO_CORES=$(nproc) - -mkdir -p $BAO_DEMOS_WRKDIR -mkdir -p $BAO_DEMOS_WRKDIR_SRC -``` - -### Generate the SoC Design - -With these variables in place use the following commands to generate the rocketchip design with the -h-extensions enabled: - -```sh -git clone https://github.com/ucb-bar/chipyard.git $BAO_DEMOS_CHIPYARD -cd $BAO_DEMOS_CHIPYARD -git checkout 64632c8 -./scripts/init-submodules-no-riscv-tools.sh -git apply $BAO_DEMOS/platforms/$PLATFORM/patches/0001-add-rocket-hyp-fpga-support.patch -git -C generators/boom apply $BAO_DEMOS/platforms/$PLATFORM/patches/0001-boom-add-usehyp-option.patch -git -C generators/ariane apply $BAO_DEMOS/platforms/$PLATFORM/patches/0001-ariane-add-usehyp-option.patch -cd $BAO_DEMOS_ROCKETCHIP -git remote add hyp https://github.com/dornerworks/rocket-chip.git -git fetch hyp -git checkout hyp -``` - -Next use the following command to build the bootROM: - -```sh -make -C $BAO_DEMOS_CHIPYARD/bootromFPGA -``` - -Finally, use the following command to generate the verilog before building the design: - -```sh -make -C $BAO_DEMOS_CHIPYARD/sims/vcs verilog SUB_PROJECT=rocket \ - CONFIG=$BAO_DEMOS_ROCKET_CONFIG -``` - -### Modifying the scripts - -Before building the design, a few lines in the tcl scripts must be modified in order to ensure we -are building for the ZCU102. Change directory to `$BAO_DEMOS_VIVADO_SCRIPTS` and modify the switch -statement in `env.tcl` with the following information. - -``` - zcu102 { - set part xczu9eg-ffvb1156-2-e - set board_part xilinx.com:zcu102:part0:3.1 - } -``` - -The board declaration must be changed to ZCU102 with the following line: - -``` -set board zcu102 -``` - -### Building the SoC Design - -Vivado can be used with the generated verilog to build the SoC Design. Ensure that Vivado 2020.2 is -on your path and run the following commands: - -```sh -vivado -nolog -nojournal -mode batch -source $BAO_DEMOS_VIVADO_SCRIPTS/create_ip.tcl -vivado -nolog -nojournal -mode batch -source $BAO_DEMOS_VIVADO_SCRIPTS/create_design.tcl -vivado -nolog -nojournal -mode batch -source $BAO_DEMOS_VIVADO_SCRIPTS/build.tcl -``` - -## Prebuilt Rocketchip Bitstreams - -DornerWorks has pre-built a version of the rocketchip with and without the h-extensions -available. The bitsteams, along with the corresponding `psu_init.tcl` scripts, can be found at the -following [repo](https://github.com/dornerworks/Vivado-Prebuilts). This repo also contains a script -to flash the rocketchip onto the ZCU102. - -## Booting the Rocketchip - -Use the Xilinx `xsct` tool to flash the ZCU102. Connect the JTAG and UART ports to your computer. If -using VMWare, ensure that USB3.0 is enabled. Set the ZCU102 to boot via JTAG and power on the board. - - -Open a `screen` session for the ZCU102 with the following command: - -```sh -screen /dev/ttyUSB1 115200 -``` - -Next, ensure the generated seL4 image is in the binary format. This will be the case when the -`ElfloaderImage` CMake variable is set to `binary`. - -Finally, flash the ZCU102 with the following command: - -```sh -xsct $BAO_DEMOS_VIVADO_SCRIPTS/deploy.tcl /PATH/TO/BINARY/SEL4/IMAGE -``` - -Alternatively, if using the prebuilt bitstream provided by DornerWorks, the `Vivado-Prebuilts` -repository contains a `flash_rocket` shell script which can be invoked to flash the ZCU102 with the -prebuilt bitstream. - -```sh -cd $DW_VIVADO_PREBUILTS -source flash_rocket.sh /PATH/TO/BINARY/SEL4/IMAGE -``` diff --git a/Hardware/rocketchip.html b/Hardware/rocketchip.html new file mode 100644 index 00000000000..7395de2daf1 --- /dev/null +++ b/Hardware/rocketchip.html @@ -0,0 +1,638 @@ + + + + + + + Rocketchip FPGA mapped to Zynq ZC706 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Rocketchip FPGA mapped to Zynq ZC706

+ +

The current rocketchip implementation only tested on ZC706 FPGA, it should work +for other Zynq FPGAs. Refer to +https://github.com/ucb-bar/fpga-zynq for +details.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Rocketchip
Architecture RV64IMAFDC
CPU Rocket
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform namerocketchip
Contributed by Data61
Maintained by seL4 Foundation
+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=rocketchip -DRISCV64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/rocketchip.md b/Hardware/rocketchip.md deleted file mode 100644 index 3f9dd82b31f..00000000000 --- a/Hardware/rocketchip.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: rocketchip -xcompiler_arg: -DRISCV64=1 -platform: Rocketchip -arch: RV64IMAFDC -virtualization: false -iommu: false -simulation_target: false -verification: [] -Contrib: Data61 -Maintained: seL4 Foundation -cpu: Rocket -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Rocketchip FPGA mapped to Zynq ZC706 - -The current rocketchip implementation only tested on ZC706 FPGA, it should work -for other Zynq FPGAs. Refer to -[https://github.com/ucb-bar/fpga-zynq](https://github.com/ucb-bar/fpga-zynq) for -details. - -{% include hw-info.html %} - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Building seL4test - -{% include sel4test.md %} diff --git a/Hardware/rockpro64.html b/Hardware/rockpro64.html new file mode 100644 index 00000000000..d2c521d35b7 --- /dev/null +++ b/Hardware/rockpro64.html @@ -0,0 +1,716 @@ + + + + + + + ROCKPro64 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

ROCKPro64

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform ROCKPro64
Architecture ARMv8A, AArch64
System-on-chip RK3399 hexa-core
CPU Cortex-A53 Quad 1.8 GHz
seL4 virtualisation support + +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform namerockpro64
Contributed by Data61
Maintained by seL4 Foundation
+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=rockpro64 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

Flashing the SPI with U-Boot

+ +

WARNING! DO NOT POWER OFF THE DEVICE FOR ANY REASON DURING SPI FLASH! YOU WILL GET A (soft-) BRICKED DEVICE

+ +

The first step is getting U-Boot onto the system. It is recommended, particularly for TFTP boot, to put U-Boot on the SPI flash.

+ +

If you have a “dirty” (any previously used) SPI flash, first:

+
    +
  1. Download https://github.com/sigmaris/u-boot/releases/download/v2020.01-ci/erase_spi.img.gz
    2. +
  2. Write it to an SD card
    3. +
  3. Boot from the SD card (will be done automatically if you don’t have a very weird setup). Once it completes (see this over serial or when white LED becomes stable), remove the SD card, but DO NOT reset.
    4. +
+ +

Then, to flash the actual image:

+
    +
  1. Get https://github.com/sigmaris/u-boot/releases/download/v2020.01-ci/flash_spi.img.gz and write it to an SD card.
    2. +
  2. Put the SD card into the ROCKPro64 and boot. Wait for completion (seen over serial or when white LED becomes stable).
    3. +
  3. Remove the SD card.
    4. +
  4. Reset and observe U-Boot come up.
    5. +
+ +

Compiling u-boot by oneself has not been done and has been left as an exercise to the reader if wanted. HINT: https://github.com/sigmaris/u-boot/blob/v2020.01-ci/.azure-pipelines.yml. This fork is used as it resolves a number of issues present in mainline U-Boot and has pre-built images.

+ + + +

I assume you have:

+
    +
  • setup a TFTP server
    • +
  • setup a DHCP server
    • +
  • linked the TFTP and DHCP servers appropriately
    • +
+ +

Luckily the U-Boot defconfig for ROCKPro64 includes UEFI support. We are not using EDK2 because no stable and tested implementations exist for ROCKPro64.

+ +

Copy your seL4 image to the TFTP root under the name sel4img (or any other name of your choosing but you will have to adjust following commands).

+ +

Manual method (well tested)

+ +

Drop into a U-Boot console when asked. Type in:

+ +
dhcp
+tftpboot ${kernel_addr_r} sel4img
+bootefi ${kernel_addr_r}
+
+ +
    +
  • Watch seL4 boot!
    • +
+ +

Automated method

+ +

Create pxelinux.cfg/default in TFTP root:

+ +
menu title PXE!
+
+timeout 200
+
+label sel4
+menu default
+kernel /sel4img
+
+ +

Create boot.scr:

+ +
bootefi 0x2080000
+
+ +

Significance of 0x2080000 being where seL4 image is loaded by U-Boot.

+ +

Convert boot.scr to a uImage using mkimage -A arm -T script -C none -n boot.scr -d boot.scr boot.scr.uimg. Ensure boot.scr.uimg is in the TFTP root and boot.scr is removed.

+ +

Setting up with UEFI, SD card

+ +

This process is similar to above with TFTP. The SD card should have one or more partitions, the first one must be ext2 and have the file files on it. (If required, you can change the 1:1 in the below commands to 1:2, 1:3 etc for using 2nd, 3rd, partition, etc).

+ +

Copy your sel4img aforementioned in UEFI section to SD card.

+ +

Manual

+ +

Drop to a U-Boot console and type in:

+ +
ext2load mmc 1:1 ${kernel_addr_r} sel4img
+bootefi ${kernel_addr_r}
+
+ +

Automated

+ +

Create boot.scr:

+ +
ext2load mmc 1:1 ${kernel_addr_r} sel4img
+bootefi ${kernel_addr_r}
+
+ +

Convert to uImage using mkimage -A arm -T script -C none -n boot.scr -d boot.scr boot.scr.uimg. Put in SD card and boot.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/rockpro64.md b/Hardware/rockpro64.md deleted file mode 100644 index d56287bc365..00000000000 --- a/Hardware/rockpro64.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -arm_hardware: true -cmake_plat: rockpro64 -xcompiler_arg: -DAARCH64=1 -platform: ROCKPro64 -arch: ARMv8A, AArch64 -virtualization: true -iommu: false -soc: RK3399 hexa-core -cpu: Cortex-A53 Quad 1.8 GHz -verification: [AARCH64] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# ROCKPro64 - -{% include hw-info.html %} - -## Building seL4test - -{% include sel4test.md %} - -## Flashing the SPI with U-Boot - -**WARNING! DO NOT POWER OFF THE DEVICE FOR ANY REASON DURING SPI FLASH! YOU WILL GET A (soft-) BRICKED DEVICE** - -The first step is getting U-Boot onto the system. It is recommended, particularly for TFTP boot, to put U-Boot on the SPI flash. - -If you have a "dirty" (any previously used) SPI flash, first: -1. Download https://github.com/sigmaris/u-boot/releases/download/v2020.01-ci/erase_spi.img.gz -2. Write it to an SD card -3. Boot from the SD card (will be done automatically if you don't have a very weird setup). Once it completes (see this over serial or when white LED becomes stable), remove the SD card, but DO NOT reset. - -Then, to flash the actual image: -1. Get https://github.com/sigmaris/u-boot/releases/download/v2020.01-ci/flash_spi.img.gz and write it to an SD card. -2. Put the SD card into the ROCKPro64 and boot. Wait for completion (seen over serial or when white LED becomes stable). -3. Remove the SD card. -4. Reset and observe U-Boot come up. - -Compiling u-boot by oneself has not been done and has been left as an exercise to the reader if wanted. HINT: https://github.com/sigmaris/u-boot/blob/v2020.01-ci/.azure-pipelines.yml. This fork is used as it resolves a number of issues present in mainline U-Boot and has pre-built images. - -## Setting up with TFTP, DHCP, UEFI (recommended!) - -I assume you have: -- setup a TFTP server -- setup a DHCP server -- linked the TFTP and DHCP servers appropriately - -Luckily the U-Boot defconfig for ROCKPro64 includes UEFI support. We are not using EDK2 because no stable and tested implementations exist for ROCKPro64. - -Copy your seL4 image to the TFTP root under the name `sel4img` (or any other name of your choosing but you will have to adjust following commands). - -### Manual method (well tested) - -Drop into a U-Boot console when asked. Type in: - -``` -dhcp -tftpboot ${kernel_addr_r} sel4img -bootefi ${kernel_addr_r} -``` - -- Watch seL4 boot! - -### Automated method - -Create `pxelinux.cfg/default` in TFTP root: - -``` -menu title PXE! - -timeout 200 - -label sel4 -menu default -kernel /sel4img -``` - -Create `boot.scr`: - -``` -bootefi 0x2080000 -``` - -Significance of 0x2080000 being where seL4 image is loaded by U-Boot. - -Convert `boot.scr` to a uImage using `mkimage -A arm -T script -C none -n boot.scr -d boot.scr boot.scr.uimg`. Ensure `boot.scr.uimg` is in the TFTP root and `boot.scr` is removed. - - -## Setting up with UEFI, SD card - -This process is similar to above with TFTP. The SD card should have one or more partitions, the first one must be ext2 and have the file files on it. (If required, you can change the 1:1 in the below commands to 1:2, 1:3 etc for using 2nd, 3rd, partition, etc). - -Copy your `sel4img` aforementioned in UEFI section to SD card. - -### Manual - -Drop to a U-Boot console and type in: - -``` -ext2load mmc 1:1 ${kernel_addr_r} sel4img -bootefi ${kernel_addr_r} -``` - -### Automated - -Create `boot.scr`: - -``` -ext2load mmc 1:1 ${kernel_addr_r} sel4img -bootefi ${kernel_addr_r} -``` - -Convert to uImage using `mkimage -A arm -T script -C none -n boot.scr -d boot.scr boot.scr.uimg`. Put in SD card and boot. diff --git a/Hardware/sabreLite.html b/Hardware/sabreLite.html new file mode 100644 index 00000000000..b19450e284c --- /dev/null +++ b/Hardware/sabreLite.html @@ -0,0 +1,836 @@ + + + + + + + Sabre Lite | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Sabre Lite

+ +

For board details see +Sabre Lite

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Sabre Lite
Simulation platform yes
Architecture ARMv7A
System-on-chip i.MX6
CPU Cortex-A9
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + +
Proof configsARM
seL4 CMake platform namesabre
Contributed by Data61
Maintained by seL4 Foundation
+ +

Booting on the Sabre Lite

+ +

Hardware Requirements

+ +
    +
  • 5V/3A power supply
    • +
  • RS232 cable (or USB-RS232 adapter)
    • +
  • USB OTG cable for Fastboot or Ethernet cable for TFTPboot
    • +
+ +

Board Setup

+ +

The SabreLite can be configured to boot from either +USB or SPI flash. USB booting is typically only used when there is a +failure in the SPI flash resident bootloader. One may use USB boot to +temporarily boot u-boot and reflash the SPI memory.

+ +

SPI flash contains a simple boot loader that will can boot from either +SPI flash, or from an image starting at block 2 of the SD or μSD card +depending on which boot loader has been flashed.

+ +

Booting U-Boot from USB

+ +

USB booting offers a back door into the +system. This method is usually only used to reprogram the SPI flash boot +program.

+ +

You will first need to acquire and compile the IMX USB loader tool from

+ +
git clone git://github.com/boundarydevices/imx_usb_loader.git
+
+ +

NOTE 1: The Element14 Sabrelite platform has its DIP switch mounted +incorrectly.

+ +

NOTE 2: The connection order is important. You may find that your +USB-TTY converter has locked up.

+ +
    +
  1. Move the DIP switch nearest the Ethernet port to the OFF position
    2. +
  2. Move the DIP switch farthest from the Ethernet port to the +ON position.
    3. +
  3. Plug the USB cable into the USB-OTG port located near the +HDMI port.
    4. +
  4. Connect the RS232 port to your computer and open minicom.
    5. +
  5. Power up the device.
    6. +
+ +

Now you are ready to load your image into memory and execute:

+ +
$ lsusb
+....
+Bus 001 Device 019: ID
+15a2:0054 Freescale Semiconductor, Inc.
+....
+$ sudo ./imx_usb image_file
+
+ +

The image file that is used will typically be named +u-boot.bin

+ +

Booting U-Boot from SPI Flash

+ +

To boot from SPI flash:

+ +
    +
  1. Move the DIP switch nearest the Ethernet port to the OFF position
    2. +
  2. Move the DIP switch farthest from the Ethernet port to the OFF +position
    3. +
  3. Connect the RS232 port to your computer and open minicom.
    4. +
  4. Insert an SD or μSD card depending on which boot loader is +resident in SPI flash
    5. +
  5. Power up the device.
    6. +
+ +

Now you are ready to load your image into memory and execute:

+ +
$ lsusb
+....
+Bus 001 Device 019: ID 15a2:0054 Freescale Semiconductor, Inc.
+....
+$ sudo ./imx_usb image_file
+
+ +

The image file that is used will typically be named +u-boot.bin

+ +

SD and μSD cards

+ +

To boot U-Boot from an SD or μSD card, one must +install the appropriate boot loader into SPI flash. The method and boot +loader images are provided in the SPI flash programming section. U-Boot +must be located at block 2 of the SD or μSD card. This can be achieved +with the following command, assuming that the SD or μSD device is +/dev/sdb.

+ +
dd if=u-boot.bin of=/dev/sdb seek=2 bs=512; sync
+
+ +

U-Boot for the Sabre Lite

+ +

Obtaining and Building

+ +

There are many versions of U-Boot available for the Sabre +Lite. The ones for Android support Fastboot; the mainline ones do not.

+ +

We use the one from +<git://github.com/boundarydevices/u-boot-2009-08.git> with these patches +applied:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
NamePurpose
01_android-imx6-uboot-enable_bootelf.patchEnable bootelf command
02_android-imx6-uboot-fastbootfix.patchFix fastboot to allow the booting of elf and u-boot images
03_android-imx6-uboot-extra_fs_features.patchAdd some extra file systems and associated features
04_android-imx6-uboot-update_env.patchSetup default environment. In particular, bootsel4_mmc and bootsel4_net
+ +

Prebuilt: +u-boot.bin

+ +

The prebuilt version is for booting from SPI.

+ +

To obtain and build U-Boot, do:

+ +
git clone git://github.com/boundarydevices/u-boot-2009-08.git
+cd u-boot-2009-08
+git checkout origin/boundary-imx_3.0.35_1.1.0 -b boundary-imx_3.0.35_1.1.0
+export ARCH=arm
+export CROSS_COMPILE=arm-none-eabi-
+make mx6q_sabrelite_android_config
+make all
+ls -l u-boot.bin
+
+ +

Installing U-Boot to SPI Flash

+ +

To install U-Boot, put u-boot.bin onto the first partition (either FAT16 or +EXT2) of an SD card, boot into U-Boot then do this at the U-Boot prompt:

+ +
# Initialise the SD card. Replace 1 with 0 for standard SD
+mmc dev 1
+
+# Load the file with name "u-boot.bin" from the 1st partition of the SD card to RAM at address 0x12000000
+ext2load mmc 1:1 12000000 u-boot.bin
+
+# Initialise the SPI flash subsystem
+sf probe | sf probe 1
+
+# Erase 0x100000 bytes from the SPI flash starting at address 0x00000000
+# This covers both U-Boot and its saved environment.
+sf erase 0 0x100000
+
+# Copy ${filesize} bytes from RAM at address 0x12000000 to SPI flash at address 0x00000000
+# Note that the filesize variable was set when the file was loaded into RAM
+sf write 0x12000000 0 ${filesize}
+
+# Ensure that the boot select switches are set appropriately, then reboot the Sabrelite
+
+ +

Booting seL4 applications

+ +

This assumes that the U-Boot version above is installed in SPI flash.

+ + + + + + + + + + + + + + + + + + + + + + +
CommandOperation
run bootsel4_mmcScans through the SD card and their partitions looking for an elf file named “sel4-image” in the root directory. This file will be loaded and executed.
run bootsel4_netPerforms a DHCP request followed by a TFTPBoot request and attempts to load a file named “sabre/sel4-image”.
run bootsel4_fastbootSimple alias for the fastboot command
+ +

Running seL4 test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=sabre -DAARCH32=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+# This platform is a simulation target. This script should work to run the
+# generated image if you also use -DSIMULATION=1 for init-build above:
+./simulate
+
+
+

If you plan to use the ./simulate script, please be sure to add the +-DSIMULATION=1 argument when running cmake.

+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/sabreLite.md b/Hardware/sabreLite.md deleted file mode 100644 index 9771cd1ae93..00000000000 --- a/Hardware/sabreLite.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -arm_hardware: true -simulation_target: true -simulation_only: false -cmake_plat: sabre -xcompiler_arg: -DAARCH32=1 -platform: Sabre Lite -arch: ARMv7A -virtualization: false -iommu: false -soc: i.MX6 -cpu: Cortex-A9 -verification: [ARM] -Contrib: Data61 -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Sabre Lite - -For board details see -[Sabre Lite](https://boundarydevices.com/product/bd-sl-i-mx6/) - -{% include hw-info.html %} - -## Booting on the Sabre Lite - -### Hardware Requirements - -* 5V/3A power supply -* RS232 cable (or USB-RS232 adapter) -* USB OTG cable for Fastboot or Ethernet cable for TFTPboot - -### Board Setup - - The SabreLite can be configured to boot from either -USB or SPI flash. USB booting is typically only used when there is a -failure in the SPI flash resident bootloader. One may use USB boot to -temporarily boot u-boot and reflash the SPI memory. - -SPI flash contains a simple boot loader that will can boot from either -SPI flash, or from an image starting at block 2 of the SD or μSD card -depending on which boot loader has been flashed. - -### Booting U-Boot from USB - - USB booting offers a back door into the -system. This method is usually only used to reprogram the SPI flash boot -program. - -You will first need to acquire and compile the IMX USB loader tool from - -```bash -git clone git://github.com/boundarydevices/imx_usb_loader.git -``` - -NOTE 1: The Element14 Sabrelite platform has its DIP switch mounted -incorrectly. - -NOTE 2: The connection order is important. You may find that your -USB-TTY converter has locked up. - - 1. Move the DIP switch nearest the Ethernet port to the OFF position - 2. Move the DIP switch farthest from the Ethernet port to the - ON position. - 3. Plug the USB cable into the USB-OTG port located near the - HDMI port. - 4. Connect the RS232 port to your computer and open minicom. - 5. Power up the device. - -Now you are ready to load your image into memory and execute: - -```bash -$ lsusb -.... -Bus 001 Device 019: ID -15a2:0054 Freescale Semiconductor, Inc. -.... -$ sudo ./imx_usb image_file -``` - -The image file that is used will typically be named -u-boot.bin - -### Booting U-Boot from SPI Flash - -To boot from SPI flash: - - 1. Move the DIP switch nearest the Ethernet port to the OFF position - 2. Move the DIP switch farthest from the Ethernet port to the OFF - position - 3. Connect the RS232 port to your computer and open minicom. - 4. Insert an SD or μSD card depending on which boot loader is - resident in SPI flash - 5. Power up the device. - -Now you are ready to load your image into memory and execute: - -```bash -$ lsusb -.... -Bus 001 Device 019: ID 15a2:0054 Freescale Semiconductor, Inc. -.... -$ sudo ./imx_usb image_file -``` - -The image file that is used will typically be named -u-boot.bin - -### SD and μSD cards - -To boot U-Boot from an SD or μSD card, one must -install the appropriate boot loader into SPI flash. The method and boot -loader images are provided in the SPI flash programming section. U-Boot -must be located at block 2 of the SD or μSD card. This can be achieved -with the following command, assuming that the SD or μSD device is -`/dev/sdb`. - -```bash -dd if=u-boot.bin of=/dev/sdb seek=2 bs=512; sync -``` - -### U-Boot for the Sabre Lite - -#### Obtaining and Building - -There are many versions of U-Boot available for the Sabre -Lite. The ones for Android support Fastboot; the mainline ones do not. - -We use the one from - with these patches -applied: - -|Name |Purpose | -|-|-| -|[01_android-imx6-uboot-enable_bootelf.patch](https://sel4.systems/Info/Hardware/sabreLite/01_android-imx6-uboot-enable_bootelf.patch)|Enable bootelf command | -|[02_android-imx6-uboot-fastbootfix.patch](https://sel4.systems/Info/Hardware/sabreLite/02_android-imx6-uboot-fastbootfix.patch)|Fix fastboot to allow the booting of elf and u-boot images | -|[03_android-imx6-uboot-extra_fs_features.patch](https://sel4.systems/Info/Hardware/sabreLite/03_android-imx6-uboot-extra_fs_features.patch)|Add some extra file systems and associated features | -|[04_android-imx6-uboot-update_env.patch](https://sel4.systems/Info/Hardware/sabreLite/04_android-imx6-uboot-update_env.patch)|Setup default environment. In particular, bootsel4_mmc and bootsel4_net | - -Prebuilt: -[u-boot.bin](https://sel4.systems/Info/Hardware/sabreLite/u-boot.bin) - -The prebuilt version is for booting from SPI. - -To obtain and build U-Boot, do: - -```bash -git clone git://github.com/boundarydevices/u-boot-2009-08.git -cd u-boot-2009-08 -git checkout origin/boundary-imx_3.0.35_1.1.0 -b boundary-imx_3.0.35_1.1.0 -export ARCH=arm -export CROSS_COMPILE=arm-none-eabi- -make mx6q_sabrelite_android_config -make all -ls -l u-boot.bin -``` - -#### Installing U-Boot to SPI Flash - -To install U-Boot, put u-boot.bin onto the first partition (either FAT16 or -EXT2) of an SD card, boot into U-Boot then do this at the U-Boot prompt: - -```bash -# Initialise the SD card. Replace 1 with 0 for standard SD -mmc dev 1 - -# Load the file with name "u-boot.bin" from the 1st partition of the SD card to RAM at address 0x12000000 -ext2load mmc 1:1 12000000 u-boot.bin - -# Initialise the SPI flash subsystem -sf probe | sf probe 1 - -# Erase 0x100000 bytes from the SPI flash starting at address 0x00000000 -# This covers both U-Boot and its saved environment. -sf erase 0 0x100000 - -# Copy ${filesize} bytes from RAM at address 0x12000000 to SPI flash at address 0x00000000 -# Note that the filesize variable was set when the file was loaded into RAM -sf write 0x12000000 0 ${filesize} - -# Ensure that the boot select switches are set appropriately, then reboot the Sabrelite -``` - -## Booting seL4 applications - -This assumes that the U-Boot version above is installed in SPI flash. - -|Command|Operation| -|-|-| -|run bootsel4_mmc |Scans through the SD card and their partitions looking for an elf file named "sel4-image" in the root directory. This file will be loaded and executed. | -|run bootsel4_net |Performs a DHCP request followed by a TFTPBoot request and attempts to load a file named "sabre/sel4-image". | -|run bootsel4_fastboot|Simple alias for the fastboot command | - -## Running seL4 test - -{% include sel4test.md %} diff --git a/Hardware/spike.html b/Hardware/spike.html new file mode 100644 index 00000000000..9347e88f325 --- /dev/null +++ b/Hardware/spike.html @@ -0,0 +1,653 @@ + + + + + + + Spike | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Spike

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Spike
Simulation platform yes
Architecture RV32GC, RV64IMAFDC
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + – +
Proof configs–
seL4 CMake platform namespike
Contributed by Data61, Hesham Almatary
Maintained by seL4 Foundation
+ +

Building the GCC toolchain

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Getting the Simulator

+ +

You can use either RISC-V ISA +Simulator or QEMU >= v4.2 shipped with +your Linux distribution.

+ +

If you prefer to build qemu from source, make sure you have the correct target +enabled.

+ +
git clone https://git.qemu.org/git/qemu.git
+cd qemu
+mkdir build
+cd build
+../configure --prefix=/opt/riscv --target-list=riscv64-softmmu,riscv32-softmmu
+make
+
+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=spike -DRISCV64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+./simulate
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

You can also use run the tests on the 32-bit spike platform by replacing +the -DRISCV64=TRUE option with -DRISCV32=TRUE.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/spike.md b/Hardware/spike.md deleted file mode 100644 index 907169ec712..00000000000 --- a/Hardware/spike.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -riscv_hardware: true -cmake_plat: spike -xcompiler_arg: -DRISCV64=1 -platform: Spike -arch: RV32GC, RV64IMAFDC -virtualization: false -iommu: false -simulation_target: true -verification: [] -Contrib: 'Data61, Hesham Almatary' -Maintained: "seL4 Foundation" -redirect_from: - - /Hardware/RISCV -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Spike - -{% include hw-info.html %} - -## Building the GCC toolchain - -{% include risc-v.md %} - -## Getting the Simulator - -You can use either [RISC-V ISA -Simulator](https://github.com/riscv/riscv-isa-sim) or QEMU >= v4.2 shipped with -your Linux distribution. - -If you prefer to build qemu from source, make sure you have the correct target -enabled. - -```sh -git clone https://git.qemu.org/git/qemu.git -cd qemu -mkdir build -cd build -../configure --prefix=/opt/riscv --target-list=riscv64-softmmu,riscv32-softmmu -make -``` - -## Building seL4test - -{% include sel4test.md %} - -You can also use run the tests on the 32-bit spike platform by replacing -the `-DRISCV64=TRUE` option with `-DRISCV32=TRUE`. diff --git a/Hardware/tqma8xqp1gb.html b/Hardware/tqma8xqp1gb.html new file mode 100644 index 00000000000..a7a74a39a8c --- /dev/null +++ b/Hardware/tqma8xqp1gb.html @@ -0,0 +1,629 @@ + + + + + + + TQMa8XQP 1GB | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

TQMa8XQP 1GB

+ +

The +TQMa8XQP +is a system-on-module designed by TQ-Systems +GmbH. The modules incorporates an NXP i.MX8X Quad +Plus system-on-chip and 1GiB ECC memory.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform TQMa8XQP 1GB
Architecture ARMv8A, AArch64
System-on-chip i.MX8X Quad Plus
CPU Cortex-A35
seL4 virtualisation support +– +
seL4 SMMU support +– +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nametqma8xqp1gb
Contributed by Breakaway Consulting
Maintained by seL4 Foundation
+ +

The seL4 TQMa8XQP port currently only supports running the board in AArch64 +mode. Virtualization support is untested.

+ +

Building seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=tqma8xqp1gb -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/tqma8xqp1gb.md b/Hardware/tqma8xqp1gb.md deleted file mode 100644 index 10ef31bb23a..00000000000 --- a/Hardware/tqma8xqp1gb.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -arm_hardware: true -cmake_plat: tqma8xqp1gb -xcompiler_arg: -DAARCH64=1 -platform: TQMa8XQP 1GB -arch: ARMv8A, AArch64 -virtualization: false -iommu: false -soc: i.MX8X Quad Plus -cpu: Cortex-A35 -verification: [AARCH64] -Contrib: Breakaway Consulting -Maintained: seL4 Foundation -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. ---- - -# TQMa8XQP 1GB - -The -[TQMa8XQP](https://www.tq-group.com/en/products/tq-embedded/arm-architecture/tqma8xx/) -is a system-on-module designed by [TQ-Systems -GmbH](https://www.tq-group.com/en/). The modules incorporates an NXP i.MX8X Quad -Plus system-on-chip and 1GiB ECC memory. - -{% include hw-info.html %} - -The seL4 TQMa8XQP port currently only supports running the board in AArch64 -mode. Virtualization support is untested. - -## Building seL4test - -{% include sel4test.md %} diff --git a/Hardware/ultra96v2.html b/Hardware/ultra96v2.html new file mode 100644 index 00000000000..df5d287d469 --- /dev/null +++ b/Hardware/ultra96v2.html @@ -0,0 +1,644 @@ + + + + + + + Ultra96v2 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Ultra96v2

+ +

The Avnet Ultra96v2 is a low-cost Zynq MPSoC development platform developed by +AVNET.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Platform Ultra96v2 Evaluation Kit
Architecture ARMv8A
System-on-chip Zynq UltraScale+ MPSoC
CPU Cortex-A53
seL4 virtualisation support + +
seL4 SMMU support + +
Proofs + +
Proof configsAARCH64
seL4 CMake platform nameultra96v2
Contributed by DornerWorks
Maintained by DornerWorks
+ +

AVNET maintains online material, including designs and documentation.

+ +

Building

+ +

seL4test

+ +

Checkout the sel4test project using repo as per seL4Test

+
repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+mkdir cbuild
+cd cbuild
+../init-build.sh -DPLATFORM=ultra96v2 -DAARCH64=1
+# The default cmake wrapper sets up a default configuration for the target platform.
+# To change individual settings, run `ccmake .` and change the configuration
+# parameters to suit your needs.
+ninja
+
+
+ +

Generated binaries can be found in the images/ directory.

+ +

The Ultra96v2 also supports AArch32 mode. If you choose to build the AArch32 kernel, +please be sure to pass -DAARCH32=1 instead of -DAARCH64=1. This requires modifications to u-boot +to execute in 32-bit mode. See the ZCU102 page for instructions.

+ +

Booting via SD Card

+ +

The ultra96v2 comes with a pre-formatted SD card. Load the sel4test-driver-image-arm-zynqmp onto +the SD card, then insert the SD card into the Ultra96v2 and power on the board, dropping into the +U-boot prompt. When at the prompt, type the following to run sel4test:

+ +
fatload mmc 0 0x10000000 sel4test-driver-image-arm-zynqmp
+bootelf 0x10000000
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/Hardware/ultra96v2.md b/Hardware/ultra96v2.md deleted file mode 100644 index a043bbe3b83..00000000000 --- a/Hardware/ultra96v2.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -cmake_plat: ultra96v2 -xcompiler_arg: -DAARCH64=1 -arm_hardware: true -platform: Ultra96v2 Evaluation Kit -arch: ARMv8A -virtualization: true -iommu: true -soc: Zynq UltraScale+ MPSoC -cpu: Cortex-A53 -verification: [AARCH64] -Contrib: 'DornerWorks' -Maintained: 'DornerWorks' -parent: /Hardware/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Ultra96v2 - -The Avnet Ultra96v2 is a low-cost Zynq MPSoC development platform developed by -AVNET. - -{% include hw-info.html %} - -AVNET maintains online material, including [designs and documentation](https://www.avnet.com/americas/product/avnet-engineering-services/aes-ultra96-v2-i-g/evolve-42136369/). - -## Building - -### seL4test - -{% include sel4test.md %} - -The Ultra96v2 also supports AArch32 mode. If you choose to build the AArch32 kernel, -please be sure to pass `-DAARCH32=1` instead of `-DAARCH64=1`. This requires modifications to u-boot -to execute in 32-bit mode. See the ZCU102 page for instructions. - -## Booting via SD Card - -The ultra96v2 comes with a pre-formatted SD card. Load the `sel4test-driver-image-arm-zynqmp` onto -the SD card, then insert the SD card into the Ultra96v2 and power on the board, dropping into the -U-boot prompt. When at the prompt, type the following to run sel4test: - -```bash -fatload mmc 0 0x10000000 sel4test-driver-image-arm-zynqmp -bootelf 0x10000000 -``` diff --git a/HardwareHacks.html b/HardwareHacks.html new file mode 100644 index 00000000000..b5ffd2d396a --- /dev/null +++ b/HardwareHacks.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/HostDependencies.html b/HostDependencies.html new file mode 100644 index 00000000000..d5f76db0935 --- /dev/null +++ b/HostDependencies.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/LICENSES/BSD-2-Clause.txt b/LICENSES/BSD-2-Clause.txt deleted file mode 100644 index baa80b56a29..00000000000 --- a/LICENSES/BSD-2-Clause.txt +++ /dev/null @@ -1,22 +0,0 @@ -Copyright (c) All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, -this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, -this list of conditions and the following disclaimer in the documentation -and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/LICENSES/CC-BY-NC-SA-4.0.txt b/LICENSES/CC-BY-NC-SA-4.0.txt deleted file mode 100644 index baee873b679..00000000000 --- a/LICENSES/CC-BY-NC-SA-4.0.txt +++ /dev/null @@ -1,170 +0,0 @@ -Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International - - Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. - -Using Creative Commons Public Licenses - -Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. - -Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. More considerations for licensors. - -Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public. - -Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License - -By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. - -Section 1 – Definitions. - - a. Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. - - b. Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. - - c. BY-NC-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, approved by Creative Commons as essentially the equivalent of this Public License. - - d. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. - - e. Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. - - f. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. - - g. License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution, NonCommercial, and ShareAlike. - - h. Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License. - - i. Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. - - j. Licensor means the individual(s) or entity(ies) granting rights under this Public License. - - k. NonCommercial means not primarily intended for or directed towards commercial advantage or monetary compensation. For purposes of this Public License, the exchange of the Licensed Material for other material subject to Copyright and Similar Rights by digital file-sharing or similar means is NonCommercial provided there is no payment of monetary compensation in connection with the exchange. - - l. Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. - - m. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. - - n. You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. - -Section 2 – Scope. - - a. License grant. - - 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: - - A. reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes only; and - - B. produce, reproduce, and Share Adapted Material for NonCommercial purposes only. - - 2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. - - 3. Term. The term of this Public License is specified in Section 6(a). - - 4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. - - 5. Downstream recipients. - - A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. - - B. Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. - - C. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. - - 6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). - - b. Other rights. - - 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. - - 2. Patent and trademark rights are not licensed under this Public License. - - 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties, including when the Licensed Material is used other than for NonCommercial purposes. - -Section 3 – License Conditions. - -Your exercise of the Licensed Rights is expressly made subject to the following conditions. - - a. Attribution. - - 1. If You Share the Licensed Material (including in modified form), You must: - - A. retain the following if it is supplied by the Licensor with the Licensed Material: - - i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); - - ii. a copyright notice; - - iii. a notice that refers to this Public License; - - iv. a notice that refers to the disclaimer of warranties; - - v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; - - B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and - - C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. - - 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. - - 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. - - b. ShareAlike.In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. - - 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-NC-SA Compatible License. - - 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. - - 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. - -Section 4 – Sui Generis Database Rights. - -Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: - - a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database for NonCommercial purposes only; - - b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and - - c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. -For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. - -Section 5 – Disclaimer of Warranties and Limitation of Liability. - - a. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You. - - b. To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You. - - c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. - -Section 6 – Term and Termination. - - a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. - - b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: - - 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or - - 2. upon express reinstatement by the Licensor. - - For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. - - c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. - - d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. - -Section 7 – Other Terms and Conditions. - - a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. - - b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. - -Section 8 – Interpretation. - - a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. - - b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. - - c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. - - d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. - -Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. - -Creative Commons may be contacted at creativecommons.org. diff --git a/LICENSES/CC-BY-SA-4.0.txt b/LICENSES/CC-BY-SA-4.0.txt deleted file mode 100644 index 4dfebb88f65..00000000000 --- a/LICENSES/CC-BY-SA-4.0.txt +++ /dev/null @@ -1,349 +0,0 @@ -Creative Commons Attribution-ShareAlike 4.0 International - -Creative Commons Corporation (“Creative Commons”) is not a law firm and does -not provide legal services or legal advice. Distribution of Creative Commons -public licenses does not create a lawyer-client or other relationship. Creative -Commons makes its licenses and related information available on an “as-is” -basis. Creative Commons gives no warranties regarding its licenses, any material -licensed under their terms and conditions, or any related information. Creative -Commons disclaims all liability for damages resulting from their use to the -fullest extent possible. - -Using Creative Commons Public Licenses - -Creative Commons public licenses provide a standard set of terms and conditions -that creators and other rights holders may use to share original works of -authorship and other material subject to copyright and certain other rights -specified in the public license below. The following considerations are for -informational purposes only, are not exhaustive, and do not form part of our -licenses. - -Considerations for licensors: Our public licenses are intended for use by -those authorized to give the public permission to use material in ways otherwise -restricted by copyright and certain other rights. Our licenses are irrevocable. -Licensors should read and understand the terms and conditions of the license -they choose before applying it. Licensors should also secure all rights necessary -before applying our licenses so that the public can reuse the material as -expected. Licensors should clearly mark any material not subject to the license. -This includes other CC-licensed material, or material used under an exception -or limitation to copyright. More considerations for licensors. - -Considerations for the public: By using one of our public licenses, a licensor -grants the public permission to use the licensed material under specified -terms and conditions. If the licensor’s permission is not necessary for any -reason–for example, because of any applicable exception or limitation to copyright–then -that use is not regulated by the license. Our licenses grant only permissions -under copyright and certain other rights that a licensor has authority to -grant. Use of the licensed material may still be restricted for other reasons, -including because others have copyright or other rights in the material. A -licensor may make special requests, such as asking that all changes be marked -or described. - -Although not required by our licenses, you are encouraged to respect those -requests where reasonable. More considerations for the public. - -Creative Commons Attribution-ShareAlike 4.0 International Public License - -By exercising the Licensed Rights (defined below), You accept and agree to -be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike -4.0 International Public License ("Public License"). To the extent this Public -License may be interpreted as a contract, You are granted the Licensed Rights -in consideration of Your acceptance of these terms and conditions, and the -Licensor grants You such rights in consideration of benefits the Licensor -receives from making the Licensed Material available under these terms and -conditions. - -Section 1 – Definitions. - -a. Adapted Material means material subject to Copyright and Similar Rights -that is derived from or based upon the Licensed Material and in which the -Licensed Material is translated, altered, arranged, transformed, or otherwise -modified in a manner requiring permission under the Copyright and Similar -Rights held by the Licensor. For purposes of this Public License, where the -Licensed Material is a musical work, performance, or sound recording, Adapted -Material is always produced where the Licensed Material is synched in timed -relation with a moving image. - -b. Adapter's License means the license You apply to Your Copyright and Similar -Rights in Your contributions to Adapted Material in accordance with the terms -and conditions of this Public License. - -c. BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, -approved by Creative Commons as essentially the equivalent of this Public -License. - -d. Copyright and Similar Rights means copyright and/or similar rights closely -related to copyright including, without limitation, performance, broadcast, -sound recording, and Sui Generis Database Rights, without regard to how the -rights are labeled or categorized. For purposes of this Public License, the -rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. - -e. Effective Technological Measures means those measures that, in the absence -of proper authority, may not be circumvented under laws fulfilling obligations -under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, -and/or similar international agreements. - -f. Exceptions and Limitations means fair use, fair dealing, and/or any other -exception or limitation to Copyright and Similar Rights that applies to Your -use of the Licensed Material. - -g. License Elements means the license attributes listed in the name of a Creative -Commons Public License. The License Elements of this Public License are Attribution -and ShareAlike. - -h. Licensed Material means the artistic or literary work, database, or other -material to which the Licensor applied this Public License. - -i. Licensed Rights means the rights granted to You subject to the terms and -conditions of this Public License, which are limited to all Copyright and -Similar Rights that apply to Your use of the Licensed Material and that the -Licensor has authority to license. - -j. Licensor means the individual(s) or entity(ies) granting rights under this -Public License. - -k. Share means to provide material to the public by any means or process that -requires permission under the Licensed Rights, such as reproduction, public -display, public performance, distribution, dissemination, communication, or -importation, and to make material available to the public including in ways -that members of the public may access the material from a place and at a time -individually chosen by them. - -l. Sui Generis Database Rights means rights other than copyright resulting -from Directive 96/9/EC of the European Parliament and of the Council of 11 -March 1996 on the legal protection of databases, as amended and/or succeeded, -as well as other essentially equivalent rights anywhere in the world. - -m. You means the individual or entity exercising the Licensed Rights under -this Public License. Your has a corresponding meaning. - -Section 2 – Scope. - - a. License grant. - -1. Subject to the terms and conditions of this Public License, the Licensor -hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, -irrevocable license to exercise the Licensed Rights in the Licensed Material -to: - -A. reproduce and Share the Licensed Material, in whole or in part; and - - B. produce, reproduce, and Share Adapted Material. - -2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions -and Limitations apply to Your use, this Public License does not apply, and -You do not need to comply with its terms and conditions. - -3. Term. The term of this Public License is specified in Section 6(a). - -4. Media and formats; technical modifications allowed. The Licensor authorizes -You to exercise the Licensed Rights in all media and formats whether now known -or hereafter created, and to make technical modifications necessary to do -so. The Licensor waives and/or agrees not to assert any right or authority -to forbid You from making technical modifications necessary to exercise the -Licensed Rights, including technical modifications necessary to circumvent -Effective Technological Measures. For purposes of this Public License, simply -making modifications authorized by this Section 2(a)(4) never produces Adapted -Material. - - 5. Downstream recipients. - -A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed -Material automatically receives an offer from the Licensor to exercise the -Licensed Rights under the terms and conditions of this Public License. - -B. Additional offer from the Licensor – Adapted Material. Every recipient -of Adapted Material from You automatically receives an offer from the Licensor -to exercise the Licensed Rights in the Adapted Material under the conditions -of the Adapter’s License You apply. - -C. No downstream restrictions. You may not offer or impose any additional -or different terms or conditions on, or apply any Effective Technological -Measures to, the Licensed Material if doing so restricts exercise of the Licensed -Rights by any recipient of the Licensed Material. - -6. No endorsement. Nothing in this Public License constitutes or may be construed -as permission to assert or imply that You are, or that Your use of the Licensed -Material is, connected with, or sponsored, endorsed, or granted official status -by, the Licensor or others designated to receive attribution as provided in -Section 3(a)(1)(A)(i). - - b. Other rights. - -1. Moral rights, such as the right of integrity, are not licensed under this -Public License, nor are publicity, privacy, and/or other similar personality -rights; however, to the extent possible, the Licensor waives and/or agrees -not to assert any such rights held by the Licensor to the limited extent necessary -to allow You to exercise the Licensed Rights, but not otherwise. - -2. Patent and trademark rights are not licensed under this Public License. - -3. To the extent possible, the Licensor waives any right to collect royalties -from You for the exercise of the Licensed Rights, whether directly or through -a collecting society under any voluntary or waivable statutory or compulsory -licensing scheme. In all other cases the Licensor expressly reserves any right -to collect such royalties. - -Section 3 – License Conditions. - -Your exercise of the Licensed Rights is expressly made subject to the following -conditions. - - a. Attribution. - -1. If You Share the Licensed Material (including in modified form), You must: - -A. retain the following if it is supplied by the Licensor with the Licensed -Material: - -i. identification of the creator(s) of the Licensed Material and any others -designated to receive attribution, in any reasonable manner requested by the -Licensor (including by pseudonym if designated); - - ii. a copyright notice; - - iii. a notice that refers to this Public License; - - iv. a notice that refers to the disclaimer of warranties; - -v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; - -B. indicate if You modified the Licensed Material and retain an indication -of any previous modifications; and - -C. indicate the Licensed Material is licensed under this Public License, and -include the text of, or the URI or hyperlink to, this Public License. - -2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner -based on the medium, means, and context in which You Share the Licensed Material. -For example, it may be reasonable to satisfy the conditions by providing a -URI or hyperlink to a resource that includes the required information. - -3. If requested by the Licensor, You must remove any of the information required -by Section 3(a)(1)(A) to the extent reasonably practicable. - -b. ShareAlike.In addition to the conditions in Section 3(a), if You Share -Adapted Material You produce, the following conditions also apply. - -1. The Adapter’s License You apply must be a Creative Commons license with -the same License Elements, this version or later, or a BY-SA Compatible License. - -2. You must include the text of, or the URI or hyperlink to, the Adapter's -License You apply. You may satisfy this condition in any reasonable manner -based on the medium, means, and context in which You Share Adapted Material. - -3. You may not offer or impose any additional or different terms or conditions -on, or apply any Effective Technological Measures to, Adapted Material that -restrict exercise of the rights granted under the Adapter's License You apply. - -Section 4 – Sui Generis Database Rights. - -Where the Licensed Rights include Sui Generis Database Rights that apply to -Your use of the Licensed Material: - -a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, -reuse, reproduce, and Share all or a substantial portion of the contents of -the database; - -b. if You include all or a substantial portion of the database contents in -a database in which You have Sui Generis Database Rights, then the database -in which You have Sui Generis Database Rights (but not its individual contents) -is Adapted Material, including for purposes of Section 3(b); and - -c. You must comply with the conditions in Section 3(a) if You Share all or -a substantial portion of the contents of the database. -For the avoidance of doubt, this Section 4 supplements and does not replace -Your obligations under this Public License where the Licensed Rights include -other Copyright and Similar Rights. - -Section 5 – Disclaimer of Warranties and Limitation of Liability. - -a. Unless otherwise separately undertaken by the Licensor, to the extent possible, -the Licensor offers the Licensed Material as-is and as-available, and makes -no representations or warranties of any kind concerning the Licensed Material, -whether express, implied, statutory, or other. This includes, without limitation, -warranties of title, merchantability, fitness for a particular purpose, non-infringement, -absence of latent or other defects, accuracy, or the presence or absence of -errors, whether or not known or discoverable. Where disclaimers of warranties -are not allowed in full or in part, this disclaimer may not apply to You. - -b. To the extent possible, in no event will the Licensor be liable to You -on any legal theory (including, without limitation, negligence) or otherwise -for any direct, special, indirect, incidental, consequential, punitive, exemplary, -or other losses, costs, expenses, or damages arising out of this Public License -or use of the Licensed Material, even if the Licensor has been advised of -the possibility of such losses, costs, expenses, or damages. Where a limitation -of liability is not allowed in full or in part, this limitation may not apply -to You. - -c. The disclaimer of warranties and limitation of liability provided above -shall be interpreted in a manner that, to the extent possible, most closely -approximates an absolute disclaimer and waiver of all liability. - -Section 6 – Term and Termination. - -a. This Public License applies for the term of the Copyright and Similar Rights -licensed here. However, if You fail to comply with this Public License, then -Your rights under this Public License terminate automatically. - -b. Where Your right to use the Licensed Material has terminated under Section -6(a), it reinstates: - -1. automatically as of the date the violation is cured, provided it is cured -within 30 days of Your discovery of the violation; or - - 2. upon express reinstatement by the Licensor. - -c. For the avoidance of doubt, this Section 6(b) does not affect any right -the Licensor may have to seek remedies for Your violations of this Public -License. - -d. For the avoidance of doubt, the Licensor may also offer the Licensed Material -under separate terms or conditions or stop distributing the Licensed Material -at any time; however, doing so will not terminate this Public License. - - e. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. - -Section 7 – Other Terms and Conditions. - -a. The Licensor shall not be bound by any additional or different terms or -conditions communicated by You unless expressly agreed. - -b. Any arrangements, understandings, or agreements regarding the Licensed -Material not stated herein are separate from and independent of the terms -and conditions of this Public License. - -Section 8 – Interpretation. - -a. For the avoidance of doubt, this Public License does not, and shall not -be interpreted to, reduce, limit, restrict, or impose conditions on any use -of the Licensed Material that could lawfully be made without permission under -this Public License. - -b. To the extent possible, if any provision of this Public License is deemed -unenforceable, it shall be automatically reformed to the minimum extent necessary -to make it enforceable. If the provision cannot be reformed, it shall be severed -from this Public License without affecting the enforceability of the remaining -terms and conditions. - -c. No term or condition of this Public License will be waived and no failure -to comply consented to unless expressly agreed to by the Licensor. - -d. Nothing in this Public License constitutes or may be interpreted as a limitation -upon, or waiver of, any privileges and immunities that apply to the Licensor -or You, including from the legal processes of any jurisdiction or authority. - -Creative Commons is not a party to its public licenses. Notwithstanding, Creative -Commons may elect to apply one of its public licenses to material it publishes -and in those instances will be considered the “Licensor.” Except for the limited -purpose of indicating that material is shared under a Creative Commons public -license or as otherwise permitted by the Creative Commons policies published -at creativecommons.org/policies, Creative Commons does not authorize the use -of the trademark “Creative Commons” or any other trademark or logo of Creative -Commons without its prior written consent including, without limitation, in -connection with any unauthorized modifications to any of its public licenses -or any other arrangements, understandings, or agreements concerning use of -licensed material. For the avoidance of doubt, this paragraph does not form -part of the public licenses. - -Creative Commons may be contacted at creativecommons.org. diff --git a/LICENSES/GPL-2.0-only.txt b/LICENSES/GPL-2.0-only.txt deleted file mode 100644 index 3b6070fcd0c..00000000000 --- a/LICENSES/GPL-2.0-only.txt +++ /dev/null @@ -1,311 +0,0 @@ -GNU GENERAL PUBLIC LICENSE -Version 2, June 1991 - -Copyright (C) 1989, 1991 Free Software Foundation, Inc. -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - -Everyone is permitted to copy and distribute verbatim copies of this license -document, but changing it is not allowed. - -Preamble - -The licenses for most software are designed to take away your freedom to share -and change it. By contrast, the GNU General Public License is intended to -guarantee your freedom to share and change free software--to make sure the -software is free for all its users. This General Public License applies to -most of the Free Software Foundation's software and to any other program whose -authors commit to using it. (Some other Free Software Foundation software -is covered by the GNU Lesser General Public License instead.) You can apply -it to your programs, too. - -When we speak of free software, we are referring to freedom, not price. Our -General Public Licenses are designed to make sure that you have the freedom -to distribute copies of free software (and charge for this service if you -wish), that you receive source code or can get it if you want it, that you -can change the software or use pieces of it in new free programs; and that -you know you can do these things. - -To protect your rights, we need to make restrictions that forbid anyone to -deny you these rights or to ask you to surrender the rights. These restrictions -translate to certain responsibilities for you if you distribute copies of -the software, or if you modify it. - -For example, if you distribute copies of such a program, whether gratis or -for a fee, you must give the recipients all the rights that you have. You -must make sure that they, too, receive or can get the source code. And you -must show them these terms so they know their rights. - -We protect your rights with two steps: (1) copyright the software, and (2) -offer you this license which gives you legal permission to copy, distribute -and/or modify the software. - -Also, for each author's protection and ours, we want to make certain that -everyone understands that there is no warranty for this free software. If -the software is modified by someone else and passed on, we want its recipients -to know that what they have is not the original, so that any problems introduced -by others will not reflect on the original authors' reputations. - -Finally, any free program is threatened constantly by software patents. We -wish to avoid the danger that redistributors of a free program will individually -obtain patent licenses, in effect making the program proprietary. To prevent -this, we have made it clear that any patent must be licensed for everyone's -free use or not licensed at all. - -The precise terms and conditions for copying, distribution and modification -follow. - -TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - -0. This License applies to any program or other work which contains a notice -placed by the copyright holder saying it may be distributed under the terms -of this General Public License. The "Program", below, refers to any such program -or work, and a "work based on the Program" means either the Program or any -derivative work under copyright law: that is to say, a work containing the -Program or a portion of it, either verbatim or with modifications and/or translated -into another language. (Hereinafter, translation is included without limitation -in the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not covered -by this License; they are outside its scope. The act of running the Program -is not restricted, and the output from the Program is covered only if its -contents constitute a work based on the Program (independent of having been -made by running the Program). Whether that is true depends on what the Program -does. - -1. You may copy and distribute verbatim copies of the Program's source code -as you receive it, in any medium, provided that you conspicuously and appropriately -publish on each copy an appropriate copyright notice and disclaimer of warranty; -keep intact all the notices that refer to this License and to the absence -of any warranty; and give any other recipients of the Program a copy of this -License along with the Program. - -You may charge a fee for the physical act of transferring a copy, and you -may at your option offer warranty protection in exchange for a fee. - -2. You may modify your copy or copies of the Program or any portion of it, -thus forming a work based on the Program, and copy and distribute such modifications -or work under the terms of Section 1 above, provided that you also meet all -of these conditions: - -a) You must cause the modified files to carry prominent notices stating that -you changed the files and the date of any change. - -b) You must cause any work that you distribute or publish, that in whole or -in part contains or is derived from the Program or any part thereof, to be -licensed as a whole at no charge to all third parties under the terms of this -License. - -c) If the modified program normally reads commands interactively when run, -you must cause it, when started running for such interactive use in the most -ordinary way, to print or display an announcement including an appropriate -copyright notice and a notice that there is no warranty (or else, saying that -you provide a warranty) and that users may redistribute the program under -these conditions, and telling the user how to view a copy of this License. -(Exception: if the Program itself is interactive but does not normally print -such an announcement, your work based on the Program is not required to print -an announcement.) - -These requirements apply to the modified work as a whole. If identifiable -sections of that work are not derived from the Program, and can be reasonably -considered independent and separate works in themselves, then this License, -and its terms, do not apply to those sections when you distribute them as -separate works. But when you distribute the same sections as part of a whole -which is a work based on the Program, the distribution of the whole must be -on the terms of this License, whose permissions for other licensees extend -to the entire whole, and thus to each and every part regardless of who wrote -it. - -Thus, it is not the intent of this section to claim rights or contest your -rights to work written entirely by you; rather, the intent is to exercise -the right to control the distribution of derivative or collective works based -on the Program. - -In addition, mere aggregation of another work not based on the Program with -the Program (or with a work based on the Program) on a volume of a storage -or distribution medium does not bring the other work under the scope of this -License. - -3. You may copy and distribute the Program (or a work based on it, under Section -2) in object code or executable form under the terms of Sections 1 and 2 above -provided that you also do one of the following: - -a) Accompany it with the complete corresponding machine-readable source code, -which must be distributed under the terms of Sections 1 and 2 above on a medium -customarily used for software interchange; or, - -b) Accompany it with a written offer, valid for at least three years, to give -any third party, for a charge no more than your cost of physically performing -source distribution, a complete machine-readable copy of the corresponding -source code, to be distributed under the terms of Sections 1 and 2 above on -a medium customarily used for software interchange; or, - -c) Accompany it with the information you received as to the offer to distribute -corresponding source code. (This alternative is allowed only for noncommercial -distribution and only if you received the program in object code or executable -form with such an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for making -modifications to it. For an executable work, complete source code means all -the source code for all modules it contains, plus any associated interface -definition files, plus the scripts used to control compilation and installation -of the executable. However, as a special exception, the source code distributed -need not include anything that is normally distributed (in either source or -binary form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component itself -accompanies the executable. - -If distribution of executable or object code is made by offering access to -copy from a designated place, then offering equivalent access to copy the -source code from the same place counts as distribution of the source code, -even though third parties are not compelled to copy the source along with -the object code. - -4. You may not copy, modify, sublicense, or distribute the Program except -as expressly provided under this License. Any attempt otherwise to copy, modify, -sublicense or distribute the Program is void, and will automatically terminate -your rights under this License. However, parties who have received copies, -or rights, from you under this License will not have their licenses terminated -so long as such parties remain in full compliance. - -5. You are not required to accept this License, since you have not signed -it. However, nothing else grants you permission to modify or distribute the -Program or its derivative works. These actions are prohibited by law if you -do not accept this License. Therefore, by modifying or distributing the Program -(or any work based on the Program), you indicate your acceptance of this License -to do so, and all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - -6. Each time you redistribute the Program (or any work based on the Program), -the recipient automatically receives a license from the original licensor -to copy, distribute or modify the Program subject to these terms and conditions. -You may not impose any further restrictions on the recipients' exercise of -the rights granted herein. You are not responsible for enforcing compliance -by third parties to this License. - -7. If, as a consequence of a court judgment or allegation of patent infringement -or for any other reason (not limited to patent issues), conditions are imposed -on you (whether by court order, agreement or otherwise) that contradict the -conditions of this License, they do not excuse you from the conditions of -this License. If you cannot distribute so as to satisfy simultaneously your -obligations under this License and any other pertinent obligations, then as -a consequence you may not distribute the Program at all. For example, if a -patent license would not permit royalty-free redistribution of the Program -by all those who receive copies directly or indirectly through you, then the -only way you could satisfy both it and this License would be to refrain entirely -from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under any -particular circumstance, the balance of the section is intended to apply and -the section as a whole is intended to apply in other circumstances. - -It is not the purpose of this section to induce you to infringe any patents -or other property right claims or to contest validity of any such claims; -this section has the sole purpose of protecting the integrity of the free -software distribution system, which is implemented by public license practices. -Many people have made generous contributions to the wide range of software -distributed through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing to -distribute software through any other system and a licensee cannot impose -that choice. - -This section is intended to make thoroughly clear what is believed to be a -consequence of the rest of this License. - -8. If the distribution and/or use of the Program is restricted in certain -countries either by patents or by copyrighted interfaces, the original copyright -holder who places the Program under this License may add an explicit geographical -distribution limitation excluding those countries, so that distribution is -permitted only in or among countries not thus excluded. In such case, this -License incorporates the limitation as if written in the body of this License. - -9. The Free Software Foundation may publish revised and/or new versions of -the General Public License from time to time. Such new versions will be similar -in spirit to the present version, but may differ in detail to address new -problems or concerns. - -Each version is given a distinguishing version number. If the Program specifies -a version number of this License which applies to it and "any later version", -you have the option of following the terms and conditions either of that version -or of any later version published by the Free Software Foundation. If the -Program does not specify a version number of this License, you may choose -any version ever published by the Free Software Foundation. - -10. If you wish to incorporate parts of the Program into other free programs -whose distribution conditions are different, write to the author to ask for -permission. For software which is copyrighted by the Free Software Foundation, -write to the Free Software Foundation; we sometimes make exceptions for this. -Our decision will be guided by the two goals of preserving the free status -of all derivatives of our free software and of promoting the sharing and reuse -of software generally. - -NO WARRANTY - -11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR -THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE -STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM -"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, -BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS -FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE -OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME -THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - -12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE -THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY -GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE -OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA -OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES -OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH -HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -END OF TERMS AND CONDITIONS - -How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest possible -use to the public, the best way to achieve this is to make it free software -which everyone can redistribute and change under these terms. - -To do so, attach the following notices to the program. It is safest to attach -them to the start of each source file to most effectively convey the exclusion -of warranty; and each file should have at least the "copyright" line and a -pointer to where the full notice is found. - -one line to give the program's name and an idea of what it does. Copyright -(C) yyyy name of author - -This program is free software; you can redistribute it and/or modify it under -the terms of the GNU General Public License as published by the Free Software -Foundation; either version 2 of the License, or (at your option) any later -version. - -This program is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS -FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. - -You should have received a copy of the GNU General Public License along with -this program; if not, write to the Free Software Foundation, Inc., 51 Franklin -Street, Fifth Floor, Boston, MA 02110-1301, USA. Also add information on how -to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this when -it starts in an interactive mode: - -Gnomovision version 69, Copyright (C) year name of author Gnomovision comes -with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, -and you are welcome to redistribute it under certain conditions; type `show -c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may be -called something other than `show w' and `show c'; they could even be mouse-clicks -or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your school, -if any, to sign a "copyright disclaimer" for the program, if necessary. Here -is a sample; alter the names: - -Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' -(which makes passes at compilers) written by James Hacker. - -signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice diff --git a/LICENSES/GPL-2.0-or-later.txt b/LICENSES/GPL-2.0-or-later.txt deleted file mode 100644 index 3b6070fcd0c..00000000000 --- a/LICENSES/GPL-2.0-or-later.txt +++ /dev/null @@ -1,311 +0,0 @@ -GNU GENERAL PUBLIC LICENSE -Version 2, June 1991 - -Copyright (C) 1989, 1991 Free Software Foundation, Inc. -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - -Everyone is permitted to copy and distribute verbatim copies of this license -document, but changing it is not allowed. - -Preamble - -The licenses for most software are designed to take away your freedom to share -and change it. By contrast, the GNU General Public License is intended to -guarantee your freedom to share and change free software--to make sure the -software is free for all its users. This General Public License applies to -most of the Free Software Foundation's software and to any other program whose -authors commit to using it. (Some other Free Software Foundation software -is covered by the GNU Lesser General Public License instead.) You can apply -it to your programs, too. - -When we speak of free software, we are referring to freedom, not price. Our -General Public Licenses are designed to make sure that you have the freedom -to distribute copies of free software (and charge for this service if you -wish), that you receive source code or can get it if you want it, that you -can change the software or use pieces of it in new free programs; and that -you know you can do these things. - -To protect your rights, we need to make restrictions that forbid anyone to -deny you these rights or to ask you to surrender the rights. These restrictions -translate to certain responsibilities for you if you distribute copies of -the software, or if you modify it. - -For example, if you distribute copies of such a program, whether gratis or -for a fee, you must give the recipients all the rights that you have. You -must make sure that they, too, receive or can get the source code. And you -must show them these terms so they know their rights. - -We protect your rights with two steps: (1) copyright the software, and (2) -offer you this license which gives you legal permission to copy, distribute -and/or modify the software. - -Also, for each author's protection and ours, we want to make certain that -everyone understands that there is no warranty for this free software. If -the software is modified by someone else and passed on, we want its recipients -to know that what they have is not the original, so that any problems introduced -by others will not reflect on the original authors' reputations. - -Finally, any free program is threatened constantly by software patents. We -wish to avoid the danger that redistributors of a free program will individually -obtain patent licenses, in effect making the program proprietary. To prevent -this, we have made it clear that any patent must be licensed for everyone's -free use or not licensed at all. - -The precise terms and conditions for copying, distribution and modification -follow. - -TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - -0. This License applies to any program or other work which contains a notice -placed by the copyright holder saying it may be distributed under the terms -of this General Public License. The "Program", below, refers to any such program -or work, and a "work based on the Program" means either the Program or any -derivative work under copyright law: that is to say, a work containing the -Program or a portion of it, either verbatim or with modifications and/or translated -into another language. (Hereinafter, translation is included without limitation -in the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not covered -by this License; they are outside its scope. The act of running the Program -is not restricted, and the output from the Program is covered only if its -contents constitute a work based on the Program (independent of having been -made by running the Program). Whether that is true depends on what the Program -does. - -1. You may copy and distribute verbatim copies of the Program's source code -as you receive it, in any medium, provided that you conspicuously and appropriately -publish on each copy an appropriate copyright notice and disclaimer of warranty; -keep intact all the notices that refer to this License and to the absence -of any warranty; and give any other recipients of the Program a copy of this -License along with the Program. - -You may charge a fee for the physical act of transferring a copy, and you -may at your option offer warranty protection in exchange for a fee. - -2. You may modify your copy or copies of the Program or any portion of it, -thus forming a work based on the Program, and copy and distribute such modifications -or work under the terms of Section 1 above, provided that you also meet all -of these conditions: - -a) You must cause the modified files to carry prominent notices stating that -you changed the files and the date of any change. - -b) You must cause any work that you distribute or publish, that in whole or -in part contains or is derived from the Program or any part thereof, to be -licensed as a whole at no charge to all third parties under the terms of this -License. - -c) If the modified program normally reads commands interactively when run, -you must cause it, when started running for such interactive use in the most -ordinary way, to print or display an announcement including an appropriate -copyright notice and a notice that there is no warranty (or else, saying that -you provide a warranty) and that users may redistribute the program under -these conditions, and telling the user how to view a copy of this License. -(Exception: if the Program itself is interactive but does not normally print -such an announcement, your work based on the Program is not required to print -an announcement.) - -These requirements apply to the modified work as a whole. If identifiable -sections of that work are not derived from the Program, and can be reasonably -considered independent and separate works in themselves, then this License, -and its terms, do not apply to those sections when you distribute them as -separate works. But when you distribute the same sections as part of a whole -which is a work based on the Program, the distribution of the whole must be -on the terms of this License, whose permissions for other licensees extend -to the entire whole, and thus to each and every part regardless of who wrote -it. - -Thus, it is not the intent of this section to claim rights or contest your -rights to work written entirely by you; rather, the intent is to exercise -the right to control the distribution of derivative or collective works based -on the Program. - -In addition, mere aggregation of another work not based on the Program with -the Program (or with a work based on the Program) on a volume of a storage -or distribution medium does not bring the other work under the scope of this -License. - -3. You may copy and distribute the Program (or a work based on it, under Section -2) in object code or executable form under the terms of Sections 1 and 2 above -provided that you also do one of the following: - -a) Accompany it with the complete corresponding machine-readable source code, -which must be distributed under the terms of Sections 1 and 2 above on a medium -customarily used for software interchange; or, - -b) Accompany it with a written offer, valid for at least three years, to give -any third party, for a charge no more than your cost of physically performing -source distribution, a complete machine-readable copy of the corresponding -source code, to be distributed under the terms of Sections 1 and 2 above on -a medium customarily used for software interchange; or, - -c) Accompany it with the information you received as to the offer to distribute -corresponding source code. (This alternative is allowed only for noncommercial -distribution and only if you received the program in object code or executable -form with such an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for making -modifications to it. For an executable work, complete source code means all -the source code for all modules it contains, plus any associated interface -definition files, plus the scripts used to control compilation and installation -of the executable. However, as a special exception, the source code distributed -need not include anything that is normally distributed (in either source or -binary form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component itself -accompanies the executable. - -If distribution of executable or object code is made by offering access to -copy from a designated place, then offering equivalent access to copy the -source code from the same place counts as distribution of the source code, -even though third parties are not compelled to copy the source along with -the object code. - -4. You may not copy, modify, sublicense, or distribute the Program except -as expressly provided under this License. Any attempt otherwise to copy, modify, -sublicense or distribute the Program is void, and will automatically terminate -your rights under this License. However, parties who have received copies, -or rights, from you under this License will not have their licenses terminated -so long as such parties remain in full compliance. - -5. You are not required to accept this License, since you have not signed -it. However, nothing else grants you permission to modify or distribute the -Program or its derivative works. These actions are prohibited by law if you -do not accept this License. Therefore, by modifying or distributing the Program -(or any work based on the Program), you indicate your acceptance of this License -to do so, and all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - -6. Each time you redistribute the Program (or any work based on the Program), -the recipient automatically receives a license from the original licensor -to copy, distribute or modify the Program subject to these terms and conditions. -You may not impose any further restrictions on the recipients' exercise of -the rights granted herein. You are not responsible for enforcing compliance -by third parties to this License. - -7. If, as a consequence of a court judgment or allegation of patent infringement -or for any other reason (not limited to patent issues), conditions are imposed -on you (whether by court order, agreement or otherwise) that contradict the -conditions of this License, they do not excuse you from the conditions of -this License. If you cannot distribute so as to satisfy simultaneously your -obligations under this License and any other pertinent obligations, then as -a consequence you may not distribute the Program at all. For example, if a -patent license would not permit royalty-free redistribution of the Program -by all those who receive copies directly or indirectly through you, then the -only way you could satisfy both it and this License would be to refrain entirely -from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under any -particular circumstance, the balance of the section is intended to apply and -the section as a whole is intended to apply in other circumstances. - -It is not the purpose of this section to induce you to infringe any patents -or other property right claims or to contest validity of any such claims; -this section has the sole purpose of protecting the integrity of the free -software distribution system, which is implemented by public license practices. -Many people have made generous contributions to the wide range of software -distributed through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing to -distribute software through any other system and a licensee cannot impose -that choice. - -This section is intended to make thoroughly clear what is believed to be a -consequence of the rest of this License. - -8. If the distribution and/or use of the Program is restricted in certain -countries either by patents or by copyrighted interfaces, the original copyright -holder who places the Program under this License may add an explicit geographical -distribution limitation excluding those countries, so that distribution is -permitted only in or among countries not thus excluded. In such case, this -License incorporates the limitation as if written in the body of this License. - -9. The Free Software Foundation may publish revised and/or new versions of -the General Public License from time to time. Such new versions will be similar -in spirit to the present version, but may differ in detail to address new -problems or concerns. - -Each version is given a distinguishing version number. If the Program specifies -a version number of this License which applies to it and "any later version", -you have the option of following the terms and conditions either of that version -or of any later version published by the Free Software Foundation. If the -Program does not specify a version number of this License, you may choose -any version ever published by the Free Software Foundation. - -10. If you wish to incorporate parts of the Program into other free programs -whose distribution conditions are different, write to the author to ask for -permission. For software which is copyrighted by the Free Software Foundation, -write to the Free Software Foundation; we sometimes make exceptions for this. -Our decision will be guided by the two goals of preserving the free status -of all derivatives of our free software and of promoting the sharing and reuse -of software generally. - -NO WARRANTY - -11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR -THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE -STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM -"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, -BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS -FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE -OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME -THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - -12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE -THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY -GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE -OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA -OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES -OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH -HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -END OF TERMS AND CONDITIONS - -How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest possible -use to the public, the best way to achieve this is to make it free software -which everyone can redistribute and change under these terms. - -To do so, attach the following notices to the program. It is safest to attach -them to the start of each source file to most effectively convey the exclusion -of warranty; and each file should have at least the "copyright" line and a -pointer to where the full notice is found. - -one line to give the program's name and an idea of what it does. Copyright -(C) yyyy name of author - -This program is free software; you can redistribute it and/or modify it under -the terms of the GNU General Public License as published by the Free Software -Foundation; either version 2 of the License, or (at your option) any later -version. - -This program is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS -FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. - -You should have received a copy of the GNU General Public License along with -this program; if not, write to the Free Software Foundation, Inc., 51 Franklin -Street, Fifth Floor, Boston, MA 02110-1301, USA. Also add information on how -to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this when -it starts in an interactive mode: - -Gnomovision version 69, Copyright (C) year name of author Gnomovision comes -with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, -and you are welcome to redistribute it under certain conditions; type `show -c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may be -called something other than `show w' and `show c'; they could even be mouse-clicks -or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your school, -if any, to sign a "copyright disclaimer" for the program, if necessary. Here -is a sample; alter the names: - -Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' -(which makes passes at compilers) written by James Hacker. - -signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice diff --git a/LICENSES/LicenseRef-Trademark.txt b/LICENSES/LicenseRef-Trademark.txt deleted file mode 100644 index 03cb00b4d79..00000000000 --- a/LICENSES/LicenseRef-Trademark.txt +++ /dev/null @@ -1,5 +0,0 @@ -For license and usage guidelines on the seL4 trademark and logo, -including the seL4 Foundation logo, see -https://sel4.systems/Foundation/Trademark/ - -No further license is granted from use in this repository. diff --git a/LICENSES/MIT.txt b/LICENSES/MIT.txt deleted file mode 100644 index f0fd20ab686..00000000000 --- a/LICENSES/MIT.txt +++ /dev/null @@ -1,20 +0,0 @@ -MIT License - -Copyright (c) - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is furnished -to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS -FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS -OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF -OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/LICENSES/MPL-2.0.txt b/LICENSES/MPL-2.0.txt deleted file mode 100644 index d0a1fa1482e..00000000000 --- a/LICENSES/MPL-2.0.txt +++ /dev/null @@ -1,373 +0,0 @@ -Mozilla Public License Version 2.0 -================================== - -1. Definitions --------------- - -1.1. "Contributor" - means each individual or legal entity that creates, contributes to - the creation of, or owns Covered Software. - -1.2. "Contributor Version" - means the combination of the Contributions of others (if any) used - by a Contributor and that particular Contributor's Contribution. - -1.3. "Contribution" - means Covered Software of a particular Contributor. - -1.4. "Covered Software" - means Source Code Form to which the initial Contributor has attached - the notice in Exhibit A, the Executable Form of such Source Code - Form, and Modifications of such Source Code Form, in each case - including portions thereof. - -1.5. "Incompatible With Secondary Licenses" - means - - (a) that the initial Contributor has attached the notice described - in Exhibit B to the Covered Software; or - - (b) that the Covered Software was made available under the terms of - version 1.1 or earlier of the License, but not also under the - terms of a Secondary License. - -1.6. "Executable Form" - means any form of the work other than Source Code Form. - -1.7. "Larger Work" - means a work that combines Covered Software with other material, in - a separate file or files, that is not Covered Software. - -1.8. "License" - means this document. - -1.9. "Licensable" - means having the right to grant, to the maximum extent possible, - whether at the time of the initial grant or subsequently, any and - all of the rights conveyed by this License. - -1.10. "Modifications" - means any of the following: - - (a) any file in Source Code Form that results from an addition to, - deletion from, or modification of the contents of Covered - Software; or - - (b) any new file in Source Code Form that contains any Covered - Software. - -1.11. "Patent Claims" of a Contributor - means any patent claim(s), including without limitation, method, - process, and apparatus claims, in any patent Licensable by such - Contributor that would be infringed, but for the grant of the - License, by the making, using, selling, offering for sale, having - made, import, or transfer of either its Contributions or its - Contributor Version. - -1.12. "Secondary License" - means either the GNU General Public License, Version 2.0, the GNU - Lesser General Public License, Version 2.1, the GNU Affero General - Public License, Version 3.0, or any later versions of those - licenses. - -1.13. "Source Code Form" - means the form of the work preferred for making modifications. - -1.14. "You" (or "Your") - means an individual or a legal entity exercising rights under this - License. For legal entities, "You" includes any entity that - controls, is controlled by, or is under common control with You. For - purposes of this definition, "control" means (a) the power, direct - or indirect, to cause the direction or management of such entity, - whether by contract or otherwise, or (b) ownership of more than - fifty percent (50%) of the outstanding shares or beneficial - ownership of such entity. - -2. License Grants and Conditions --------------------------------- - -2.1. Grants - -Each Contributor hereby grants You a world-wide, royalty-free, -non-exclusive license: - -(a) under intellectual property rights (other than patent or trademark) - Licensable by such Contributor to use, reproduce, make available, - modify, display, perform, distribute, and otherwise exploit its - Contributions, either on an unmodified basis, with Modifications, or - as part of a Larger Work; and - -(b) under Patent Claims of such Contributor to make, use, sell, offer - for sale, have made, import, and otherwise transfer either its - Contributions or its Contributor Version. - -2.2. Effective Date - -The licenses granted in Section 2.1 with respect to any Contribution -become effective for each Contribution on the date the Contributor first -distributes such Contribution. - -2.3. Limitations on Grant Scope - -The licenses granted in this Section 2 are the only rights granted under -this License. No additional rights or licenses will be implied from the -distribution or licensing of Covered Software under this License. -Notwithstanding Section 2.1(b) above, no patent license is granted by a -Contributor: - -(a) for any code that a Contributor has removed from Covered Software; - or - -(b) for infringements caused by: (i) Your and any other third party's - modifications of Covered Software, or (ii) the combination of its - Contributions with other software (except as part of its Contributor - Version); or - -(c) under Patent Claims infringed by Covered Software in the absence of - its Contributions. - -This License does not grant any rights in the trademarks, service marks, -or logos of any Contributor (except as may be necessary to comply with -the notice requirements in Section 3.4). - -2.4. Subsequent Licenses - -No Contributor makes additional grants as a result of Your choice to -distribute the Covered Software under a subsequent version of this -License (see Section 10.2) or under the terms of a Secondary License (if -permitted under the terms of Section 3.3). - -2.5. Representation - -Each Contributor represents that the Contributor believes its -Contributions are its original creation(s) or it has sufficient rights -to grant the rights to its Contributions conveyed by this License. - -2.6. Fair Use - -This License is not intended to limit any rights You have under -applicable copyright doctrines of fair use, fair dealing, or other -equivalents. - -2.7. Conditions - -Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted -in Section 2.1. - -3. Responsibilities -------------------- - -3.1. Distribution of Source Form - -All distribution of Covered Software in Source Code Form, including any -Modifications that You create or to which You contribute, must be under -the terms of this License. You must inform recipients that the Source -Code Form of the Covered Software is governed by the terms of this -License, and how they can obtain a copy of this License. You may not -attempt to alter or restrict the recipients' rights in the Source Code -Form. - -3.2. Distribution of Executable Form - -If You distribute Covered Software in Executable Form then: - -(a) such Covered Software must also be made available in Source Code - Form, as described in Section 3.1, and You must inform recipients of - the Executable Form how they can obtain a copy of such Source Code - Form by reasonable means in a timely manner, at a charge no more - than the cost of distribution to the recipient; and - -(b) You may distribute such Executable Form under the terms of this - License, or sublicense it under different terms, provided that the - license for the Executable Form does not attempt to limit or alter - the recipients' rights in the Source Code Form under this License. - -3.3. Distribution of a Larger Work - -You may create and distribute a Larger Work under terms of Your choice, -provided that You also comply with the requirements of this License for -the Covered Software. If the Larger Work is a combination of Covered -Software with a work governed by one or more Secondary Licenses, and the -Covered Software is not Incompatible With Secondary Licenses, this -License permits You to additionally distribute such Covered Software -under the terms of such Secondary License(s), so that the recipient of -the Larger Work may, at their option, further distribute the Covered -Software under the terms of either this License or such Secondary -License(s). - -3.4. Notices - -You may not remove or alter the substance of any license notices -(including copyright notices, patent notices, disclaimers of warranty, -or limitations of liability) contained within the Source Code Form of -the Covered Software, except that You may alter any license notices to -the extent required to remedy known factual inaccuracies. - -3.5. Application of Additional Terms - -You may choose to offer, and to charge a fee for, warranty, support, -indemnity or liability obligations to one or more recipients of Covered -Software. However, You may do so only on Your own behalf, and not on -behalf of any Contributor. You must make it absolutely clear that any -such warranty, support, indemnity, or liability obligation is offered by -You alone, and You hereby agree to indemnify every Contributor for any -liability incurred by such Contributor as a result of warranty, support, -indemnity or liability terms You offer. You may include additional -disclaimers of warranty and limitations of liability specific to any -jurisdiction. - -4. Inability to Comply Due to Statute or Regulation ---------------------------------------------------- - -If it is impossible for You to comply with any of the terms of this -License with respect to some or all of the Covered Software due to -statute, judicial order, or regulation then You must: (a) comply with -the terms of this License to the maximum extent possible; and (b) -describe the limitations and the code they affect. Such description must -be placed in a text file included with all distributions of the Covered -Software under this License. Except to the extent prohibited by statute -or regulation, such description must be sufficiently detailed for a -recipient of ordinary skill to be able to understand it. - -5. Termination --------------- - -5.1. The rights granted under this License will terminate automatically -if You fail to comply with any of its terms. However, if You become -compliant, then the rights granted under this License from a particular -Contributor are reinstated (a) provisionally, unless and until such -Contributor explicitly and finally terminates Your grants, and (b) on an -ongoing basis, if such Contributor fails to notify You of the -non-compliance by some reasonable means prior to 60 days after You have -come back into compliance. Moreover, Your grants from a particular -Contributor are reinstated on an ongoing basis if such Contributor -notifies You of the non-compliance by some reasonable means, this is the -first time You have received notice of non-compliance with this License -from such Contributor, and You become compliant prior to 30 days after -Your receipt of the notice. - -5.2. If You initiate litigation against any entity by asserting a patent -infringement claim (excluding declaratory judgment actions, -counter-claims, and cross-claims) alleging that a Contributor Version -directly or indirectly infringes any patent, then the rights granted to -You by any and all Contributors for the Covered Software under Section -2.1 of this License shall terminate. - -5.3. In the event of termination under Sections 5.1 or 5.2 above, all -end user license agreements (excluding distributors and resellers) which -have been validly granted by You or Your distributors under this License -prior to termination shall survive termination. - -************************************************************************ -* * -* 6. Disclaimer of Warranty * -* ------------------------- * -* * -* Covered Software is provided under this License on an "as is" * -* basis, without warranty of any kind, either expressed, implied, or * -* statutory, including, without limitation, warranties that the * -* Covered Software is free of defects, merchantable, fit for a * -* particular purpose or non-infringing. The entire risk as to the * -* quality and performance of the Covered Software is with You. * -* Should any Covered Software prove defective in any respect, You * -* (not any Contributor) assume the cost of any necessary servicing, * -* repair, or correction. This disclaimer of warranty constitutes an * -* essential part of this License. No use of any Covered Software is * -* authorized under this License except under this disclaimer. * -* * -************************************************************************ - -************************************************************************ -* * -* 7. Limitation of Liability * -* -------------------------- * -* * -* Under no circumstances and under no legal theory, whether tort * -* (including negligence), contract, or otherwise, shall any * -* Contributor, or anyone who distributes Covered Software as * -* permitted above, be liable to You for any direct, indirect, * -* special, incidental, or consequential damages of any character * -* including, without limitation, damages for lost profits, loss of * -* goodwill, work stoppage, computer failure or malfunction, or any * -* and all other commercial damages or losses, even if such party * -* shall have been informed of the possibility of such damages. This * -* limitation of liability shall not apply to liability for death or * -* personal injury resulting from such party's negligence to the * -* extent applicable law prohibits such limitation. Some * -* jurisdictions do not allow the exclusion or limitation of * -* incidental or consequential damages, so this exclusion and * -* limitation may not apply to You. * -* * -************************************************************************ - -8. Litigation -------------- - -Any litigation relating to this License may be brought only in the -courts of a jurisdiction where the defendant maintains its principal -place of business and such litigation shall be governed by laws of that -jurisdiction, without reference to its conflict-of-law provisions. -Nothing in this Section shall prevent a party's ability to bring -cross-claims or counter-claims. - -9. Miscellaneous ----------------- - -This License represents the complete agreement concerning the subject -matter hereof. If any provision of this License is held to be -unenforceable, such provision shall be reformed only to the extent -necessary to make it enforceable. Any law or regulation which provides -that the language of a contract shall be construed against the drafter -shall not be used to construe this License against a Contributor. - -10. Versions of the License ---------------------------- - -10.1. New Versions - -Mozilla Foundation is the license steward. Except as provided in Section -10.3, no one other than the license steward has the right to modify or -publish new versions of this License. Each version will be given a -distinguishing version number. - -10.2. Effect of New Versions - -You may distribute the Covered Software under the terms of the version -of the License under which You originally received the Covered Software, -or under the terms of any subsequent version published by the license -steward. - -10.3. Modified Versions - -If you create software not governed by this License, and you want to -create a new license for such software, you may create and use a -modified version of this License if you rename the license and remove -any references to the name of the license steward (except to note that -such modified license differs from this License). - -10.4. Distributing Source Code Form that is Incompatible With Secondary -Licenses - -If You choose to distribute Source Code Form that is Incompatible With -Secondary Licenses under the terms of this version of the License, the -notice described in Exhibit B of this License must be attached. - -Exhibit A - Source Code Form License Notice -------------------------------------------- - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at https://mozilla.org/MPL/2.0/. - -If it is not possible or desirable to put the notice in a particular -file, then You may include the notice in a location (such as a LICENSE -file in a relevant directory) where a recipient would be likely to look -for such a notice. - -You may add additional accurate notices of copyright ownership. - -Exhibit B - "Incompatible With Secondary Licenses" Notice ---------------------------------------------------------- - - This Source Code Form is "Incompatible With Secondary Licenses", as - defined by the Mozilla Public License, v. 2.0. diff --git a/LevelConverter.html b/LevelConverter.html new file mode 100644 index 00000000000..2a33d84355f --- /dev/null +++ b/LevelConverter.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Makefile b/Makefile deleted file mode 100644 index fbd1625c7f3..00000000000 --- a/Makefile +++ /dev/null @@ -1,451 +0,0 @@ -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. -# SPDX-License-Identifier: BSD-2-Clause - -.PHONY: default -default: help - -.PHONY: help -help: - @echo "Makefile for the seL4 docsite" - @echo "Useful targets:" - @echo " serve - Serve a preview the site locally using Jekyll" - @echo " build - Build the site for production in _site" - @echo " preview - Build the site for externally hosted preview in _preview" - @echo " docker_serve - Serve a preview of the site using Docker" - @echo " docker_build - Build the site using Docker" - @echo " check_conformance_errors - Check for conformance and show errors" - @echo " check_liquid_syntax - Check the liquid syntax of the templates" - @echo " check_html_output - Check the HTML output using tidy" - @echo " checklinks - Runs html-proofer to check for broken links." - @echo " validate - Runs html5validator to check for HTML5 compliance." - -.PHONY: ruby_deps -ruby_deps: .jekyll-cache/ruby_deps - -.jekyll-cache/ruby_deps: Gemfile Gemfile.lock - bundle install - @mkdir -p .jekyll-cache/ - @touch $@ - -.npm_deps: package.json package-lock.json - npm install - @touch $@ - -# The following rules generate a yaml file that contains file modification metadata -# provided by git. The format is: -# -# date: Tue Mar 13 19:11:51 2018 +1100 -# timestamps: -# - page: BuildSystemAnatomy/index.md -# date: Tue Mar 13 19:11:51 2018 +1100 -# - page: CAmkESDifferences.md -# date: Tue Mar 13 19:11:51 2018 +1100 -# ... -# If this prebuild _data generation step gets more complicated then it should -# probably be moved to a python script. - -FILE_NAME=_data/generated.yml - -UPDATE_DATE:= $(shell git log -1 --format='%cd %h') -FILES:= $(shell find . -iname "*.md" | grep -ve "./README.md" | grep -ve "^./_repos/"| sed 's/.\///') - -.PHONY: _data/generated.yml -_data/generated.yml: - echo "date: $(UPDATE_DATE)" > $(FILE_NAME) - echo timestamps: >> $(FILE_NAME) && \ - for i in $(FILES); do \ - echo " - page: $$i" >> $(FILE_NAME) &&\ - echo " date: `git log -1 --format='%cd %h' -- $$i`" >> $(FILE_NAME); \ - done - -.PHONY: generate_data_files -generate_data_files: _data/generated.yml - -GIT_REPOS:=$(shell (cd _data/projects && for i in `ls *.yml`; do cat $$i | ../../tools/get_repos.py ; done) | sort -u) -REPOSITORIES = $(GIT_REPOS:%=_repos/%) - -$(REPOSITORIES): - mkdir -p $@ - git clone --depth=1 --recursive https://github.com/$(@:_repos/%=%) $@ - -.PHONY: repos -repos: $(REPOSITORIES) - -# Microkit - -MICROKIT_REPO = _repos/sel4/microkit -$(MICROKIT_REPO)/platforms.yml: $(MICROKIT_REPO) - -_data/microkit_platforms.yml: $(MICROKIT_REPO)/platforms.yml - cp $< $@ - -.PHONY: microkit -microkit: _data/microkit_platforms.yml - -# Tutorials - -TUTES_DST = _processed/tutes -TUTES_REPO = _repos/sel4/sel4-tutorials -TUTES_SRC = $(TUTES_REPO)/tutorials - -$(TUTES_DST): - mkdir -p $@ - -TUTORIAL_FILES := \ - hello-world \ - capabilities \ - untyped \ - ipc \ - interrupts \ - mapping \ - threads \ - notifications \ - mcs \ - fault-handlers \ - hello-camkes-0 \ - hello-camkes-1 \ - hello-camkes-2 \ - hello-camkes-timer \ - camkes-vm-crossvm \ - camkes-vm-linux \ - libraries-1 \ - libraries-2 \ - libraries-3 \ - libraries-4 - -$(TUTES_DST)/hello-world.md: $(TUTES_SRC)/hello-world/hello-world.md -$(TUTES_DST)/capabilities.md: $(TUTES_SRC)/capabilities/capabilities.md -$(TUTES_DST)/untyped.md: $(TUTES_SRC)/untyped/untyped.md -$(TUTES_DST)/ipc.md: $(TUTES_SRC)/ipc/ipc.md -$(TUTES_DST)/mapping.md: $(TUTES_SRC)/mapping/mapping.md -$(TUTES_DST)/threads.md: $(TUTES_SRC)/threads/threads.md -$(TUTES_DST)/notifications.md: $(TUTES_SRC)/notifications/notifications.md -$(TUTES_DST)/mcs.md: $(TUTES_SRC)/mcs/mcs.md -$(TUTES_DST)/fault-handlers.md: $(TUTES_SRC)/fault-handlers/fault-handlers.md -$(TUTES_DST)/hello-camkes-0.md: $(TUTES_SRC)/hello-camkes-0/hello-camkes-0.md -$(TUTES_DST)/hello-camkes-1.md: $(TUTES_SRC)/hello-camkes-1/hello-camkes-1.md -$(TUTES_DST)/hello-camkes-2.md: $(TUTES_SRC)/hello-camkes-2/hello-camkes-2.md -$(TUTES_DST)/hello-camkes-timer.md: $(TUTES_SRC)/hello-camkes-timer/hello-camkes-timer.md -$(TUTES_DST)/camkes-vm-crossvm.md: $(TUTES_SRC)/camkes-vm-crossvm/camkes-vm-crossvm.md -$(TUTES_DST)/camkes-vm-linux.md: $(TUTES_SRC)/camkes-vm-linux/camkes-vm-linux.md -$(TUTES_DST)/interrupts.md: $(TUTES_SRC)/interrupts/interrupts.md -$(TUTES_DST)/libraries-1.md: $(TUTES_SRC)/libraries-1/libraries-1.md -$(TUTES_DST)/libraries-2.md: $(TUTES_SRC)/libraries-2/libraries-2.md -$(TUTES_DST)/libraries-3.md: $(TUTES_SRC)/libraries-3/libraries-3.md -$(TUTES_DST)/libraries-4.md: $(TUTES_SRC)/libraries-4/libraries-4.md - -TUTORIALS := $(TUTORIAL_FILES:%=$(TUTES_DST)/%.md) -$(TUTORIALS): - @if [ -z "$<" ]; then echo "No dependency specified for $@"; exit 1; fi - @echo "$< ==> $@" - @PYTHONPATH=_repos/sel4/capdl/python-capdl-tool \ - $(TUTES_REPO)/template.py --docsite --out-dir $(TUTES_DST) --tut-file $< - -.PHONY: tutorials -tutorials: $(TUTES_DST) $(TUTORIALS) - -PROCESS_MDBOOK = tools/process-mdbook.py -MICROKIT_TUT_DST = _processed/microkit-tutorial -MICROKIT_TUT_DOC = projects/microkit/tutorial -MICROKIT_TUT_REPO = _repos/au-ts/microkit_tutorial -MICROKIT_TUT_SRC = $(MICROKIT_TUT_REPO)/website/src -# wildcard on files in this repo under projects/microkit to avoid empty wildcard -# when _repos does not exist yet -MICROKIT_TUT_DOC_FILES = $(wildcard $(MICROKIT_TUT_DOC)/*.md) -MICROKIT_TUT_SRC_FILES = $(patsubst $(MICROKIT_TUT_DOC)/%, $(MICROKIT_TUT_SRC)/%, $(MICROKIT_TUT_DOC_FILES)) -MICROKIT_TUT_DST_FILES = $(patsubst $(MICROKIT_TUT_DOC)/%, $(MICROKIT_TUT_DST)/%, $(MICROKIT_TUT_DOC_FILES)) - -# Make sure `make` knows how to build $(MICROKIT_TUT_DST)/%.md if _repos does not exist yet. -# It is not enough for the repos to be cloned before the rule fires -- the implicit rule will only -# fire if it has a complete path to the source when the Makefile is first invoked. -$(MICROKIT_TUT_SRC_FILES) $(MICROKIT_TUT_SRC)/../build.sh: $(MICROKIT_TUT_REPO) - -$(MICROKIT_TUT_DST)/%.md: $(MICROKIT_TUT_SRC)/%.md - @echo "$< ==> $@" - @$(PROCESS_MDBOOK) $< $(dir $@) - -_data/microkit_tutorial.yml: $(MICROKIT_TUT_SRC)/../build.sh - @tools/mk_tutorial_vars.sh $< $@ - -.PHONY: microkit-tutorial -microkit-tutorial: $(MICROKIT_TUT_DST_FILES) _data/microkit_tutorial.yml - -RUST_TUT_REPO = _repos/sel4/sel4-rust-tutorial -RUST_TUT_BOOK = $(RUST_TUT_REPO)/book -RUST_TUT_BUILD = $(RUST_TUT_BOOK)/build -RUST_TUT_DST = _processed/rust/tutorial -RUST_TUT_FINAL_DST = projects/rust/tutorial - -$(RUST_TUT_DST): $(RUST_TUT_REPO) - SITE_URL="/projects/rust/tutorial/" \ - RUSTDOC_URL="https://sel4.github.io/seL4-rust-tutorial/rustdoc" \ - make -C $(RUST_TUT_BOOK) build - rm -rf $(RUST_TUT_DST) - mkdir -p $(dir $(RUST_TUT_DST)) - cp -rL $(RUST_TUT_BUILD) $(RUST_TUT_DST) - tools/inject_backlink.sh $(RUST_TUT_DST) - -.PHONY: rust-tutorial -rust-tutorial: $(RUST_TUT_DST) - -.PHONY: _generate_api_pages -_generate_api_pages: _repos/sel4/sel4 - $(MAKE) markdown -C _repos/sel4/sel4/manual - -PROJECT_LIBS_REPO = _repos/sel4/sel4_projects_libs -LIBSEL4VM_SRC = $(PROJECT_LIBS_REPO)/libsel4vm/docs -LIBSEL4VM_DST = projects/virtualization/docs/api -# Does not use wildcard, because _repos may not exist yet and the wildcard would then be empty. -LIBSEL4VM_FILES = \ - libsel4vm_arm_guest_vm.md \ - libsel4vm_boot.md \ - libsel4vm_guest_arm_context.md \ - libsel4vm_guest_iospace.md \ - libsel4vm_guest_irq_controller.md \ - libsel4vm_guest_memory_helpers.md \ - libsel4vm_guest_memory.md \ - libsel4vm_guest_ram.md \ - libsel4vm_guest_vcpu_fault.md \ - libsel4vm_guest_vm_util.md \ - libsel4vm_guest_vm.md \ - libsel4vm_guest_x86_context.md \ - libsel4vm_x86_guest_vm.md \ - libsel4vm_x86_ioports.md \ - libsel4vm_x86_vmcall.md -LIBSEL4VM_SRC_FILES = $(patsubst %, $(LIBSEL4VM_SRC)/%, $(LIBSEL4VM_FILES)) -LIBSEL4VM_DST_FILES = $(patsubst %, $(LIBSEL4VM_DST)/%, $(LIBSEL4VM_FILES)) - -$(LIBSEL4VM_SRC_FILES): $(PROJECT_LIBS_REPO) - -$(LIBSEL4VM_DST)/%.md: $(LIBSEL4VM_SRC)/%.md - @echo "$< ==> $@" - @tools/gen_markdown_api_doc.py -f $< -o $@ -p libsel4vm.html - -$(LIBSEL4VM_DST): - mkdir -p $@ - -.PHONY: generate_libsel4vm_api -generate_libsel4vm_api: $(LIBSEL4VM_DST) $(LIBSEL4VM_DST_FILES) - -LIBSEL4VMM_SRC = $(PROJECT_LIBS_REPO)/libsel4vmmplatsupport/docs -# Does not use wildcard, because _repos may not exist yet and the wildcard would then be empty. -LIBSEL4VMM_FILES = \ - libsel4vmmplatsupport_arm_ac_device.md \ - libsel4vmmplatsupport_arm_generic_forward_device.md \ - libsel4vmmplatsupport_arm_guest_boot_init.md \ - libsel4vmmplatsupport_arm_guest_reboot.md \ - libsel4vmmplatsupport_arm_guest_vcpu_fault.md \ - libsel4vmmplatsupport_arm_guest_vcpu_util.md \ - libsel4vmmplatsupport_arm_vpci.md \ - libsel4vmmplatsupport_arm_vusb.md \ - libsel4vmmplatsupport_cross_vm_connection.md \ - libsel4vmmplatsupport_device_utils.md \ - libsel4vmmplatsupport_device.md \ - libsel4vmmplatsupport_guest_image.md \ - libsel4vmmplatsupport_guest_memory_util.md \ - libsel4vmmplatsupport_guest_vcpu_util.md \ - libsel4vmmplatsupport_ioports.md \ - libsel4vmmplatsupport_pci_helper.md \ - libsel4vmmplatsupport_pci.md \ - libsel4vmmplatsupport_virtio_con.md \ - libsel4vmmplatsupport_virtio_net.md \ - libsel4vmmplatsupport_x86_acpi.md \ - libsel4vmmplatsupport_x86_guest_boot_init.md \ - libsel4vmmplatsupport_x86_vmm_pci_helper.md -LIBSEL4VMM_SRC_FILES = $(patsubst %, $(LIBSEL4VMM_SRC)/%, $(LIBSEL4VMM_FILES)) -# same destination dir as libsel4vm -LIBSEL4VMM_DST_FILES = $(patsubst %, $(LIBSEL4VM_DST)/%, $(LIBSEL4VMM_FILES)) - -$(LIBSEL4VMM_SRC_FILES): $(PROJECT_LIBS_REPO) - -$(LIBSEL4VM_DST)/%.md: $(LIBSEL4VMM_SRC)/%.md - @echo "$< ==> $@" - @tools/gen_markdown_api_doc.py -f $< -o $@ -p libsel4vmm.html - -.PHONY: generate_libsel4vmmplatsupport_api -generate_libsel4vmmplatsupport_api: $(LIBSEL4VM_DST) $(LIBSEL4VMM_DST_FILES) - -.PHONY: generate_api -generate_api: _generate_api_pages generate_libsel4vm_api generate_libsel4vmmplatsupport_api - -# Rules for local serving of the site using jekyll. -# Supports docker or running using local environment. -# The _production versions run with JEKYLL_ENV=production which will show additional content. -# The _production versions require `generate_data_files` to have been run separately. -JEKYLL_ENV:=development -DOCKER_IMG:=docs_builder -.PHONY: docker_serve -docker_serve: docker_build - docker run -p 4000:4000 -v $(PWD):/docs -w /docs -it $(DOCKER_IMG) bash -c 'make serve JEKYLL_ENV=$(JEKYLL_ENV)' - -.PHONY: docker_build -docker_build: - docker build -t $(DOCKER_IMG) tools/ - -# --host 0.0.0.0 serves on all interfaces, so that docker can export -# the connection; also works locally -.PHONY: serve -serve: generate - JEKYLL_ENV=$(JEKYLL_ENV) bundle exec jekyll serve - -.PHONY: generate -generate: repos ruby_deps .npm_deps generate_api microkit microkit-tutorial rust-tutorial tutorials -ifeq ($(JEKYLL_ENV),production) - $(MAKE) generate_data_files -endif - mkdir -p $(JEKYLL_OUT)/$(RUST_TUT_FINAL_DST) - rsync -a $(RUST_TUT_DST)/ $(JEKYLL_OUT)/$(RUST_TUT_FINAL_DST)/ - -JEKYLL_OUT = _site - -.PHONY: build -build: generate - JEKYLL_ENV=$(JEKYLL_ENV) bundle exec jekyll build $(BUILD_OPTS) - -.PHONY: preview -preview: JEKYLL_ENV := production -preview: BUILD_OPTS := --config "_config.yml,_preview.yml" $(BUILD_OPTS) -preview: JEKYLL_OUT := _preview -preview: build - -.PHONY: clean -clean: - rm -rf _site - rm -rf _preview - rm -rf _data/generated.yml - rm -rf _processed/microkit-tutorial - rm -rf _processed/tutes - rm -rf projects/virtualization/docs/api - rm -rf $(RUST_TUT_DST) $(RUST_TUT_FINAL_DST) - rm -f _data/microkit_tutorial.yml - rm -f _data/microkit_platforms.yml - -.PHONY: repoclean -repoclean: clean - rm -rf _repos - -.PHONY: realclean -realclean: repoclean - rm -rf .jekyll-cache - rm -rf vendor - rm -rf node_modules - rm -f .npm_deps - -# Check conformance for Web Content Accessibility Guidelines (WCAG) 2.0, AA -# This relies on Automated Accessibility Testing Tool (AATT) (https://github.com/paypal/AATT) -# to be running and listening on http://localhose:3000 -# The resulting conformance_results.xml file can be viewed with `make check_conformance_errors` or using a junit xml viewer -.PHONY: check_conformance -check_conformance: build - find _site -iname "*.html"| sed "s/_site.//" | python tools/testWCAG.py > conformance_results.xml - -.PHONY: check_conformance_errors -check_conformance_errors: conformance_results.xml - grep -B1 'type="failure"' conformance_results.xml || true - -LIQUID_CUSTOM_TAGS := continue - -LIQUID_LINTER_CMDLINE := liquid-linter $(LIQUID_CUSTOM_TAGS:%=--custom-tag %) - -# Liquid syntax linting check. -# If it is complaining about unknown custom tags -> add them to the list above. -# Requires `liquid-linter` to be installed. -# git ls-files won't list any files that are untracked -.PHONY: check_liquid_syntax -check_liquid_syntax: - git ls-files "*.html" | xargs $(LIQUID_LINTER_CMDLINE) - git ls-files "*.md" | xargs $(LIQUID_LINTER_CMDLINE) - -# Output html checking using tidy. -# Any warnings or errors will be printed to stdout -# Requires `tidy` to be installed. -.PHONY: check_html_output -check_html_output: build - find _site/ -iname "*.html"| xargs -l tidy -q --drop-empty-elements n -e - -# list of URL regexps to ignore when checking links -# font preload/preconnect URLS give 404 on link check, but work; -IGNORE_URLS = fonts.gstatic.com -IGNORE_URLS += fonts.googleapis.com -# avoid spamming GitHub too much -IGNORE_URLS += github.com.seL4.rfcs.pulls\?q -IGNORE_URLS += https://github.com/seL4/.*/edit/ -# fail even though they work manually -IGNORE_URLS += https://dl.acm.org/citation.cfm\?id=917665 -IGNORE_URLS += https://www.avnet.com/americas/product/avnet-engineering-services/aes-ultra96-v2-i-g/evolve-42136369/ -IGNORE_URLS += https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/soc-fpga/softconsole -IGNORE_URLS += https://wiki.odroid.com/odroid-c2/odroid-c2 -IGNORE_URLS += https://wiki.odroid.com/odroid-c4/odroid-c4 -IGNORE_URLS += http://ww1.microchip.com/downloads/en/DeviceDoc/9514.pdf -IGNORE_URLS += https://digilent.com/reference/programmable-logic/genesys-2/reference-manual -IGNORE_URLS += https://reference.digilentinc.com/reference/programmable-logic/genesys-2/reference-manual -IGNORE_URLS += https://www.microchip.com/en-us/development-tool/MPFS-ICICLE-KIT-ES -IGNORE_URLS += https://www.microchip.com/en-us/products/fpgas-and-plds/system-on-chip-fpgas/polarfire-soc-fpgas.* -IGNORE_URLS += https://www.amd.com/en/products/adaptive-socs-and-fpgas/evaluation-boards/ek-z7-zc706-g.html -IGNORE_URLS += https://www.amd.com/en/products/adaptive-socs-and-fpgas/evaluation-boards/ek-u1-zcu102-g.html -IGNORE_URLS += https://www.amd.com/en/products/adaptive-socs-and-fpgas/evaluation-boards/zcu106.html -# link checker complains about missing #target, but it exists and works -IGNORE_URLS += https://releases.llvm.org/8.0.0/tools/clang/docs/CrossCompilation.html -# link checker chrashes on #target reference for PPF in rust tutorial -IGNORE_URLS += https://sel4.systems/Info/Docs/seL4-manual-13.0.0.pdf - -# GitHub links with dynamic internal targets such as #L12 fail in the target link check -# The #target is interpreted as comment by "make", which is what we want -- the link checker has no option -# to ignore specific targets, but we still want to know what the original target was. -IGNORE_URLS += https://github.com/seL4/seL4/blob/master/libsel4/sel4_arch_include/ia32/sel4/sel4_arch/syscalls.h#L621 -IGNORE_URLS += https://github.com/seL4/seL4/blob/master/libsel4/mode_include/32/sel4/shared_types.bf#L11 -IGNORE_URLS += https://github.com/seL4/seL4/blob/master/src/arch/arm/config.cmake#L21 -IGNORE_URLS += https://github.com/seL4/seL4/blob/master/src/arch/x86/config.cmake#L15 -IGNORE_URLS += https://github.com/seL4/seL4/blob/master/src/arch/riscv/config.cmake#L15 -IGNORE_URLS += https://github.com/sel4/camkes-vm-apps/blob/master/apps/Arm/vm_minimal/tx2/devices.camkes#L40 -IGNORE_URLS += https://github.com/seL4/camkes-vm-examples/blob/master/apps/x86/optiplex9020/optiplex9020.camkes#L46 -IGNORE_URLS += https://github.com/u-boot/u-boot/blob/8937bb265a7f2251c1bd999784a4ef10e9c6080d/board/xilinx/zynqmp/zynqmp.c#L234 -IGNORE_URLS += https://github.com/u-boot/u-boot/blob/8937bb265a7f2251c1bd999784a4ef10e9c6080d/board/xilinx/zynqmp/zynqmp.c#L234 -IGNORE_URLS += https://github.com/seL4/microkit/blob/main/docs/manual.md#limits -IGNORE_URLS += https://github.com/seL4/rust-sel4/blob/main//support/targets#readme -IGNORE_URLS += https://github.com/seL4/rust-sel4/tree/main/support/targets#readme -IGNORE_URLS += https://github.com/seL4/microkit/blob/b8cf3094ba08b37198b1943ec832c3a1168f4409/libmicrokit/include/microkit.h#L14C22-L14C38 -IGNORE_URLS += https://github.com/seL4/microkit/blob/b8cf3094ba08b37198b1943ec832c3a1168f4409/libmicrokit/include/microkit.h#L16C28-L16C44 -IGNORE_URLS += https://github.com/seL4/seL4-rust-tutorial-code/blob/42d026476c7da08aa84ce17b99ab56dae37ff227/docker/Dockerfile#L94-L108 -IGNORE_URLS += https://github.com/seL4/seL4-rust-tutorial-code/blob/42d026476c7da08aa84ce17b99ab56dae37ff227/mk/root-task.mk#L31-L36 -IGNORE_URLS += https://github.com/seL4/seL4-rust-tutorial-code/blob/42d026476c7da08aa84ce17b99ab56dae37ff227/.cargo/config.toml#L8 -IGNORE_URLS += https://github.com/seL4/seL4/blob/b63043c41a5db1f64253ea98b104eab54c256c56/include/benchmark/benchmark.h#L63 -IGNORE_URLS += https://github.com/seL4/camkes-tool/blob/camkes-3.0.0/docs/index.md#cache-accelerator - -sep:= /,/ -empty:= -space:= $(empty) $(empty) -IGNORE_URLS:= $(subst /,\/,$(IGNORE_URLS)) -IGNORE_EXP:= $(subst $(space),$(sep),$(IGNORE_URLS)) - -HTMLPROOFEROPT := --swap-urls '^https\://docs.sel4.systems:http\://localhost\:4000' -HTMLPROOFEROPT += --enforce-https=false --disable-external=false -HTMLPROOFEROPT += --ignore-urls '/$(IGNORE_EXP)/' -HTMLPROOFEROPT += --ignore-files "/.*rustdoc.*/,/rust\/tutorial\/404|print/,/projects.rust.tutorial.microkit.shared-memory.*/" -HTMLPROOFEROPT += --assume-extension "" -HTMLPROOFEROPT += --ignore-status-codes 429 -# HTMLPROOFEROPT += --log-level debug -# HTMLPROOFEROPT += --disable-external=true - -checklinks: build - @bundle exec htmlproofer $(HTMLPROOFEROPT) _site - -validate: -# ignore errors from inline SVG files - @html5validator --root _site \ - --ignore 'is not a "color" value' \ - 'not allowed on element "svg"' \ - 'The "font" element is obsolete' \ - 'xmlns:svg' \ - 'sodipodi:namedview' \ - 'xmlns:inkscape' \ - 'sodipodi:role' \ - 'inkscape:label' \ - 'inkscape:groupmode' \ - 'xmlns:sodipodi' \ - 'Element "g" not allowed as child of element "clipPath"' \ - 'error: Duplicate ID "layer1".' - -update: - bundle update - npm update diff --git a/PortingSeL4.html b/PortingSeL4.html new file mode 100644 index 00000000000..aba5c9ed579 --- /dev/null +++ b/PortingSeL4.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/README.md b/README.md deleted file mode 100644 index da383ca2de3..00000000000 --- a/README.md +++ /dev/null @@ -1,160 +0,0 @@ - - -# seL4 Documentation site - -These are the sources for the seL4 Documentation site located at -. It is for cooperatively developing and sharing -documentation on [seL4](https://sel4.systems). - -See [CONTRIBUTING.md](processes/docs-contributing.md) for information on how to -contribute. _TL;DR click edit on the page in GitHub, make your changes and then -submit a pull request._ - -Ask on the [mailing list][mailing-list] or open an issue if something doesn't -make sense. - -We've tried to make sure the hosted site is [WCAG 2.0 -AA](https://www.w3.org/TR/WCAG20/) compliant. Please let us know if we have -missed something. - -[mailing-list]: https://lists.sel4.systems/postorius/lists/ - -## Building the site - -### Install - -#### Ruby - -We recommend using [rbenv](https://github.com/rbenv/rbenv) to install the -correct Ruby version. - -On Mac, using [homebrew](https://brew.sh): - -```sh -brew install ruby-build rbenv -# follow the instructions this command shows, and start a new shell afterwards -rbenv init -# in the docs directory (root of this repo): -rbenv install -``` - -On apt-based Linux distributions (e.g. Ubuntu, Debian): - -```sh -apt install rbenv -# follow the instructions this command shows, and start a new shell afterwards -rbenv init -# in the docs directory (root of this repo): -rbenv install -``` - -After these, you should be able to forget about `rbenv`, the `Makefile` will now -see the correct Ruby version. - -#### Node/JS - -The doc site needs `node` version 20 or later at build time. The default -`node` and `npm` of recent distribution should work fine: - -```sh -apt install node -``` - -or on Mac: - -```sh -brew install node -``` - -The Makefile does the rest of the JS dependency installation. - -#### Rust - -For building the Rust tutorials we need `cargo`. The easiest way to get Rust -installed is via . Follow the instructions there. A default -install for your platform will work for the doc site. - -You can test if `cargo` is available after the installation by trying - -```sh -cargo --version -``` - -#### Python - -The build is tested with Python 3.9. More recent versions are likely to work as -well. After installing Python via e.g. `homebrew` or `apt`, you can install the -Python build dependencies with: - -```sh -pip3 install --user camkes-deps -``` - -#### Linters - -If you are using the lint checks, they require `tidy` and `liquid-linter`. If -you just want to build the site, you can skip these. - -- HTML output checking using `tidy`: `make check_html_output` -- Liquid syntax checking using `liquid-linter`: `make check_liquid_syntax` - -### Build - -To build and host locally: - -```sh -make serve -# Server address: http://127.0.0.1:4000/ -# Server running... press ctrl-c to stop. -``` - -Or using Docker (you need [Docker -installed](https://docs.docker.com/get-docker/) and running for this): - -```sh -make docker_serve -``` - -### Makefile and JEKYLL_ENV=production version - -Jekyll environment flags can be used to provide some content only in a -production environment. - -One way we use this is to show data generated by rules in the Makefile and saved -in `\_data/generated.yml`. If you want to serve the site locally in production -mode there are `make` rules for this. You will need to call the make rule to -generate the `\_data/generated.yml` also. - -## How the site is set up - -Our documentation is contained in a collection of Markdown files stored in this -repository. We use [Jekyll](https://jekyllrb.com/) to generate a static html -website that is then hosted on GitHub pages. Our continuous integration is -configured to regenerate and update the live site whenever a pull request is -merged. There is a timestamp in the source that indicates when it was last -generated. Additionally, each page has a timestamp and revision hash from when -it was last updated located in the footer based on the git history. - -The markdown pages are rendered using -[Kramdown](https://kramdown.gettalong.org/), a ruby-based markdown converter -that is configured to interpret the markdown files (`.md`) as GitHub flavoured -markdown. - -## Compliance, style and formatting checks - -### WCAG 2.0 AA conformance - -There is a make rule to check conformance to all testable statements from the -guidelines. `make check_conformance`. It requires the site to be hosted locally -(using `make serve`) and a local server of [Automated Accessibility Testing Tool -(AATT)](https://github.com/paypal/AATT). - -`make check_conformance` will output a file named `conformance_results.xml` -which is a junit test suite output file that will contain a test case for each -generated html file of the site. A make rule `make check_conformance_errors` -will grep for failing test cases and output the html page name. The idea here is -to detect if any pages are failing and then manually using the AATT tool's -web interface to check what parts of the page violate the guidelines. diff --git a/RepoCheatsheet.html b/RepoCheatsheet.html new file mode 100644 index 00000000000..0c8ddc37e40 --- /dev/null +++ b/RepoCheatsheet.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Resources.html b/Resources.html new file mode 100644 index 00000000000..d5f76db0935 --- /dev/null +++ b/Resources.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Resources.md b/Resources.md deleted file mode 100644 index 7197cc9afad..00000000000 --- a/Resources.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: /projects/buildsystem/host-dependencies.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/Rust.html b/Rust.html new file mode 100644 index 00000000000..14d9169beed --- /dev/null +++ b/Rust.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/SeL4Libraries.html b/SeL4Libraries.html new file mode 100644 index 00000000000..8e9c58dd86f --- /dev/null +++ b/SeL4Libraries.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Tutorials/camkes-vm-crossvm.html b/Tutorials/camkes-vm-crossvm.html new file mode 100644 index 00000000000..3a131570eb3 --- /dev/null +++ b/Tutorials/camkes-vm-crossvm.html @@ -0,0 +1,1069 @@ + + + + + + + CAmkES cross-VM connectors | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

CAmkES Cross VM Connectors

+ +

This tutorial provides an introduction to using the cross virtual machine (VM) connector mechanisms +provided by seL4 and CAmkES in order to connect processes in a guest Linux instance to CAmkES components.

+ +

In this tutorial you will learn how to:

+ +
    +
  • Configure processes in a Linux guest VM to communicate with CAmkES components
    • +
+ +

Prerequisites

+
    +
  1. Set up your machine
    2. +
  2. CAmkES VM Linux tutorial
    3. +
+ +

Note that the instructions for this tutorial are only for Linux.

+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut camkes-vm-crossvm
+# building the tutorial exercise
+cd camkes-vm-crossvm_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut camkes-vm-crossvm
+# building the tutorial exercise
+cd camkes-vm-crossvm_build
+ninja
+
+ +
+ +

Background

+ +

In order to connect guest Linux instances to CAmkES components, +three additional kernel modules must be installed in the guest. +These modules are included in the root filesystem by default:

+ +
    +
  • dataport: facilitates setting up shared memory between the guest +and CAmkES components.
    • +
  • consumes_event: allows a process in the guest to wait or poll +for an event sent by a CAmkES component.
    • +
  • emits_event: allows a process to emit an event to a CAmkES component.
    • +
+ +

Each type of module can be statically assigned to one or more file descriptors to associate that +file descriptor with a specific instance of an interface. ioctl can then be used to +manipulate that file descriptor and use the module.

+ +

Dataports

+ +

Dataports are the mechanism which allows guests and components to share memory. +The dataport initialisation process is as follows:

+ +
    +
  • The guest process uses ioctl on on the file associated with the dataport and specify a + page-aligned size for the shared memory.
    • +
  • The dataport kernel module in the guest then allocates a page-aligned buffer of the requested size, +and makes a hypercall to the VMM, with the guest physical address and id of the data port. +The ID is derived from the file on which ioctl was called.
    • +
  • The virtual machine manager (VMM) then modifies the guest’s address space, creating the shared memory region. + between a camkes component and the guest.
    • +
  • Linux processes can then map this memory into their own address space by calling mmap on the file +associated with the dataport.
    • +
+ +

Emitting Events

+ +

Guest processes can emit events by using ioctl on files associated with the event interface. +This results in the emits_event kernel module in the guest making a +making a hypercall to the VMM, which triggers the event and resumes the guest.

+ +

Consuming Events

+ +

Linux process can wait or poll for an event by calling poll +on the file associated with that event, using the timeout argument to +specify whether or not it should block. The event it polls for is +POLLIN. When the VMM receives an event destined for the guest, it places +the event id in some memory shared between the VMM and the +consumes_event kernel module, and then injects an interrupt into the +guest. The consumes_event kernel module is registered to handle this +interrupt, which reads the event ID from shared memory, and wakes a +thread blocked on the corresponding event file. If no threads are +blocked on the file, some state is set in the module such that the next +time a process waits on that file, it returns immediately and clears the +state, mimicking the behaviour of notifications.

+ +

Exercises

+ +

In this tutorial you will +create a program that runs in the guest, and sends a string +to a CAmkES component to output. To achieve this, the guest program will write a string +to a shared buffer between itself and a CAmkES component. When its ready +for the string to be printed, it will emit an event, received by the +CAmkES component. The CAmkES component will print the string, then send +an event to the guest process so the guest knows it’s safe to send a new +string.

+ +

Add modules to the guest

+ +

There is a library in projects/camkes/vm-linux/camkes-linux-artifacts/camkes-linux-apps/camkes-connector-apps/libs +containing Linux system call wrappers, and some utility programs in +projects/camkes/vm-linux/camkes-linux-artifacts/camkes-linux-apps/camkes-connector-apps/pkgs/{dataport,consumes_event,emits_event} +which initialize and interact with cross VM connections. To build and use these modules in your rootfs the vm-linux +project provides an overlay target you can use.

+ +

Exercise First add the dataport, consumes_event and emits_event kernel modules to the rootfs in the guest.

+ +

Start by replacing the line:

+ +
AddToFileServer("rootfs.cpio" ${default_rootfs_file})
+
+ +

in the target applications CMakeLists.txt file with the following:

+ +
set(CAmkESVMDefaultBuildrootOverlay ON CACHE BOOL "" FORCE)
+AddOverlayDirToRootfs(default_buildroot_overlay ${default_rootfs_file} "buildroot" "rootfs_install"
+    rootfs_file rootfs_target)
+AddToFileServer("rootfs.cpio" ${rootfs_file})
+
+ +

Define interfaces in the VMM

+ +

Exercise Update the CAmkES file, crossvm_tutorial.camkes by replacing the Init0 component definition:

+ +
component Init0 {
+    VM_INIT_DEF()
+}
+
+ +

with the following definition:

+ +
component Init0 {
+  VM_INIT_DEF()
+
+  // this is the data port for shared memory between the component and guest process
+  dataport Buf(4096) data;
+  // this event tells the component that there is data ready to print
+  emits DoPrint do_print;
+  // this event tells the guest process that priting is complete
+  consumes DonePrinting done_printing;
+  // this mutex protects access to shared state between the VMM and the guest Linux
+  has mutex cross_vm_event_mutex;
+}
+
+ +

These interfaces will eventually be made visible to processes running in +the guest linux. The mutex is used to protect access to shared state +between the VMM and guest.

+ +

Define the component interface

+ +

Exercise Define the print server component by adding the following to +the crossvm_tutorial.camkes file, after the Init0 definition:

+
component PrintServer {
+  control;
+  dataport Buf(4096) data;
+  consumes DoPrint do_print;
+  emits DonePrinting done_printing;
+}
+
+ +

Instantiate the print server

+ +

Exercise Replace the composition definition:

+ +
    composition {
+        VM_COMPOSITION_DEF()
+        VM_PER_VM_COMP_DEF(0)
+    }
+
+ +

with the following:

+ +
    composition {
+        VM_COMPOSITION_DEF()
+        VM_PER_VM_COMP_DEF(0)
+
+        component PrintServer print_server;
+        connection seL4Notification conn_do_print(from vm0.do_print,
+                                                 to print_server.do_print);
+        connection seL4Notification conn_done_printing(from print_server.done_printing,
+                                                      to vm0.done_printing);
+
+        connection seL4SharedDataWithCaps conn_data(from print_server.data,
+                                                    to vm0.data);
+    }
+
+ +

The seL4SharedDataWithCaps +connector is a dataport connector much like seL4SharedData. +However, the to side of the connection also receives access to +the capabilities to the frames backing the dataport, which is required +for cross VM dataports, as the VMM must be able to establish shared memory +at runtime by inserting new mappings into the guest’s address space.

+ +

Exercise Interfaces connected with seL4SharedDataWithCaps must be +configured with an integer specifying the ID and size of the dataport. + Do this now by modifying crossvm_tutorial.camkes with the following +two lines in the configuration section:

+ +
    configuration {
+    ...
+        // Add the following 2 lines:
+        vm0.data_id = 1; // ids must be contiguous, starting from 1
+        vm0.data_size = 4096;
+    }
+
+ +

Implement the print server

+ +

Exercise Add the file components/print_server.c with the following contents:

+
#include <camkes.h>
+#include <stdio.h>
+
+int run(void) {
+
+    while (1) {
+        // wait for the next event
+        do_print_wait();
+
+        printf("%s\n", (char*)data);
+
+        // signal that we are done printing
+        done_printing_emit();
+    }
+
+    return 0;
+}
+
+ +

This provides a very simple component definition that loops forever, printing a string from +shared memory whenever an event is received then emitting an event. +The example code assumes that the shared buffer will contain a valid, null-terminated c string, which is not + something you should do in practice.

+ +

Implement the VMM side of the connection

+

Create another c file that tells the VMM about the cross VM connections. + This file must define 3 functions which initialize each type of cross vm interface:

+ +
    +
  • cross_vm_dataports_init
    • +
  • cross_vm_emits_events_init
    • +
  • cross_vm_consumes_events_init
    • +
+ +

Exercise Add a file src/cross_vm.c with the following contents:

+ +
#include <sel4/sel4.h>
+#include <camkes.h>
+#include <camkes_mutex.h>
+#include <camkes_consumes_event.h>
+#include <camkes_emits_event.h>
+#include <dataport_caps.h>
+#include <cross_vm_consumes_event.h>
+#include <cross_vm_emits_event.h>
+#include <cross_vm_dataport.h>
+#include <vmm/vmm.h>
+#include <vspace/vspace.h>
+
+// this is defined in the dataport's glue code
+extern dataport_caps_handle_t data_handle;
+
+// Array of dataport handles at positions corresponding to handle ids from spec
+static dataport_caps_handle_t *dataports[] = {
+    NULL, // entry 0 is NULL so ids correspond with indices
+    &data_handle,
+};
+
+// Array of consumed event callbacks and ids
+static camkes_consumes_event_t consumed_events[] = {
+    { .id = 1, .reg_callback = done_printing_reg_callback },
+};
+
+// Array of emitted event emit functions
+static camkes_emit_fn emitted_events[] = {
+    NULL,   // entry 0 is NULL so ids correspond with indices
+    do_print_emit,
+};
+
+// mutex to protect shared event context
+static camkes_mutex_t cross_vm_event_mutex = (camkes_mutex_t) {
+    .lock = cross_vm_event_mutex_lock,
+    .unlock = cross_vm_event_mutex_unlock,
+};
+
+int cross_vm_dataports_init(vmm_t *vmm) {
+    return cross_vm_dataports_init_common(vmm, dataports, sizeof(dataports)/sizeof(dataports[0]));
+}
+
+int cross_vm_emits_events_init(vmm_t *vmm) {
+    return cross_vm_emits_events_init_common(vmm, emitted_events,
+            sizeof(emitted_events)/sizeof(emitted_events[0]));
+}
+
+int cross_vm_consumes_events_init(vmm_t *vmm, vspace_t *vspace, seL4_Word irq_badge) {
+    return cross_vm_consumes_events_init_common(vmm, vspace, &cross_vm_event_mutex,
+            consumed_events, sizeof(consumed_events)/sizeof(consumed_events[0]), irq_badge);
+}
+
+ +

Update the build system

+ +

Exercise Make the following changes in CMakeLists.txt by firstly replacing the declaration of Init0:

+ +
DeclareCAmkESVM(Init0)
+
+ +

with the following declaration:

+ +
# Retrieve Init0 cross vm src files
+file(GLOB init0_extra src/*.c)
+# Declare VM component: Init0
+DeclareCAmkESVM(Init0
+    EXTRA_SOURCES ${init0_extra}
+    EXTRA_LIBS crossvm
+)
+
+ +

Also add a declaration for a PrintServer component:

+ +
# Declare the CAmkES PrintServer component
+DeclareCAmkESComponent(PrintServer SOURCES components/print_server.c)
+
+ +

This extends the definition of the Init component with the cross_vm connector source and the crossvm +library, and defines the new CAmkES component PrintServer.

+ +

Add interfaces to the Guest

+ +

Exercise Create the following camkes_init shell script that is executed as Linux is initialized:

+ +
#!/bin/sh
+# Initialises linux-side of cross vm connections.
+
+# Dataport sizes must match those in the camkes spec.
+# For each argument to dataport_init, the nth pair
+# corresponds to the dataport with id n.
+dataport_init /dev/camkes_data 4096
+
+# The nth argument to event_init corresponds to the
+# event with id n according to the camkes vmm.
+consumes_event_init /dev/camkes_done_printing
+emits_event_init /dev/camkes_do_print
+
+ +

Each of these commands creates device nodes associated with a particular +Linux kernel module supporting cross VM communication. Each command +takes a list of device nodes to create, which must correspond to the IDs +assigned to interfaces in crossvm_tutorial.camkes and cross_vm.c. The +dataport_init command must also be passed the size of each dataport.

+ +

These changes will cause device nodes to be created which correspond to +the interfaces you added to the VMM component.

+ +

Create a process

+ +

Now make a process that uses the device nodes to communicate with the +print server.

+ +

Exercise First create a new directory:

+
mkdir -p pkgs/print_client
+
+ +

with the following file pkgs/print_client/print_client.c:

+ +
#include <string.h>
+#include <assert.h>
+
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <sys/mman.h>
+#include <fcntl.h>
+
+#include "dataport.h"
+#include "consumes_event.h"
+#include "emits_event.h"
+
+int main(int argc, char *argv[]) {
+
+    int data_fd = open("/dev/camkes_data", O_RDWR);
+    assert(data_fd >= 0);
+
+    int do_print_fd = open("/dev/camkes_do_print", O_RDWR);
+    assert(do_print_fd >= 0);
+
+    int done_printing_fd = open("/dev/camkes_done_printing", O_RDWR);
+    assert(done_printing_fd >= 0);
+
+    char *data = (char*)dataport_mmap(data_fd);
+    assert(data != MAP_FAILED);
+
+    ssize_t dataport_size = dataport_get_size(data_fd);
+    assert(dataport_size > 0);
+
+    for (int i = 1; i < argc; i++) {
+        strncpy(data, argv[i], dataport_size);
+        emits_event_emit(do_print_fd);
+        consumes_event_wait(done_printing_fd);
+    }
+
+    close(data_fd);
+    close(do_print_fd);
+    close(done_printing_fd);
+
+    return 0;
+}
+
+ +

This program prints each of its arguments on a separate line, by sending +each argument to the print server one at a time.

+ +

Exercise Create pkgs/print_client/CMakeLists.txt for our client program:

+ +
cmake_minimum_required(VERSION 3.8.2)
+
+project(print_client C)
+
+file(READ ${CMAKE_MODULE_PATH_FILE} module_path)
+list(APPEND CMAKE_MODULE_PATH ${module_path})
+find_package(camkes-vm-linux REQUIRED)
+add_subdirectory(${CAMKES_VM_LINUX_DIR}/camkes-linux-artifacts/camkes-linux-apps/camkes-connector-apps/libs/camkes camkes)
+
+add_executable(print_client print_client.c)
+target_link_libraries(print_client camkeslinux)
+
+ +

Exercise Update our the VM apps CMakeLists.txt. Below the line:

+ +
AddToFileServer("bzimage" ${decompressed_kernel} DEPENDS extract_linux_kernel)
+
+ +

add the ExternalProject declaration to include the print application:

+ +
# Get Custom toolchain for 32 bit Linux
+include(cross_compiling)
+FindCustomPollyToolchain(LINUX_32BIT_TOOLCHAIN "linux-gcc-32bit-pic")
+# Declare our print server app external project
+include(ExternalProject)
+file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/module_path "${CMAKE_MODULE_PATH}")
+ExternalProject_Add(print_client-app
+    SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/pkgs/print_client
+    BINARY_DIR ${CMAKE_BINARY_DIR}/print_client-app
+    BUILD_ALWAYS ON
+    STAMP_DIR ${CMAKE_CURRENT_BINARY_DIR}/print_client-app-stamp
+    EXCLUDE_FROM_ALL
+    INSTALL_COMMAND ""
+    CMAKE_ARGS
+        -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
+        -DCMAKE_TOOLCHAIN_FILE=${LINUX_32BIT_TOOLCHAIN}
+        -DCMAKE_MODULE_PATH_FILE=${CMAKE_CURRENT_BINARY_DIR}/module_path
+)
+# Add the print client app to our overlay ('default_buildroot_overlay')
+AddExternalProjFilesToOverlay(print_client-app ${CMAKE_BINARY_DIR}/print_client-app default_buildroot_overlay "usr/sbin"
+    FILES print_client)
+
+ +

Directly below this we also want to add our camkes_init script into the overlay. We place this into the VMs init.d directory so +the script is run on start up:

+ +
AddFileToOverlayDir("S90camkes_init" ${CMAKE_CURRENT_LIST_DIR}/camkes_init "etc/init.d" default_buildroot_overlay)
+
+ +

That’s it. Build and run the system, and you should see the following output:

+ +
...
+Creating dataport node /dev/camkes_data
+Allocating 4096 bytes for /dev/camkes_data
+Creating consuming event node /dev/camkes_done_printing
+Creating emitting event node /dev/camkes_do_print
+
+Welcome to Buildroot
+buildroot login: root
+Password:
+# print_client hello world
+[   12.730073] dataport received mmap for minor 1
+hello
+world
+
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/camkes-vm-crossvm.md b/Tutorials/camkes-vm-crossvm.md deleted file mode 100644 index 8712c0056a9..00000000000 --- a/Tutorials/camkes-vm-crossvm.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: CAmkES cross-VM connectors -tutorial: camkes-vm-crossvm -layout: tutorial -description: walkthrough of adding communication between Linux guests in separate VMs -nav_prev: camkes-vm-linux.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} \ No newline at end of file diff --git a/Tutorials/camkes-vm-linux.html b/Tutorials/camkes-vm-linux.html new file mode 100644 index 00000000000..138677b16a1 --- /dev/null +++ b/Tutorials/camkes-vm-linux.html @@ -0,0 +1,1127 @@ + + + + + + + CAmkES VM Linux | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

CAmkES VM Linux

+ +

This tutorial provides an introduction to creating VM guests and applications on seL4 using CAmkES.

+ +

You will become familiar with:

+ +
    +
  • Creating, configuring and building guest Linux VM components in CAmkES.
    • +
  • Building and installing your own Linux VM user-level programs and kernel modules.
    • +
+ +

Note that the instructions for this tutorial are only for Linux.

+ +

Prerequisites

+
    +
  1. Set up your machine
    2. +
  2. CAmkES timer tutorial
    3. +
+ +

capDL Loader

+ +

This tutorial uses the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +
+ Get capDL +

The capDL loader parses +a static description of the system and the relevant ELF binaries. +It is primarily used in CAmkES projects +but we also use it in the tutorials to reduce redundant code. +The program that you construct will end up with its own CSpace and VSpace, which are separate +from the root task, meaning CSlots like seL4_CapInitThreadVSpace have no meaning +in applications loaded by the capDL loader.

+ +

More information about capDL projects can be found here.

+ +

For this tutorial clone the capDL repo. This can be added in a directory that is adjacent to the main tutorials directory.

+
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut camkes-vm-linux
+# building the tutorial exercise
+cd camkes-vm-linux_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut camkes-vm-linux
+# building the tutorial exercise
+cd camkes-vm-linux_build
+ninja
+
+ +
+ +

Background

+ +

This tutorial is set up with a basic CAmkES VM configuration for you to build upon. +The starting application should boot a single, very basic Linux guest.

+ +

To build the tutorial, run:

+ +
# In build directory
+ninja
+
+ +

You can boot the tutorial on an x86 hardware platform with a multiboot boot loader, +or use the QEMU simulator. Note if you are using QEMU +it is important to ensure that your host machine has VT-x support and KVM +installed. You also need to ensure you have enabled nested virtulisation with KVM guests as described +here.

+ +

To simulate the image you can run the provided simulation script with some additional parameters:

+ +
# In the build directory
+# You will need to set up a tap device first:
+# ip tuntap add tap0 mode tap
+# ip addr add 10.0.120.100/24 dev tap0
+# ip link set dev tap0 up
+sudo ./simulate --machine q35,accel=kvm,kernel-irqchip=split --mem-size 2G --extra-cpu-opts "+vmx" --extra-qemu-args="-enable-kvm -device intel-iommu,intremap=off -net nic,model=e1000 -net tap,script=no,ifname=tap0"
+
+ +

When first simulating the image you should see the following login prompt:

+
Welcome to Buildroot
+buildroot login:
+
+ +

You can login with the username root and the password root.

+ +

The Linux guest was built using buildroot, which +creates a compatible kernel and minimal root filesystem containing busybox and a in-memory file system (a ramdisk).

+ +

VM Components

+ +

Each VM component has its own assembly implementation, where the guest environment is configured. +The provided VM configuration is defined in vm_tutorial.camkes:

+ +
import <VM/vm.camkes>;
+
+#include <configurations/vm.h>
+
+#define VM_GUEST_CMDLINE "earlyprintk=ttyS0,115200 console=ttyS0,115200 i8042.nokbd=y i8042.nomux=y \
+i8042.noaux=y io_delay=udelay noisapnp pci=nomsi debug root=/dev/mem"
+
+component Init0 {
+    VM_INIT_DEF()
+}
+
+assembly {
+    composition {
+        VM_COMPOSITION_DEF()
+        VM_PER_VM_COMP_DEF(0)
+    }
+
+    configuration {
+        VM_CONFIGURATION_DEF()
+        VM_PER_VM_CONFIG_DEF(0)
+
+        vm0.simple_untyped23_pool = 20;
+        vm0.heap_size = 0x2000000;
+        vm0.guest_ram_mb = 128;
+        vm0.kernel_cmdline = VM_GUEST_CMDLINE;
+        vm0.kernel_image = "bzimage";
+        vm0.kernel_relocs = "bzimage";
+        vm0.initrd_image = "rootfs.cpio";
+        vm0.iospace_domain = 0x0f;
+    }
+}
+
+ +

Most of the work here is done by five C preprocessor macros: +VM_INIT_DEF, VM_COMPOSITION_DEF, VM_PER_VM_COMP_DEF, +VM_CONFIGURATION_DEF, VM_PER_VM_CONFIG_DEF.

+ +

These are all defined in projects/camkes/vm/components/VM/configurations/vm.h, +and are concerned with specifying and configuring components that all +VM(M)s need.

+ +

The Init0 component corresponds to a single guest. Because of some rules +in the cpp macros, the Ith guest in your system must be defined as a +component named InitI. InitI components will be instantiated in the +composition section by the VM_PER_VM_COMP_DEF macro with instance +names vmI. The vm0 component instance being configured above is an +instance of Init0. The C source code forInitI components is in +projects/camkes/vm/components/Init/src. This source will be used for components +named InitI for I in 0..VM_NUM_VM - 1.

+ +

The values of vm0.kernel_cmdline, vm0.kernel_image and vm0.initrd_image are all +strings specifying:

+
    +
  • boot arguments to the guest Linux,
    • +
  • the name of the guest Linux kernel image file,
    • +
  • and the name of the guest Linux initrd file (the root filesystem to use during system initialisation).
    • +
+ +

The kernel command-line is defined in the VM_GUEST_CMDLINE macro. The kernel image +and rootfs names are defined in the applications CMakeLists.txt file. +These are the names of files in a CPIO archive that gets created by the build system, and +linked into the VMM. In the simple configuration for thie tutorial, the VMM uses +the bzimage and rootfs.cpio names to find the appropriate files +in this archive.

+ +

To see how the Init component and CPIO archive are defined within the build system, +look at the app’s CMakeList.txt:

+ +
include(${SEL4_TUTORIALS_DIR}/settings.cmake)
+sel4_tutorials_regenerate_tutorial(${CMAKE_CURRENT_SOURCE_DIR})
+
+cmake_minimum_required(VERSION 3.8.2)
+
+project(vm-app C ASM)
+include(ExternalProject)
+find_package(camkes-vm REQUIRED)
+include(${CAMKES_VM_SETTINGS_PATH})
+camkes_x86_vm_setup_x86_vm_environment()
+include(${CAMKES_VM_HELPERS_PATH})
+find_package(camkes-vm-linux REQUIRED)
+include(${CAMKES_VM_LINUX_HELPERS_PATH})
+
+
+# Include CAmkES VM helper functions
+
+
+
+
+# Declare VM component: Init0
+DeclareCAmkESVM(Init0)
+
+# Get Default Linux VM files
+GetArchDefaultLinuxKernelFile("32" default_kernel_file)
+GetArchDefaultLinuxRootfsFile("32" default_rootfs_file)
+
+# Decompress Linux Kernel image and add to file server
+DecompressLinuxKernel(extract_linux_kernel decompressed_kernel ${default_kernel_file})
+
+AddToFileServer("bzimage" ${decompressed_kernel} DEPENDS extract_linux_kernel)
+
+
+
+# Add rootfs images into file server
+AddToFileServer("rootfs.cpio" ${default_rootfs_file})
+
+
+
+# Initialise CAmkES Root Server with addition CPP includes
+DeclareCAmkESVMRootServer(vm_tutorial.camkes)
+GenerateCAmkESRootserver()
+
+
+ +

The file projects/camkes/vm/camkes_vm_helpers.cmake provides helper functions for the VM projects, +including DeclareCAmkESVM(Init0), which is used to define the Init0 VM component. +Each Init component requires a corresponding DeclareCAmkESVM function.

+ +

GetArchDefaultLinuxKernelFile (defined in projects/camkes/vm-linux/vm-linux-helpers.cmake) +is a helper function that retrieves the location of an architectural specific VM image provided +in the projects/vm-linux folder, which contains some tools for building new linux kernel +and root filesystem images, as well as the images that these tools +produce. A fresh checkout of this project will contain some pre-built +images (bzimage and rootfs.cpio), to speed up build times.

+ +

DecompressLinuxKernel is used to extract the vmlinux image, which AddToFileServer then places +in the fileserver along with the rootfs.

+ +

Adding to the guest

+ +

In the simple buildroot guest image, the +initrd (rootfs.cpio) is also the filesystem you get access to after +logging in. To make new programs available to the guest you need to add them to the +rootfs.cpio archive. Similarly, to make new kernel modules available to +the guest they must be added to the rootfs.cpio archive also.

+ +

In this tutorial you will install new programs into the guest VM.

+ +

vm-linux-helpers.cmake

+ +

The projects/camkes/vm-linux directory contains CMake helpers to +overlay rootfs.cpio archives with a desired set of programs, modules +and scripts.

+ +

AddFileToOverlayDir(filename file_location root_location overlay_name)

+

This helper allows you to overlay specific files onto a rootfs image. The caller specifies +the file they wish to install in the rootfs image (file_location), the name they want the file +to be called in the rootfs (filename) and the location they want the file to installed in the +rootfs (root_location), e.g “usr/bin”. Lastly the caller passes in a unique target name for the overlay +(overlay_name). You can repeatedly call this helper with different files for a given target to build +up a set of files to be installed on a rootfs image.

+ +

AddOverlayDirToRootfs(rootfs_overlay rootfs_image rootfs_distro rootfs_overlay_mode output_rootfs_location target_name)

+

This helper allows you to install a defined overlay target onto a given rootfs image. The caller specifies +the rootfs overlay target name (rootfs_overlay), the rootfs image they wish to install their files onto +(rootfs_image), the distribution of their rootfs image (rootfs_distro, only ‘buildroot’ and ‘debian’ is +supported) and the output location of their overlayed rootfs image (output_rootfs_location). Lastly the caller +specifies how the files will be installed into their rootfs image through rootfs_overlay_mode. These modes include:

+
    +
  • rootfs_install: The files are installed onto the rootfs image. This is useful if the rootfs image is the filesystem +your guest VM is using when it boots. However this won’t be useful if your VM will be booting from disk since the installed files +won’t be present after the VM boots.
    • +
  • overlay: The files are mounted as an overlayed filesystem (overlayfs). This is useful if you are booting from disk and don’t wish to +install the artifacts permanently onto the VM. The downside to this is that writes to the overlayed root do not persist between boots. This +mode is benefitial for debugging purposes and live VM images.
    • +
  • fs_install: The files are permanently installed on the VM’s file system, after the root has been mounted. +

    AddExternalProjFilesToOverlay(external_target external_install_dir overlay_target overlay_root_location)

    +

    This helper allows you to add files generated from an external CMake project to an overlay target. This is mainly a wrapper around +AddOverlayDirToRootfs which in addition creates a target for the generated file in the external project. The caller passes the external +project target (external_target), the external projects install directory (external_install_dir), the overlay target you want to add the +file to (overlay_target) and the location you wish to install the file within the rootfs image (overlay_root_location).

    +
    • +
+ +

linux-source-helpers.cmake

+ +

DownloadLinux(linux_major linux_minor linux_md5 linux_out_dir linux_out_target)

+

This is a helper function for downloading the linux source. This is needed if we wish to build our own kernel modules.

+ +

ConfigureLinux(linux_dir linux_config_location linux_symvers_location configure_linux_target)

+

This helper function is used for configuring downloaded linux source with a given Kbuild defconfig (linux_config_location) +and symvers file (linux_symvers_location).

+ +

Exercises

+ +

Adding a program

+ +

This exercise guides you through adding a new program to the Linux guest user-level environment.

+ +

First, make a new directory:

+
mkdir -p pkg/hello
+
+

Then a simple C program in pkg/hello/hello.c:

+
#include <stdio.h>
+
+int main(int argc, char *argv[]) {
+    printf("Hello, World!\n");
+    return 0;
+}
+
+

Then create a build file for the program at pkg/hello/CMakeLists.txt:

+ +
cmake_minimum_required(VERSION 3.8.2)
+
+project(hello C)
+
+add_executable(hello hello.c)
+
+target_link_libraries(hello -static)
+
+

Now integrate the new program with the build system. +Update the VM apps CMakeLists.txt to declare the hello application as an +external project and add it to our overlay. + Do this by replacing the line AddToFileServer("rootfs.cpio" ${default_rootfs_file}) with the following:

+ +
# Get Custom toolchain for 32 bit Linux
+include(cross_compiling)
+FindCustomPollyToolchain(LINUX_32BIT_TOOLCHAIN "linux-gcc-32bit-pic")
+# Declare our hello app external project
+ExternalProject_Add(hello-app
+    SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/pkg/hello
+    BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}/hello-app
+    BUILD_ALWAYS ON
+    STAMP_DIR ${CMAKE_CURRENT_BINARY_DIR}/hello-app-stamp
+    EXCLUDE_FROM_ALL
+    INSTALL_COMMAND ""
+    CMAKE_ARGS
+        -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
+        -DCMAKE_TOOLCHAIN_FILE=${LINUX_32BIT_TOOLCHAIN}
+)
+# Add the hello world app to our overlay ('vm-overlay')
+AddExternalProjFilesToOverlay(hello-app ${CMAKE_CURRENT_BINARY_DIR}/hello-app vm-overlay "usr/sbin"
+    FILES hello)
+# Add the overlay directory to our default rootfs image
+AddOverlayDirToRootfs(vm-overlay ${default_rootfs_file} "buildroot" "rootfs_install"
+    rootfs_file rootfs_target)
+AddToFileServer("rootfs.cpio" ${rootfs_file} DEPENDS rootfs_target)
+
+

Now rebuild the project…

+ +
# In build directory
+ninja
+
+

..and run it (use root as username and password). +You should be able to use the new program.

+ +
Welcome to Buildroot
+buildroot login: root
+Password:
+# hello
+Hello, World!
+
+ +

Adding a kernel module

+ +

The next exercise guides you through the addition of a new kernel module that provides +guest to VMM communication. This is a very simply module: you’ll create a special file +associated with the new module, which when written to causes the VMM to print message.

+ +

First, make a new directory:

+
mkdir -p modules/poke
+
+

Then create the following file for the module in modules/poke/poke.c.

+
#include <linux/module.h>
+#include <linux/kernel.h>
+#include <linux/init.h>
+#include <linux/fs.h>
+
+#include <asm/uaccess.h>
+#include <asm/kvm_para.h>
+#include <asm/io.h>
+
+#define DEVICE_NAME "poke"
+
+static int major_number;
+
+static ssize_t poke_write(struct file *f, const char __user*b, size_t s, loff_t *o) {
+    printk("hi\n"); // TODO replace with hypercall
+    return s;
+}
+
+struct file_operations fops = {
+    .write = poke_write,
+};
+
+static int __init poke_init(void) {
+    major_number = register_chrdev(0, DEVICE_NAME, &fops);
+    printk(KERN_INFO "%s initialized with major number %dn", DEVICE_NAME, major_number);
+    return 0;
+}
+
+static void __exit poke_exit(void) {
+    unregister_chrdev(major_number, DEVICE_NAME);
+    printk(KERN_INFO"%s exitn", DEVICE_NAME);
+}
+
+module_init(poke_init);
+module_exit(poke_exit);
+
+

Now add a Makefile for building the module in modules/poke/Makefile:

+ +
obj-m += poke.o
+
+all:
+	make -C $(KHEAD) M=$(PWD) modules
+
+clean:
+	make -C $(KHEAD) M=$(PWD) clean
+
+ +

Create a modules/CMakeLists.txt to define the new Linux module with the following content:

+
cmake_minimum_required(VERSION 3.8.2)
+
+if(NOT MODULE_HELPERS_FILE)
+    message(FATAL_ERROR "MODULE_HELPERS_FILE is not defined")
+endif()
+
+include("${MODULE_HELPERS_FILE}")
+
+DefineLinuxModule(${CMAKE_CURRENT_LIST_DIR}/poke poke-module poke-target KERNEL_DIR ${LINUX_KERNEL_DIR})
+
+

Update the VM CMakeLists.txt file to declare the new poke module as an +external project and add it to the overlay.

+ +

At the top of the file include our linux helpers, add the following:

+ +
include(${CAMKES_VM_LINUX_SOURCE_HELPERS_PATH})
+
+

Below the includes (before AddOverlayDirToRootfs that was added in the first exercise Adding a program) add:

+
# Setup Linux Sources
+GetDefaultLinuxMajor(linux_major)
+GetDefaultLinuxMinor(linux_minor)
+GetDefaultLinuxMd5(linux_md5)
+# Download and Configure our Linux sources
+DownloadLinux(${linux_major} ${linux_minor} ${linux_md5} vm_linux_extract_dir download_vm_linux)
+set(linux_config "${CAMKES_VM_LINUX_DIR}/linux_configs/${linux_major}.${linux_minor}/32/config.backup-singlecore")
+set(linux_symvers "${CAMKES_VM_LINUX_DIR}/linux_configs/${linux_major}.${linux_minor}/32/Module.symvers")
+ConfigureLinux(${vm_linux_extract_dir} ${linux_config} ${linux_symvers} configure_vm_linux
+    DEPENDS download_vm_linux
+)
+# Add the external poke module project
+ExternalProject_Add(poke-module
+    SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/modules
+    BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}/poke-module
+    BUILD_ALWAYS ON
+    STAMP_DIR ${CMAKE_CURRENT_BINARY_DIR}/poke-module-stamp
+    EXCLUDE_FROM_ALL
+    INSTALL_COMMAND ""
+    DEPENDS download_vm_linux configure_vm_linux
+    CMAKE_ARGS
+        -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
+        -DCMAKE_TOOLCHAIN_FILE=${LINUX_32BIT_TOOLCHAIN}
+        -DLINUX_KERNEL_DIR=${vm_linux_extract_dir}
+        -DMODULE_HELPERS_FILE=${CAMKES_VM_LINUX_DIR}/linux-module-helpers.cmake
+)
+# Add our module binary to the overlay
+AddExternalProjFilesToOverlay(poke-module ${CMAKE_CURRENT_BINARY_DIR}/poke-module vm-overlay "lib/modules/4.8.16/kernel/drivers/vmm"
+    FILES poke.ko)
+
+ +

Write a custom init script that loads the new module during initialization. +Create a file called init in our tutorial directory with the following:

+ +
#!/bin/sh
+# devtmpfs does not get automounted for initramfs
+/bin/mount -t devtmpfs devtmpfs /dev
+exec 0</dev/console
+exec 1>/dev/console
+exec 2>/dev/console
+
+insmod /lib/modules/4.8.16/kernel/drivers/vmm/poke.ko
+exec /sbin/init $*
+
+

Now update our the VM apps CMakeLists.txt file to add the new init script to the +overlay. After our call to AddExternalProjFilesToOverlay and before AddOverlayDirToRootfs for the poke module add the following:

+ +
AddFileToOverlayDir("init" ${CMAKE_CURRENT_LIST_DIR}/init "." vm-overlay)
+
+

and give the script executable permissions:

+
chmod +x init
+
+

Rebuild the project:

+ +
# In build directory
+ninja
+
+

Run the following commands to see the module being used:

+ +
Welcome to Buildroot
+buildroot login: root
+Password:
+# grep poke /proc/devices        # figure out the major number of our driver
+246 poke
+# mknod /dev/poke c 246 0        # create the special file
+# echo > /dev/poke               # write to the file
+[ 57.389643] hi
+-sh: write error: Bad address    # the shell complains, but our module is being invoked!
+
+ +

Creating a hypercall

+ +

In modules/poke/poke.c, replace printk("hi\n"); with kvm_hypercall1(4, 0);. +The choice of 4 is because 0..3 are already used by existing hypercalls.

+ +

Then register a handler for this hypercall in projects/camkes/vm/components/Init/src/main.c:. +Add a new function at the top of the file:

+ +
static int poke_handler(vm_vcpu_t *vm_vcpu) {
+    printf("POKE!!!\n");
+    return 0;
+}
+
+ +

In the function main_continued register `poke_handler`:

+ +
vm_reg_new_vmcall_handler(&vm, poke_handler, 4); // <--- added
+
+/* Now go run the event loop */
+vm_run(&vm);
+
+ +

Rebuild the project and try out the hypercall + module:

+ +
# In build directory
+ninja
+
+
Welcome to Buildroot
+buildroot login: root
+Password:
+# mknod /dev/poke c 246 0
+# echo > /dev/poke
+POKE!!!
+
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/camkes-vm-linux.md b/Tutorials/camkes-vm-linux.md deleted file mode 100644 index 86981adfe66..00000000000 --- a/Tutorials/camkes-vm-linux.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: CAmkES VM Linux -tutorial: camkes-vm-linux -tutorial-order: vm-1 -layout: tutorial -nav_prev: hello-camkes-timer.html -nav_next: camkes-vm-crossvm.html -description: using Linux as a guest in the CAmkES VM -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/capabilities.html b/Tutorials/capabilities.html new file mode 100644 index 00000000000..e3473891eca --- /dev/null +++ b/Tutorials/capabilities.html @@ -0,0 +1,986 @@ + + + + + + + Capabilities | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Capabilities

+ +

You will learn:

+
    +
  1. The jargon CNode, CSpace, CSlot.
    2. +
  2. How to invoke a capability.
    3. +
  3. How to delete and copy CSlots.
    4. +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Hello world
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut capabilities
+# building the tutorial exercise
+cd capabilities_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut capabilities
+# building the tutorial exercise
+cd capabilities_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

Background

+ +

What is a capability?

+ +

A capability is a unique, unforgeable token that gives the possessor +permission to access an entity or object in system. One way to think of a +capability is as a pointer with access rights. There are three kinds of +capabilities in seL4:

+ +
    +
  • capabilities that control access to kernel objects such as thread control blocks,
    • +
  • capabilities that control access to abstract resources such as IRQControl, and
    • +
  • untyped capabilities, that are responsible for memory ranges and allocation +from those (see also the Untyped tutorial).
    • +
+ +

In seL4, capabilities to all resources controlled by the kernel are given to the root +task on initialisation. To change the state of any resource, user code can use +the kernel API, available in libsel4 to request an operation on the resource +a specific capability points to.

+ +

For example, the root task is provided with a capability to its own thread +control block (TCB), seL4_CapInitThreadTCB, a constant defined by libsel4. +To change the properties of the initial TCB, one can use any of the TCB API +methods on this +capability.

+ +

Below is an example which changes the stack pointer of the root task’s TCB, a +common operation in the root task if a larger stack is needed:

+ +
    seL4_UserContext registers;
+    seL4_Word num_registers = sizeof(seL4_UserContext)/sizeof(seL4_Word);
+
+    /* Read the registers of the TCB that the capability in seL4_CapInitThreadTCB grants access to. */
+    seL4_Error error = seL4_TCB_ReadRegisters(seL4_CapInitThreadTCB, 0, 0, num_registers, &registers);
+    assert(error == seL4_NoError);
+
+    /* set new register values */
+    registers.sp = new_sp; // the new stack pointer, derived by prior code.
+
+    /* Write new values */
+    error = seL4_TCB_WriteRegisters(seL4_CapInitThreadTCB, 0, 0, num_registers, &registers);
+    assert(error == seL4_NoError);
+
+ +

The first argument of seL4_TCB_ReadRegisters and seL4_TCB_WriteRegisters +addresses the capability in slot seL4_CapInitThreadTCB. We will explain +addressing and slots below. The rest of the arguments are specific to the +invocations. Further documentation is available on +TCB_ReadRegisters +and +TCB_WriteRegisters.

+ +

CNodes and CSlots

+ +

A CNode (capability-node) is an object full of capabilities: you can think of a CNode as an array of capabilities. +We refer to slots as CSlots (capability-slots). In the example above, seL4_CapInitThreadTCB is the slot in the root +task’s CNode that contains the capability to the root task’s TCB. +Each CSlot in a CNode can be in the following state:

+ +
    +
  • empty: the CNode slot contains a null capability,
    • +
  • full: the slot contains a capability to a kernel resource.
    • +
+ +

By convention the 0th CSlot is kept empty, for the same reasons as keeping NULL unmapped in + process virtual address spaces: to avoid errors when uninitialised slots are used unintentionally.

+ +

The field info->CNodeSizeBits gives a measure of the size of the initial +CNode: it will have 1 << CNodeSizeBits CSlots. A CSlot has +1 << seL4_SlotBits bytes, so the size of a CNode in bytes is +1 << (CNodeSizeBits + seL4_SlotBits).

+ +

CSpaces

+ +

A CSpace (capability-space) is the full range of capabilities accessible to a thread, which may be +formed of one or more CNodes. In this tutorial, we focus on the CSpace constructed for the root task +by seL4’s initialisation protocol, which consists of one CNode.

+ +

CSpace addressing

+ +

To refer to a capability and perform operations on it, you must address the +capability. There are two ways to address capabilities in the seL4 API. First is +by invocation, the second is by direct addressing. Invocation is a shorthand and +it is what we used to manipulate the registers of the root task’s TCB, which we +now explain in further detail.

+ +

Invocation

+ +

Each thread has a special CNode capability installed in its TCB as its CSpace +root. This root can be empty (a null cap), for instance when the thread is not +authorised to invoke any capabilities at all, or it can be a capability to a +CNode. The root task always has a CSpace root capability that points to a CNode.

+ +

In an invocation, a CSlot is addressed by implicitly invoking the CSpace root +of the thread that is performing the invocation. In the code example above, we +use an invocation on the seL4_CapInitThreadTCB CSlot to read from and write to +the registers of the TCB represented by the capability in that specific CSlot.

+ +
seL4_TCB_WriteRegisters(seL4_CapInitThreadTCB, 0, 0, num_registers, &registers);
+
+ +

This implicitly looks up the seL4_CapInitThreadTCB CSlot in the CNode pointed to +by the CSpace root capability of the calling thread, which here is the root task.

+ +

When it is clear by context and not otherwise relevant, we sometimes identify +the capability with the object it points to. So, instead of saying “the CNode +pointed to by the CSpace root capability”, we sometimes say “the CSpace root”. +If not sure, it is better to be precise. Like structs and pointers in C, objects +and capabilities are not actually interchangeable: one object can be pointed to +by multiple capabilities, and each of these capabilities could have a different +level of permissions to that object.

+ +

Direct CSpace addressing

+ +

In contrast to invocation addressing, direct addressing allows you to specify +the CNode to look up in, rather than implicitly using the CSpace root. This form +of addressing is primarily used to construct and manipulate the shape of CSpaces +– potentially the CSpace of another thread. Note that direct addressing also +requires invocation: the operation occurs by invoking a CNode capability, which +itself is indexed from the CSpace root.

+ +

The following fields are used when directly addressing CSlots:

+ +
    +
  • _service/root A capability to the CNode to operate on.
    • +
  • index The index of the CSlot in the CNode to address.
    • +
  • depth How far to traverse the CNode before resolving the CSlot.
    • +
+ +

For the initial, single-level CSpace, the depth value is always seL4_WordBits. For invocations, the depth is always + implicitly seL4_WordBits. +More on CSpace depth will be discussed in future tutorials.

+ +

In the example below, we directly address the root task’s TCB to make a copy of +it in the 0th slot in the CSpace root. CNode +copy requires two +CSlots to be directly addressed: the destination CSlot, and the source CSlot. +seL4_CapInitThreadCNode is used in three different roles here: as source root, +as destination root, and as source slot. It is used as source and destination +root, because we are copying within the same CNode – the CNode of the initial +thread. It is used as source slot, because within the CNode of the initial +thread, seL4_CapInitThreadCNode is the slot of the capability we want to copy +(and the slot 0 is the destination).

+ +
    seL4_Error error = seL4_CNode_Copy(
+        seL4_CapInitThreadCNode, 0, seL4_WordBits, // destination root, slot, and depth
+        seL4_CapInitThreadCNode, seL4_CapInitThreadTCB, seL4_WordBits, // source root, slot, and depth
+        seL4_AllRights);
+    assert(error == seL4_NoError);
+
+ +

All CNode invocations require direct CSpace addressing.

+ +

Initial CSpace

+ +

The root task has a CSpace, set up by seL4 during boot, which contains capabilities to all +resources managed by seL4. We have already seen several capabilities in the root CSpace: seL4_CapInitThreadTCB, + and seL4_CapInitThreadCNode. Both of these are specified by constants in libsel4, however not all initial + capabilities are statically specified. Other capabilities are described by the seL4_BootInfo data structure, + described in libsel4 and initialised by seL4. seL4_BootInfo describes ranges of initial capabilities, + including free slots available in the initial CSpace.

+ +

Exercises

+ +

The initial state of this tutorial provides you with the BootInfo structure, +and calculates the size (in slots) of the initial CNode object.

+ +
int main(int argc, char *argv[]) {
+
+    /* parse the location of the seL4_BootInfo data structure from
+    the environment variables set up by the default crt0.S */
+    seL4_BootInfo *info = platsupport_get_bootinfo();
+
+    size_t initial_cnode_object_size = BIT(info->initThreadCNodeSizeBits);
+    printf("Initial CNode is %zu slots in size\n", initial_cnode_object_size);
+
+ +

When you run the tutorial without changes, you will see something like the following output:

+ +
Booting all finished, dropped to user space
+Initial CNode is 65536 slots in size
+The CNode is 0 bytes in size
+<<seL4(CPU 0) [decodeInvocation/530 T0xffffff801ffb5400 "rootserver" @401397]: Attempted to invoke a null cap #4095.>>
+main@main.c:33 [Cond failed: error]
+    Failed to set priority
+
+ +

By the end of the tutorial all of the output will make sense. For now, the first line is from the kernel. +The second is the printf, telling you the size of the initial CNode. +The third line stating the number of slots in the CSpace, is incorrect, and your first task is to fix that.

+ +

How big is your CSpace?

+ +

Exercise: refer to the background above, and calculate the number of bytes occupied by the initial thread’s CSpace.

+ +
    size_t initial_cnode_object_size_bytes = 0; // TODO calculate this.
+    printf("The CNode is %zu bytes in size\n", initial_cnode_object_size_bytes);
+
+ +
+ Quick solution + + 
    size_t initial_cnode_object_size_bytes = initial_cnode_object_size * (1u << seL4_SlotBits);
+    printf("The CNode is %zu bytes in size\n", initial_cnode_object_size_bytes);
+
+ +
+ +

Copy a capability between CSlots

+ +

After the output showing the number of bytes in the CSpace, you will see an error:

+ +
<<seL4(CPU 0) [decodeInvocation/530 T0xffffff801ffb5400 "rootserver" @401397]: Attempted to invoke a null cap #4095.>>
+main@main.c:33 [Cond failed: error]
+    Failed to set priority
+
+ +

The error occurs as the existing code tries to set the priority of the initial thread’s TCB by + invoking the last CSlot in the CSpace, which is currently empty. seL4 then returns an error code, + and our check that the operation succeeded fails.

+ +

Exercise: fix this problem by making another copy of the TCB capability into the last slot in the CNode.

+ +
    seL4_CPtr first_free_slot = info->empty.start;
+    seL4_Error error = seL4_CNode_Copy(seL4_CapInitThreadCNode, first_free_slot, seL4_WordBits,
+                                       seL4_CapInitThreadCNode, seL4_CapInitThreadTCB, seL4_WordBits,
+                                       seL4_AllRights);
+    ZF_LOGF_IF(error, "Failed to copy cap!");
+    seL4_CPtr last_slot = info->empty.end - 1;
+    /* TODO use seL4_CNode_Copy to make another copy of the initial TCB capability to the last slot in the CSpace */
+
+    /* set the priority of the root task */
+    error = seL4_TCB_SetPriority(last_slot, last_slot, 10);
+    ZF_LOGF_IF(error, "Failed to set priority");
+
+ +
+ Quick solution + + 
    seL4_CPtr first_free_slot = info->empty.start;
+    seL4_Error error = seL4_CNode_Copy(seL4_CapInitThreadCNode, first_free_slot, seL4_WordBits,
+                                       seL4_CapInitThreadCNode, seL4_CapInitThreadTCB, seL4_WordBits,
+                                       seL4_AllRights);
+    ZF_LOGF_IF(error, "Failed to copy cap!");
+    seL4_CPtr last_slot = info->empty.end - 1;
+
+    /* use seL4_CNode_Copy to make another copy of the initial TCB capability to the last slot in the CSpace */
+    error = seL4_CNode_Copy(seL4_CapInitThreadCNode, last_slot, seL4_WordBits,
+                      seL4_CapInitThreadCNode, first_free_slot, seL4_WordBits, seL4_AllRights);
+    ZF_LOGF_IF(error, "Failed to copy cap!");
+
+    /* set the priority of the root task */
+    error = seL4_TCB_SetPriority(last_slot, last_slot, 10);
+    ZF_LOGF_IF(error, "Failed to set priority");
+
+
+ +

On success, you will now see the output:

+ +
<<seL4(CPU 0) [decodeCNodeInvocation/94 T0xffffff801ffb5400 "rootserver" @401397]: CNode Copy/Mint/Move/Mutate: Destination not empty.>>
+main@main.c:44 [Cond failed: error != seL4_FailedLookup]
+    first_free_slot is not empty
+
+ +

Which will be fixed in the next exercise.

+ +

How do you delete capabilities?

+ +

The provided code checks that both first_free_slot and last_slot are empty, which of course is not +true, as you copied TCB capabilities into those CSlots. Checking if CSlots are empty is done +by a neat hack: by attempting to move the CSlots onto themselves. This should fail with an error code +seL4_FailedLookup if the source CSLot is empty, and an seL4_DeleteFirst if not.

+ +

Exercise: delete both copies of the TCB capability.

+ +
    +
  • You can either use seL4_CNode_Delete on the copies, or
    • +
  • seL4_CNode_Revoke on the original capability to achieve this.
    • +
+ +
    // TODO delete the created TCB capabilities
+
+    // check first_free_slot is empty
+    error = seL4_CNode_Move(seL4_CapInitThreadCNode, first_free_slot, seL4_WordBits,
+                            seL4_CapInitThreadCNode, first_free_slot, seL4_WordBits);
+    ZF_LOGF_IF(error != seL4_FailedLookup, "first_free_slot is not empty");
+
+    // check last_slot is empty
+    error = seL4_CNode_Move(seL4_CapInitThreadCNode, last_slot, seL4_WordBits,
+                            seL4_CapInitThreadCNode, last_slot, seL4_WordBits);
+    ZF_LOGF_IF(error != seL4_FailedLookup, "last_slot is not empty");
+
+
+ Quick solution + + 
    // delete the created TCB capabilities
+    seL4_CNode_Revoke(seL4_CapInitThreadCNode, seL4_CapInitThreadTCB, seL4_WordBits);
+
+    // check first_free_slot is empty
+    error = seL4_CNode_Move(seL4_CapInitThreadCNode, first_free_slot, seL4_WordBits,
+                            seL4_CapInitThreadCNode, first_free_slot, seL4_WordBits);
+    ZF_LOGF_IF(error != seL4_FailedLookup, "first_free_slot is not empty");
+
+    // check last_slot is empty
+    error = seL4_CNode_Move(seL4_CapInitThreadCNode, last_slot, seL4_WordBits,
+                            seL4_CapInitThreadCNode, last_slot, seL4_WordBits);
+    ZF_LOGF_IF(error != seL4_FailedLookup, "last_slot is not empty");
+
+ +
+ +

On success, the output will now show:

+ +
<<seL4(CPU 0) [decodeCNodeInvocation/106 T0xffffff801ffb5400 "rootserver" @401397]: CNode Copy/Mint/Move/Mutate: Source slot invalid or empty.>>
+<<seL4(CPU 0) [decodeCNodeInvocation/106 T0xffffff801ffb5400 "rootserver" @401397]: CNode Copy/Mint/Move/Mutate: Source slot invalid or empty.>>
+Suspending current thread
+main@main.c:56 Failed to suspend current thread
+
+ +

Suspend a thread

+ +

Exercise Use seL4_TCB_Suspend to try and suspend the current thread.

+ +
    printf("Suspending current thread\n");
+    // TODO suspend the current thread
+    ZF_LOGF("Failed to suspend current thread\n");
+
+ +
+ Quick solution + + 
    printf("Suspending current thread\n");
+    seL4_TCB_Suspend(seL4_CapInitThreadTCB);
+    ZF_LOGF("Failed to suspend current thread\n");
+
+
+ +

On success, the output will be as follows:

+ +
<<seL4(CPU 0) [decodeCNodeInvocation/106 T0xffffff801ffb5400 "rootserver" @401397]: CNode Copy/Mint/Move/Mutate: Source slot invalid or empty.>>
+<<seL4(CPU 0) [decodeCNodeInvocation/106 T0xffffff801ffb5400 "rootserver" @401397]: CNode Copy/Mint/Move/Mutate: Source slot invalid or empty.>>
+Suspending current thread
+
+ +

Further exercises

+ +

That’s all for the detailed content of this tutorial. Below we list other ideas for exercises you can try, +to become more familiar with CSpaces.

+ +
    +
  • Use a data structure to track which CSlots in a CSpace are free.
    • +
  • Make copies of the entire CSpace described by seL4_BootInfo
    • +
  • Experiment with other CNode invocations.
    • +
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/capabilities.md b/Tutorials/capabilities.md deleted file mode 100644 index 6338bfa4ff6..00000000000 --- a/Tutorials/capabilities.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Capabilities -tutorial: capabilities -layout: tutorial -nav_prev: hello-world.html -nav_next: untyped.html -description: an introduction to capabilities in the seL4 kernel API -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -{% include tutorial.md %} diff --git a/Tutorials/fault-handlers.html b/Tutorials/fault-handlers.html new file mode 100644 index 00000000000..25aba8d8821 --- /dev/null +++ b/Tutorials/fault-handlers.html @@ -0,0 +1,979 @@ + + + + + + + Faults | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Fault handling

+ +

This tutorial covers fault handling in seL4.

+ +

You will learn:

+
    +
  1. About thread faults.
    2. +
  2. That a thread fault is different from a processor hardware fault.
    3. +
  3. About fault handlers.
    4. +
  4. What the kernel does to a thread which has faulted.
    5. +
  5. How to set the endpoint that the kernel will deliver fault messages on (master vs MCS).
    6. +
  6. How to resume threads after they have faulted.
    7. +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Capabilities tutorial
    3. +
  3. IPC tutorial
    4. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut fault-handlers
+# building the tutorial exercise
+cd fault-handlers_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut fault-handlers
+# building the tutorial exercise
+cd fault-handlers_build
+ninja
+
+ +
+ +

capDL Loader

+ +

This tutorial uses the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +
+ Get capDL +

The capDL loader parses +a static description of the system and the relevant ELF binaries. +It is primarily used in CAmkES projects +but we also use it in the tutorials to reduce redundant code. +The program that you construct will end up with its own CSpace and VSpace, which are separate +from the root task, meaning CSlots like seL4_CapInitThreadVSpace have no meaning +in applications loaded by the capDL loader.

+ +

More information about capDL projects can be found here.

+ +

For this tutorial clone the capDL repo. This can be added in a directory that is adjacent to the main tutorials directory.

+
+ +

Background: What is a fault, and what is a fault handler?

+ +

A fault handler is a separate instruction stream which the CPU can jump to in +order to rectify an anomalous condition in the current thread and then return to +the previous instruction stream.

+ +

In seL4, faults are modelled as separately programmer-designated “fault handler” +threads. In monolithic kernels, faults are not usually delivered to a userspace +handler, but they are handled by the monolithic kernel itself.

+ +

In general, attempting to resume execution of the faulted thread +without rectifying the anomaly will simply re-trigger the fault ad infinitum +until the anomaly is cleared away.

+ +

Thread faults vs other sources of faults

+ +

There are several sources of faults in a running system; they include:

+
    +
  • Fault events generated by the CPU itself when it encounters anomalies in the instruction stream (aka, “processor exceptions”).
    • +
  • Fault events generated by hardware in the event of some hardware anomaly (such as a machine check or non-maskable interrupt).
    • +
  • Fault events generated by the seL4 kernel when it encounters anomalies in the current thread.
    • +
+ +

This tutorial is only concerned with those fault events generated by the seL4 +kernel. We will call them “thread faults” from here onward to reduce ambiguity.

+ +

How does thread fault handling work?

+ +

In seL4, when a thread generates a thread fault, the kernel will block the +faulting thread’s execution and attempt to deliver a message across a special +endpoint associated with that thread, called its “fault handler” endpoint.

+ +

The only special thing about the fault handler endpoint is that a thread can +only have one of them. Otherwise it is created and managed just the same way +as any other kind of seL4 endpoint object.

+ +

The thread which is listening on the other end of the fault endpoint is called +the “fault handler”. The kernel expects that the fault handler will correct the +anomaly that ails the faulting thread and then tell the kernel when it is safe +to try executing the faulting thread once again.

+ +

To tell the kernel to resume execution of the faulting thread, the fault handler +can either:

+
    +
  • Invoke a reply operation (with seL4_Reply()) on the fault handler endpoint and make sure that the label in the seL4_MessageInfo_t tag is set to 0;
    • +
  • Explicitly tell the kernel to resume executing the faulting thread using seL4_TCB_Resume().
    • +
+ +

Please note that if the handler sets message registers in the reply message, +the kernel may interpret these as meaning something: some fault replies accept +parameters. See the seL4 manual for the reply message format for all faults.

+ +

If the fault handler did not properly rectify the anomaly in the faulting +thread, resuming the faulting thread will simply cause the kernel to re-generate +the fault.

+ +

Reasons for thread faults

+ +

Thread faults can be generated for different reasons. When a fault occurs the +kernel will pass information describing the cause of the fault as an IPC +message. At the time of writing, the following faults could be generated by +the Master version of the seL4 kernel:

+ +
    +
  • Cap fault: A fault triggered because of an invalid cap access.
    • +
  • VM fault: A fault triggered by incoherent page table state or incorrect memory accesses by a thread.
    • +
  • Unknown Syscall fault: Triggered by performing a syscall invocation that is unknown to the kernel.
    • +
  • Debug fault: Triggered when a breakpoint, watchpoint or single-step debug event occurs.
    • +
+ +

In addition, the following fault types are added by the MCS kernel:

+ +
    +
  • Timeout fault: Triggered when a thread consumes all of its budget and still has further execution to do in the current period.
    • +
+ +

Thread fault messages

+ +

When a fault is generated, the kernel will deliver an IPC message across the +fault endpoint. This IPC message contains information that tells the fault +handler why the fault occurred as well as surrounding contextual information +about the fault which might help the fault handler to rectify the anomaly.

+ +

Each anomaly has its own message format because the information needed to +describe each anomaly will be different. For more information about the contents +of the IPC message sent by the seL4 kernel for each fault anomaly, please see +the seL4 Manual.

+ +

The rest of this tutorial will attempt to teach the reader how to receive and +handle seL4 thread faults.

+ +

Setting up a fault endpoint for a thread

+ +

In the scenario where a fault message is being delivered on a fault endpoint, +the kernel acts as the IPC “sender” and the fault handler acts as a receiver.

+ +

This implies that when caps are being handed out to the fault endpoint object, +one cap to the object must be given to the kernel and one cap to the object must +be given to the handler.

+ +

Kernel end vs handler end

+ +

Programmers specify the capability to use a fault handler for a thread when +configuring a TCB. As a result the programmer can also set a badge on the +kernel’s cap to the fault endpoint object.

+ +

When the kernel sends a fault IPC message using a badged endpoint cap, the badge +is delivered to the receiver just the same way it is delivered for any other +IPC where there is a badge on the sender’s cap.

+ +

A keen reader would probably have realised that this means that a badge on the +kernel’s cap to a fault endpoint can be used to distinguish fault messages +from different faulting threads, such that a single handler can handle +faults from multiple threads. Please see the +IPC Tutorial for a refresher on how +badged fault endpoints work.

+ +

Differences between MCS and Master kernel

+ +

There is a minor difference in the way that the kernel is informed of the +cap to a fault endpoint, between the master and MCS kernels.

+ +

Regardless though, on both versions of the kernel, to inform the kernel of the +fault endpoint for a thread, call the usual seL4_TCB_SetSpace().

+ +

See the MCS tutorial for more information.

+ +

Exercises

+ +

This tutorial has one address space set up by the capDL loader, containing two +threads which share the same CSpace. One of the threads is a fault handler while +the other triggers a virtual memory fault.

+ +

You will be guided through the following broad steps:

+
    +
  1. Badging and configuring a fault handler for the faulting thread.
    2. +
  2. Having the faulting thread trigger a thread fault.
    3. +
  3. Handling the fault in the fault handler.
    4. +
  4. Resuming the execution of the faulting thread.
    5. +
+ +

Description of the tutorial program

+ +

The tutorial features two threads in different virtual address spaces. One +thread is the “faulter” and the other is the “handler”. The faulter is going to +generate a fault, and the handler will “handle” it.

+ +

In order for the handler to handle the fault, the handler must set up a +fault-handling endpoint and tell the kernel to send all fault IPC messages +generated by the faulter thread to itself. This is therefore the first step we +take.

+ +

However, we have to ensure that the fault is only triggered after the handler +thread has set up the fault-handling endpoint and is ready to receive the fault +IPC message from the kernel.

+ +

If the faulter thread generates a fault and there is no thread to handle the +the IPC message, the kernel will simply suspend the faulting thread.

+ +

For this reason we make the faulter thread seL4_call() the handler thread +across an endpoint and tell it which slot the handler should place the fault +handling endpoint cap into. After the handler has set up the handler endpoint, +the handler will seL4_Reply() to the faulter to let it know that it the +handler is ready to handle fault IPC messages.

+ +

After that we trigger a fault in the faulter, handle the fault in the handler, +and then resume the faulter and that’s the end of the exercise.

+ +

Setting up the endpoint to be used for thread fault IPC messages.

+ +

The first exercise is to configure the TCB of the faulter with a fault endpoint. +This exercise is meant to achieve two learning outcomes:

+
    +
  1. Explain that the end of the endpoint that is given to the kernel can be badged, and the kernel will return that badge value when it sends a fault IPC message.
    2. +
  2. Explain the differences between the Master and MCS kernels when it comes to telling the kernel about the fault endpoint.
    3. +
+ +

Right now the faulter thread is blocked on an Endpoint, waiting for the handler +to tell it where to put the fault handler endpoint within its own (the +faulter’s) CSpace (for the Master kernel).

+ +

To set up the fault handler endpoint, we will to first badge it so that when the +kernel sends us a fault IPC message, we will be able to identify the faulter. +Fault handlers can handle faults from multiple threads, so a badge +enables handlers to identify the faulters they are handling.

+ +

To badge the endpoint, use the seL4_CNode_Mint() syscall:

+ +
    error = seL4_CNode_Mint(
+        handler_cspace_root,
+        badged_faulter_fault_ep_cap,
+        seL4_WordBits,
+        handler_cspace_root,
+        faulter_fault_ep_cap,
+        seL4_WordBits,
+        seL4_AllRights, FAULTER_BADGE_VALUE);
+
+ +

Since we are using the Master kernel, you will also need to copy the badged cap +into the faulter’s CSpace (See the MCS tutorial +for an explanation of the differences between the Master and MCS kernel when +configuring fault endpoints):

+ +
    error = seL4_CNode_Copy(
+        faulter_cspace_root,
+        foreign_badged_faulter_empty_slot_cap,
+        seL4_WordBits,
+        handler_cspace_root,
+        badged_faulter_fault_ep_cap,
+        seL4_WordBits,
+        seL4_AllRights);
+
+ +

Finally, we tell the kernel the cap address of the fault endpoint so that the +kernel can deliver fault IPC messages to the handler. Since we’re +using the Master kernel, we need to pass a CPtr that can be resolved from within +the CSpace of the faulter thread:

+ +
    /* Here we need to keep in mind which CPtr we give the kernel. On the MCS
+     * kernel, we must give a CPtr which can be resolved during the course of
+     * this seL4_TCB_SetSpace syscall, from within our own CSpace.
+     *
+     * On the Master kernel, we must give a CPtr which can be resolved during
+     * the generation of a fault message, from within the CSpace of the
+     * (usually foreign) faulting thread.
+     */
+
+    error = seL4_TCB_SetSpace(
+        faulter_tcb_cap,
+        foreign_badged_faulter_empty_slot_cap,
+        faulter_cspace_root,
+        0,
+        faulter_vspace_root,
+        0);
+
+    ZF_LOGF_IF(error != 0, PROGNAME "Failed to configure faulter's TCB with our fault ep!");
+    printf(PROGNAME "Successfully registered badged fault handling ep with "
+           "the kernel.\n"
+           PROGNAME "About to wake the faulter thread.\n");
+
+    /* Signal the faulter thread to try to touch the invalid cspace slot. */
+    seL4_Reply(seL4_MessageInfo_new(0, 0, 0, 0));
+    /* Now wait for the fault IPC message from the kernel. */
+    seL4_Recv(faulter_fault_ep_cap, &tmp_badge);
+
+ +

Receiving the IPC message from the kernel

+ +

The kernel will deliver the IPC message to any thread waiting on the fault +endpoint. To wait for a fault IPC message simply seL4_Recv(), the same way +you’d wait for any other IPC message:

+ +
    /* The IPC message for a cap fault contains the cap address of the slot
+     * which generated the cap fault.
+     *
+     * We need to retrieve this slot address and fill that slot with a random
+     * endpoint cap of our choosing so that the faulter thread can touch that
+     * slot successfully.
+     */
+
+    foreign_faulter_capfault_cap = seL4_GetMR(seL4_CapFault_Addr);
+
+    printf(PROGNAME "Received fault IPC message from the kernel.\n"
+           PROGNAME "Fault occured at cap addr %lu within faulter's cspace.\n",
+           foreign_faulter_capfault_cap);
+
+ +

Finding out information about the generated thread fault

+ +

In the thread fault IPC message, the kernel will send information about the +fault including the capability address whose access triggered the thread fault. +The seL4 manual gives detailed information on which message registers in the IPC +buffer contain information about the fault and if you’re so inclined, the +libsel4 source code also has the exact code values as well.

+ +

In our example here, our sample code generated a Cap Fault, so according to the +seL4 manual, we can find out the cap fault address using at offset +seL4_CapFault_Addr in the IPC message, as you see above in the code snippet.

+ +

Handling a thread fault

+ +

Now that we know the cap address that generated a fault in the faulting thread, +we can “handle” the fault by putting a random cap into that slot and then when +the faulter thread re-tries to access that slot, it will succeed this time and +no thread fault will be generated.

+ +

So here we’ll copy an endpoint cap into the faulting slot:

+ +
    /* Handle the fault by copying an endpoint cap into the empty slot. It
+     * doesn't matter which one: as long as we copy it in with receive rights
+     * because the faulter is going to attempt to perform an seL4_NBRecv() on
+     * it.
+     */
+
+    error = seL4_CNode_Copy(
+        faulter_cspace_root,
+        foreign_faulter_capfault_cap,
+        seL4_WordBits,
+        handler_cspace_root,
+        sequencing_ep_cap,
+        seL4_WordBits,
+        seL4_AllRights);
+
+    ZF_LOGF_IF(error != 0, PROGNAME "Failed to copy a cap into faulter's cspace to resolve the fault!");
+    printf(PROGNAME "Successfully copied a cap into foreign faulting slot.\n"
+           PROGNAME "About to resume the faulter thread.\n");
+
+ +

Resuming a faulting thread

+ +

Finally, to have the faulter thread wake up and try to execute again, we +seL4_Reply() to it:

+ +
     seL4_Reply(seL4_MessageInfo_new(0, 0, 0, 0));
+
+    printf(PROGNAME "Successfully resumed faulter thread.\n"
+           PROGNAME "Finished execution.\n");
+
+ +

Further exercises

+ +

If you’d like to challenge yourself, make sure to set up the fault handling on +both versions of the kernel: master and MCS.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/fault-handlers.md b/Tutorials/fault-handlers.md deleted file mode 100644 index f36766c19eb..00000000000 --- a/Tutorials/fault-handlers.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Faults -tutorial: fault-handlers -layout: tutorial -description: fault (e.g virtual memory fault) handling and fault endpoints -nav_prev: interrupts.html -nav_next: mcs.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/get-the-tutorials.html b/Tutorials/get-the-tutorials.html new file mode 100644 index 00000000000..37832850ba0 --- /dev/null +++ b/Tutorials/get-the-tutorials.html @@ -0,0 +1,634 @@ + + + + + + + Getting the tutorials | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+

Getting the tutorials

+ +
+
+ + Note +
+
+ +

The steps on this page only need to be done once, before doing your first tutorial.

+ +
+
+ +

Python Dependencies

+ +

The CAmkES python dependencies are required to build the seL4 tutorials. To install you can run:

+ +
pip3 install --user camkes-deps
+
+ +
+ Error: Python environment is externally managed +
+ +

Some Linux distributions have changed how Python is managed. If you get an error +saying the Python ‘environment is externally managed’ follow the instructions +below. The first two steps are needed only once for setup.

+ + 
python3 -m venv seL4-venv
+./seL4-venv/bin/pip install camkes-deps
+
+ +

The following step is needed every time you start using the build environment +in a new shell.

+ + 
source ./seL4-venv/bin/activate
+
+ +

It is not important where the seL4-venv directory is located.

+
+
+ +

Get the code

+ +

The collection of code needed for the tutorials is defined in the sel4-tutorials-manifest. Get the code with:

+ +
mkdir tutorials
+cd tutorials
+repo init -u https://github.com/seL4/sel4-tutorials-manifest
+repo sync
+
+ +

repo sync may take a few moments to run

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/get-the-tutorials.md b/Tutorials/get-the-tutorials.md deleted file mode 100644 index 0de2e333f49..00000000000 --- a/Tutorials/get-the-tutorials.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -layout: tutorial -description: steps and code for getting tutorials -nav_next: hello-world.html -nav_prev: setting-up.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC. ---- - -# Getting the tutorials - -{% include note.html %} -The steps on this page only need to be done once, before doing your first tutorial. -{% include endnote.html %} - -## Python Dependencies - -The CAmkES python dependencies are required to build the seL4 tutorials. To install you can run: - -```sh -pip3 install --user camkes-deps -``` - -{% include pip-instructions.md %} - -## Get the code - -The collection of code needed for the tutorials is defined in the [sel4-tutorials-manifest]. Get the code with: - -```bash -mkdir tutorials -cd tutorials -repo init -u https://github.com/seL4/sel4-tutorials-manifest -repo sync -``` - -`repo sync` may take a few moments to run - -[sel4-tutorials-manifest]: https://github.com/seL4/sel4-tutorials-manifest diff --git a/Tutorials/hello-camkes-0.html b/Tutorials/hello-camkes-0.html new file mode 100644 index 00000000000..235fe8b6b2a --- /dev/null +++ b/Tutorials/hello-camkes-0.html @@ -0,0 +1,756 @@ + + + + + + + Hello CAmkES | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Hello CAmkES

+ +

This tutorial is an introduction to CAmkES. This will involve introducing the CAmkES syntax, bootstrapping a basic +static CAmkES application and describing its components.

+ +

Outcomes:

+ +
    +
  1. Understand the structure of a CAmkES application, as a described, well-defined, static system.
    2. +
  2. Understand the file-layout of a CAmkES ADL project.
    3. +
  3. Become acquainted with the basics of creating a practical CAmkES application.
    4. +
+ +

Use this slide presentation to guide you through the tutorials 0, 1 and 2.

+ +

Prerequisites

+
    +
  1. Set up your machine.
    2. +
  2. Hello world tutorial
    3. +
  3. Familiarise yourself with the CAmkES manual. +Note that it’s possible to successfully complete the CAmkES tutorial without having read the manual, however highly +recommended.
    4. +
+ +

Background

+ +

The fundamentals of CAmkES are the component, the interface and the connection. Components are logical +groupings of code and resources. They communicate with other component instances via well-defined +interfaces which must be statically defined, over communication channels.

+ +

Component

+ +

As briefly described above, we identify a component as a functional grouping of code and resources. We +use the term component in CAmkES to refer to the type of our functional grouping (see the Component section in the manual). +An example of this in concrete CAmkES syntax can be seen below:

+ +
component foo {
+  control;
+  uses MyInterface a;
+  attribute Int b;
+}
+
+ +

Disregarding the items defined within the component (we will unpack these in a later tutorial), we defined a component above +whose type is foo. We later can use our foo type to define a component instance. +For example, the statement component foo bar refers to a component instance bar whose type is +foo.

+ +

Describing a static system: Assembly, Composition and Configuration

+ +

In CAmkES, we will commonly see the use of three hierarchical elements, being assembly, composition and configuration. We use these concepts +to build upon a well-defined static system. We firstly use the term ‘assembly’ to refer to a complete description of our static system. In the CAmkES ADL (Architecture Description Language), +we employ the term assembly as a top-level element that will encapsulate our system definition. Each CAmkES project must contain +at least one assembly definition. An example of using the assembly term in CAmkES can be seen below:

+ +
assembly {
+  composition {
+    component foo bar;
+  }
+
+  configuration {
+      bar.b = 0;
+  }
+}
+
+ +

In the above example we can also see the use of the composition and configuration elements. The composition element is +used as a container to encapsulate our component and connector instantiations. Above we declare an instance of +our foo component and we appropriately called it bar. The configuration element is also used to describe settings and attribute +assignments in our given system.

+ +

Creating your first CAmkES application

+ +

In this tutorial we will create a simple ‘Hello World’ example within the CAmkES. This will invole creating a CAmkES component that will +print “Hello CAmkES World” when it starts up.

+ +

Looking at the sources

+ +

In the tutorial directory, you will find the following files:

+
    +
  • CMakeLists.txt - the file that defines how to build our CAmkES application
    • +
  • client.c - the single source file for our ‘Hello World’ client component
    • +
  • hello.camkes - Our CAmkES file describing our static system
    • +
+ +

client.c

+ +

For this tutorial we require our component to simply print “Hello CAmkES World”. We define this in +a typical C file client.c:

+ +
/*
+ * CAmkES tutorial part 0: just a component.
+ */
+
+#include <stdio.h>
+
+/* generated header for our component */
+#include <camkes.h>
+
+/* run the control thread */
+int run(void) {
+    printf("Hello CAmkES World\n");
+    return 0;
+}
+
+ +

Note above that in the source code of client.c instead of typically using main, we place +our runtime code in the function int run(void). run is the entry point +of a CAmkES component.

+ +

hello.camkes

+ +

The hello.camkes file is where we form our description of a static CAmkES system. Our .camkes +files are written using the CAmkES syntax. Employing the concepts discussed in the background +section, we define the following:

+ +
/*
+ * CAmkES tutorial part 0: just a component.
+ */
+
+component Client {
+    control;
+}
+
+assembly {
+    composition {
+        component Client client;
+    }
+}
+
+ +

In the source above we create a minimal static system with a single component instance. We define +our component Client and declare an instance of that component in our system.

+ +

CMakeLists.txt

+ +

Every CAmkES project requires a CMakeLists.txt file to be incorporated in the seL4 build system. Our tutorial +directory should contain the following CMakeLists.txt file:

+ +

+include(${SEL4_TUTORIALS_DIR}/settings.cmake)
+sel4_tutorials_regenerate_tutorial(${CMAKE_CURRENT_SOURCE_DIR})
+
+cmake_minimum_required(VERSION 3.7.2)
+
+project(hello-camkes-0 C ASM)
+
+find_package(camkes-tool REQUIRED)
+camkes_tool_setup_camkes_build_environment()
+
+DeclareCAmkESComponent(Client SOURCES client.c)
+
+DeclareCAmkESRootserver(hello.camkes)
+
+GenerateCAmkESRootserver()
+
+ +

Our CMakeLists.txt file declares our Client component, linking it with our client.c source +file. In addition it declares the CAmkES Root Server using our hello.camkes system description.

+ +

Building your first CAmkES system

+ +

At this point all you need to do is build and run the tutorial:

+ +
# In build directory
+ninja
+
+ +

If build successfully, we can run our system as follows:

+ +
# In build directory
+./simulate
+
+ +

and should see the following once the system has booted:

+ +
Hello CAmkES World
+
+ +

Done

+

Congratulations: be sure to read up on the keywords and +structure of ADL: it’s key to understanding CAmkES. And well done on +building and running your first CAmkES application.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/hello-camkes-0.md b/Tutorials/hello-camkes-0.md deleted file mode 100644 index 7120d0a081d..00000000000 --- a/Tutorials/hello-camkes-0.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Hello CAmkES -tutorial: hello-camkes-0 -layout: tutorial -description: an introduction to CAmkES concepts -nav_next: hello-camkes-1.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/hello-camkes-1.html b/Tutorials/hello-camkes-1.html new file mode 100644 index 00000000000..956658c93e2 --- /dev/null +++ b/Tutorials/hello-camkes-1.html @@ -0,0 +1,858 @@ + + + + + + + Introduction to CAmkES | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Introduction to CAmkES

+ +

This tutorial is an introduction to CAmkES: bootstrapping a basic static CAmkES +application, describing its components, and linking them together.

+ +

Outcomes:

+ +
    +
  1. Understand the structure of a CAmkES application, as a described, +well-defined, static system.
    2. +
  2. Understand the file-layout of a CAmkES ADL project.
    3. +
  3. Become acquainted with the basics of creating a practical CAmkES application.
    4. +
+ +

Use this slide presentation to guide you through the tutorials 0, 1 and 2.

+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. CAmkES hello world tutorial
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut hello-camkes-1
+# building the tutorial exercise
+cd hello-camkes-1_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut hello-camkes-1
+# building the tutorial exercise
+cd hello-camkes-1_build
+ninja
+
+ +
+ +

Background

+ +

The fundamentals of CAmkES are the component, the interface and the connection.

+ +

Components

+ +

Components are logical groupings of code and resources. They communicate with +other component instances via well-defined interfaces which must be statically +defined, over communication channels. This tutorial will lead you through the +construction of a CAmkES application with two components: an Echo server, and +its Client that makes calls to it. These components are defined when you +initialise your build repository, found in the following camkes file:

+ +
    +
  • hello-camkes-1/hello-1.camkes
    • +
+ +

See also the Component +definition in +the CAmkES manual.

+ +

Connections

+ +

The second fundamental component of CAmkES applications is the Connection: a +connection is the representation of a method of communication between two +software components in CAmkES. The underlying implementation may be shared +memory, synchronous IPC, notifications or some other implementation-provided +means. In this particular tutorial, we are using synchronous IPC. In +implementation terms, this boils down to the seL4_Call syscall on seL4.

+ +

See also the Connection +keyword in +the CAmkES manual.

+ +

Interfaces

+ +

All communications over a CAmkES connection must be well defined: static +systems’ communications should be able to be reasoned about at build time. All +the function calls which will be delivered over a communication channel then, +also are well defined, and logically grouped so as to provide clear directional +understanding of all transmissions over a connection. Components are connected +together in CAmkES, yes — but the interfaces that are exposed over each +connection for calling by other components, are also described.

+ +

There are different kinds of interfaces:

+ +
    +
  • Dataports,
    • +
  • Procedural interfaces,
    • +
  • and Notifications.
    • +
+ +

This tutorial will lead you through the construction of a Procedural +interface, which is an interface over which function calls are made +according to a well-defined pre-determined API. The keyword for this +kind of interface in CAmkES is procedure. The definition of this +Procedure interface may be found here: +hello-camkes-1/interfaces/HelloSimple.idl4

+ +

See also the Procedure +keyword in the +CAmkES manual.

+ +

Component source

+ +

Based on the ADL, CAmkES generates boilerplate which conforms to your system’s +architecture, and enables you to fill in the spaces with your program’s logic. +The two generated files in this tutorial application are, in accordance with the +Components we have defined:

+ +
    +
  • hello-camkes-1/components/Echo/src/echo.c
    • +
  • hello-camkes-1/components/Client/src/client.c
    • +
+ +

Now when it comes to invoking the functions that were defined in the +Interface specification +(hello-camkes-1/interfaces/HelloSimple.idl4), +you must prefix the API function name with the name of the Interface +instance that you are exposing over the particular connection.

+ +

The reason for this is because it is possible for one component to +expose an interface multiple times, with each instance of that interface +referring to a different function altogether. For example, if a +composite device, such as a network card with with a serial interface +integrated into it, exposes two instances of a procedural interface that +has a particular procedure named send() – how will the caller of +send() know whether his send() is the one that is exposed over the +NIC connection, or the serial connection?

+ +

The same component provides both. Therefore, CAmkES prefixes the +instances of functions in an Interface with the Interface-instance’s +name. In the dual-function NIC device’s case, it might have a +provides <INTERFACE_NAME> serial and a provides <INTERFACE_NAME> nic. +When a caller wants to call for the NIC-send, it would call, +nic_send(), and when a caller wants to invoke the Serial-send, it would +call, serial_send().

+ +

So if the Hello interface is provided once by Echo as a, you would +call for the a instance of Echo’s Hello by calling for a_hello(). +But what if Echo had provided 2 instances of the Hello interface, and +the second one was named a2? Then in order to call on that second +Hello interface instance on Echo, you would call a2_hello().

+ +

Exercises

+ +

Define an instance in the composition section of the ADL

+ +

Exercise First modify hello-1.camkes. Define instances of Echo and Client in the +composition section of the ADL.

+ +
assembly {
+    composition {
+         component EmptyComponent empty;
+         // TODO define an Echo and a Client component
+
+ +
+ Quick solution + + 
assembly {
+    composition {
+         component EmptyComponent empty;
+         component Client client;
+         component Echo echo;
+
+ +
+ +

Add a connection

+ +

Exercise Now add a connection from client.hello to echo.hello.

+ +
        /* hint 1: use seL4RPCCall as the connector (or you could use seL4RPC if you prefer)
+         * hint 2: look at
+         * /projects/camkes/manual.html#creating-an-application
+         */
+
+ +
+ Quick solution + + 
        connection seL4RPCCall hello_con(from client.hello, to echo.hello);
+
+ +
+ +

Define an interface

+ +

Exercise Define the interface for hello in interfaces/HelloSimple.idl4.

+ +
/* Simple RPC interface */
+procedure HelloSimple {
+    /* TODO define RPC functions */
+    /* hint 1: define at least one function that takes a string as input parameter. call it say_hello. no return value
+     * hint 2: look at /projects/camkes/manual.html#creating-an-application
+     */
+
+ +
+ Quick solution + + 
    void say_hello(in string str);
+
+ +
+ +

Implement an RPC function

+ +

Exercise Implement the RPC hello function.

+ +
/* Implement the RPC function. */
+/* hint 1: the name of the function to implement is a composition of an interface name and a function name:
+ * i.e.: <interface>_<function>
+ * hint 2: the interfaces available are defined by the component, e.g. in hello-1.camkes
+ * hint 3: the function name is defined by the interface definition, e.g. in interfaces/HelloSimple.idl4
+ * hint 4: so the function would be: hello_say_hello()
+ * hint 5: the CAmkES 'string' type maps to 'const char *' in C
+ * hint 6: make the function print out a mesage using printf
+ * hint 7: look at /projects/camkes/manual.html#creating-an-application
+ */
+
+ +
+ Quick solution + + 
/* Implement the RPC function. */
+void hello_say_hello(const char *str) {
+    printf("Component %s saying: %s\n", get_instance_name(), str);
+}
+
+ +
+ +

Invoke an RPC function

+ +

Exercise Invoke the RPC function in components/Client/src/client.c.

+ +
    /* TODO: invoke the RPC function */
+    /* hint 1: the name of the function to invoke is a composition of an interface name and a function name:
+     * i.e.: <interface>_<function>
+     * hint 2: the interfaces available are defined by the component, e.g. in hello-1.camkes
+     * hint 3: the function name is defined by the interface definition, e.g. in interfaces/HelloSimple.idl4
+     * hint 4: so the function would be:  hello_say_hello()
+     * hint 5: look at /projects/camkes/manual.html#creating-an-application
+     */
+
+ +
+ Quick solution + + 
    /* Invoke the RPC function */
+    char *shello = "hello world";
+    hello_say_hello(shello);
+
+ +
+ +

Done

+ +

Now build and run the project. If it compiles: Congratulations!

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/hello-camkes-1.md b/Tutorials/hello-camkes-1.md deleted file mode 100644 index 558cbed0274..00000000000 --- a/Tutorials/hello-camkes-1.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Introduction to CAmkES -tutorial: hello-camkes-1 -layout: tutorial -description: an introduction to CAmkES concepts -nav_prev: hello-camkes-0.html -nav_next: hello-camkes-2.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/hello-camkes-2.html b/Tutorials/hello-camkes-2.html new file mode 100644 index 00000000000..94983a53501 --- /dev/null +++ b/Tutorials/hello-camkes-2.html @@ -0,0 +1,1243 @@ + + + + + + + Events in CAmkES | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Events in CAmkES

+ +

This tutorial shows how to build events in CAmkES.

+ +

Learn how to:

+ +
    +
  • Represent and implement events in CAmkES.
    • +
  • Use Dataports.
    • +
+ +

Use this slide presentation to guide you through the tutorials 0, 1 and 2.

+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Introduction to CAmkES tutorial
    3. +
+ +

capDL Loader

+ +

This tutorial uses the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +
+ Get capDL + +

The capDL loader parses a static description of the system and the relevant ELF +binaries. It is primarily used in +CAmkES projects but we also use it +in the tutorials to reduce redundant code. The program that you construct will +end up with its own CSpace and VSpace, which are separate from the root task, +meaning CSlots like seL4_CapInitThreadVSpace have no meaning in applications +loaded by the capDL loader.

+ +

More information about capDL projects can be found here.

+ +

For this tutorial clone the capDL repo. This can be added in a directory that is adjacent to the main tutorials directory.

+
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut hello-camkes-2
+# building the tutorial exercise
+cd hello-camkes-2_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut hello-camkes-2
+# building the tutorial exercise
+cd hello-camkes-2_build
+ninja
+
+ +
+ +

Specify an events interface

+ +

Here you’re declaring the events that will be bounced +back and forth in this tutorial. An event is a signal is sent over a +Notification connection.

+ +

You are strongly advised to read the manual section on Events here: +</projects/camkes/manual.html#an-example-of-events>.

+ +

'’Ensure that when declaring the consumes and emits keywords between + the Client.camkes and Echo.camkes files, you match them up so that + you’re not emitting on both sides of a single interface, or consuming + on both sides of an interface.’’

+ +

Specify an events interface

+ +
    /* TASK 1: the event interfaces */
+    /* hint 1: specify 2 interfaces: one "emits" and one "consumes"
+     * hint 2: you can use an arbitrary string as the interface type (it doesn't get used)
+     * hint 3: look at /projects/camkes/manual.html#an-example-of-events
+     */
+
+ +
+ Quick solution + + 
    /* TASK 1: the event interfaces */
+    emits TheEvent echo;
+    consumes TheEvent client;
+
+ +
+ +
    /* TASK 3: the event interfaces */
+    /* hint 1: specify 2 interfaces: one "emits" and one "consumes"
+     * hint 2: you can use an arbitrary string as the interface type (it doesn't get used)
+     * hint 3: look at /projects/camkes/manual.html#an-example-of-events
+     */
+
+ +
+ Quick solution + + 
    /* TASK 3: the event interfaces */
+    consumes TheEvent echo;
+    emits TheEvent client;
+
+
+ +

Add connections

+ +
    /* TASK 5: Event connections */
+    /* hint 1: connect each "emits" interface in a component to the "consumes" interface in the other
+     * hint 2: use seL4Notification as the connector
+     * hint 3: look at /projects/camkes/manual.html#an-example-of-events
+     */
+
+ +
+ Quick solution + + 
    /* TASK 5: Event connections */
+    connection seL4Notification echo_event(from client.echo, to echo.echo);
+    connection seL4Notification client_event(from echo.client, to client.client);
+
+ +
+ +

Data

+ +

Recall that CAmkES prefixes the name of the interface instance to the function +being called across that interface? This is the same phenomenon, but for events; +in the case of a connection over which events are sent, there is no API, but +rather CAmkES will generate _emit() and _wait() functions to enable the +application to transparently interact with these events.

+ +

Signal that the data is available

+ +
    /* TASK 10: emit event to signal that the data is available */
+    /* hint 1: use the function <interface_name>_emit
+    * hint 2: look at /projects/camkes/manual.html#an-example-of-events
+    */
+
+ +
+ Quick solution + + 
    /* TASK 10: emit event to signal that the data is available */
+    echo_emit();
+
+ +
+ +

Wait for data to become available

+ +
    /* TASK 11: wait to get an event back signalling that the reply data is available */
+    /* hint 1: use the function <interface_name>_wait
+     * hint 2: look at /projects/camkes/manual.html#an-example-of-events
+     */
+
+ +
+ Quick solution + + 
    /* TASK 11: wait to get an event back signalling that the reply data is available */
+    client_wait();
+
+ +
+ +

Signal that data is available

+ +
    /* TASK 14: emit event to signal that the data is available */
+    /* hint 1: we've already done this before */
+
+ +
+ Quick solution + + 
    /* TASK 14: emit event to signal that the data is available */
+    echo_emit();
+
+ +
+ +

Wait for data to be read

+ +
    /* TASK 15: wait to get an event back signalling that data has been read */
+    /* hint 1: we've already done this before */
+
+ +
+ Quick solution + + 
    /* TASK 15: wait to get an event back signalling that data has been read */
+    client_wait();
+
+ +
+ +

Signal that data is available

+ +
    /* TASK 22: notify the client that there is new data available for it */
+    /* hint 1: use the function <interface_name>_emit
+    * hint 2: look at /projects/camkes/manual.html#an-example-of-events
+    */
+
+ +
+ Quick solution + + 
    /* TASK 22: notify the client that there is new data available for it */
+    client_emit();
+
+ +
+ +

Signal that data has been read

+ +
    /* TASK 25: notify the client that we are done reading the data */
+    /* hint 1: use the function <interface_name>_emit
+    * hint 2: look at /projects/camkes/manual.html#an-example-of-events
+    */
+
+ +
+ Quick solution + + 
    /* TASK 25: notify the client that we are done reading the data */
+    client_emit();
+
+ +
+ +

Handle notifications

+ +

One way to handle notifications in CAmkES is to use callbacks when they are +raised. CAmkES generates functions that handle the registration of callbacks for +each notification interface instance. These steps help you to become familiar +with this approach.

+ +

Register a callback handler

+ +
    /* TASK 18: register the first callback handler for this interface */
+    /* hint 1: use the function <interface name>_reg_callback()
+     * hint 2: register the function "callback_handler_1"
+     * hint 3: pass NULL as the extra argument to the callback
+     * hint 4: look at /projects/camkes/manual.html#an-example-of-events
+     */
+
+ +
+ Quick solution + + 
    /* TASK 18: register the first callback handler for this interface */
+    int error = echo_reg_callback(callback_handler_1, NULL);
+    ZF_LOGF_IF(error != 0, "Failed to register callback");
+
+ +
+ +

Register another callback handler

+ +
  /* TASK 21: register the second callback for this event. */
+  /* hint 1: use the function <interface name>_reg_callback()
+    * hint 2: register the function "callback_handler_2"
+    * hint 3: pass NULL as the extra argument to the callback
+    * hint 4: look at /projects/camkes/manual.html#an-example-of-events
+    */
+
+ +
+ Quick solution + + 
    /* TASK 21: register the second callback for this event. */
+    int error = echo_reg_callback(callback_handler_2, NULL);
+    ZF_LOGF_IF(error != 0, "Failed to register callback");
+
+ +
+ +

Register a callback handler

+ +
  /* TASK 24: register the original callback handler for this event */
+    /* hint 1: use the function <interface name>_reg_callback()
+     * hint 2: register the function "callback_handler_1"
+     * hint 3: pass NULL as the extra argument to the callback
+     * hint 4: look at /projects/camkes/manual.html#an-example-of-events
+     */
+
+ +
+ Quick solution + + 
    /* TASK 24: register the original callback handler for this event */
+    int error = echo_reg_callback(callback_handler_1, NULL);
+    ZF_LOGF_IF(error != 0, "Failed to register callback");
+
+ +
+ +
+ +

Dataports

+ +

Dataports are typed shared memory mappings. In your CAmkES ADL specification, +you state what C data type you’ll be using to access the data in the shared +memory – so you can specify a C struct type, etc.

+ +

The really neat part is more that CAmkES provides access control for +accessing these shared memory mappings: if a shared memory mapping is such +that one party writes and the other reads and never writes, we can tell +CAmkES about this access constraint in ADL.

+ +

So in TASKs 2 and 4, you’re first being led to create the “Dataport” +interface instances on each of the components that will be participating +in the shared memory communication. We will then link them together using a +“seL4SharedData” connector later on.

+ +

Specify dataport interfaces

+ +
    /* TASK 2: the dataport interfaces */
+    /* hint 1: specify 3 interfaces: one of type "Buf", one of type "str_buf_t" and one of type "ptr_buf_t"
+     * hint 2: for the definition of these types see "str_buf.h".
+     * hint 3: look at /projects/camkes/manual.html#an-example-of-dataports
+     */
+
+ +
+ Quick solution + + 
    /* TASK 2: the dataport interfaces */
+    dataport Buf d;
+    dataport str_buf_t d_typed;
+    dataport ptr_buf_t d_ptrs;
+
+ +
+ +

Specify dataport interfaces

+ +
    /* TASK 4: the dataport interfaces */
+    /* hint 1: specify 3 interfaces: one of type "Buf", one of type "str_buf_t" and one of type "ptr_buf_t"
+     * hint 3: look at /projects/camkes/manual.html#an-example-of-dataports
+     */
+
+ +
+ Quick solution + + 
    /* TASK 4: the dataport interfaces */
+    dataport Buf d;
+    dataport str_buf_t d_typed;
+    dataport ptr_buf_t d_ptrs;
+
+ +
+ +

Dataport connections

+ +

And here we are: we’re about to specify connections between the shared memory +pages in each client, and tell CAmkES to link these using shared underlying +Frame objects. Fill out this step, and proceed.

+ +

Specify dataport connections

+ +
    /* TASK 6: Dataport connections */
+    /* hint 1: connect the corresponding dataport interfaces of the components to each other
+    * hint 2: use seL4SharedData as the connector
+    * hint 3: look at /projects/camkes/manual.html#an-example-of-dataports
+    */
+
+ +
+ Quick solution + + 
    /* TASK 6: Dataport connections */
+    connection seL4SharedData data_conn(from client.d, to echo.d);
+    connection seL4SharedData typed_data_conn(from client.d_typed, to echo.d_typed);
+    connection seL4SharedData ptr_data_conn(from client.d_ptrs, to echo.d_ptrs);
+
+ +
+ +

Access and manipulate share memory mapping (Dataport) of the client

+ +

These steps are asking you to write some C code to access and manipulate the +data in the shared memory mapping (Dataport) of the client. Follow through to +the next step.

+ +

Copy strings to an untyped dataport

+ +
    /* TASK 9: copy strings to an untyped dataport */
+    /* hint 1: use the "Buf" dataport as defined in the Client.camkes file
+     * hint 2: to access the dataport use the interface name as defined in Client.camkes.
+     * For example if you defined it as "dataport Buf d" then you would use "d" to refer to the dataport in C.
+     * hint 3: first write the number of strings (NUM_STRINGS) to the dataport
+     * hint 4: then copy all the strings from "s_arr" to the dataport.
+     * hint 5: look at /projects/camkes/manual.html#an-example-of-dataports
+     */
+
+ +
+ Quick solution + + 
    /* TASK 9: copy strings to an untyped dataport */
+    int *n = (int*)d;
+    *n = NUM_STRINGS;
+    char *str = (char*)(n + 1);
+    for (int i = 0; i < NUM_STRINGS; i++) {
+        strcpy(str, s_arr[i]);
+        str += strlen(str) + 1;
+    }
+
+ +
+ +

Read the reply data from a typed dataport

+ +
    /* TASK 12: read the reply data from a typed dataport */
+    /* hint 1: use the "str_buf_t" dataport as defined in the Client.camkes file
+     * hint 2: to access the dataport use the interface name as defined in Client.camkes.
+     * For example if you defined it as "dataport str_buf_t d_typed" then you would use "d_typed" to refer to the dataport in C.
+     * hint 3: for the definition of "str_buf_t" see "str_buf.h".
+     * hint 4: use the "n" field to determine the number of strings in the dataport
+     * hint 5: print out the specified number of strings from the "str" field
+     * hint 6: look at /projects/camkes/manual.html#an-example-of-dataports
+     */
+
+ +
+ Quick solution + + 
    /* TASK 12: read the reply data from a typed dataport */
+    for (int i = 0; i < d_typed->n; i++) {
+        printf("%s: string %d (%p): \"%s\"\n", get_instance_name(), i, d_typed->str[i], d_typed->str[i]);
+    }
+
+ +
+ +

Send data using dataports

+ +
  /* TASK 13: send the data over again, this time using two dataports, one
+     * untyped dataport containing the data, and one typed dataport containing
+     * dataport pointers pointing to data in the untyped, dataport.
+     */
+    /* hint 1: for the untyped dataport use the "Buf" dataport as defined in the Client.camkes file
+     * hint 2: for the typed dataport use the "ptr_buf_t" dataport as defined in the Client.camkes file
+     * hint 3: for the definition of "ptr_buf_t" see "str_buf.h".
+     * hint 4: copy all the strings from "s_arr" into the untyped dataport
+     * hint 5: use the "n" field of the typed dataport to specify the number of dataport pointers (NUM_STRINGS)
+     * hint 6: use the "ptr" field of the typed dataport to store the dataport pointers
+     * hint 7: use the function "dataport_wrap_ptr()" to create a dataport pointer from a regular pointer
+     * hint 8: the dataport pointers should point into the untyped dataport
+     * hint 9: for more information about dataport pointers see: /projects/camkes/manual.html
+     */
+
+ +
+ Quick solution + + 
    /* TASK 13: send the data over again, this time using two dataports, one
+     * untyped dataport containing the data, and one typed dataport containing
+     * dataport pointers pointing to data in the untyped, dataport.
+     */
+    d_ptrs->n = NUM_STRINGS;
+    str = (char*)d;
+    for (int i = 0; i < NUM_STRINGS; i++) {
+        strcpy(str, s_arr[i]);
+        d_ptrs->ptr[i] = dataport_wrap_ptr(str);
+        str += strlen(str) + 1;
+    }
+
+ +
+ +

Access and manipulate share memory mapping (Dataport) of the server

+ +

And these steps are asking you to write some C +code to access and manipulate the data in the shared memory mapping +(Dataport) of the server.

+ +

Read data from an untyped dataport

+ +
  /* TASK 19: read some data from the untyped dataport */
+  /* hint 1: use the "Buf" dataport as defined in the Echo.camkes file
+    * hint 2: to access the dataport use the interface name as defined in Echo.camkes.
+    * For example if you defined it as "dataport Buf d" then you would use "d" to refer to the dataport in C.
+    * hint 3: first read the number of strings from the dataport
+    * hint 4: then print each string from the dataport
+    * hint 5: look at /projects/camkes/manual.html#an-example-of-dataports
+    */
+
+ +
+ Quick solution + + 
    /* TASK 19: read some data from the untyped dataport */
+    int *n = (int*)d;
+    char *str = (char*)(n + 1);
+    for (int i = 0; i < *n; i++) {
+      printf("%s: saying (%p): \"%s\"\n", get_instance_name(), str, str);
+      str += strlen(str) + 1;
+    }
+
+ +
+ +

Put data into a typed dataport

+ +
  /* TASK 20: put a modified copy of the data from the untyped dataport into the typed dataport */
+    /* hint 1: modify each string by making it upper case, use the function "uppercase"
+     * hint 2: read from the "Buf" dataport as above
+     * hint 3: write to the "str_buf_t" dataport as defined in the Echo.camkes file
+     * hint 4: to access the dataport use the interface name as defined in Echo.camkes.
+     * For example if you defined it as "dataport str_buf_t d_typed" then you would use "d_typed" to refer to the dataport in C.
+     * hint 5: for the definition of "str_buf_t" see "str_buf.h"
+     * hint 6: use the "n" field to specify the number of strings in the dataport
+     * hint 7: copy the specified number of strings from the "Buf" dataport to the "str" field
+     * hint 8: look at /projects/camkes/manual.html#an-example-of-dataports
+     * hint 9: you could combine this TASK with the previous one in a single loop if you want
+     */
+
+ +
+ Quick solution + + 
  /* TASK 20: put a modified copy of the data from the untyped dataport into the typed dataport */
+    n = (int*)d;
+    str = (char*)(n + 1);
+    for (int i = 0, j = *n - 1; i < *n; i++, j--) {
+        strncpy(d_typed->str[j], str, STR_LEN);
+        uppercase(d_typed->str[j]);
+        str += strlen(str) + 1;
+    }
+    d_typed->n = *n;
+
+ +
+ +

Read data from a typed dataport

+ +
  /* TASK 23: read some data from the dataports. specifically:
+    * read a dataport pointer from one of the typed dataports, then use
+    * that pointer to access data in the untyped dataport.
+    */
+  /* hint 1: for the untyped dataport use the "Buf" dataport as defined in the Echo.camkes file
+    * hint 2: for the typed dataport use the "ptr_buf_t" dataport as defined in the Echo.camkes file
+    * hint 3: for the definition of "ptr_buf_t" see "str_buf.h".
+    * hint 4: the "n" field of the typed dataport specifies the number of dataport pointers
+    * hint 5: the "ptr" field of the typed dataport contains the dataport pointers
+    * hint 6: use the function "dataport_unwrap_ptr()" to create a regular pointer from a dataport pointer
+    * hint 7: for more information about dataport pointers see: /projects/camkes/manual.html
+    * hint 8: print out the string pointed to by each dataport pointer
+    */
+
+ +
+ Quick solution + + 
  /* TASK 23: read some data from the dataports. specifically:
+    * read a dataport pointer from one of the typed dataports, then use
+    * that pointer to access data in the untyped dataport.
+    */
+  char *str;
+  for (int i = 0; i < d_ptrs->n; i++) {
+      str = dataport_unwrap_ptr(d_ptrs->ptr[i]);
+      printf("%s: dptr saying (%p): \"%s\"\n", get_instance_name(), str, str);
+  }
+
+ +
+ +

CAmkES attributes

+ +

This is an introduction to CAmkES attributes: you’re +being asked to set the priority of the components.

+ +

Set component priorities

+ +
    /* TASK 7: set component priorities */
+    /* hint 1: component priority is specified as an attribute with the name <component name>.priority
+    * hint 2: the highest priority is represented by 255, the lowest by 0
+    */
+
+ +
+ Quick solution + + 
    /* TASK 7: set component priorities */
+    client.priority = 255;
+    echo.priority = 254;
+
+ +
+ +

Specify the data access constraints for Dataports

+ +

This is where we specify the data access constraints +for the Dataports in a shared memory connection. We then go about +attempting to violate those constraints to see how CAmkES has truly met +our constraints when mapping those Dataports.

+ +

Restrict access to dataports

+ +
    /* TASK 8: restrict access to dataports */
+    /* hint 1: use attribute <component>.<interface_name>_access for each component and interface
+    * hint 2: appropriate values for the to_access and from_access attributes are: "R" or "W"
+    * hint 4: make the "Buf" dataport read only for the Echo component
+    * hint 3: make the "str_buf_t" dataport read only for the Client component
+    */
+
+ +
+ Quick solution + + 
    /* TASK 8: restrict access to dataports */
+    echo.d_access = "R";
+    client.d_access = "W";
+    echo.d_typed_access = "W";
+    client.d_typed_access = "R";
+
+ +
+ +

Test the read and write permissions on the dataport

+ +
    /* TASK 16: test the read and write permissions on the dataport.
+    * When we try to write to a read-only dataport, we will get a VM fault.
+    */
+    /* hint 1: try to assign a value to a field of the "str_buf_t" dataport */
+
+ +
+ Quick solution + + 
    /* TASK 16: test the read and write permissions on the dataport.
+    * When we try to write to a read-only dataport, we will get a VM fault.
+    */
+    d_typed->n = 0;
+
+ +
+ +

Done!

+ +

Congratulations! You have completed the third CAmkES tutorial.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/hello-camkes-2.md b/Tutorials/hello-camkes-2.md deleted file mode 100644 index 34d2e5aa65d..00000000000 --- a/Tutorials/hello-camkes-2.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Events in CAmkES -tutorial: hello-camkes-2 -layout: tutorial -description: an introduction to CAmkES concepts -nav_prev: hello-camkes-1.html -nav_next: hello-camkes-timer.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/hello-camkes-timer.html b/Tutorials/hello-camkes-timer.html new file mode 100644 index 00000000000..232e458753c --- /dev/null +++ b/Tutorials/hello-camkes-timer.html @@ -0,0 +1,1121 @@ + + + + + + + CAmkES timer tutorial | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

CAmkES Timer Tutorial

+ +

This tutorial guides you through setting up a sample timer driver component in +CAmkES and using it to delay for 2 seconds. For this tutorial, we will be using +the ZYNQ7000 ARM-based platform. This platform can be simulated via QEMU so it +is not a problem if you do not have access to the actual physical board.

+ +

The tutorial also has two parts to it. The first part will teach you how to +manually define hardware details to configure the hardware component and +initialise hardware resources. The second part will teach you how to use a +CAmkES connector to initialise hardware resources automatically for you.

+ +

The solutions to this tutorial primarily uses the method of manually defining +hardware details. The solutions to the second part are also included, albeit +commented out.

+ +

Prerequisites

+ +
    +
  1. Set up your machine.
    2. +
  2. CAmkES 2
    3. +
+ +

capDL Loader

+ +

This tutorial uses the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +
+ Get capDL +

The capDL loader parses a static description of the system and the relevant ELF +binaries. It is primarily used in +CAmkES projects but we also use it +in the tutorials to reduce redundant code. The program that you construct will +end up with its own CSpace and VSpace, which are separate from the root task, +meaning CSlots like seL4_CapInitThreadVSpace have no meaning in applications +loaded by the capDL loader.

+ +

More information about capDL projects can be found +here.

+ +

For this tutorial clone the capDL repo. This +can be added in a directory that is adjacent to the main tutorials directory.

+
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut hello-camkes-timer
+# building the tutorial exercise
+cd hello-camkes-timer_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut hello-camkes-timer
+# building the tutorial exercise
+cd hello-camkes-timer_build
+ninja
+
+ +
+ +

Exercises - Part 1

+ +

Instantiate a Timer and Timerbase

+ +

Start in hello-camkes-timer.camkes.

+ +

Instantiate some components. You’re already given one component instance +— client. You need to instantiate additional components, a timer driver and +a component instance representing the timer hardware itself. Look +in components/Timer/Timer.camkes for the definitions of the components.

+ +

Once you open the file, you will notice three different components. The Timer +and Timerbase components represents the timer driver and the timer hardware +respectively. The TimerDTB component represents both the timer driver and the +timer hardware. This component is meant to be used with the seL4DTBHardware +CAmkES connector to automatically initialise hardware resources. The second +part of the tutorial will go into more detail about the TimerDTB component +and the seL4DTBHardware connector.

+ +

For now, instantiate the Timer and Timerbase components.

+ +

Note the lines connection seL4RPCCall hello_timer(from client.hello, to +timer.hello); and timer.sem_value = 0; in the hello-camkes-timer.camkes +file. They assume that the name of the timer ‘‘driver’’ will be timer. If you +wish to call your driver something else, you’ll have to change these lines.

+ +
    /* Part 1, TASK 1: component instances */
+    /* hint 1: one hardware component and one driver component
+        * hint 2: look at
+        * /projects/camkes/manual.html#creating-an-application
+        */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 1: component instances */
+    component Timerbase timerbase;
+    component Timer timer;
+
+
+ +

Connect a timer driver component

+ +

Connect the timer driver component (Timer) to the timer hardware component +(Timerbase). The timer hardware component exposes two interfaces which must +be connected to the timer driver. One of these represents memory-mapped +registers. The other represents an interrupt.

+ +
    /* Part 1, TASK 2: connections */
+    /* hint 1: use seL4HardwareMMIO to connect device memory
+        * hint 2: use seL4HardwareInterrupt to connect interrupt
+        * hint 3: look at
+        * /projects/camkes/manual.html#creating-an-application
+        */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 2: connections */
+    connection seL4HardwareMMIO timer_mem(from timer.reg, to timerbase.reg);
+    connection seL4HardwareInterrupt timer_irq(from timerbase.irq, to timer.irq);
+
+ +
+ +

Configure a timer hardware component instance

+ +

Configure the timer hardware component instance with device-specific info. The +physical address of the timer’s memory-mapped registers, and its IRQ number +must both be configured.

+ +
    /* Part 1, TASK 3: hardware resources */
+    /* Timer and Timerbase:
+        * hint 1: find out the device memory address and IRQ number from the hardware data sheet
+        * hint 2: look at
+        * /projects/camkes/manual.html#hardware-components
+        */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 3: hardware resources */
+    timerbase.reg_paddr = 0xF8001000;   // paddr of mmio registers
+    timerbase.reg_size = 0x1000;        // size of mmio registers
+    timerbase.irq_irq_number = 42;      // timer irq number
+
+ +
+ +

Call into a supplied driver to handle the interrupt

+ +

Now open components/Timer/src/timer.c.

+ +

We’ll start by completing the irq_handle function, which is called in +response to each timer interrupt. Note the name of this function. It follows +the naming convention <interface>_handle, where <interface> is the name of +an IRQ interface connected with seL4HardwareInterrupt. When an interrupt is +received on the interface <interface>, the function <interface>_handle will +be called.

+ +

The implementation of the timer driver is located inside a different folder and +can be found in the projects/sel4-tutorials/zynq_timer_driver folder from the +root of the projects directory, i.e. where the .repo folder can be found and +where the initial repo init command was executed.

+ +

This task is to call the timer_handle_irq function from the supply driver to +inform the driver that an interrupt has occurred.

+ +
    /* Part 1, TASK 4: call into the supplied driver to handle the interrupt. */
+    /* hint: timer_handle_irq
+     */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 4: call into the supplied driver to handle the interrupt. */
+    timer_handle_irq(&timer_drv);
+
+ +
+ +

Stop a timer

+ +

Stop the timer from running. The timer_stop function will be helpful here.

+ +
    /* Part 1, TASK 5: stop the timer. */
+    /* hint: timer_stop
+     */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 5: stop the timer. */
+    timer_stop(&timer_drv);
+
+ +
+ +

Acknowledge an interrupt

+ +

The interrupt now needs to be acknowledged.

+ +

CAmkES generates the seL4-specific code for ack-ing an interrupt and provides a +function <interface>_acknowldege for IRQ interfaces (specifically those +connected with seL4HardwareInterrupt).

+ +
    /* Part 1, TASK 6: acknowledge the interrupt */
+    /* hint 1: use the function <irq interface name>_acknowledge()
+     */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 6: acknowledge the interrupt */
+    error = irq_acknowledge();
+    ZF_LOGF_IF(error != 0, "failed to acknowledge interrupt");
+
+ +
+ +

Get a timer handler

+ +

Now we’ll complete hello__init - a function which is called once +before the component’s interfaces start running.

+ +

We need to initialise a handle to the timer driver for this device, and store a +handle to the driver in the global variable timer_drv.

+ +
    /* Part 1, TASK 7: call into the supplied driver to get the timer handler */
+    /* hint1: timer_init
+     * hint2: The timer ID is supplied as a #define in this file
+     * hint3: The register's variable name is the same name as the dataport in the Timer component
+     */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 7: call into the supplied driver to get the timer handler */
+    int error = timer_init(&timer_drv, DEFAULT_TIMER_ID, reg);
+    assert(error == 0);
+
+ +
+ +

Start a timer

+ +

After initialising the timer, we now need to start the timer. Do so by calling +timer_start and passing the handle to the driver.

+ +
    /* Part 1, TASK 8: start the timer */
+    /* hint: timer_start
+     */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 8: start the timer */
+    error = timer_start(&timer_drv);
+    assert(error == 0);
+
+ +
+ +

Implement an RPC interface

+ +

Note that this task is to understand the existing code. You won’t have +to modify anything for this task.

+ +

Implement the timer_inf RPC interface. This interface is defined in +interfaces/timer.camkes, and contains a single method, sleep, which +should return after a given number of seconds. in +components/Timer/Timer.camkes, we can see that the timer_inf interface +exposed by the Timer component is called hello. Thus, the function we +need to implement is called hello_sleep.

+ +
    /* Part 1, TASK 9: implement the rpc function. */
+    /* hint 1: the name of the function to implement is a composition of an interface name and a function name:
+    * i.e.: <interface>_<function>
+    * hint 2: the interfaces available are defined by the component, e.g. in components/timer/timer.camkes
+    * hint 3: the function name is defined by the interface definition, e.g. in interfaces/timer.camkes
+    * hint 4: so the function would be: hello_sleep()
+    * hint 5: the camkes 'int' type maps to 'int' in c
+    * hint 6: invoke a function in supplied driver the to set up the timer
+    * hint 7: look at /projects/camkes/manual.html#creating-an-application
+    */
+
+ +
+ Quick solution + + 
/* Part 1, TASK 9: implement the rpc function. */
+void hello_sleep(int sec) {
+    int error = 0;
+
+ +
+ +

Set a timer interrupt

+ +

Tell the timer to interrupt after the given number of seconds. The +timer_set_timeout function from the included driver will help. Note that it +expects its time argument to be given in nanoseconds.

+ +
    /* Part 1, TASK 10: invoke a function in the supplied driver to set a timeout */
+    /* hint1: timer_set_timeout
+     * hint2: periodic should be set to false
+     */
+
+ +
+ Quick solution + + 
    /* Part 1, TASK 10: invoke a function in the supplied driver to set a timeout */
+    error = timer_set_timeout(&timer_drv, sec * NS_IN_SECOND, false);
+    assert(error == 0);
+
+ +
+ +

Note the existing code in hello_sleep. It waits on a binary semaphore. +irq_handle will be called on another thread when the timer interrupt occurs, +and that function will post to the binary semaphore, unblocking us and allowing +the function to return after the delay.

+ +

Expect the following output with a 2 second delay between the last 2 +lines:

+ +
Starting the client
+------Sleep for 2 seconds------
+After the client: wakeup
+
+ +

Exercises - Part 2

+ +

Now that you’ve learnt how to manually define the hardware details of a +hardware component to initialise hardware resources, this part of the tutorial +will teach you how to use the seL4DTBHardware connector to do that +automatically.

+ +

The connector requires a device tree blob which describes an ARM platform. +Additionally, the blob’s interrupt fields also need to follow the same format +of the ARM GIC v1 and v2. There are device tree source files bundled with the +kernel, look in the tools/dts/ folder of the kernel sources. If a suitable +device tree blob is not available for your platform, then do not proceed with +the tutorial.

+ +

Instantiate a TimerDTB component

+ +

Navigate to the hello-camkes-timer.camkes file.

+ +

Remove the Timerbase and Timer component instantiations and instantiate a +TimerDTB component instead. Also change the connection seL4RPCCall +hello_timer(from client.hello, to timer.hello); and timer.sem_value = 0; +lines if necessary.

+ +
    /* Part 2, TASK 1: component instances */
+    /* hint 1: a single TimerDTB component
+    * hint 2: look at
+    * /projects/camkes/manual.html#creating-an-application
+    */
+
+ +
+ Quick solution + + 
    /* Part 2, TASK 1: component instances */
+    //uncomment the line below
+//    component TimerDTB timer;
+
+ +
+ +

Connect interfaces using the seL4DTBHardware connector

+ +

Remove the seL4HardwareMMIO and seL4HardwareInterrupt connections. Connect +the two interfaces inside the TimerDTB component with the seL4DTBHardware +connector.

+ +
    /* Part 2, TASK 2: connections */
+    /* hint 1: connect the dummy_source and timer interfaces
+    * hint 2: the dummy_source should be the 'from' end
+    * hint 3: look at
+    * /projects/camkes/manual.html#creating-an-application
+    */
+
+ +
+ Quick solution + + 
      /* Part 2, TASK 2: connections */
+      // uncomment the line below
+//    connection seL4DTBHardware timer_dtb(from timer.dummy_source, to timer.tmr);
+
+ +
+ +

Configure the TimerDTB component

+ +

Before opening components/Timer/Timer.camkes, remove the Timerbase settings +inside the configurations block.

+ +

Configure the TimerDTB component to pass in the correct DTB path to a timer +to the connector and also initialise the interrupt resources for the timer. +This will allow the connector to read a device node from the device tree blob +and grab the necessary data to initialise hardware resources. More +specifically, it reads the registers field and optionally the interrupts field +to allocate memory and interrupts.

+ +
    /* Part 2, TASK 3: hardware resources */
+    /* TimerDTB:
+     * hint 1: look in the DTB/DTS for the path of a timer
+     * hint 2: set the 'dtb' setting for the tmr interface in the TimerDTB component,
+     *         e.g. foo.dtb = dtb({"path" : "/bar"});
+     * hint 3: set the 'generate_interrupts' setting to 1
+     */
+
+ +
+ Quick solution + + 
     /* Part 2, TASK 3: hardware resources */
+     // uncomment the lines below
+//    tmr.dtb = dtb({"path" : "/amba/timer@f8001000"});   // path of the timer in the DTB
+//    tmr.generate_interrupts = 1;                        // tell seL4DTBHardware to init interrupts
+
+ +
+ +

Handle the interrupt

+ +

Move to components/TimerDTB/src/timerdtb.c.

+ +

Similar to part one, we’ll start with the tmr_irq_handle function. This +function is called in response to a timer interrupt. The name of the function +has a special meaning and the meaning is unique to the seL4DTBHardware +connector.

+ +

The IRQ handling functions of the connector follows the naming convention +<to_interface>_irq_handle, where <to_interface> is the name of the +interface of the ‘to’ end in an instance of a seL4DTBHardware connection. +Also notice that it takes a ps_irq_t * type. This is because, for a given +device, there may be multiple interrupts associated with the device. A +ps_irq_t struct is given to the IRQ handling function and it contains +information about the interrupt, allowing the handler to differentiate between +the numerous interrupts of a device.

+ +

Likewise with part one, the implementation of the timer driver is in the +included driver in timer_driver and the task here is to call +timer_handle_irq.

+ +
    /* Part 2, TASK 4: call into the supplied driver to handle the interrupt. */
+    /* hint: timer_handle_irq
+     */
+
+ +
+ Quick solution + + 
    /* Part 2, TASK 4: call into the supplied driver to handle the interrupt. */
+    timer_handle_irq(&timer_drv);
+
+ +
+ +

Stop a timer

+ +

Stop the timer from running. The timer_stop function will be helpful here.

+ +
    /* Part 2, TASK 5: stop the timer. */
+    /* hint: timer_stop
+     */
+
+ +
+ Quick solution + + 
    /* Part 2, TASK 5: stop the timer. */
+    timer_stop(&timer_drv);
+
+ +
+ +

Acknowledge the interrupt

+ +

Again, the interrupt now has to be acknowledged.

+ +

For the seL4DTBHardware connector, CAmkES also generates and provides a +function to acknowledge interrupts. This function follows a similar naming +convention to the IRQ handler above, <to_interface>_irq_acknowledge also +takes in a ps_irq_t * argument. Similarly, the ps_irq_t * argument helps +CAmkES to differentiate between the possibly many interrupts of a device that +you wish to acknowledge.

+ +
    /* Part 2, TASK 6: acknowledge the interrupt */
+    /* hint 1: use the function <to_interface_name>_irq_acknowledge()
+     * hint 2: pass in the 'irq' variable to the function
+     */
+
+ +
+ Quick solution + + 
    /* Part 2, TASK 6: acknowledge the interrupt */
+    error = tmr_irq_acknowledge(irq);
+    ZF_LOGF_IF(error != 0, "failed to acknowledge interrupt");
+
+ +
+ +

TASK 7 - 10

+ +

Task 7 to 10 are the exact same as the tasks in part one.

+ +

You should also expect the same output as the first part.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/hello-camkes-timer.md b/Tutorials/hello-camkes-timer.md deleted file mode 100644 index d4c4b0f88e0..00000000000 --- a/Tutorials/hello-camkes-timer.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: CAmkES timer tutorial -tutorial: hello-camkes-timer -layout: tutorial -description: introduce CAmkES hardware components -nav_prev: hello-camkes-2.html -nav_next: camkes-vm-linux.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/hello-world.html b/Tutorials/hello-world.html new file mode 100644 index 00000000000..8078633f8e9 --- /dev/null +++ b/Tutorials/hello-world.html @@ -0,0 +1,805 @@ + + + + + + + Hello, World! | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Hello, World!

+ +

In this tutorial you will:

+ +
    +
  1. Run Hello, World! to ensure your setup is working correctly
    2. +
  2. Become familiar with the jargon root task
    3. +
  3. Build and simulate a seL4 project
    4. +
  4. Have a basic understanding of the role of the CMakeLists.txt file in applications
    5. +
+ +

Prerequisites

+
    +
  1. Set up your machine
    2. +
+ +

Building your first program

+

seL4 is a microkernel, not an operating system, and as a result only provides very minimal services.

+ +

After the kernel boots, an initial thread called the root task is started, which is then responsible for setting up the user-level system.

+ +

When the root task starts there are no available drivers, however a minimal C library is provided.

+ +

The tutorial is already set up to print “Hello, world!”, so at this point all you need to do is build and run the tutorial.

+ +

Revisiting containers

+ +

We will use two terminals, as described in Setting up your machine.

+
    +
  • Terminal A is just a normal terminal, and is used for git operations, editing (e.g., vim, emacs), and other normal operations.
    • +
  • Terminal B is running in a container, and is only used for compilation.
    • +
+ +

This gives you the flexibility to use all the normal tools you are used to, while having the seL4 dependencies separated from your machine.

+ +

Create a container

+ +

Open a new terminal, Terminal B, to run a container.

+ +

Create a container:

+ +
container
+
+ +

Initialising

+ +

Initialise the tutorial in Terminal B, which is running the container.

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut hello-world
+# building the tutorial exercise
+cd hello-world_build
+ninja
+
+ +

This step creates two new directories in tutorials/, namely hello-world and hello-world_build

+ +
+ + Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut hello-world
+# building the tutorial exercise
+cd hello-world_build
+ninja
+
+ +

This will generate another hello-world directory and hello-world_build directory, with unique names, e.g. hello-world44h1po5q and hello-world44h1po5q_build.

+ +
+ +

Build the program

+ +
cd tutorials/hello-world_build
+
+ +

Next, build the program in Terminal B using ninja

+ +
# In build directory
+ninja
+
+ +

If successful, you should see the final ninja rule passing, e.g.:

+ +
[150/150] objcopy kernel into bootable elf
+
+ +

Run Hello, World using QEMU

+ +

The final image can be run by:

+ +
./simulate
+
+ +

This will run the result on an instance of the QEMU simulator.

+ +

If everything has worked, you should see:

+ +
Booting all finished, dropped to user space
+
+Hello, World!
+
+ +

After that output, there should be a capability violation and a stack dump, +because the program hasn’t properly cleaned up after itself yet. (This will come in later examples)

+ +

Ctrl-A, X will terminate QEMU.

+ +

Looking at the sources

+

To look at the sources, open a new terminal, Terminal A:

+ +
cd tutorials/hello-world
+ls
+
+ +

In your tutorial directory, you will find the following files:

+
    +
  • CMakeLists.txt - the file that incorporates the root task into the wider seL4 build system.
    • +
  • src/main.c - the single source file for the initial task.
    • +
  • hello-world.md - A generated README for the tutorial.
    • +
+ +

CMakeLists.txt

+ +

Every application and library in an seL4 project requires a CMakeLists.txt file in order to be + incorporated into the project build system.

+ +
include(${SEL4_TUTORIALS_DIR}/settings.cmake)
+sel4_tutorials_regenerate_tutorial(${CMAKE_CURRENT_SOURCE_DIR})
+
+cmake_minimum_required(VERSION 3.7.2)
+# declare the hello-world CMake project and the languages it is written in (just C)
+project(hello-world C ASM)
+
+# In future tutorials, these setup steps will be replaced with
+# sel4_tutorials_setup_roottask_tutorial_environment()
+find_package(seL4 REQUIRED)
+find_package(elfloader-tool REQUIRED)
+find_package(musllibc REQUIRED)
+find_package(util_libs REQUIRED)
+find_package(seL4_libs REQUIRED)
+
+sel4_import_kernel()
+elfloader_import_project()
+
+# This sets up environment build flags and imports musllibc and runtime libraries.
+musllibc_setup_build_environment_with_sel4runtime()
+sel4_import_libsel4()
+util_libs_import_libraries()
+sel4_libs_import_libraries()
+sel4_tutorials_import_libsel4tutorials()
+
+# Name the executable and list source files required to build it
+add_executable(hello-world src/main.c)
+
+# List of libraries to link with the application.
+target_link_libraries(hello-world
+    sel4runtime sel4
+    muslc utils sel4tutorials
+    sel4muslcsys sel4platsupport sel4utils sel4debug)
+
+# Tell the build system that this application is the root task.
+include(rootserver)
+DeclareRootserver(hello-world)
+
+
+ +

main.c

+ +

The main C is a very typical C file. For a basic root server application, the only requirement is that +a main function is provided.

+ +
#include <stdio.h>
+int main(int argc, char *argv[]) {
+    printf("Hello, World!\n");
+
+    return 0;
+}
+
+ +

Making a change

+ +

Test making a change to main.c by adding a second printf to output "Second hello\n".

+ +
int main(int argc, char *argv[]) {
+    printf("Hello, World!\n");
+
+    printf("Second hello\n");
+    return 0;
+}
+
+ +

Once you have made your change, use Terminal B to rebuild the project.

+ +

Hint: Remember to exit the QEMU simulator before rerunning the project with ctrl-A,x

+ +
# In build directory
+ninja
+
+

Then run the simulator again:

+ +
# In build directory
+./simulate
+
+ +

On success, you should see the following:

+ +

+Second hello
+
+
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/hello-world.md b/Tutorials/hello-world.md deleted file mode 100644 index de97ab7fbde..00000000000 --- a/Tutorials/hello-world.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Hello, World! -tutorial: hello-world -layout: tutorial -nav_prev: get-the-tutorials.html -nav_next: capabilities.html -description: an introduction to seL4 projects and tutorials -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -{% include tutorial.md %} diff --git a/Tutorials/how-to-CAmkES.html b/Tutorials/how-to-CAmkES.html new file mode 100644 index 00000000000..49164c44def --- /dev/null +++ b/Tutorials/how-to-CAmkES.html @@ -0,0 +1,623 @@ + + + + + + + How-to guide for CAmkES | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

How-to guide for CAmkES

+ +

This guide provides links to CAmkES tutorial solutions as quick how-to reference guide.

+ +

A basic CAmkES application

+ + + +

Events in CAmkES

+ + + +

CAmkES Timer

+ + + +

CAmkES VM Linux

+ + + +

CAmkeES Cross VM Connectors

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/Tutorials/how-to-CAmkES.md b/Tutorials/how-to-CAmkES.md deleted file mode 100644 index 8825a7c48fb..00000000000 --- a/Tutorials/how-to-CAmkES.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC. ---- - -# How-to guide for CAmkES - -This guide provides links to CAmkES tutorial solutions as quick how-to reference guide. - -{% assign url = "hello-camkes-1.html?tut_expand" %} - -## [A basic CAmkES application]({{ url }}) - -- [Define an instance in the composition section of the ADL]({{ url }}#define-an-instance-in-the-composition-section-of-the-adl) -- [Add a connection]({{ url }}#add-a-connection) -- [Define an interface]({{ url }}#define-an-interface) -- [Implement an RPC function]({{ url }}#implement-an-rpc-function) -- [Invoke an RPC function]({{ url }}#invoke-an-rpc-function) - -{% assign url = "hello-camkes-2.html?tut_expand" %} - -## [Events in CAmkES]({{ url }}) - -- [Specify an events interface]({{ url }}#specify-an-events-interface) -- [Add connections]({{ url }}#add-connections) -- [Wait for data to become available]({{ url }}#wait-for-data-to-become-available) -- [Signal that data is available]({{ url }}#signal-that-data-is-available) -- [Register a callback handler]({{ url }}#register-a-callback-handler) -- [Specify dataport interfaces]({{ url }}#specify-dataport-interfaces) -- [Specify dataport connections]({{ url }}#specify-dataport-connections) -- [Copy strings to an untyped dataport]({{ url }}#copy-strings-to-an-untyped-dataport) -- [Read the reply data from a typed dataport]({{ url }}#read-the-reply-data-from-a-typed-dataport) -- [Send data using dataports]({{ url }}#send-data-using-dataports) -- [Read data from an untyped dataport]({{ url }}#read-data-from-an-untyped-dataport) -- [Put data into a typed dataport]({{ url }}#put-data-into-a-typed-dataport) -- [Read data from a typed dataport]({{ url }}#read-data-from-a-typed-dataport) -- [Set component priorities]({{ url }}#set-component-priorities) -- [Restrict access to dataports]({{ url }}#restrict-access-to-dataports) -- [Test the read and write permissions on the dataport]({{ url }}#test-the-read-and-write-permissions-on-the-dataport) - -{% assign url = "hello-camkes-timer.html?tut_expand" %} - -## [CAmkES Timer]({{ url }}) - -- [Instantiate a Timer and Timerbase]({{ url }}#instantiate-a-timer-and-timerbase) -- [Connect a timer driver component]({{ url }}#connect-a-timer-driver-component) -- [Configure a timer hardware component instance]({{ url }}#configure-a-timer-hardware-component-instance) -- [Call into a supplied driver to handle the interrupt]({{ url }}#call-into-a-supplied-driver-to-handle-the-interrupt) -- [Stop a timer]({{ url }}#stop-a-timer) -- [Acknowledge an interrupt]({{ url }}#acknowledge-an-interrupt) -- [Get a timer handler]({{ url }}#get-a-timer-handler) -- [Start a timer]({{ url }}#start-a-timer) -- [Implement an RPC interface]({{ url }}#implement-an-rpc-interface) -- [Set a timer interrupt]({{ url }}#set-a-timer-interrupt) -- [Instantiate a TimerDTB component]({{ url }}#instantiate-a-timerdtb-component) -- [Connect interfaces using the seL4DTBHardware connector]({{ url }}#connect-interfaces-using-the-sel4dtbhardware-connector) -- [Configure the TimerDTB component]({{ url }}#configure-the-timerdtb-component) -- [Handle the interrupt]({{ url }}#handle-the-interrupt) -- [Stop the timer]({{ url }}#stop-a-timer-1) - -{% assign url = "camkes-vm-linux.html?tut_expand" %} - -## [CAmkES VM Linux]({{ url }}) - -- [Add a program]({{ url }}#adding-a-program) -- [Add a kernel module]({{ url }}#adding-a-kernel-module) -- [Create a hypercall]({{ url }}#creating-a-hypercall) - -{% assign url = "camkes-vm-crossvm.html?tut_expand" %} - -## [CAmkeES Cross VM Connectors]({{ url }}) - -- [Add modules to the guest]({{ url }}#add-modules-to-the-guest) -- [Define interfaces in the VMM]({{ url }}#define-interfaces-in-the-vmm) -- [Define the component interface]({{ url }}#define-the-component-interface) -- [Instantiate the print server]({{ url }}#instantiate-the-print-server) -- [Implement the print server]({{ url }}#implement-the-print-server) -- [Implement the VMM side of the connection]({{ url }}#implement-the-vmm-side-of-the-connection) -- [Update the build system]({{ url }}#update-the-build-system) -- [Add interfaces to the Guest]({{ url }}#add-interfaces-to-the-guest) -- [Create a process]({{ url }}#create-a-process) diff --git a/Tutorials/how-to-libs.html b/Tutorials/how-to-libs.html new file mode 100644 index 00000000000..df00f27d219 --- /dev/null +++ b/Tutorials/how-to-libs.html @@ -0,0 +1,612 @@ + + + + + + + How-to guide for the seL4 C libraries | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+ + + + +
+
+
+ + diff --git a/Tutorials/how-to-libs.md b/Tutorials/how-to-libs.md deleted file mode 100644 index 4177df4e8e8..00000000000 --- a/Tutorials/how-to-libs.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC. ---- - -# How-to guide for the seL4 C libraries - -This guide provides links to tutorial solutions as quick references for the seL4 -C prototyping libraries. - -{% assign url = "libraries-1.html?tut_expand" %} - -## [Initialisation & threading]({{ url }}) - -- [Obtain BootInfo]({{ url }}#obtain-bootinfo) -- [Initialise simple]({{ url }}#initialise-simple) -- [Use simple to print BootInfo]({{ url }}#use-simple-to-print-bootinfo) -- [Initialise an allocator]({{ url }}#initialise-an-allocator) -- [Obtain a generic allocation interface (vka)]({{ url }}#obtain-a-generic-allocation-interface-vka) -- [Find the CSpace root cap]({{ url }}#find-the-cspace-root-cap) -- [Find the VSpace root cap]({{ url }}#find-the-vspace-root-cap) -- [Allocate a TCB Object]({{ url }}#allocate-a-tcb-object) -- [Configure the new TCB]({{ url }}#configure-the-new-tcb) -- [Name the new TCB]({{ url }}#name-the-new-tcb) -- [Set the instruction pointer]({{ url }}#set-the-instruction-pointer) -- [Set the stack pointer]({{ url }}#set-the-stack-pointer) -- [Write the registers]({{ url }}#write-the-registers) -- [Start the new thread]({{ url }}#start-the-new-thread) -- [Print]({{ url }}#print-something) - -{% assign url = "libraries-2.html?tut_expand" %} - -## [IPC]({{ url }}) - -- [Allocate an IPC buffer]({{ url }}#allocate-an-ipc-buffer) -- [Allocate a page table]({{ url }}#allocate-a-page-table) -- [Map a page table]({{ url }}#map-a-page-table) -- [Map a page]({{ url }}#map-a-page) -- [Allocate an endpoint]({{ url }}#allocate-an-endpoint) -- [Badge an endpoint]({{ url }}#badge-an-endpoint) -- [Set a message register]({{ url }}#message-registers) -- [Send and wait for a reply]({{ url }}#ipc) -- [Receive a reply]({{ url }}#receive-a-reply) -- [Receive an IPC]({{ url }}#receive-an-ipc) -- [Validate a message]({{ url }}#validate-the-message) -- [Write the message registers]({{ url }}#write-the-message-registers) -- [Reply to a message]({{ url }}#reply-to-a-message) - -{% assign url = "libraries-3.html?tut_expand" %} - -## [Processes & Elf loading]({{ url }}) - -- [Create a VSpace object]({{ url }}#virtual-memory-management) -- [Configure a process]({{ url }}#configure-a-process) -- [Get a CSpace path]({{ url }}#get-a-cspacepath) -- [Badge a capability]({{ url }}#badge-a-capability) -- [Spawn a process]({{ url }}#spawn-a-process) -- [Receive a message]({{ url }}#receive-a-message) -- [Send a reply]({{ url }}#send-a-reply) -- [Initiate communications by using seL4_Call]({{ url }}#client-call) - -{% assign url = "libraries-4.html?tut_expand" %} - -## [Timer]({{ url }}) - -- [Allocate a notification object]({{ url }}#allocate-a-notification-object) -- [Initialise a timer]({{ url }}#initialise-the-timer) -- [Use a timer]({{ url }}#use-the-timer) -- [Handle an interrupt]({{ url }}#handle-the-interrupt) -- [Destroy a timer]({{ url }}#destroy-the-timer) diff --git a/Tutorials/how-to-seL4.html b/Tutorials/how-to-seL4.html new file mode 100644 index 00000000000..e119271c0a1 --- /dev/null +++ b/Tutorials/how-to-seL4.html @@ -0,0 +1,635 @@ + + + + + + + How-to guide for seL4 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+ + + + +
+
+
+ + diff --git a/Tutorials/how-to-seL4.md b/Tutorials/how-to-seL4.md deleted file mode 100644 index a378d27772f..00000000000 --- a/Tutorials/how-to-seL4.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC. ---- - -# How-to guide for seL4 - -This guide provides links to the seL4 tutorial solutions as a quick references -for seL4 calls and methods. - -{% assign url = "capabilities.html?tut_expand" %} - -## [Capabilities]({{ url }}) - -- [Calculate the size of a CSpace]({{ url }}#how-big-is-your-cspace) -- [Copy a capability between CSlots]({{ url }}#copy-a-capability-between-cslots) -- [Delete a capability]({{ url }}#how-do-you-delete-capabilities) -- [Suspend a thread]({{ url }}#suspend-a-thread) - -{% assign url = "untyped.html?tut_expand" %} - -## [Untyped]({{ url }}) - -- [Create an untyped capability]({{ url }}#create-an-untyped-capability) -- [Create a TCB object]({{ url }}#create-a-tcb-object) -- [Create an endpoint object]({{ url }}#create-an-endpoint-object) -- [Create a notification object]({{ url }}#create-a-notification-object) -- [Delete an object]({{ url }}#delete-the-objects) - -{% assign url = "mapping.html?tut_expand" %} - -## [Mapping]({{ url }}) - -- [Map a page directory]({{ url }}#map-a-page-directory) -- [Map a page table]({{ url }}#map-a-page-table) -- [Remap a page]({{ url }}#remap-a-page) -- [Unmap a page]({{ url }}#unmapping-pages) - -{% assign url = "threads.html?tut_expand" %} - -## [Threads]({{ url }}) - -- [Configure a TCB]({{ url }}#configure-a-tcb) -- [Change the priority of a thread]({{ url }}#change-priority-via-sel4_tcb_setpriority) -- [Set initial register state]({{ url }}#set-initial-register-state) -- [Start the thread]({{ url }}#start-the-thread) -- [Set the arguments of a thread]({{ url }}#passing-arguments) -- [Resolve a fault]({{ url }}#resolving-a-fault) - -{% assign url = "ipc.html?tut_expand" %} - -## [IPC]({{ url }}) - -- [Use capability transfer to send the badged capability]({{ url }}#use-capability-transfer-to-send-the-badged-capability) -- [Get a message]({{ url }}#get-a-message) -- [Reply and wait]({{ url }}#reply-and-wait) -- [Save a reply and store reply capabilities]({{ url }}#save-a-reply-and-store-reply-capabilities) - -{% assign url = "notifications.html?tut_expand" %} - -## [Notifications]({{ url }}) - -- [Set up shared memory]({{ url }}#set-up-shared-memory) -- [Signalling]({{ url }}#signal-the-producers-to-go) -- [Differentiate signals]({{ url }}#differentiate-signals) - -{% assign url = "interrupts.html?tut_expand" %} - -## [Interrupts]({{ url }}) - -- [Invoke IRQ control]({{ url }}#invoke-irq-control) -- [Set NTFN]({{ url }}#set-ntfn) -- [Acknowledge an interrupt]({{ url }}#acknowledge-an-interrupt) - -{% assign url = "fault-handlers.html?tut_expand" %} - -### [Fault handling]({{ url }}) - -- [Set up an endpoint for thread fault IPC messages]({{ url }}#setting-up-the-endpoint-to-be-used-for-thread-fault-ipc-messages) -- [Receive an IPC message from the kernel]({{ url }}#receiving-the-ipc-message-from-the-kernel) -- [Get information about a thread fault]({{ url }}#finding-out-information-about-the-generated-thread-fault) -- [Handle a thread fault]({{ url }}#handling-a-thread-fault) -- [Resume a faulting thread]({{ url }}#resuming-a-faulting-thread) - -{% assign url = "mcs.html?tut_expand" %} - -## [MCS]({{ url }}) - -- [Set up a periodic thread]({{ url }}#periodic-threads) -- [Unbind a scheduling context]({{ url }}#unbinding-scheduling-contexts) -- [Experiment with sporadic tasks]({{ url }}#sporadic-threads) -- [Use passive servers]({{ url }}#passive-servers) -- [Configure fault endpoints]({{ url }}#configuring-a-fault-endpoint-on-the-mcs-kernel) diff --git a/Tutorials/index.html b/Tutorials/index.html new file mode 100644 index 00000000000..a68987d3cca --- /dev/null +++ b/Tutorials/index.html @@ -0,0 +1,622 @@ + + + + + + + Tutorial Overview | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Tutorial Overview

+ +

The seL4 docsite provides a set of tutorials that introduce seL4 and show how to +develop systems on seL4. They are split into the following categories.

+ +
    +
  • +

    The Microkit tutorial tutorial is an easy way to get started with seL4. +The seL4 Microkit is a software development kit (SDK) for building systems +with a statically described architecture on top of seL4. It provides simple, +high-performance abstractions that manage much of the complexity of the seL4 +API.

    +
    • +
  • +

    The seL4 tutorials are for people keen to learn about the +base mechanisms provided by the seL4 kernel. It explains the kernel API with +short exercises that show basic usage examples.

    +
    • +
  • +

    The CAmkES tutorial introduces the CAmkES component platform +on top of seL4. CAmkES provides abstractions for component on top of seL4 and +communication glue code between them. It is designed for building +high-assurance systems with a static software architecture. CAmkES is being +superseded by Microkit and we recommend starting with the Microkit tutorial +instead if you are starting a new project.

    +
    • +
  • +

    The Rust on seL4 tutorial introduces the basic Rust crates for seL4 and +shows how to get started writing root tasks and Microkit components in the +Rust programming language.

    +
    • +
  • +

    The C library tutorials provide walkthroughs and exercises for +using the libraries provided in seL4_libs. These libraries were developed +for rapidly prototyping systems on seL4. They are not meant for production +code, but for experimenting with the seL4 API.

    +
    • +
+ + + +

Note that most of these tutorials require C programming experience and some +understanding of operating systems and computer architecture. Suggested +resources for these topics include:

+ + + +

Further Resources

+ +

Additional learning resources that may be helpful:

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/Tutorials/index.md b/Tutorials/index.md deleted file mode 100644 index 701be93f397..00000000000 --- a/Tutorials/index.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -redirect_from: - - /projects/sel4-tutorials.html - - /projects/sel4-tutorials/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Tutorial Overview - -The seL4 docsite provides a set of tutorials that introduce seL4 and show how to -develop systems on seL4. They are split into the following categories. - -- The [Microkit tutorial] tutorial is an easy way to get started with seL4. - The seL4 Microkit is a software development kit (SDK) for building systems - with a statically described architecture on top of seL4. It provides simple, - high-performance abstractions that manage much of the complexity of the seL4 - API. - -- The [seL4 tutorials](setting-up.html) are for people keen to learn about the - base mechanisms provided by the seL4 kernel. It explains the kernel API with - short exercises that show basic usage examples. - -- The [CAmkES tutorial](hello-camkes-0.html) introduces the CAmkES component platform - on top of seL4. CAmkES provides abstractions for component on top of seL4 and - communication glue code between them. It is designed for building - high-assurance systems with a static software architecture. CAmkES is being - superseded by Microkit and we recommend starting with the [Microkit tutorial] - instead if you are starting a new project. - -- The [Rust on seL4 tutorial] introduces the basic Rust crates for seL4 and - shows how to get started writing root tasks and Microkit components in the - Rust programming language. - -- The [C library tutorials](libraries-1.html) provide walkthroughs and exercises for - using the libraries provided in `seL4_libs`. These libraries were developed - for rapidly prototyping systems on seL4. They are not meant for production - code, but for experimenting with the seL4 API. - -[Microkit tutorial]: {% link projects/microkit/tutorial/welcome.md %} -[Rust on seL4 tutorial]: ../projects/rust/tutorial/introduction.html - -## Recommended reading - -Note that most of these tutorials require C programming experience and some -understanding of operating systems and computer architecture. Suggested -resources for these topics include: - -- C programming language - - [C tutorial](https://www.cprogramming.com/tutorial/c-tutorial.html) -- Operating Systems: - - [Modern Operating Systems (book)](https://www.amazon.com/Modern-Operating-Systems-Andrew-Tanenbaum/dp/013359162X) - - [COMP3231 slides at UNSW](http://www.cse.unsw.edu.au/~cs3231) - -## Further Resources - -Additional learning resources that may be helpful: - -- The [seL4 manual](https://sel4.systems/Info/Docs/seL4-manual-latest.pdf) -- The [seL4 API reference](../projects/sel4/api-doc.html) -- The How-to pages for [seL4](how-to-seL4.html), [CAmkES](how-to-CAmkES.html), - and [C libraries](how-to-libs.html) provide links to tutorial solutions as - quick reference. -- The [seL4 white paper](https://sel4.systems/About/seL4-whitepaper.pdf) for a - high-level overview of what seL4 is and what it can do. -- [FAQs](https://sel4.systems/About/FAQ.html) -- [Debugging guide](../projects/sel4-tutorials/debugging-guide.html) -- [Help & Support](https://sel4.systems/support.html) diff --git a/Tutorials/interrupts.html b/Tutorials/interrupts.html new file mode 100644 index 00000000000..b35b41d3e66 --- /dev/null +++ b/Tutorials/interrupts.html @@ -0,0 +1,815 @@ + + + + + + + Interrupts | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Interrupts

+ +

This tutorial covers seL4 interrupts.

+ +

You will learn:

+ +
    +
  1. The purpose of the IRQControl capability.
    2. +
  2. How to obtain capabilities for specific interrupts.
    3. +
  3. How to handle interrupts and their relation with notification objects.
    4. +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Notifications tutorial
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut interrupts
+# building the tutorial exercise
+cd interrupts_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut interrupts
+# building the tutorial exercise
+cd interrupts_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

capDL Loader

+ +

This tutorial uses the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +
+ Get capDL +

The capDL loader parses +a static description of the system and the relevant ELF binaries. +It is primarily used in CAmkES projects +but we also use it in the tutorials to reduce redundant code. +The program that you construct will end up with its own CSpace and VSpace, which are separate +from the root task, meaning CSlots like seL4_CapInitThreadVSpace have no meaning +in applications loaded by the capDL loader.

+ +

More information about capDL projects can be found here.

+ +

For this tutorial clone the capDL repo. This can be added in a directory that is adjacent to the main tutorials directory.

+
+ +

Background

+ +

IRQControl

+ +

The root task is given a single capability from which capabilities to all irq numbers +in the system can be derived, seL4_CapIRQControl. This capability can be moved between CSpaces +and CSlots but cannot be duplicated. Revoking this capability results in all access to all +irq capabilities being removed.

+ +

IRQHandlers

+ +

IRQHandler capabilities give access to a single irq and are standard seL4 capabilities: they +can be moved and duplicated according to system policy. IRQHandlers are obtained by +invoking the IRQControl capability, with architecture specific parameters. Below is an +example of obtaining an IRQHandler.

+ +
// Get a capability for irq number 7 and place it in cslot 10 in a single-level cspace.
+error = seL4_IRQControl_Get(seL4_IRQControl, 7, cspace_root, 10, seL4_WordBits);
+
+ +

There are a variety of different invocations to obtain irq capabilities which are hardware +dependent, including:

+ + + +

Receiving interrupts

+ +

Interrupts are received by registering a capability to a notification object +with the IRQHandler capability for that irq, as follows:

+ +
seL4_IRQHandler_SetNotification(irq_handler, notification);
+
+ +

On success, this call will result in signals being delivered to the notification object when +an interrupt occurs. To handle multiple interrupts on the same notification object, you +can set different badges on the notification capabilities bound to each IRQHandler. + When an interrupt arrives, +the badge of the notification object bound to that IRQHandler is bitwise or-ed with the data +word in the notification object. +Recall the badging technique for differentiating signals from the + notification tutorial.

+ +

Interrupts can be polled for using seL4_Poll or waited for using seL4_Wait. Either system +call results in the data word of the notification object being delivered as the badge of the +message, and the data word cleared.

+ +

seL4_IRQHandler_Clear can be used to unbind +the notification from an IRQHandler.

+ +

Handling interrupts

+ +

Once an interrupt is received and processed by the software, you can unmask the interrupt +using seL4_IRQHandler_Ack on the IRQHandler. +seL4 will not deliver any further interrupts after an IRQ is raised until that IRQHandler +has been acked.

+ +

Exercises

+ +

In this tutorial you will set up interrupt handling for a provided timer driver +on the zynq7000 ARM platform. This timer driver can be located inside the +projects/sel4-tutorials/zynq_timer_driver folder from the root of the +projects directory, i.e. where the .repo folder can be found and where the +initial repo init command was executed. The tutorial has been set up with two +processes: timer.c, the timer driver and RPC server, and client.c, which +makes a single request.

+ +

On successful initialisation of the tutorial, you will see the following:

+ +
timer client: hey hey hey
+timer: got a message from 61 to sleep 2 seconds
+<<seL4(CPU 0) [decodeInvocation/530 T0xe8265600 "tcb_timer" @84e4]: Attempted to invoke a null cap #9.>>
+main@timer.c:78 [Cond failed: error]
+	Failed to ack irq
+
+ +

The timer driver we are using emits an interrupt in the TTC0_TIMER1_IRQ number.

+ +

Invoke IRQ control

+ +

Exercise Invoke irq_control, which contains the seL4_IRQControl capability, +the place the IRQHandler capability for TTC0_TIMER1_IRQ into the irq_handler CSlot.

+ +
    /* TODO invoke irq_control to put the interrupt for TTC0_TIMER1_IRQ in
+       cslot irq_handler (depth is seL4_WordBits) */
+
+
+ +
+ Quick solution + + 
    /* put the interrupt handle for TTC0_TIMER1_IRQ in the irq_handler cslot */
+    error = seL4_IRQControl_Get(irq_control, TTC0_TIMER1_IRQ, cnode, irq_handler, seL4_WordBits);
+    ZF_LOGF_IF(error, "Failed to get irq capability");
+
+ +
+ +

On success, you should see the following output, without the error message that occurred earlier, +as the irq_handle capability is now valid:

+ +
Undelivered IRQ: 42
+
+ +

This is a warning message from the kernel that an IRQ was recieved for irq number 42, but no +notification capability is set to sent a signal to.

+ +

Set NTFN

+ +

Exercise Now set the notification capability (ntfn) by invoking the irq handler.

+ +
     /* TODO set ntfn as the notification for irq_handler */
+
+
+ +
+ Quick solution + + 
    /* set ntfn as the notification for irq_handler */
+    error =  seL4_IRQHandler_SetNotification(irq_handler, ntfn);
+    ZF_LOGF_IF(error, "Failed to set notification");
+
+ +
+ +

Now the output will be:

+ +
Tick
+
+ +

Only one interrupt is delivered, as the interrupt has not been acknowledged. The timer driver is +programmed to emit an interrupt every millisecond, so we need to count 2000 interrupts +before replying to the client.

+ +

Acknowledge an interrupt

+ +

Exercise Acknowledge the interrupt after handling it in the timer driver.

+ +
        /* TODO ack the interrupt */
+
+
+ +
+ Quick solution + + 
        /* ack the interrupt */
+        error = seL4_IRQHandler_Ack(irq_handler);
+        ZF_LOGF_IF(error, "Failed to ack irq");
+
+ +
+ +

Now the timer interrupts continue to come in, and the reply is delivered to the client.

+ +
timer client wakes up
+
+ +

That’s it for this tutorial.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/interrupts.md b/Tutorials/interrupts.md deleted file mode 100644 index ad92988c458..00000000000 --- a/Tutorials/interrupts.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Interrupts -tutorial: interrupts -layout: tutorial -description: receiving and handling interrupts -nav_prev: notifications.html -nav_next: fault-handlers.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/ipc.html b/Tutorials/ipc.html new file mode 100644 index 00000000000..511ec197202 --- /dev/null +++ b/Tutorials/ipc.html @@ -0,0 +1,972 @@ + + + + + + + IPC | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

IPC

+ +

This tutorial is about interprocess communication (IPC), the microkernel mechanism for synchronous transmission of small amounts of data.

+ +

You will learn:

+
    +
  1. How to use IPC to send data and capabilities between processes.
    2. +
  2. The jargon cap transfer.
    3. +
  3. How to differentiate requests via badged capabilities.
    4. +
  4. Design protocols that use the IPC fastpath.
    5. +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Capabilities tutorial
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut ipc
+# building the tutorial exercise
+cd ipc_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut ipc
+# building the tutorial exercise
+cd ipc_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

capDL Loader

+ +

This tutorial uses the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +
+ Get capDL +

The capDL loader parses +a static description of the system and the relevant ELF binaries. +It is primarily used in CAmkES projects +but we also use it in the tutorials to reduce redundant code. +The program that you construct will end up with its own CSpace and VSpace, which are separate +from the root task, meaning CSlots like seL4_CapInitThreadVSpace have no meaning +in applications loaded by the capDL loader.

+ +

More information about capDL projects can be found here.

+ +

For this tutorial clone the capDL repo. This can be added in a directory that is adjacent to the main tutorials directory.

+
+ +

Background

+ +

Interprocess communication (IPC) is the microkernel mechanism for synchronous transmission of small amounts of data +and capabilities between processes. In seL4, IPC is facilitated by small kernel objects known as endpoints, which +act as general communication ports. Invocations on endpoint objects are used to send and receive IPC messages.

+ +

Endpoints consist of a queue of threads waiting to send, or waiting to receive messages. To understand +this, consider an example where n threads are waiting for a message on an endpoint. If n threads +send messages on the endpoint, all n waiting threads will receive the message and wake up. If an n+1th +sender sends a message, that sender is now queued.

+ +

System calls

+ +

Threads can send messages on endpoints with the system call seL4_Send, which blocks until the message has been +consumed by another thread. seL4_NBSend can also be used, which performs a polling send: the send is only +successful if a receiver is already blocked waiting for a message, and otherwise fails. To avoid a +back channel, seL4_NBSend does not return a result indicating if the message was sent or not.

+ +

seL4_Recv can be used to receive messages, and seL4_NBRecv can be used to poll for messages.

+ +

seL4_Call is a system call that essentially combines an seL4_Send and an seL4_Recv with one +major difference: in the receive phase, thread which uses this function is blocked on a one-time capability termed a +reply capability, and not the endpoint itself. In a client-server scenario, where clients use +seL4_Call to make requests, the server can explicitly reply to the correct client.

+ +

The reply capability is stored internally in the thread control block (TCB) of the receiver. The system +call seL4_Reply invokes this capability, which sends an IPC to the client and wakes it up. seL4_ReplyRecv +does the same, except it sends the reply and blocks on the provided endpoint in a combined system call.

+ +

Since TCBs have a single space to store a reply capability, if servers need to service multiple +requests (e.g saving requests to reply at a later time, after hardware operations have been completed), +seL4_CNode_SaveCaller can be used to save +the reply capability to an empty slot in the receivers CSpace.

+ +

IPC Buffer

+ +

Each thread has a buffer (referred to as the IPC buffer), which contains the payload of the IPC message, +consisting of data and capabilities. Senders specify a message length and the kernel copies this (bounded) +amount between the sender and receiver IPC buffer.

+ +

Data transfer

+ +

The IPC buffer contains a bounded area of message registers (MR) used to transmit data on IPC. Each +register is the machine word size, and the maximum message size is available in the +seL4_MsgMaxLength constant provided by libsel4.

+ +

Messages can be loaded into the IPC buffer using seL4_SetMR and extracted using seL4_GetMR. +Small messages are sent in registers and do not require a copy operation. The amount of words +that fit in registers is available in the seL4_FastMessageRegisters constant.

+ +

The amount of data being transferred, in terms of the number of message registers used, must be +set in as the length field in the seL4_MessageInfo_t data structure.

+ +

Cap transfer

+ +

Along with data, IPC can be used to send capabilities between processes per message. This is referred to as + cap transfer. The number of capabilities being transferred is encoded in the seL4_MessageInfo_t +structure as extraCaps. Below is an example for sending a capability via IPC:

+ +
   seL4_MessageInfo info = seL4_MessageInfo_new(0, 0, 1, 0);
+   seL4_SetCap(0, free_slot);
+   seL4_Call(endpoint, info);
+
+ +

To receive a capability, the receiver must specify a cspace address to place the capability in. This is +shown in the code example below:

+ +
    seL4_SetCapReceivePath(cnode, badged_endpoint, seL4_WordBits);
+    seL4_Recv(endpoint, &sender);
+
+ +

The access rights of the received capability are the same as by the rights that the receiver has to the endpoint. +Note that while senders can send multiple capabilities, receivers can only receive one at a time.

+ +

Capability unwrapping

+ +

seL4 can also unwrap capabilities on IPC. +If the n-th capability in the message refers to the endpoint through which the message +is sent, the capability is unwrapped: its badge is placed into the n-th position of the +receiver’s IPC buffer (in the field caps_or_badges), and the kernel sets the n-th bit +(counting from the least significant) in the capsUnwrapped field of seL4_MessageInfo_t.

+ +

Message Info

+ +

The seL4_MessageInfo_t data structure is used to encode the description of an IPC message into a single word. +It is used to describe a message to be sent to seL4, and for seL4 to describe the message that was +sent to the receiver. +It contains the following fields:

+ +
    +
  • length the amount of message registers (data) in the message (seL4_MsgMaxLength maximum),
    • +
  • extraCaps the number of capabilities in the message (seL4_MsgMaxExtraCaps)
    • +
  • capsUnwrapped marks any capabilities unwrapped by the kernel.
    • +
  • label data that is transferred unmodified by the kernel from sender to receiver,
    • +
+ +

Badges

+ +

Along with the message the kernel additionally delivers the badge of the endpoint capability +that the sender invoked to send the message. Endpoints can be badged using +seL4_CNode_Mint or + seL4_CNode_Mutate. Once an endpoint is badged, +the badge of the endpoint is transferred to any receiver that receives messages on that endpoint. +The code example below demonstrates this:

+ +
seL4_Word badge;
+seL4_Recv(endpoint, &badge);
+// once a message is received, the badge value is set by seL4 to the
+// badge of capability used by the sender to send the message
+
+ +

Fastpath

+ +

Fast IPC is essential to microkernel-based systems, as services are often separated from each other +for isolation, with IPC one of the core mechanisms for communication between clients and services. +Consequently, IPC has a fastpath – a heavily optimised path in the kernel – which allows these operations +to be very fast. In order to use the fastpath, an IPC must meet the following conditions:

+ +
    +
  • seL4_Call or seL4_ReplyRecv must be used.
    • +
  • The data in the message must fit into the seL4_FastMessageRegisters registers.
    • +
  • The processes must have valid address spaces.
    • +
  • No caps should be transferred.
    • +
  • No other threads in the scheduler of higher priority than the thread unblocked by the IPC can be running.
    • +
+ +

Exercises

+ +

This tutorial has several processes set up by the capDL loader, two clients and a server. All processes have +access to a single endpoint capability, which provides access to the same endpoint object.

+ +

In this tutorial, you will construct a server which echos the contents of messages sent by clients. You +will also alter the ordering of replies from the clients to get the right message.

+ +

When you run the tutorial, the output should be something like this:

+ +
Client 2: waiting for badged endpoint
+Badged 2
+Assertion failed: seL4_MessageInfo_get_extraCaps(info) == 1 (../ipcCkQ6Ub/client_2.c: main: 22)
+Client 1: waiting for badged endpoint
+Badged 1
+Assertion failed: seL4_MessageInfo_get_extraCaps(info) == 1 (../ipcCkQ6Ub/client_1.c: main: 22)
+
+ +

On initialisation, both clients use the following protocol: they wait on the provided endpoint for +a badged endpoint to be sent to them via cap transfer. All following messages sent by the client +uses the badged endpoint, such that the server can identify the client. However, the server does not +currently send the badged capability! We have provided code to badge the endpoint capability, and +reply to the client.

+ +

Use capability transfer to send the badged capability

+ +

Exercise Your task is to set up the cap transfer such that the client successfully +receives the badged endpoint.

+ +
             /* No badge! give this sender a badged copy of the endpoint */
+             seL4_Word badge = seL4_GetMR(0);
+             seL4_Error error = seL4_CNode_Mint(cnode, free_slot, seL4_WordBits,
+                                                cnode, endpoint, seL4_WordBits,
+                                                seL4_AllRights, badge);
+             printf("Badged %lu\n", badge);
+
+             // TODO use cap transfer to send the badged cap in the reply
+
+             /* reply to the sender and wait for the next message */
+             seL4_Reply(info);
+
+             /* now delete the transferred cap */
+             error = seL4_CNode_Delete(cnode, free_slot, seL4_WordBits);
+             assert(error == seL4_NoError);
+
+             /* wait for the next message */
+             info = seL4_Recv(endpoint, &sender);
+
+ +
+ Quick solution + + 
             /* No badge! give this sender a badged copy of the endpoint */
+             seL4_Word badge = seL4_GetMR(0);
+             seL4_Error error = seL4_CNode_Mint(cnode, free_slot, seL4_WordBits,
+                                                cnode, endpoint, seL4_WordBits,
+                                                seL4_AllRights, badge);
+             printf("Badged %lu\n", badge);
+
+             // use cap transfer to send the badged cap in the reply
+             seL4_SetCap(0, free_slot);
+             info = seL4_MessageInfo_new(0, 0, 1, 0);
+
+             /* reply to the sender and wait for the next message */
+             seL4_Reply(info);
+
+             /* now delete the transferred cap */
+             error = seL4_CNode_Delete(cnode, free_slot, seL4_WordBits);
+             assert(error == seL4_NoError);
+
+             /* wait for the next message */
+             info = seL4_Recv(endpoint, &sender);
+
+ +
+ +

Now the output should look something like:

+
Booting all finished, dropped to user space
+Client 2: waiting for badged endpoint
+Badged 2
+Client 1: waiting for badged endpoint
+Badged 1
+Client 2: received badged endpoint
+Client 1: received badged endpoint
+
+ +

Depending on timing, the messages may be different, the result is the same: the system hangs. +This is because one of the clients has hit the else case, where the badge is set, and the server +does not respond, or wait for new messages from this point.

+ +

Get a message

+ +

Exercise Your next task is to implement the echo part of the server.

+ +
             // TODO use printf to print out the message sent by the client
+             // followed by a new line
+
+ +
+ Quick solution + + 
             for (int i = 0; i < seL4_MessageInfo_get_length(info); i++) {
+                 printf("%c", (char) seL4_GetMR(i));
+             }
+             printf("\n");
+
+
+ +

At this point, you should see a single word output to the console in a loop.

+
the
+the
+the
+
+ +

This is because the server does not reply to the client, and continues to spin in a loop + repeating the last message.

+ +

Reply and wait

+ +

Exercise Update the code to reply to the clients after printing the message.

+ +
             // TODO reply to the client and wait for the next message
+
+
+ +
+ Quick solution + + 
             info = seL4_ReplyRecv(endpoint, info, &sender);
+
+
+ +

Now the output should be something like this:

+ +
Client 2: received badged endpoint
+the
+brown
+jumps
+the
+dog
+Client 1: received badged endpoint
+quick
+fox
+over
+lazy
+
+ +

Save a reply and store reply capabilities

+ +

Exercise Currently each client is scheduled for its full timeslice until it is preempted. Alter +your server to only print one message from each client, alternating. You will need to use +seL4_CNode_SaveCaller to save the reply +capability for each sender. You can use free_slot to store the reply capabilities.

+ +
+ Quick solution + + 
              error = seL4_CNode_SaveCaller(cnode, free_slot, seL4_WordBits);
+              assert(error == 0);
+              info = seL4_Recv(endpoint, &sender);
+              for (int i = 0; i < seL4_MessageInfo_get_length(info); i++) {
+                 printf("%c", (char) seL4_GetMR(i));
+              }
+              printf("\n");
+              seL4_Send(free_slot, seL4_MessageInfo_new(0, 0, 0, 0));
+
+ +
+ +

Depending on your approach, successful output should look something like this:

+
Client 2: received badged endpoint
+the
+Client 1: received badged endpoint
+quick
+fox
+brown
+jumps
+over
+lazy
+the
+dog
+
+ +

Further exercises

+ +

That’s all for the detailed content of this tutorial. Below we list other ideas for exercises you can try, +to become more familiar with IPC.

+ +
    +
  • Try using seL4_Send and seL4_Recv.
    • +
  • Try the non-blocking variants, seL4_NBSend and seL4_NBRecv.
    • +
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/ipc.md b/Tutorials/ipc.md deleted file mode 100644 index dec8ab30b2f..00000000000 --- a/Tutorials/ipc.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: IPC -tutorial: ipc -layout: tutorial -description: overview of interprocess communication (IPC) -nav_prev: threads.html -nav_next: notifications.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/libraries-1.html b/Tutorials/libraries-1.html new file mode 100644 index 00000000000..727ad48399f --- /dev/null +++ b/Tutorials/libraries-1.html @@ -0,0 +1,1196 @@ + + + + + + + Libraries initialisation & threading | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

seL4 Libraries: Initialisation & Threading

+ +

This tutorial provides code examples and exercises for using the libraries +found in seL4_libs to bootstrap a system and start a thread.

+ +

The tutorial is useful in that +it addresses conceptual problems for two different types of developers:

+ +
    +
  • Experienced kernel developers whose minds are pre-programmed to + think in terms of “One address space equals one process”, and + begins to introduce the seL4 CSpace vs VSpace model.
    • +
  • New kernel developers, for whom the tutorial will provide prompts on what to read.
    • +
+ +

Don’t gloss over the globals declared before main() – they’re declared +for your benefit so you can grasp some of the basic data structures.

+ +

Outcomes:

+ +
    +
  • Understand the kernel’s startup procedure.
    • +
  • Understand that the kernel centres around certain objects and + capabilities to those objects.
    • +
  • Understand that libraries exist to automate the very + fine-grained nature of the seL4 API, and get a rough idea of + some of those libraries.
    • +
  • Learn how the kernel hands over control to userspace.
    • +
  • Get a feel for how the seL4 API enables developers to manipulate + the objects referred to by the capabilities they encounter.
    • +
  • Understand the how to spawn new threads in seL4, and the basic + idea that a thread has a TCB, VSpace and CSpace, and that you + must fill these out.
    • +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Hello world tutorial
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut libraries-1
+# building the tutorial exercise
+cd libraries-1_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut libraries-1
+# building the tutorial exercise
+cd libraries-1_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

Exercises

+ +

When you first run the tutorial, you should see the following output:

+ +
Booting all finished, dropped to user space
+main@main.c:89 [Cond failed: info == NULL]
+Failed to get bootinfo.
+
+ +

Obtain BootInfo

+ +

After bootstrapping the system, the seL4 kernel hands over control to the root task. + to an init thread. +This thread receives a structure from the kernel that describes all the +resources available on the machine. This structure is called the +BootInfo structure. It includes information on all IRQs, memory, and +IO-Ports (x86). This structure also tells the init thread where certain +important capability references are. This step is teaching you how to +obtain that structure.

+ +

seL4_BootInfo* platsupport_get_bootinfo(void) is a function that returns the BootInfo structure. +It also sets up the IPC buffer so that it can perform some syscalls such as seL4_DebugNameThread used by name_thread.

+ + + +

+    /* TASK 1: get boot info */
+    /* hint: platsupport_get_bootinfo()
+     * seL4_BootInfo* platsupport_get_bootinfo(void);
+     * @return Pointer to the bootinfo, NULL on failure
+     */
+
+ +
+ Quick solution + + 
    info = platsupport_get_bootinfo();
+
+ +
+ +

On success, you should see the following:

+ +
libraries-1: main@main.c:124 [Cond failed: allocman == NULL]
+    Failed to initialize alloc manager.
+    Memory pool sufficiently sized?
+    Memory pool pointer valid?
+
+ +

Initialise simple

+ +

libsel4simple provides an abstraction for the boot environment of a thread. +You need to initialise it with some default state before using it.

+ + + +

+   /* TASK 2: initialise simple object */
+   /* hint: simple_default_init_bootinfo()
+    * void simple_default_init_bootinfo(simple_t *simple, seL4_BootInfo *bi);
+    * @param simple Structure for the simple interface object. This gets initialised.
+    * @param bi Pointer to the bootinfo describing what resources are available
+    */
+
+ +
+ Quick solution + + 
    simple_default_init_bootinfo(&simple, info);
+
+ +
+

On successful completion of this task, the output should not change.

+ +

Use simple to print BootInfo

+ +

Use a simple function to print out the contents of the seL4_BootInfo function.

+ +

+    /* TASK 3: print out bootinfo and other info about simple */
+    /* hint: simple_print()
+     * void simple_print(simple_t *simple);
+     * @param simple Pointer to simple interface.
+     */
+
+
+ +
+ Quick solution + + 
    simple_print(&simple);
+
+ +
+ + + +

The error message should remain, but your output should now also contain something like:

+ +
Node 0 of 1
+IOPT levels:     4294967295
+IPC buffer:      0x52c000
+Empty slots:     [406 --> 4096)
+sharedFrames:    [0 --> 0)
+userImageFrames: [16 --> 316)
+userImagePaging: [12 --> 15)
+untypeds:        [316 --> 406)
+Initial thread domain: 0
+Initial thread cnode size:
+libraries-1: main@main.c:126 [Cond failed: allocman == NULL]
+
+ +

Initialise an allocator

+ +

In seL4, memory management is delegated in large part to userspace, and +each thread manages its own page faults with a custom pager. Without +the use of the allocman library and the VKA library, you would have to +manually allocate a frame, then map the frame into a page-table, before +you could use new memory in your address space. In this tutorial you +don’t go through that procedure, but you’ll encounter it later. For now, +use the allocman and VKA allocation system. The allocman library +requires some initial memory to bootstrap its metadata. Complete this +step.

+ + + +

+    /* TASK 4: create an allocator */
+    /* hint: bootstrap_use_current_simple()
+     * allocman_t *bootstrap_use_current_simple(simple_t *simple, uint32_t pool_size, char *pool);
+     * @param simple Pointer to simple interface.
+     * @param pool_size Size of the initial memory pool.
+     * @param pool Initial memory pool.
+     * @return returns NULL on error
+     */
+
+ +
+ Quick solution + + 
    allocman = bootstrap_use_current_simple(&simple, ALLOCATOR_STATIC_POOL_SIZE, allocator_mem_pool);
+
+ +
+ +

The output should now be as follows:

+ +
<<seL4(CPU 0) [decodeInvocation/530 T0xffffff801ffb5400 "libraries-1" @401303]: Attempted to invoke a null cap #0.>>
+libraries-1: main@main.c:199 [Err seL4_InvalidCapability]:
+    Failed to set the priority for the new TCB object.
+
+ +

Obtain a generic allocation interface (vka)

+ +

libsel4vka is an seL4 type-aware object allocator that will allocate new +kernel objects for you. The term “allocate new kernel objects” in seL4 +is a more detailed process of “retyping” previously un-typed memory. +seL4 considers all memory that hasn’t been explicitly earmarked for a +purpose to be “untyped”, and in order to repurpose any memory into a +useful object, you must give it an seL4-specific type. This is retyping, +and the VKA library simplifies this for you, among other things.

+ + + +

+    /* TASK 5: create a vka (interface for interacting with the underlying allocator) */
+    /* hint: allocman_make_vka()
+     * void allocman_make_vka(vka_t *vka, allocman_t *alloc);
+     * @param vka Structure for the vka interface object.  This gets initialised.
+     * @param alloc allocator to be used with this vka
+     */
+
+ +
+ Quick solution + + 
    allocman_make_vka(&vka, allocman);
+
+ +
+ +

On successful completion this task, the output should not change.

+ +

Find the CSpace root cap

+ +

+    /* TASK 6: get our cspace root cnode */
+    /* hint: simple_get_cnode()
+     * seL4_CPtr simple_get_cnode(simple_t *simple);
+     * @param simple Pointer to simple interface.
+     * @return The cnode backing the simple interface. no failure.
+     */
+    seL4_CPtr cspace_cap;
+
+ +
+ Quick solution + + 
    cspace_cap = simple_get_cnode(&simple);
+
+ +
+ +

This is where the differences between seL4 and contemporary kernels +begin to start playing out. Every kernel-object that you “retype” will +be handed to you using a capability reference. The seL4 kernel keeps +multiple trees of these capabilities. Each separate tree of capabilities +is called a “CSpace”. Each thread can have its own CSpace, or a CSpace +can be shared among multiple threads. The delineations between +“Processes” aren’t well-defined, since seL4 doesn’t have any real +concept of “processes”. It deals with threads. Sharing and isolation is +based on CSpaces (shared vs not-shared) and VSpaces (shared vs +not-shared). The “process” idea goes as far as perhaps the fact that at +the hardware level, threads sharing the same VSpace are in a traditional +sense, siblings, but logically in seL4, there is no concept of +“Processes” really.

+ +

So you’re being made to grab a reference to your thread’s CSpace’s root +“CNode”. A CNode is one of the many blocks of capabilities that make up +a CSpace.

+ + +

On successful completion this task, the output should not change.

+ +

Find the VSpace root cap

+ +

+    /* TASK 7: get our vspace root page diretory */
+    /* hint: simple_get_pd()
+     * seL4_CPtr simple_get_pd(simple_t *simple);
+     * @param simple Pointer to simple interface.
+     * @return The vspace (PD) backing the simple interface. no failure.
+     */
+    seL4_CPtr pd_cap;
+
+
+ +
+ Quick solution + + 
    pd_cap = simple_get_pd(&simple);
+
+ +
+ +

Just as in the previous step, you were made to grab a reference to the +root of your thread’s CSpace, now you’re being made to grab a reference +to the root of your thread’s VSpace.

+ + +

On successful completion this task, the output should not change.

+ +

Allocate a TCB Object

+ +

+    /* TASK 8: create a new TCB */
+    /* hint: vka_alloc_tcb()
+     * int vka_alloc_tcb(vka_t *vka, vka_object_t *result);
+     * @param vka Pointer to vka interface.
+     * @param result Structure for the TCB object.  This gets initialised.
+     * @return 0 on success
+     */
+    vka_object_t tcb_object = {0};
+
+ +
+ Quick solution + + 
    error = vka_alloc_tcb(&vka, &tcb_object);
+
+ +
+ +

In order to manage the threads that are created in seL4, the seL4 kernel +keeps track of TCB (Thread Control Block) objects. Each of these +represents a schedulable executable resource. Unlike other contemporary +kernels, seL4 doesn’t allocate a stack, virtual-address space +(VSpace) and other metadata on your behalf. This step creates a TCB, +which is a very bare-bones, primitive resource, which requires you to +still manually fill it out.

+ + + +

After completing this task, the errors should disappear, and you should see the following +output:

+ +
main: hello world
+
+ +

Configure the new TCB

+ +

+   /* TASK 9: initialise the new TCB */
+    /* hint 1: seL4_TCB_Configure()
+     * int seL4_TCB_Configure(seL4_TCB _service, seL4_Word fault_ep, seL4_CNode cspace_root, seL4_Word cspace_root_data, seL4_CNode vspace_root, seL4_Word vspace_root_data, seL4_Word buffer, seL4_CPtr bufferFrame)
+     * @param service Capability to the TCB which is being operated on.
+     * @param fault_ep Endpoint which receives IPCs when this thread faults (must be in TCB's cspace).
+     * @param cspace_root The new CSpace root.
+     * @param cspace_root_data Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect.
+     * @param vspace_root The new VSpace root.
+     * @param vspace_root_data Has no effect on IA-32 or ARM processors.
+     * @param buffer Address of the thread's IPC buffer. Must be 512-byte aligned. The IPC buffer may not cross a page boundary.
+     * @param bufferFrame Capability to a page containing the thread?s IPC buffer.
+     * @return 0 on success.
+     * Note: this function is generated during build.  It is generated from the following definition:
+     *
+     * hint 2: use seL4_CapNull for the fault endpoint
+     * hint 3: use seL4_NilData for cspace and vspace data
+     * hint 4: we don't need an IPC buffer frame or address yet
+     */
+
+ +
+ Quick solution + + 
    error = seL4_TCB_Configure(tcb_object.cptr, seL4_CapNull,  cspace_cap, seL4_NilData, pd_cap, seL4_NilData, 0, 0);
+
+ +
+ +

You must create a new VSpace for your new thread if you need it to +execute in its own isolated address space, and tell the kernel which +VSpace you plan for the new thread to execute in. This opens up the +option for threads to share VSpaces. In similar fashion, you must also +tell the kernel which CSpace your new thread will use – whether it will +share a currently existing one, or whether you’ve created a new one for +it. That’s what you’re doing now.

+ +

In this particular example, you’re allowing the new thread to share your +main thread’s CSpace and VSpace.

+ +

In addition, a thread needs to have a priority set on it in order for it to run. +seL4_TCB_SetPriority(tcb_object.cptr, seL4_CapInitThreadTCB, seL4_MaxPrio); +will give your new thread the same priority as the current thread, allowing it +to be run the next time the seL4 scheduler is invoked. The seL4 scheduler is invoked +everytime there is a kernel timer tick.

+ + + +

On successful completion this task, the output should not change.

+ +

Name the new TCB

+ +

+    /* TASK 10: give the new thread a name */
+    /* hint: we've done thread naming before */
+
+ +
+ Quick solution + + 
    NAME_THREAD(tcb_object.cptr, "libraries-1: thread_2");
+
+ +
+ +

This is a convenience function – sets a name string for the TCB object.

+ +

On successful completion this task, the output should not change.

+ +

Set the instruction pointer

+ +

+    /*
+     * set start up registers for the new thread:
+     */
+    UNUSED seL4_UserContext regs = {0};
+
+    /* TASK 11: set instruction pointer where the thread shoud start running */
+    /* hint 1: sel4utils_set_instruction_pointer()
+     * void sel4utils_set_instruction_pointer(seL4_UserContext *regs, seL4_Word value);
+     * @param regs Data structure in which to set the instruction pointer value
+     * @param value New instruction pointer value
+     *
+     * hint 2: we want the new thread to run the function "thread_2"
+     */
+
+ +
+ Quick solution + + 
    sel4utils_set_instruction_pointer(&regs, (seL4_Word)thread_2);
+
+ +
+ +

Pay attention to the line that precedes this particular task – the line +that zeroes out a new “seL4_UserContext” object. As we previously +explained, seL4 requires you to fill out the Thread Control Block +manually. That includes the new thread’s initial register contents. You +can set the value of the stack pointer, the instruction pointer, and if +you want to get a little creative, you can pass some initial data to +your new thread through its registers.

+ + + +

On successful completion this task, the output should not change.

+ +

Set the stack pointer

+ +

+    /* TASK 12: set stack pointer for the new thread */
+    /* hint 1: sel4utils_set_stack_pointer()
+     * void sel4utils_set_stack_pointer(seL4_UserContext *regs, seL4_Word value);
+     * @param regs  Data structure in which to set the stack pointer value
+     * @param value New stack pointer value
+     *
+     * hint 2: remember the stack grows down!
+     */
+
+ +
+ Quick solution + + 
    sel4utils_set_stack_pointer(&regs, thread_2_stack_top);
+
+ +
+ +

This TASK is just some pointer arithmetic. The cautionary note that the +stack grows down is meant to make you think about the arithmetic. +Processor stacks push new values toward decreasing addresses, so give it +some thought.

+ + + +

On successful completion this task, the output should not change.

+ +

Write the registers

+ +

+    /* TASK 13: actually write the TCB registers.  We write 2 registers:
+     * instruction pointer is first, stack pointer is second. */
+    /* hint: seL4_TCB_WriteRegisters()
+     * int seL4_TCB_WriteRegisters(seL4_TCB service, seL4_Bool resume_target, seL4_Uint8 arch_flags, seL4_Word count, seL4_UserContext *regs)
+     * @param service Capability to the TCB which is being operated on.
+     * @param resume_target The invocation should also resume the destination thread.
+     * @param arch_flags Architecture dependent flags. These have no meaning on either IA-32 or ARM.
+     * @param count The number of registers to be set.
+     * @param regs Data structure containing the new register values.
+     * @return 0 on success
+     */
+
+ +
+ Quick solution + + 
    error = seL4_TCB_WriteRegisters(tcb_object.cptr, 0, 0, 2, &regs);
+
+ +
+ +

As explained above, we’ve been filling out our new thread’s TCB for the +last few operations, so now we’re writing the values we’ve chosen, to +the TCB object in the kernel.

+ + + +

On successful completion this task, the output should not change.

+ +

Start the new thread

+ +

+    /* TASK 14: start the new thread running */
+    /* hint: seL4_TCB_Resume()
+     * int seL4_TCB_Resume(seL4_TCB service)
+     * @param service Capability to the TCB which is being operated on.
+     * @return 0 on success
+     */
+
+ +
+ Quick solution + + 
    error = seL4_TCB_Resume(tcb_object.cptr);
+
+ +
+ +

Finally, we tell the kernel that our new thread is runnable. From here, +the kernel itself will choose when to run the thread based on the +priority we gave it, and according to the kernel’s configured scheduling +policy.

+ + + +

On successful completion this task, the output should not change.

+ + + +

+    /* TASK 15: print something */
+    /* hint: printf() */
+
+ +
+ Quick solution + + 
    printf("thread_2: hallo wereld\n");
+
+ +
+ +

For the sake of confirmation that our new thread was executed by the +kernel successfully, we cause it to print something to the screen.

+ +

On success, you should see output from your new thread.

+ + + + + +

That’s it for this tutorial.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/libraries-1.md b/Tutorials/libraries-1.md deleted file mode 100644 index 30535ade526..00000000000 --- a/Tutorials/libraries-1.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Libraries initialisation & threading -tutorial: libraries-1 -layout: tutorial -description: system initialisation & threading with seL4_libs. -nav_next: libraries-2.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/libraries-2.html b/Tutorials/libraries-2.html new file mode 100644 index 00000000000..37a11b72ff9 --- /dev/null +++ b/Tutorials/libraries-2.html @@ -0,0 +1,1343 @@ + + + + + + + Libraries IPC | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

seL4 Libraries: IPC

+ +

The tutorial is designed to +teach the basics of seL4 IPC using Endpoint objects, and userspace +paging management. You’ll be led through the process of creating a new +thread (retyping an untyped object into a TCB object), and also made to +manually do your own memory management to allocate some virtual memory +for use as the shared memory buffer between your two threads.

+ +

Don’t gloss over the globals declared before main() – they’re declared +for your benefit so you can grasp some of the basic data structures.

+ +

You’ll observe that the things you’ve already covered in the second +tutorial are filled out and you don’t have to repeat them: in much the +same way, we won’t be repeating conceptual explanations on this page, if +they were covered by a previous tutorial in the series.

+ +

Learning outcomes:

+ +
    +
  • Repeat the spawning of a thread. “'’If it’s nice, do it twice’’” + – Caribbean folk-saying. Once again, the new thread will be + sharing its creator’s VSpace and CSpace.
    • +
  • Introduction to the idea of badges, and minting badged copies of + an Endpoint capability. NB: you don’t mint a new copy of the + Endpoint object, but a copy of the capability that + references it.
    • +
  • Basic IPC: sending and receiving: how to make two + threads communicate.
    • +
  • IPC Message format, and Message Registers. seL4 binds some of + the first Message Registers to hardware registers, and the rest + are transferred in the IPC buffer.
    • +
  • Understand that each thread has only one IPC buffer, which is + pointed to by its TCB. It’s possible to make a thread wait on + both an Endpoint and a Notification using “Bound Notifications”.
    • +
  • Understand CSpace pointers, which are really just integers with + multiple indexes concatenated into one. Understanding them well + however, is important to understanding how capabilities work.
    • +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Libraries: initialisation & threading
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut libraries-2
+# building the tutorial exercise
+cd libraries-2_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut libraries-2
+# building the tutorial exercise
+cd libraries-2_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

Exercises

+ +

When you first run this tutorial, you will see a fault as follows:

+ +
Booting all finished, dropped to user space
+Caught cap fault in send phase at address (nil)
+while trying to handle:
+vm fault on data at address 0x70003c8 with status 0x6
+in thread 0xffffff801ffb5400 "rootserver" at address 0x402977
+With stack:
+0x43df70: 0x0
+0x43df78: 0x0
+
+ +

Allocate an IPC buffer

+ +

As we mentioned in passing before, threads in seL4 do their own memory +management. You implement your own Virtual Memory Manager, essentially. +To the extent that you must allocate a physical memory frame, then map +it into your thread’s page directory – and even manually allocate page +tables on your own, where necessary.

+ +

Here’s the first step in a conventional memory manager’s process of +allocating memory: first allocate a physical frame. As you would expect, +you cannot directly write to or read from this frame object since it is +not mapped into any virtual address space as yet. Standard restrictions +of a MMU-utilizing kernel apply.

+ + + +

+    /* TASK 1: get a frame cap for the ipc buffer */
+    /* hint: vka_alloc_frame()
+     * int vka_alloc_frame(vka_t *vka, uint32_t size_bits, vka_object_t *result)
+     * @param vka Pointer to vka interface.
+     * @param size_bits Frame size: 2^size_bits
+     * @param result Structure for the Frame object.  This gets initialised.
+     * @return 0 on success
+     */
+    vka_object_t ipc_frame_object;
+
+ +
+ Quick solution + + 
    error = vka_alloc_frame(&vka, IPCBUF_FRAME_SIZE_BITS, &ipc_frame_object);
+    ZF_LOGF_IFERR(error, "Failed to alloc a frame for the IPC buffer.\n"
+                  "\tThe frame size is not the number of bytes, but an exponent.\n"
+                  "\tNB: This frame is not an immediately usable, virtually mapped page.\n")
+
+ +
+ +

On completion, the output will not change.

+ +

Try to map a page

+ +

Take note of the line of code that precedes this: the one where a +virtual address is randomly chosen for use. This is because, as we +explained before, the process is responsible for its own Virtual Memory +Management. As such, if it chooses, it can map any page in its VSpace to +physical frame. It can technically choose to do unconventional things, +like not unmap PFN #0. The control of how the address space is managed +is up to the threads that have write-capabilities to that address space. +There is both flexibility and responsibility implied here. Granted, seL4 +itself provides strong guarantees of isolation even if a thread decides +to go rogue.

+ +

Attempt to map the frame you allocated earlier, into your VSpace. A keen +reader will pick up on the fact that it’s unlikely that this will work, +since you’d need a new page table to contain the new page-table-entry. +The tutorial deliberately walks you through both the mapping of a frame +into a VSpace, and the mapping of a new page-table into a VSpace.

+ + + +

+    /* TASK 2: try to map the frame the first time  */
+    /* hint 1: seL4_ARCH_Page_Map()
+     * The *ARCH* versions of seL4 sys calls are abstractions over the architecture provided by libsel4utils
+     * this one is defined as:
+     * #define seL4_ARCH_Page_Map seL4_X86_Page_Map
+     * The signature for the underlying function is:
+     * int seL4_X86_Page_Map(seL4_X86_Page service, seL4_X86_PageDirectory pd, seL4_Word vaddr, seL4_CapRights rights, seL4_X86_VMAttributes attr)
+     * @param service Capability to the page to map.
+     * @param pd Capability to the VSpace which will contain the mapping.
+     * @param vaddr Virtual address to map the page into.
+     * @param rights Rights for the mapping.
+     * @param attr VM Attributes for the mapping.
+     * @return 0 on success.
+     *
+     * Note: this function is generated during build.  It is generated from the following definition:
+     *
+     * hint 2: for the rights, use seL4_AllRights
+     * hint 3: for VM attributes use seL4_ARCH_Default_VMAttributes
+     * Hint 4: It is normal for this function call to fail. That means there are
+     *    no page tables with free slots -- proceed to the next step where you'll
+     *    be led to allocate a new empty page table and map it into the VSpace,
+     *    before trying again.
+     */
+
+ +
+ Quick solution + + 
    error = seL4_ARCH_Page_Map(ipc_frame_object.cptr, pd_cap, ipc_buffer_vaddr,
+                               seL4_AllRights, seL4_ARCH_Default_VMAttributes);
+
+ +
+ +

On completion, the output will be as follows:

+ +
libraries-2: main@main.c:260 [Err seL4_FailedLookup]:
+    Failed to allocate new page table.
+
+ +

Allocate a page table

+ +

So just as you previously had to manually retype a new frame to use for +your IPC buffer, you’re also going to have to manually retype a new +page-table object to use as a leaf page-table in your VSpace.

+ + + +

+        /* TASK 3: create a page table */
+        /* hint: vka_alloc_page_table()
+         * int vka_alloc_page_table(vka_t *vka, vka_object_t *result)
+         * @param vka Pointer to vka interface.
+         * @param result Structure for the PageTable object.  This gets initialised.
+         * @return 0 on success
+         */
+
+ +
+ Quick solution + + 
        vka_object_t pt_object;
+        error =  vka_alloc_page_table(&vka, &pt_object);
+
+ +
+ +

On completion, you will see another fault.

+ +

Map a page table

+ +

If you successfully retyped a new page table from an untyped memory +object, you can now map that new page table into your VSpace, and then +try again to finally map the IPC-buffer’s frame object into the VSpace.

+ + + +

+        /* TASK 4: map the page table */
+        /* hint 1: seL4_ARCH_PageTable_Map()
+         * The *ARCH* versions of seL4 sys calls are abstractions over the architecture provided by libsel4utils
+         * this one is defined as:
+         * #define seL4_ARCH_PageTable_Map seL4_X86_PageTable_Map
+         * The signature for the underlying function is:
+         * int seL4_X86_PageTable_Map(seL4_X86_PageTable service, seL4_X86_PageDirectory pd, seL4_Word vaddr, seL4_X86_VMAttributes attr)
+         * @param service Capability to the page table to map.
+         * @param pd Capability to the VSpace which will contain the mapping.
+         * @param vaddr Virtual address to map the page table into.
+         * @param rights Rights for the mapping.
+         * @param attr VM Attributes for the mapping.
+         * @return 0 on success.
+         *
+         * Note: this function is generated during build.  It is generated from the following definition:
+         *
+         * hint 2: for VM attributes use seL4_ARCH_Default_VMAttributes
+         */
+
+ +

On completion, you will see another fault.

+
+ Quick solution + + 
        error = seL4_ARCH_PageTable_Map(pt_object.cptr, pd_cap,
+                                        ipc_buffer_vaddr, seL4_ARCH_Default_VMAttributes);
+
+ +
+ +

Map a page

+ +

Use seL4_ARCH_Page_Map to map the frame in. +If everything was done correctly, there is no reason why this step +should fail. Complete it and proceed.

+ +

+        /* TASK 5: then map the frame in */
+        /* hint 1: use seL4_ARCH_Page_Map() as above
+         * hint 2: for the rights, use seL4_AllRights
+         * hint 3: for VM attributes use seL4_ARCH_Default_VMAttributes
+         */
+
+
+ +
+ Quick solution + + 
        error = seL4_ARCH_Page_Map(ipc_frame_object.cptr, pd_cap,
+                                   ipc_buffer_vaddr, seL4_AllRights, seL4_ARCH_Default_VMAttributes);
+
+ +
+ +

On completion, you will see the following:

+ +
main: hello world
+libraries-2: main@main.c:464 [Cond failed: seL4_MessageInfo_get_length(tag) != 1]
+    Response data from thread_2 was not the length expected.
+    How many registers did you set with seL4_SetMR within thread_2?
+
+ +

Allocate an endpoint

+ +

Now we have a (fully mapped) IPC buffer – but no Endpoint object to +send our IPC data across. We must retype an untyped object into a kernel +Endpoint object, and then proceed. This could be done via a more +low-level approach using seL4_Untyped_Retype(), but instead, the +tutorial makes use of the VKA allocator. Remember that the VKA allocator +is an seL4 type-aware object allocator? So we can simply ask it for a +new object of a particular type, and it will do the low-level retyping +for us, and return a capability to a new object as requested.

+ +

In this case, we want a new Endpoint so we can do IPC. Complete the step +and proceed.

+ + + +

+    /* TASK 6: create an endpoint */
+    /* hint: vka_alloc_endpoint()
+     * int vka_alloc_endpoint(vka_t *vka, vka_object_t *result)
+     * @param vka Pointer to vka interface.
+     * @param result Structure for the Endpoint object.  This gets initialised.
+     * @return 0 on success
+     */
+
+ +
+ Quick solution + + 
    error = vka_alloc_endpoint(&vka, &ep_object);
+
+ +
+ +

On completion, the output will not change.

+ +

Badge an endpoint

+ +

Badges are used to uniquely identify a message queued on an endpoint as +having come from a particular sender. Recall that in seL4, each thread +has only one IPC buffer. If multiple other threads are sending data to a +listening thread, how can that listening thread distinguish between the +data sent by each of its IPC partners? Each sender must “badge” its +capability to its target’s endpoint.

+ +

Note the distinction: the badge is not applied to the target endpoint, +but to the sender’s capability to the target endpoint. This +enables the listening thread to mint off copies of a capability to an +Endpoint to multiple senders. Each sender is responsible for applying a +unique badge value to the capability that the listener gave it so that +the listener can identify it.

+ +

In this step, you are badging the endpoint that you will use when +sending data to the thread you will be creating later on. The +vka_mint_object() call will return a new, badged copy of the +capability to the endpoint that your new thread will listen on. When you +send data to your new thread, it will receive the badge value with the +data, and know which sender you are. Complete the step and proceed.

+ + + +

+    /* TASK 7: make a badged copy of it in our cspace. This copy will be used to send
+     * an IPC message to the original cap */
+    /* hint 1: vka_mint_object()
+     * int vka_mint_object(vka_t *vka, vka_object_t *object, cspacepath_t *result, seL4_CapRights rights, seL4_Word badge)
+     * @param[in] vka The allocator for the cspace.
+     * @param[in] object Target object for cap minting.
+     * @param[out] result Allocated cspacepath.
+     * @param[in] rights The rights for the minted cap.
+     * @param[in] badge The badge for the minted cap.
+     * @return 0 on success
+     *
+     * hint 2: for the rights, use seL4_AllRights
+     * hint 3: for the badge use EP_BADGE
+     */
+
+ +
+ Quick solution + + 
    error = vka_mint_object(&vka, &ep_object, &ep_cap_path, seL4_AllRights,
+                            EP_BADGE);
+
+ +
+ +

On completion, the output will not change.

+ +

Message registers

+ +

Here we get a formal introduction to message registers. At first glance, +you might wonder why the sel4_SetMR() calls don’t specify a message +buffer, and seem to know which buffer to fill out – and that would be +correct, because they do. They are operating directly on the sending +thread’s IPC buffer. Recall that each thread has only one IPC buffer. Go +back and look at your call to seL4_TCB_Configure() in step 7 again: +you set the IPC buffer for the new thread in the last 2 arguments to +this function. Likewise, the thread that created your main thread +also set an IPC buffer up for you.

+ +

So seL4_SetMR() and seL4_GetMR() simply write to and read from the IPC +buffer you designated for your thread. MSG_DATA is uninteresting – can +be any value. You’ll find the seL4_MessageInfo_t type explained in the +manuals. In short, it’s a header that is embedded in each message that +specifies, among other things, the number of Message Registers that hold +meaningful data, and the number of capabilities that are going to be +transmitted in the message.

+ + + +

+    /* TASK 8: set the data to send. We send it in the first message register */
+    /* hint 1: seL4_MessageInfo_new()
+     * seL4_MessageInfo_t CONST seL4_MessageInfo_new(seL4_Uint32 label, seL4_Uint32 capsUnwrapped, seL4_Uint32 extraCaps, seL4_Uint32 length)
+     * @param label The value of the label field
+     * @param capsUnwrapped The value of the capsUnwrapped field
+     * @param extraCaps The value of the extraCaps field
+     * @param length The number of message registers to send
+     * @return The seL4_MessageInfo_t containing the given values.
+     *
+     * seL4_MessageInfo_new() is generated during build. It can be found in:
+     * build/x86/pc99/libsel4/include/sel4/types_gen.h
+     *
+     * hint 2: use 0 for the first 3 fields.
+     * hint 3: send only 1 message register of data
+     *
+     * hint 4: seL4_SetMR()
+     * void seL4_SetMR(int i, seL4_Word mr)
+     * @param i The message register to write
+     * @param mr The value of the message register
+     *
+     * hint 5: send MSG_DATA
+     */
+
+ +
+ Quick solution + + 
    tag = seL4_MessageInfo_new(0, 0, 0, 1);
+    seL4_SetMR(0, MSG_DATA);
+
+ +
+ +

On completion, the output should change as follows:

+ +
libraries-2: main@main.c:472 [Cond failed: msg != ~MSG_DATA]
+    Response data from thread_2's content was not what was expected.
+
+ +

IPC

+ +

Now that you’ve constructed your message and badged the endpoint that +you’ll use to send it, it’s time to send it. The seL4_Call() syscall +will send a message across an endpoint synchronously. If there is no +thread waiting at the other end of the target endpoint, the sender will +block until there is a waiter. The reason for this is because the seL4 +kernel would prefer not to buffer IPC data in the kernel address space, +so it just sleeps the sender until a receiver is ready, and then +directly copies the data. It simplifies the IPC logic. There are also +polling send operations, as well as polling receive operations in case +you don’t want to be forced to block if there is no receiver on the +other end of an IPC Endpoint.

+ +

When you send your badged data using seL4_Call(), our receiving thread +(which we created earlier) will pick up the data, see the badge, and +know that it was us who sent the data. Notice how the sending thread +uses the badged capability to the endpoint object, and the +receiving thread uses the unmodified original capability to the same +endpoint? The sender must identify itself.

+ +

Notice also that the fact that both the sender and the receiver share +the same root CSpace, enables the receiving thread to just casually use +the original, unbadged capability without any extra work needed to make +it accessible.

+ +

Notice however also, that while the sending thread has a capability that +grants it full rights to send data across the endpoint since it was the +one that created that capability, the receiver’s capability may not +necessarily grant it sending powers (write capability) to the endpoint. +It’s entirely possible that the receiver may not be able to send a +response message, if the sender doesn’t want it to.

+ + + +

+    /* TASK 9: send and wait for a reply. */
+    /* hint: seL4_Call()
+     * seL4_MessageInfo_t seL4_Call(seL4_CPtr dest, seL4_MessageInfo_t msgInfo)
+     * @param dest The capability to be invoked.
+     * @param msgInfo The messageinfo structure for the IPC.  This specifies information about the message to send (such as the number of message registers to send).
+     * @return A seL4_MessageInfo_t structure.  This is information about the repy message.
+     *
+     * hint 2: seL4_MessageInfo_t is generated during build.
+     * The type definition and generated field access functions are defined in a generated file:
+     * build/x86/pc99/libsel4/include/sel4/types_gen.h
+     * It is generated from the following definition:
+     */
+
+ +
+ Quick solution + + 
    tag = seL4_Call(ep_cap_path.capPtr, tag);
+
+ +
+ +

On completion, you should see thread_2 fault as follows:

+ +
thread_2: hallo wereld
+thread_2: got a message 0 from 0
+Caught cap fault in send phase at address (nil)
+while trying to handle:
+vm fault on data at address (nil) with status 0x4
+in thread 0xffffff801ffb4400 "child of: 'rootserver'" at address (nil)
+in thread 0xffffff801ffb4400 "child of: 'rootserver'" at address (nil)
+With stack:
+
+ +

Receive a reply

+ +

While this task is out of order, since we haven’t yet examined the +receive-side of the operation here, it’s fairly simple anyway: this task +occurs after the receiver has sent a reply, and it shows the sender now +reading the reply from the receiver. As mentioned before, the +seL4_GetMR() calls are simply reading from the calling thread’s +designated, single IPC buffer.

+ + + +

+    /* TASK 10: get the reply message */
+    /* hint: seL4_GetMR()
+     * seL4_Word seL4_GetMR(int i)
+     * @param i The message register to retreive
+     * @return The message register value
+     */
+
+ +
+ Quick solution + + 
    msg = seL4_GetMR(0);
+
+ +
+ +

On completion, the output should not change.

+ +

Receive an IPC

+ +

We’re now in the receiving thread. The seL4_Recv() syscall performs a +blocking listen on an Endpoint or Notification capability. When new data +is queued (or when the Notification is signalled), the seL4_Recv +operation will unqueue the data and resume execution.

+ +

Notice how the seL4_Recv() operation explicitly makes allowance for +reading the badge value on the incoming message? The receiver is +explicitly interested in distinguishing the sender.

+ + + +

+    /* TASK 11: wait for a message to come in over the endpoint */
+    /* hint 1: seL4_Recv()
+     * seL4_MessageInfo_t seL4_Recv(seL4_CPtr src, seL4_Word* sender)
+     * @param src The capability to be invoked.
+     * @param sender The badge of the endpoint capability that was invoked by the sender is written to this address.
+     * @return A seL4_MessageInfo_t structure
+     *
+     * hint 2: seL4_MessageInfo_t is generated during build.
+     * The type definition and generated field access functions are defined in a generated file:
+     * build/x86/pc99/libsel4/include/sel4/types_gen.h
+     */
+
+ +
+ Quick solution + + 
    tag = seL4_Recv(ep_object.cptr, &sender_badge);
+
+ +
+ +

On completion, the output should change slightly:

+ +
thread_2: got a message 0 from 0x61
+
+ +

Validate the message

+ +

These two calls here are just verification of the fidelity of the +transmitted message. It’s very unlikely you’ll encounter an error here. +Complete them and proceed to the next step.

+ + + +

+    /* TASK 12: make sure it is what we expected */
+    /* hint 1: check the badge. is it EP_BADGE?
+     * hint 2: we are expecting only 1 message register
+     * hint 3: seL4_MessageInfo_get_length()
+     * seL4_Uint32 CONST seL4_MessageInfo_get_length(seL4_MessageInfo_t seL4_MessageInfo)
+     * @param seL4_MessageInfo the seL4_MessageInfo_t to extract a field from
+     * @return the number of message registers delivered
+     * seL4_MessageInfo_get_length() is generated during build. It can be found in:
+     * build/x86/pc99/libsel4/include/sel4/types_gen.h
+     */
+
+ +
+ Quick solution + + 
    ZF_LOGF_IF(sender_badge != EP_BADGE,
+               "Badge on the endpoint was not what was expected.\n");
+
+    ZF_LOGF_IF(seL4_MessageInfo_get_length(tag) != 1,
+               "Length of the data send from root thread was not what was expected.\n"
+               "\tHow many registers did you set with seL4_SetMR, within the root thread?\n");
+
+ +
+ +

On completion, the output should not change.

+ +

Read the message registers

+ +

Again, just reading the data from the Message Registers.

+ + + +

+    /* TASK 13: get the message stored in the first message register */
+    /* hint: seL4_GetMR()
+     * seL4_Word seL4_GetMR(int i)
+     * @param i The message register to retreive
+     * @return The message register value
+     */
+
+ +
+ Quick solution + + 
    msg = seL4_GetMR(0);
+
+ +
+ +

On completion, the output should change slightly:

+ +
thread_2: got a message 0x6161 from 0x61
+
+ +

Write the message registers

+ +

And writing Message Registers again.

+ + + +

+    /* TASK 14: copy the modified message back into the message register */
+    /* hint: seL4_SetMR()
+     * void seL4_SetMR(int i, seL4_Word mr)
+     * @param i The message register to write
+     * @param mr The value of the message register
+     */
+
+ +
+ Quick solution + + 
    seL4_SetMR(0, msg);
+
+ +
+ +

On completion, the output should not change.

+ +

Reply to a message

+ +

This is a formal introduction to the Reply capability which is +automatically generated by the seL4 kernel, whenever an IPC message is +sent using the seL4_Call() syscall. This is unique to the seL4_Call() +syscall, and if you send data instead with the seL4_Send() syscall, the +seL4 kernel will not generate a Reply capability.

+ +

The Reply capability solves the issue of a receiver getting a message +from a sender, but not having a sufficiently permissive capability to +respond to that sender. The “Reply” capability is a one-time capability +to respond to a particular sender. If a sender doesn’t want to grant the +target the ability to send to it repeatedly, but would like to allow the +receiver to respond to a specific message once, it can use seL4_Call(), +and the seL4 kernel will facilitate this one-time permissive response. +Complete the step and pat yourself on the back.

+ + + +

+    /* TASK 15: send the message back */
+    /* hint 1: seL4_ReplyRecv()
+     * seL4_MessageInfo_t seL4_ReplyRecv(seL4_CPtr dest, seL4_MessageInfo_t msgInfo, seL4_Word *sender)
+     * @param dest The capability to be invoked.
+     * @param msgInfo The messageinfo structure for the IPC.  This specifies information about the message to send (such as the number of message registers to send) as the Reply part.
+     * @param sender The badge of the endpoint capability that was invoked by the sender is written to this address.  This is a result of the Wait part.
+     * @return A seL4_MessageInfo_t structure.  This is a result of the Wait part.
+     *
+     * hint 2: seL4_MessageInfo_t is generated during build.
+     * The type definition and generated field access functions are defined in a generated file:
+     * build/x86/pc99/libsel4/include/sel4/types_gen.h
+     * It is generated from the following definition:
+     */
+
+ +
+ Quick solution + + 
    seL4_ReplyRecv(ep_object.cptr, tag, &sender_badge);
+
+ +
+ +

On completion, the output should change, with the fault message replaced with the following:

+ +
main: got a reply: [0xffff9e9e|0xffffffffffff9e9e]
+
+ +

That’s it for this tutorial.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/libraries-2.md b/Tutorials/libraries-2.md deleted file mode 100644 index d8c61b0d05b..00000000000 --- a/Tutorials/libraries-2.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Libraries IPC -tutorial: libraries-2 -layout: tutorial -description: IPC with seL4_libs -nav_prev: libraries-1.html -nav_next: libraries-3.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/libraries-3.html b/Tutorials/libraries-3.html new file mode 100644 index 00000000000..08e5e3b0aa3 --- /dev/null +++ b/Tutorials/libraries-3.html @@ -0,0 +1,1040 @@ + + + + + + + Libraries processes & ELF loading | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

seL4 Libraries: Processes & ELF loading

+ +

This tutorial shows how a separate ELF file can be loaded and expanded into a +VSpace, and subsequently executed, while facilitating IPC between the +two modules. It also shows how threads with different CSpaces have to +maneuver in order to pass capabilities to one another.

+ +

Don’t gloss over the globals declared before main() – they’re declared +for your benefit so you can grasp some of the basic data structures. +Uncomment them one by one as needed when going through the tasks.

+ +

You’ll observe that the things you’ve already covered in the second +tutorial are filled out and you don’t have to repeat them: in much the +same way, we won’t be repeating conceptual explanations on this page, if +they were covered by a previous tutorial in the series.

+ +

Learning outcomes:

+ +
    +
  • Once again, repeat the spawning of a thread: however, this time + the two threads will only share the same vspace, but have + different CSpaces. This is an automatic side effect of the way + that sel4utils creates new “processes”.
    • +
  • Learn how the init thread in an seL4 system performs some types + of initialisation that aren’t traditionally left to userspace.
    • +
  • Observe and understand the effects of creating thread that do + not share the same CSpace.
    • +
  • Understand IPC across CSpace boundaries.
    • +
  • Understand how minting a capability to a thread in another + CSpace works.
    • +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Libraries: IPC
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut libraries-3
+# building the tutorial exercise
+cd libraries-3_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut libraries-3
+# building the tutorial exercise
+cd libraries-3_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

Exercises

+ +

Tasks in this tutorial are in main.c and app.c.

+ +

When you first run this tutorial, you should see the following output:

+ +
Booting all finished, dropped to user space
+Node 0 of 1
+IOPT levels:     4294967295
+IPC buffer:      0x57f000
+Empty slots:     [488 --> 4096)
+sharedFrames:    [0 --> 0)
+userImageFrames: [16 --> 399)
+userImagePaging: [12 --> 15)
+untypeds:        [399 --> 488)
+Initial thread domain: 0
+Initial thread cnode size: 12
+libraries-3: vspace_reserve_range_aligned@vspace.h:621 Not implemented
+libraries-3: main@main.c:117 [Cond failed: virtual_reservation.res == NULL]
+    Failed to reserve a chunk of memory.
+
+ +

Virtual memory management

+ +

Aside from receiving information about IRQs in the IRQControl object +capability, and information about available IO-Ports, and ASID +availability, and several other privileged bits of information, the init +thread is also responsible, surprisingly, for reserving certain critical +ranges of memory as being used, and unavailable for applications.

+ +

This call to sel4utils_bootstrap_vspace_with_bootinfo_leaky() does +that. For an interesting look at what sorts of things the init thread +does, see: +static int reserve_initial_task_regions(vspace_t *vspace, void *existing_frames[]), +which is eventually called on by +sel4utils_bootstrap_vspace_with_bootinfo_leaky(). So while this +function may seem tedious, it’s doing some important things.

+ + + +

+    /* TASK 1: create a vspace object to manage our vspace */
+    /* hint 1: sel4utils_bootstrap_vspace_with_bootinfo_leaky()
+     * int sel4utils_bootstrap_vspace_with_bootinfo_leaky(vspace_t *vspace, sel4utils_alloc_data_t *data, seL4_CPtr page_directory, vka_t *vka, seL4_BootInfo *info)
+     * @param vspace Uninitialised vspace struct to populate.
+     * @param data Uninitialised vspace data struct to populate.
+     * @param page_directory Page directory for the new vspace.
+     * @param vka Initialised vka that this virtual memory allocator will use to allocate pages and pagetables. This allocator will never invoke free.
+     * @param info seL4 boot info
+     * @return 0 on succes.
+     */
+
+ +
+ Quick solution + + 
    error = sel4utils_bootstrap_vspace_with_bootinfo_leaky(&vspace,
+                                                           &data, simple_get_pd(&simple), &vka, info);
+
+ +
+ +

On success, you should see a different error:

+ +
<<seL4(CPU 0) [handleUnknownSyscall/106 T0xffffff801ffb5400 "libraries-3" @40139e]: SysDebugNameThread: cap is not a TCB, halting>>
+halting...
+
+ +

Configure a process

+ +

sel4utils_configure_process_custom took a large amount of the work +out of creating a new “processs”. We skipped a number of steps. Take a +look at the source for sel4utils_configure_process_custom() and +notice how it spawns the new thread with its own CSpace by +automatically. This will have an effect on our tutorial! It means that +the new thread we’re creating will not share a CSpace with our main +thread.

+ + + +

+    /* TASK 2: use sel4utils to make a new process */
+    /* hint 1: sel4utils_configure_process_custom()
+     * hint 2: process_config_default_simple()
+     * @param process Uninitialised process struct.
+     * @param vka Allocator to use to allocate objects.
+     * @param vspace Vspace allocator for the current vspace.
+     * @param priority Priority to configure the process to run as.
+     * @param image_name Name of the elf image to load from the cpio archive.
+     * @return 0 on success, -1 on error.
+     *
+     * hint 2: priority is in APP_PRIORITY and can be 0 to seL4_MaxPrio
+     * hint 3: the elf image name is in APP_IMAGE_NAME
+     */
+
+ +
+ Quick solution + + 
    sel4utils_process_config_t config = process_config_default_simple(&simple, APP_IMAGE_NAME, APP_PRIORITY);
+    error = sel4utils_configure_process_custom(&new_process, &vka, &vspace, config);
+
+ +
+ +

On success, you should see a different error:

+ +
 libraries-3: main@main.c:196 [Cond failed: new_ep_cap == 0]
+    Failed to mint a badged copy of the IPC endpoint into the new thread's CSpace.
+    sel4utils_mint_cap_to_process takes a cspacepath_t: double check what you passed.
+
+ +

Get a cspacepath

+ +

Now, in this particular case, we are making the new thread be the +sender. Recall that the sender must have a capability to the endpoint +that the receiver is listening on, in order to send to that listener. +But in this scenario, our threads do not share the same CSpace! +The only way the new thread will know which endpoint it needs a +capability to, is if we tell it. Furthermore, even if the new thread +knows which endpoint object we are listening on, if it doesn’t have a +capability to that endpoint, it still can’t send data to us. So we must +provide our new thread with both a capability to the endpoint we’re +listening on, and also make sure, that that capability we give it has +sufficient privileges to send across the endpoint.

+ +

There is a number of ways we could approach this, but in this tutorial +we decided to just pre-initialize the sender’s CSpace with a sufficient +capability to enable it to send to us right from the start of its +execution. We could also have spawned the new thread as a listener +instead, and made it wait for us to send it a message with a sufficient +capability.

+ +

So we use vka_cspace_make_path(), which locates one free capability +slot in the selected CSpace, and returns a handle to it, to us. We then +filled that free slot in the new thread’s CSpace with a badged +capability to the endpoint we are listening on, so as so allow it to +send to us immediately. We could have filled the slot with an unbadged +capability, but then if we were listening for multiple senders, we +wouldn’t know who was whom.

+ + + +

+    /* TASK 3: make a cspacepath for the new endpoint cap */
+    /* hint 1: vka_cspace_make_path()
+     * void vka_cspace_make_path(vka_t *vka, seL4_CPtr slot, cspacepath_t *res)
+     * @param vka Vka interface to use for allocation of objects.
+     * @param slot A cslot allocated by the cspace alloc function
+     * @param res Pointer to a cspacepath struct to fill out
+     *
+     * hint 2: use the cslot of the endpoint allocated above
+     */
+    cspacepath_t ep_cap_path;
+    seL4_CPtr new_ep_cap = 0;
+
+ +
+ Quick solution + + 
    vka_cspace_make_path(&vka, ep_object.cptr, &ep_cap_path);
+
+ +
+ +

On success, the output should not change.

+ +

Badge a capability

+ +

As discussed above, we now just mint a badged copy of a capability to +the endpoint we’re listening on, into the new thread’s CSpace, in the +free slot that the VKA library found for us.

+ + + +

+    /* TASK 4: copy the endpont cap and add a badge to the new cap */
+    /* hint 1: sel4utils_mint_cap_to_process()
+     * seL4_CPtr sel4utils_mint_cap_to_process(sel4utils_process_t *process, cspacepath_t src, seL4_CapRights rights, seL4_Word data)
+     * @param process Process to copy the cap to
+     * @param src Path in the current cspace to copy the cap from
+     * @param rights The rights of the new cap
+     * @param data Extra data for the new cap (e.g., the badge)
+     * @return 0 on failure, otherwise the slot in the processes cspace.
+     *
+     * hint 2: for the rights, use seL4_AllRights
+     * hint 3: for the badge value use EP_BADGE
+     */
+
+ +
+ Quick solution + + 
    new_ep_cap = sel4utils_mint_cap_to_process(&new_process, ep_cap_path,
+                                               seL4_AllRights, EP_BADGE);
+
+ +
+ +

On success, the output should look something like:

+ +
NEW CAP SLOT: 6ac.
+main: hello world
+libraries-3: main@main.c:247 [Cond failed: sender_badge != EP_BADGE]
+    The badge we received from the new thread didn't match our expectation
+
+ +

Spawn a process

+ +

So now that we’ve given the new thread everything it needs to +communicate with us, we can let it run. Complete this step and proceed.

+ + + +

+    /* TASK 5: spawn the process */
+    /* hint 1: sel4utils_spawn_process_v()
+     * int sel4utils_spawn_process_v(sel4utils_process_t *process, vka_t *vka, vspace_t *vspace, int argc, char *argv[], int resume)
+     * @param process Initialised sel4utils process struct.
+     * @param vka Vka interface to use for allocation of frames.
+     * @param vspace The current vspace.
+     * @param argc The number of arguments.
+     * @param argv A pointer to an array of strings in the current vspace.
+     * @param resume 1 to start the process, 0 to leave suspended.
+     * @return 0 on success, -1 on error.
+     */
+    /* hint 2: sel4utils_create_word_args()
+     * void sel4utils_create_word_args(char strings[][WORD_STRING_SIZE], char *argv[], int argc, ...)
+     * Create c-formatted argument list to pass to a process from arbitrarily long amount of words.
+     *
+     * @param strings empty 2d array of chars to populate with word strings.
+     * @param argv empty 1d array of char pointers which will be set up with pointers to
+     *             strings in strings.
+     * @param argc number of words
+     * @param ... list of words to create arguments from.
+     *
+     */
+
+ +
+ Quick solution + + 
    new_ep_cap = sel4utils_mint_cap_to_process(&new_process, ep_cap_path,
+                                               seL4_AllRights, EP_BADGE);
+    seL4_Word argc = 1;
+    char string_args[argc][WORD_STRING_SIZE];
+    char* argv[argc];
+    sel4utils_create_word_args(string_args, argv, argc, new_ep_cap);
+
+    error = sel4utils_spawn_process_v(&new_process, &vka, &vspace, argc, (char**) &argv, 1);
+
+ +
+ +

On success, you should be able to see the second process running. The output should +be as follows:

+ +
NEW CAP SLOT: 6ac.
+process_2: hey hey hey
+main@app.c:67 [Cond failed: msg != ~MSG_DATA]
+    Unexpected response from root thread.
+main: hello world
+libraries-3: main@main.c:255 [Cond failed: sender_badge != EP_BADGE]
+    The badge we received from the new thread didn't match our expectation.
+
+ +

Receive a message

+ +

We now wait for the new thread to send us data using seL4_Recv()… +Then we verify the fidelity of the data that was transmitted.

+ + + +

+    /* TASK 6: wait for a message */
+    /* hint 1: seL4_Recv()
+     * seL4_MessageInfo_t seL4_Recv(seL4_CPtr src, seL4_Word* sender)
+     * @param src The capability to be invoked.
+     * @param sender The badge of the endpoint capability that was invoked by the sender is written to this address.
+     * @return A seL4_MessageInfo_t structure
+     *
+     * hint 2: seL4_MessageInfo_t is generated during build.
+     * hint 3: use the badged endpoint cap that you minted above
+     */
+
+ +
+ Quick solution + + 
    tag = seL4_Recv(ep_cap_path.capPtr, &sender_badge);
+
+ +
+ +

On success, the badge error should no longer be visible.

+ +

Send a reply

+ +

Another demonstration of the sel4_Reply() facility: we reply to the +message sent by the new thread.

+ + + +

+    /* TASK 7: send the modified message back */
+    /* hint 1: seL4_ReplyRecv()
+     * seL4_MessageInfo_t seL4_ReplyRecv(seL4_CPtr dest, seL4_MessageInfo_t msgInfo, seL4_Word *sender)
+     * @param dest The capability to be invoked.
+     * @param msgInfo The messageinfo structure for the IPC.  This specifies information about the message to send (such as the number of message registers to send) as the Reply part.
+     * @param sender The badge of the endpoint capability that was invoked by the sender is written to this address. This is a result of the Wait part.
+     * @return A seL4_MessageInfo_t structure.  This is a result of the Wait part.
+     *
+     * hint 2: seL4_MessageInfo_t is generated during build.
+     * hint 3: use the badged endpoint cap that you used for Call
+     */
+
+ +
+ Quick solution + + 
    seL4_ReplyRecv(ep_cap_path.capPtr, tag, &sender_badge);
+
+ +
+ +

On success, the output should not change.

+ +

Client Call

+ +

In the new thread, we initiate communications by using seL4_Call(). As +outlined above, the receiving thread replies to us using +sel4_ReplyRecv(). The new thread then checks the fidelity of the data +that was sent, and that’s the end.

+ + + +

+ /* TASK 8: send and wait for a reply */
+    /* hint 1: seL4_Call()
+     * seL4_MessageInfo_t seL4_Call(seL4_CPtr dest, seL4_MessageInfo_t msgInfo)
+     * @param dest The capability to be invoked.
+     * @param msgInfo The messageinfo structure for the IPC.  This specifies information about the message to send (such as the number of message registers to send).
+     * @return A seL4_MessageInfo_t structure.  This is information about the repy message.
+     *
+     * hint 2: send the endpoint cap using argv (see TASK 6 in the other main.c)
+     */
+    ZF_LOGF_IF(argc < 1,
+               "Missing arguments.\n");
+    seL4_CPtr ep = (seL4_CPtr) atol(argv[0]);
+
+ +
+ Quick solution + + 
    tag = seL4_Call(ep, tag);
+
+ +
+

On success, you should see the following:

+ +
process_2: hey hey hey
+main: got a message 0x6161 from 0x61
+process_2: got a reply: 0xffffffffffff9e9e
+
+ +

That’s it for this tutorial.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/libraries-3.md b/Tutorials/libraries-3.md deleted file mode 100644 index a5edd4f259d..00000000000 --- a/Tutorials/libraries-3.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Libraries processes & ELF loading -tutorial: libraries-3 -layout: tutorial -description: process management with seL4_libs -nav_prev: libraries-2.html -nav_next: libraries-4.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/libraries-4.html b/Tutorials/libraries-4.html new file mode 100644 index 00000000000..681a99b1936 --- /dev/null +++ b/Tutorials/libraries-4.html @@ -0,0 +1,804 @@ + + + + + + + Libraries timer tutorial | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

seL4 Libraries: Timer Tutorial

+ +

This tutorial demonstrates how to set up and use a basic timer driver using the +seL4_libs libraries.

+ +

You’ll observe that the things you’ve already covered in the other +tutorials are already filled out and you don’t have to repeat them: in +much the same way, we won’t be repeating conceptual explanations on this +page, if they were covered by a previous tutorial in the series.

+ +

Learning outcomes:

+ +
    +
  • Allocate a notification object.
    • +
  • Set up a timer provided by util_libs.
    • +
  • Use seL4_libs and util_libs functions to manipulate timer and + handle interrupts.
    • +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Libraries: processes & elf loading
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut libraries-4
+# building the tutorial exercise
+cd libraries-4_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut libraries-4
+# building the tutorial exercise
+cd libraries-4_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

Exercises

+ +

Once you initialise and run the tutorials, you will see the following output:

+ +
Booting all finished, dropped to user space
+Node 0 of 1
+IOPT levels:     4294967295
+IPC buffer:      0x5a1000
+Empty slots:     [523 --> 4096)
+sharedFrames:    [0 --> 0)
+userImageFrames: [16 --> 433)
+userImagePaging: [12 --> 15)
+untypeds:        [433 --> 523)
+Initial thread domain: 0
+Initial thread cnode size: 12
+timer client: hey hey hey
+main: hello world
+main: got a message from 0x61 to sleep 2 seconds
+ltimer_get_time@ltimer.h:267 get_time not implemented
+timer client wakes up:
+ got the current timer tick:
+ 0
+
+

Allocate a notification object

+ +

The first task is to allocate a notification object to receive +interrupts on.

+

+    /* TASK 1: create a notification object for the timer interrupt */
+    /* hint: vka_alloc_notification()
+     * int vka_alloc_notification(vka_t *vka, vka_object_t *result)
+     * @param vka Pointer to vka interface.
+     * @param result Structure for the notification object. This gets initialised.
+     * @return 0 on success
+     * https://github.com/seL4/libsel4vka/blob/master/include/vka/object.h#L98
+     */
+    vka_object_t ntfn_object = {0};
+
+ +
+ Quick solution + + 
    error = vka_alloc_notification(&vka, &ntfn_object);
+    assert(error == 0);
+
+
+ +

The output will not change as a result of completing this task.

+ +

Initialise the timer

+ +

Use our library function ltimer_default_init to +initialise a timer driver. Assign it to the timer global variable.

+

+    /* TASK 2: call ltimer library to get the default timer */
+    /* hint: ltimer_default_init, you can set NULL for the callback and token
+     */
+    ps_io_ops_t ops = 0;
+    error = sel4platsupport_new_malloc_ops(&ops.malloc_ops);
+    assert(error == 0);
+    error = sel4platsupport_new_io_mapper(&vspace, &vka, &ops.io_mapper);
+    assert(error == 0);
+    error = sel4platsupport_new_fdt_ops(&ops.io_fdt, &simple, &ops.malloc_ops);
+    assert(error == 0);
+    if (ntfn_object.cptr != seL4_CapNull) {
+        error = sel4platsupport_new_mini_irq_ops(&ops.irq_ops, &vka, &simple, &ops.malloc_ops,
+                                                 ntfn_object.cptr, MASK(seL4_BadgeBits));
+        assert(error == 0);
+    }
+    error = sel4platsupport_new_arch_ops(&ops, &simple, &vka);
+    assert(error == 0);
+
+ +
+ Quick solution + + 
    error = ltimer_default_init(&timer, ops, NULL, NULL);
+    assert(error == 0);
+
+
+ +

After this change, the server will output non-zero for the tick value at the end.

+
 got the current timer tick:
+ 1409040
+
+ +

Use the timer

+ +

While at the end of the previous task the tutorial appears to be +working, the main thread replies immediately to the client and doesn’t +wait at all.

+ +

Consequently, the final task is to interact with the timer: set a +timeout, wait for an interrupt on the created notification, and handle +it.

+ +

+    /*
+     * TASK 3: Start and configure the timer
+     * hint 1: ltimer_set_timeout
+     * hint 2: set period to 1 millisecond
+     */
+
+ +
+ Quick solution + + 
    error = ltimer_set_timeout(&timer, NS_IN_MS, TIMEOUT_PERIODIC);
+    assert(error == 0);
+
+
+ +

The output will cease after the following line as a result of completing this task.

+
main: got a message from 0x61 to sleep 2 seconds
+
+ +

Handle the interrupt

+ +

In order to receive more interrupts, you need to handle the interrupt in the driver +and acknowledge the irq.

+ +

+        /*
+         * TASK 4: Handle the timer interrupt
+         * hint 1: wait for the incoming interrupt and handle it
+         * The loop runs for (1000 * msg) times, which is basically 1 second * msg.
+         *
+         * hint2: seL4_Wait
+         * hint3: sel4platsupport_irq_handle
+         * hint4: 'ntfn_id' should be MINI_IRQ_INTERFACE_NTFN_ID and handle_mask' should be the badge
+         *
+         */
+
+ +
+ Quick solution + + 
        seL4_Word badge;
+        seL4_Wait(ntfn_object.cptr, &badge);
+        sel4platsupport_irq_handle(&ops.irq_ops, MINI_IRQ_INTERFACE_NTFN_ID, badge);
+        count++;
+        if (count == 1000 * msg) {
+            break;
+        }
+
+
+

The timer interrupts are bound to the IRQ interface initialised in Task 2, +hence when we receive an interrupt, we forward it to the interface and let it notify the timer driver.

+ +

After this task is completed you should see a 2 second wait, then output from the + client as follows:

+
timer client wakes up:
+ got the current timer tick:
+ 2365866120
+
+ +

Destroy the timer

+ +

+    /*
+     * TASK 5: Stop the timer
+     * hint: ltimer_destroy
+     */
+
+ +
+ Quick solution + + 
    ltimer_destroy(&timer);
+
+
+ +

The output should not change on successful completion of completing this task.

+ +

That’s it for this tutorial.

+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/libraries-4.md b/Tutorials/libraries-4.md deleted file mode 100644 index 59a1ca0cc64..00000000000 --- a/Tutorials/libraries-4.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Libraries timer tutorial -tutorial: libraries-4 -layout: tutorial -description: timers and timeouts with seL4_libs -nav_prev: libraries-3.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/mapping.html b/Tutorials/mapping.html new file mode 100644 index 00000000000..728ae264f94 --- /dev/null +++ b/Tutorials/mapping.html @@ -0,0 +1,870 @@ + + + + + + + Mapping | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Mapping

+ +

This tutorial provides an introduction to virtual memory management on seL4.

+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Capabilities tutorial
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut mapping
+# building the tutorial exercise
+cd mapping_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut mapping
+# building the tutorial exercise
+cd mapping_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

Background

+ +

Virtual memory

+ +

seL4 does not provide virtual memory management, beyond kernel primitives for manipulating hardware +paging structures. User-level must provide services for creating intermediate paging structures, +mapping and unmapping pages.

+ +

Users are free to define their own address space layout with one restriction: the seL4 kernel claims +the high part of the virtual memory range. On most 32-bit platforms, this is +0xe0000000 and above. This variable is set per platform, and can be found by finding the kernelBase variable +in the seL4 source.

+ +

Paging structures

+ +

As part of the boot process, seL4 initialises the root task with a top-level hardware virtual +memory object, which is referred to as a VSpace. A capability to this structure is made available in the +seL4_CapInitThreadVSpace slot in the root tasks CSpace. For each architecture, this capability is +to a different object type corresponding to the hardware, top-level paging structure. The table below + lists the VSpace object type for each supported architecture.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArchitectureVSpace Object
aarch32seL4_PageDirectory
aarch64seL4_PageGlobalDirectory
ia32seL4_PageDirectory
x86_64seL4_PML4
RISC-VseL4_PageTable
+ +

In addition to the top-level paging structure, intermediate hardware virtual memory objects are required to +map pages. The table below lists those objects, in order, for each architecture.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArchitectureObjects
aarch32seL4_PageTable
aarch64seL4_PageUpperDirectory, seL4_PageDirectory, seL4_PageTable
ia32seL4_PageTable
x86_64seL4_PDPT, seL4_PageDirectory, seL4_PageTable
RISC-VseL4_PageTable
+ +

This tutorial covers the x86_64 architecture, but should contain sufficient information on the virtual +memory API provided by seL4 to generalise to other architectures.

+ +

Each paging structure can be invoked in order to map or unmap it. Below is an example of mapping +an x86_64 seL4_PDPT object:

+ +
    /* map a PDPT at TEST_VADDR */
+    error = seL4_X86_PDPT_Map(pdpt, seL4_CapInitThreadVSpace, TEST_VADDR, seL4_X86_Default_VMAttributes);
+
+ +

All mapping functions take three arguments:

+
    +
  • the VSpace to map the object into,
    • +
  • the virtual address to map the object at,
    • +
  • and virtual memory attributes.
    • +
+ +

If the virtual memory address provided is not aligned to the size of the paging object, seL4 will mask out any +unused bits e.g a 4KiB page mapped at 0xDEADBEEF will end up mapped at 0xDEADB000.

+ +

Virtual memory attributes determine the caching attributes of the mapping, which is architecture dependent. +Alongside the attributes used in this tutorial (seL4_X86_Default_VMAttributes) you can find alternative values, in +libsel4.

+ +

Pages

+ +

Once all of the intermediate paging structures have been mapped for a specific virtual address range, +physical frames can be mapped into that range by invoking the frame capability. The code snippet below +shows an example of mapping a frame at address TEST_VADDR.

+ +
    /* map a read-only page at TEST_VADDR */
+    error = seL4_X86_Page_Map(frame, seL4_CapInitThreadVSpace, TEST_VADDR, seL4_CanRead, seL4_X86_Default_VMAttributes);
+
+ +

For a page mapping to succeed, all mid-level paging structures must be mapped. The libsel4 function +seL4_MappingFailedLookupLevel() can be used to determine at which level paging structures are missing. +Note that to map a frame multiple times, one must make copies of the frame capability: each frame capability +can only track one mapping.

+ +

In addition to the arguments taken by the map methods for intermediate paging structures, page mapping takes a +rights argument which determines the mapping type. In the example above, we map the page read only.

+ +

Types and sizes

+ +

Page types and sizes are architecture dependent. For both x86 and ARM architectures, +each size of page is a different object type with a specific size. +On RISC-V, pages are the same object type and variably sized. +Configuration and hardware settings alter the available page sizes.

+ +

Exercises

+ +

This tutorial uses several helper functions to allocate objects and capabilities. All object and +CSlot allocations have already been done for you using these functions. For more information see the +on these mechanisms, see the capabilities and untyped tutorials.

+ +

Map a page directory

+ +

On starting the tutorial, you will see the following output:

+
Missing intermediate paging structure at level 30
+main@main.c:34 [Cond failed: error != seL4_NoError]
+	Failed to map page
+
+

This is because while the provided code maps in a seL4_PDPT object, there are two missing levels of +paging structures. The value corresponds to the libsel4 constant SEL4_MAPPING_LOOKUP_NO_PD which is +the number of bits in the virtual address that could not be resolved due to missing paging structures.

+ +

Exercise Map in the pd structure using (seL4_PageDirectory_Map)[/projects/sel4/api-doc.html#map-5].

+ +
    // TODO map a page directory object
+
+ +
+ Quick solution + + 
    error = seL4_X86_PageDirectory_Map(pd, seL4_CapInitThreadVSpace, TEST_VADDR, seL4_X86_Default_VMAttributes);
+    assert(error == seL4_NoError);
+
+
+ +

On success, you should see the following:

+
Missing intermediate paging structure at level 21
+main@main.c:34 [Cond failed: error != seL4_NoError]
+	Failed to map page
+
+ +

Map a page table

+ +

Note that in the above output, the number of failed bits has changed from 30 to 21: this is because another +9 bits could be resolved from the newly mapped page directory.

+ +

Exercise Map in the pt structure using seL4_PageTable_Map.

+ +
    // TODO map a page table object
+
+ +
+ Quick solution + + 
    // map a page table object
+    error = seL4_X86_PageTable_Map(pt, seL4_CapInitThreadVSpace, TEST_VADDR, seL4_X86_Default_VMAttributes);
+    assert(error == seL4_NoError);
+
+
+ +

On success, you should see the following:

+
Read x: 0
+Set x to 5
+Caught cap fault in send phase at address (nil)
+while trying to handle:
+vm fault on data at address 0xa000000000 with status 0x7
+in thread 0xffffff801ffb5400 "rootserver" at address 0x401afe
+With stack:
+0x41c920: 0x41c9d0
+...
+
+ +

The page is successfully mapped and we read a value of 0: as seL4 zeros all non-device pages when they are retyped from +untyped memory. However, then the code attempts to write to the page. Since you mapped the page as read-only, this fails +and the kernel raises a VM fault.

+ +

Since the initial task does not have a fault handler (more details in the upcoming +threads tutorial), this triggers a subsequent capability fault (cap fault) on slot 0 (nil). Because you are running a +debug kernel for the tutorial, the kernel outputs the details of both faults.

+ +

The vm fault is the most interesting: it shows the fault address, fault status register, and the instruction pointer +that the fault occured on (address).

+ +

Remap a page

+ +

Exercise Fix the fault by remapping the page with seL4_ReadWrite permissions, using the +seL4_X86_Page_Map invocation.

+
    // TODO remap the page
+
+ +
+ Quick solution + + 
    error = seL4_X86_Page_Map(frame, seL4_CapInitThreadVSpace, TEST_VADDR, seL4_ReadWrite, seL4_X86_Default_VMAttributes);
+    assert(error == seL4_NoError);
+
+ +
+ +

Unmapping pages

+ +

Pages can be unmapped by either using Unmap invocations on the page or any intermediate paging structure, or deleting +the final capability to any of the paging structure.

+ +

Further exercises

+ +

That’s all for the detailed content of this tutorial. Below we list other ideas for exercises you can try, +to become more familiar with virtual memory management on seL4.

+ +
    +
  • Try unmapping the structures you just mapped in.
    • +
  • Port this tutorial to another architecture (ARM, RISCV).
    • +
  • Create a generic function for converting from seL4_MappingFailedLookupLevel to the required seL4 object.
    • +
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/mapping.md b/Tutorials/mapping.md deleted file mode 100644 index 604cc4c8fbf..00000000000 --- a/Tutorials/mapping.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Mapping -tutorial: mapping -layout: tutorial -description: virtual memory in seL4 -nav_prev: untyped.html -nav_next: threads.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/mcs.html b/Tutorials/mcs.html new file mode 100644 index 00000000000..0af8548afcd --- /dev/null +++ b/Tutorials/mcs.html @@ -0,0 +1,1041 @@ + + + + + + + MCS | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

MCS Extensions

+ +

This tutorial presents the features in the Mixed-Criticality System (MCS) extensions for seL4, which are currently undergoing +verification. For further context on the new features, please see the +paper or phd + which provides a comprehensive background on the changes.

+ +

Learn:

+
    +
  1. About the MCS new kernel API.
    2. +
  2. How to create and configure scheduling contexts.
    3. +
  3. The jargon passive server.
    4. +
  4. How to spawn round-robin and periodic threads.
    5. +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Hello world tutorial
    3. +
  3. Capabilities tutorial
    4. +
  4. Untyped tutorial
    5. +
  5. Mapping tutorial
    6. +
  6. Threads tutorial
    7. +
  7. IPC tutorial
    8. +
  8. Notifications tutorial
    9. +
  9. Interrupts tutorial
    10. +
  10. Fault handlers tutorial
    11. +
+ +

Initialising

+ +

Then initialise the tutorial:

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut mcs
+# building the tutorial exercise
+cd mcs_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut mcs
+# building the tutorial exercise
+cd mcs_build
+ninja
+
+ +
+ +

Background

+ +

The MCS extensions provide capability-based access to CPU time, and provide mechanisms to limit the upper +bound of execution of a thread.

+ +

Scheduling Contexts

+ +

Scheduling contexts are a new object type in the kernel, which contain scheduling parameters amoung other +accounting details. Most importantly, scheduling contexts contain a budget and a period, which +represent an upper bound on execution time allocated: the kernel will enforce that threads cannot execute +for more than budget microseconds out of period microseconds.

+ +

SchedControl

+ +

Parameters for scheduling contexts are configured by invoking seL4_SchedControl capabilities, one of +which is provided per CPU. The invoked seL4_SchedControl determines which processing core that specific +scheduling context provides access to.

+ +

Scheduling contexts can be configured as full or partial. Full scheduling contexts have budget == +period and grant access to 100% of CPU time. Partial scheduling contexts grant access to an upper bound of + budget/period CPU time.

+ +

The code example below configures a +scheduling context with a budget and period both equal to 1000us. Because the budget and period are equal, +the scheduling context is treated as round-robin

+ +
    error = seL4_SchedControl_Configure(sched_control, sched_context, US_IN_S, US_IN_S, 0, 0);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to configure schedcontext");
+
+ +

SchedContext Binding

+ +

Thread control blocks (TCBs) must have a scheduling context configured with non-zero budget and period + in order to be picked by the scheduler. This +can by invoking the scheduling context capability with the seL4_SchedContext_Bind invocation, or by +using seL4_TCB_SetSchedParams, which takes a scheduling context capability. Below is example code for +binding a TCB and a scheduling context.

+ +
    error = seL4_SchedContext_Bind(sched_context, spinner_tcb);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to bind sched_context to round_robin_tcb");
+
+ +

TCB’s can only be bound to one scheduling context at a time, and vice versa. If a scheduling context has not +been configured with any time, then although the TCB has a scheduling context it will remain ineligible +for scheduling.

+ +

Bounding execution

+ +

For partial scheduling contexts, an upper bound on execution is enforced by seL4 using the sporadic server +algorithm, which work by guaranteeing the sliding window constrain, meaning that during any period, the +budget cannot be exceeded. This is achieved by tracking the eligible budget in chunks called +replenishments (abbreviated to refills in the API for brevity). A replenishment is simply an amount + of time, and a timestamp from which that time can be consumed. We explain this now through an example:

+ +

Consider a scheduling context with period T and budget C. Initially, the scheduling context has +a single replenishment of size C which is eligible to be used from time t.

+ +

The scheduling context is scheduled at time t and blocks at time t + n. A new replenishment is then scheduled +for time t+T for n. The existing replenishment is updated to C - n, subtracting the amount consumed. +For further details on the sporadic server algorithm, see the +original paper.

+ +

If the replenishment data structure is full, replenishments are merged and the upper bound on execution is +reduced. For this reason, the bound on execution is configurable with the extra_refills parameter +on scheduling contexts. By default, scheduling contexts contain only two parameters, meaning if a +scheduling context is blocked, switched or preempted more than twice, the rest of the budget is forfeit until +the next period. extra_refills provides more replenishment data structures in a scheduling context. Note +that the higher the number of replenishments the more fragmentation of budget can occur, which will increase +scheduling overhead.

+ +

extra_refills itself is bounded by the size of a scheduling context, which is itself configurable. +On scheduling context creation a size can be specified, and must be > seL4_MinSchedContextBits. The +maximum number of extra refills that can fit into a specific scheduling context size can be calculated +with the function seL4_MaxExtraRefills() provided in libsel4.

+ +

Threads bound to scheduling contexts that do not have an available replenishment are placed into an ordered +queue of threads, and woken once their next replenishment is ready.

+ +

Scheduler

+ +

The seL4 scheduler is largely unchanged: the highest priority, non-blocked thread with a configured + scheduling context that has available budget is chosen by the scheduler to run.

+ +

Passive servers

+ +

The MCS extensions allow for RPC style servers to run on client TCBs’ scheduling contexts. This is achived by +unbinding the scheduling context once a server is blocked on an endpoint, rendering the server passive. +Caller scheduling contexts are donated to the server on seL4_Call and returned on seL4_ReplyRecv.

+ +

Passive servers can also receive scheduling contexts from their bound notification object, which is +achieved by binding a notification object using seL4_SchedContext_Bind.

+ +

Timeout faults

+ +

Threads can register a timeout fault handler using seL4_TCB_SetTimeoutEndpoint. Timeout fault +handlers are optional and are raised when a thread’s replenishment expires and they have a valid handler +registered. The timeout fault message from the kernel contains the data word which can be used to identify the +scheduling context that the thread was using when the timeout fault occurred, and the amount of time +consumed by the thread since the last fault or seL4_SchedContext_Consumed.

+ +

New invocations

+ +
    +
  • seL4_SchedContext_Bind - bind a TCB or Notification capability to the invoked scheduling context.
    • +
  • seL4_SchedContext_Unbind - unbind any objects from the invoked scheduling context.
    • +
  • seL4_SchedContext_UnbindObject- unbind a specific object from the invoked scheduling context.
    • +
  • seL4_SchedContext_YieldTo - if the thread running on the invoked scheduling context is +schedulable, place it at the head of the scheduling queue for its priority. For same priority threads, this +will result in the target thread being scheduled. Return the amount of time consumed by this scheduling +context since the last timeout fault, YieldTo or Consumed invocation.
    • +
  • seL4_SchedContext_Consumed - Return the amount of time consumed by this scheduling +context since the last timeout fault, YieldTo or Consumed invocation.
    • +
  • seL4_TCB_SetTimeoutEndpoint - Set the timeout fault endpoint for a TCB.
    • +
+ +

Reply objects

+ +

The MCS API also makes the reply channel explicit: reply capabilities are now fully fledged objects +which must be provided by a thread on seL4_Recv operations. They are used to track the scheduling +context donation chain and return donated scheduling contexts to callers.

+ +

Please see the release notes and +manual for further details + on the API changes.

+ +

Exercises

+ +

In the initial state of the tutorial, the main function in mcs.c is running in one process, and the +following loop from spinner.c is running in another process:

+ +
    int i = 0;
+    while (1) {
+        printf("Yield\n");
+        seL4_Yield();
+    }
+
+ +

Both processes share the same priority. The code in mcs.c binds +a scheduling context (sched_context) to the TCB of the spinner process (spinner_tcb) with round-robin scheduling parameters. As a result, you should see + something like the following output, which continues uninterrupted:

+ +
Yield
+Yield
+Yield
+
+ +

Periodic threads

+ +

Exercise Reconfigure sched_context with the following periodic scheduling parameters, + (budget = 0.9 * US_IN_S, period = 1 * US_IN_S).

+ +
    //TODO reconfigure sched_context to be periodic
+
+ +
+ Quick solution + + 
    // reconfigure sched_context to be periodic
+    error = seL4_SchedControl_Configure(sched_control, sched_context, 0.9 * US_IN_S, 1 * US_IN_S, 0, 0);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to configure schedcontext");
+
+
+ +

By completing this task successfully, the output will not change, but the rate that the output is +printed will slow: each subsequent line should be output once the period has elapsed. You should now +be able to see the loop where the mcs.c process and spinner.c process alternate, until the mcs.c +process blocks, at which point "Yield" is emitted by spinner.c every second, as shown below:

+ +
Yield
+Tick 0
+Yield
+Tick 1
+Yield
+Tick 2
+Yield
+Tick 3
+Yield
+Tick 4
+Yield
+Tick 5
+Yield
+Tick 6
+Yield
+Tick 7
+Yield
+Tick 8
+Yield
+Yield
+Yield
+
+ +

Before you completed this task, the scheduling context was round-robin, and so was +schedulable immediately after the call to seL4_Yield. +By changing +the scheduling parameters of sched_context to periodic parameters (budget < period), each time +seL4_Yield() is called the available budget in the scheduling context is abandoned, causing the +thread to sleep until the next replenishment, determined by the period.

+ +

Unbinding scheduling contexts

+ +

You can cease a threads execution by unbinding the scheduling context. +Unlike suspending a thread via seL4_TCB_Suspend, unbinding will not change the thread state. Using suspend +cancels any system calls in process (e.g IPC) and renders the thread unschedulable by changing the +thread state. Unbinding a scheduling context does not alter the thread state, but merely removes the thread +from the scheduler queues.

+ +

Exercise Unbind sched_context to stop the spinner process from running.

+ +
    //TODO unbind sched_context to stop yielding thread
+
+ +
+ Quick solution + + 
    // unbind sched_context to stop the yielding thread
+    error = seL4_SchedContext_Unbind(sched_context);
+    ZF_LOGF_IF(error, "Failed to unbind sched_context");
+
+ +
+ +

On success, you should see the output from the yielding thread stop.

+ +

Sporadic threads

+ +

Your next task is to use a different process, sender to experiment with sporadic tasks. The +sender process is ready to run, and just needs a scheduling context in order to do so.

+ +

Exercise First, bind sched_context to sender_tcb.

+ +
    //TODO bind sched_context to sender_tcb
+
+
+ Quick solution + + 
    // bind sched_context to sender_tcb
+    error = seL4_SchedContext_Bind(sched_context, sender_tcb);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to bind schedcontext");
+
+ +
+ +

The output should look like the following:

+
...
+Tock 3
+Tock 4
+Tock 5
+Tock 6
+
+ +

Note the rate of the output: currently, you should see 2 lines come out at a time, with roughly +a second break between (the period of the scheduling context you set earlier). This is because +scheduling context only has the minimum sporadic refills (see background), and each time a context switch +occurs a refill is used up to schedule another.

+ +

Exercise Reconfigure the sched_context to an extra 6 refills, such that all of the Tock output +occurs in one go.

+ +
    //TODO reconfigure sched_context to be periodic with 6 extra refills
+
+
+ Quick solution + + 
    // reconfigure sched_context to be periodic with 6 extra refills
+    error = seL4_SchedControl_Configure(sched_control, sched_context, 0.9 * US_IN_S, 1 * US_IN_S, 6, 0);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to configure schedcontext");
+
+ +
+ +

Passive servers

+ +

Now look to the third process, server.c, which is a very basic echo server. It currently does +not have a scheduling context, and needs one to initialise.

+ +

Exercise Bind sched_context to server_tcb.

+ +
    //TODO bind sched_context to server_tcb
+
+
+ Quick solution + + 
    // bind the servers sched context
+    error = seL4_SchedContext_Bind(sched_context, server_tcb);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to bind sched_context to server_tcb");
+
+ +
+ +

Now you should see the server initialise and echo the messages sent. Note the initialisation protocol: +first, you bound sched_context to the server. At this point, in server.c, the server calls +seL4_NBSendRecv which sends an IPC message on endpoint, indicating that the server is now initialised. +The output should be as follows

+ +
Tock 8
+Starting server
+Wait for server
+Server initialising
+running
+passive
+echo server
+Yield
+
+ +

The following code then converts the server to passive:

+ +
    // convert to passive
+    error = seL4_SchedContext_Unbind(sched_context);
+
+ +

From this point, the server runs on the mcs process’s scheduling context.

+ +

Timeout Faults

+ +

But before we discuss timeout faults, we must first discuss the differences +between configuring a fault endpoint on the master vs the MCS kernel. There is a +minor difference in the way that the kernel is informed of the cap to a fault +endpoint, between the master and MCS kernels.

+ +

Regardless though, on both versions of the kernel, to inform the kernel of the +fault endpoint for a thread, call the usual seL4_TCB_SetSpace().

+ +

Configuring a fault endpoint on the MCS kernel:

+ +

On the MCS kernel the cap given to the kernel must be a cap to an object in +the CSpace of the thread which is calling the syscall (seL4_TCB_Configure()) +to give the cap to the kernel.

+ +

This calling thread may be the handler thread, or some other thread which +manages both the handler thread and the faulting thread. Or in an oddly designed +system, it might be the faulting thread itself if the faulting thread is allowed +to configure its own fault endpoint.

+ +

The reason for this difference is merely that it is faster to lookup the fault +endpoint this way since it is looked up only once at the time it is configured.

+ +

Configuring a fault endpoint on the Master kernel

+ +

On the Master kernel the cap given to the kernel must be a cap to an object in +the CSpace of the faulting thread.

+ +

On the Master kernel, the fault endpoint cap is looked up from within the CSpace +of the faulting thread everytime a fault occurs.

+ +

Exercise

+ +

Exercise Set the data field of sched_context using seL4_SchedControl_Configure and set a 10s period, 1ms +budget and 0 extra refills.

+ +
    //TODO reconfigure sched_context with 10s period, 1ms budget, 0 extra refills and data of 5.
+
+ +
+ Quick solution + + 

+    // reconfigure sched_context with 1s period, 500 microsecond budget, 0 extra refills and data of 5.
+    error = seL4_SchedControl_Configure(sched_control, sched_context, 500, US_IN_S, 0, 5);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to configure sched_context");
+
+ +
+ +

The code then binds the scheduling context back to spinner_tcb, which starts yielding again.

+ +

Exercise set the timeout fault endpoint for spinner_tcb.

+ +
    //TODO set endpoint as the timeout fault handler for spinner_tcb
+
+
+ Quick solution + + 
    // set endpoint as the timeout fault handler for spinner_tcb
+    error = seL4_TCB_SetTimeoutEndpoint(spinner_tcb, endpoint);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to set timeout fault endpoint for spinner");
+
+ +
+ +

When the spinner faults, you should see the following output:

+ +
Received timeout fault
+Success!
+
+ +

Further exercises

+ +

That’s all for the detailed content of this tutorial. Below we list other ideas for exercises you can try, +to become more familiar with the MCS extensions.

+ +
    +
  • Set up a passive server with a timeout fault handlers, with policies for clients that exhaust their budget.
    • +
  • Experiment with notification binding on a passive server, by binding both a notification object to the +server TCB and an SC to the notification object.
    • +
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/mcs.md b/Tutorials/mcs.md deleted file mode 100644 index 431a4f361ad..00000000000 --- a/Tutorials/mcs.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: MCS -tutorial: mcs -layout: tutorial -description: An introduction to the seL4 MCS extensions. -nav_prev: fault-handlers.html -nav_next: seL4-end.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/notifications.html b/Tutorials/notifications.html new file mode 100644 index 00000000000..4bf94a49bcb --- /dev/null +++ b/Tutorials/notifications.html @@ -0,0 +1,828 @@ + + + + + + + Notifications | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Notifications and shared memory

+ +

This tutorial covers notification objects.

+ +

You will learn how to:

+
    +
  1. Set up shared memory between tasks.
    2. +
  2. Use notification objects for synchronisation between tasks.
    3. +
  3. Use badges to differentiate notifications.
    4. +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Capabilities tutorial
    3. +
  3. Mapping tutorial
    4. +
  4. Threads tutorial
    5. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut notifications
+# building the tutorial exercise
+cd notifications_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut notifications
+# building the tutorial exercise
+cd notifications_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

capDL Loader

+ +

This tutorial uses the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +
+ Get capDL +

The capDL loader parses +a static description of the system and the relevant ELF binaries. +It is primarily used in CAmkES projects +but we also use it in the tutorials to reduce redundant code. +The program that you construct will end up with its own CSpace and VSpace, which are separate +from the root task, meaning CSlots like seL4_CapInitThreadVSpace have no meaning +in applications loaded by the capDL loader.

+ +

More information about capDL projects can be found here.

+ +

For this tutorial clone the capDL repo. This can be added in a directory that is adjacent to the main tutorials directory.

+
+ +

Background

+ +

Notifications allow processes to send asynchronous signals to each other, and are primarily used for interrupt handling +and to synchronise access to shared data buffers.

+ +

Notification objects

+ +

Signals are sent and received with invocations on capabilities to notification objects. +A notification object consists of a data word, which acts as an array of binary semaphores, and a queue of +TCBs waiting for notifications.

+ +

Notification objects can be in three states:

+
    +
  • Waiting - there are TCBs queued on this notification waiting for it to be signalled.
    • +
  • Active - TCBs have signalled data on this notification,
    • +
  • Idle - no TCBs are queued and no TCBs have signalled this object since it was last set to idle.
    • +
+ +

Signalling

+ +

When a task signals a notification object (using seL4_Signal), what occurs depends on the state of the object:

+
    +
  • Idle - the data word is set to the badge of the capability used to send the signal, and the object is converted + to active.
    • +
  • Active - the badge of the capability used to signal the notification object is bitwise-orred with the notifications data word.
    • +
  • Waiting - the head of the queue of TCBs is woken and the badge sent to that TCB. If the queue is empty, the notification +object is transitioned to idle.
    • +
+ +

In this way notification objects can be seen as a binary array of semaphores - if the signallers all use a +different bit in the badge, they can set different badge bits and waiters can observe which bits have been set.

+ +

Waiting

+ +

Tasks can wait on a notification object using seL4_Wait, which does the following:

+ +
    +
  • Idle - the TCB is queued, and the notification transitioned to waiting.
    • +
  • Active - the TCB receives the data word, the data word is reset to 0 and the notification transitioned to idle,
    • +
  • Waiting - the TCB is appended to the queue.
    • +
+ +

Polling

+ +

Notification objects can also be polled with seL4_Poll, which is a non-blocking version of seL4_Wait that returns +immediately regardless of the state.

+ +

Interrupts and IPC

+ +

Notification objects can be used to receive signals of interrupt delivery, and can also be bound to TCBs +such that signals and IPC can be received by the same thread. This is explained in more detail in the +timer tutorial.

+ +

Exercises

+ +

These exercises guide you through a basic producer consumer set up using notifications and shared memory. The +tutorial uses the capDL loader, and already has 2 producer processes (producer_1.c and producer_2) and 1 consumer + process running (consumer.c). Each has access to a number of capabilities.

+ +

Each producer shares a buffer with the consumer, and the consumer processes data from both producers when it is +available.

+ +

When you start the tutorial, the output will look something like this:

+
Booting all finished, dropped to user space
+Waiting for producer
+
+

Set up shared memory

+ +

Both producers start and block immediately, waiting for the consumer to send an IPC with the address of the shared +mapping. We provide code below that sets up the shared page between producer 1 and the consumer:

+ +
    /* set up shared memory for consumer 1 */
+    /* first duplicate the cap */
+    error = seL4_CNode_Copy(cnode, mapping_1, seL4_WordBits,
+                          cnode, buf1_frame_cap, seL4_WordBits, seL4_AllRights);
+    ZF_LOGF_IFERR(error, "Failed to copy cap");
+    /* now do the mapping */
+    error = seL4_ARCH_Page_Map(mapping_1, producer_1_vspace, BUF_VADDR,
+                               seL4_AllRights, seL4_ARCH_Default_VMAttributes);
+    ZF_LOGF_IFERR(error, "Failed to map frame");
+
+ +

However, we do not map the second buffer in, so producer 2 crashes immediately.

+ +

Exercise Understand the above code, and create a second shared page between producer_2 and consumer.

+ +
    // TODO share buf2_frame_cap with producer_2
+
+
+
+ Quick solution + + 
    /* set up shared memory for producer 2 */
+    error = seL4_CNode_Copy(cnode, mapping_2, seL4_WordBits,
+                            cnode, buf2_frame_cap, seL4_WordBits, seL4_AllRights);
+    ZF_LOGF_IFERR(error, "Failed to copy cap");
+   /* now do the mapping */
+    error = seL4_ARCH_Page_Map(mapping_2, producer_2_vspace, BUF_VADDR,
+                               seL4_AllRights, seL4_ARCH_Default_VMAttributes);
+    ZF_LOGF_IFERR(error, "Failed to map frame");
+
+
+ +

Whether this is successful will be visible after the next exercise when the consumers access their buffers. If the shared page setup for producer 2 is not correct, it will fail with a vm fault.

+ +

Signal the producers to go

+ +

At this point, both producers are waiting on the empty notification for a signal that the buffer is ready +to be written to.

+ +

Exercise signal both producers via the buf1_empty and buf2_empty notification objects.

+ +
    // TODO signal both producers
+
+
+ Quick solution + + 
    seL4_Signal(buf1_empty);
+    seL4_Signal(buf2_empty);
+
+
+ +

Differentiate signals

+ +

Now you should see something like the following:

+ +
Booting all finished, dropped to user space
+Waiting for producer
+2: produce
+1: produce
+Got badge: 2
+Got badge: 1
+
+ +

At this point, the consumer should consume data from the appropriate buffer(s) and signal to the appropriate consumer(s) +that the buffer is empty again. The capability to the full notification object has already been badged: producer_1s +copy has a badge of 0b1 and producer_2 a badge of 0b10. By checking the bits in the badge, you can see +which of the producers (it may be both) has produced data.

+ +

Exercise Check the badge and signal the empty notification for the producers according to the bits set in the badge + value.

+ +
    // TODO, use the badge to check which producer has signalled you, and signal it back. Note that you
+    // may recieve more than 1 signal at a time.
+
+
+
+ Quick solution + + 
        if (badge & 0b01) {
+            assert(*buf1 == 1);
+            *buf1 = 0;
+            seL4_Signal(buf1_empty);
+        }
+        if (badge & 0b10) {
+            assert(*buf2 == 2);
+            *buf2 = 0;
+            seL4_Signal(buf2_empty);
+        }
+
+
+ +

At this point, you should see signals from both producers being processed, and the final Success! message printed.

+ +

Further exercises

+ +

That’s all for the detailed content of this tutorial. Below we list other ideas for exercises you can try, +to become more familiar with IPC.

+ +
    +
  • Create a counting semaphore implementation using notification objects.
    • +
  • Create a bounded-buffer producer consumer with a buffer size greater than 1.
    • +
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/notifications.md b/Tutorials/notifications.md deleted file mode 100644 index 49f54183149..00000000000 --- a/Tutorials/notifications.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Notifications -tutorial: notifications -layout: tutorial -description: using notification objects and signals -nav_prev: ipc.html -nav_next: interrupts.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/pathways.html b/Tutorials/pathways.html new file mode 100644 index 00000000000..f985becebd8 --- /dev/null +++ b/Tutorials/pathways.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/Tutorials/pathways.md b/Tutorials/pathways.md deleted file mode 100644 index cb192ad520b..00000000000 --- a/Tutorials/pathways.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: /Tutorials/index.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/Tutorials/seL4-end.html b/Tutorials/seL4-end.html new file mode 100644 index 00000000000..78bc96ac7b1 --- /dev/null +++ b/Tutorials/seL4-end.html @@ -0,0 +1,720 @@ + + + + + + + End of the seL4 Tutorial | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+

End of the seL4 Tutorial

+ +

That’s all for the seL4 kernel tutorial.

+ +

You might want to check out some of the following tutorials as well.

+ +
+
+ +
+ +
+ +
+ +
+ +
+

+ Microkit tutorial +

+
+ Tutorial on building static systems on Microkit. Building a simple Wordle server with drivers and a VM. +
+
+ Learn more + + +
+
+
+ +
+ +
+ +
+ + + + + + + + + +
+ +
+ +
+

+ C library tutorials +

+
+ Tutorials on the no-assurance C prototyping libraries for seL4. Initialisation, threading, ELF loading. +
+
+ Learn more + + +
+
+
+ +
+ +
+ +
+ + + + + + + + +
+ +
+ +
+

+ Rust on seL4 tutorial +

+
+ Tutorial on running the Rust language on seL4. +
+
+ Learn more + + +
+
+
+ +
+ +
+ +
+ +
+ +
+ +
+

+ CAmkES tutorial +

+
+ Tutorials for the CAmkES component framework. +
+
+ Learn more + + +
+
+
+ +
+ +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/seL4-end.md b/Tutorials/seL4-end.md deleted file mode 100644 index 3551f27d2f6..00000000000 --- a/Tutorials/seL4-end.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -layout: tutorial -nav_prev: mcs.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# End of the seL4 Tutorial - -## That's all for the seL4 kernel tutorial. - -You might want to check out some of the following tutorials as well. - -
- {% include card.html - icon="puzzle-piece" - title="Microkit tutorial" - body="Tutorial on building static systems on Microkit. Building a simple Wordle server with drivers and a VM." - link="/projects/microkit/tutorial/welcome.html" - %} - {% include card.html - icon="other/C" - title="C library tutorials" - body="Tutorials on the no-assurance C prototyping libraries for seL4. Initialisation, threading, ELF loading." - link="/Tutorials/libraries-1.html" - %} - {% include card.html - icon="other/rust-logo-blk" - title="Rust on seL4 tutorial" - body="Tutorial on running the Rust language on seL4." - link="/projects/rust/tutorial/introduction.html" - %} - {% include card.html - icon="puzzle-piece" - title="CAmkES tutorial" - body="Tutorials for the CAmkES component framework." - link="/Tutorials/hello-camkes-0.html" - %} -
diff --git a/Tutorials/setting-up.html b/Tutorials/setting-up.html new file mode 100644 index 00000000000..e68ccadd820 --- /dev/null +++ b/Tutorials/setting-up.html @@ -0,0 +1,712 @@ + + + + + + + Setting up your machine | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+

Setting up your machine

+ +

Welcome to the seL4 tutorials!

+ +

The first step is to set up your machine with the development tools that the +tutorials will use.

+ +

Google’s Repo tool

+ +

The primary way of obtaining and managing seL4 project sources is through the use of Google’s Repo tool.

+ +

To install run:

+
  sudo apt-get update
+  sudo apt-get install repo
+
+ +
+ More on Repo + +

More details about on installing Repo.

+ +

seL4 Repo cheatsheet

+
+ +

Docker

+ +

To compile and use seL4, it is recommended that you use Docker to isolate the dependencies from your machine.

+ +

These instructions assume you are using Debian (or a derivative, such as Ubuntu), and are using Bash for your shell. However, it should be informative enough for users of other distros/shells to adapt.

+ +

These instructions are intended for Ubuntu LTS versions 20.04 and 22.04.

+ +

To begin, you will need at least these two programs:

+ + + +

For convenience, add your account to the docker group:

+ +
sudo usermod -aG docker $(whoami)
+
+ +
+ More on Docker + +

Available images

+ +

All the prebuilt docker images are available on DockerHub here

+ +

These images are used by the Trustworthy Systems Continuous Integration (CI) software, and so represent a standard software setup we use. + The CI software always uses the latest docker image, but images are also tagged with the date they were built.

+ +

More information

+ +

You can find the dockerfiles and supporting Makefile here

+ +
+ +

Getting a build environment

+

To get a running build environment for seL4 and CAmkES, run:

+ +
git clone https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles.git
+cd seL4-CAmkES-L4v-dockerfiles
+make user
+
+ +

This will give you a terminal inside a container that has all the relevant tools to build, simulate, and test seL4 & CAmkES programs.

+ +

The first time you run this, docker will fetch the relevant images, which may take a while.

+ +

The last line will say something like:

+ +
Hello, welcome to the seL4/CAmkES/L4v docker build environment
+
+ +

Mapping a container

+

To run the container from other directories (e.g. starting a container for the Hello World tutorial, which we’ll do next), you can setup a bash alias such as this:

+ +
echo $'alias container=\'make -C /<path>/<to>/seL4-CAmkES-L4v-dockerfiles user HOST_DIR=$(pwd)\'' >> ~/.bashrc
+# now open a new terminal, or run `source ~/.bashrc`
+
+ +

Replace /<path>/<to>/ to match where you cloned the git repo of the docker files.

+ +

Reminder: Include the absolute path to your seL4-CAmkES-L4v-dockerfiles folder, e.g.

+ +
echo $'alias container=\'make -C /~/seL4-CAmkES-L4v-dockerfiles user HOST_DIR=$(pwd)\'' >> ~/.bashrc
+# now open a new terminal, or run `source ~/.bashrc`
+
+
+ +

This then allows you to run container from any directory.

+ +

Reminder: start a new terminal for the changes in .bashrc to take effect or run source ~/.bashrc.

+ +

An example workflow

+ +

A good workflow is to run two terminals:

+ +
    +
  • Terminal A is just a normal terminal, and is used for git operations, editing (e.g., vim, emacs, vscode), and other non-build operations.
    • +
  • Terminal B is running in a container, and is only used for compilation.
    • +
+ +

This gives you the flexibility to use all the normal tools you are used to, while having the seL4 dependencies separated from your machine.

+ +

Compiling seL4 test

+ +

Start two terminals (terminal A and terminal B).

+ +

In terminal A, run these commands:

+ +
jblogs@host:~$ mkdir ~/seL4test
+jblogs@host:~$ cd ~/seL4test
+jblogs@host:~/seL4test$ repo init -u https://github.com/seL4/seL4test-manifest.git
+jblogs@host:~/seL4test$ repo sync
+
+ +

In terminal B, run these commands:

+ +
jblogs@host:~$ cd ~/seL4test
+jblogs@host:~/seL4test$ container  # using the bash alias defined above
+jblogs@in-container:/host$ mkdir build-x86
+jblogs@in-container:/host$ cd build-x86
+jblogs@in-container:/host/build-x86$ ../init-build.sh -DPLATFORM=x86_64 -DSIMULATION=TRUE
+jblogs@in-container:/host/build-x86$ ninja
+jblogs@in-container:/host/build-x86$ ./simulate
+
+ +

If you need to make any code modifications or commit things to git, use terminal A. If you need to recompile or simulate an image, use terminal B.

+ +

./simulate is run using QEMU, and will take a few minutes to run. If QEMU works, you’ll see something like

+ +
Test suite passed. 121 tests passed. 57 tests disabled.
+All is well in the universe
+
+ +

Note, if QEMU fails when trying to simulate the image, try configuring your Docker host to give the container more memory using Docker Desktop.

+ +

That’s it! seL4 is running.

+ +

To quit QEMU: Ctrl+a, x

+ +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/setting-up.md b/Tutorials/setting-up.md deleted file mode 100644 index 5acb134508f..00000000000 --- a/Tutorials/setting-up.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -layout: tutorial -description: guide to machine set-up for tutorials -nav_next: get-the-tutorials.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Setting up your machine - -## Welcome to the seL4 tutorials! - -The first step is to set up your machine with the development tools that the -tutorials will use. - -## Google's Repo tool - -The primary way of obtaining and managing seL4 project sources is through the use of Google's Repo tool. - -To install run: -```sh - sudo apt-get update - sudo apt-get install repo -``` - -
-More on Repo - -[More details about on installing Repo](https://gerrit.googlesource.com/git-repo#install). - -[seL4 Repo cheatsheet](../projects/buildsystem/repo-cheatsheet.html) -
- -## Docker - -To compile and use seL4, it is recommended that you use Docker to isolate the dependencies from your machine. - -These instructions assume you are using Debian (or a derivative, such as Ubuntu), and are using Bash for your shell. However, it should be informative enough for users of other distros/shells to adapt. - -These instructions are intended for Ubuntu LTS versions 20.04 and 22.04. - -To begin, you will need at least these two programs: - - * make (`sudo apt install make`) - * docker (See [Docker Engine - Installation](https://docs.docker.com/engine/installation) for installation - instructions or the [get.docker.com](https://get.docker.com) script. - You can also install [Docker Desktop](https://docs.docker.com/get-started/get-docker/)). - -For convenience, add your account to the docker group: - -```bash -sudo usermod -aG docker $(whoami) -``` - -
- More on Docker - - **Available images** - - All the prebuilt docker images are available on [DockerHub here](https://hub.docker.com/u/trustworthysystems) - - These images are used by the Trustworthy Systems Continuous Integration (CI) software, and so represent a standard software setup we use. - The CI software always uses the `latest` docker image, but images are also tagged with the date they were built. - - **More information** - - You can find the dockerfiles and supporting Makefile [here](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles) - -
- - -### Getting a build environment -To get a running build environment for seL4 and CAmkES, run: - -```bash -git clone https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles.git -cd seL4-CAmkES-L4v-dockerfiles -make user -``` - -This will give you a terminal inside a container that has all the relevant tools to build, simulate, and test seL4 & CAmkES programs. - -The first time you run this, docker will fetch the relevant images, which may take a while. - -The last line will say something like: - -``` -Hello, welcome to the seL4/CAmkES/L4v docker build environment -``` - -### Mapping a container -To run the container from other directories (e.g. starting a container for the [Hello World](hello-world.md) tutorial, which we'll do next), you can setup a bash alias such as this: - -```bash -echo $'alias container=\'make -C ///seL4-CAmkES-L4v-dockerfiles user HOST_DIR=$(pwd)\'' >> ~/.bashrc -# now open a new terminal, or run `source ~/.bashrc` -``` - -Replace `///` to match where you cloned the git repo of the docker files. - -*Reminder:* Include the absolute path to your `seL4-CAmkES-L4v-dockerfiles` folder, e.g. - -```bash -echo $'alias container=\'make -C /~/seL4-CAmkES-L4v-dockerfiles user HOST_DIR=$(pwd)\'' >> ~/.bashrc -# now open a new terminal, or run `source ~/.bashrc` - -``` - -This then allows you to run `container` from any directory. - -*Reminder:* start a new terminal for the changes in `.bashrc` to take effect or run `source ~/.bashrc`. - - -## An example workflow - -A good workflow is to run two terminals: - - - Terminal A is just a normal terminal, and is used for git operations, editing (e.g., vim, emacs, vscode), and other non-build operations. - - Terminal B is running in a container, and is only used for compilation. - -This gives you the flexibility to use all the normal tools you are used to, while having the seL4 dependencies separated from your machine. - -### Compiling seL4 test - -Start two terminals (terminal A and terminal B). - -In terminal A, run these commands: - -```bash -jblogs@host:~$ mkdir ~/seL4test -jblogs@host:~$ cd ~/seL4test -jblogs@host:~/seL4test$ repo init -u https://github.com/seL4/seL4test-manifest.git -jblogs@host:~/seL4test$ repo sync -``` - -In terminal B, run these commands: - -```bash -jblogs@host:~$ cd ~/seL4test -jblogs@host:~/seL4test$ container # using the bash alias defined above -jblogs@in-container:/host$ mkdir build-x86 -jblogs@in-container:/host$ cd build-x86 -jblogs@in-container:/host/build-x86$ ../init-build.sh -DPLATFORM=x86_64 -DSIMULATION=TRUE -jblogs@in-container:/host/build-x86$ ninja -jblogs@in-container:/host/build-x86$ ./simulate -``` - -If you need to make any code modifications or commit things to git, use terminal A. If you need to recompile or simulate an image, use terminal B. - -`./simulate` is run using [QEMU](https://www.qemu.org/), and will take a few minutes to run. If QEMU works, you'll see something like - -``` -Test suite passed. 121 tests passed. 57 tests disabled. -All is well in the universe -``` - -Note, if QEMU fails when trying to simulate the image, try configuring your Docker host to give the container more memory using [Docker Desktop](https://docs.docker.com/desktop/use-desktop/). - -That's it! seL4 is running. - -To quit QEMU: `Ctrl+a, x` diff --git a/Tutorials/threads.html b/Tutorials/threads.html new file mode 100644 index 00000000000..ba8bfa3eff6 --- /dev/null +++ b/Tutorials/threads.html @@ -0,0 +1,1131 @@ + + + + + + + Threads | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Threads

+

This is a tutorial for using threads on seL4.

+ +

In this tutorial, you will:

+
    +
  1. Learn the jargon TCB.
    2. +
  2. Learn how to start a thread in the same address space.
    3. +
  3. Learn how to read and update TCB register state.
    4. +
  4. Learn how to suspend and resume a thread.
    5. +
  5. Understand thread priorities and their interaction with the seL4 scheduler.
    6. +
  6. Gain a basic understanding of exceptions and debug fault handlers.
    7. +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Capabilities tutorial
    3. +
  3. Mapping tutorial
    4. +
+ +

capDL Loader

+ +

Previous tutorials have taken place in the root task where the starting CSpace layout is set by the +seL4 boot protocol. This tutorial uses the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +

The capDL loader parses +a static description of the system and the relevant ELF binaries. +It is primarily used in CAmkES projects +but we also use it in the tutorials to reduce redundant code. +The program that you construct will end up with its own CSpace and VSpace, which are separate +from the root task, meaning CSlots like seL4_CapInitThreadVSpace have no meaning +in applications loaded by the capDL loader.

+ +

More information about capDL projects can be found here.

+ +

For this tutorial clone the capDL repo. This can be added in a directory that is adjacent to the main tutorials directory.

+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut threads
+# building the tutorial exercise
+cd threads_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut threads
+# building the tutorial exercise
+cd threads_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

Background

+ +

Thread Control Blocks

+ +

seL4 provides threads to represent an execution context and manage processor time. Threads in +seL4 are realised by thread control block objects (TCBs), one for each kernel thread.

+ +

TCBs contain the following information:

+
    +
  • a priority and maximum control priority,
    • +
  • register state and floating-point context,
    • +
  • CSpace capability,
    • +
  • VSpace capability,
    • +
  • endpoint capability to send fault messages to,
    • +
  • and the reply capability slot.
    • +
+ +

Scheduling model

+ +

The seL4 scheduler chooses the next thread to run on a specific +processing core, and is a priority-based round-robin scheduler. The scheduler picks +threads that are runnable: that is, resumed, and not blocked on any IPC operation.

+ +

Priorities

+ +

The scheduler picks the highest-priority, runnable thread. seL4 provides a priority range of 0-255, where +255 is the maximum priority (encoded in libsel4 as seL4_MinPrio and seL4_MaxPrio).

+ +

TCBs also have a maximum control priority (MCP), which acts as an informal capability over priorities. +When setting the priority of a TCB, an explicit TCB capability must be provided to derive the +authority from to set the priority. The priority being set is checked against the authority TCB’s +MCP and the target priority is greater, the operation fails. The root task starts with both priority and +MCP set to seL4_MaxPrio.

+ +

Round robin

+ +

When multiple TCBs are runnable and have the same priority, they are scheduled in a +first-in, first-out round-robin fashion. In more detail, kernel time +is accounted for in fixed-time quanta referred to as ticks, and each TCB has +a timeslice field which represents the number of ticks that TCB is eligible to execute +until preempted. The kernel timer driver is configured to fire a periodic interrupt which +marks each tick, and when the timeslice is exhausted round robin scheduling is applied. +Threads can surrender their current timeslice using the seL4_Yield system call.

+ +

Domain scheduling

+ +

In order to provide confidentiality seL4 provides a top-level hierarchical scheduler which +provides static, cyclical scheduling of scheduling partitions known as domains. Domains are +statically configured at compile time with a cyclic schedule, and are non-preemptible resulting in +completely deterministic scheduling of domains.

+ +

Threads can be assigned to domains, and threads are only scheduled +when their domain is active. Cross-domain IPC is delayed until a domain switch, and +seL4_Yield between domains is not possible. When there are no threads to run while a +domain is scheduled, a domain-specific idle thread will run until a switch occurs.

+ +

Assigning a thread to a domain requires access to the seL4_DomainSet capability. This allows a +thread to be added to any domain.

+ +
/* Set thread's domain */
+seL4_Error seL4_DomainSet_Set(seL4_DomainSet _service, seL4_Uint8 domain, seL4_TCB thread);
+
+
+ +

Thread Attributes

+ +

seL4 threads are configured by invocations on the TCB object.

+ +

Exercises

+ +

This tutorial will guide you through using TCB invocations to create a new thread in the same +address space and pass arguments to the new thread. +Additionally, you will learn about how to debug a virtual memory +fault.

+ +

By the end of this tutorial you want to spawn a new thread to call the function in the code example + below.

+ +

+int new_thread(void *arg1, void *arg2, void *arg3) {
+    printf("Hello2: arg1 %p, arg2 %p, arg3 %p\n", arg1, arg2, arg3);
+    void (*func)(int) = arg1;
+    func(*(int *)arg2);
+    while(1);
+}
+
+
+ +

capDL Loader

+ +

Previous tutorials have taken place in the root task where the starting CSpace layout is set by the +seL4 boot protocol. This tutorial uses a the capDL loader, a root task which allocates statically + configured objects and capabilities.

+ +

The capDL loader parses +a static description of the system and the relevant ELF binaries. +It is primarily used in CAmkES projects +but we also use it in the tutorials to reduce redundant code. +The program that you construct will end up with its own CSpace and VSpace, which are separate +from the root task, meaning CSlots like seL4_CapInitThreadVSpace have no meaning +in applications loaded by the capDL loader.

+ +

Information about capDL projects can be found here.

+ +

Configure a TCB

+ +

When you first build and run the tutorial, you should see something like the following:

+
Hello, World!
+Dumping all tcbs!
+Name                                        State           IP                       Prio    Core
+--------------------------------------------------------------------------------------
+tcb_threads                                running         0x4012ef    254                 0
+idle_thread                                 idle            (nil)   0                   0
+rootserver                                  inactive        0x4024c2    255                 0
+<<seL4(CPU 0) [decodeInvocation/530 T0xffffff8008140c00 "tcb_threads" @4012ef]: Attempted to invoke a >
+main@threads.c:42 [Cond failed: result]
+Failed to retype thread: 2
+
+ +

Dumping all tcbs! and the following table is generated by a debug syscall called seL4_DebugDumpScheduler(). +seL4 has a series of debug syscalls that are available in debug kernel builds. The available debug syscalls +can be found in libsel4. seL4_DebugDumpScheduler() +is used to dump the current state of the scheduler and can be useful to debug situations where a +system seems to have hung.

+ +

After the TCB table, you can see the seL4_Untyped_Retype invocation is failing due to invalid arguments. +The loader has been configured to set up the following capabilities and symbols:

+ +

+// the root CNode of the current thread
+extern seL4_CPtr root_cnode;
+// VSpace of the current thread
+extern seL4_CPtr root_vspace;
+// TCB of the current thread
+extern seL4_CPtr root_tcb;
+// Untyped object large enough to create a new TCB object
+
+extern seL4_CPtr tcb_untyped;
+extern seL4_CPtr buf2_frame_cap;
+extern const char buf2_frame[4096];
+
+// Empty slot for the new TCB object
+extern seL4_CPtr tcb_cap_slot;
+// Symbol for the IPC buffer mapping in the VSpace, and capability to the mapping
+extern seL4_CPtr tcb_ipc_frame;
+extern const char thread_ipc_buff_sym[4096];
+// Symbol for the top of a 16 * 4KiB stack mapping, and capability to the mapping
+extern const char tcb_stack_base[65536];
+static const uintptr_t tcb_stack_top = (const uintptr_t)&tcb_stack_base + sizeof(tcb_stack_base);
+
+ +

Exercise Fix the seL4_Untyped_Retype call (shown below) using the capabilities provided above, such +that a new TCB object is created in tcb_cap_slot.

+ +
int main(int c, char* arbv[]) {
+
+    printf("Hello, World!\n");
+
+    seL4_DebugDumpScheduler();
+    // TODO fix the parameters in this invocation
+    seL4_Error result = seL4_Untyped_Retype(seL4_CapNull, seL4_TCBObject, seL4_TCBBits, seL4_CapNull, 0, 0, seL4_CapNull, 1);
+    ZF_LOGF_IF(result, "Failed to retype thread: %d", result);
+    seL4_DebugDumpScheduler();
+
+ +
+ Quick solution + + 
    seL4_Error result = seL4_Untyped_Retype(tcb_untyped, seL4_TCBObject, seL4_TCBBits, root_cnode, 0, 0, tcb_cap_slot, 1);
+    ZF_LOGF_IF(result, "Failed to retype thread: %d", result);
+    seL4_DebugDumpScheduler();
+
+
+ +

Once the TCB has been created it will show up in the seL4_DebugDumpScheduler() output as +child of: 'tcb_threads'. Throughout the tutorial you can use this syscall to debug some of the TCB attributes +that you set.

+ +

After the scheduler table, you should see a another error:

+ +
  <<seL4(CPU 0) [decodeInvocation/530 T0xffffff800813fc00 "tcb_threads" @4004bf]: Attempted to invoke a null cap #0.>>
+main@threads.c:46 [Cond failed: result]
+	Failed to configure thread: 2
+
+ +

Exercise Now that you have a TCB object, configure it to have the same CSpace and VSpace +as the current thread. Use the IPC buffer we have provided, but don’t set a fault handler, + as the kernel will print any fault we receive with a debug build.

+ +
    //TODO fix the parameters in this invocation
+    result = seL4_TCB_Configure(seL4_CapNull, seL4_CapNull, 0, seL4_CapNull, 0, 0, (seL4_Word) NULL, seL4_CapNull);
+    ZF_LOGF_IF(result, "Failed to configure thread: %d", result);
+
+ +
+ Quick solution + + 
    result = seL4_TCB_Configure(tcb_cap_slot, seL4_CapNull, root_cnode, 0, root_vspace, 0, (seL4_Word) thread_ipc_buff_sym, tcb_ipc_frame);
+    ZF_LOGF_IF(result, "Failed to configure thread: %d", result);
+
+ +
+ +

You should now be getting the following error:

+
<<seL4(CPU 0) [decodeSetPriority/1035 T0xffffff8008140c00 "tcb_threads" @4012ef]: Set priority: author>
+main@threads.c:51 [Cond failed: result]
+Failed to set the priority for the new TCB object.
+
+ +

Change priority via seL4_TCB_SetPriority

+ +

A newly created thread will have a priority of 0, while the thread created by the loader is at +a priority of 254. You need to change the priority of your new thread such that it will be + scheduled round-robin with the current thread.

+ +

Exercise use seL4_TCB_SetPriority to set the priority. Remember that to set a thread’s priority, +the calling thread must have the authority to do so. In this case, the main thread can use its own +TCB capability, which has an MCP of 254.

+ +
    // TODO fix the call to set priority using the authority of the current thread
+    // and change the priority to 254
+    result = seL4_TCB_SetPriority(tcb_cap_slot, seL4_CapNull, 0);
+    ZF_LOGF_IF(result, "Failed to set the priority for the new TCB object.\n");
+    seL4_DebugDumpScheduler();
+
+ +
+ Quick solution + + 
    result = seL4_TCB_SetPriority(tcb_cap_slot, root_tcb, 254);
+    ZF_LOGF_IF(result, "Failed to set the priority for the new TCB object.\n");
+    seL4_DebugDumpScheduler();
+
+
+ +

Fixing up the seL4_TCB_SetPriority call should allow you to see that the thread’s priority is now +set to the same as the main thread in the next seL4_DebugDumpScheduler() call.

+ +
Name                                        State           IP                       Prio    Core
+--------------------------------------------------------------------------------------
+child of: 'tcb_threads'                    inactive        (nil)   254                 0
+tcb_threads                                running         0x4012ef    254                 0
+idle_thread                                 idle            (nil)   0                   0
+rootserver                                  inactive        0x4024c2    255                 0
+<<seL4(CPU 0) [decodeInvocation/530 T0xffffff8008140c00 "tcb_threads" @4012ef]: Attempted to invoke a >
+main@threads.c:57 [Err seL4_InvalidCapability]:
+Failed to write the new thread's register set.
+
+ +

Set initial register state

+ +

The TCB is nearly ready to run, except for its initial registers. You need to set the +program counter and stack pointer to valid values, otherwise your thread will crash immediately.

+ +

libsel4utils contains some functions for setting register contents in a platform agnostic manner. +You can use these methods to set the program counter (instruction pointer) and stack pointer in +this way. Note: It is assumed that the stack grows downwards on all platforms.

+ +

Exercise Set up the new thread to call the function new_thread. You can use the debug syscall to verify that +you have at least set the instruction pointer (IP) correctly.

+ +
    seL4_UserContext regs = {0};
+    int error = seL4_TCB_ReadRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+    ZF_LOGF_IFERR(error, "Failed to read the new thread's register set.\n");
+
+    // TODO use valid instruction pointer
+    sel4utils_set_instruction_pointer(&regs, (seL4_Word)NULL);
+    // TODO use valid stack pointer
+    sel4utils_set_stack_pointer(&regs, NULL);
+    // TODO fix parameters to this invocation
+    error = seL4_TCB_WriteRegisters(seL4_CapNull, 0, 0, 0, &regs);
+    ZF_LOGF_IFERR(error, "Failed to write the new thread's register set.\n"
+                  "\tDid you write the correct number of registers? See arg4.\n");
+    seL4_DebugDumpScheduler();
+
+ +
+ Quick solution + + 
    seL4_UserContext regs = {0};
+    int error = seL4_TCB_ReadRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+    ZF_LOGF_IFERR(error, "Failed to read the new thread's register set.\n");
+
+    sel4utils_set_instruction_pointer(&regs, (seL4_Word)new_thread);
+    sel4utils_set_stack_pointer(&regs, tcb_stack_top);
+    error = seL4_TCB_WriteRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+    ZF_LOGF_IFERR(error, "Failed to write the new thread's register set.\n"
+                  "\tDid you write the correct number of registers? See arg4.\n");
+    seL4_DebugDumpScheduler();
+
+
+ +

On success, you will see the following output:

+
<<seL4(CPU 0) [decodeInvocation/530 T0xffffff800813fc00 "tcb_threads" @4004bf]: Attempted to invoke a null cap #0.>>
+main@threads.c:63 [Err seL4_InvalidCapability]:
+	Failed to start new thread.
+
+ +

Start the thread

+ +

Finally you are ready to start the thread, which makes the TCB runnable and eligible to be picked by + the seL4 scheduler. This can be done by changing the second argument of +seL4_TCB_WriteRegisters to 1 and removing the seL4_TCB_Resume call, or by fixing the resume call below.

+ +

Exercise resume the new thread.

+ +
    // TODO resume the new thread
+    error = seL4_TCB_Resume(seL4_CapNull);
+    ZF_LOGF_IFERR(error, "Failed to start new thread.\n");
+
+ +
+ Quick solution + + 
    // resume the new thread
+    error = seL4_TCB_Resume(tcb_cap_slot);
+    ZF_LOGF_IFERR(error, "Failed to start new thread.\n");
+
+
+ +

If everything has been configured correctly, resuming the thread should result in the string +Hello2: arg1 0, arg2 0, arg3 0 followed by a fault.

+ +

Passing arguments

+ +

You will notice that all of the arguments to the new thread are 0. You can set the arguments by +using the helper function sel4utils_arch_init_local_context or by directly manipulating the registers +for your target architecture.

+ +

Exercise update the values written with seL4_TCB_WriteRegisters to pass the values 1, 2, 3 as arg1, +arg2, and arg3 respectively.

+ +
    seL4_UserContext regs = {0};
+    int error = seL4_TCB_ReadRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+    ZF_LOGF_IFERR(error, "Failed to read the new thread's register set.\n");
+
+     // use valid instruction pointer
+    sel4utils_set_instruction_pointer(&regs, (seL4_Word) new_thread);
+    // use valid stack pointer
+    sel4utils_set_stack_pointer(&regs, tcb_stack_top);
+    // fix parameters to this invocation
+    error = seL4_TCB_WriteRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+
+    ZF_LOGF_IFERR(error, "Failed to write the new thread's register set.\n"
+                  "\tDid you write the correct number of registers? See arg4.\n");
+    seL4_DebugDumpScheduler();
+
+ +
+ Quick solution + + 

+UNUSED seL4_UserContext regs = {0};
+    int error = seL4_TCB_ReadRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+    ZF_LOGF_IFERR(error, "Failed to write the new thread's register set.\n"
+                  "\tDid you write the correct number of registers? See arg4.\n");
+
+    sel4utils_arch_init_local_context((void*)new_thread,
+                                  (void *)1, (void *)2, (void *)3,
+                                  (void *)tcb_stack_top, &regs);
+    error = seL4_TCB_WriteRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+    ZF_LOGF_IFERR(error, "Failed to write the new thread's register set.\n"
+                  "\tDid you write the correct number of registers? See arg4.\n");
+
+ +
+ +

Resolving a fault

+ +

At this point, you have created and configured a new thread, and given it initial arguments. +The last part of this tutorial is what to do when your thread faults. We provide further detail + on fault handling in a future tutorial, but for now you can rely on the +kernel printing a fault message, as the thread you have created does not have a fault handler.

+ +

In the output below you can see a cap fault has occurred. The first part of the error is that +the kernel was unable to send a fault to a fault handler as it is set to (nil). The kernel +then prints out the fault it was trying to send. In this case, the fault is a virtual memory fault. +The new thread has tried to access data at address 0x2 which is an invalid and unmapped address. +The output shows that the program counter of the thread when it faulted was 0x401e66.

+ +

The fault status register is also output, which can be decoded by +using the relevant architecture manual. +Additionally, the kernel prints a raw stack dump from the current stack pointer. +The size of the stack dump is configurable, using the + KernelUserStackTraceLength cmake variable.

+ +
Caught cap fault in send phase at address (nil)
+while trying to handle:
+vm fault on data at address 0x2 with status 0x4
+in thread 0xffffff8008140400 "child of: 'tcb_threads'" at address 0x401e66
+With stack:
+0x439fc0: 0x0
+0x439fc8: 0x3
+0x439fd0: 0x2
+0x439fd8: 0x1
+0x439fe0: 0x0
+0x439fe8: 0x1
+0x439ff0: 0x0
+0x439ff8: 0x0
+0x43a000: 0x404fb3
+0x43a008: 0x0
+0x43a010: 0x0
+0x43a018: 0x0
+0x43a020: 0x0
+0x43a028: 0x0
+0x43a030: 0x0
+0x43a038: 0x0
+
+ +

To investigate the fault, you can use a tool such as objdump on the ELF file that was loaded to +inspect the instruction that caused the fault. + In this case, the ELF file is located at ./<BUILD_DIR>/<TUTORIAL_BUILD_DIR>/threads.

+ +

You should be able to see that arg2 is being dereferenced, but does not point to valid memory.

+ +

Exercise pass a valid arg2, by passing the address of a global variable.

+ +
+ Quick solution +

Create a new variable

+ 
    int data = 42;
+
+ +

And fix sel4utils_arch_init_local_context

+ + 
    sel4utils_arch_init_local_context((void*)new_thread,
+                                  (void *)1, (void *)&data, (void *)3,
+                                  (void *)tcb_stack_top, &regs);
+
+
+ +

Next, another fault will occur as the new thread expects arg1 to be a pointer to a function.

+ +

Exercise Pass the address of a function which outputs the argument which is passed to it, as arg2.

+ +
+ Quick solution +

Create a new function

+ + 
int call_once(int arg) {
+    printf("Hello 3 %d\n", arg);
+}
+
+ +

and fix sel4utils_arch_init_local_context

+ + 
    UNUSED seL4_UserContext regs = {0};
+    int error = seL4_TCB_ReadRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+    ZF_LOGF_IFERR(error, "Failed to write the new thread's register set.\n"
+                  "\tDid you write the correct number of registers? See arg4.\n");
+
+
+    sel4utils_arch_init_local_context((void*)new_thread,
+                                  (void *)call_once, (void *)&data, (void *)3,
+
+                                  (void *)tcb_stack_top, &regs);
+    error = seL4_TCB_WriteRegisters(tcb_cap_slot, 0, 0, sizeof(regs)/sizeof(seL4_Word), &regs);
+    ZF_LOGF_IFERR(error, "Failed to write the new thread's register set.\n"
+                  "\tDid you write the correct number of registers? See arg4.\n");
+
+
+
+ +

Now you should have a new thread, which immediately calls the function passed in arg2.

+ +

Further exercises

+ +

That’s all for the detailed content of this tutorial. Below we list other ideas for exercises you can try, +to become more familiar with TCBs and threading in seL4.

+ +
    +
  • Using different TCB invocations to change the new thread’s attributes or objects
    • +
  • Investigate how setting different priorities affects when the threads are scheduled to run
    • +
  • Implementing synchronisation primitives using global memory.
    • +
  • Trying to repeat this tutorial in the root task where there are more resources available to +create more thread objects.
    • +
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/threads.md b/Tutorials/threads.md deleted file mode 100644 index b5fa3f3b7a1..00000000000 --- a/Tutorials/threads.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Threads -tutorial: threads -layout: tutorial -description: how to start a thread using the seL4 API -nav_prev: mapping.html -nav_next: ipc.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/Tutorials/untyped.html b/Tutorials/untyped.html new file mode 100644 index 00000000000..84ed421be58 --- /dev/null +++ b/Tutorials/untyped.html @@ -0,0 +1,993 @@ + + + + + + + Untyped | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ + + +

Untyped

+ +

This tutorial provides an introduction to physical memory management on seL4.

+ +

It covers:

+
    +
  1. The jargon untyped, device untyped, and bit size.
    2. +
  2. How to create objects from untyped memory in seL4.
    3. +
  3. How to reclaim objects.
    4. +
+ +

Prerequisites

+ +
    +
  1. Set up your machine
    2. +
  2. Capabilities tutorial
    3. +
+ +

Initialising

+ +
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --tut untyped
+# building the tutorial exercise
+cd untyped_build
+ninja
+
+ +
+ Hint: tutorial solutions + +

All tutorials come with complete solutions. To get solutions run:

+ + 
# For instructions about obtaining the tutorial sources see /Tutorials/get-the-tutorials
+#
+# Follow these instructions to initialise the tutorial
+# initialising the build directory with a tutorial exercise
+./init --solution --tut untyped
+# building the tutorial exercise
+cd untyped_build
+ninja
+
+ +

Answers are also available in drop down menus under each section.

+
+ +

Background

+ +

Physical memory

+ +

Apart from a small, static amount of kernel memory, all physical memory is managed by user level in an seL4 +system. Capabilities to objects created by seL4 at boot, as well as the rest of the physical resources managed by seL4, +are passed to the root task on start up.

+ +

Untyped memory and capabilities

+ +

Excluding the objects used to create the root task, capabilities to all +available physical memory are passed to the root task as capabilities to +untyped memory. Untyped memory is a block of contiguous physical memory with a +specific size. Untyped capabilities are capabilities to untyped memory. Untyped +capabilities can be retyped into kernel objects together with capabilities to +them, or into further, usually smaller, untyped capabilities.

+ +

Untyped capabilities have a boolean property device which indicates whether +the memory is writable by the kernel or not: it may not be backed by RAM but +some other device, or it may be in an area of RAM not addressable by the kernel. +Device untyped capabilities can only be retyped into frame objects (physical +memory frames, which can be mapped into virtual memory), and cannot be written +to by the kernel.

+ +

Initial state

+ +

The seL4_BootInfo structure provided to the root task describes all of the untyped capabilities, including their size, +if they are a device untyped, and the physical address of the untyped. The code example below +shows how to print out the initial untyped capabilities provided from seL4_BootInfo.

+ +
    printf("    CSlot   \tPaddr           \tSize\tType\n");
+    for (seL4_CPtr slot = info->untyped.start; slot != info->untyped.end; slot++) {
+        seL4_UntypedDesc *desc = &info->untypedList[slot - info->untyped.start];
+        printf("%8p\t%16p\t2^%d\t%s\n", (void *) slot, (void *) desc->paddr, desc->sizeBits, desc->isDevice ? "device untyped" : "untyped");
+    }
+
+ +

Retyping

+ +

Untyped capabilities have a single invocation: +seL4_Untyped_Retype which is +used to create a new capability (and potentially object) from an untyped +capability. Specifically, the new capability created by a retype invocation +provides access to a subset of the memory range of the original capability, +either as a smaller untyped capability, or pointing to a new object with a +specific type. New capabilities created by retyping an untyped capability are +referred to as children of that untyped capability.

+ +

Untyped capabilities are retyped incrementally in a greedy fashion from the +invoked untyped, which is important to understand in order to gain efficient +memory utilisation in seL4 systems. Each untyped capability maintains a single +watermark, with addresses before the watermark being unavailable (already +retyped) and after the watermark being free (not retyped yet). On a retype +operation, the watermark is moved first to the alignment of the object being +created, and then to the end of the size of the object. For example, if we +create first a 4KiB object and then a 16KiB object, the 12KiB between the end of +the 4KiB object and the start of the 16KiB object are wasted due to alignment. +The memory cannot be reclaimed until both children are revoked.

+ +

TL;DR: objects should be allocated in order of size, largest first, to avoid wasting memory.

+ +
    error = seL4_Untyped_Retype(parent_untyped, // the untyped capability to retype
+                                seL4_UntypedObject, // type
+                                untyped_size_bits,  //size
+                                seL4_CapInitThreadCNode, // root
+                                0, // node_index
+                                0, // node_depth
+                                child_untyped, // node_offset
+                                1 // num_caps
+                                );
+
+ +

The above code snippet shows an example of retyping an untyped into a smaller, +4KiB untyped capability (despite the name seL4_UntypedObject no object is +created, the new untyped capability simply points to a subset of the untyped +memory of parent_untyped. However, it is convenient to treat this memory like +an object for the purposes of this operation). We will refer to this snippet as +we discuss each parameter in the retype invocation. Recall that the first +parameter is the untyped capability being invoked to do the retype.

+ +

Types

+ +

Each object in seL4 has a specific type, and all of the type constants can be found in libsel4. Some types +are architecture specific, while others are general across architectures. In the example above, we create a +new untyped capability, which can be further retyped. All other object type parameters create kernel objects and +capabilities to them, and the type of the created object (and capability) determines the invocations +that can be made on that capability. For example, were we to retype into a thread control block +(TCB – seL4_TCBObject), we could then perform TCB invocations on the capability to the new TCB object, including seL4_TCB_SetPriority.

+ +

Size

+ +

The size argument determines the size of the new object. The meaning of the argument +depends on the object type that is being requested:

+ +
    +
  • most objects in seL4 are fixed size, and for these, the kernel will ignore +the size argument;
    • +
  • the types seL4_UntypedObject and seL4_SchedContextObject allow a +variable size, which is specified in size_bits (more below);
    • +
  • the type seL4_CapTableObject is also of variable size, and the argument specifies +the number of capability slots. The same mechanism as for size_bits is used, +but for the number of slots, not the size in bytes.
    • +
+ +

In general in seL4, if sizes are measured in bits, they are powers +of two. “Bits” does not refer to the number of bits the object takes up, but +the bit-width that is needed to describe its contents. An object of bit size n +measures 2n bytes. Also, generally in seL4, objects and memory +regions are aligned to their size, i.e. an n-bit object is aligned to +2n bytes, or, equivalently, the address of the object has 0 as its +n bottom bits.

+ +

For retype, it is enough to remember that the parameter size_bits means the +object will measure 2size_bits bytes, and for seL4_CapTableObject +that you are requesting 2size_bits slots (you can compute the size +in bytes by taking 2size_bits + seL4_SlotBits).

+ +

Root, node_index & node_depth

+ +

The root, node_index and node_depth parameters are used to specify the CNode in which to place the new capabilities. +Depending on the depth parameter, the CSlot to use is addressed by invocation or by direct addressing (see the capabilities tutorial for an explanation of those terms).

+ +

In the example above, node_depth is set to 0, which means invocation addressing is used: the root parameter is +looked up implicitly using the CSpace root of the current thread at a depth of seL4_WordBits. So the example code +specifies the root task’s CNode (seL4_CapInitThreadCNode). The node_index parameter in this case is ignored.

+ +

If the node_depth value is not set to 0, then direct addressing is used with the current thread’s CSpace root +as the root. Then the node_index parameter is used to locate the CNode capability to place new capabilities in, +at the specified node_depth. This is designed for managing multi-level CSpaces, and is not covered in this tutorial.

+ +

Node_offset

+ +

The node_offset is the CSlot to start creating new capabilities at, in the CNode selected by the previous parameters. + In this case, the first empty CSlot in the initial CNode is selected.

+ +

Num_caps

+ +

The retype invocation can be used to create more than 1 capability and object at a time – the number of capabilities is +specified using this argument. Note that there are two constraints on this value:

+ +
    +
  1. The untyped must be big enough to fit all of the memory being retyped (num_caps * (1u << size_bits)).
    2. +
  2. The CNode must have enough consecutive free CSlots to fit all of the new capabilities.
    3. +
+ +

Exercises

+ +

Create an untyped capability

+ +

When you first run this tutorial, you will see something like the following output, which lists all of the +untyped capabilities provided to the root task on boot:

+ +
Booting all finished, dropped to user space
+    CSlot   Paddr       Size    Type
+   0x12d    0x100000    2^20    device untyped
+   0x12e    0x200000    2^21    device untyped
+   0x12f    0x400000    2^22    device untyped
+   0x130    0xb2e000    2^13    device untyped
+
+ +

At the end of the output, there is an error:

+ +
<<seL4(CPU 0) [decodeUntypedInvocation/105 T0xffffff801ffb5400 "rootserver" @4012e1]: Untyped Retype: Requested UntypedItem size too small.>>
+main@main.c:49 [Cond failed: error != seL4_NoError]
+    Failed to retype
+
+ +

This error happens because we are trying to create an untyped of size 0.

+ +

Exercise Calculate the size of the child untyped required, such that the child untyped can be used + to create all of the objects listed in the objects array. Remember that object sizes are measured in + bits, that is, in powers of two.

+ +
    // list of general seL4 objects
+    seL4_Word objects[] = {seL4_TCBObject, seL4_EndpointObject, seL4_NotificationObject};
+    // list of general seL4 object size_bits
+    seL4_Word sizes[] = {seL4_TCBBits, seL4_EndpointBits, seL4_NotificationBits};
+
+    // TODO work out what size object we need to create to be able to create all of the objects
+    // listed above. Remember that sizes are in bits, that is, the exponents of powers of two.
+    seL4_Word untyped_size_bits = 0;
+    seL4_CPtr parent_untyped = 0;
+    seL4_CPtr child_untyped = info->empty.start;
+
+    // First, find an untyped big enough to fit all of our objects
+    for (int i = 0; i < (info->untyped.end - info->untyped.start); i++) {
+        if (info->untypedList[i].sizeBits >= untyped_size_bits && !info->untypedList[i].isDevice) {
+            parent_untyped = info->untyped.start + i;
+            break;
+        }
+    }
+
+
+ +
+ Quick solution + + 
    // list of general seL4 objects
+    seL4_Word objects[] = {seL4_TCBObject, seL4_EndpointObject, seL4_NotificationObject};
+    // list of general seL4 object size_bits
+    seL4_Word sizes[] = {seL4_TCBBits, seL4_EndpointBits, seL4_NotificationBits};
+
+    // seL4_EndpointBits and seL4_NotificationBits are both less than seL4_TCBBits, which
+    // means that all objects together fit into the size of two TCBs, or 2^(seL4_TCBBits + 1):
+    seL4_Word untyped_size_bits = seL4_TCBBits + 1;
+    seL4_CPtr parent_untyped = 0;
+    seL4_CPtr child_untyped = info->empty.start;
+
+    // First, find an untyped big enough to fit all of our objects
+    for (int i = 0; i < (info->untyped.end - info->untyped.start); i++) {
+        if (info->untypedList[i].sizeBits >= untyped_size_bits && !info->untypedList[i].isDevice) {
+            parent_untyped = info->untyped.start + i;
+            break;
+        }
+    }
+
+ +
+ +

On success, the tutorial will progress further, printing “Failed to set priority”

+ +

Create a TCB Object

+ +

The priority check is failing as child_tcb is an empty CSlot.

+ +

Exercise fix this by creating a TCB object from child_untyped and place its cap into the child_tcb CSlot.

+ +
    // use the slot after child_untyped for the new TCB cap:
+    seL4_CPtr child_tcb = child_untyped + 1;
+    /* TODO create a TCB in CSlot child_tcb */
+
+    // try to set the TCB priority
+    error = seL4_TCB_SetPriority(child_tcb, seL4_CapInitThreadTCB, 10);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to set priority");
+
+ +
+ Quick solution + + 
    // use the slot after child_untyped for the new TCB cap:
+    seL4_CPtr child_tcb = child_untyped + 1;
+    seL4_Untyped_Retype(child_untyped, seL4_TCBObject, 0, seL4_CapInitThreadCNode, 0, 0, child_tcb, 1);
+
+    // try to set the TCB priority
+    error = seL4_TCB_SetPriority(child_tcb, seL4_CapInitThreadTCB, 10);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to set priority");
+
+
+ +

On success, the tutorial will progress further, printing “Endpoint cap is null cap”.

+ +

Create an endpoint object

+ +

The error you see now is caused be an invalid endpoint capability.

+ +

Exercise Create an endpoint object from child_untyped and place its cap into the child_ep CSlot.

+ +
    // use the slot after child_tcb for the new endpoint cap:
+    seL4_CPtr child_ep = child_tcb + 1;
+    /* TODO create an endpoint in CSlot child_ep */
+
+    // identify the type of child_ep
+    uint32_t cap_id = seL4_DebugCapIdentify(child_ep);
+    ZF_LOGF_IF(cap_id == 0, "Endpoint cap is null cap");
+
+
+ +
+ Quick solution + + 
    // use the slot after child_tcb for the new endpoint cap:
+    seL4_CPtr child_ep = child_tcb + 1;
+    seL4_Untyped_Retype(child_untyped, seL4_EndpointObject, 0, seL4_CapInitThreadCNode, 0, 0, child_ep, 1);
+
+    // identify the type of child_ep
+    uint32_t cap_id = seL4_DebugCapIdentify(child_ep);
+    ZF_LOGF_IF(cap_id == 0, "Endpoint cap is null cap");
+
+ +
+ +

On success, the output will be “Failed to bind notification.”

+ +

Create a notification object

+ +

The next part of the tutorial attempts to use a notification object that does not yet exist.

+ +

Exercise create a notification object from child_untyped and place its cap into the child_ntfn CSlot.

+ +
    // use the slot after child_ep for the new notification cap:
+    seL4_CPtr child_ntfn = child_ep + 1;
+    // TODO create a notification object in CSlot child_ntfn
+
+    // try to use child_ntfn
+    error = seL4_TCB_BindNotification(child_tcb, child_ntfn);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to bind notification.");
+
+ +
+ Quick solution + + 
    // use the slot after child_ep for the new notification cap:
+    seL4_CPtr child_ntfn = child_ep + 1;
+    seL4_Untyped_Retype(child_untyped, seL4_NotificationObject, 0, seL4_CapInitThreadCNode, 0, 0, child_ntfn, 1);
+
+    // try to use child_ntfn
+    error = seL4_TCB_BindNotification(child_tcb, child_ntfn);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to bind notification.");
+
+ +
+ +

On success, the output will be “Failed to create endpoints.”

+ +

Delete the objects

+ +

The final part of the tutorial attempts to create enough endpoint objects from child_untyped to consume the +entire untyped object. However, this fails, because the untyped is already completely consumed by the previous allocations.

+ +

Exercise revoke the child untyped, so we can create new objects from it that use up the whole thing.

+ +
    // TODO revoke the child untyped
+
+    // allocate the whole child_untyped as endpoints
+    // Remember the sizes are exponents, so this computes 2^untyped_size_bits / 2^seL4_EndpointBits:
+    seL4_Word num_eps = BIT(untyped_size_bits - seL4_EndpointBits);
+    error = seL4_Untyped_Retype(child_untyped, seL4_EndpointObject, 0, seL4_CapInitThreadCNode, 0, 0, child_tcb, num_eps);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to create endpoints.");
+
+    printf("Success\n");
+
+ +
+ Quick solution + + 
    error = seL4_CNode_Revoke(seL4_CapInitThreadCNode, child_untyped, seL4_WordBits);
+    assert(error == seL4_NoError);
+
+    // allocate the whole child_untyped as endpoints
+    // Remember the sizes are exponents, so this computes 2^untyped_size_bits / 2^seL4_EndpointBits:
+    seL4_Word num_eps = BIT(untyped_size_bits - seL4_EndpointBits);
+    error = seL4_Untyped_Retype(child_untyped, seL4_EndpointObject, 0, seL4_CapInitThreadCNode, 0, 0, child_tcb, num_eps);
+    ZF_LOGF_IF(error != seL4_NoError, "Failed to create endpoints.");
+
+    printf("Success\n");
+
+ +
+ +

Once the tutorial is completed successfully, you should see the message “Success.”

+ +

Further exercises

+ +

That’s all for the detailed content of this tutorial. Below we list other ideas for exercises you can try +to become more familiar with untyped objects and memory allocation in seL4.

+ +
    +
  • Allocate objects at specific physical addresses.
    • +
  • Create a simple object allocator for allocating seL4 objects.
    • +
+ + +
+ + + +
+
+ + + +
+ +
+
+ + diff --git a/Tutorials/untyped.md b/Tutorials/untyped.md deleted file mode 100644 index 5537107f8d4..00000000000 --- a/Tutorials/untyped.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Untyped -tutorial: untyped -layout: tutorial -description: user-level memory management -nav_prev: capabilities.html -nav_next: mapping.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -{% include tutorial.md %} diff --git a/VM/CAmkESVMCentOS.html b/VM/CAmkESVMCentOS.html new file mode 100644 index 00000000000..d3fbd6dfb04 --- /dev/null +++ b/VM/CAmkESVMCentOS.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/VM/CAmkESX86VM.html b/VM/CAmkESX86VM.html new file mode 100644 index 00000000000..88ec105e289 --- /dev/null +++ b/VM/CAmkESX86VM.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/VM/index.html b/VM/index.html new file mode 100644 index 00000000000..ffcbcc22104 --- /dev/null +++ b/VM/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/VerifiedConfigurations.html b/VerifiedConfigurations.html new file mode 100644 index 00000000000..67c120b24d6 --- /dev/null +++ b/VerifiedConfigurations.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/VisualCAmkES/index.html b/VisualCAmkES/index.html new file mode 100644 index 00000000000..c0a3d916f13 --- /dev/null +++ b/VisualCAmkES/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/_config.yml b/_config.yml deleted file mode 100644 index f0aae9320f8..00000000000 --- a/_config.yml +++ /dev/null @@ -1,124 +0,0 @@ -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. -# SPDX-License-Identifier: BSD-2-Clause -# -# Welcome to Jekyll! -# -# This config file is meant for settings that affect your whole blog, values -# which you are expected to set up once and rarely edit after that. If you find -# yourself editing this file very often, consider using Jekyll's data files -# feature for the data you need to update frequently. -# -# For technical reasons, this file is *NOT* reloaded automatically when you use -# 'bundle exec jekyll serve'. If you change this file, please restart the server process. - -# Site settings -# These are used to personalize your new site. If you look in the HTML files, -# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. -# You can create any custom variable you would like, and they will be accessible -# in the templates via {{ site.myvariable }}. -title: seL4 docs - -baseurl: "" # the subpath of your site, e.g. /blog - -git_repo: https://github.com/seL4/docs -url: "https://docs.sel4.systems" -static_url: "https://docs.sel4.systems" - -description: "This site is for displaying seL4 related documentation. Pull requests are welcome." -github_username: "sel4" - -collections_dir: content_collections - -collections: - releases: - output: true - updates: - output: true - status: - output: true - -sel4: "14.0.0" -camkes: "camkes-3.11.1" -capdl: "0.4.0" -microkit: "2.1.0" - -# Front matter defaults: -defaults: - - scope: - path: "" - type: releases - values: - layout: "release" - - scope: - path: "" - type: updates - values: - layout: "release" - - scope: - path: "" - values: - layout: "default" - - -# Build/plugin settings. These settings configure plugins. -# Themes and plugins transparently add files to the site project. To see what plugins -# are being used run `bundle show`. To see what files are contributed by each plugin: -# ls `bundle show $plugin_name` -markdown: Kramdown - -plugins: - # Sets the page title to the first heading. Removes need for title to be set in every file - - jekyll-titles-from-headings - # Converts markdown relative links to valid html urls. - - jekyll-relative-links - # Default includes .md files to be templated without needing the --- front matter. - - jekyll-optional-front-matter - # Adds a sitemap.xml to site for webcrawlers - - jekyll-sitemap - # Adds a table of contents to top of page if toc: true is set in the front matter. - - jekyll-toc - # Allow multiple urls to redirect to a single page - - jekyll-redirect-from - # For tailwind postcss - - jekyll-postcss-v2 - # For icons - - jekyll-inline-svg - -toc: - min_level: 2 # default: 1 - max_level: 5 # default: 6 - -kramdown: - input: GFM - -breadcrumbs: - root: - hide: false # show breadcrumbs on root/home page - image: false # Show image or title text - -optional_front_matter: -# Set this to false if you want .md files to be accessible also - remove_originals: true - -# Exclude files from processing. dotfiles don't seem to be included by default -exclude: - - Gemfile - - Gemfile.lock - - dependencies - - Makefile - - README.md - - LICENSES/ - - tools/ - - package.json - - postcss.config.js - - package-lock.json - - node_modules/ - - "**/*.license" - - .github/ - - .reuse/ - - _processed/ - - vendor/ - - _repos/ - -keep_files: - - projects/rust/tutorial diff --git a/_data/maintained.yml b/_data/maintained.yml deleted file mode 100644 index b6d53576af8..00000000000 --- a/_data/maintained.yml +++ /dev/null @@ -1,59 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -github: - - name: seL4 - repos: - - l4v - - seL4 - - seL4_tools - - seL4_libs - - seL4-CAmkES-L4v-dockerfiles - - musllibc - - util_libs - - sel4test - - sel4bench - - sel4bench-manifest - - sel4test-manifest - - sel4-tutorials - - sel4-tutorials-manifest - - seL4-CAmkES-L4v-dockerfiles - - seL4_projects_libs - - global-components - - cakeml_libs - - capdl - - camkes - - camkes-manifest - - camkes-tool - - camkes-vm - - camkes-vm-apps - - camkes-vm-examples - - camkes-vm-examples-manifest - - camkes-vm-linux - - camkes-vm-images - - rumprun-sel4-demoapps - - rumprun-packages - - pruner - - verification-manifest - - projects_libs - - sel4webserver - - sel4webserver-manifest - - sel4runtime - - rumprun - - graph-refine - - picotcp - - picotcp-bsd - - isabelle - - HOL - - polyml - - repo_projects: - - sel4test-manifest - - sel4bench-manifest - - camkes-manifest - - camkes-vm-examples-manifest - - sel4webserver-manifest - - sel4-tutorials-manifest - - rumprun-sel4-demoapps - - verification-manifest - diff --git a/_data/projects/buildsystem.yml b/_data/projects/buildsystem.yml deleted file mode 100644 index a35b0a66f75..00000000000 --- a/_data/projects/buildsystem.yml +++ /dev/null @@ -1,12 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: buildsystem -display_name: seL4 Buildsystem -description: System configuration and building using mostly CMake -project_order: 5 -repositories: - - org: sel4 - repo: sel4 - - org: sel4 - repo: sel4_tools diff --git a/_data/projects/camkes-vm.yml b/_data/projects/camkes-vm.yml deleted file mode 100644 index 66f70ffd6a0..00000000000 --- a/_data/projects/camkes-vm.yml +++ /dev/null @@ -1,180 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: camkes-vm -display_name: camkes-vm -description: x86 or Arm Virtual Machine build as a CAmkES component -project_order: 8 - -repositories: - - org: seL4 - repo: camkes-vm - - org: seL4 - repo: camkes-vm-examples - - org: seL4 - repo: camkes-vm-examples-manifest - - -components: - - name: odroid_vm - display_name: odroid_vm - description: "Legacy exynos5410 flight computer application." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vm-application - - name: vm_minimal - display_name: vm_minimal - description: "A simple VMM application, launching a single guest Linux with a buildroot RAM-based file system" - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vm-application - - name: vm_cross_connector - display_name: vm_cross_connector - description: "Application demonstrating communication between a Linux guest user-level process and a native seL4 component. This leveraging cross vm communication channels established between the VMM and the seL4 component" - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vm-application - - name: vm_multi - display_name: vm_multi - description: "Application demonstrating running multiple guest VM's. This is achieved through having multiple VMM components, each managing a single Linux guest (1-1 model)." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vm-application - - name: vm_serial_server - display_name: vm_serial_server - description: "Application demonstrating the use of Virtio Console, where a VM's serial I/O is forwarded to/from a serial server." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vm-application - - name: vm_virtio_net - display_name: vm_virtio_net - description: "Application demonstrating the use of Virtio Net, where a virtual network interface is presented to a VM and subsequent network traffic on the virtual network interface is sent to/from other native seL4 components." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vm-application - - name: camkes-arm-vm-component - display_name: "camkes-arm-vm VM component" - description: "CAmkES `VM` component that contains a VMM + guest instance" - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vm-application - - name: camkes-connector-seL4VMDTBPassthrough - display_name: "seL4VMDTBPassthrough" - description: "CAmkES connector for specifying nodes of a device tree for VM device passthrough." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-connector - - name: libvirtio - display_name: "libvirtio" - description: "Utility library for installing virtio devices (virtio-cons, virtio-net) from VM modules." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vm-library - - name: exynos5410_init - display_name: exynos5410_init - description: "Platform init VMM module for exynos5410" - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vmm-module - - name: tk1_init - display_name: tk1_init - description: "Platform init VMM module for tk1" - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vmm-module - - name: device_fwd - display_name: device_fwd - description: "tk1 module for installing virtual UART and Clock/Reset devices that forward access to a separate CAmkES component." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vmm-module - - name: map_frame_hack - display_name: map_frame_hack - description: "VMM module from SMACCM project to provide an insecure shared memory connection between a VM and untrusted CAmkES component for insecure system demonstration." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vmm-module - - name: virtio_con - display_name: virtio_con - description: "VMM module for installing virtio console device into guest with backend provided by connection to a CAmkES serial server component." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vmm-module - - name: virtio_net_arping - display_name: virtio_net_arping - description: "VMM module for installing a test virtio-net device into guest which only responds to arping requests." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vmm-module - - name: virtio_net_virtqueue - display_name: virtio_net_virtqueue - description: "VMM module for installing a virtio-net device into the guest backed by virtqueues for sending and receiving ethernet packets between a separate CAmkES component." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-arm-vmm-module - - name: libvirtio - display_name: "libvirtio" - description: "Utility library for installing virtio devices (virtio-cons, virtio-net) from VM modules." - maintainer: "maintainer wanted" - status: "active" - component_type: camkes-connector - - name: Findcamkes-arm-vm - display_name: "Findcamkes-arm-vm" - description: "CMake module for camkes-arm-vm components" - maintainer: "maintainer wanted" - status: "active" - component_type: cmake-module - - name: arm_vmConfig - display_name: "arm_vm Configuration library" - description: "Configuration library containing camkes-arm-vm build configuration values." - maintainer: "maintainer wanted" - status: "active" - component_type: config-library - - name: linux - display_name: linux - description: "exynos5410 Linux kernel guest image." - maintainer: "maintainer wanted" - status: "active" - component_type: guest-vm-kernel-image - - name: linux-secure-dtb - display_name: linux-secure-dtb - description: "exynos5410 device tree binary (dtb) for Linux kernel guest image." - maintainer: "maintainer wanted" - status: "active" - component_type: guest-vm-device-tree - - name: linux-secure-vusb-dtb - display_name: linux-secure-vusb-dtb - description: "exynos5410 device tree binary (dtb) with virtual USB device for Linux kernel guest image." - maintainer: "maintainer wanted" - status: "active" - component_type: guest-vm-device-tree - - name: linux-tk1-debian - display_name: linux-tk1-debian - description: "tk1 Buildroot Linux kernel guest image for Debian distro user level installed on emmc." - maintainer: "maintainer wanted" - status: "active" - component_type: guest-vm-kernel-image - - name: linux-tk1-initrd - display_name: linux-tk1-initrd - description: "tk1 Buildroot Linux kernel guest image containing rootfs.cpio user level" - maintainer: "maintainer wanted" - status: "active" - component_type: guest-vm-kernel-image - - name: linux-tk1-nonsecured.dts - display_name: linux-tk1-nonsecured.dts - description: "tk1 device tree source (dts) with most devices given to guest to manage via device passthrough." - maintainer: "maintainer wanted" - status: "active" - component_type: guest-vm-device-tree - - name: linux-tk1-secire.dts - display_name: linux-tk1-secure.dts - description: "tk1 device tree source (dts) with most devices not given to guest vm and instead marked as disabled." - maintainer: "maintainer wanted" - status: "active" - component_type: guest-vm-device-tree - - name: rootfs-tk1.cpio - display_name: rootfs-tk1.cpio - description: "A in-memory buildroot filesystem for tk1." - maintainer: "maintainer wanted" - status: "active" - component_type: guest-vm-rootfs diff --git a/_data/projects/camkes.yml b/_data/projects/camkes.yml deleted file mode 100644 index d6726f0e0fd..00000000000 --- a/_data/projects/camkes.yml +++ /dev/null @@ -1,919 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: camkes -display_name: CAmkES -description: Component Architecture for microkernel-based Embedded Systems -useful_urls: - - label: "CAmkES Manual" - url: "/projects/camkes/manual.html" - - label: "Trustworthy Systems CAmkES project" - url: "https://trustworthy.systems/projects/TS/camkes.pml" -project_order: 3 - -repositories: - - org: sel4 - repo: camkes-tool - - org: sel4 - repo: camkes - - org: sel4 - repo: camkes-manifest - - org: sel4 - repo: global-components - - -features: - - name: assembly - display_name: Assembly - description: "An assembly is a top level component system description. It contains a complete description of a full system." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: composition - display_name: Composition - description: "A container for the component and connector instantiations that form a system." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: configuration - display_name: Configuration - description: "A container for describing settings. This is a syntactic element to hold the assignment of attributes for a given system.\ - It is expressed inside an assembly block." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: component-definitions - display_name: Component definition - description: "A `type` of functional entity. 'Component' is used colloquially to refer to both types and instances, but in a formal sense 'component' refers only to the type." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: hierarchical-components - display_name: Hierarchical components - description: "A component can contain its own composition and configuration sections that can define components and connections that are in a different namespace from the toplevel - composition and configuration namespaces. Each component instance is still a separate component. The top level component type can then select internal interfaces to export as its own interfaces." - maintainer: "maintainer wanted" - status: "Mostly supported. There are some known template bugs where a component exporting dataport interfaces is also required to have a connection to the dataport." - component_type: adl-feature - - name: grouped-components - display_name: Component Groups - description: "A `Group` combines components into a single underlying process so they share an address space. This can reduce communication costs due to reduced context switching - requirements, but components in a group are required to mutually trust each other." - maintainer: "maintainer wanted" - status: "Mostly supported. Connector implementations need to be aware that they are being used in a group component context. There are also issues with variable storage as some - global variables will be defined for each component instance in the group, and threads that call across component boundaries may access incorrect variable instances." - component_type: adl-feature - - name: hardware-components - display_name: Hardware components - description: "A hardware component represents an interface to hardware in the form of a component. Declaring a component with the hardware keyword creates a hardware component." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: interfaces - display_name: Component Interfaces - description: "An abstract exposed interaction point of a component. The subcategories of interface are procedure, event and dataport." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: exported-interfaces - display_name: Exported Interfaces - description: "An interface of a compound component that is not implemented by that component, but is an alias for internal instance’s interface." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: optional-interfaces - display_name: Optional Interfaces - description: "Interfaces of components can be made optional using the `maybe` keyword. Optional interfaces do not need to be connected to any other interfaces." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: procedure-definition - display_name: Procedure IDL - description: "An interface with function call semantics use procedures which consist of a series of methods that can be invoked independently. Procedures are defined - within the ADL which has a IDL subset for defining methods and parameters." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: attributes - display_name: Attributes - description: "An attribute is a configuration option that can be set on a component, connection or procedure definition. \ - It is used to pass configuration information through to the underlying implementations." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: structs - display_name: Structured attributes - description: "Attribute types support struct- and array-like declarations that support bundling and variable length attribute definitions." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: attribute-defaults - display_name: Default attribute values - description: "Attribute definitions can also provide default settings. These defaults are used in the absence attribute settings." - maintainer: "maintainer wanted" - status: "Supported for component and connection attributes" - component_type: adl-feature - - name: synchronization-primitives - display_name: Synchronization Primitives - description: "CAmkES provides three primitives for intra-component mutual exclusion and synchronization. Mutexes, semaphores, and binary semaphores are declared similarly to attributes of a component definition." - maintainer: "maintainer wanted" - status: "Supported" - component_type: adl-feature - - name: includes - display_name: "`include` statements" - description: "`include` statements are used to declare source language include dependencies on component and procedure definitions. These are used when CAmkES is using types defined by another language." - maintainer: "maintainer wanted" - status: "Supported, but only used with C header files." - component_type: adl-feature - - name: connector-types - display_name: Connector definitions - description: "A type of link between instances. A connector implements the transportation for the interfaces it is connected between." - maintainer: "maintainer wanted" - status: "Supported." - component_type: adl-feature - - name: connections - display_name: Connections - description: "An instantiation of a connector. Connections connect two or more instances together via their interfaces." - maintainer: "maintainer wanted" - status: "Supported." - component_type: adl-feature - - name: imports - display_name: Imports - description: "`import` statements are used to define an assembly over multiple `.camkes` files and combine them together into a single AST." - maintainer: "maintainer wanted" - status: "Supported. It is possible to provide an import path argument to the camkes tool for where to search for files to import." - component_type: adl-feature - - name: cpreprocessor - display_name: "C-Preprocessed ADL files" - description: "The C Preprocessor is run over the ADL files before the parser starts parsing them." - maintainer: "maintainer wanted" - status: "Supported. Because of the C-Preprocessor, the ADL ignores lines starting with #. This is not a valid comment syntax." - component_type: adl-feature - - name: query-plugins - display_name: "Query syntax and plugins" - description: "The parser supports adding plugins that can provide configuration values via a setting querying syntax. A plugin is able - to respond to a query with a valid configuration value." - maintainer: "maintainer wanted" - status: "Supported. Currently only 1 plugin exists, fdtQueryEngine, for querying values out of a Flattened device tree (FDT)." - component_type: adl-feature - -# Build definitions - -components: - # - # camkes - # - - name: adder - display_name: adder - description: "A simple 'Hello world' CAmkES application which demonstrates some basics of the CAmkES framework." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: aeroplage - display_name: aeroplage - description: "A CAmkES application which implements a prototype of a previous multi-level terminal for seL4." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: alignment - display_name: alignment - description: "A CAmkES application which tests if the stack is aligned properly by crashing on an unaligned stack." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: attributes - display_name: attributes - description: "A CAmkES application which demonstrates the use of aliasing attributes." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: binary-semaphore - display_name: binary-semaphore - description: "A CAmkES application which demonstrates how to use a binary semaphore to turn an asynchronous interface into a synchronous one." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: cakeml_hello - display_name: cakeml_hello - description: "A 'Hello world' CAmkES application which demonstrates the ability to run CakeML-based CAmkES components inside CAmkES." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: cakeml_regex - display_name: cakeml_regex - description: "A CAmkES application which demonstrates the use of CakeML to implement a CAmkES component which filters data between two different components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: cakeml_tipc - display_name: cakeml_tipc - description: "A CAmkES application which demonstrates the Transparent IPC protocol (TIPC) and the use of CakeML to implement a CAmkES component to filter data between two different CAmkES components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: cms-donate - display_name: cms-donate - description: "A CAmkES application which demonstrates the donation of a scheduling context between a client and server via an intermediary under a Mixed Criticality Scheduling (MCS) environment." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: cs-donate - display_name: cs-donate - description: "A CAmkES application which demonstrates the donation of a scheduling context between a client and server under a Mixed Criticality Scheduling (MCS) environment." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: cs-nodonate - display_name: cs-nodonate - description: "A CAmkES application which demonstrates two CAmkES components running using their own scheduling contexts under a Mixed Criticality Scheduling (MCS) environment." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: dataport - display_name: dataport - description: "A CAmkES application which demonstrates an example of the usage of CAmkES dataports." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: debug-simple - display_name: debug-simple - description: "A CAmkES application which demonstrates the use of the seL4GDB connector to debug CAmkES components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: dhcp - display_name: dhcp - description: "A CAmkES application which demonstrates an example DHCP server." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: dma-example - display_name: dma-example - description: "A CAmkES application which demonstrates the use of a CAmKES-allocated DMA pool." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: epit - display_name: epit - description: "A CAmkES application which demonstrates a simple hardware driver CAmkES component for the EPIT timers on the KZM platform." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: event - display_name: event - description: "A CAmkES application which demonstrates an example of CAmkES events." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: event-driven - display_name: event-driven - description: "A CAmkES application which demonstrates an example of a CAmkES event-driven application." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: exchangestring - display_name: exchangestring - description: "A CAmkES application which demonstrates how to pass string arguments between CAmkES components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: fdtgen - display_name: fdtgen - description: "A CAmkES application which demonstrates an example on how to include a DTB blob and how to modify it." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: filter - display_name: filter - description: "A CAmkES application which demonstrates the use of a CAmkES component to filter communication between two other CAmkES components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: global-imports - display_name: global-imports - description: "A CAmkES application which demonstrates an example of allowing CAmkES components to be globally imported using specific CMake macros." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: hellorust - display_name: hellorust - description: "A CAmkES application which demonstrates an example of running a Rust application inside CAmkES." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: hierarchical-attributes - display_name: hierarchical-attributes - description: "A CAmkES application which demonstrates an example of hierarchical attributes in CAmKES." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: hierarchical-components - display_name: hierarchical-components - description: "A CAmkES application which demonstrates an example of hierarhical CAmkES components in CAmkES." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: keyboard - display_name: keyboard - description: "A CAmkES application which demonstrates an example keyboard driver for x86 platforms." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: lockserver - display_name: lockserver - description: "A CAmkES application which demonstrates an example system which contains a CAmkES component that manages a lock." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: mcs-donate - display_name: mcs-donate - description: "A CAmkES application which demonstrates the donation of scheduling contexts betwen two clients and a server under a Mixed Criticality Scheduling (MCS) environment." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: mcs-nodonate - display_name: mcs-nodonate - description: "A CAmkES application which demonstrates the three CAmkES components running using their own scheduling contexts under a Mixed Criticality Scheduling (MCS) environment." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: multiassembly - display_name: multiassembly - description: "A CAmkES application which demonstrates the ability to have two different 'assembly' blocks." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: multiclient - display_name: multiclient - description: "A CAmkES application which demonstrates the ability to allow multiple clients to share one connection." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: multiplier - display_name: multiplier - description: "A CAmkES application which demonstrates an example of using arrays as arguments for RPC functions between CAmkES components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: mutex - display_name: mutex - description: "A CAmkES application which demonstrates the use of user-defined connectors in CAmkES to implement a lock." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: periodic - display_name: periodic - description: "A CAmkES application which demonstrates the periodic timeslices of CAmkES components under a Mixed Criticality Scheduling (MCS) environment." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: picoserver - display_name: picoserver - description: "A CAmkES application which demonstrates a simple networking example which uses the PicoServer in the global-components repository." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: pit - display_name: pit - description: "A CAmkES application which demonstrates a timer driver CAmkES component for the Programmable Interval Timer on x86 platforms." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: reversestring - display_name: reversestring - description: "A CAmkES application which demonstrates dataport release and acquire semantics." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: rotate - display_name: rotate - description: "A CAmkES application which demonstrates the use of user-defined types as arguments of a RPC interface." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: RPCOverMultiSharedData - display_name: RPCOverMultiSharedData - description: "A CAmkES application which demonstrates the use of the seL4RPCOverMultiSharedData connector to perform RPC using shared memory buffers between the client and server." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: rumprun_ethernet - display_name: rumprun_ethernet - description: "A CAmkES application which demonstrates a single TCP echo program that runs in a Rumprun unikernel instance on CAmkES." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: rumprun_pthreads - display_name: rumprun_pthreads - description: "A CAmKES application which demonstrates a simple pthreads program that runs in a Rumprun unikernel instance on CAmKES." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: rumprun_rust - display_name: rumprun_rust - description: "A CAmkES application which demonstrates a simple Rust 'Hello world' program that runs in a Rumprun unikernel instance on CAmkES." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: serialserver - display_name: serialserver - description: "A CAmkES application which demonstrates the use of the SerialServer component in the global-components repository." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: serialserver_loopback - display_name: serialserver_loopback - description: "A CAmkES application which demonstrates the use of the SerialServer component in the global-components repository looping back characters that it reads in from the serial device." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: simple - display_name: simple - description: "A CAmkES application which demonstrates an example of a CAmkES RPC connection." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: simplesingleaddressspace - display_name: simplesingleaddressspace - description: "A CAmkES application which demonstrates an example of a single address space CAmkES system which contains a RPC connection between its two components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: socket - display_name: socket - description: "A CAmkES application which demonstrates a user-defined dataport." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: structs - display_name: structs - description: "A CAmkES application which demonstrates the use of structs and arrays for CAmkES component attribute types." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: swapcounter - display_name: swapcounter - description: "A CAmkES application which was used for demonstration purposes for a paper submission to Formal Methods 2015 but has since been modified." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: terminal - display_name: terminal - description: "A CAmkES application which serves as a prototype for a secure terminal system." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testbufvariant - display_name: testbufvariant - description: "A CAmkES application which is used to test dataports." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testcamkes438 - display_name: testcamkes438 - description: "A CAmkES application that is used to test a specific function of the CAmkES framework." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testcontrolname - display_name: testcontrolname - description: "A CAmkES application that is used to test if interfaces could be named with a particular suffix." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testdataportbifurcate - display_name: testdataportbifurcate - description: "A CAmkES application that tests if we can have multiple dataports within a single component that maps to the same underlying physical memory." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testdataportmux - display_name: testdataportmux - description: "A CAmkES application that tests the ability to have multiple CAmkES components connected to the same dataport." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testdataportmuxflat - display_name: testdataportmuxflat - description: "A CAmkES application that tests the ability to have N-to-M dataport connections in a single address space." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testdataportptrwrap - display_name: testdataportptrwrap - description: "A CAmkES application that tests if dataport pointer wrapping and unwrapping functionality works on multiplexed dataports." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testdataportrpc - display_name: testdataportrpc - description: "A CAmkES application that tests if we can back an seL4RPCCall connection with various types of dataports." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testfaulthandlers - display_name: testfaulthandlers - description: "A CAmkES application that tests if the fault handlers work correctly as intended." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testgrouping - display_name: testgrouping - description: "A CAmkES application which tests for the various edge cases in grouping CAmkES components into single address spaces." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testgroupingcontrol - display_name: testgroupingcontrol - description: "A CAmkES application which tests whether CAmkES components with a control thread work correctly when grouped in a single address spaces." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testhardwareinterrupt - display_name: testhardwareinterrupt - description: "A CAmkES application which tests if an application containing an seL4HardwareInterrupt successfully compiles." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testhwdataportlrgpages - display_name: testhwdataportlrgpages - description: "A CAmkES application which tests whether or not large pages will be used to back a large dataport." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testnto1mmio - display_name: testnto1mmio - description: "A CAmkES application that tests if an N-to-1 MMIO connection to a piece of hardware functions correctly." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testnto1overload - display_name: testnto1overload - description: "A CAmKES application that tests if N-to-1 connections involving multiple ends from a single CAmkES component uses distinct caps." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testrefin - display_name: testrefin - description: "A CAmKES application that tests the 'refin' parameter function in CAmkES procedure interfaces." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testreplycapprotection - display_name: testreplycapprotection - description: "A CAmkES application that tests the reply cap protection functionality." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testsel4notification - display_name: testsel4notification - description: "A CAmkES application that tests the seL4Notification connector." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testsingleaddressspaceheap - display_name: testsingleaddressspaceheap - description: "A CAmkES application that tests that the heaps of CAmkES components that share a single address space do not overlap." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: teststringarrays - display_name: teststringarrays - description: "A CAmkES application that tests some unusual usages of string array parameters in procedure interfaces." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testsyscalls - display_name: testsyscalls - description: "A CAmkES application that serves as a testing sandbox for POSIX syscall functionality on CAmkES." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: testunderscorename - display_name: testunderscorename - description: "A CAmkES application that tests if CAmkES components can have interface names prefixed with an underscore." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: timeserver - display_name: timeserver - description: "A CAmkES application which demonstrates the use of the TimeServer componen fromthe global-components repository." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: uart - display_name: uart - description: "A CAmkES application which demonstrates a UART driver CAmkES component for the KZM platform." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - - name: vgatest - display_name: vgatest - description: "A CAmkES application which demonstrates a minimal implementation for a text mode VGA terminal." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-application - # - # global-components - # - - name: ClockServer - display_name: ClockServer - description: "A CAmkES component which abstracts over and multiplexes client accesses to clock devices on a platform." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: Ethdriver - display_name: Ethdriver - description: "A CAmkES component which abstracts over and multiplexes client accesses to an Ethernet device." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: FileServer - display_name: FileServer - description: "A CAmkES component which abstracts over and multiplexes client accesses to a CPIO-based file system." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: GPIOMUXServer - display_name: GPIOMUXServer - description: "A CAmkES component which abstracts over and multiplexes client accesses to a GPIO and pin multiplexer controller." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: PCIConfigIO - display_name: PCIConfigIO - description: "A CAmkES component which abstracts over and multiplexes client accesses to the PCI configuration space of a platform." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: PicoServer - display_name: PicoServer - description: "A CAmkES component which abstracts over and multiplexes client accesses to an IP stack, specifically, the PicoTCP TCP/IP stack." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: ResetServer - display_name: ResetServer - description: "A CAmkES component which abstracts over and multiplexes client accesses to a reset line controller." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: RTC - display_name: RTC - description: "A CAmkES component which abstracts over and multiplexes client accesses to a real-time clock device." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: SerialServer - display_name: SerialServer - description: "A CAmkES component which abstracts over and multiplexes client accesses to a serial device." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: TimeServer - display_name: TimeServer - description: "A CAmkES component which abstracts over and multiplexes client accesses to a timer device." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: VirtQueue - display_name: VirtQueue - description: "A stub CAmkES component which is used to help initialise virtqueue connections." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: camkes-connector-seL4Ethdriver - display_name: seL4Ethdriver - description: "CAmkES connector which is used to connect clients to the Ethdriver component's procedure interface." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4GlobalAsynchCallback - display_name: seL4GlobalAsynchCallback - description: "CAmkES connector which is used to make the underlying seL4 notification\ - capability available to the consuming side of the Event interface. \ - This also allows the coupling of callback function that is called upon\ - receiving an Event." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4GlobalAsync - display_name: seL4GlobalAsync - description: "CAmkES connector which is used to make the underlying seL4 notification capability available to the consuming side of the Event interface." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4MessageQueue - display_name: seL4MessageQueue - description: "CAmkES connector which allows the sending and queueing of user-defined messages from one component to another." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4MultiSharedData - display_name: seL4MultiSharedData - description: "CAmkES connector which allows multiple dataports to be connected to a single components and also provides multiplexed access across the dataports." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4RPCCallSignal - display_name: seL4RPCCallSignal - description: "CAmkES connector which bundles a procedure interface with an event interface." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4RPCDataport - display_name: seL4RPCDataport - description: "CAmkES connector which bundles a procedure interface with a dataport interface." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4RPCDataportSignal - display_name: seL4RPCDataportSignal - description: "CAmkES connector which bundles a procedure interface, event interface, and a dataport interface." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4RPCOverMultiSharedData - display_name: seL4RPCOverMultiSharedData - description: "CAmkES connector which uses shared memory to transfer data instead of the IPC buffer for procedure interfaces." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4SharedDataWithCaps - display_name: seL4SharedDataWithCaps - description: "CAmkES connector which allocates a shared memory region between components and also exposes the underlying frame caps." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4VirtQueues - display_name: seL4VirtQueues - description: "CAmkES connector which initialises a virtqueue connection between two components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: Findglobal-components - display_name: Findglobal-components - description: "CMake module for including the global-components components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: cmake-module - # - # camkes-tool - # - - name: camkes - display_name: camkes - description: "The implementation of the CAmkES framework." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-implementation - - name: libsel4camkes - display_name: libsel4camkes - description: "Supporting library for CAmkES components to access and manipulate CAmkES-allocated resources." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-library - - name: libcamkescakeml - display_name: libcamkescakeml - description: "Utility library for CakeML-based CAmkES components that contains functions and interfaces to allow interaction with a CAmkES system." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-library - - name: pc99-Serial - display_name: Serial - description: "Stub hardware CAmkES component that abstracts over a pc99-based serial device." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: pc99-Pit - display_name: PIT - description: "Stub hardware CAmkES component that abstracts over the x86 Programmable Interval Timer." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-component - - name: camkes-connector-seL4DirectCall - display_name: "seL4DirectCall" - description: "Used for RPC interfaces between grouped components. Each call becomes a direct function call." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4Notification - display_name: "seL4Notification" - description: "Event connector where an seL4 Notification object is used for sending events. On the receiving end, a callback handler can be registerd or a thread can block waiting for events." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4NotificationBind - display_name: "seL4NotificationBind" - description: "Similar event connector to seL4Notification but the receiver has bound the Notification to its TCB." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4NotificationNative - display_name: "seL4NotificationNative" - description: "Similar event connector to seL4Notification but the receiver end can only call Poll or Wait on notification object." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4NotificationQueue - display_name: "seL4NotificationQueue" - description: "seL4Endpoint object is used to queue notifications so that if the sender is sending faster than the receiver is receiving, unreceived events will accumulate in a counter." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4RPCCall - display_name: "seL4RPCCall" - description: "Used for RPC interfaces where parameters will be marshalled into and out of IPC buffers and calls ocurr over seL4Endpoint objects." - maintainer: "maintainer wanted" - status: "Supported. There is also a CakeML implementation for the receiving end." - component_type: camkes-connector - - name: camkes-connector-seL4DTBHardware - display_name: "seL4DTBHardware" - description: "Hardware connector to hardware component specified by a Device tree node. This will extract MMIO and potentially IRQ information for creating connections to the component." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4RPCCallNoType - display_name: "seL4RPCCallNoType" - description: "seL4 RPCCall connector but without requirement of single procedure interface. This allows a single receiver thread to handle multiple senders with different interfaces." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4SharedData - display_name: "seL4SharedData" - description: "seL4 Dataport connector. Creates a shared memory connection between components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4HardwareMMIO - display_name: "seL4HardwareMMIO" - description: "seL4 Dataport connector to MMIO region. Creates a MMIO mapping for device registers into a component." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4HardwareIOPort - display_name: "seL4HardwareIOPort" - description: "seL4 Procedure connector for x86 IOPorts. Provides functions for performing IOPort instructions via seL4 invocations." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4HardwareInterrupt - display_name: "seL4HardwareInterrupt" - description: "seL4 event connector for hardware interrupts. Provides interface for polling or blocking on interrupts and also for acknowledging IRQs." - maintainer: "maintainer wanted" - status: "Supported" - component_type: camkes-connector - - name: camkes-connector-seL4IOAPICHardwareInterrupt - display_name: "seL4IOAPICHardwareInterrupt" - description: "seL4 event connector for IOAPIC hardware interrupts. Specialised connector for dealing with IOAPIC interrupts." - maintainer: "maintainer wanted" - status: "Supported on x86" - component_type: camkes-connector - - - - name: Findcamkes-tool - display_name: Findcamkes-tool - description: "CMake module for including the camkes-tool components." - maintainer: "maintainer wanted" - status: "Supported" - component_type: cmake-module - # Manifests - - name: master.xml - display_name: master.xml - description: "CAmkES project manifest with all repositories from master branches." - maintainer: "maintainer wanted" - status: "Supported. Updated whenever project repository structure changes." - component_type: repo-manifest - - name: default.xml - display_name: default.xml - description: "CAmkES project manifest with all repositories pinned to last versions that passed all tests." - maintainer: "maintainer wanted" - status: "Supported. This gets updated automatically by continuous integration." - component_type: repo-manifest - - - -configurations: - - name: CAMKES_APP - display_name: "CAMKES_APP (STRING)" - description: "CAmkES application to build" - maintainer: "maintainer wanted" - status: "(Default: adder)" - component_type: camkes-option - - name: SIMULATION - display_name: "SIMULATION (BOOL)" - description: "Try and use simulable features" - maintainer: "maintainer wanted" - status: "(Default: ON)" - component_type: camkes-option - - name: RELEASE - display_name: "RELEASE (BOOL)" - description: "Performance optimized build" - maintainer: "maintainer wanted" - status: "(Default: OFF)" - component_type: camkes-option - - name: PLATFORM - display_name: "PLATFORM (STRING)" - description: "Platform to use" - maintainer: "maintainer wanted" - status: "(Default: x86_64)" - component_type: camkes-option diff --git a/_data/projects/capdl.yml b/_data/projects/capdl.yml deleted file mode 100644 index b9b66b11181..00000000000 --- a/_data/projects/capdl.yml +++ /dev/null @@ -1,173 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: capdl -display_name: CapDL -description: Collection of tools for generating, parsing and loading capdl specifications of systems -project_order: 4 - -repositories: - - org: seL4 - repo: capdl - -components: - # - # capdl-loader-app - # - - name: capdl-loader-app - display_name: capdl-loader-app - description: "The capDL initialiser for seL4." - maintainer: "seL4 Foundation" - status: "active" - component_type: capdl-loader-app - - # - # python-capdl-tool - # - - name: capdl - display_name: capdl - description: "The source code of the Python CapDL module." - maintainer: "seL4 Foundation" - status: "active" - component_type: python-capdl-tool - - # - # python-capdl-tool-example - # - - name: allocation - display_name: allocation - description: "The module contains an object and CSpace allocator. This example shows how these can be used for convenience." - status: "active" - component_type: python-capdl-tool-example - - - name: capdl-manipulation - display_name: capdl-manipulation - description: "An example of how to use the Python CapDL module" - status: "active" - component_type: python-capdl-tool-example - - - name: construct-address-space - display_name: construct-address-space - description: "An example of how to use the Python CapDL module" - status: "active" - component_type: python-capdl-tool-example - - - name: to-capdl - display_name: to-capdl - description: "An example of how to use the Python CapDL module" - status: "active" - component_type: python-capdl-tool-example - - # - # python-capdl-tool-test - # - - name: allocator - display_name: allocator - description: "A basic test of the functionality of the Python CapDL module" - status: "active" - component_type: python-capdl-tool-test - - - name: runall - display_name: runall - description: "A basic test of the functionality of the Python CapDL module" - status: "active" - component_type: python-capdl-tool-test - - - name: testelf - display_name: testelf - description: "A basic test of the functionality of the Python CapDL module" - status: "active" - component_type: python-capdl-tool-test - - - name: testmerge - display_name: testmerge - description: "A basic test of the functionality of the Python CapDL module" - status: "active" - component_type: python-capdl-tool-test - - # - # capDL-tool - # - - name: CapDL - display_name: CapDL - description: "Haskell source code of the capDL-tool" - status: "active" - component_type: capDL-tool - - # - # capDL-tool-example - # - - name: camkes-adder-arm - display_name: camkes-adder-arm - description: "One of the capDL-tool examples used as test files" - status: "active" - component_type: capDL-tool-example - - - name: cap-dist-elf-simpleserver - display_name: cap-dist-elf-simpleserver - description: "One of the capDL-tool examples used as test files" - status: "active" - component_type: capDL-tool-example - - - name: example-arm - display_name: example-arm - description: "One of the capDL-tool examples used as test files" - status: "active" - component_type: capDL-tool-example - - - name: example-ia32 - display_name: example-ia32 - description: "One of the capDL-tool examples used as test files" - status: "active" - component_type: capDL-tool-example - - - name: example - display_name: example - description: "One of the capDL-tool examples used as test files" - status: "active" - component_type: capDL-tool-example - - - name: hello-dump - display_name: hello-dump - description: "One of the capDL-tool examples used as test files" - status: "active" - component_type: capDL-tool-example - - - name: iwana-ia32 - display_name: iwana-ia32 - description: "One of the capDL-tool examples used as test files" - status: "active" - component_type: capDL-tool-example - # - # cdl_utils - # - - name: capdl_linker - display_name: capdl_linker - description: "The capdl_linker generates a final capDL spec from a input list of ELF files, and a record of which resources via objects and capabilities that the ELF file applications require." - status: "active" - component_type: cdl_utils - - - name: untyped_gen - display_name: untyped_gen - description: "The untyped_gen takes a description of the memory layout in a system from an seL4 build system artifact and generates the list of untyped objects that the kernel is expected to create." - status: "active" - component_type: cdl_utils - - # - # cdl_utils-templates - # - - name: cspace.template - display_name: cspace.template - description: "" - status: "active" - component_type: cdl_utils-templates - - # - # object_sizes - # - - name: object_sizes - display_name: object_sizes - description: "" - status: "active" - component_type: cmake-target-runs - diff --git a/_data/projects/dockerfiles.yml b/_data/projects/dockerfiles.yml deleted file mode 100644 index f810fe7ce54..00000000000 --- a/_data/projects/dockerfiles.yml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: dockerfiles -display_name: Dockerfiles -description: Dockerfiles defining the dependencies required to build seL4, CAmkES, and L4v -project_order: 9 - -repositories: - - org: sel4 - repo: seL4-CAmkES-L4v-dockerfiles diff --git a/_data/projects/docsite.yml b/_data/projects/docsite.yml deleted file mode 100644 index 9aa1fd8f48d..00000000000 --- a/_data/projects/docsite.yml +++ /dev/null @@ -1,7 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: docsite -display_name: seL4 Documentation website -description: For cooperatively developing and sharing documentation on seL4 -project_order: 9 diff --git a/_data/projects/elfloader.yml b/_data/projects/elfloader.yml deleted file mode 100644 index 42a84718c6f..00000000000 --- a/_data/projects/elfloader.yml +++ /dev/null @@ -1,103 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: elfloader -display_name: Elfloader -description: For preparing the hardware for seL4 on ARM and RISC-V -project_order: 5 - -repositories: - - org: seL4 - repo: sel4_tools - -components: - - name: arch-arm - display_name: arch-arm - description: "Bootstrapping and image loading for seL4 kernel and user applications on ARM" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-architecture - - name: arch-riscv - display_name: arch-riscv - description: "Bootstrapping and image loading for seL4 kernel and user applications on RISC-V" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-architecture - - name: ELF - display_name: "ELF file parser" - description: "Utility for parsing and getting information out of an ELF file" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-binary - - name: EFI - display_name: "UEFI boot loading" - description: "Utility for parsing and getting information out of an EFI file" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-binary - - name: drivers - display_name: Driver framework - description: "Device driver framework for the elfloader supported platforms" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-driver - - name: uart - display_name: UART - description: "UART drivers for various ARM platforms" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-driver - - name: smp - display_name: SMP - description: "SMP support on ARM using driver model" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-driver - - name: exynos5 - display_name: exynos5 - description: "Platform specific code for Samsung Exynos 5 SoCs" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-platform - - name: fvp - display_name: fvp - description: "Platform specific code for ARM Fixed Virtual Platforms" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-platform - - name: imx6 - display_name: imx6 - description: "Platform specific code for NXP i.MX6 Processors" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-platform - - name: imx7 - display_name: imx7 - description: "Platform specific code for NXP i.MX7 Processors" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-platform - - name: tk1 - display_name: tk1 - description: "Platform specific code for Nvidia Jatson TK1" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-platform - - name: tx2 - display_name: tx2 - description: "Platform specific code for Nvidia Jatson TX2" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-platform - - name: zynq7000 - display_name: zynq7000 - description: "Platform specific code for Xilinx Zynq-7000 SoC" - maintainer: "seL4 Foundation" - status: "active" - component_type: elfloader-platform - - name: utils - display_name: utils - description: "A set of MD5 and SHA256 cryptographic hash functions" - maintainer: "DornerWorks" - status: "inactive" - component_type: elfloader-utils diff --git a/_data/projects/hardware_hacks.yml b/_data/projects/hardware_hacks.yml deleted file mode 100644 index 74d862f41e9..00000000000 --- a/_data/projects/hardware_hacks.yml +++ /dev/null @@ -1,7 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: hardware_hacks -display_name: Hardware Hacks -description: Various bits and pieces to enable easier use of our hardware -project_order: 10 diff --git a/_data/projects/l4v.yml b/_data/projects/l4v.yml deleted file mode 100644 index 9d7d7b33786..00000000000 --- a/_data/projects/l4v.yml +++ /dev/null @@ -1,31 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: l4v -display_name: L4.verified -description: seL4 specification and proofs -project_order: 2 - -repositories: - - org: seL4 - repo: l4v - -useful_urls: - - label: "Trustworthy Systems seL4 verification project" - url: "https://trustworthy.systems/projects/seL4-verification/" - - label: "Commercial verification services (Proofcraft)" - url: "https://proofcraft.systems" - -roadmap: - - name: MCS - display_name: MCS Kernel extensions - description: Functional correctness proofs for a new scheduling model to support trustworthy mixed-criticality real-time systems. - assigned: Proofcraft - status: C verification ongoing - roadmap_type: in-progress - - name: AARCH64 - display_name: AArch64 port - description: Functional correctness proofs for the AArch64 port of seL4 completed. Integrity (access control) ongoing. - assigned: Proofcraft - status: Integrity verification to complete Q1/25 - roadmap_type: in-progress diff --git a/_data/projects/microkit.yml b/_data/projects/microkit.yml deleted file mode 100644 index 0c1715448fd..00000000000 --- a/_data/projects/microkit.yml +++ /dev/null @@ -1,110 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: microkit -display_name: Microkit -description: A simple operating system framework for developing systems on top of seL4 - -repositories: - - org: sel4 - repo: microkit - - org: au-ts - repo: microkit_tutorial - -sdk_downloads: - - version: 2.1.0 - sdks: - - label: "microkit-sdk-2.1.0-linux-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.1.0/microkit-sdk-2.1.0-linux-x86-64.tar.gz" - os: Linux - arch: x86-64 - - label: "microkit-sdk-2.1.0-linux-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.1.0/microkit-sdk-2.1.0-linux-aarch64.tar.gz" - os: Linux - arch: AArch64 - - label: "microkit-sdk-2.1.0-macos-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.1.0/microkit-sdk-2.1.0-macos-x86-64.tar.gz" - os: macOS - arch: x86-64 - - label: "microkit-sdk-2.1.0-macos-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.1.0/microkit-sdk-2.1.0-macos-aarch64.tar.gz" - os: macOS - arch: AArch64 - - version: 2.0.1 - sdks: - - label: "microkit-sdk-2.0.1-linux-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.0.1/microkit-sdk-2.0.1-linux-x86-64.tar.gz" - os: Linux - arch: x86-64 - - label: "microkit-sdk-2.0.1-linux-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.0.1/microkit-sdk-2.0.1-linux-aarch64.tar.gz" - os: Linux - arch: AArch64 - - label: "microkit-sdk-2.0.1-macos-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.0.1/microkit-sdk-2.0.1-macos-x86-64.tar.gz" - os: macOS - arch: x86-64 - - label: "microkit-sdk-2.0.1-macos-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.0.1/microkit-sdk-2.0.1-macos-aarch64.tar.gz" - os: macOS - arch: AArch64 - - version: 2.0.0 - sdks: - - label: "microkit-sdk-2.0.0-linux-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.0.0/microkit-sdk-2.0.0-linux-x86-64.tar.gz" - os: Linux - arch: x86-64 - - label: "microkit-sdk-2.0.0-linux-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.0.0/microkit-sdk-2.0.0-linux-aarch64.tar.gz" - os: Linux - arch: AArch64 - - label: "microkit-sdk-2.0.0-macos-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.0.0/microkit-sdk-2.0.0-macos-x86-64.tar.gz" - os: macOS - arch: x86-64 - - label: "microkit-sdk-2.0.0-macos-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/2.0.0/microkit-sdk-2.0.0-macos-aarch64.tar.gz" - os: macOS - arch: AArch64 - - version: 1.4.1 - sdks: - - label: "microkit-sdk-1.4.1-linux-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.4.1/microkit-sdk-1.4.1-linux-x86-64.tar.gz" - os: Linux - arch: x86-64 - - label: "microkit-sdk-1.4.1-macos-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.4.1/microkit-sdk-1.4.1-macos-x86-64.tar.gz" - os: macOS - arch: x86-64 - - label: "microkit-sdk-1.4.1-macos-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.4.1/microkit-sdk-1.4.1-macos-aarch64.tar.gz" - os: macOS - arch: AArch64 - - version: 1.4.0 - sdks: - - label: "microkit-sdk-1.4.0-linux-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.4.0/microkit-sdk-1.4.0-linux-x86-64.tar.gz" - os: Linux - arch: x86-64 - - label: "microkit-sdk-1.4.0-macos-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.4.0/microkit-sdk-1.4.0-macos-x86-64.tar.gz" - os: macOS - arch: x86-64 - - label: "microkit-sdk-1.4.0-macos-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.4.0/microkit-sdk-1.4.0-macos-aarch64.tar.gz" - os: macOS - arch: AArch64 - - version: 1.3.0 - sdks: - - label: "microkit-sdk-1.3.0-linux-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.3.0/microkit-sdk-1.3.0-linux-x86-64.tar.gz" - os: Linux - arch: x86-64 - - label: "microkit-sdk-1.3.0-macos-x86-64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.3.0/microkit-sdk-1.3.0-macos-x86-64.tar.gz" - os: macOS - arch: x86-64 - - label: "microkit-sdk-1.3.0-macos-aarch64.tar.gz" - url: "https://github.com/seL4/microkit/releases/download/1.3.0/microkit-sdk-1.3.0-macos-aarch64.tar.gz" - os: macOS - arch: aarch64 diff --git a/_data/projects/rust.yml b/_data/projects/rust.yml deleted file mode 100644 index c8a20569f7e..00000000000 --- a/_data/projects/rust.yml +++ /dev/null @@ -1,27 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: rust -display_name: Rust -description: seL4 Rust support -project_order: 11 - -repositories: - - org: sel4 - repo: rust-sel4 - - org: sel4 - repo: seL4-rust-tutorial - -releases: - - version: 1.0.0 - url: "https://github.com/seL4/rust-sel4/releases/tag/v1.0.0" - kernel_version: 13.0.0 - microkit_version: 1.3.0 - - version: 2.0.0 - url: "https://github.com/seL4/rust-sel4/releases/tag/v2.0.0" - kernel_version: 13.0.0 - microkit_version: 2.0.1 - - version: 3.0.0 - url: "https://github.com/seL4/rust-sel4/releases/tag/v3.0.0" - kernel_version: 14.0.0 - microkit_version: 2.1.0 diff --git a/_data/projects/sel4-tutorials.yml b/_data/projects/sel4-tutorials.yml deleted file mode 100644 index e4d45e8d74e..00000000000 --- a/_data/projects/sel4-tutorials.yml +++ /dev/null @@ -1,203 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: sel4-tutorials -display_name: seL4 tutorials -description: Collection of tutorials for learning to use seL4 and its ecosystem -project_order: 7 - -repositories: - - org: sel4 - repo: sel4-tutorials - - org: sel4 - repo: sel4-tutorials-manifest - -# The order of the components list determines the order of the tutorials in the -# tutorial nav side bar. The field section is used there to include groups of -# tutorials. - -components: - - name: hello-world - display_name: "Hello world" - description: "The first seL4 application to run" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: capabilities - display_name: "Capabilities" - description: "seL4 capabilities tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: untyped - display_name: "Untyped" - description: "Physical memory management tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: mapping - display_name: "Mapping" - description: "Virtual memory management tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: threads - display_name: "Threads" - description: "Threads on seL4 tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: ipc - display_name: "IPC" - description: "seL4 IPC tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: notifications - display_name: "Notifications" - description: "seL4 notification tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: interrupts - display_name: "Interrupts" - description: "Tutorial for accessing interrupts on seL4" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: fault-handlers - display_name: "Fault handling" - description: "Fault handling tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: mcs - display_name: "MCS extensions" - description: "MCS extension tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: sel4 - - - name: libraries-1 - display_name: "Initialisation & threading" - description: "Initialisation and threading tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: libraries - - - name: libraries-2 - display_name: "IPC" - description: "seL4 IPC and userspace paging management tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: libraries - - - name: libraries-3 - display_name: "Processes & Elf loading" - description: "Processes and ELF loading tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: libraries - - - name: libraries-4 - display_name: "Timer" - description: "Tutorial for using device drivers" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: libraries - - - name: hello-camkes-0 - display_name: "Hello CAmkES" - description: "The first CAmkES application to run" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: camkes - - - name: hello-camkes-1 - display_name: "Introduction to CAmkES" - description: "CAmkES ADL and RPC interface tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: camkes - - - name: hello-camkes-2 - display_name: "Events in CAmkES" - description: "CAmkES event and dataport tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: camkes - - - name: hello-camkes-timer - display_name: "CAmkES timer tutorial" - description: "CAmkES tutorial for accessing hardware" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: camkes - - - name: camkes-vm-linux - display_name: "CAmkES VM" - description: "Tutorial for creating VM guests and applications on seL4 using CAmkES" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: camkes - - - name: camkes-vm-crossvm - display_name: "CAmkES cross-VM connectors" - description: "Tutorial for using cross virtual machine connectors" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-application - section: camkes - - - name: libsel4tutorials - display_name: "libsel4tutorials" - description: "Utility Library for doing seL4 tutorials" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-library - - name: zynq_timer_driver - display_name: "Zynq-7000 timer driver" - description: "Zynq-7000 timer device driver used by CAmkES timer tutorial" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-driver - - name: docs - display_name: "docs" - description: "seL4 documents" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-docs - - name: tools - display_name: "tools" - description: "Utilities for generating and managing seL4 tutorials" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-tutorials-utils diff --git a/_data/projects/sel4.yml b/_data/projects/sel4.yml deleted file mode 100644 index 67c60df26dd..00000000000 --- a/_data/projects/sel4.yml +++ /dev/null @@ -1,1124 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: sel4 -display_name: seL4 -description: The seL4 microkernel -project_order: 1 - -repositories: - - org: seL4 - repo: sel4 - -configurations: - - - name: KernelVerificationBuild - display_name: "KernelVerificationBuild" - description: "When enabled this configuration option prevents the usage of any other options that \ - would compromise the verification story of the kernel. Enabling this option does NOT \ - imply you are using a verified kernel." - maintainer: "seL4 Foundation" - status: "Always set. (Default: ON)" - component_type: generic - - name: KernelIsMCS - display_name: "KernelIsMCS" - description: "Enable MCS feature for seL4." - maintainer: "seL4 Foundation" - status: "Available on all MCS supported platforms (Default: Off)" - component_type: generic - - name: KernelRootCNodeSizeBits - display_name: "KernelRootCNodeSizeBits" - description: "Root CNode Size (2^n slots) \ - The acceptable range is 12-27 and 12-26, for 32-bit and 64-bit respectively. \ - The root CNode needs at least enough space to contain up to BI_CAP_DYN_START." - maintainer: "seL4 Foundation" - status: "Always set (Default: 12)" - component_type: generic - - name: KernelRetypeFanOutLimit - display_name: "KernelRetypeFanOutLimit" - description: "Maximum number of objects that can be created in a single Retype() invocation." - maintainer: "seL4 Foundation" - status: "Always set. (Default: 256)" - component_type: generic - - name: KernelMaxNumBootinfoUntypedCaps - display_name: "KernelMaxNumBootinfoUntypedCaps" - description: "Max number of untyped capabilities given to initial boot thread. Additional caps - won't be handed to the system." - maintainer: "seL4 Foundation" - status: "Always set. (Default: 230 caps)" - component_type: generic - - - name: KernelTimerTickMS - display_name: "KernelTimerTickMS" - description: "Kernel timer tick period in milliseconds." - maintainer: "seL4 Foundation" - status: "Only available on non-MCS kernels. (Default: 2 milliseconds)" - component_type: scheduling - - name: KernelTimeSlice - display_name: "KernelTimeSlice" - description: "Number of kernel timer ticks until a thread is preempted." - maintainer: "seL4 Foundation" - status: "Only available on non-MCS kernels. (Default: 5 ticks)" - component_type: scheduling - - name: KernelBootThreadTimeSlice - display_name: "KernelBootThreadTimeSlice" - description: "Budget of booth thread: Number of milliseconds until the boot thread is preempted." - maintainer: "seL4 Foundation" - status: "Available on all MCS supported platforms. (Default: 5 milliseconds)" - component_type: scheduling - - name: KernelMaxNumWorkUnitsPerPreemption - display_name: "KernelMaxNumWorkUnitsPerPreemption" - description: "Maximum number of work units (delete/revoke iterations) until the kernel checks for \ - pending interrupts (and preempts the currently running syscall if interrupts are pending)." - maintainer: "seL4 Foundation" - status: "Always set. (Default: 100)" - component_type: scheduling - - name: KernelResetChunkBits - display_name: "KernelResetChunkBits" - description: "Maximum size in bits of chunks of memory to zero before checking a preemption point." - maintainer: "seL4 Foundation" - status: "Always set. (Default: 8 bits)" - component_type: scheduling - - name: KernelNumDomains - display_name: "KernelNumDomains" - description: "The number of scheduler domains in the system" - maintainer: "seL4 Foundation" - status: "Always set. (Default: 1 domain)" - component_type: scheduling - - name: KernelDomainSchedule - display_name: "KernelDomainSchedule" - description: "A C file providing the symbols ksDomSchedule and ksDomeScheudleLength \ - to be linked with the kernel as a scheduling configuration." - maintainer: "seL4 Foundation" - status: "Always set. (Default: src/config/default_domain.c)" - component_type: scheduling - - name: KernelNumPriorities - display_name: "KernelNumPriorities" - description: "The number of priority levels per domain." - maintainer: "seL4 Foundation" - status: "Always set, Valid range 1-256. (Default: 256)" - component_type: scheduling - - name: KernelWcetScale - display_name: "KernelWcetScale" - description: "Multiplier to scale kernel WCET estimate by: the kernel WCET estimate \ - is used to ensure a thread has enough budget to get in and out of the \ - kernel. When running in a simulator the WCET estimate, which is tuned \ - for hardware, may not be sufficient. This option provides a hacky knob \ - that can be fiddled with when running inside a simulator." - maintainer: "seL4 Foundation" - status: "Enabled if KernelIsMCS. (Default: 1)" - component_type: scheduling - - - name: KernelDebugBuild - display_name: "KernelDebugBuild" - description: "Enable debug facilities (symbols and assertions) in the kernel" - maintainer: "seL4 Foundation" - status: "Disabled if KernelVerificationBuild is set. (Default: ON)" - component_type: debug - - name: HardwareDebugAPI - display_name: "HardwareDebugAPI" - description: "Builds the kernel with support for a userspace debug API, which can \ - allows userspace processes to set breakpoints, watchpoints and to \ - single-step through thread execution." - maintainer: "seL4 Foundation" - status: "Requires platform support. (Default: Off)" - component_type: debug - - name: KernelPrinting - display_name: "KernelPrinting" - description: "Allow the kernel to print out messages to the serial console during bootup and execution." - maintainer: "seL4 Foundation" - status: "Disabled if KernelVerificationBuild is set. (Default: Set to initial value of KernelDebugBuild)" - component_type: debug - - name: KernelIRQReporting - display_name: "KernelIRQReporting" - description: "seL4 does not properly check for and handle spurious interrupts. This can result \ - in unnecessary output from the kernel during debug builds. If you are CERTAIN these \ - messages are benign then use this config to turn them off." - maintainer: "seL4 Foundation" - status: "Enabled if KernelPrinting is set. (Default: On)" - component_type: debug - - name: KernelColourPrinting - display_name: "KernelColourPrinting" - description: "In debug mode, seL4 prints diagnostic messages to its serial output describing, \ - e.g., the cause of system call errors. This setting determines whether ANSI escape \ - codes are applied to colour code these error messages. You may wish to disable this \ - setting if your serial output is redirected to a file or pipe." - maintainer: "seL4 Foundation" - status: "Enabled if KernelPrinting is set. (Default: On)" - component_type: debug - - name: KernelUserStackTraceLength - display_name: "KernelUserStackTraceLength" - description: "On a double fault the kernel can try and print out the users stack to aid \ - debugging. This option determines how many words of stack should be printed." - maintainer: "seL4 Foundation" - status: "Enabled if KernelPrinting is set. (Default: 16)" - component_type: debug - - name: KernelDebugDisablePrefetchers - display_name: "KernelDebugDisablePrefetchers" - description: "On ia32 platforms, this option disables the L2 hardware prefetcher, the L2 adjacent \ - cache line prefetcher, the DCU prefetcher and the DCU IP prefetcher. On the cortex \ - a53 this disables the L1 Data prefetcher." - maintainer: "seL4 Foundation" - status: "Available if KernelArchX86 OR KernelPlatformHikey is set. (Default: Off)" - component_type: debug - - - - - name: KernelFastpath - display_name: "KernelFastpath" - description: "Enable IPC fastpath. Can be disabled for performance analyses." - maintainer: "seL4 Foundation" - status: "Always set. (Default: ON)" - component_type: profiling - - name: KernelFPUMaxRestoresSinceSwitch - display_name: "KernelFPUMaxRestoresSinceSwitch" - description: "This option is a heuristic to attempt to detect when the FPU is no longer in use, \ - allowing the kernel to save the FPU state out so that the FPU does not have to be \ - enabled/disabled every thread switch. Every time we restore a thread and there is \ - active FPU state, we increment this setting and if it exceeds this threshold we \ - switch to the NULL state." - maintainer: "seL4 Foundation" - status: "Only set if the system is using the FPU. (Default: 64 switches)" - component_type: profiling - - name: KernelBenchmarks - display_name: "KernelBenchmarks" - description: "Enable benchamrks including logging and tracing info. \ - Setting this value > 1 enables a 1MB log buffer and functions for extracting data from it \ - at user level. NOTE this is only tested on the sabre and will not work on platforms with < 512mb memory. \ - This is not fully implemented for x86.
\ - **none** -> No Benchmarking features enabled.
\ - **generic** -> Enable global benchmarks config variable with no specific features.
\ - **track_kernel_entries** -> Log kernel entries information including timing, number of invocations and arguments for \ - system calls, interrupts, user faults and VM faults.
\ - **tracepoints** -> Enable manually inserted tracepoints that the kernel will track time consumed between.
\ - **track_utilisation** -> Enable the kernel to track each thread's utilisation time." - maintainer: "seL4 Foundation" - status: "Disabled if KernelVerificationBuild is set. (Default: None)" - component_type: profiling - - name: KernelMaxNumTracePoints - display_name: "KernelMaxNumTracePoints" - description: "The maximum number of different trace point identifiers which can be used. Use `TRACE_POINT_START(k)` \ - and `TRACE_POINT_STOP(k)` macros for recording data, where k is an integer between 0 and this value - 1" - maintainer: "seL4 Foundation" - status: "Requires KernelBenchmarksTracepoints is set. (Default: 1)" - component_type: profiling - - name: KernelOptimisation - display_name: "KernelOptimisation" - description: "Select the kernel optimisation level. This should only be changed as part of performance analysis. -O2 is required for normal use." - maintainer: "seL4 Foundation" - status: "Always set. (Default: -O2)" - component_type: profiling - - name: KernelFWholeProgram - display_name: "KernelFWholeProgram" - description: "Enable -fwhole-program when linking kernel. This should work modulo gcc bugs, which \ - are not uncommon with -fwhole-program. Consider this feature experimental!" - maintainer: "seL4 Foundation" - status: "Always set. (Default: OFF)" - component_type: profiling - - name: KernelDangerousCodeInjection - display_name: "KernelDangerousCodeInjection" - description: "Adds a system call that allows users to specify code to be run in kernel mode. \ - Useful for profiling." - maintainer: "seL4 Foundation" - status: "Can only be set if: NOT KernelARMHypervisorSupport;NOT KernelVerificationBuild;NOT KernelPlatformHikey;NOT KernelSkimWindow. (Default: Off)" - component_type: profiling - - name: KernelStackBits - display_name: "KernelStackBits" - description: "This describes the log2 size of the kernel stack. Great care should be taken as \ - there is no guard below the stack so setting this too small will cause random \ - memory corruption" - maintainer: "seL4 Foundation" - status: "Always set. (Default: 12 bits)" - component_type: profiling - - - name: KernelPlatform - display_name: "KernelPlatform" - description: "Hardware platform to target. This setting influences other kernel configuration values." - maintainer: "seL4 Foundation" - status: 'See list of supported platforms.' - component_type: platform - - name: KernelArch - display_name: "KernelArch" - description: "Architecture to use when building the kernel." - maintainer: "seL4 Foundation" - status: "Supported values: (arm, x86, riscv)." - component_type: platformform - - name: KernelSel4Arch - display_name: "KernelSel4Arch" - description: "Architecture mode for building the kernel." - maintainer: "seL4 Foundation" - status: "Supported values: (aarch32, aarch64, arm_hyp, riscv32, riscv64, x86_64, ia32)." - component_type: platform - - name: KernelHaveFPU - display_name: "KernelHaveFPU" - description: "Set if the platform and toolchain supports floating point unit." - maintainer: "seL4 Foundation" - status: "Set on x86, Unset on RISC-V, toolchain + verirification dependent on Arm" - component_type: platform - - name: KernelMaxNumNodes - display_name: "KernelMaxNumNodes" - description: "Max number of CPU cores to boot." - maintainer: "seL4 Foundation" - status: "Always set. (Default: 1 node)" - component_type: platform - - - name: KernelX86MicroArch - display_name: "KernelX86MicroArch" - description: "Select the x86 micro architecture." - maintainer: "seL4 Foundation" - status: "x86 Option. Supported values:nehalem, generic, westmere, sandy, ivy, haswell, broadwell, skylake. (Default: nehalem)" - component_type: platform-x86 - - name: KernelIRQController - display_name: "KernelIRQController" - description: "Select the IRQ controller seL4 will use. Code for others may still be included if \ - needed to disable at run time." - maintainer: "seL4 Foundation" - status: "x86 Option. Supported values: PIC, IOAPIC. (Default: IOAPIC)" - component_type: platform-x86 - - name: KernelMaxNumIOAPIC - display_name: "KernelMaxNumIOAPIC" - description: "Configure the maximum number of IOAPIC controllers that can be supported. SeL4 \ - will detect IOAPICs regardless of whether the IOAPIC will actually be used as \ - the final IRQ controller." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: 1)" - component_type: platform-x86 - - name: KernelLAPICMode - display_name: "KernelLAPICMode" - description: "Select the mode local APIC will use: XAPIC, X2APIC " - maintainer: "seL4 Foundation" - status: "x86 Option. Not all machines support X2APIC mode (Default: XAPIC)" - component_type: platform-x86 - - name: KernelUseLogcalIDs - display_name: "KernelUseLogcalIDs" - description: "Use logical IDs to broadcast IPI between cores. Not all machines support logical \ - IDs. In xAPIC mode only 8 cores can be addressed using logical IDs." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: OFF)" - component_type: platform-x86 - - name: KernelCacheLnSz - display_name: "KernelCacheLnSz" - description: "Define cache line size for x86." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: 64)" - component_type: platform-x86 - - name: KernelVTX - display_name: "KernelVTX" - description: "VT-x support compiled into the kernel." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: Off)" - component_type: platform-x86 - - name: KernelIOMMU - display_name: "KernelIOMMU" - description: "IOMMU support for VT-d enabled chipset." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: ON)" - component_type: platform-x86 - - name: KernelMaxRMRREntries - display_name: "KernelMaxRMRREntries" - description: "Sets the maximum number of Reserved Memory Region Reporting structures we support \ - recording from the ACPI tables. These structures are used for setting up passthrouh IOMMU mappings \ - for legacy devices." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: 32)" - component_type: platform-x86 - - name: KernelMaxVPIDs - display_name: "KernelMaxVPIDs" - description: "The kernel maintains a mapping of 16-bit VPIDs to VCPUs. This option should be \ - sized as small as possible to save memory, but be at least the number of VCPUs that \ - will be run for optimum performance." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: 1024)" - component_type: platform-x86 - - name: KernelHugePage - display_name: "KernelHugePage" - description: "Add support for 1GB huge page." - maintainer: "seL4 Foundation" - status: "x86 Option. Not all recent processor models support this feature (Default: On)" - component_type: platform-x86 - - name: KernelSupportPCID - display_name: "KernelSupportPCID" - description: "Add support for PCIDs (aka hardware ASIDs)." - maintainer: "seL4 Foundation" - status: "x86_64 Option. Not all recent processor models support this feature (Default: On)" - component_type: platform-x86 - - name: KernelSyscall - display_name: "KernelSyscall" - description: "Which syscall method that the kernel supports. This \ - config should be set to the most efficient one that is support by the hardware the \ - system will run on." - maintainer: "seL4 Foundation" - status: "x86 Option. The kernel only ever supports one method at a time: syscall, sysenter (Default: syscall)" - component_type: platform-x86 - - name: KernelFPU - display_name: "KernelFPU" - description: "Choose the method that FPU state is stored in. This \ - directly affects the method used to save and restore it.
\ - **FXSAVE** -> This chooses the legacy 512-byte region used by the fxsave and fxrstor functions
\ - **XSAVE** -> This chooses the variable xsave region, and enables the ability to use any \ - of the xsave variants to save and restore. The actual size of the region is dependent on \ - the features enabled." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: XSAVE)" - component_type: platform-x86 - - name: KernelXSave - display_name: "KernelXSave" - description: "The XSAVE area supports multiple instructions to save - and restore to it. These instructions are dependent upon specific CPU support. See Chapter 13 of Volume \ - 1 of the Intel Architectures SOftware Developers Manual for discussion on the init and modified \ - optimizations.
\ - **XSAVE** -> Original XSAVE instruction. This is the only XSAVE instruction that is guaranteed to exist if \ - XSAVE is present
\ - **XSAVEC** -> Save state with compaction. This compaction has to do with minimizing the total size of \ - XSAVE buffer, if using non contiguous features, XSAVEC will attempt to use the init optimization \ - when saving
\ - **XSAVEOPT** -> Save state taking advantage of both the init optimization and modified optimization
\ - **XSAVES** -> Save state taking advantage of the modified optimization. This instruction is only \ - available in OS code, and is the preferred save method if it exists." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: XSAVEOPT)" - component_type: platform-x86 - - name: KernelXSaveFeatureSet - display_name: "KernelXSaveFeatureSet" - description: "XSAVE can save and restore the state for various features \ - through the use of the feature mask. This config option represents the feature mask that we want to \ - support. The CPU must support all bits in this feature mask. Current known bits are
\ - 0 - FPU
\ - 1 - SSE
\ - 2 - AVX
\ - FPU and SSE is guaranteed to exist if XSAVE exists." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: 3)" - component_type: platform-x86 - - name: KernelFSGSBase - display_name: "KernelFSGSBase" - description: "There are three ways to to set FS/GS base addresses: \ - IA32_FS/GS_GDT, IA32_FS/GS_BASE_MSR, and fsgsbase instructions. \ - IA32_FS/GS_GDT and IA32_FS/GS_BASE_MSR are availble for 32-bit. \ - IA32_FS/GS_BASE_MSR and fsgsbase instructions are available for 64-bit." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default x86_64: fsgsbase, ia32: gdt)" - component_type: platform-x86 - - name: KernelMultibootGFXMode - display_name: "KernelMultibootGFXMode" - description: "The type of graphics mode to request from the boot loader. This is encoded into the \ - multiboot header and is merely a hint, the boot loader is free to ignore or set some \ - other mode" - maintainer: "seL4 Foundation" - status: "x86 Option. Options: none, text, linear (Default: none)" - component_type: platform-x86 - - name: KernelMultibootGFXDepth - display_name: "KernelMultibootGFXDepth" - description: "The bits per pixel of the linear graphics mode ot request. Value of zero indicates \ - no preference." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: 32)" - component_type: platform-x86 - - name: KernelMultibootGFXWidth - display_name: "KernelMultibootGFXWidth" - description: "The width of the graphics mode to request. For a linear graphics mode this is the \ - number of pixels. For a text mode this is the number of characters, value of zero \ - indicates no preference." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: 0)" - component_type: platform-x86 - - name: KernelMultibootGFXHeight - display_name: "KernelMultibootGFXHeight" - description: "The height of the graphics mode to request. For a linear graphics mode this is the \ - number of pixels. For a text mode this is the number of characters, value of zero \ - indicates no preference." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: 0)" - component_type: platform-x86 - - name: KernelMultiboot1Header - display_name: "KernelMultiboot1Header" - description: "Inserts a header that indicates to the bootloader that the kernel supports a multiboot 1 boot header" - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: On)" - component_type: platform-x86 - - name: KernelMultiboot2Header - display_name: "KernelMultiboot2Header" - description: "Inserts a header that indicates to the bootloader that the kernel supports a multiboot 2 boot header. \ - This is can be enabled together with a multiboot 1 header and the boot loader may use either one" - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: On)" - component_type: platform-x86 - - name: KernelSkimWindow - display_name: "KernelSkimWindow" - description: "Prevent against the Meltdown vulnerability by using a reduced Static Kernel - Image and Micro-state window instead of having all kernel state in the kernel window. - This only needs to be enabled if deploying to a vulnerable processor" - maintainer: "seL4 Foundation" - status: "x86_64 Option. (Default: On)" - component_type: platform-x86 - - name: KernelExportPMCUser - display_name: "KernelExportPMCUser" - description: "Grant user access to the Performance Monitoring Counters. - This allows the user to read performance counters, although - not control what the counters are and whether or not they - are counting. Nevertheless whilst this is useful for - evalulating performance this option opens timing and covert - channels." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: Off)" - component_type: platform-x86 - - name: KernelExportPMCUser - display_name: "KernelExportPMCUser" - description: "Grant user access to the Performance Monitoring Counters. - This allows the user to read performance counters, although - not control what the counters are and whether or not they - are counting. Nevertheless whilst this is useful for - evalulating performance this option opens timing and covert - channels." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: Off)" - component_type: platform-x86 - - name: KernelX86DangerousMSR - display_name: "KernelX86DangerousMSR" - description: "rdmsr/wrmsr kernel interface. Provides a syscall interface for reading and writing arbitrary MSRs. - This is extremely dangerous as no checks are performed and exists - to aid debugging and benchmarking." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: Off)" - component_type: platform-x86 - - name: KernelX86IBRSMode - display_name: "KernelX86IBRSMode" - description: "Indirect Branch Restricted Speculation mode - Used to prevent a user from manipulating the branch predictor to manipulate speculative - execution of other processes. On current processors IBRS has a prohibitive performance - penalty and it is recommended that it be disabled such that software mitigations are - used instead. Software mitigation is done by disabling jump tables (the only form of - indirect jump in seL4 except for 'ret') and flushing the RSB on vmexit. Flushing the RSB - at other times is not needed as seL4 does not switch kernel stacks and so is not - vulnerable to RSB underflow. The STIBP is essentially software mitigation but enables - the single thread isolation for branch predictions. This is only needed if attempting - to protect user level process from each other in a multicore environment." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: ibrs_none)" - component_type: platform-x86 - - name: KernelX86IBPBOnContextSwitch - display_name: "KernelX86IBPBOnContextSwitch" - description: "Performs a IBPB on every context switch to prevent Spectre attacks between user - processes. This is extremely expensive and is recommended you only turn this on - if absolutely necessary. - Note that in a multicore environment you should also enable STIBP to prevent - other cores retraining the branch predictor even after context switch." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: OFF)" - component_type: platform-x86 - - name: KernelX86RSBOnContextSwitch - display_name: "KernelX86RSBOnContextSwitch" - description: "Flushes the RSB on context switch to prevent Spectre attacks between user processes. - Whilst not nearly as expensive as an IBPB it is not enabled by default as it is - largely pointless to flush the RSB without also doing an IBPB as the RSB is already - a harder attack vector." - maintainer: "seL4 Foundation" - status: "x86 Option. (Default: OFF)" - component_type: platform-x86 - - name: KernelDebugDisableL2Cache - display_name: "KernelDebugDisableL2Cache" - description: "Do not enable the L2 cache on startup for debugging purposes." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelDebugDisableL1ICache - display_name: "KernelDebugDisableL1ICache" - description: "Do not enable the L1 instruction cache on startup for debugging purposes." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelDebugDisableL1DCache - display_name: "KernelDebugDisableL1DCache" - description: "Do not enable the L1 data cache on startup for debugging purposes." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelDebugDisableBranchPrediction - display_name: "KernelDebugDisableBranchPrediction" - description: "Do not enable branch prediction (also called program flow control) on startup - for debugging purposes. This makes execution time more deterministic at the - expense of dramatically decreasing performance." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelArmHypervisorSupport - display_name: "KernelArmHypervisorSupport" - description: "Utilise Arm virtualisation extensions to build the kernel as a hypervisor." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: the value of ARM_HYP (TRUE or FALSE))" - component_type: platform-arm - - name: KernelArmHypervisorSupport - display_name: "KernelArmHypervisorSupport" - description: "Utilise Arm virtualisation extensions to build the kernel as a hypervisor." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: the value of ARM_HYP (TRUE or FALSE))" - component_type: platform-arm - - name: KernelArmHypEnableVCPUCP14SaveAndRestore - display_name: "KernelArmHypEnableVCPUCP14SaveAndRestore" - description: "The kernel does not save or restore VCPUs' CP14 accesses. - As a result, accessing VPU threads' CP14 context triggers a trap, - which allows the kernel to intercept the access and deliver it as a fault message - to the VM monitor." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: ON)" - component_type: platform-arm - - name: KernelArmErrata430973 - display_name: "KernelArmErrata430973" - description: "Enable a workaround for 430973 Cortex-A8 (r1p0..r1p2) erratum - An error occurs if an instruction contains Arm/Thumb interworking branch - that is replaced by a different instruction from the same virtual address." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelArmErrata773022 - display_name: "KernelArmErrata773022" - description: "Enable a workaround for 773022 Cortex-A15 (r0p0..r0p4) erratum. - An error occurs on rare sequences of instructions which results on the loop buffer delivering - incorrect instructions. The workaround is to disable the loop buffer." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelArmSMMU - display_name: "KernelArmSMMU" - description: "Enable the System MMU on the Tegra TK1 SoC." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelArmEnableA9Prefetcher - display_name: "KernelArmEnableA9Prefetcher" - description: "Enable the prefetcher on Arm Cortex-A9 core. - The Cortex-A9 has L1 and L2 prefetchers, which are disabled by default. - This config option enables those prefetchers, requiring the kernel to be executed in the secure mode. - Arm document indicates that the bit used for enabling those prefetchers is no longer supported - from version r4p1 of the Cortex-A9. However, the correctness of that is uncertain." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelArmExportPMUUser - display_name: "KernelArmExportPMUUser" - description: "Grant user access to the performance monitoring unit. While useful for - benchmarking, this option opens the possibility of timing channels." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelArmDisableWFIWFETraps - display_name: "KernelArmDisableWFIWFETraps" - description: "Disable the trapping of WFI and WFE instructions by configuring the - Hyp Configuration Registor (HCR) of a VCPU." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelARMSMMUInterruptEnable - display_name: "KernelARMSMMUInterruptEnable" - description: "Enable system MMU (SMMU) interrupts. System MMU interrupts currently only serve for debugging purpose because - they are not forwarded to user level. Enabling this will - cause some SMMU fault types to print out a message in the kernel. High frequency faults - can result in all time spent in the kernel printing fault messages." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: OFF)" - component_type: platform-arm - - name: KernelAArch32FPUEnableContextSwitch - display_name: "KernelAArch32FPUEnableContextSwitch" - description: "Enable hardware VFP and SIMD context switch. - This enables the VFP and SIMD context switch on platforms with hardware support, - allowing the user to execute hardware VFP and SIMD operations in a - multithreading environment, instead of relying on - software emulation of FPU/VFP from the C library (e.g. mfloat-abi=soft)." - maintainer: "seL4 Foundation" - status: "Arm option. (Default: ON)" - component_type: platform-arm - -features: - - name: arm - display_name: "Arm" - description: "Arm architecture support." - maintainer: "seL4 Foundation" - status: "ArmV6, ArmV7, ArmV8, 32 and 64bit" - component_type: architecture - - name: x86 - display_name: "x86" - description: "x86 architecture support." - maintainer: "seL4 Foundation" - status: "ia32 and x86_64 (32/64bit)" - component_type: architecture - - name: riscv - display_name: "RISC-V" - description: "RISC-V architecture support." - maintainer: "seL4 Foundation" - status: "riscv32, riscv64, imac extensions, sv32 and sv39 virtual memory" - component_type: architecture - - name: aarch64-hyp - display_name: "Aarch64 hyp" - description: "Support for running seL4 in EL2, Aarch64 on ArmV8" - maintainer: "seL4 Foundation" - status: "Supported on the following platforms: FIXME" - component_type: hyp-support - - name: aarch32-hyp - display_name: "arm hyp" - description: "Support for running seL4 in hyp mode, on ArmV7" - maintainer: "seL4 Foundation" - status: "Supported on the following platforms: FIXME" - component_type: hyp-support - - name: intel-vtx - display_name: "Intel VT-x" - description: "Support for using x86 hardware virtualization on seL4." - maintainer: "seL4 Foundation" - status: "Supported on the following platforms: FIXME" - component_type: hyp-support - - name: riscv-hyp - display_name: "RISC-V hyp mode" - description: "Support for utilizing RISC-V Hyp extensions on seL4. [More information](https://github.com/sel4proj/sel4-riscv-vmm-manifest/blob/master/README.md)" - maintainer: "seL4 Foundation" - status: "Experimental branches exist for RISCV HE v0.6" - component_type: hyp-support - - name: arm-smp - display_name: "Arm multicore support" - description: "Support for Arm SMP" - maintainer: "seL4 Foundation" - status: "Supported on the following platforms/cores: FIXME" - component_type: smp-support - - name: x86-smp - display_name: "x86 multicore support" - description: "Support for x86 SMP" - maintainer: "seL4 Foundation" - status: "Supported on the following platforms/cores: FIXME" - component_type: smp-support - - name: riscv-smp - display_name: "RISC-V multicore support" - description: "Support for RISC-V SMP" - maintainer: "seL4 Foundation" - status: "Supported on the following platforms/cores: HiFive Unleashed" - component_type: smp-support - - name: call-fastpath - display_name: "seL4_Call() Fastpath" - description: "seL4_Call operations that meet certain criteria will use the fastpath." - maintainer: "seL4 Foundation" - status: "Supported on all platforms" - component_type: fastpath-support - - name: replyrecv-fastpath - display_name: "seL4_ReplyRecv() Fastpath" - description: "seL4_ReplyRecv operations that meet certain criteria will use the fastpath." - maintainer: "seL4 Foundation" - status: "Supported on all platforms" - component_type: fastpath-support - - name: intel-vtd - display_name: "Intel VT-d" - description: "x86 IOMMU support on seL4 via additional page table object definitions." - maintainer: "seL4 Foundation" - status: "Supported on the following platforms/cores: FIXME" - component_type: iommu-support - - name: tk1-smmu - display_name: "Jetson TK1 SMMU" - description: "Supported on seL4 via additional page table object definitions." - maintainer: "seL4 Foundation" - status: "Only applies to Jetson TK1 platform." - component_type: iommu-support - - name: smmuv2 - display_name: "Arm SMMUv2" - description: "Generic Arm SMMU support on seL4 via additional page table object definitions." - maintainer: "seL4 Foundation" - status: "Under development." - component_type: iommu-support - - name: mcs-verification - display_name: "MCS Verification support" - description: "Verification of the MCS extenstions to seL4" - maintainer: "seL4 Foundation" - status: "Under development." - component_type: mcs-support - - name: mcs-hyp - display_name: "MCS Hyp support" - description: "MCS + Hyp extensions on seL4" - maintainer: "seL4 Foundation" - status: "?." - component_type: mcs-support - - name: mcs-smp - display_name: "MCS SMP support" - description: "MCS + SMP on seL4" - maintainer: "seL4 Foundation" - status: "?." - component_type: mcs-support - - name: mcs-fastpath - display_name: "MCS Fastpath support" - description: "Fastpath operations require a Scheduling Context donation to occur." - maintainer: "seL4 Foundation" - status: "?." - component_type: mcs-support - - -components: - - name: sel4-microkernel - display_name: "seL4 Microkernel" - description: "Formally verified operating system kernel" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4 - - name: libsel4 - display_name: "libsel4" - description: "seL4 user level API bindings" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-library - - name: manual - display_name: "seL4 Manual" - display_name_url: https://sel4.systems/Info/Docs/seL4-manual-latest.pdf - description: "seL4 Reference Manual. Released for each seL4 version." - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4-manual - - name: sel4-deps - display_name: "sel4-deps python package" - description: "Python meta package for seL4 python dependencies" - maintainer: "seL4 Foundation" - status: "active" - component_type: python-package - - name: FindseL4.cmake - display_name: "FindseL4 CMake module" - description: "CMake module for importing seL4 into buildsystem" - maintainer: "seL4 Foundation" - status: "active" - component_type: cmake-module - - name: ti,am33xx-intc - display_name: "ti,am33xx-intc" - description: "am335x interrupt controller seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by am335x seL4 platforms" - component_type: kernel-driver-irq - - name: brcm,bcm2836-armctrl-ic - display_name: "brcm,bcm2836-armctrl-ic" - description: "Broadcom Raspberry Pi interrupt controller seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the rpi3 seL4 platform" - component_type: kernel-driver-irq - - name: hifive-plic - display_name: "hifive-plic" - description: "HiFive interrupt controller seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the hifive seL4 platform" - component_type: kernel-driver-irq - - name: ti,omap3-intc - display_name: "ti,omap3-intc" - description: "omap3 interrupt controller seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the omap3 seL4 platform" - component_type: kernel-driver-irq - - name: arm,gic-v2 - display_name: "arm,gic-v2" - description: "Arm GICv2 interrupt controller seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by several seL4 platforms" - component_type: kernel-driver-irq - - name: arm,gic-v3 - display_name: "arm,gic-v3" - description: "Arm GICv2 interrupt controller seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by several seL4 platforms" - component_type: kernel-driver-irq - - name: x86,pic - display_name: "x86,pic" - description: "Intel 8259 Programmable Interrupt Controller (PIC) seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the pc99 seL4 platform" - component_type: kernel-driver-irq - - name: x86,ioapic - display_name: "x86,ioapic" - description: "Intel IOAPIC seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the pc99 seL4 platform" - component_type: kernel-driver-irq - - name: x86,lapic - display_name: "x86,lapic" - description: "Intel Local APIC seL4 IRQ and timer driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the pc99 seL4 platform" - component_type: kernel-driver-irq - - name: brcm,bcm2835-aux-uart - display_name: "brcm,bcm2835-aux-uart" - description: "Raspberry Pi serial seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the rpi3 seL4 platform" - component_type: kernel-driver-serial - - name: samsung,exynos4210-uart - display_name: "samsung,exynos4210-uart" - description: "exynos4210 serial seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the exynos4 seL4 platform" - component_type: kernel-driver-serial - - name: amlogic,meson-gx-uart - display_name: "amlogic,meson-gx-uart" - description: "odroidc2 serial seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by the odroidc2 seL4 platform" - component_type: kernel-driver-serial - - name: arm,pl011 - display_name: "arm,pl011" - description: "Arm standard serial seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by several seL4 platforms" - component_type: kernel-driver-serial - - name: xlnx,xuartps - display_name: "xlnx,xuartps" - description: "Xilinx serial seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by some zynq* seL4 platforms" - component_type: kernel-driver-serial - - name: fsl,imx**-uart - display_name: "fsl,imx**-uart" - description: "i.MX serial seL4 driver" - maintainer: "seL4 Foundation" - status: "active, currently used by some imx* seL4 platforms" - component_type: kernel-driver-serial - - name: qcom,msm-uartdm - display_name: "qcom,msm-uartdm" - description: "apq8064 serial seL4 driver" - maintainer: "seL4 Foundation" - status: "Inactive, currently used by the currently unmaintained apq8064 seL4 platform" - component_type: kernel-driver-serial - - name: arm-misc - display_name: "nvidia,tegra20-uart;ti,omap3-uart;snps,dw-apb-uart" - description: "Simple Arm serial seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by nvidia- and beagle- based seL4 platforms" - component_type: kernel-driver-serial - - name: allwinner,sun4i-a10-timer - display_name: "allwinner,sun4i-a10-timer" - description: "allwinnera20 timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Inactive, currently used by the unmaintained alwinnera20 platform" - component_type: kernel-driver-timer - - name: samsung,exynos4210-mct - display_name: "samsung,exynos4210-mct" - description: "exynos5 timer seL4 driver that wraps Arm Generic timer" - maintainer: "seL4 Foundation" - status: "Active, currently used by the exynos5 platforms" - component_type: kernel-driver-timer - - name: arm,cortex-a9-global-timer - display_name: "arm,cortex-a9-global-timer" - description: "Arm cortex-a9 global timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the cortex-a9 platforms" - component_type: kernel-driver-timer - - name: qcom,kpss-timer - display_name: "qcom,kpss-timer" - description: "apq8064 timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Inactive, currently used by the currently unmaintained apq8064 seL4 platform" - component_type: kernel-driver-timer - - name: ti,am335x-timer - display_name: "ti,am335x-timer" - description: "am335x timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the am335x seL4 platforms" - component_type: kernel-driver-timer - - name: samsung,exynos4412-mct - display_name: "samsung,exynos4412-mct" - description: "exynos4 timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the exynos4 seL4 platform" - component_type: kernel-driver-timer - - name: ti,omap3430-timer - display_name: "ti,omap3430-timer" - description: "omap3 timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the omap3 seL4 platform" - component_type: kernel-driver-timer - - name: "arm,armv7-timer;arm,armv8-timer" - display_name: "arm,armv7-timer;arm,armv8-timer" - description: "Arm generic timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by several Arm seL4 platforms" - component_type: kernel-driver-timer - - name: "arm,cortex-a9-twd-timer" - display_name: "arm,cortex-a9-twd-timer" - description: "Arm cortex-a9 private timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the cortex-a9 seL4 platforms" - component_type: kernel-driver-timer - - name: "pc99,pit" - display_name: "pc99,pit" - description: "x86 PIT timer seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the pc99 seL4 platform" - component_type: kernel-driver-timer - - name: "tk1,smmu" - display_name: "tk1,smmu" - description: "Tegra K1 System MMU (SMMU) seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the tk1 seL4 platform" - component_type: kernel-driver-iommu - - name: "intel,vtd" - display_name: "intel,vtd" - description: "Intel VT-d (IOMMU) seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the pc99 seL4 platform" - component_type: kernel-driver-iommu - - name: "x86,serial" - display_name: "x86,serial" - description: "Intel COM port serial seL4 driver" - maintainer: "seL4 Foundation" - status: "Active, currently used by the pc99 seL4 platform" - component_type: kernel-driver-serial - - - name: am335x-boneblack.dts - display_name: am335x-boneblack.dts - description: "am335x-boneblack platform device tree (dts) sourced from Linux kernel path: am335x-boneblack" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: am335x-boneblue.dts - display_name: am335x-boneblue.dts - description: "am335x-boneblue platform device tree (dts) sourced from Linux kernel path: am335x-boneblue" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: rpi3.dts - display_name: rpi3.dts - description: "rpi3 platform device tree (dts) sourced from Linux kernel path: bcm2837-rpi-3-b" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: exynos4.dts - display_name: exynos4.dts - description: "exynos4 platform device tree (dts) sourced from Linux kernel path: exynos4412-odroidx" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: exynos5250.dts - display_name: exynos5250.dts - description: "exynos5250 platform device tree (dts) sourced from Linux kernel path: exynos5250-arndale" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: exynos5410.dts - display_name: exynos5410.dts - description: "exynos5410 platform device tree (dts) sourced from Linux kernel path: exynos5410-odroidxu" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: exynos5422.dts - display_name: exynos5422.dts - description: "exynos5422 platform device tree (dts) sourced from Linux kernel path: exynos5422-odroidxu4" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: sabre.dts - display_name: sabre.dts - description: "sabre platform device tree (dts) sourced from Linux kernel path: imx6q-sabrelite" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: wandq.dts - display_name: wandq.dts - description: "wandq platform device tree (dts) sourced from Linux kernel path: imx6q-wandboard-revd1" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: imx7sabre.dts - display_name: imx7sabre.dts - description: "imx7sabre platform device tree (dts) sourced from Linux kernel path: imx7d-sdb" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: omap3.dts - display_name: omap3.dts - description: "omap3 platform device tree (dts) sourced from Linux kernel path: omap3-beagle" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: apq8064.dts - display_name: apq8064.dts - description: "apq8064 platform device tree (dts) sourced from Linux kernel path: qcom-apq8064-ifc6410" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: allwinnera20.dts - display_name: allwinnera20.dts - description: "allwinnera20 platform device tree (dts) sourced from Linux kernel path: sun7i-a20-cubietruck" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: tk1.dts - display_name: tk1.dts - description: "tk1 platform device tree (dts) sourced from Linux kernel path: tegra124-jetson-tk1" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: zynq7000.dts - display_name: zynq7000.dts - description: "zynq7000 platform device tree (dts) sourced from Linux kernel path: zynq-zc706" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: odroidc2.dts - display_name: odroidc2.dts - description: "odroidc2 platform device tree (dts) sourced from Linux kernel path: amlogic/meson-gxbb-odroidc2" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: hikey.dts - display_name: hikey.dts - description: "hikey platform device tree (dts) sourced from Linux kernel path: hisilicon/hi6220-hikey" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: tx1.dts - display_name: tx1.dts - description: "tx1 platform device tree (dts) sourced from Linux kernel path: nvidia/tegra210-p2371-2180" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: ultra96.dts - display_name: ultra96.dts - description: "ultra96 platform device tree (dts) sourced from Linux kernel path: xilinx/avnet-ultra96-rev1" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: zynqmp.dts - display_name: zynqmp.dts - description: "zynqmp platform device tree (dts) sourced from Linux kernel path: xilinx/zynqmp-zcu102-rev1.0" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: imx8mq-evk.dts - display_name: imx8mq-evk.dts - description: "imx8mq-evk platform device tree (dts) sourced from Linux kernel path: freescale/fsl-imx8mq-evk" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: imx8mm-evk.dts - display_name: imx8mm-evk.dts - description: "imx8mm-evk platform device tree (dts) sourced from Linux kernel path: freescale/fsl-imx8mm-evk" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - - name: rockpro64.dts - display_name: rockpro64.dts - description: "rockpro64 platform device tree (dts) sourced from Linux kernel path: rockchip/rk3399-rockpro64" - maintainer: "seL4 Foundation" - status: "active" - component_type: kernel-device-tree - -roadmap: - - name: MCS - display_name: MCS Kernel extensions - description: A new scheduling model to support trustworthy mixed-criticality real-time systems. - assigned: UNSW - status: "In progress. Main API stable and available. Note: smaller API changes while verification is in progress." - roadmap_type: in-progress - - name: Microkit - display_name: seL4 Microkit - description: A simple operating systems framework for building systems on seL4. - assigned: UNSW - status: Ongoing research & development. Available for use. Detailed roadmap available here. - roadmap_type: in-progress - - name: sDDF - display_name: seL4 Device Driver Framework - description: A high-performance and secure driver framework for seL4. - assigned: UNSW - status: Ongoing research & development. Available for use. Find out more here. - roadmap_type: in-progress - - name: LionsOS - display_name: LionsOS - description: A secure, fast, and adaptable OS based on the seL4 Microkit. - assigned: UNSW - status: Ongoing research & development. An initial release containing a non-trivial example system has been made. Find out more here. - roadmap_type: in-progress diff --git a/_data/projects/sel4_tools.yml b/_data/projects/sel4_tools.yml deleted file mode 100644 index 69d58e2faf4..00000000000 --- a/_data/projects/sel4_tools.yml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: sel4_tools -display_name: seL4_tools -description: Provides tools used to build seL4 projects -project_order: 9 - -repositories: - - org: seL4 - repo: sel4_tools diff --git a/_data/projects/sel4bench.yml b/_data/projects/sel4bench.yml deleted file mode 100644 index db49dfb4507..00000000000 --- a/_data/projects/sel4bench.yml +++ /dev/null @@ -1,175 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: sel4bench -display_name: sel4bench -description: sel4bench contains benchmarking applications and a support library for seL4 -project_order: 7 - -repositories: - - org: seL4 - repo: sel4bench - - org: seL4 - repo: sel4bench-manifest - -components: - - name: sel4bench - display_name: sel4bench - description: "Driver process for seL4 benchmarking applications" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-driver - - name: fault - display_name: Fault - description: "Fault delivery, measured from user space" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: hardware - display_name: Hardware - description: "Hardware-related seL4 operations" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: ipc - display_name: IPC - description: "A benchmark of the kernel IPC path" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: irq - display_name: IRQ - description: "The IRQ path, measured from inside the kernel." - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: irquser - display_name: IRQ user - description: "The IRQ path, measured from user space." - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: page_mapping - display_name: Page mapping - description: "Performance of mapping a series of pages" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: schedule - display_name: Scheduler - description: 'Benchmark for scheduling decisions, - using a producer/consumer pattern between two notification objects. - Also measures `seL4_Yield()`.' - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: signal - display_name: Signal - description: "The seL4 signal operation, measured from user space" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: smp - display_name: SMP - description: "Intra-core IPC round-trip benchmark to measure overhead of - kernel synchronization on IPC throughput." - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: sync - display_name: Synchronisation library - description: "Measuring the user-level seL4 sync library" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: vcpu - display_name: Aarch64 VCPU - description: "seL4 VCPU performance, including - privilege escalation from EL1 to EL2 with `HVC`, - privilege de-escalation from EL2 to EL1 with `ERET`, - null invocation of the EL2 kernel using `HVC`, - cost of `seL4_Call()` from an EL1 guest thread to a native seL4 - thread, and - cost of an `seL4_Reply()` from an seL4 native thread to an EL1 - guest thread. See the sel4bench repository - [README](https://github.com/seL4/sel4bench) - for instructions. - " - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-application - - name: libsel4benchsupport - display_name: libsel4benchsupport - description: "Support library for writing benchmarking applications" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4bench-library - - name: Findsel4benchupport - display_name: "Findsel4benchupport" - description: "CMake module for libsel4benchsupport" - maintainer: "seL4 Foundation" - status: "active" - component_type: cmake-module - # Manifests - - name: master.xml - display_name: master.xml - description: "seL4bench project manifest with all repositories from master branches." - maintainer: "seL4 Foundation" - status: "active. Updated whenever project repository structure changes." - component_type: repo-manifest - - name: default.xml - display_name: default.xml - description: "seL4bench project manifest with all repositories pinned to last versions that successfully produced benchmark results." - maintainer: "seL4 Foundation" - status: "active. This gets updated automatically by continuous integration." - component_type: repo-manifest - -configurations: - - name: RELEASE - display_name: "RELEASE" - description: "Performance optimized build" - maintainer: "seL4 Foundation" - status: "(Default: ON)" - component_type: sel4test-option - - name: HARDWARE - display_name: "HARDWARE" - description: "Configuration for sel4bench hardware app" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: FAULT - display_name: "FAULT" - description: "Configuration sel4bench fault app" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: VCPU - display_name: "VCPU" - description: "Whether or not to run the VCPU benchmarks" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: SMP - display_name: "SMP" - description: "Configuration sel4bench smp app" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: PLATFORM - display_name: "PLATFORM" - description: "Platform to test" - maintainer: "seL4 Foundation" - status: "(Default: x86_64)" - component_type: sel4test-option - - name: FASTPATH - display_name: "FASTPATH" - description: "Turn fastpath on or off" - maintainer: "seL4 Foundation" - status: "(Default: ON)" - component_type: sel4test-option - - name: ARM_HYP - display_name: "ARM_HYP" - description: "ARM EL2 hypervisor features on or off" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option diff --git a/_data/projects/sel4runtime.yml b/_data/projects/sel4runtime.yml deleted file mode 100644 index b9b8372b552..00000000000 --- a/_data/projects/sel4runtime.yml +++ /dev/null @@ -1,37 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: sel4runtime -display_name: The seL4 run-time -description: A minimal runtime for running a C or C-compatible process in a minimal seL4 environment -project_order: 6 - -repositories: - - org: seL4 - repo: sel4runtime - -components: - - name: sel4runtime - display_name: "The seL4 C run-time" - description: "A minimal C run-time for use with ELF processes on seL4" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4runtime - - name: libsel4runtime - display_name: "The seL4 C run-time library" - description: "Library to interface with the seL4 C run-time" - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4runtime-library - - name: Findsel4runtime - display_name: "Findsel4runtime" - description: "CMake module for sel4runtime" - maintainer: "seL4 Foundation" - status: "active" - component_type: cmake-module - - name: sel4runtimeConfig - display_name: "sel4runtime Configuration library" - description: "Configuration library containing sel4runtime build configuration values." - maintainer: "seL4 Foundation" - status: "active" - component_type: config-library diff --git a/_data/projects/sel4test.yml b/_data/projects/sel4test.yml deleted file mode 100644 index 575a41d9c66..00000000000 --- a/_data/projects/sel4test.yml +++ /dev/null @@ -1,142 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: sel4test -display_name: seL4Test -description: Test suite for seL4 -project_order: 7 - -repositories: - - org: sel4 - repo: sel4test - - org: sel4 - repo: sel4test-manifest - -components: - - name: sel4test-driver - display_name: sel4test-driver - description: "The rootserver for the seL4 test suite." - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4test-application - - name: sel4test-tests - display_name: sel4test-tests - description: "The seL4 test suite." - maintainer: "seL4 Foundation" - status: "active" - component_type: sel4test-application - # Manifests - - name: master.xml - display_name: master.xml - description: "seL4test project manifest with all repositories from master branches." - maintainer: "seL4 Foundation" - status: "active. Updated whenever project repository structure changes." - component_type: repo-manifest - - name: default.xml - display_name: default.xml - description: "seL4test project manifest with all repositories pinned to last versions that passed all tests." - maintainer: "seL4 Foundation" - status: "active. This gets updated automatically by continuous integration." - component_type: repo-manifest - - # Test environments - - name: basic-testtype - display_name: BASIC test type - description: "General test type where test is launched in own process and can report test results to driver over IPC." - maintainer: "seL4 Foundation" - status: "active" - component_type: test-environment - - name: bootstrap-testtype - display_name: BOOTSTRAP test type - description: "Bootstrapping test type where each test is called in the same address space as the test driver. Used for testing functionality required for BASIC test type." - maintainer: "seL4 Foundation" - status: "active." - component_type: test-environment - - # Tests.... - -configurations: - - name: SIMULATION - display_name: "SIMULATION" - description: "Include only simulation compatible tests" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: RELEASE - display_name: "RELEASE" - description: "Performance optimized build" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: VERIFICATION - display_name: "VERIFICATION" - description: "Only verification friendly kernel features" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: BAMBOO - display_name: "BAMBOO" - description: "Enable machine parseable xml output" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: DOMAINS - display_name: "DOMAINS" - description: "Test multiple domains" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: SMP - display_name: "SMP" - description: "(if supported) Test SMP kernel" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: NUM_NODES - display_name: "NUM_NODES" - description: "(if SMP) The number of nodes" - maintainer: "seL4 Foundation" - status: "(Default: 4)" - component_type: sel4test-option - - name: PLATFORM - display_name: "PLATFORM" - description: "Platform to test" - maintainer: "seL4 Foundation" - status: "(Default: x86_64)" - component_type: sel4test-option - - name: ARM_HYP - display_name: "ARM_HYP" - description: "Hyp mode for ARM platforms" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: MCS - display_name: "MCS" - description: "MCS kernel" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: KernelSel4Arch - display_name: "KernelSel4Arch" - description: "aarch32, aarch64, arm_hyp, ia32, x86_64, riscv32, riscv64" - maintainer: "seL4 Foundation" - status: "(Default: set by PLATFORM)" - component_type: sel4test-option - - name: LibSel4TestPrinterRegex - display_name: "LibSel4TestPrinterRegex" - description: "A POSIX regex pattern used to filter tests" - maintainer: "seL4 Foundation" - status: "(Default: .*)" - component_type: sel4test-option - - name: LibSel4TestPrinterHaltOnTestFailure - display_name: "LibSel4TestPrinterHaltOnTestFailure" - description: "Halt on the first test failure" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option - - name: Sel4testAllowSettingsOverride - display_name: "Sel4testAllowSettingsOverride" - description: "Do not use meta options above, expect manual user config settings for the kernel instead" - maintainer: "seL4 Foundation" - status: "(Default: OFF)" - component_type: sel4test-option diff --git a/_data/projects/sel4webserver.yml b/_data/projects/sel4webserver.yml deleted file mode 100644 index 8605a59e65c..00000000000 --- a/_data/projects/sel4webserver.yml +++ /dev/null @@ -1,57 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: sel4webserver -display_name: seL4webserver -description: A reference for implementing applications on seL4 -project_order: 7 - -repositories: - - org: seL4 - repo: sel4webserver - - org: seL4 - repo: sel4webserver-manifest - -components: - - name: Finddocsite - display_name: "Finddocsite" - description: "CMake module for building and installing an instance of the docsite in the vm filesystem, to be served by lighttpd." - maintainer: "UNSW" - status: "active" - component_type: cmake-module - - name: Findlighttpd - display_name: "Findlighttpd" - description: "CMake module for building and installing lighttpd in the VM filesystem." - maintainer: "UNSW" - status: "active" - component_type: cmake-module - - name: main - display_name: "main" - description: "CAmkES main module for running a single VM with lighttpd serving the docsite." - maintainer: "UNSW" - status: "active" - component_type: camkes-module - - name: exynos-devices - display_name: "exynos-devices" - description: "CAmkES description of exynos5422 devices for single VM webserver" - maintainer: "UNSW" - status: "active" - component_type: camkes-module - - name: exynos-multi-devices - display_name: "exynos-multi-devices" - description: "CAmkES description of exynos5422 devices for multi VM webserver" - maintainer: "UNSW" - status: "active" - component_type: camkes-module - - name: qemu-arm-virt-devices - display_name: "qemu-arm-virt-devices" - description: "CAmkES description of qemu-arm-virt devices for single VM webserver" - maintainer: "UNSW" - status: "active" - component_type: camkes-module - - name: overlay-files - display_name: "overlay-files" - description: "Files to be added to the VM filesystem overlay, mostly network setup" - maintainer: "UNSW" - status: "active" - component_type: init-script diff --git a/_data/projects/user_libs.yml b/_data/projects/user_libs.yml deleted file mode 100644 index 87ac1135365..00000000000 --- a/_data/projects/user_libs.yml +++ /dev/null @@ -1,1068 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: user_libs -display_name: user_libs -description: Userlevel libraries on seL4 -project_order: 6 - -repositories: - - org: sel4 - repo: util_libs - - org: sel4 - repo: sel4_libs - - org: sel4 - repo: sel4_projects_libs - - org: sel4 - repo: projects_libs - -components: - - name: libcpio - display_name: libcpio - description: "A library for parsing files in CPIO format." - maintainer: "seL4 Foundation" - status: "active" - component_type: util_libs - - name: libelf - display_name: libelf - description: "A library for reading ELF files." - maintainer: "seL4 Foundation" - status: "active" - component_type: util_libs - - name: libethdrivers - display_name: libethdrivers - description: "A library for ethernet drivers on selected platforms, supporting lwIP and picoTCP." - maintainer: "seL4 Foundation" - status: "active" - component_type: util_libs - - name: libfdt - display_name: libfdt - description: "A library for flat device tree manipulation, ported from linux kernel version: 5.0.6." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: util_libs - - name: liblwip - display_name: liblwip - description: "A library for the lwIP, ported from lwip-1.4.1." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: util_libs - - name: libpci - display_name: libpci - description: "A library for PCI drivers." - maintainer: "seL4 Foundation" - status: "active" - component_type: util_libs - - name: libpicotcp - display_name: libpicotcp - description: "A library of picoTCP header files." - maintainer: "seL4 Foundation" - status: "active" - component_type: util_libs - - name: libplatsupport - display_name: libplatsupport - description: "A library of platform support utilities, interfaces for interacting with drivers, timer drivers, serial drivers and clock drivers." - maintainer: "seL4 Foundation" - status: "active" - component_type: util_libs - - name: libutils - display_name: libutils - description: "A library of generic utilities, such as debugging macros and compile time asserts." - maintainer: "seL4 Foundation" - status: "active" - component_type: util_libs - - name: libsel4allocman - display_name: libsel4allocman - description: "An allocator for managing virtual memory, malloc memory and cspaces." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4bench - display_name: libsel4bench - description: "A library of benchmarking utilities on seL4, such as logging and PMU event counters." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4debug - display_name: libsel4debug - description: "A library for debugging userspace applications on seL4." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4muslcsys - display_name: libsel4muslcsys - description: "A library of minimal muslc syscall implementation for seL4." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4platsupport - display_name: libsel4platsupport - description: "A wrapper around libplatsupport specificially for seL4." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4serialserver - display_name: libsel4serialserver - description: "A library for creating serial servers. A server thread is able to connect to a serial device and act as a multiplexer for writes." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4simple - display_name: libsel4simple - description: "An interface which abstracts over the boot environment of an seL4 application." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4simple-default - display_name: libsel4simple-default - description: "An implementation of libsel4simple for the master branch of the seL4 kernel." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4sync - display_name: libsel4sync - description: "A synchronisation library that uses notifications to construct basic locks." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4test - display_name: libsel4test - description: "A library for running tests and generating test output in either human readable or xml format." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4utils - display_name: libsel4utils - description: "A library of OS-like utilities for building benchmarks and applications on seL4." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4vka - display_name: libsel4vka - description: "An allocation interface for seL4." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4vspace - display_name: libsel4vspace - description: "A virtual memory management interface for seL4. " - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_libs - - name: libsel4bga - display_name: libsel4bga - description: "A basic driver for the Bochs Graphics Adaptor, currently only supports the x86 IA32 architecture." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: seL4_projects_libs - - name: libsel4dma - display_name: libsel4dma - description: "An allocator for managing DMA memory." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_projects_libs - - name: libsel4keyboard - display_name: libsel4keyboard - description: "A basic keyboard driver." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_projects_libs - - name: libsel4nanopb - display_name: libsel4nanopb - description: "An interface between seL4 IPC buffers and nanopb. Nanopb is a small code-size Protocol Buffers implementation in ANSI C." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_projects_libs - - name: libsel4rpc - display_name: libsel4rpc - description: "A library for allocating resources over process boundaries. It defines a Protocol Buffer protocol, and contains wrappers for processing RPC messages used by servers." - maintainer: "seL4 Foundation" - status: "active" - component_type: seL4_projects_libs - - name: libsel4vchan - display_name: libsel4vchan - description: "A vchan implementation on seL4, which provides communication channels between virtual machines." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: seL4_projects_libs - - name: libfdtgen - display_name: libfdtgen - description: "A library for generating flattened device trees which can be passed to virtual machines." - maintainer: "seL4 Foundation" - status: "active" - component_type: projects_libs - - name: libjansson - display_name: libjansson - description: "The port of Jansson-2.7 to seL4 and the seL4 project build system." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: projects_libs - - name: libmsgpack - display_name: libmsgpack - description: "An seL4 build system wrapper to build msgpack-c, a library for dealing with MessagePack data." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: projects_libs - - name: libnfs - display_name: libnfs - description: "A wrapper for supporting project build for a given network file system implementation." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: projects_libs - - name: libplatsupportports - display_name: libplatsupportports - description: "A collection of drivers proted from GPL-based sources such as U-Boot and Linux." - maintainer: "seL4 Foundation" - status: "active" - component_type: projects_libs - - name: libringbuffer - display_name: libringbuffer - description: "A library of the ring buffer implementation." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: projects_libs - - name: libsdhcdrivers - display_name: libsdhcdrivers - description: "A library of the SD card driver." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: projects_libs - - name: libtx2bpmp - display_name: libtx2bpmp - description: "A port of the Tegra186 Boot and Power Management Processor (BPMP) interfaces from U-Boot to seL4." - maintainer: "seL4 Foundation" - status: "active" - component_type: projects_libs - - name: libusbdrivers - display_name: libusbdrivers - description: "A USB driver." - maintainer: "seL4 Foundation" - status: "inactive" - component_type: projects_libs - - name: libvirtqueue - display_name: libvirtqueue - description: "A library implementation of a virtqueue inspired from the virtio specification." - maintainer: "seL4 Foundation" - status: "active" - component_type: projects_libs - - name: libvswitch - display_name: libvswitch - description: "A library implementation of a vswitch, which is designed for providing an interface to manage and route data between components identified by a MAC address." - maintainer: "seL4 Foundation" - status: "active" - component_type: projects_libs -# Drivers - - name: arch/x86/delay.c - display_name: "arch/x86/delay.c" - description: "x86 busy wait delay driver by spinning on tsc value" - maintainer: "seL4 Foundation" - status: "Supported on x86 but currently unused by anything." - component_type: user-driver-other - - name: arch/x86/tsc.c - display_name: "arch/x86/tsc.c" - description: "Calculates tsc frequency using HPET or PIT" - maintainer: "seL4 Foundation" - status: "Supported on x86. It may be better to use the tsc_freq Bootinfo field that seL4 provides." - component_type: user-driver-other - - name: arch/arm/generic_timer.c - display_name: "arch/arm/generic_timer.c" - description: "Arm generic timer driver. Should be used for debugging or development configurations only as register access is global." - maintainer: "seL4 Foundation" - status: "Requires configuring seL4 to make the Physical timer registers available to user level." - component_type: user-driver-timer - - name: arch/arm/generic_ltimer.c - display_name: "arch/arm/generic_ltimer.c" - description: "ltimer implementation for Arm generic timer physical timer. Should be used for debugging or development configurations only as register access is global" - maintainer: "seL4 Foundation" - status: "Requires configuring seL4 to make the Physical timer registers available to user level." - component_type: user-driver-ltimer - - name: arch/arm/delay.c - display_name: "arch/arm/delay.c" - description: "arm busy wait delay driver by repeatedly performing no-op instructions" - maintainer: "seL4 Foundation" - status: "Supported on arm but currently relies on each instruction taking a constant amount of time" - component_type: user-driver-other - # FIXME: commented out, should use filter - # - name: arch/arm/dma330.c - # display_name: "arch/arm/dma330.c" - # description: "ARM PL-330 (DMA-330) DMA controller" - # maintainer: "seL4 Foundation" - # status: "Unused currently" - # component_type: user-driver-other - - name: arch/arm/i2c_bitbang.c - display_name: "arch/arm/i2c_bitbang.c" - description: "Transforms a GPIO interface into an I2C bitbang interface" - maintainer: "seL4 Foundation" - status: "Currently used by libusbdrivers." - component_type: user-driver-i2c - - name: local_time_manager.c - display_name: "local_time_manager.c" - description: "Uses an ltimer to provide timeout multiplexing across several clients" - maintainer: "seL4 Foundation" - status: "Requires ltimer implementation for the target platform." - component_type: user-driver-ltimer - - name: plat/rockpro64/timer.c - display_name: "plat/rockpro64/timer.c" - description: "rockchip,rk3399-timer driver" - maintainer: "seL4 Foundation" - status: "Supported on rockpro64 platform" - component_type: user-driver-timer - - name: plat/rockpro64/serial.c - display_name: "plat/rockpro64/serial.c" - description: "rockchip,rk3399-uart driver" - maintainer: "seL4 Foundation" - status: "Supported on rockpro64 platform" - component_type: user-driver-serial - - name: plat/rockpro64/ltimer.c - display_name: "plat/rockpro64/ltimer.c" - description: "rockpro64 ltimer implementation using 2 rk3399-timers" - maintainer: "seL4 Foundation" - status: "Supported on rockpro64 platform" - component_type: user-driver-ltimer - - name: plat/bcm2837/spt.c - display_name: "plat/bcm2837/spt.c" - description: "rpi3 spt timer driver. The timer is based on a SP804 timer with some modifications." - maintainer: "seL4 Foundation" - status: "Supported on rpi3 platform" - component_type: user-driver-timer - - name: plat/bcm2837/serial.c - display_name: "plat/bcm2837/serial.c" - description: "rpi3 brcm,bcm2835-aux-uart UART driver" - maintainer: "seL4 Foundation" - status: "Supported on rpi3 platform" - component_type: user-driver-serial - - name: plat/bcm2837/system_timer.c - display_name: "plat/bcm2837/system_timer.c" - description: "rpi3 system timer driver." - maintainer: "seL4 Foundation" - status: "Supported on rpi3 platform" - component_type: user-driver-timer - - name: plat/bcm2837/ltimer.c - display_name: "plat/bcm2837/ltimer.c" - description: "rpi3 ltimer implementation using the system timer and spt timer" - maintainer: "seL4 Foundation" - status: "Supported on rpi3 platform" - component_type: user-driver-ltimer - - name: plat/zynq7000/devcfg.c - display_name: "plat/zynq7000/devcfg.c" - description: "devcfg (Device configuration Interface) zynq7000 driver" - maintainer: "seL4 Foundation" - status: "Supported only for zynq7000 platform. Only functionality is mapping registers and providing a reference." - component_type: user-driver-other - - name: plat/zynq7000/tmu.c - display_name: "plat/zynq7000/tmu.c" - description: "Temperature sensor driver for zynq7000 tmu." - maintainer: "seL4 Foundation" - status: "Supported on zynq7000 platform." - component_type: user-driver-other - - name: plat/zynq7000/clock.c - display_name: "plat/zynq7000/clock.c" - description: "zynq7000 clock subsystem driver" - maintainer: "seL4 Foundation" - status: "Supported on zynq7000 platform." - component_type: user-driver-clock - - name: plat/zynq7000/xadc.c - display_name: "plat/zynq7000/xadc.c" - description: "zynq7000 XADC driver" - maintainer: "seL4 Foundation" - status: "Supported on zynq7000 platform. Currently only used to read values from a temperature monitoring unit." - component_type: user-driver-other - - name: plat/zynq7000/src.c - display_name: "plat/zynq7000/src.c" - description: "zynq7000 System Level Control Registers driver" - maintainer: "seL4 Foundation" - status: "Supported on zynq7000 platform. Currently used to unlock clock and reset registers only." - component_type: user-driver-other - - name: plat/exynos5/sysreg.c - display_name: "plat/exynos5/sysreg.c" - description: "exynos5 samsung,exynos5-sysreg system control driver" - maintainer: "seL4 Foundation" - status: "Supported on exynos5 platforms. Currently can only be used to enable power for USB PHYs." - component_type: user-driver-other - - name: plat/exynos5/clock.c - display_name: "plat/exynos5/clock.c" - description: "exynos5 clock subsystem driver" - maintainer: "seL4 Foundation" - status: "Supported on exynos5 platform." - component_type: user-driver-clock - - name: plat/odroidc2/serial.c - display_name: "plat/odroidc2/serial.c" - description: "odroidc2 amlogic,meson-gx-uart uart driver" - maintainer: "seL4 Foundation" - status: "Supported on odroidc2 platform" - component_type: user-driver-serial - - name: plat/odroidc2/ltimer.c - display_name: "plat/odroidc2/ltimer.c" - description: "odroidc2 ltimer implementation using the meson timer" - maintainer: "seL4 Foundation" - status: "Supported on odroidc2 platform" - component_type: user-driver-ltimer - - name: plat/odroidc2/meson_timer.c - display_name: "plat/odroidc2/meson_timer.c" - description: "odroidc2 meson timer implementation" - maintainer: "seL4 Foundation" - status: "Supported on odroidc2 platform" - component_type: user-driver-timer - - name: plat/am335x/timer.c - display_name: "plat/am335x/timer.c" - description: "am335x ti,am335x-timer driver for DMTimer" - maintainer: "seL4 Foundation" - status: "Supported on am335x platforms." - component_type: user-driver-timer - - name: plat/am335x/serial.c - display_name: "plat/am335x/serial.c" - description: "am335x ti,am3352-uart serial driver" - maintainer: "seL4 Foundation" - status: "Supported on am335x platforms." - component_type: user-driver-serial - - name: plat/am335x/ltimer.c - display_name: "plat/am335x/ltimer.c" - description: "am335x ltimer implementation using 2 DMTimers" - maintainer: "seL4 Foundation" - status: "Supported on am335x platforms." - component_type: user-driver-ltimer - - name: plat/am335x/i2c.c - display_name: "plat/am335x/i2c.c" - description: "am335x ti,omap4-i2c driver for I2C." - maintainer: "seL4 Foundation" - status: "Supported on am335x platforms." - component_type: user-driver-i2c - - name: plat/tk1/mux.c - display_name: "plat/tk1/mux.c" - description: "tk1 nvidia,tegra124-pinmux pinmux driver" - maintainer: "seL4 Foundation" - status: "Supported on tk1 platform" - component_type: user-driver-pinmux - - name: plat/tk1/clock.c - display_name: "plat/tk1/clock.c" - description: "tk1 nvidia,tegra124-car clock subsystem driver" - maintainer: "seL4 Foundation" - status: "Supported on tk1 platform." - component_type: user-driver-clock - - name: plat/tk1/spi.c - display_name: "plat/tk1/spi.c" - description: "tk1 nvidia,tegra124-spi SPI driver" - maintainer: "seL4 Foundation" - status: "Supported on tk1 platform." - component_type: user-driver-other - - name: plat/tk1/i2c.c - display_name: "plat/tk1/i2c.c" - description: "tk1 nvidia,tegra124-i2c I2C driver" - maintainer: "seL4 Foundation" - status: "Supported on tk1 platform." - component_type: user-driver-i2c - - name: plat/tk1/gpio.c - display_name: "plat/tk1/gpio.c" - description: "tk1 nvidia,tegra124-gpio GPIO driver" - maintainer: "seL4 Foundation" - status: "Supported on i2c platform." - component_type: user-driver-gpio - - name: plat/fvp/serial.c - display_name: "plat/fvp/serial.c" - description: "fvp arm,pl011 serial driver" - maintainer: "seL4 Foundation" - status: "Derived from the pl011 driver for the hikey platform." - component_type: user-driver-serial - - name: plat/fvp/sp804.c - display_name: "plat/fvp/sp804.c" - description: "fvp arm,sp804 timer driver" - maintainer: "seL4 Foundation" - status: "Derived from the sp804 driver for the hikey platform." - component_type: user-driver-timer - - name: plat/fvp/ltimer.c - display_name: "plat/fvp/ltimer.c" - description: "fvp ltimer implementation using 2 sp804 timers." - maintainer: "seL4 Foundation" - status: "Supported on fvp platform." - component_type: user-driver-ltimer - - name: plat/exynos4/clock.c - display_name: "plat/exynos4/clock.c" - description: "exynos4 clock subsystem driver" - maintainer: "seL4 Foundation" - status: "Supported on exynos4 platform." - component_type: user-driver-clock - - name: plat/exynos4/src.c - display_name: "plat/exynos4/src.c" - description: "exynos4 samsung,exynos4-sysreg system control driver" - maintainer: "seL4 Foundation" - status: "Supported on exynos4 platforms. Currently can only be used to enable power for USB PHYs." - component_type: user-driver-other - - name: plat/hikey/serial.c - display_name: "plat/hikey/serial.c" - description: "hikey arm,pl011 Serial driver" - maintainer: "seL4 Foundation" - status: "Supported on Hikey platform. Could likely be extended to other platforms." - component_type: user-driver-serial - - name: plat/hikey/ltimer.c - display_name: "plat/hikey/ltimer.c" - description: "hikey ltimer implementation using 2 sp804 timers" - maintainer: "seL4 Foundation" - status: "Supported on hikey platform." - component_type: user-driver-ltimer - - name: plat/hikey/rtc.c - display_name: "plat/hikey/rtc.c" - description: "hikey arm,pl031 RTC driver" - maintainer: "seL4 Foundation" - status: "Supported on Hikey platform. Could likely be extended to other platforms." - component_type: user-driver-timer - - name: plat/hikey/dmt.c - display_name: "plat/hikey/dmt.c" - description: "hikey arm,sp804 timer driver" - maintainer: "seL4 Foundation" - status: "Supported on Hikey platform. Could likely be extended to other platforms." - component_type: user-driver-timer - - name: plat/qemu-arm-virt/serial.c - display_name: "plat/qemu-arm-virt/serial.c" - description: "qemu-arm-virt arm,pl011 serial driver" - maintainer: "seL4 Foundation" - status: "Derived from the pl011 driver for the hikey platform." - component_type: user-driver-serial - # FIXME: commented out for now, should use a filter instead - # - name: plat/apq8064/timer.c - # display_name: "plat/apq8064/timer.c" - # description: "apq8064 timer driver" - # maintainer: "seL4 Foundation" - # status: "Supported on apq8064 platform. (Platform is currently unmaintained)" - # component_type: user-driver-timer - # - name: plat/apq8064/serial.c - # display_name: "plat/apq8064/serial.c" - # description: "apq8064 qcom,gsbi-v1.0.0 serial driver" - # maintainer: "seL4 Foundation" - # status: "Supported on apq8064 platform. (Platform is currently unmaintained)" - # component_type: user-driver-serial - # - name: plat/apq8064/clock.c - # display_name: "plat/apq8064/clock.c" - # description: "apq8064 qcom,gcc-apq8064 clock subsystem driver" - # maintainer: "seL4 Foundation" - # status: "Supported on apq8064 platform. (Platform is currently unmaintained)" - # component_type: user-driver-clock - - name: plat/hifive/pwm.c - display_name: "plat/hifive/pwm.c" - description: "hifive sifive,pwm0 timer driver" - maintainer: "seL4 Foundation" - status: "Supported on hifive platform" - component_type: user-driver-timer - - name: plat/hifive/ltimer.c - display_name: "plat/hifive/ltimer.c" - description: "ltimer implementation for the hifive platform using two PWM timers" - maintainer: "seL4 Foundation" - status: "Supported on hifive platform" - component_type: user-driver-ltimer - - name: plat/hifive/uart.c" - display_name: "plat/hifive/uart.c" - description: "hifive sifive,uart0 UART serial driver" - maintainer: "seL4 Foundation" - status: "Supported on hifive platform" - component_type: user-driver-serial - - name: plat/pc99/keyboard_chardev.c - display_name: "plat/pc99/keyboard_chardev.c" - description: "chardev implementation for the pc99 keyboard which uses the pc99 PS/2 driver" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-chardev - - name: plat/pc99/acpi/ - display_name: "plat/pc99/acpi/*" - description: "ACPI driver for the ACPI interface in the pc99 platform" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-acpi - - name: plat/pc99/serial.c - display_name: "plat/pc99/serial.c" - description: "UART serial driver for the serial devices on the pc99 platform" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-serial - - name: plat/pc99/keyboard_ps2.c - display_name: plat/pc99/keyboard_ps2.c - description: "Keyboard driver for the pc99 platform over the PS/2 keyboard interface" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-keyboard - - name: plat/pc99/keyboard_vkey.c - display_name: "plat/pc99/keyboard_vkey.c" - description: "Virtual keycodes for the pc99 PS/2 keyboard driver" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-keyboard - - name: plat/pc99/ltimer.c - display_name: "plat/pc99/ltimer.c" - description: "ltimer implementation for the pc99 platform using either PIT or HPET timers" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-ltimer - - name: plat/pc99/pit.c - display_name: "plat/pc99/pit.c" - description: "PIT driver for the PIT (Programmable Interval Timer) on the pc99 platform" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-timer - - name: plat/pc99/rtc.c - display_name: "plat/pc99/rtc.c" - description: "RTC driver for the RTC on the pc99 platform" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-timer - - name: plat/pc99/ega.c - display_name: "plat/pc99/ega.c" - description: "EGA driver for the EGA (Enhanced Graphics Adapter) device on the pc99 platform" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-serial - - name: plat/pc99/hpet.c - display_name: "plat/pc99/hpet.c" - description: "HPET driver for the HPET (High Precision Event Timer) device on the pc99 platform" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-timer - - name: plat/omap3/serial.c - display_name: "plat/omap3/serial.c" - description: "omap3 ti,omap3-uart UART serial driver" - maintainer: "seL4 Foundation" - status: "Supported on omap3 platform" - component_type: user-driver-serial - # FIXME: commented out, should use a filter instead - # - name: plat/omap3/mux.c - # display_name: "plat/omap3/mux.c" - # description: "omap3 ti,omap3-padconf pin controller driver" - # maintainer: "seL4 Foundation" - # status: "Non-functional skeleton implementation, supported on omap3 platform" - # component_type: user-driver-pinmux - # - name: plat/omap3/clock.c - # display_name: "plat/omap3/clock.c" - # description: "omap3 ti,omap3-cm clock controller driver" - # maintainer: "seL4 Foundation" - # status: "Non-functional skeleton implementation, supported on omap3 platform" - # component_type: user-driver-clock - # - name: plat/rocketchip/serial.c - # display_name: "plat/rocketchip/serial.c" - # description: "Empty driver implementation for the serial device on the rocketchip platform." - # maintainer: "seL4 Foundation" - # status: "Non-functional skeleton implementation, supported on rocketchip platform" - # component_type: user-driver-serial - # - name: plat/rocketchip/chardev.c - # display_name: "plat/rocketchip/chardev.c" - # description: "Empty chardev implementation for the rocketchip platform." - # maintainer: "seL4 Foundation" - # status: "Non-functional skeleton implementation, supported on rocketchip platform" - # component_type: user-driver-serial - - name: plat/imx6/mux.c - display_name: "plat/imx6/mux.c" - description: "i.MX6 fsl,imx6q-iomuxc IO MUX driver" - maintainer: "seL4 Foundation" - status: "Supported on sabre" - component_type: user-driver-pinmux - - name: plat/imx6/clock.c - display_name: "plat/imx6/clock.c" - description: "i.MX6 fsl,imx6q-ccm clock subsystem driver" - maintainer: "seL4 Foundation" - status: "Supported on sabre platform" - component_type: user-driver-clock - - name: plat/imx6/i2c.c - display_name: "plat/imx6/i2c.c" - description: "i.MX6 fsl,imx6q-i2c driver I2C" - maintainer: "seL4 Foundation" - status: "Supported on sabre platform" - component_type: user-driver-i2c - - name: plat/imx6/gpio.c - display_name: "plat/imx6/gpio.c" - description: "i.MX6 fsl,imx6q-gpio GPIO driver" - maintainer: "seL4 Foundation" - status: "Supported on sabre platform" - component_type: user-driver-gpio - - name: plat/imx6/src.c - display_name: "plat/imx6/src.c" - description: "i.MX6 fsl,imx6q-src reset controller driver" - maintainer: "seL4 Foundation" - status: "Supported on sabre platform" - component_type: user-driver-reset - - name: mach/omap/gpt.c - display_name: "mach/omap/gpt.c" - description: "GPT driver for the GPT timers in the OMAP SoCs" - maintainer: "seL4 Foundation" - status: "Supported on OMAP SoCs" - component_type: user-driver-timer - - name: mach/omap/ltimer.c - display_name: "mach/omap/ltimer.c" - description: "ltimer implementation for the OMAP platforms using GPT timers" - maintainer: "seL4 Foundation" - status: "Supported on OMAP SoCs" - component_type: user-driver-other - - name: mach/imx/epit/epit.c - display_name: "mach/imx/epit/epit.c" - description: "EPIT driver for the EPIT timers in the i.MX SoCs" - maintainer: "seL4 Foundation" - status: "Supported on i.MX SoCs" - component_type: user-driver-timer - - name: mach/imx/ltimer.c - display_name: "mach/imx/ltimer.c" - description: "ltimer implementation for the i.MX platforms using a combination of GPT and EPIT timers" - maintainer: "seL4 Foundation" - status: "Supported on i.MX SoCs" - component_type: user-driver-ltimer - - name: mach/imx/serial/serial.c - display_name: "mach/imx/serial/serial.c" - description: "UART serial drivers for the UART devices in the i.MX SoCs" - maintainer: "seL4 Foundation" - status: "Supported on i.MX SoCs" - component_type: user-driver-serial - - name: mach/imx/gpt.c - display_name: "mach/imx/gpt.c" - description: "GPT driver for the GPT timers in the i.MX SoCs" - maintainer: "seL4 Foundation" - status: "Supported on i.MX SoCs" - component_type: user-driver-timer - - name: mach/exynos/clock/exynos_common_clock.c - display_name: "mach/exynos/clock/exynos_common_clock.c" - description: "Exynos platform-common functions to manipulate the clock device in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on Exynos SoCs" - component_type: user-driver-timer - - name: mach/exynos/clock/exynos_5422_clock.c - display_name: "mach/exynos/clock/exynos_5422_clock.c" - description: "Exynos5422 platform-specific functions to manipulate the clock device in the Exynos5422 SoC" - maintainer: "seL4 Foundation" - status: "Supported on Exynos SoCs" - component_type: user-driver-timer - - name: mach/exynos/clock.c - display_name: "mach/exynos/clock.h" - description: "Clock subsystem driver for the clock controller in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on Exynos SoCs" - component_type: user-driver-timer - - name: mach/exynos/pwm.c - display_name: "mach/exynos/pwm.c" - description: "PWM drivers for the PWM timers in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on Exynos SoCs" - component_type: user-driver-timer - - name: mach/exynos/tmu.c - display_name: "mach/exynos/tmu.c" - description: "TMU driver for the TMU (Thermal Management Unit) device in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on Exynos SoCs" - component_type: user-driver-other - - name: mach/exynos/serial.c - display_name: "mach/exynos/serial.c" - description: "UART serial driver for the UART devices in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on Exynos SoCs" - component_type: user-driver-serial - - name: mach/exynos/pmic.c - display_name: "mach/exynos/pmic.c" - description: "PMIC driver for the PMIC (Power Management IC) device in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos SoCs" - component_type: user-driver-other - - name: mach/exynos4/mux.c - display_name: "mach/exnyos4/mux.c" - description: "Pinctrl configurations for the Exynos4xxx SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos4xxx SoCs" - component_type: user-driver-pinmux - - name: mach/exynos5/mux.c - display_name: "mach/exynos5/mux.c" - description: "Pinctrl configurations for the Exynos5xxx SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos5xxx SoCs" - component_type: user-driver-pinmux - - name: mach/exynos/mux.c - display_name: "mach/exynos/mux.c" - description: "Pinctrl driver for the pinctrl device in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos SoCs" - component_type: user-driver-pinmux - - name: mach/exynos/ltimer.c - display_name: "mach/exynos/ltimer.c" - description: "ltimer implementation for the Exynos platforms using the PWM timers" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos SoCs" - component_type: user-driver-pinmux - - name: mach/exynos/spi.c - display_name: "mach/exynos/spi.c" - description: "SPI driver for the SPI devices in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos SoCs" - component_type: user-driver-spi - - name: mach/exynos/i2c.c - display_name: "mach/exynos/i2c.c" - description: "I2C driver for the I2C devices in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos SoCs" - component_type: user-driver-i2c - - name: mach/exynos/pmic_rtc.c - display_name: "mach/exynos/pmic_rtc.c" - description: "RTC driver for the RTC located inside the PMIC device in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos SoCs" - component_type: user-driver-other - - name: mach/exnyos/irq_combiner.c - display_name: "mach/exnyos/irq_combiner.c" - description: "IRQ combiner driver for the IRQ combiner device in the Exynos SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the Exynos SoCs" - component_type: user-driver-other - - name: mach/zynq/timer.c - display_name: "mach/zynq/timer.c" - description: "TTC driver for the TTC timers in the ZYNQ SoCs" - maintainer: "seL4 Foundation" - status: "Supported on ZYNQ SoCs" - component_type: user-driver-timer - - name: mach/zynq/serial.c - display_name: "mach/zynq/serial.c" - description: "UART serial drivers for the UART devices in the ZYNQ SoCs" - maintainer: "seL4 Foundation" - status: "Supported on ZYNQ SoCs" - component_type: user-driver-serial - # FIXME: commented out, should use a filter instead - # - name: mach/zynq/mux.c - # display_name: "mach/zynq/mux.c" - # description: "Pinmux drivers for the pin controller in the ZYNQ SoCs" - # maintainer: "seL4 Foundation" - # status: "Non-functional skeleton implementation, supported on ZYNQ SoCs" - # component_type: user-driver-pinmux - - name: mach/zynq/ltimer.c - display_name: "mach/zynq/ltimer.c" - description: "ltimer implementation for the ZYNQ platforms using TTC timers" - maintainer: "seL4 Foundation" - status: "Supported on ZYNQ SoCs" - component_type: user-driver-ltimer - - name: mach/zynq/axi_uartlite.c - display_name: "mach/zynq/axi_uartlite.c" - description: "UART serial driver to the AXI UART lite device on ZYNQ SoCs" - maintainer: "seL4 Foundation" - status: "Suppored on ZYNQ SoCs" - component_type: user-driver-serial - - name: mach/nvidia/timer.c - display_name: "mach/nvidia/timer.c" - description: "Timer drivers for the timers on the NVIDIA SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the NVIDIA SoCs" - component_type: user-driver-timer - - name: mach/nvidia/serial.c - display_name: "mach/nvidia/serial.c" - description: "Serial drivers for the UART serial devices on the NVIDIA SoCs" - maintainer: "seL4 Foundation" - status: "Supported on the NVIDIA SoCs" - component_type: user-driver-serial - - name: mach/nvidia/ltimer.c - display_name: "mach/nvidia/ltimer.c" - description: "ltimer implementation for the NVIDIA platforms using the NVIDIA timers" - maintainer: "seL4 Foundation" - status: "Supported on the NVIDIA SoCs" - component_type: user-driver-ltimer - # - # libethdrivers - # - - name: src/pico_dev_eth.c - display_name: "src/pico_dev_eth.c" - description: "Ethernet device interface to connect with the PicoTCP TCP/IP stack" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-ethernet - - name: src/lwip.c - display_name: "src/lwip.c" - description: "Ethernet device interface to connect with the lwIP TCP/IP stack" - maintainer: "seL4 Foundation" - status: "Deprecated in favour of the PicoTCP Ethernet device interface" - component_type: user-driver-ethernet - - name: src/helpers.c - display_name: "src/helpers.c" - description: "Helper functions for the Ethernet drivers in libethdrivers" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-other - - name: src/plat/imx6 - display_name: "src/plat/imx6/*" - description: "Ethernet driver for the i.MX6 platform based off on U-Boot's implementation" - maintainer: "seL4 Foundation" - status: "Supported on the sabre platform" - component_type: user-driver-ethernet - - name: src/plat/pc99 - display_name: "src/plat/pc99/*" - description: "Ethernet driver for the e1000 Ethernet devices" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform" - component_type: user-driver-ethernet - - name: src/plat/tx2 - display_name: "src/plat/tx2/*" - description: "Ethernet driver for the TX2 platform based off on U-Boot's implementation" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-ethernet - - name: src/plat/zynq7000 - display_name: "src/plat/zynq700/*" - description: "Ethernet driver for the zynq7000 platform based off on U-Boot's implementation" - maintainer: "Dornerworks" - status: "Supported on the zynq7000 platform" - component_type: user-driver-ethernet - # - # libplatsupportports - # - - name: src/plat/tx2/clock_bindings.c - display_name: "src/plat/tx2/clock_bindings.c" - description: "libplatsupport clock ID to TX2 BPMP clock ID bindings" - maintainer: "seL4 Foundation" - status: "Supported on tx2 platform" - component_type: user-driver-clock - - name: src/plat/tx2/clock.c - display_name: "src/plat/tx2/clock_bindings.c" - description: "Clock driver for the TX2 CAR (Clock And Reset) controller which relies on libtx2bpmp" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-clock - - name: src/plat/tx2/gpio.c - display_name: "src/plat/tx2/gpio.c" - description: "GPIO driver for the TX2 GPIO controller based off on U-Boot's implementation" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-gpio - - name: src/plat/tx2/mux.c - display_name: "src/plat/tx2/mux.c" - description: "Pin controller driver for the TX2 MUX based off on NVIDIA's L4T implementation" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-pinmux - - name: src/plat/tx2/reset_bindings.c - display_name: "src/plat/tx2/reset_bindings.c" - description: "libplatsupport reset ID to TX2 BPMP reset ID bindings" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-reset - - name: src/plat/tx2/reset.c - display_name: "src/plat/tx2/reset.c" - description: "Reset driver for the TX2 CAR (Clock And Reset) controller which relies on libtx2bpmp" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-reset - # - # libtx2bpmp - # - - name: src/bpmp.c - display_name: "src/bpmp.c" - description: "BPMP driver for the BPMP (Boot and Power Management Processor) co-processor on the TX2 based off on U-Boot's implementation" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-other - - name: src/hsp.c - display_name: "src/hsp.c" - description: "HSP driver for the HSP (Hardware Synchronisation Primitives) module on the TX2" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-other - - name: src/ivc.c - display_name: "src/ivc.c" - description: "IVC implementation for the IVC (Inter-VM Communication) protocol used for communicating with the BPMP" - maintainer: "seL4 Foundation" - status: "Supported on the tx2 platform" - component_type: user-driver-other - # - # libusbdrivers - # - - name: src/usb.c - display_name: "src/usb.c" - description: "Common USB driver for all the USB classes" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/ehci/ - display_name: "src/ehci/*" - description: "Common USB EHCI host controller driver" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/otg.c - display_name: src/otg.c - description: "Common USB OTG driver for the USB OTG specification" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/plat/exynos5/ehci-exynos5.c - display_name: "src/plat/exynos5/ehci-exynos5.c" - description: "Exynos5xxx platform-specific EHCI driver functions" - maintainer: "seL4 Foundation" - status: "Supported on exynos5 platform" - component_type: user-driver-usb - - name: src/plat/imx6/ehci-imx6.c - display_name: "src/plat/imx6/ehci-imx6.c" - description: "i.MX6 platform-specific EHCI driver functions" - maintainer: "seL4 Foundation" - status: "Supported on sabre platform" - component_type: user-driver-usb - - name: src/plat/imx6/otg-imx6.c - display_name: "src/plat/imx6/otg-imx6.c" - description: "i.MX6 platform-specific OTG driver functions" - maintainer: "seL4 Foundation" - status: "Supported on sabre platform" - component_type: user-driver-usb - - name: src/plat/pc99/ehci-pci.c - display_name: "src/plat/pc99/echi-pci.c" - description: "pc99 platform-specific EHCI driver functions" - maintainer: "seL4 Foundation" - status: "Supported on pc99 platform, requires libpci" - component_type: user-driver-usb - - name: src/drivers/arch/arm/usb3503_hub.c - display_name: "src/drivers/arch/arm/usb3503_hub.c" - description: "USB hub controller driver for the Microchip USB3503 USB2.0 hub controller" - maintainer: "seL4 Foundation" - status: "Supported on Arm platforms" - component_type: user-driver-usb - - name: src/drivers/cdc.c - display_name: "src/drivers/cdc.c" - description: "USB driver for the CDC and CDC PSTN subclass specifications" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/drivers/hid.c - display_name: "src/drivers/hid.c" - description: "USB driver for the HID subclass specification" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/drivers/lan9730.c - display_name: "src/drivers/lan9730.c" - description: "USB driver for the Microchip USB to 10/100 Ethernet adaptor" - maintainer: "seL4 Foundation" - status: "Deprecated, requires the lwIP TCP/IP stack" - component_type: user-driver-usb - - name: src/drivers/mouse.c - display_name: "src/drivers/mouse.c" - description: "USB driver for the USB mouse class of devices" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/drivers/otgusbtty.c - display_name: "src/drivers/otgusbtty.c" - description: "USB driver for the OTG tty class of devices" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/drivers/pl2303.c - display_name: "src/drivers/pl2303.c" - description: "USB driver for the Prolific PL2303 USB to Serial adaptor" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/drivers/storage.c - display_name: "src/drivers/storage.c" - description: "USB driver for the USB Mass Storage Class Bulk-Only Transport specification" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/drivers/ufi.c - display_name: "src/drivers/ufi.c" - description: "USB driver for the UFI commands for the USB Mass Storage Class specification" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/drivers/usbhub.c - display_name: "src/drivers/usbhub.c" - description: "USB driver for the USB hub driver class of devices" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb - - name: src/drivers/usbkbd.c - display_name: "src/drivers/usbkbd.c" - description: "USB driver for the USB keyboard class of devices" - maintainer: "seL4 Foundation" - status: "Supported" - component_type: user-driver-usb diff --git a/_data/projects/virtualization.yml b/_data/projects/virtualization.yml deleted file mode 100644 index 762248e209f..00000000000 --- a/_data/projects/virtualization.yml +++ /dev/null @@ -1,115 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -name: virtualization -display_name: Virtualization -description: seL4 hardware virtualization support -project_order: 8 - -repositories: - - org: seL4 - repo: seL4_projects_libs - -components: - - name: arch-arm - display_name: arch-arm - description: "A guest hardware virtualisation library for ARM." - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-architecture - - name: arch-x86 - display_name: arch-x86 - description: "A guest hardware virtualisation library for x86." - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-architecture - - name: boot - display_name: boot - description: "Create initialise and configure VM and VCPU instances" - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-interface - - name: boot - display_name: boot - description: "Create initialise and configure VM and VCPU instances" - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-interface - - name: guest_iospace - display_name: guest_iospace - description: "Registration and management of a guest VM's IO Space." - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-interface - - name: guest_irq_controller - display_name: guest_irq_controller - description: "Initialisation and management of a guest VM irq controller." - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-interface - - name: guest_memory - display_name: guest_memory - description: "Management of a guest VM's address space." - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-interface - - name: vcpu_falut - display_name: vcpu_fault - description: "Query and configure vcpu objects that have faulted during execution." - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-interface - - name: guest_vm - display_name: guest_vm - description: "Provides definitions of the guest vm datastructure and primitives to run the VM instance and start its vcpus." - maintainer: "maintainer wanted" - status: "active" - component_type: vm-virtualization-interface - - name: vmm_device - display_name: vmm_device - description: "Datastructures and helpers to manage VMM devices." - maintainer: "maintainer wanted" - status: "active" - component_type: vmmplatsupport-virtualization-interface - - name: vmm_guest_image - display_name: vmm_guest_image - description: "General utilites to load guest vm images (e.g. kernel, initrd, modules)." - maintainer: "maintainer wanted" - status: "active" - component_type: vmmplatsupport-virtualization-interface - - name: vmm_ioports - display_name: vmm_ioports - description: "Initialising, registering and handling ioport events for a guest VM instance" - maintainer: "maintainer wanted" - status: "active" - component_type: vmmplatsupport-virtualization-interface - - name: pci - display_name: pci - description: "VMM pci driver" - maintainer: "maintainer wanted" - status: "active" - component_type: vmmplatsupport-drivers - - name: virtio_con - display_name: virtio_con - description: "VMM virtio console driver." - maintainer: "maintainer wanted" - status: "active" - component_type: vmmplatsupport-virtualization-interface - - name: virtio_net - display_name: virtio_net - description: "VMM virtio net driver." - maintainer: "maintainer wanted" - status: "active" - component_type: vmmplatsupport-virtualization-interface - - name: cross_vm_connection - display_name: cross_vm_connection - description: "Facilitates the creation of communication channels between VM's and other components on an seL4-based system." - maintainer: "maintainer wanted" - status: "active" - component_type: vmmplatsupport-virtualization-interface - - name: vusb - display_name: vusb - description: "Virtual USB driver for ARM-based VM's." - maintainer: "maintainer wanted" - status: "active" - component_type: vmmplatsupport-virtualization-interface diff --git a/_data/sidebar.yml b/_data/sidebar.yml deleted file mode 100644 index d467937a374..00000000000 --- a/_data/sidebar.yml +++ /dev/null @@ -1,221 +0,0 @@ -# SPDX-License-Identifier: BSD-2-Clause -# Copyright 2020 seL4 Project a Series of LF Projects, LLC. - -toc: - - title: Getting Started - subfolderitems: - - page: Overview - url: /getting-started.html - - page: Tutorials - url: /Tutorials/ - - page: Setting up with Docker - url: /projects/dockerfiles/ - - page: Repo manifest cheat sheet - url: /projects/buildsystem/repo-cheatsheet.html - - - title: The seL4 Kernel - subfolderitems: - - page: Overview - url: /projects/sel4/ - - page: Setting up - url: /projects/buildsystem/host-dependencies.html - - title: Tutorial - subfolderitems: - - page: Setting up - url: /Tutorials/setting-up.html - - page: Getting the tutorials - url: /Tutorials/get-the-tutorials.html - - page: Hello world - url: /Tutorials/hello-world.html - - page: Capabilities - url: /Tutorials/capabilities.html - - page: Untyped - url: /Tutorials/untyped.html - - page: Mapping - url: /Tutorials/mapping.html - - page: Threads - url: /Tutorials/threads.html - - page: IPC - url: /Tutorials/ipc.html - - page: Notifications - url: /Tutorials/notifications.html - - page: Interrupts - url: /Tutorials/interrupts.html - - page: Fault handling - url: /Tutorials/fault-handlers.html - - page: MCS - url: /Tutorials/mcs.html - - page: End - url: /Tutorials/seL4-end.html - - page: How-to - url: /Tutorials/how-to-seL4.html - - page: API docs - url: /projects/sel4/api-doc.html - - page: Manual - url: /projects/sel4/manual.html - - page: Supported platforms - url: /Hardware/ - - page: Verified configurations - url: /projects/sel4/verified-configurations.html - - page: Configurations - url: /projects/sel4/configurations.html - - page: Standalone seL4 builds - url: /projects/buildsystem/standalone.html - - page: Bitfield generator - url: /projects/sel4/bfgen.html - - title: Testing & benchmarking - subfolderitems: - - page: seL4test - url: /projects/sel4test/ - - page: Debugging guide - url: /projects/sel4-tutorials/debugging-guide.html - - page: Debugging user space - url: /projects/sel4-tutorials/debugging-userspace.html - - page: sel4bench - url: /projects/sel4bench/ - - page: Benchmarking guide - url: /projects/sel4-tutorials/benchmarking-guide.html - - page: Contributing - url: /projects/sel4/kernel-contribution.html - - page: Porting to a new platform - url: /projects/sel4/porting.html - - page: Releases - url: /releases/seL4.html - - page: Sources - url: https://github.com/seL4/seL4 - - - divider: true - - - title: Microkit - subfolderitems: - - page: Overview - url: /projects/microkit/ - - page: Setting up your machine - url: /projects/microkit/setting-up.html - - title: Tutorial - subfolderitems: - - page: Welcome - url: /projects/microkit/tutorial/welcome.html - - page: Part 0 - Setting up - url: /projects/microkit/tutorial/part0.html - - page: Part 1 - Serial server - url: /projects/microkit/tutorial/part1.html - - page: Part 2 - Client - url: /projects/microkit/tutorial/part2.html - - page: Part 3 - Wordle server - url: /projects/microkit/tutorial/part3.html - - page: Part 4 - Virtual machines - url: /projects/microkit/tutorial/part4.html - - page: End - url: /projects/microkit/tutorial/end.html - - page: Manual - url: /projects/microkit/manual/latest/ - - page: Roadmap - url: /projects/microkit/roadmap.html - - page: Supported platforms - url: /projects/microkit/platforms.html - - page: Releases - url: /releases/microkit.html - - page: Sources - url: https://github.com/seL4/microkit - - title: CAmkES - subfolderitems: - - page: Overview - url: /projects/camkes/ - - page: Setting up your machine - url: /projects/camkes/setting-up.html - - title: Tutorials - subfolderitems: - - page: Hello CAmkES - url: /Tutorials/hello-camkes-0.html - - page: Introduction - url: /Tutorials/hello-camkes-1.html - - page: Events - url: /Tutorials/hello-camkes-2.html - - page: Timer - url: /Tutorials/hello-camkes-timer.html - - page: Virtual Machines - url: /Tutorials/camkes-vm-linux.html - - page: Cross-VM connectors - url: /Tutorials/camkes-vm-crossvm.html - - page: How-to - url: /Tutorials/how-to-CAmkES.html - - page: Manual - url: /projects/camkes/manual.html - - page: Supported platforms - url: /projects/camkes/hardware.html - - title: Virtualisation - subfolderitems: - - page: CAmkES VM - url: /projects/camkes-vm/ - - page: VM library - url: /projects/virtualization/docs/libsel4vm.html - - page: VMM library - url: /projects/virtualization/docs/libsel4vmm.html - - page: Releases - url: /releases/camkes.html - - page: Sources - url: https://github.com/seL4/camkes-tool/ - - - divider: true - - - title: C support - subfolderitems: - - page: C runtime - url: /projects/sel4runtime/ - - page: User-level libraries - url: /projects/user_libs/ - - page: Build System - url: /projects/buildsystem/ - - title: Tutorials - subfolderitems: - - page: Init & Threads - url: /Tutorials/libraries-1.html - - page: IPC - url: /Tutorials/libraries-2.html - - page: ELF loading & Processes - url: /Tutorials/libraries-3.html - - page: Timer - url: /Tutorials/libraries-4.html - - page: How-to - url: /Tutorials/how-to-libs.html - - title: Rust support - subfolderitems: - - page: Overview - url: /projects/rust/ - - page: How to use - url: /projects/rust/how-to-use.html - - page: Tutorial - url: /projects/rust/tutorial/introduction.html - - page: API - url: https://sel4.github.io/rust-sel4/ - - page: Supported configurations - url: /projects/rust/supported-configurations.html - - page: Releases - url: /projects/rust/releases.html - - page: Sources - url: https://github.com/seL4/rust-sel4 - - - divider: true - - - title: ELF loader - subfolderitems: - - page: ELF loader for C - url: /projects/elfloader/ - - title: capDL - subfolderitems: - - page: Overview - url: /projects/capdl/ - - page: Language Spec - url: /projects/capdl/lang-spec.html - - page: capDL loader (C) - url: /projects/capdl/c-loader-app.html - - page: Releases - url: /releases/capDL.html - - - divider: true - - - title: Examples & demos - subfolderitems: - - page: Overview - url: /examples.html diff --git a/_icons/academic-cap.svg b/_icons/academic-cap.svg deleted file mode 100644 index cd05c0e30f9..00000000000 --- a/_icons/academic-cap.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/adjustments-horizontal.svg b/_icons/adjustments-horizontal.svg deleted file mode 100644 index 24a8bc7ce64..00000000000 --- a/_icons/adjustments-horizontal.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/adjustments-vertical.svg b/_icons/adjustments-vertical.svg deleted file mode 100644 index 8ec937cd32d..00000000000 --- a/_icons/adjustments-vertical.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/archive-box-arrow-down.svg b/_icons/archive-box-arrow-down.svg deleted file mode 100644 index a325df478a1..00000000000 --- a/_icons/archive-box-arrow-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/archive-box-x-mark.svg b/_icons/archive-box-x-mark.svg deleted file mode 100644 index cca86e1017b..00000000000 --- a/_icons/archive-box-x-mark.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/archive-box.svg b/_icons/archive-box.svg deleted file mode 100644 index 921a5826457..00000000000 --- a/_icons/archive-box.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-down-circle.svg b/_icons/arrow-down-circle.svg deleted file mode 100644 index 954042dc5e0..00000000000 --- a/_icons/arrow-down-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-down-left.svg b/_icons/arrow-down-left.svg deleted file mode 100644 index be398da5d9f..00000000000 --- a/_icons/arrow-down-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-down-on-square-stack.svg b/_icons/arrow-down-on-square-stack.svg deleted file mode 100644 index 6032f2c75d0..00000000000 --- a/_icons/arrow-down-on-square-stack.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-down-on-square.svg b/_icons/arrow-down-on-square.svg deleted file mode 100644 index d7253860826..00000000000 --- a/_icons/arrow-down-on-square.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-down-right.svg b/_icons/arrow-down-right.svg deleted file mode 100644 index d31282ef027..00000000000 --- a/_icons/arrow-down-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-down-tray.svg b/_icons/arrow-down-tray.svg deleted file mode 100644 index 2b8890c57a9..00000000000 --- a/_icons/arrow-down-tray.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-down.svg b/_icons/arrow-down.svg deleted file mode 100644 index 5e1a5de9ebe..00000000000 --- a/_icons/arrow-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-left-circle.svg b/_icons/arrow-left-circle.svg deleted file mode 100644 index 82402825bdf..00000000000 --- a/_icons/arrow-left-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-left-end-on-rectangle.svg b/_icons/arrow-left-end-on-rectangle.svg deleted file mode 100644 index 4bca1c92015..00000000000 --- a/_icons/arrow-left-end-on-rectangle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-left-on-rectangle.svg b/_icons/arrow-left-on-rectangle.svg deleted file mode 100644 index 4bca1c92015..00000000000 --- a/_icons/arrow-left-on-rectangle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-left-start-on-rectangle.svg b/_icons/arrow-left-start-on-rectangle.svg deleted file mode 100644 index 29997d2d6f1..00000000000 --- a/_icons/arrow-left-start-on-rectangle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-left.svg b/_icons/arrow-left.svg deleted file mode 100644 index 10719883b8c..00000000000 --- a/_icons/arrow-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-long-down.svg b/_icons/arrow-long-down.svg deleted file mode 100644 index 768a29957b9..00000000000 --- a/_icons/arrow-long-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-long-left.svg b/_icons/arrow-long-left.svg deleted file mode 100644 index 0c019237098..00000000000 --- a/_icons/arrow-long-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-long-right.svg b/_icons/arrow-long-right.svg deleted file mode 100644 index 746e1e46c42..00000000000 --- a/_icons/arrow-long-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-long-up.svg b/_icons/arrow-long-up.svg deleted file mode 100644 index bebf680c045..00000000000 --- a/_icons/arrow-long-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-path-rounded-square.svg b/_icons/arrow-path-rounded-square.svg deleted file mode 100644 index 4392295177f..00000000000 --- a/_icons/arrow-path-rounded-square.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-path.svg b/_icons/arrow-path.svg deleted file mode 100644 index fba7241af87..00000000000 --- a/_icons/arrow-path.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-right-circle.svg b/_icons/arrow-right-circle.svg deleted file mode 100644 index 6f065a08bb2..00000000000 --- a/_icons/arrow-right-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-right-end-on-rectangle.svg b/_icons/arrow-right-end-on-rectangle.svg deleted file mode 100644 index 48ffe90160a..00000000000 --- a/_icons/arrow-right-end-on-rectangle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-right-on-rectangle.svg b/_icons/arrow-right-on-rectangle.svg deleted file mode 100644 index abea6bfaa24..00000000000 --- a/_icons/arrow-right-on-rectangle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-right-start-on-rectangle.svg b/_icons/arrow-right-start-on-rectangle.svg deleted file mode 100644 index abea6bfaa24..00000000000 --- a/_icons/arrow-right-start-on-rectangle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-right.svg b/_icons/arrow-right.svg deleted file mode 100644 index f700b1fd6f2..00000000000 --- a/_icons/arrow-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-small-down.svg b/_icons/arrow-small-down.svg deleted file mode 100644 index 9977f0ee847..00000000000 --- a/_icons/arrow-small-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-small-left.svg b/_icons/arrow-small-left.svg deleted file mode 100644 index 8d54067cf32..00000000000 --- a/_icons/arrow-small-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-small-right.svg b/_icons/arrow-small-right.svg deleted file mode 100644 index af2ef624841..00000000000 --- a/_icons/arrow-small-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-small-up.svg b/_icons/arrow-small-up.svg deleted file mode 100644 index 78e282d2139..00000000000 --- a/_icons/arrow-small-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-top-right-on-square.svg b/_icons/arrow-top-right-on-square.svg deleted file mode 100644 index f3fb15f7664..00000000000 --- a/_icons/arrow-top-right-on-square.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-trending-down.svg b/_icons/arrow-trending-down.svg deleted file mode 100644 index 75f083af95a..00000000000 --- a/_icons/arrow-trending-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-trending-up.svg b/_icons/arrow-trending-up.svg deleted file mode 100644 index b79bfbeee25..00000000000 --- a/_icons/arrow-trending-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-turn-down-left.svg b/_icons/arrow-turn-down-left.svg deleted file mode 100644 index 4425ea1c7ff..00000000000 --- a/_icons/arrow-turn-down-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-turn-down-right.svg b/_icons/arrow-turn-down-right.svg deleted file mode 100644 index 1efaec14309..00000000000 --- a/_icons/arrow-turn-down-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-turn-left-down.svg b/_icons/arrow-turn-left-down.svg deleted file mode 100644 index 8ca63d95ab2..00000000000 --- a/_icons/arrow-turn-left-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-turn-left-up.svg b/_icons/arrow-turn-left-up.svg deleted file mode 100644 index 37cc0b9cc1a..00000000000 --- a/_icons/arrow-turn-left-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-turn-right-down.svg b/_icons/arrow-turn-right-down.svg deleted file mode 100644 index e10ebd3679f..00000000000 --- a/_icons/arrow-turn-right-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-turn-right-up.svg b/_icons/arrow-turn-right-up.svg deleted file mode 100644 index ddf4cd81a79..00000000000 --- a/_icons/arrow-turn-right-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-turn-up-left.svg b/_icons/arrow-turn-up-left.svg deleted file mode 100644 index 3b2a3304d4c..00000000000 --- a/_icons/arrow-turn-up-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-turn-up-right.svg b/_icons/arrow-turn-up-right.svg deleted file mode 100644 index 7a9e437d3c5..00000000000 --- a/_icons/arrow-turn-up-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-up-circle.svg b/_icons/arrow-up-circle.svg deleted file mode 100644 index c2e0359995b..00000000000 --- a/_icons/arrow-up-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-up-left.svg b/_icons/arrow-up-left.svg deleted file mode 100644 index 65531688307..00000000000 --- a/_icons/arrow-up-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-up-on-square-stack.svg b/_icons/arrow-up-on-square-stack.svg deleted file mode 100644 index f1b3d5ec8d9..00000000000 --- a/_icons/arrow-up-on-square-stack.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-up-on-square.svg b/_icons/arrow-up-on-square.svg deleted file mode 100644 index 3625717f1f3..00000000000 --- a/_icons/arrow-up-on-square.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-up-right.svg b/_icons/arrow-up-right.svg deleted file mode 100644 index 9ec7dee53b9..00000000000 --- a/_icons/arrow-up-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-up-tray.svg b/_icons/arrow-up-tray.svg deleted file mode 100644 index 3779677d6f4..00000000000 --- a/_icons/arrow-up-tray.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-up.svg b/_icons/arrow-up.svg deleted file mode 100644 index cb05fb249dc..00000000000 --- a/_icons/arrow-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-uturn-down.svg b/_icons/arrow-uturn-down.svg deleted file mode 100644 index f3620083943..00000000000 --- a/_icons/arrow-uturn-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-uturn-left.svg b/_icons/arrow-uturn-left.svg deleted file mode 100644 index 5a9819c4ec2..00000000000 --- a/_icons/arrow-uturn-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-uturn-right.svg b/_icons/arrow-uturn-right.svg deleted file mode 100644 index 244e674c648..00000000000 --- a/_icons/arrow-uturn-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrow-uturn-up.svg b/_icons/arrow-uturn-up.svg deleted file mode 100644 index a19ff964827..00000000000 --- a/_icons/arrow-uturn-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrows-pointing-in.svg b/_icons/arrows-pointing-in.svg deleted file mode 100644 index 2621d38e730..00000000000 --- a/_icons/arrows-pointing-in.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrows-pointing-out.svg b/_icons/arrows-pointing-out.svg deleted file mode 100644 index 73de08c6d84..00000000000 --- a/_icons/arrows-pointing-out.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrows-right-left.svg b/_icons/arrows-right-left.svg deleted file mode 100644 index 22dca0aa569..00000000000 --- a/_icons/arrows-right-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/arrows-up-down.svg b/_icons/arrows-up-down.svg deleted file mode 100644 index f8cc08f60ef..00000000000 --- a/_icons/arrows-up-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/at-symbol.svg b/_icons/at-symbol.svg deleted file mode 100644 index 2b9e4469ca4..00000000000 --- a/_icons/at-symbol.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/backspace.svg b/_icons/backspace.svg deleted file mode 100644 index 1563d7d1230..00000000000 --- a/_icons/backspace.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/backward.svg b/_icons/backward.svg deleted file mode 100644 index ff788f8b79e..00000000000 --- a/_icons/backward.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/banknotes.svg b/_icons/banknotes.svg deleted file mode 100644 index 945f60eaf87..00000000000 --- a/_icons/banknotes.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bars-2.svg b/_icons/bars-2.svg deleted file mode 100644 index d64a9bbba89..00000000000 --- a/_icons/bars-2.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bars-3-bottom-left.svg b/_icons/bars-3-bottom-left.svg deleted file mode 100644 index 9960567af46..00000000000 --- a/_icons/bars-3-bottom-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bars-3-bottom-right.svg b/_icons/bars-3-bottom-right.svg deleted file mode 100644 index 4e90c18c79d..00000000000 --- a/_icons/bars-3-bottom-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bars-3-center-left.svg b/_icons/bars-3-center-left.svg deleted file mode 100644 index cca274c9eb8..00000000000 --- a/_icons/bars-3-center-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bars-3.svg b/_icons/bars-3.svg deleted file mode 100644 index 6d2221f7ef5..00000000000 --- a/_icons/bars-3.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bars-4.svg b/_icons/bars-4.svg deleted file mode 100644 index b9e9c465329..00000000000 --- a/_icons/bars-4.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bars-arrow-down.svg b/_icons/bars-arrow-down.svg deleted file mode 100644 index 91af7e4e550..00000000000 --- a/_icons/bars-arrow-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bars-arrow-up.svg b/_icons/bars-arrow-up.svg deleted file mode 100644 index 5c515e5187a..00000000000 --- a/_icons/bars-arrow-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/battery-0.svg b/_icons/battery-0.svg deleted file mode 100644 index b9811f78a32..00000000000 --- a/_icons/battery-0.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/battery-100.svg b/_icons/battery-100.svg deleted file mode 100644 index f88087909c5..00000000000 --- a/_icons/battery-100.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/battery-50.svg b/_icons/battery-50.svg deleted file mode 100644 index 0018f8dee43..00000000000 --- a/_icons/battery-50.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/beaker.svg b/_icons/beaker.svg deleted file mode 100644 index 9457e9aed1e..00000000000 --- a/_icons/beaker.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bell-alert.svg b/_icons/bell-alert.svg deleted file mode 100644 index 68d2f64cd3f..00000000000 --- a/_icons/bell-alert.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bell-slash.svg b/_icons/bell-slash.svg deleted file mode 100644 index fc31652c891..00000000000 --- a/_icons/bell-slash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bell-snooze.svg b/_icons/bell-snooze.svg deleted file mode 100644 index 10fa5bdd8eb..00000000000 --- a/_icons/bell-snooze.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bell.svg b/_icons/bell.svg deleted file mode 100644 index 8145b9d2b05..00000000000 --- a/_icons/bell.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bold.svg b/_icons/bold.svg deleted file mode 100644 index d815857cf4e..00000000000 --- a/_icons/bold.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bolt-slash.svg b/_icons/bolt-slash.svg deleted file mode 100644 index 91f81b4a0c3..00000000000 --- a/_icons/bolt-slash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bolt.svg b/_icons/bolt.svg deleted file mode 100644 index 506283d9a3e..00000000000 --- a/_icons/bolt.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/book-open.svg b/_icons/book-open.svg deleted file mode 100644 index de02b1466dd..00000000000 --- a/_icons/book-open.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bookmark-slash.svg b/_icons/bookmark-slash.svg deleted file mode 100644 index d55d5aea568..00000000000 --- a/_icons/bookmark-slash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bookmark-square.svg b/_icons/bookmark-square.svg deleted file mode 100644 index 538d9e64a7a..00000000000 --- a/_icons/bookmark-square.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bookmark.svg b/_icons/bookmark.svg deleted file mode 100644 index 4e88a5cc545..00000000000 --- a/_icons/bookmark.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/briefcase.svg b/_icons/briefcase.svg deleted file mode 100644 index d0c1fc35248..00000000000 --- a/_icons/briefcase.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/bug-ant.svg b/_icons/bug-ant.svg deleted file mode 100644 index 056d5a5ff1e..00000000000 --- a/_icons/bug-ant.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/building-library.svg b/_icons/building-library.svg deleted file mode 100644 index 2ea181cb4d3..00000000000 --- a/_icons/building-library.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/building-office-2.svg b/_icons/building-office-2.svg deleted file mode 100644 index d1f922aac6d..00000000000 --- a/_icons/building-office-2.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/building-office.svg b/_icons/building-office.svg deleted file mode 100644 index 695729fe59f..00000000000 --- a/_icons/building-office.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/building-storefront.svg b/_icons/building-storefront.svg deleted file mode 100644 index 8e287f88943..00000000000 --- a/_icons/building-storefront.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cake.svg b/_icons/cake.svg deleted file mode 100644 index aa770ce75bf..00000000000 --- a/_icons/cake.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/calculator.svg b/_icons/calculator.svg deleted file mode 100644 index ef441d61f21..00000000000 --- a/_icons/calculator.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/calendar-date-range.svg b/_icons/calendar-date-range.svg deleted file mode 100644 index e1e91190fa2..00000000000 --- a/_icons/calendar-date-range.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/calendar-days.svg b/_icons/calendar-days.svg deleted file mode 100644 index 94731d7b187..00000000000 --- a/_icons/calendar-days.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/calendar.svg b/_icons/calendar.svg deleted file mode 100644 index 81b3dfc847c..00000000000 --- a/_icons/calendar.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/camera.svg b/_icons/camera.svg deleted file mode 100644 index aabc3c637a4..00000000000 --- a/_icons/camera.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/chart-bar-square.svg b/_icons/chart-bar-square.svg deleted file mode 100644 index e03b7df5c3c..00000000000 --- a/_icons/chart-bar-square.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chart-bar.svg b/_icons/chart-bar.svg deleted file mode 100644 index 31ff30c4eb8..00000000000 --- a/_icons/chart-bar.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chart-pie.svg b/_icons/chart-pie.svg deleted file mode 100644 index eebd21fe578..00000000000 --- a/_icons/chart-pie.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/chat-bubble-bottom-center-text.svg b/_icons/chat-bubble-bottom-center-text.svg deleted file mode 100644 index 549b4b2eeec..00000000000 --- a/_icons/chat-bubble-bottom-center-text.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chat-bubble-bottom-center.svg b/_icons/chat-bubble-bottom-center.svg deleted file mode 100644 index 3bd9cf4eaf8..00000000000 --- a/_icons/chat-bubble-bottom-center.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chat-bubble-left-ellipsis.svg b/_icons/chat-bubble-left-ellipsis.svg deleted file mode 100644 index 5865363c1ad..00000000000 --- a/_icons/chat-bubble-left-ellipsis.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chat-bubble-left-right.svg b/_icons/chat-bubble-left-right.svg deleted file mode 100644 index fb00eb15d28..00000000000 --- a/_icons/chat-bubble-left-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chat-bubble-left.svg b/_icons/chat-bubble-left.svg deleted file mode 100644 index 1c0d9867c86..00000000000 --- a/_icons/chat-bubble-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chat-bubble-oval-left-ellipsis.svg b/_icons/chat-bubble-oval-left-ellipsis.svg deleted file mode 100644 index 3cc9ce5ae98..00000000000 --- a/_icons/chat-bubble-oval-left-ellipsis.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chat-bubble-oval-left.svg b/_icons/chat-bubble-oval-left.svg deleted file mode 100644 index c4bab3a678e..00000000000 --- a/_icons/chat-bubble-oval-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/check-badge.svg b/_icons/check-badge.svg deleted file mode 100644 index d39704d01fc..00000000000 --- a/_icons/check-badge.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/check-circle-mini.svg b/_icons/check-circle-mini.svg deleted file mode 100644 index 763716ead0c..00000000000 --- a/_icons/check-circle-mini.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/check-circle.svg b/_icons/check-circle.svg deleted file mode 100644 index 912ffc67ff4..00000000000 --- a/_icons/check-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/check.svg b/_icons/check.svg deleted file mode 100644 index 37ad683eb3a..00000000000 --- a/_icons/check.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-double-down.svg b/_icons/chevron-double-down.svg deleted file mode 100644 index 308710e13a3..00000000000 --- a/_icons/chevron-double-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-double-left.svg b/_icons/chevron-double-left.svg deleted file mode 100644 index 7af02329e17..00000000000 --- a/_icons/chevron-double-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-double-right.svg b/_icons/chevron-double-right.svg deleted file mode 100644 index e29b66f104f..00000000000 --- a/_icons/chevron-double-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-double-up.svg b/_icons/chevron-double-up.svg deleted file mode 100644 index ab19f2e470a..00000000000 --- a/_icons/chevron-double-up.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/chevron-down-mini.svg b/_icons/chevron-down-mini.svg deleted file mode 100644 index 18cbc1d415b..00000000000 --- a/_icons/chevron-down-mini.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-down.svg b/_icons/chevron-down.svg deleted file mode 100644 index b6ac1cf6e76..00000000000 --- a/_icons/chevron-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-left.svg b/_icons/chevron-left.svg deleted file mode 100644 index 5e9f57b8b1f..00000000000 --- a/_icons/chevron-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-right.svg b/_icons/chevron-right.svg deleted file mode 100644 index cd8a45723c7..00000000000 --- a/_icons/chevron-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-up-down.svg b/_icons/chevron-up-down.svg deleted file mode 100644 index ba6820a0efb..00000000000 --- a/_icons/chevron-up-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/chevron-up.svg b/_icons/chevron-up.svg deleted file mode 100644 index eafbff4a38b..00000000000 --- a/_icons/chevron-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/circle-stack.svg b/_icons/circle-stack.svg deleted file mode 100644 index 2f75456c509..00000000000 --- a/_icons/circle-stack.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/clipboard-document-check.svg b/_icons/clipboard-document-check.svg deleted file mode 100644 index b4be34b8e52..00000000000 --- a/_icons/clipboard-document-check.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/clipboard-document-list.svg b/_icons/clipboard-document-list.svg deleted file mode 100644 index 11e818a37d9..00000000000 --- a/_icons/clipboard-document-list.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/clipboard-document.svg b/_icons/clipboard-document.svg deleted file mode 100644 index 31eb487aa14..00000000000 --- a/_icons/clipboard-document.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/clipboard.svg b/_icons/clipboard.svg deleted file mode 100644 index 2e7501e123e..00000000000 --- a/_icons/clipboard.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/clock.svg b/_icons/clock.svg deleted file mode 100644 index a7fce7bdf83..00000000000 --- a/_icons/clock.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cloud-arrow-down.svg b/_icons/cloud-arrow-down.svg deleted file mode 100644 index 9bbee4ffa7f..00000000000 --- a/_icons/cloud-arrow-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cloud-arrow-up.svg b/_icons/cloud-arrow-up.svg deleted file mode 100644 index 09944371958..00000000000 --- a/_icons/cloud-arrow-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cloud.svg b/_icons/cloud.svg deleted file mode 100644 index 9662d6cced9..00000000000 --- a/_icons/cloud.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/code-bracket-square.svg b/_icons/code-bracket-square.svg deleted file mode 100644 index de71371e903..00000000000 --- a/_icons/code-bracket-square.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/code-bracket.svg b/_icons/code-bracket.svg deleted file mode 100644 index 8754e635669..00000000000 --- a/_icons/code-bracket.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cog-6-tooth.svg b/_icons/cog-6-tooth.svg deleted file mode 100644 index 91ba7db9fbf..00000000000 --- a/_icons/cog-6-tooth.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/cog-8-tooth.svg b/_icons/cog-8-tooth.svg deleted file mode 100644 index 515cc16d99a..00000000000 --- a/_icons/cog-8-tooth.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/cog.svg b/_icons/cog.svg deleted file mode 100644 index 5aadb3e484b..00000000000 --- a/_icons/cog.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/command-line.svg b/_icons/command-line.svg deleted file mode 100644 index 6f9f8f9c751..00000000000 --- a/_icons/command-line.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/computer-desktop.svg b/_icons/computer-desktop.svg deleted file mode 100644 index 1744ea270dd..00000000000 --- a/_icons/computer-desktop.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cpu-chip.svg b/_icons/cpu-chip.svg deleted file mode 100644 index 7ab9e09c9e9..00000000000 --- a/_icons/cpu-chip.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/credit-card.svg b/_icons/credit-card.svg deleted file mode 100644 index fbe46d802e2..00000000000 --- a/_icons/credit-card.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cube-transparent.svg b/_icons/cube-transparent.svg deleted file mode 100644 index 10f4c2c4aa2..00000000000 --- a/_icons/cube-transparent.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cube.svg b/_icons/cube.svg deleted file mode 100644 index 87d16c0b40e..00000000000 --- a/_icons/cube.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/currency-bangladeshi.svg b/_icons/currency-bangladeshi.svg deleted file mode 100644 index 4aaae03bb62..00000000000 --- a/_icons/currency-bangladeshi.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/currency-dollar.svg b/_icons/currency-dollar.svg deleted file mode 100644 index a69380e1e90..00000000000 --- a/_icons/currency-dollar.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/currency-euro.svg b/_icons/currency-euro.svg deleted file mode 100644 index b6504f3432c..00000000000 --- a/_icons/currency-euro.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/currency-pound.svg b/_icons/currency-pound.svg deleted file mode 100644 index fb323779296..00000000000 --- a/_icons/currency-pound.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/currency-rupee.svg b/_icons/currency-rupee.svg deleted file mode 100644 index 2040a225af8..00000000000 --- a/_icons/currency-rupee.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/currency-yen.svg b/_icons/currency-yen.svg deleted file mode 100644 index 80d3c998036..00000000000 --- a/_icons/currency-yen.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cursor-arrow-rays.svg b/_icons/cursor-arrow-rays.svg deleted file mode 100644 index 813793c3f06..00000000000 --- a/_icons/cursor-arrow-rays.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/cursor-arrow-ripple.svg b/_icons/cursor-arrow-ripple.svg deleted file mode 100644 index 24dbb3e1770..00000000000 --- a/_icons/cursor-arrow-ripple.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/device-phone-mobile.svg b/_icons/device-phone-mobile.svg deleted file mode 100644 index 7ff5ae21f34..00000000000 --- a/_icons/device-phone-mobile.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/device-tablet.svg b/_icons/device-tablet.svg deleted file mode 100644 index 58b94a4cb66..00000000000 --- a/_icons/device-tablet.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/divide.svg b/_icons/divide.svg deleted file mode 100644 index d657f36bf44..00000000000 --- a/_icons/divide.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-arrow-down.svg b/_icons/document-arrow-down.svg deleted file mode 100644 index 39cb4d3b0a9..00000000000 --- a/_icons/document-arrow-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-arrow-up.svg b/_icons/document-arrow-up.svg deleted file mode 100644 index f4ad8445bf6..00000000000 --- a/_icons/document-arrow-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-chart-bar.svg b/_icons/document-chart-bar.svg deleted file mode 100644 index 0bf7dc1e226..00000000000 --- a/_icons/document-chart-bar.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-check.svg b/_icons/document-check.svg deleted file mode 100644 index 6ef1c98cec4..00000000000 --- a/_icons/document-check.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-currency-bangladeshi.svg b/_icons/document-currency-bangladeshi.svg deleted file mode 100644 index 16bc3bffdce..00000000000 --- a/_icons/document-currency-bangladeshi.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-currency-dollar.svg b/_icons/document-currency-dollar.svg deleted file mode 100644 index e07ce046829..00000000000 --- a/_icons/document-currency-dollar.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-currency-euro.svg b/_icons/document-currency-euro.svg deleted file mode 100644 index 0a9846acf3f..00000000000 --- a/_icons/document-currency-euro.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-currency-pound.svg b/_icons/document-currency-pound.svg deleted file mode 100644 index 9944c17742b..00000000000 --- a/_icons/document-currency-pound.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-currency-rupee.svg b/_icons/document-currency-rupee.svg deleted file mode 100644 index 5767becb1ff..00000000000 --- a/_icons/document-currency-rupee.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-currency-yen.svg b/_icons/document-currency-yen.svg deleted file mode 100644 index 8e2b98331ee..00000000000 --- a/_icons/document-currency-yen.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-duplicate.svg b/_icons/document-duplicate.svg deleted file mode 100644 index 9c6bc80d821..00000000000 --- a/_icons/document-duplicate.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-magnifying-glass.svg b/_icons/document-magnifying-glass.svg deleted file mode 100644 index ebf1b1352c0..00000000000 --- a/_icons/document-magnifying-glass.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-minus.svg b/_icons/document-minus.svg deleted file mode 100644 index a13b6fe91ba..00000000000 --- a/_icons/document-minus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-plus.svg b/_icons/document-plus.svg deleted file mode 100644 index e06def85247..00000000000 --- a/_icons/document-plus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document-text.svg b/_icons/document-text.svg deleted file mode 100644 index 8c03e9ede9c..00000000000 --- a/_icons/document-text.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/document.svg b/_icons/document.svg deleted file mode 100644 index 5a4881a188c..00000000000 --- a/_icons/document.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/ellipsis-horizontal-circle.svg b/_icons/ellipsis-horizontal-circle.svg deleted file mode 100644 index d6f11dd99bd..00000000000 --- a/_icons/ellipsis-horizontal-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/ellipsis-horizontal.svg b/_icons/ellipsis-horizontal.svg deleted file mode 100644 index 4efa28a1977..00000000000 --- a/_icons/ellipsis-horizontal.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/ellipsis-vertical.svg b/_icons/ellipsis-vertical.svg deleted file mode 100644 index 2caf3e05a0b..00000000000 --- a/_icons/ellipsis-vertical.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/envelope-open.svg b/_icons/envelope-open.svg deleted file mode 100644 index 01f34be546d..00000000000 --- a/_icons/envelope-open.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/envelope.svg b/_icons/envelope.svg deleted file mode 100644 index b8029e8623e..00000000000 --- a/_icons/envelope.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/equals.svg b/_icons/equals.svg deleted file mode 100644 index 3c9702bafb1..00000000000 --- a/_icons/equals.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/exclamation-circle.svg b/_icons/exclamation-circle.svg deleted file mode 100644 index 0833d8e6839..00000000000 --- a/_icons/exclamation-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/exclamation-triangle.svg b/_icons/exclamation-triangle.svg deleted file mode 100644 index dc2e6cf8513..00000000000 --- a/_icons/exclamation-triangle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/eye-dropper.svg b/_icons/eye-dropper.svg deleted file mode 100644 index c1b7b8acaf4..00000000000 --- a/_icons/eye-dropper.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/eye-slash.svg b/_icons/eye-slash.svg deleted file mode 100644 index fb794247970..00000000000 --- a/_icons/eye-slash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/eye.svg b/_icons/eye.svg deleted file mode 100644 index f4ae935cd44..00000000000 --- a/_icons/eye.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/face-frown.svg b/_icons/face-frown.svg deleted file mode 100644 index 86af7b0b687..00000000000 --- a/_icons/face-frown.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/face-smile.svg b/_icons/face-smile.svg deleted file mode 100644 index e9872820677..00000000000 --- a/_icons/face-smile.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/film.svg b/_icons/film.svg deleted file mode 100644 index f02856d8139..00000000000 --- a/_icons/film.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/finger-print.svg b/_icons/finger-print.svg deleted file mode 100644 index 2de9f82392c..00000000000 --- a/_icons/finger-print.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/fire.svg b/_icons/fire.svg deleted file mode 100644 index 0e944f56cc8..00000000000 --- a/_icons/fire.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/flag.svg b/_icons/flag.svg deleted file mode 100644 index f5d17df363c..00000000000 --- a/_icons/flag.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/folder-arrow-down.svg b/_icons/folder-arrow-down.svg deleted file mode 100644 index 74f0b6c751c..00000000000 --- a/_icons/folder-arrow-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/folder-minus.svg b/_icons/folder-minus.svg deleted file mode 100644 index fc4212b9200..00000000000 --- a/_icons/folder-minus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/folder-open.svg b/_icons/folder-open.svg deleted file mode 100644 index df90e716593..00000000000 --- a/_icons/folder-open.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/folder-plus.svg b/_icons/folder-plus.svg deleted file mode 100644 index 8acf5f7f041..00000000000 --- a/_icons/folder-plus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/folder.svg b/_icons/folder.svg deleted file mode 100644 index 4c301addab1..00000000000 --- a/_icons/folder.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/forward.svg b/_icons/forward.svg deleted file mode 100644 index 317f5ce7b61..00000000000 --- a/_icons/forward.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/funnel.svg b/_icons/funnel.svg deleted file mode 100644 index 5937bdc1119..00000000000 --- a/_icons/funnel.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/gif.svg b/_icons/gif.svg deleted file mode 100644 index 6d22acae0db..00000000000 --- a/_icons/gif.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/gift-top.svg b/_icons/gift-top.svg deleted file mode 100644 index 3eb1793ad4a..00000000000 --- a/_icons/gift-top.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/gift.svg b/_icons/gift.svg deleted file mode 100644 index a856b6f717c..00000000000 --- a/_icons/gift.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/globe-alt.svg b/_icons/globe-alt.svg deleted file mode 100644 index b63d26891b4..00000000000 --- a/_icons/globe-alt.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/globe-americas.svg b/_icons/globe-americas.svg deleted file mode 100644 index f0a6beb5d34..00000000000 --- a/_icons/globe-americas.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/globe-asia-australia.svg b/_icons/globe-asia-australia.svg deleted file mode 100644 index 396cd3cc55f..00000000000 --- a/_icons/globe-asia-australia.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/globe-europe-africa.svg b/_icons/globe-europe-africa.svg deleted file mode 100644 index 427637dd23b..00000000000 --- a/_icons/globe-europe-africa.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/h1.svg b/_icons/h1.svg deleted file mode 100644 index e70d229a21b..00000000000 --- a/_icons/h1.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/h2.svg b/_icons/h2.svg deleted file mode 100644 index 5fd0ee03968..00000000000 --- a/_icons/h2.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/h3.svg b/_icons/h3.svg deleted file mode 100644 index 386c70f4178..00000000000 --- a/_icons/h3.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/hand-raised.svg b/_icons/hand-raised.svg deleted file mode 100644 index c9008af25e6..00000000000 --- a/_icons/hand-raised.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/hand-thumb-down.svg b/_icons/hand-thumb-down.svg deleted file mode 100644 index 3d2cc169a0b..00000000000 --- a/_icons/hand-thumb-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/hand-thumb-up.svg b/_icons/hand-thumb-up.svg deleted file mode 100644 index 01b987736ce..00000000000 --- a/_icons/hand-thumb-up.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/hashtag.svg b/_icons/hashtag.svg deleted file mode 100644 index 9956ce047af..00000000000 --- a/_icons/hashtag.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/heart.svg b/_icons/heart.svg deleted file mode 100644 index 2c371f3347d..00000000000 --- a/_icons/heart.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/home-modern.svg b/_icons/home-modern.svg deleted file mode 100644 index b081fe88eaf..00000000000 --- a/_icons/home-modern.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/home.svg b/_icons/home.svg deleted file mode 100644 index e1900b8eb3c..00000000000 --- a/_icons/home.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/identification.svg b/_icons/identification.svg deleted file mode 100644 index 9a99a61d3ec..00000000000 --- a/_icons/identification.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/inbox-arrow-down.svg b/_icons/inbox-arrow-down.svg deleted file mode 100644 index 686060b1908..00000000000 --- a/_icons/inbox-arrow-down.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/inbox-stack.svg b/_icons/inbox-stack.svg deleted file mode 100644 index c8a6ebbbb66..00000000000 --- a/_icons/inbox-stack.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/inbox.svg b/_icons/inbox.svg deleted file mode 100644 index 2a26cee2d03..00000000000 --- a/_icons/inbox.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/information-circle.svg b/_icons/information-circle.svg deleted file mode 100644 index d4ac360db25..00000000000 --- a/_icons/information-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/italic.svg b/_icons/italic.svg deleted file mode 100644 index b4243241ac7..00000000000 --- a/_icons/italic.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/key.svg b/_icons/key.svg deleted file mode 100644 index 30c5bde595b..00000000000 --- a/_icons/key.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/language.svg b/_icons/language.svg deleted file mode 100644 index 1094eb16fdc..00000000000 --- a/_icons/language.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/lifebuoy.svg b/_icons/lifebuoy.svg deleted file mode 100644 index 446562bc469..00000000000 --- a/_icons/lifebuoy.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/light-bulb.svg b/_icons/light-bulb.svg deleted file mode 100644 index 37c0317925f..00000000000 --- a/_icons/light-bulb.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/link-slash.svg b/_icons/link-slash.svg deleted file mode 100644 index 9d6f0e8e62f..00000000000 --- a/_icons/link-slash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/link.svg b/_icons/link.svg deleted file mode 100644 index 38febfc2df1..00000000000 --- a/_icons/link.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/list-bullet.svg b/_icons/list-bullet.svg deleted file mode 100644 index 0dcb9404e90..00000000000 --- a/_icons/list-bullet.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/lock-closed.svg b/_icons/lock-closed.svg deleted file mode 100644 index 4917dbb43d5..00000000000 --- a/_icons/lock-closed.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/lock-open.svg b/_icons/lock-open.svg deleted file mode 100644 index 7f9a5a33244..00000000000 --- a/_icons/lock-open.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/magnifying-glass-circle.svg b/_icons/magnifying-glass-circle.svg deleted file mode 100644 index 4c0da1f028f..00000000000 --- a/_icons/magnifying-glass-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/magnifying-glass-minus.svg b/_icons/magnifying-glass-minus.svg deleted file mode 100644 index d4dfada09b1..00000000000 --- a/_icons/magnifying-glass-minus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/magnifying-glass-plus.svg b/_icons/magnifying-glass-plus.svg deleted file mode 100644 index a1d4363b6d3..00000000000 --- a/_icons/magnifying-glass-plus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/magnifying-glass.svg b/_icons/magnifying-glass.svg deleted file mode 100644 index 947336ca825..00000000000 --- a/_icons/magnifying-glass.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/map-pin.svg b/_icons/map-pin.svg deleted file mode 100644 index 74cc7867a65..00000000000 --- a/_icons/map-pin.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/map.svg b/_icons/map.svg deleted file mode 100644 index 2d9e239b9bf..00000000000 --- a/_icons/map.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/megaphone.svg b/_icons/megaphone.svg deleted file mode 100644 index 2b3c60b6853..00000000000 --- a/_icons/megaphone.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/microphone.svg b/_icons/microphone.svg deleted file mode 100644 index e349845ba91..00000000000 --- a/_icons/microphone.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/minus-circle.svg b/_icons/minus-circle.svg deleted file mode 100644 index 7cc1de3c661..00000000000 --- a/_icons/minus-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/minus-small.svg b/_icons/minus-small.svg deleted file mode 100644 index 25144c88cc1..00000000000 --- a/_icons/minus-small.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/minus.svg b/_icons/minus.svg deleted file mode 100644 index fa1fb8b2b5d..00000000000 --- a/_icons/minus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/moon.svg b/_icons/moon.svg deleted file mode 100644 index 6a13b2f2295..00000000000 --- a/_icons/moon.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/musical-note.svg b/_icons/musical-note.svg deleted file mode 100644 index d903ff2be05..00000000000 --- a/_icons/musical-note.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/newspaper.svg b/_icons/newspaper.svg deleted file mode 100644 index 666274fc54c..00000000000 --- a/_icons/newspaper.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/no-symbol.svg b/_icons/no-symbol.svg deleted file mode 100644 index a7dd36568b9..00000000000 --- a/_icons/no-symbol.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/numbered-list.svg b/_icons/numbered-list.svg deleted file mode 100644 index 10ba0725a1f..00000000000 --- a/_icons/numbered-list.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/other/C.svg b/_icons/other/C.svg deleted file mode 100644 index afe73f1b568..00000000000 --- a/_icons/other/C.svg +++ /dev/null @@ -1,56 +0,0 @@ - - - - - - - - - - - - diff --git a/_icons/other/external.svg b/_icons/other/external.svg deleted file mode 100644 index c79e3a2e095..00000000000 --- a/_icons/other/external.svg +++ /dev/null @@ -1,3 +0,0 @@ - \ No newline at end of file diff --git a/_icons/other/github.svg b/_icons/other/github.svg deleted file mode 100644 index 7665190e2bb..00000000000 --- a/_icons/other/github.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/other/rust-logo-blk.svg b/_icons/other/rust-logo-blk.svg deleted file mode 100644 index e4ef32bde1c..00000000000 --- a/_icons/other/rust-logo-blk.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - - \ No newline at end of file diff --git a/_icons/paint-brush.svg b/_icons/paint-brush.svg deleted file mode 100644 index 21a208e6562..00000000000 --- a/_icons/paint-brush.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/paper-airplane.svg b/_icons/paper-airplane.svg deleted file mode 100644 index 80db4d0d70e..00000000000 --- a/_icons/paper-airplane.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/paper-clip.svg b/_icons/paper-clip.svg deleted file mode 100644 index c27a60ab4b4..00000000000 --- a/_icons/paper-clip.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/pause-circle.svg b/_icons/pause-circle.svg deleted file mode 100644 index 723e5f2c331..00000000000 --- a/_icons/pause-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/pause.svg b/_icons/pause.svg deleted file mode 100644 index 7a611048d71..00000000000 --- a/_icons/pause.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/pencil-square.svg b/_icons/pencil-square.svg deleted file mode 100644 index 01de21ea0a4..00000000000 --- a/_icons/pencil-square.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/pencil.svg b/_icons/pencil.svg deleted file mode 100644 index 7af74ab9182..00000000000 --- a/_icons/pencil.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/percent-badge.svg b/_icons/percent-badge.svg deleted file mode 100644 index 2f84596994c..00000000000 --- a/_icons/percent-badge.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/phone-arrow-down-left.svg b/_icons/phone-arrow-down-left.svg deleted file mode 100644 index 31185c876f2..00000000000 --- a/_icons/phone-arrow-down-left.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/phone-arrow-up-right.svg b/_icons/phone-arrow-up-right.svg deleted file mode 100644 index ab875b04b89..00000000000 --- a/_icons/phone-arrow-up-right.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/phone-x-mark.svg b/_icons/phone-x-mark.svg deleted file mode 100644 index 50568f0f616..00000000000 --- a/_icons/phone-x-mark.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/phone.svg b/_icons/phone.svg deleted file mode 100644 index a8789d133ac..00000000000 --- a/_icons/phone.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/photo.svg b/_icons/photo.svg deleted file mode 100644 index 0e65af2129c..00000000000 --- a/_icons/photo.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/play-circle.svg b/_icons/play-circle.svg deleted file mode 100644 index d83a73f33f4..00000000000 --- a/_icons/play-circle.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/play-pause.svg b/_icons/play-pause.svg deleted file mode 100644 index 943efcb5ca6..00000000000 --- a/_icons/play-pause.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/play.svg b/_icons/play.svg deleted file mode 100644 index 3c0fad30896..00000000000 --- a/_icons/play.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/plus-circle.svg b/_icons/plus-circle.svg deleted file mode 100644 index 1beab85b1b0..00000000000 --- a/_icons/plus-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/plus-small.svg b/_icons/plus-small.svg deleted file mode 100644 index 7fb7dcb148b..00000000000 --- a/_icons/plus-small.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/plus.svg b/_icons/plus.svg deleted file mode 100644 index 06b312f7972..00000000000 --- a/_icons/plus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/power.svg b/_icons/power.svg deleted file mode 100644 index e471a03ab69..00000000000 --- a/_icons/power.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/presentation-chart-bar.svg b/_icons/presentation-chart-bar.svg deleted file mode 100644 index d0564395938..00000000000 --- a/_icons/presentation-chart-bar.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/presentation-chart-line.svg b/_icons/presentation-chart-line.svg deleted file mode 100644 index ed212e5cf00..00000000000 --- a/_icons/presentation-chart-line.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/printer.svg b/_icons/printer.svg deleted file mode 100644 index f3c1c54874d..00000000000 --- a/_icons/printer.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/puzzle-piece.svg b/_icons/puzzle-piece.svg deleted file mode 100644 index 004855be7f3..00000000000 --- a/_icons/puzzle-piece.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/qr-code.svg b/_icons/qr-code.svg deleted file mode 100644 index 1cbd5d4ccf9..00000000000 --- a/_icons/qr-code.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/question-mark-circle.svg b/_icons/question-mark-circle.svg deleted file mode 100644 index e3dd599a878..00000000000 --- a/_icons/question-mark-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/queue-list.svg b/_icons/queue-list.svg deleted file mode 100644 index 09f0066485a..00000000000 --- a/_icons/queue-list.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/radio.svg b/_icons/radio.svg deleted file mode 100644 index 81c891b89b6..00000000000 --- a/_icons/radio.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/receipt-percent.svg b/_icons/receipt-percent.svg deleted file mode 100644 index 4dd59964a24..00000000000 --- a/_icons/receipt-percent.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/receipt-refund.svg b/_icons/receipt-refund.svg deleted file mode 100644 index 345a8977aac..00000000000 --- a/_icons/receipt-refund.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/rectangle-group.svg b/_icons/rectangle-group.svg deleted file mode 100644 index 8184b196967..00000000000 --- a/_icons/rectangle-group.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/rectangle-stack.svg b/_icons/rectangle-stack.svg deleted file mode 100644 index 8eb419a4573..00000000000 --- a/_icons/rectangle-stack.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/rocket-launch.svg b/_icons/rocket-launch.svg deleted file mode 100644 index a6a6cb97ed5..00000000000 --- a/_icons/rocket-launch.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/rss.svg b/_icons/rss.svg deleted file mode 100644 index ff1e1a81d7b..00000000000 --- a/_icons/rss.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/scale.svg b/_icons/scale.svg deleted file mode 100644 index 559bcdab8ff..00000000000 --- a/_icons/scale.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/scissors.svg b/_icons/scissors.svg deleted file mode 100644 index 4df73af1c49..00000000000 --- a/_icons/scissors.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/server-stack.svg b/_icons/server-stack.svg deleted file mode 100644 index 060c8208911..00000000000 --- a/_icons/server-stack.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/server.svg b/_icons/server.svg deleted file mode 100644 index eef8b9e5a84..00000000000 --- a/_icons/server.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/share.svg b/_icons/share.svg deleted file mode 100644 index e931243977d..00000000000 --- a/_icons/share.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/shield-check.svg b/_icons/shield-check.svg deleted file mode 100644 index 82b91259ae8..00000000000 --- a/_icons/shield-check.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/shield-exclamation.svg b/_icons/shield-exclamation.svg deleted file mode 100644 index 5a8df1724a0..00000000000 --- a/_icons/shield-exclamation.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/shopping-bag.svg b/_icons/shopping-bag.svg deleted file mode 100644 index 7c5f29b4976..00000000000 --- a/_icons/shopping-bag.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/shopping-cart.svg b/_icons/shopping-cart.svg deleted file mode 100644 index b86c2abbcf8..00000000000 --- a/_icons/shopping-cart.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/signal-slash.svg b/_icons/signal-slash.svg deleted file mode 100644 index b858fdf7239..00000000000 --- a/_icons/signal-slash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/signal.svg b/_icons/signal.svg deleted file mode 100644 index 9daa002575e..00000000000 --- a/_icons/signal.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/slash.svg b/_icons/slash.svg deleted file mode 100644 index 782434d9581..00000000000 --- a/_icons/slash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/sparkles.svg b/_icons/sparkles.svg deleted file mode 100644 index c8df7f1f32a..00000000000 --- a/_icons/sparkles.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/speaker-wave.svg b/_icons/speaker-wave.svg deleted file mode 100644 index 7bb46f263e7..00000000000 --- a/_icons/speaker-wave.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/speaker-x-mark.svg b/_icons/speaker-x-mark.svg deleted file mode 100644 index e89da3e685e..00000000000 --- a/_icons/speaker-x-mark.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/square-2-stack.svg b/_icons/square-2-stack.svg deleted file mode 100644 index d6d6ca9de2a..00000000000 --- a/_icons/square-2-stack.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/square-3-stack-3d.svg b/_icons/square-3-stack-3d.svg deleted file mode 100644 index d11f07bc101..00000000000 --- a/_icons/square-3-stack-3d.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/squares-2x2.svg b/_icons/squares-2x2.svg deleted file mode 100644 index 1fe6594da80..00000000000 --- a/_icons/squares-2x2.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/squares-plus.svg b/_icons/squares-plus.svg deleted file mode 100644 index b87a5f12f01..00000000000 --- a/_icons/squares-plus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/star.svg b/_icons/star.svg deleted file mode 100644 index 1f27ec8d3b7..00000000000 --- a/_icons/star.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/stop-circle.svg b/_icons/stop-circle.svg deleted file mode 100644 index 26c2aba9fe2..00000000000 --- a/_icons/stop-circle.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/stop.svg b/_icons/stop.svg deleted file mode 100644 index 2058714a68c..00000000000 --- a/_icons/stop.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/strikethrough.svg b/_icons/strikethrough.svg deleted file mode 100644 index 9ec9b9da7f2..00000000000 --- a/_icons/strikethrough.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/sun.svg b/_icons/sun.svg deleted file mode 100644 index 0e49045aa68..00000000000 --- a/_icons/sun.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/swatch.svg b/_icons/swatch.svg deleted file mode 100644 index e1e1b2761ac..00000000000 --- a/_icons/swatch.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/table-cells.svg b/_icons/table-cells.svg deleted file mode 100644 index 3d0f11413a6..00000000000 --- a/_icons/table-cells.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/tag.svg b/_icons/tag.svg deleted file mode 100644 index 01eb0a355ca..00000000000 --- a/_icons/tag.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/ticket.svg b/_icons/ticket.svg deleted file mode 100644 index f06ce3bfcba..00000000000 --- a/_icons/ticket.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/trash.svg b/_icons/trash.svg deleted file mode 100644 index 71669b096ce..00000000000 --- a/_icons/trash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/trophy.svg b/_icons/trophy.svg deleted file mode 100644 index 955622718e0..00000000000 --- a/_icons/trophy.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/truck.svg b/_icons/truck.svg deleted file mode 100644 index 7f475c87bd1..00000000000 --- a/_icons/truck.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/tv.svg b/_icons/tv.svg deleted file mode 100644 index b6fae6aa730..00000000000 --- a/_icons/tv.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/underline.svg b/_icons/underline.svg deleted file mode 100644 index 56a205164ae..00000000000 --- a/_icons/underline.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/user-circle.svg b/_icons/user-circle.svg deleted file mode 100644 index 74a941e6ded..00000000000 --- a/_icons/user-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/user-group.svg b/_icons/user-group.svg deleted file mode 100644 index 2a3159e92a8..00000000000 --- a/_icons/user-group.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/user-minus.svg b/_icons/user-minus.svg deleted file mode 100644 index 878cc7a9659..00000000000 --- a/_icons/user-minus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/user-plus.svg b/_icons/user-plus.svg deleted file mode 100644 index a3c9bfce09f..00000000000 --- a/_icons/user-plus.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/user.svg b/_icons/user.svg deleted file mode 100644 index 9a343c4cef6..00000000000 --- a/_icons/user.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/users.svg b/_icons/users.svg deleted file mode 100644 index 1de4a729920..00000000000 --- a/_icons/users.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/variable.svg b/_icons/variable.svg deleted file mode 100644 index 4656e2f124c..00000000000 --- a/_icons/variable.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/video-camera-slash.svg b/_icons/video-camera-slash.svg deleted file mode 100644 index c08bd006911..00000000000 --- a/_icons/video-camera-slash.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/video-camera.svg b/_icons/video-camera.svg deleted file mode 100644 index 1af46bdafd5..00000000000 --- a/_icons/video-camera.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/view-columns.svg b/_icons/view-columns.svg deleted file mode 100644 index bc9a440aee9..00000000000 --- a/_icons/view-columns.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/viewfinder-circle.svg b/_icons/viewfinder-circle.svg deleted file mode 100644 index 947dcd8fc82..00000000000 --- a/_icons/viewfinder-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/wallet.svg b/_icons/wallet.svg deleted file mode 100644 index 58989cf954f..00000000000 --- a/_icons/wallet.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/wifi.svg b/_icons/wifi.svg deleted file mode 100644 index c838da48726..00000000000 --- a/_icons/wifi.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/window.svg b/_icons/window.svg deleted file mode 100644 index fcccbe2f774..00000000000 --- a/_icons/window.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/wrench-screwdriver.svg b/_icons/wrench-screwdriver.svg deleted file mode 100644 index 8d05c28d4fa..00000000000 --- a/_icons/wrench-screwdriver.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/wrench.svg b/_icons/wrench.svg deleted file mode 100644 index 56c6f8d4d62..00000000000 --- a/_icons/wrench.svg +++ /dev/null @@ -1,4 +0,0 @@ - diff --git a/_icons/x-circle.svg b/_icons/x-circle.svg deleted file mode 100644 index e8d86efb328..00000000000 --- a/_icons/x-circle.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_icons/x-mark.svg b/_icons/x-mark.svg deleted file mode 100644 index 19b4ac7698a..00000000000 --- a/_icons/x-mark.svg +++ /dev/null @@ -1,3 +0,0 @@ - diff --git a/_includes/archived.html b/_includes/archived.html deleted file mode 100644 index 7a4de09fba9..00000000000 --- a/_includes/archived.html +++ /dev/null @@ -1,10 +0,0 @@ -{%- comment %} -Copyright 2025 Proofcraft Pty Ltd -SPDX-License-Identifier: CC-BY-SA-4.0 -{% endcomment -%} -{%- if page.archive %} -
-

This page is archived and is no longer receiving updates.

-

It remains here because some of the content may still be useful.

-
-{%- endif %} diff --git a/_includes/card.html b/_includes/card.html deleted file mode 100644 index 3dea023569d..00000000000 --- a/_includes/card.html +++ /dev/null @@ -1,54 +0,0 @@ -{%- comment %} -Copyright 2025 Proofcraft Pty Ltd -SPDX-License-Identifier: CC-BY-SA-4.0 -{% endcomment -%} -{%- assign link_text = include.link_text | default: "Learn more" -%} -{%- assign icon = "_icons/" | append: include.icon | append: ".svg" -%} -{%- assign icon_colour = include.icon_colour | default: "bg-logogreen text-black" -%} -{%- if include.center %} -{%- assign centering = "col-span-1 sm:col-span-2 lg:col-span-1 sm:w-1/2 sm:mx-auto lg:w-full" %} -{%- endif -%} -
- {% if include.icon %} -
- {% if include.link %}{% endif %} -
- {% svg "{{icon}}" class="h-8 w-8" %} -
- {% if include.link %}{% endif %} -
- {% endif %} -
-

- {{ include.title }} -

-
- {{ include.body }} -
- {%- if include.no_link_text and include.link %} - - Link to {{ include.title }} - - - {%- endif %} - {%- unless include.no_link_text %} - {%- if include.link %} -
- {{ link_text }} - - -
- {% endif -%} - {% endunless -%} - {%- if include.info %} -
-
{{include.info}}
-
- {% endif -%} -
-
diff --git a/_includes/card_example.html b/_includes/card_example.html deleted file mode 100644 index 8d474421fc4..00000000000 --- a/_includes/card_example.html +++ /dev/null @@ -1,43 +0,0 @@ -{%- comment %} -Copyright 2025 Proofcraft Pty Ltd -SPDX-License-Identifier: CC-BY-SA-4.0 -{% endcomment -%} -{% capture info %} -
- {% if include.rust %} -
- Rust -
- {% endif %} - {% if include.C %} -
- C -
- {% endif %} - {% if include.mkit %} -
- Microkit -
- {% endif %} - {% if include.camkes %} -
- CAmkES -
- {% endif %} -
-
- See the code -   - {% svg _icons/other/external.svg class="inline-icon" %} -
-{% endcapture -%} -{%- include card.html - title = include.title - link = include.link - icon = include.icon - center = include.center - class = include.class - no_link_text = true - body = include.body - info = info --%} diff --git a/_includes/component_list.md b/_includes/component_list.md deleted file mode 100644 index 8cbefb77f51..00000000000 --- a/_includes/component_list.md +++ /dev/null @@ -1,14 +0,0 @@ -{%- comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{%- endcomment %} -{%- assign list = include.list | default: 'components' %} -{%- assign status = include.status | default: "Status" %} -{%- include config_list.md - project=include.project - list=list - type=include.type - code=include.code - status=status - no_status=include.no_status - filter=include.filter %} diff --git a/_includes/cond-wrap-link.md b/_includes/cond-wrap-link.md deleted file mode 100644 index 7cd55ef1671..00000000000 --- a/_includes/cond-wrap-link.md +++ /dev/null @@ -1,5 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} -{%- if include.link != '' %}[{{include.text}}]({{include.link}}){% else %}{{include.text}}{% endif -%} diff --git a/_includes/config_list.md b/_includes/config_list.md deleted file mode 100644 index 90c996622e2..00000000000 --- a/_includes/config_list.md +++ /dev/null @@ -1,70 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} -{%- assign project = site.data.projects[include.project] %} -{%- assign list = include.list | default: 'configurations' %} -{%- assign status = include.status | default: "Value" %} -{%- if include.code == false %} -{%- assign code = "" %} -{%- assign endcode = "" %} -{%- else %} -{%- assign code = '
' %}
-{%-   assign endcode = "
" %} -{%- endif %} - - - - - - {%- unless include.no_status %} - - {%- endunless %} - - - -{%- for component in project[list] %} -{%- if include.type and include.type != component.component_type -%} -{%- continue %} -{%- endif %} -{%- if include.filter and component.status != include.filter %} -{%- continue %} -{%- endif %} -{%- capture link_text %}{{component.display_name_url}}{% endcapture %} -{%- capture display_text %}{{code}}{{component.display_name}}{{endcode}}{% endcapture %} - - - - {%- unless include.no_status %} - - {%- endunless %} - -{%- endfor -%} - - - -
-{%- for component in project[list] %} -{%- if include.type and include.type != component.component_type -%} -{%- continue %} -{%- endif %} -{%- if include.filter and component.status != include.filter %} -{%- continue %} -{%- endif %} -
-{%- capture link_text %}{{component.display_name_url}}{% endcapture %} -{%- capture display_text %}{{code}}{{component.display_name}}{{endcode}}{% endcapture %} -
{% include cond-wrap-link.md text=display_text link=link_text %}
-
-
- {{component.description | markdownify}} -
- {%- unless include.no_status %} -
- {{component.status}} -
- {%- endunless %} -{%- endfor -%} -
diff --git a/_includes/custom-navbar.html b/_includes/custom-navbar.html deleted file mode 100644 index 1a837fd2c0a..00000000000 --- a/_includes/custom-navbar.html +++ /dev/null @@ -1,43 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} -
- - -
-
diff --git a/_includes/endnote.html b/_includes/endnote.html deleted file mode 100644 index 590262df734..00000000000 --- a/_includes/endnote.html +++ /dev/null @@ -1,6 +0,0 @@ -{%- comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd -{% endcomment %} - - diff --git a/_includes/endtab.html b/_includes/endtab.html deleted file mode 100644 index 590262df734..00000000000 --- a/_includes/endtab.html +++ /dev/null @@ -1,6 +0,0 @@ -{%- comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd -{% endcomment %} - - diff --git a/_includes/endtabs.html b/_includes/endtabs.html deleted file mode 100644 index 08b02d08695..00000000000 --- a/_includes/endtabs.html +++ /dev/null @@ -1,5 +0,0 @@ -{%- comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd -{% endcomment %} - diff --git a/_includes/footer.html b/_includes/footer.html deleted file mode 100644 index ffdae3c423d..00000000000 --- a/_includes/footer.html +++ /dev/null @@ -1,31 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} -
- Sitemap - Test status -
-{%- if page.include_file %} -{%- assign edit_url = 'https://github.com/' | append: page.repo | - append: '/edit/master/' | append: page.include_file %} -{%- assign included = 'included' %} -{%- else %} -{%- comment %} - Collection pages set their absolute path variable relative to the site.collections_dir property. - To provide a URL to this page in the GitHub repository, we need to amend the path. -{%- endcomment %} -{%- if page.collection -%} -{%- assign src_path = site.collections_dir | append: "/" | append: page.path -%} -{%- else -%} -{%- assign src_path = page.path -%} -{%- endif -%} -{%- assign edit_url = site.git_repo | append: '/edit/master/' | append: src_path %} -{%- assign included = '' %} -{%- endif %} -Edit - {{included}} page on GitHub -
diff --git a/_includes/generic_update_page.md b/_includes/generic_update_page.md deleted file mode 100644 index 99530eea479..00000000000 --- a/_includes/generic_update_page.md +++ /dev/null @@ -1,9 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} -{% assign update_where_exp = "item.url contains '/updates/" | append: include.project | append: "/'" %} -{% assign updates = site['updates'] | where_exp:"item", update_where_exp %} -{% for update in updates | sort: "date" %} -[{{ update.title }}]({{ update.url }}) -{% endfor %} diff --git a/_includes/header.html b/_includes/header.html deleted file mode 100644 index e7ad5790ccf..00000000000 --- a/_includes/header.html +++ /dev/null @@ -1,39 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} -
-
-
- {% svg _icons/bars-3.svg class="text-dark ml-3 mr-0 sm:mr-3 lg:mx-4 w-4 h-4 lg:w-6 lg:h-6 cursor-pointer" %} -
-
- - Releases - - - Contribute - - - Contact - - - Support - - - Main Site - {% svg _icons/other/external.svg class="hidden sm:inline-icon" %} - - - - seL4 on GitHub - {% svg _icons/other/github.svg class="w-4 h-4 sm:w-5 sm:h-5 lg:w-6 lg:h-6" %} - -
-
diff --git a/_includes/highlight.css b/_includes/highlight.css deleted file mode 100644 index 2ba4028b380..00000000000 --- a/_includes/highlight.css +++ /dev/null @@ -1,101 +0,0 @@ -/* - Copyright 2025 seL4 Project a Series of LF Projects, LLC. - SPDX-License-Identifier: CC-BY-SA-4.0 -*/ - -.highlight table td { padding: 5px; } -.highlight table pre { margin: 0; } -.highlight, .highlight .w { - color: #fbf1c7; -} -.highlight .err { - color: #fb4934; - background-color: #282828; - font-weight: bold; -} -.highlight .c, .highlight .ch, .highlight .cd, .highlight .cm, .highlight .cpf, .highlight .c1, .highlight .cs { - color: var(--color-slate-400); - font-style: italic; -} -.highlight .cp { - color: #8ec07c; -} -.highlight .nt { - color: #fb4934; -} -.highlight .o, .highlight .ow { - color: #fbf1c7; -} -.highlight .p, .highlight .pi { - color: #fbf1c7; -} -.highlight .gi { - color: #b8bb26; - background-color: #282828; -} -.highlight .gd { - color: #fb4934; - background-color: #282828; -} -.highlight .gh { - color: #b8bb26; - font-weight: bold; -} -.highlight .ge { - font-style: italic; -} -.highlight .ges { - font-weight: bold; - font-style: italic; -} -.highlight .gs { - font-weight: bold; -} -.highlight .k, .highlight .kn, .highlight .kp, .highlight .kr, .highlight .kv { - color: #fb4934; -} -.highlight .kc { - color: #d3869b; -} -.highlight .kt { - color: #fabd2f; -} -.highlight .kd { - color: #fe8019; -} -.highlight .s, .highlight .sb, .highlight .sc, .highlight .dl, .highlight .sd, .highlight .s2, .highlight .sh, .highlight .sx, .highlight .s1 { - color: #b8bb26; - font-style: italic; -} -.highlight .si { - color: #b8bb26; - font-style: italic; -} -.highlight .sr { - color: #b8bb26; - font-style: italic; -} -.highlight .sa { - color: #fb4934; -} -.highlight .se { - color: #fe8019; -} -.highlight .nn { - color: #8ec07c; -} -.highlight .nc { - color: #8ec07c; -} -.highlight .no { - color: #d3869b; -} -.highlight .na { - color: #b8bb26; -} -.highlight .m, .highlight .mb, .highlight .mf, .highlight .mh, .highlight .mi, .highlight .il, .highlight .mo, .highlight .mx { - color: #d3869b; -} -.highlight .ss { - color: #83a598; -} diff --git a/_includes/hw-info.html b/_includes/hw-info.html deleted file mode 100644 index 30a6f55a66f..00000000000 --- a/_includes/hw-info.html +++ /dev/null @@ -1,106 +0,0 @@ -{%- comment %} -Copyright 2025 Proofcraft Pty Ltd -SPDX-License-Identifier: CC-BY-SA-4.0 -{% endcomment -%} -{% if page.Maintained == false %} -{% include note.html kind="Important" %} -This board is no longer supported by seL4. -{% include endnote.html %} -{% endif %} - - - - - -{% if page.simulation_target -%} - - - -{%- endif %} - - - -{% if page.soc -%} - - - -{%- endif %} -{% if page.cpu -%} - - - -{%- endif %} - - - - - -{%- if page.platform == "PC99" %} -{%- assign SMMU = "IOMMU (VT-d)" %} -{%- else %} -{%- assign SMMU = "SMMU" %} -{%- endif %} - - - -{%- assign status = "" %} -{%- for config in page.verification -%} -{%- assign link = "/projects/sel4/verified-configurations.html#" | append: config | relative_url -%} -{%- assign status = status | append: '' | append: config | append: '' %} -{%- unless forloop.last %} -{%- assign status = status | append: ", " %} -{%- endunless %} -{%- endfor %} - - - - - - - - -{% if page.cmake_plat -%} - - - - -{%- endif %} - - - -{% unless page.Maintained == false or page.archive %} - - - -{% endunless %} - -
Platform {{ page.platform }}
Simulation platform yes
Architecture {{ page.arch }}
System-on-chip {{ page.soc }}
CPU {{ page.cpu }}
seL4 virtualisation support -{%- if page.virtualization %} -{% svg _icons/check.svg class="inline-icon stroke-3 text-f_green-500 dark:text-logogreen" %} -{%- else %} -– -{%- endif %} -
seL4 {{SMMU}} support -{%- if page.iommu %} -{%- if page.iommu == "limited" %} -{%- assign color="text-yellow-500" %} -{%- assign text="limited support" %} -{%- else %} -{%- assign color="text-f_green-500 dark:text-logogreen" %} -{%- assign text="" %} -{%- endif %} -{% svg _icons/check.svg class="inline-icon stroke-3" %} {{text}} -{%- else %} -– -{%- endif %} -
Proofs -{%- if status != "" %} - {% svg _icons/check.svg class="inline-icon stroke-3 text-f_green-500 dark:text-logogreen" %} -{%- elsif page.simulation_only %} -N/A -{%- assign status = "N/A" %} -{%- else %} -{%- assign status = "–" %} - – -{%- endif %} -
Proof configs{{status}}
seL4 CMake platform name{{ page.cmake_plat }}
Contributed by {{ page.Contrib }}
Maintained by {{ page.Maintained }}
diff --git a/_includes/include_external_markdown.md b/_includes/include_external_markdown.md deleted file mode 100644 index 02481d84087..00000000000 --- a/_includes/include_external_markdown.md +++ /dev/null @@ -1,14 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} -{% capture file %} -{% include_absolute {{include.file}} %} -{% endcapture %} -{% assign file = file | replace: site.static_url, site.baseurl %} -{% assign file = file | replace: '.md)', '.html)' %} - -{% if include.indent_headings %} -{% assign file = file | replace: '# ', '## ' %} -{% endif %} -{{ file }} diff --git a/_includes/include_github_repo_markdown.md b/_includes/include_github_repo_markdown.md deleted file mode 100644 index caa755ba473..00000000000 --- a/_includes/include_github_repo_markdown.md +++ /dev/null @@ -1,10 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} - -{% assign repo = include.repo | default: page.repo | downcase %} -{% assign include_file = include.file | default: page.include_file %} -{% assign file = '_repos/' | append: repo | append: "/" | append: include_file %} - -{% include include_external_markdown.md file=file indent_headings=include.indent_headings %} diff --git a/_includes/note.html b/_includes/note.html deleted file mode 100644 index 45913537a55..00000000000 --- a/_includes/note.html +++ /dev/null @@ -1,36 +0,0 @@ -{%- comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd -{% endcomment %} -{% unless include.html -%} -{% assign md = 'markdown="1"' -%} -{% endunless -%} -{% assign kind = include.kind | default: "Note" -%} -{% if kind == "Note" -%} -{% assign icon = "information-circle" -%} -{% assign bcolour = "border-blue-500" -%} -{% assign tcolour = "text-blue-400" -%} -{% elsif kind == "Warning" -%} -{% assign icon = "exclamation-triangle" -%} -{% assign bcolour = "border-yellow-500" -%} -{% assign tcolour = "text-yellow-400" -%} -{% elsif kind == "Caution" -%} -{% assign icon = "shield-exclamation" -%} -{% assign bcolour = "border-red-500" -%} -{% assign tcolour = "text-red-400" -%} -{% elsif kind == "Important" -%} -{% assign icon = "exclamation-circle" -%} -{% assign bcolour = "border-violet-500" -%} -{% assign tcolour = "text-violet-400" -%} -{% elsif kind == "Tip" -%} -{% assign icon = "light-bulb" -%} -{% assign bcolour = "border-f_green-500" -%} -{% assign tcolour = "text-logogreen" -%} -{% endif -%} -{% assign icon = "_icons/" | append: icon | append: ".svg" -%} -
-
- {% svg {{icon}} class="h-5 w-5 inline -mt-0.5 mr-1" %} - {{ kind }} -
-
diff --git a/_includes/pc99.md b/_includes/pc99.md deleted file mode 100644 index 5d7732e9f15..00000000000 --- a/_includes/pc99.md +++ /dev/null @@ -1,77 +0,0 @@ -{%- comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. - -This text is shared between ia32 and x64 -{%- endcomment %} - -seL4 runs on 32-bit ia32 and 64-bit x64 machines, on QEMU and on hardware. - -{% include hw-info.html %} - -## Simulation - -{% include sel4test.md %} - -## Real Hardware - -When running on real hardware console output will be over serial. You will need -to plug a serial cable into your machine to see any output. - -The build system produces a multiboot compliant image for x86; a grub2 -stanza is here, but we usually boot via PXE for convenience. - -``` -menuentry "Load seL4 VM" --class os { - load_video - insmod gzio - insmod part_msdos - insmod ext2 - set root='(hd0,msdos2)' - multiboot /boot/sel4kernel - module /boot/sel4rootserver -} -``` - -Booting via PXEBOOT using -[syslinux PXELINUX](http://www.syslinux.org/wiki/index.php?title=PXELINUX) requires setting up a tftp and dhcp server on the network -that the machine you want to boot is connected to. The -[syslinux](http://www.syslinux.org/wiki/index.php?title=Download) -site has a download for pxelinux which we load over PXEBOOT -that then can load seL4. The configuration for pxelinux.cfg/default is -provided below. - -``` -label seL4 - kernel mboot.32 - append kernel-{{ page.cmake_plat }}-pc99 --- apps-{{ page.cmake_plat }}-pc99 -``` - -## Booting off USB with syslinux - -Use syslinux to create a bootable USB stick as follows. - -Assuming your USB flash drive is at `/dev/sdb` with a FAT partition at -`/dev/sdb1`: - -```bash -install-mbr /dev/sdb -syslinux --install /dev/sdb1 -mount /dev/sdb1 /mnt -cp images/sel4test-driver-image-{{ page.cmake_plat }}-pc99 /mnt/rootserver -cp images/kernel-{{ page.cmake_plat }}-pc99 /mnt/sel4kernel -cat > /mnt/syslinux.cfg < - Error: Python environment is externally managed -
- -Some Linux distributions have changed how Python is managed. If you get an error -saying the Python 'environment is externally managed' follow the instructions -below. The first two steps are needed only once for setup. - -```sh -python3 -m venv {{venv}} -./{{venv}}/bin/pip install {{deps}} -``` - -The following step is needed every time you start using the build environment -in a new shell. - -```sh -source ./{{venv}}/bin/activate -``` - -It is not important where the `{{venv}}` directory is located. -
- diff --git a/_includes/releases.html b/_includes/releases.html deleted file mode 100644 index 2a7e3f28726..00000000000 --- a/_includes/releases.html +++ /dev/null @@ -1,32 +0,0 @@ -{%- comment -%} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd -{%- endcomment %} -{%- assign li-style = "text-center p-1 sm:p-2 rounded-md shadow-md border - dark:border-gray-700/80 bg-white dark:bg-darkblue - dark:shadow-gray-300/30 - hover:bg-slate-50 dark:hover:bg-slate-900 hover:underline - relative" -%} - diff --git a/_includes/risc-v.md b/_includes/risc-v.md deleted file mode 100644 index d9b5425d9e4..00000000000 --- a/_includes/risc-v.md +++ /dev/null @@ -1,20 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} - -It is recommended to build the toolchain from source. - -```sh -git clone https://github.com/riscv/riscv-gnu-toolchain.git -cd riscv-gnu-toolchain -git submodule update --init --recursive -export RISCV=/opt/riscv -./configure --prefix="${RISCV}" --enable-multilib -make linux -``` - -After it is built, add the `$RISCV/bin` folder to your PATH. The built -toolchain works for both 32-bit and 64-bit. - -Alternatively, any pre-built toolchain with `multilib` enabled should work. diff --git a/_includes/seL4-deps.md b/_includes/seL4-deps.md deleted file mode 100644 index 2dcf6464490..00000000000 --- a/_includes/seL4-deps.md +++ /dev/null @@ -1,121 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} - -## Get Google's Repo tool - -The primary way of obtaining and managing seL4 project sources is through -Google's `repo` tool. To start with, get repo by following the -instructions in the section “Install” on the [repo -site](https://gerrit.googlesource.com/git-repo#install). - -See the [repo cheatsheet] page for a quick explanation of how we use repo. - -## Docker or native - -To compile and use seL4 you can either: - -* *Recommended:* follow the [instructions here][docker] to use Docker for - isolating the dependencies from your machine, or -* install the build dependencies below on your local OS - -The following instructions describe how to set up the required dependencies on -your local OS. This page assumes you are building in a Linux OS. We however -encourage site [contributions] for build instructions in other OSes (e.g. -macOS). - -## Ubuntu - -These instructions are intended for Ubuntu LTS versions 20.04 and 22.04. - -{% include note.html %} -If you discover any missing dependencies and packages we welcome new -[contributions] to the page. You can [edit this section directly on GitHub][edit]. -{% include endnote.html %} - -### Base dependencies - -The basic build package on Ubuntu is the `build-essential` package. To install run: - -```sh -sudo apt-get update -sudo apt-get install build-essential -``` - -Additional base dependencies for building seL4 projects on Ubuntu include installing: - -```sh -sudo apt-get install cmake ccache ninja-build cmake-curses-gui -sudo apt-get install libxml2-utils ncurses-dev -sudo apt-get install curl git doxygen device-tree-compiler xxd -sudo apt-get install u-boot-tools -sudo apt-get install python3-dev python3-pip python-is-python3 -sudo apt-get install protobuf-compiler python3-protobuf -``` - -### Simulating with QEMU - -In order to run seL4 projects on a simulator you will need QEMU: - -```sh -sudo apt-get install qemu-system-arm qemu-system-x86 qemu-system-misc -``` - -### Cross-compiling for ARM targets - -To build for ARM targets you will need a cross compiler: - -```sh -sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi -sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu -``` - -(you can install the hardware floating point versions as well if you wish) - -```sh -sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf -``` - -### Cross-compiling for RISC-V targets - -To build for RISC-V targets you will need a cross compiler: - -{% include risc-v.md %} - -### Building the seL4 manual - -If you would like to build the seL4 manual, you will need the following LaTeX pacakges: - -```sh -sudo apt-get install texlive texlive-latex-extra texlive-fonts-extra -``` - -## Debian - -The dependencies listed in our Docker files -[repository](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles) will work for -a Debian Bullseye, most likely also for later releases. You can refer to this repository -for an up-to-date list of base build dependencies. Specifically refer to the -dependencies listed in the file here: - -* [Base Tools](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/blob/master/scripts/base_tools.sh) -* [seL4](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/blob/master/scripts/sel4.sh) -* [LaTeX](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/blob/master/scripts/apply-tex.sh) - -## Python - -A number of Python packages are required to build seL4 and its manual. To install these you can run: - -```sh -pip3 install --user setuptools sel4-deps -``` - -(Some distributions use `pip` for python3, others use `pip3`. Use the Python 3 version for your distribution) - -{% include pip-instructions.md deps="sel4-deps" %} - -[edit]: https://github.com/seL4/docs/edit/master/_includes/seL4-deps.md -[repo cheatsheet]: {{ '/projects/buildsystem/repo-cheatsheet.html' | relative_url }} -[contributions]: {{ '/processes/docs-contributing.html' | relative_url }} -[docker]: {{ '/projects/dockerfiles/' | relative_url }} diff --git a/_includes/sel4test.md b/_includes/sel4test.md deleted file mode 100644 index d300fe0941d..00000000000 --- a/_includes/sel4test.md +++ /dev/null @@ -1,40 +0,0 @@ -{% comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{% endcomment %} - -{% comment %} -This include generates commands for checking out and building sel4test for a particular platorm. -The platform defines what config it uses, and if it specifies a simulation target, then a simulation command will be added. -{% endcomment %} - -Checkout the sel4test project using repo as per [seL4Test] -```bash -repo init -u https://github.com/seL4/sel4test-manifest.git -repo sync -mkdir cbuild -cd cbuild -../init-build.sh -DPLATFORM={{ page.cmake_plat }} {{page.xcompiler_arg}} -# The default cmake wrapper sets up a default configuration for the target platform. -# To change individual settings, run `ccmake .` and change the configuration -# parameters to suit your needs. -ninja - -{%- if page.simulation_target and page.simulation_only == false %} -# This platform is a simulation target. This script should work to run the -# generated image if you also use -DSIMULATION=1 for init-build above: -{%- endif %} -{%- if page.simulation_target %} -./simulate -{%- endif %} - -``` - -{%- if page.simulation_target and page.simulation_only == false %} -If you plan to use the ./simulate script, please be sure to add the -`-DSIMULATION=1` argument when running cmake. -{%- endif %} - -Generated binaries can be found in the `images/` directory. - -[seL4Test]: {{ '/projects/sel4test/' | relative_url }} diff --git a/_includes/sidebar.html b/_includes/sidebar.html deleted file mode 100644 index 5da08b24e61..00000000000 --- a/_includes/sidebar.html +++ /dev/null @@ -1,94 +0,0 @@ -{%- comment -%} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -{%- endcomment -%} -{%- assign page_url = page.url | split: "/" -%} - - - {% svg assets/logo-sel4-docs.svg class="px-4 w-50 h-20 mx-auto mt-4 mb-10" %} - - -
    -{%- for item in site.data.sidebar.toc -%} -{%- if item.divider %} -
  •  
    • -{%- else -%} -{%- assign page_in_list = item.subfolderitems | where: "url", page.url | size -%} -{%- if page.parent -%} -{%- assign subpage_in_list = item.subfolderitems | where: "url", page.parent | size -%} -{%- else -%} -{%- assign subpage_in_list = 0 -%} -{%- endif -%} -{%- if page_in_list == 0 and subpage_in_list == 0 -%} -{%- for entry in item.subfolderitems -%} -{%- assign page_in_list = entry.subfolderitems | where: "url", page.url | size -%} -{%- if page.parent -%} -{%- assign subpage_in_list = entry.subfolderitems | where: "url", page.parent | size -%} -{%- endif -%} -{%- if page_in_list == 1 or subpage_in_list == 1 -%} -{%- break -%} -{%- endif -%} -{%- endfor -%} -{%- endif -%} -{%- if page_in_list == 1 or subpage_in_list == 1 -%} -{%- assign active_title="font-bold" -%} -{%- assign maybe_rotate="" -%} -{%- assign maybe_on="on" -%} -{%- else -%} -{%- assign active_title="" -%} -{%- assign maybe_rotate="rotate-270" -%} -{%- assign maybe_on="" -%} -{%- endif %} -
  • -
    - {% svg _icons/chevron-down-mini.svg class="menu-chevron p-0 h-4 w-4 mb-px -mr-0.5 inline cursor-pointer {{maybe_rotate}}" %} - {{ item.title }} -
    -
      - {%- for entry in item.subfolderitems -%} - {%- if entry.title -%} - {%- assign page_in_sublist = entry.subfolderitems | where: "url", page.url | size -%} - {%- assign subpage_in_sublist = entry.subfolderitems | where: "url", page.parent | size -%} - {%- if page_in_sublist == 1 or subpage_in_sublist == 1 -%} - {%- assign active_title="font-bold" -%} - {%- assign maybe_rotate="" -%} - {%- assign maybe_on="on" -%} - {%- else -%} - {%- assign active_title="" -%} - {%- assign maybe_rotate="rotate-270" -%} - {%- assign maybe_on="" -%} - {%- endif %} -
    • -
      - {% svg _icons/chevron-down-mini.svg class="menu-chevron h-4 w-4 mb-0.5 -ml-2 -mr-0.5 inline cursor-pointer {{maybe_rotate}}" %} - {{ entry.title }} -
      -
        - {%- for subentry in entry.subfolderitems -%} - {%- if page.url == subentry.url or page.parent == subentry.url-%} - {%- assign active_item="text-hi border-f_green-500" -%} - {%- else -%} - {%- assign active_item="text-light bordercol" -%} - {%- endif %} -
      • - {{ subentry.page }} -
        • - {%- endfor %} -
      -
      • - {%- else %} - {%- if page.url == entry.url or page.parent == entry.url -%} - {%- assign active_item="text-hi border-f_green-500" -%} - {%- else -%} - {%- assign active_item="text-light bordercol" -%} - {%- endif %} -
    • - {{ entry.page }} -
      • - {%- endif -%} - {%- endfor %} -
    -
    • -{%- endif -%} -{%- endfor %} -
diff --git a/_includes/tab.html b/_includes/tab.html deleted file mode 100644 index 33f3697f9a7..00000000000 --- a/_includes/tab.html +++ /dev/null @@ -1,11 +0,0 @@ -{%- comment %} -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd -{% endcomment -%} - - - +
+
+ + diff --git a/package-lock.json b/package-lock.json deleted file mode 100644 index 2ac28b30e87..00000000000 --- a/package-lock.json +++ /dev/null @@ -1,1367 +0,0 @@ -{ - "name": "@sel4/docs", - "version": "2.0.0", - "lockfileVersion": 3, - "requires": true, - "packages": { - "": { - "name": "@sel4/docs", - "version": "2.0.0", - "dependencies": { - "@tailwindcss/postcss": "^4.1", - "@tailwindcss/typography": "^0.5.16", - "postcss": "^8.4.49", - "postcss-cli": "^11.0.0", - "tailwindcss": "^4.1" - } - }, - "node_modules/@alloc/quick-lru": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@alloc/quick-lru/-/quick-lru-5.2.0.tgz", - "integrity": "sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==", - "license": "MIT", - "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/@jridgewell/gen-mapping": { - "version": "0.3.13", - "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz", - "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==", - "license": "MIT", - "dependencies": { - "@jridgewell/sourcemap-codec": "^1.5.0", - "@jridgewell/trace-mapping": "^0.3.24" - } - }, - "node_modules/@jridgewell/remapping": { - "version": "2.3.5", - "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz", - "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==", - "license": "MIT", - "dependencies": { - "@jridgewell/gen-mapping": "^0.3.5", - "@jridgewell/trace-mapping": "^0.3.24" - } - }, - "node_modules/@jridgewell/resolve-uri": { - "version": "3.1.2", - "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", - "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", - "license": "MIT", - "engines": { - "node": ">=6.0.0" - } - }, - "node_modules/@jridgewell/sourcemap-codec": { - "version": "1.5.5", - "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz", - "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==", - "license": "MIT" - }, - "node_modules/@jridgewell/trace-mapping": { - "version": "0.3.31", - "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz", - "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==", - "license": "MIT", - "dependencies": { - "@jridgewell/resolve-uri": "^3.1.0", - "@jridgewell/sourcemap-codec": "^1.4.14" - } - }, - "node_modules/@tailwindcss/node": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/node/-/node-4.1.18.tgz", - "integrity": "sha512-DoR7U1P7iYhw16qJ49fgXUlry1t4CpXeErJHnQ44JgTSKMaZUdf17cfn5mHchfJ4KRBZRFA/Coo+MUF5+gOaCQ==", - "license": "MIT", - "dependencies": { - "@jridgewell/remapping": "^2.3.4", - "enhanced-resolve": "^5.18.3", - "jiti": "^2.6.1", - "lightningcss": "1.30.2", - "magic-string": "^0.30.21", - "source-map-js": "^1.2.1", - "tailwindcss": "4.1.18" - } - }, - "node_modules/@tailwindcss/oxide": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.1.18.tgz", - "integrity": "sha512-EgCR5tTS5bUSKQgzeMClT6iCY3ToqE1y+ZB0AKldj809QXk1Y+3jB0upOYZrn9aGIzPtUsP7sX4QQ4XtjBB95A==", - "license": "MIT", - "engines": { - "node": ">= 10" - }, - "optionalDependencies": { - "@tailwindcss/oxide-android-arm64": "4.1.18", - "@tailwindcss/oxide-darwin-arm64": "4.1.18", - "@tailwindcss/oxide-darwin-x64": "4.1.18", - "@tailwindcss/oxide-freebsd-x64": "4.1.18", - "@tailwindcss/oxide-linux-arm-gnueabihf": "4.1.18", - "@tailwindcss/oxide-linux-arm64-gnu": "4.1.18", - "@tailwindcss/oxide-linux-arm64-musl": "4.1.18", - "@tailwindcss/oxide-linux-x64-gnu": "4.1.18", - "@tailwindcss/oxide-linux-x64-musl": "4.1.18", - "@tailwindcss/oxide-wasm32-wasi": "4.1.18", - "@tailwindcss/oxide-win32-arm64-msvc": "4.1.18", - "@tailwindcss/oxide-win32-x64-msvc": "4.1.18" - } - }, - "node_modules/@tailwindcss/oxide-android-arm64": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.1.18.tgz", - "integrity": "sha512-dJHz7+Ugr9U/diKJA0W6N/6/cjI+ZTAoxPf9Iz9BFRF2GzEX8IvXxFIi/dZBloVJX/MZGvRuFA9rqwdiIEZQ0Q==", - "cpu": [ - "arm64" - ], - "license": "MIT", - "optional": true, - "os": [ - "android" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-darwin-arm64": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-arm64/-/oxide-darwin-arm64-4.1.18.tgz", - "integrity": "sha512-Gc2q4Qhs660bhjyBSKgq6BYvwDz4G+BuyJ5H1xfhmDR3D8HnHCmT/BSkvSL0vQLy/nkMLY20PQ2OoYMO15Jd0A==", - "cpu": [ - "arm64" - ], - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-darwin-x64": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.1.18.tgz", - "integrity": "sha512-FL5oxr2xQsFrc3X9o1fjHKBYBMD1QZNyc1Xzw/h5Qu4XnEBi3dZn96HcHm41c/euGV+GRiXFfh2hUCyKi/e+yw==", - "cpu": [ - "x64" - ], - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-freebsd-x64": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.1.18.tgz", - "integrity": "sha512-Fj+RHgu5bDodmV1dM9yAxlfJwkkWvLiRjbhuO2LEtwtlYlBgiAT4x/j5wQr1tC3SANAgD+0YcmWVrj8R9trVMA==", - "cpu": [ - "x64" - ], - "license": "MIT", - "optional": true, - "os": [ - "freebsd" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-linux-arm-gnueabihf": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.1.18.tgz", - "integrity": "sha512-Fp+Wzk/Ws4dZn+LV2Nqx3IilnhH51YZoRaYHQsVq3RQvEl+71VGKFpkfHrLM/Li+kt5c0DJe/bHXK1eHgDmdiA==", - "cpu": [ - "arm" - ], - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-linux-arm64-gnu": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.1.18.tgz", - "integrity": "sha512-S0n3jboLysNbh55Vrt7pk9wgpyTTPD0fdQeh7wQfMqLPM/Hrxi+dVsLsPrycQjGKEQk85Kgbx+6+QnYNiHalnw==", - "cpu": [ - "arm64" - ], - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-linux-arm64-musl": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.1.18.tgz", - "integrity": "sha512-1px92582HkPQlaaCkdRcio71p8bc8i/ap5807tPRDK/uw953cauQBT8c5tVGkOwrHMfc2Yh6UuxaH4vtTjGvHg==", - "cpu": [ - "arm64" - ], - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-linux-x64-gnu": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.1.18.tgz", - "integrity": "sha512-v3gyT0ivkfBLoZGF9LyHmts0Isc8jHZyVcbzio6Wpzifg/+5ZJpDiRiUhDLkcr7f/r38SWNe7ucxmGW3j3Kb/g==", - "cpu": [ - "x64" - ], - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-linux-x64-musl": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.1.18.tgz", - "integrity": "sha512-bhJ2y2OQNlcRwwgOAGMY0xTFStt4/wyU6pvI6LSuZpRgKQwxTec0/3Scu91O8ir7qCR3AuepQKLU/kX99FouqQ==", - "cpu": [ - "x64" - ], - "license": "MIT", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-wasm32-wasi": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.1.18.tgz", - "integrity": "sha512-LffYTvPjODiP6PT16oNeUQJzNVyJl1cjIebq/rWWBF+3eDst5JGEFSc5cWxyRCJ0Mxl+KyIkqRxk1XPEs9x8TA==", - "bundleDependencies": [ - "@napi-rs/wasm-runtime", - "@emnapi/core", - "@emnapi/runtime", - "@tybys/wasm-util", - "@emnapi/wasi-threads", - "tslib" - ], - "cpu": [ - "wasm32" - ], - "license": "MIT", - "optional": true, - "dependencies": { - "@emnapi/core": "^1.7.1", - "@emnapi/runtime": "^1.7.1", - "@emnapi/wasi-threads": "^1.1.0", - "@napi-rs/wasm-runtime": "^1.1.0", - "@tybys/wasm-util": "^0.10.1", - "tslib": "^2.4.0" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@tailwindcss/oxide-win32-arm64-msvc": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.18.tgz", - "integrity": "sha512-HjSA7mr9HmC8fu6bdsZvZ+dhjyGCLdotjVOgLA2vEqxEBZaQo9YTX4kwgEvPCpRh8o4uWc4J/wEoFzhEmjvPbA==", - "cpu": [ - "arm64" - ], - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/oxide-win32-x64-msvc": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.1.18.tgz", - "integrity": "sha512-bJWbyYpUlqamC8dpR7pfjA0I7vdF6t5VpUGMWRkXVE3AXgIZjYUYAK7II1GNaxR8J1SSrSrppRar8G++JekE3Q==", - "cpu": [ - "x64" - ], - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">= 10" - } - }, - "node_modules/@tailwindcss/postcss": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/@tailwindcss/postcss/-/postcss-4.1.18.tgz", - "integrity": "sha512-Ce0GFnzAOuPyfV5SxjXGn0CubwGcuDB0zcdaPuCSzAa/2vII24JTkH+I6jcbXLb1ctjZMZZI6OjDaLPJQL1S0g==", - "license": "MIT", - "dependencies": { - "@alloc/quick-lru": "^5.2.0", - "@tailwindcss/node": "4.1.18", - "@tailwindcss/oxide": "4.1.18", - "postcss": "^8.4.41", - "tailwindcss": "4.1.18" - } - }, - "node_modules/@tailwindcss/typography": { - "version": "0.5.19", - "resolved": "https://registry.npmjs.org/@tailwindcss/typography/-/typography-0.5.19.tgz", - "integrity": "sha512-w31dd8HOx3k9vPtcQh5QHP9GwKcgbMp87j58qi6xgiBnFFtKEAgCWnDw4qUT8aHwkCp8bKvb/KGKWWHedP0AAg==", - "license": "MIT", - "dependencies": { - "postcss-selector-parser": "6.0.10" - }, - "peerDependencies": { - "tailwindcss": ">=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1" - } - }, - "node_modules/ansi-regex": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", - "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/ansi-styles": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", - "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", - "license": "MIT", - "dependencies": { - "color-convert": "^2.0.1" - }, - "engines": { - "node": ">=8" - }, - "funding": { - "url": "https://github.com/chalk/ansi-styles?sponsor=1" - } - }, - "node_modules/anymatch": { - "version": "3.1.3", - "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", - "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", - "license": "ISC", - "dependencies": { - "normalize-path": "^3.0.0", - "picomatch": "^2.0.4" - }, - "engines": { - "node": ">= 8" - } - }, - "node_modules/binary-extensions": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz", - "integrity": "sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==", - "license": "MIT", - "engines": { - "node": ">=8" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/braces": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz", - "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==", - "license": "MIT", - "dependencies": { - "fill-range": "^7.1.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/chokidar": { - "version": "3.6.0", - "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz", - "integrity": "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==", - "license": "MIT", - "dependencies": { - "anymatch": "~3.1.2", - "braces": "~3.0.2", - "glob-parent": "~5.1.2", - "is-binary-path": "~2.1.0", - "is-glob": "~4.0.1", - "normalize-path": "~3.0.0", - "readdirp": "~3.6.0" - }, - "engines": { - "node": ">= 8.10.0" - }, - "funding": { - "url": "https://paulmillr.com/funding/" - }, - "optionalDependencies": { - "fsevents": "~2.3.2" - } - }, - "node_modules/cliui": { - "version": "8.0.1", - "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", - "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", - "license": "ISC", - "dependencies": { - "string-width": "^4.2.0", - "strip-ansi": "^6.0.1", - "wrap-ansi": "^7.0.0" - }, - "engines": { - "node": ">=12" - } - }, - "node_modules/color-convert": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", - "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", - "license": "MIT", - "dependencies": { - "color-name": "~1.1.4" - }, - "engines": { - "node": ">=7.0.0" - } - }, - "node_modules/color-name": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", - "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", - "license": "MIT" - }, - "node_modules/cssesc": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz", - "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==", - "license": "MIT", - "bin": { - "cssesc": "bin/cssesc" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/dependency-graph": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/dependency-graph/-/dependency-graph-1.0.0.tgz", - "integrity": "sha512-cW3gggJ28HZ/LExwxP2B++aiKxhJXMSIt9K48FOXQkm+vuG5gyatXnLsONRJdzO/7VfjDIiaOOa/bs4l464Lwg==", - "license": "MIT", - "engines": { - "node": ">=4" - } - }, - "node_modules/detect-libc": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", - "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", - "license": "Apache-2.0", - "engines": { - "node": ">=8" - } - }, - "node_modules/emoji-regex": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", - "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", - "license": "MIT" - }, - "node_modules/enhanced-resolve": { - "version": "5.18.4", - "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.18.4.tgz", - "integrity": "sha512-LgQMM4WXU3QI+SYgEc2liRgznaD5ojbmY3sb8LxyguVkIg5FxdpTkvk72te2R38/TGKxH634oLxXRGY6d7AP+Q==", - "license": "MIT", - "dependencies": { - "graceful-fs": "^4.2.4", - "tapable": "^2.2.0" - }, - "engines": { - "node": ">=10.13.0" - } - }, - "node_modules/escalade": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", - "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", - "license": "MIT", - "engines": { - "node": ">=6" - } - }, - "node_modules/fill-range": { - "version": "7.1.1", - "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz", - "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==", - "license": "MIT", - "dependencies": { - "to-regex-range": "^5.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/fs-extra": { - "version": "11.3.3", - "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.3.tgz", - "integrity": "sha512-VWSRii4t0AFm6ixFFmLLx1t7wS1gh+ckoa84aOeapGum0h+EZd1EhEumSB+ZdDLnEPuucsVB9oB7cxJHap6Afg==", - "license": "MIT", - "dependencies": { - "graceful-fs": "^4.2.0", - "jsonfile": "^6.0.1", - "universalify": "^2.0.0" - }, - "engines": { - "node": ">=14.14" - } - }, - "node_modules/fsevents": { - "version": "2.3.3", - "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", - "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", - "hasInstallScript": true, - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": "^8.16.0 || ^10.6.0 || >=11.0.0" - } - }, - "node_modules/get-caller-file": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", - "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", - "license": "ISC", - "engines": { - "node": "6.* || 8.* || >= 10.*" - } - }, - "node_modules/glob-parent": { - "version": "5.1.2", - "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", - "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", - "license": "ISC", - "dependencies": { - "is-glob": "^4.0.1" - }, - "engines": { - "node": ">= 6" - } - }, - "node_modules/graceful-fs": { - "version": "4.2.11", - "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", - "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", - "license": "ISC" - }, - "node_modules/is-binary-path": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", - "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", - "license": "MIT", - "dependencies": { - "binary-extensions": "^2.0.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/is-extglob": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", - "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/is-fullwidth-code-point": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", - "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/is-glob": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", - "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", - "license": "MIT", - "dependencies": { - "is-extglob": "^2.1.1" - }, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/is-number": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", - "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", - "license": "MIT", - "engines": { - "node": ">=0.12.0" - } - }, - "node_modules/jiti": { - "version": "2.6.1", - "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.6.1.tgz", - "integrity": "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==", - "license": "MIT", - "bin": { - "jiti": "lib/jiti-cli.mjs" - } - }, - "node_modules/jsonfile": { - "version": "6.2.0", - "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.0.tgz", - "integrity": "sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg==", - "license": "MIT", - "dependencies": { - "universalify": "^2.0.0" - }, - "optionalDependencies": { - "graceful-fs": "^4.1.6" - } - }, - "node_modules/lightningcss": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.30.2.tgz", - "integrity": "sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==", - "license": "MPL-2.0", - "dependencies": { - "detect-libc": "^2.0.3" - }, - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - }, - "optionalDependencies": { - "lightningcss-android-arm64": "1.30.2", - "lightningcss-darwin-arm64": "1.30.2", - "lightningcss-darwin-x64": "1.30.2", - "lightningcss-freebsd-x64": "1.30.2", - "lightningcss-linux-arm-gnueabihf": "1.30.2", - "lightningcss-linux-arm64-gnu": "1.30.2", - "lightningcss-linux-arm64-musl": "1.30.2", - "lightningcss-linux-x64-gnu": "1.30.2", - "lightningcss-linux-x64-musl": "1.30.2", - "lightningcss-win32-arm64-msvc": "1.30.2", - "lightningcss-win32-x64-msvc": "1.30.2" - } - }, - "node_modules/lightningcss-android-arm64": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.30.2.tgz", - "integrity": "sha512-BH9sEdOCahSgmkVhBLeU7Hc9DWeZ1Eb6wNS6Da8igvUwAe0sqROHddIlvU06q3WyXVEOYDZ6ykBZQnjTbmo4+A==", - "cpu": [ - "arm64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "android" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-darwin-arm64": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.30.2.tgz", - "integrity": "sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==", - "cpu": [ - "arm64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-darwin-x64": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.30.2.tgz", - "integrity": "sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==", - "cpu": [ - "x64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-freebsd-x64": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.30.2.tgz", - "integrity": "sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==", - "cpu": [ - "x64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "freebsd" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-linux-arm-gnueabihf": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.30.2.tgz", - "integrity": "sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==", - "cpu": [ - "arm" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-linux-arm64-gnu": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.30.2.tgz", - "integrity": "sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==", - "cpu": [ - "arm64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-linux-arm64-musl": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.30.2.tgz", - "integrity": "sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==", - "cpu": [ - "arm64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-linux-x64-gnu": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.30.2.tgz", - "integrity": "sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==", - "cpu": [ - "x64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-linux-x64-musl": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.30.2.tgz", - "integrity": "sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==", - "cpu": [ - "x64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "linux" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-win32-arm64-msvc": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.30.2.tgz", - "integrity": "sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==", - "cpu": [ - "arm64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lightningcss-win32-x64-msvc": { - "version": "1.30.2", - "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.30.2.tgz", - "integrity": "sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==", - "cpu": [ - "x64" - ], - "license": "MPL-2.0", - "optional": true, - "os": [ - "win32" - ], - "engines": { - "node": ">= 12.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" - } - }, - "node_modules/lilconfig": { - "version": "3.1.3", - "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz", - "integrity": "sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==", - "license": "MIT", - "engines": { - "node": ">=14" - }, - "funding": { - "url": "https://github.com/sponsors/antonk52" - } - }, - "node_modules/magic-string": { - "version": "0.30.21", - "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz", - "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==", - "license": "MIT", - "dependencies": { - "@jridgewell/sourcemap-codec": "^1.5.5" - } - }, - "node_modules/nanoid": { - "version": "3.3.11", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz", - "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/ai" - } - ], - "license": "MIT", - "bin": { - "nanoid": "bin/nanoid.cjs" - }, - "engines": { - "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" - } - }, - "node_modules/normalize-path": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", - "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/picocolors": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", - "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", - "license": "ISC" - }, - "node_modules/picomatch": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", - "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", - "license": "MIT", - "engines": { - "node": ">=8.6" - }, - "funding": { - "url": "https://github.com/sponsors/jonschlinkert" - } - }, - "node_modules/pify": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", - "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/postcss": { - "version": "8.5.6", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz", - "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==", - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/postcss/" - }, - { - "type": "tidelift", - "url": "https://tidelift.com/funding/github/npm/postcss" - }, - { - "type": "github", - "url": "https://github.com/sponsors/ai" - } - ], - "license": "MIT", - "dependencies": { - "nanoid": "^3.3.11", - "picocolors": "^1.1.1", - "source-map-js": "^1.2.1" - }, - "engines": { - "node": "^10 || ^12 || >=14" - } - }, - "node_modules/postcss-cli": { - "version": "11.0.1", - "resolved": "https://registry.npmjs.org/postcss-cli/-/postcss-cli-11.0.1.tgz", - "integrity": "sha512-0UnkNPSayHKRe/tc2YGW6XnSqqOA9eqpiRMgRlV1S6HdGi16vwJBx7lviARzbV1HpQHqLLRH3o8vTcB0cLc+5g==", - "license": "MIT", - "dependencies": { - "chokidar": "^3.3.0", - "dependency-graph": "^1.0.0", - "fs-extra": "^11.0.0", - "picocolors": "^1.0.0", - "postcss-load-config": "^5.0.0", - "postcss-reporter": "^7.0.0", - "pretty-hrtime": "^1.0.3", - "read-cache": "^1.0.0", - "slash": "^5.0.0", - "tinyglobby": "^0.2.12", - "yargs": "^17.0.0" - }, - "bin": { - "postcss": "index.js" - }, - "engines": { - "node": ">=18" - }, - "peerDependencies": { - "postcss": "^8.0.0" - } - }, - "node_modules/postcss-load-config": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-5.1.0.tgz", - "integrity": "sha512-G5AJ+IX0aD0dygOE0yFZQ/huFFMSNneyfp0e3/bT05a8OfPC5FUoZRPfGijUdGOJNMewJiwzcHJXFafFzeKFVA==", - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/postcss/" - }, - { - "type": "github", - "url": "https://github.com/sponsors/ai" - } - ], - "license": "MIT", - "dependencies": { - "lilconfig": "^3.1.1", - "yaml": "^2.4.2" - }, - "engines": { - "node": ">= 18" - }, - "peerDependencies": { - "jiti": ">=1.21.0", - "postcss": ">=8.0.9", - "tsx": "^4.8.1" - }, - "peerDependenciesMeta": { - "jiti": { - "optional": true - }, - "postcss": { - "optional": true - }, - "tsx": { - "optional": true - } - } - }, - "node_modules/postcss-reporter": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/postcss-reporter/-/postcss-reporter-7.1.0.tgz", - "integrity": "sha512-/eoEylGWyy6/DOiMP5lmFRdmDKThqgn7D6hP2dXKJI/0rJSO1ADFNngZfDzxL0YAxFvws+Rtpuji1YIHj4mySA==", - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/postcss/" - }, - { - "type": "github", - "url": "https://github.com/sponsors/ai" - } - ], - "license": "MIT", - "dependencies": { - "picocolors": "^1.0.0", - "thenby": "^1.3.4" - }, - "engines": { - "node": ">=10" - }, - "peerDependencies": { - "postcss": "^8.1.0" - } - }, - "node_modules/postcss-selector-parser": { - "version": "6.0.10", - "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.0.10.tgz", - "integrity": "sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==", - "license": "MIT", - "dependencies": { - "cssesc": "^3.0.0", - "util-deprecate": "^1.0.2" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/pretty-hrtime": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz", - "integrity": "sha512-66hKPCr+72mlfiSjlEB1+45IjXSqvVAIy6mocupoww4tBFE9R9IhwwUGoI4G++Tc9Aq+2rxOt0RFU6gPcrte0A==", - "license": "MIT", - "engines": { - "node": ">= 0.8" - } - }, - "node_modules/read-cache": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz", - "integrity": "sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==", - "license": "MIT", - "dependencies": { - "pify": "^2.3.0" - } - }, - "node_modules/readdirp": { - "version": "3.6.0", - "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", - "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", - "license": "MIT", - "dependencies": { - "picomatch": "^2.2.1" - }, - "engines": { - "node": ">=8.10.0" - } - }, - "node_modules/require-directory": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", - "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/slash": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz", - "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==", - "license": "MIT", - "engines": { - "node": ">=14.16" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/source-map-js": { - "version": "1.2.1", - "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz", - "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==", - "license": "BSD-3-Clause", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/string-width": { - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", - "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", - "license": "MIT", - "dependencies": { - "emoji-regex": "^8.0.0", - "is-fullwidth-code-point": "^3.0.0", - "strip-ansi": "^6.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/strip-ansi": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", - "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", - "license": "MIT", - "dependencies": { - "ansi-regex": "^5.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/tailwindcss": { - "version": "4.1.18", - "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.18.tgz", - "integrity": "sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==", - "license": "MIT" - }, - "node_modules/tapable": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.3.0.tgz", - "integrity": "sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==", - "license": "MIT", - "engines": { - "node": ">=6" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/webpack" - } - }, - "node_modules/thenby": { - "version": "1.3.4", - "resolved": "https://registry.npmjs.org/thenby/-/thenby-1.3.4.tgz", - "integrity": "sha512-89Gi5raiWA3QZ4b2ePcEwswC3me9JIg+ToSgtE0JWeCynLnLxNr/f9G+xfo9K+Oj4AFdom8YNJjibIARTJmapQ==", - "license": "Apache-2.0" - }, - "node_modules/tinyglobby": { - "version": "0.2.15", - "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz", - "integrity": "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==", - "license": "MIT", - "dependencies": { - "fdir": "^6.5.0", - "picomatch": "^4.0.3" - }, - "engines": { - "node": ">=12.0.0" - }, - "funding": { - "url": "https://github.com/sponsors/SuperchupuDev" - } - }, - "node_modules/tinyglobby/node_modules/fdir": { - "version": "6.5.0", - "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", - "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==", - "license": "MIT", - "engines": { - "node": ">=12.0.0" - }, - "peerDependencies": { - "picomatch": "^3 || ^4" - }, - "peerDependenciesMeta": { - "picomatch": { - "optional": true - } - } - }, - "node_modules/tinyglobby/node_modules/picomatch": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", - "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", - "license": "MIT", - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/sponsors/jonschlinkert" - } - }, - "node_modules/to-regex-range": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", - "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", - "license": "MIT", - "dependencies": { - "is-number": "^7.0.0" - }, - "engines": { - "node": ">=8.0" - } - }, - "node_modules/universalify": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz", - "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==", - "license": "MIT", - "engines": { - "node": ">= 10.0.0" - } - }, - "node_modules/util-deprecate": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", - "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", - "license": "MIT" - }, - "node_modules/wrap-ansi": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", - "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", - "license": "MIT", - "dependencies": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - }, - "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/chalk/wrap-ansi?sponsor=1" - } - }, - "node_modules/y18n": { - "version": "5.0.8", - "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", - "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", - "license": "ISC", - "engines": { - "node": ">=10" - } - }, - "node_modules/yaml": { - "version": "2.8.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz", - "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==", - "license": "ISC", - "bin": { - "yaml": "bin.mjs" - }, - "engines": { - "node": ">= 14.6" - }, - "funding": { - "url": "https://github.com/sponsors/eemeli" - } - }, - "node_modules/yargs": { - "version": "17.7.2", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz", - "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==", - "license": "MIT", - "dependencies": { - "cliui": "^8.0.1", - "escalade": "^3.1.1", - "get-caller-file": "^2.0.5", - "require-directory": "^2.1.1", - "string-width": "^4.2.3", - "y18n": "^5.0.5", - "yargs-parser": "^21.1.1" - }, - "engines": { - "node": ">=12" - } - }, - "node_modules/yargs-parser": { - "version": "21.1.1", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", - "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", - "license": "ISC", - "engines": { - "node": ">=12" - } - } - } -} diff --git a/package.json b/package.json deleted file mode 100644 index 698b729b583..00000000000 --- a/package.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "name": "@sel4/docs", - "version": "2.0.0", - "dependencies": { - "@tailwindcss/typography": "^0.5.16", - "@tailwindcss/postcss": "^4.1", - "postcss": "^8.4.49", - "postcss-cli": "^11.0.0", - "tailwindcss": "^4.1" - } -} diff --git a/postcss.config.js b/postcss.config.js deleted file mode 100644 index 75de99e1d4e..00000000000 --- a/postcss.config.js +++ /dev/null @@ -1,8 +0,0 @@ -// Copyright 2025 Proofcraft Pty Ltd -// SPDX-License-Identifier: BSD-2-Clause - -module.exports = { - plugins: [ - require('@tailwindcss/postcss'), - ] -} diff --git a/processes/code-review.html b/processes/code-review.html new file mode 100644 index 00000000000..9d87ded1640 --- /dev/null +++ b/processes/code-review.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/code-review.md b/processes/code-review.md deleted file mode 100644 index ee0651bab96..00000000000 --- a/processes/code-review.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Contribute/pull-requests.html ---- diff --git a/processes/conduct.html b/processes/conduct.html new file mode 100644 index 00000000000..45bb1da43af --- /dev/null +++ b/processes/conduct.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/conduct.md b/processes/conduct.md deleted file mode 100644 index cd39d1c2c83..00000000000 --- a/processes/conduct.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Contribute/conduct.html ---- diff --git a/processes/contributing.html b/processes/contributing.html new file mode 100644 index 00000000000..e16fb5e8192 --- /dev/null +++ b/processes/contributing.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/contributing.md b/processes/contributing.md deleted file mode 100644 index c1c965a36a2..00000000000 --- a/processes/contributing.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Contribute/ ---- diff --git a/processes/docs-contributing.html b/processes/docs-contributing.html new file mode 100644 index 00000000000..407d70d2372 --- /dev/null +++ b/processes/docs-contributing.html @@ -0,0 +1,650 @@ + + + + + + + Contributing to the seL4 documentation | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Contributing to the seL4 documentation

+ +

Thank you for considering helping improve the seL4 documentation.

+ +

This page is about contributing to the documentation site. For +contributing to other parts of the seL4 ecosystem, visit our main contributing +page.

+ +

We believe that documentation is important for any project and appreciate any +contributions that improves it. The sort of contributions that we are looking +for are:

+ +
    +
  • Bug reporting +
      +
    • Stale or incorrect sections
      • +
    • Missing documentation
      • +
    • Ideas of how our documentation could be structured better
      • +
    +
    • +
  • Improvements +
      +
    • Grammar, consistency, and spelling fixes
      • +
    • Missing documentation
      • +
    • Usage examples
      • +
    • Tutorials
      • +
    • Links to related external documentation
      • +
    +
    • +
+ +

For reporting issues about a particular project, please use the relevant +repository’s issue tracker or if that doesn’t work post on any of the community +channels.

+ +

Your first contribution

+ +

You have noticed something that is wrong with some documentation on the site. +GitHub makes it pretty easy to edit Markdown files without having to leave the +browser. By clicking “Edit” on the relevant file, making your change and then +submitting a pull request, someone can then review you change and merge it which +will result in the update appearing on the website.

+ +

More detailed changes can be achieved by checking out the repository and editing +locally, followed by committing and making a pull request manually. The +README.md files describes how to host the site locally so that you can see how +your changes are presented.

+ +

Contributions that are most helpful to us at the moment are:

+ +
    +
  • Identifying which pages contain stale documentation. Filing an issue in the +issue tracker will let us know that something is broken or old.
    • +
  • Identifying areas where there is missing documentation or it is confusing.
    • +
+ +

Submitting a contribution

+ +

Contributions can be submitted by pull requests at https://www.github.com/seL4/docs.

+ +

Please follow the git commit style guide.

+ +

Style

+ +

This repository contains sources in various formats. The general principle is to +follow the same style used in the rest of the file or similar files.

+ +

Languages and style guides that the docsite uses:

+ +
    +
  • Markdown: GitHub flavoured markdown, rendered by kramdown. +Styleguide. Please wrap +lines at 80 characters.
    • +
  • HTML: Should be only used for presentation related content. +Use markdown when possible. Styleguide.
    • +
  • Liquid templating language: We use +liquid-linter to check for +liquid errors.
    • +
+ +

Code review process

+ +

Someone who is familiar with the source will review your changes. They may +request changes or have questions, or merge the pull request if everything looks +good.

+ +

Reporting an issue or feature enhancement

+ +

To report an issue, open an issue in the repository issue tracker. +Issues can be reporting problems, or ideas for improvement.

+ +
    +
  • What is the issue?
    • +
  • Why is it a issue?
    • +
+ +

And if relevant

+ +
    +
  • What do you think a good fix or change may be?
    • +
  • How the fix or change removes the issue?
    • +
+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/processes/docs-contributing.md b/processes/docs-contributing.md deleted file mode 100644 index b7c6e778722..00000000000 --- a/processes/docs-contributing.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -redirect_from: - - /DocsContributing -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Contributing to the seL4 documentation - -Thank you for considering helping improve the seL4 documentation. - -This page is about contributing to the [documentation site][docsite]. For -contributing to other parts of the seL4 ecosystem, visit our main [contributing -page][contribute]. - -We believe that documentation is important for any project and appreciate any -contributions that improves it. The sort of contributions that we are looking -for are: - -- Bug reporting - - Stale or incorrect sections - - Missing documentation - - Ideas of how our documentation could be structured better -- Improvements - - Grammar, consistency, and spelling fixes - - Missing documentation - - Usage examples - - Tutorials - - Links to related external documentation - -For reporting issues about a particular project, please use the relevant -repository's issue tracker or if that doesn't work post on any of the [community -channels][support]. - -## Your first contribution - -You have noticed something that is wrong with some documentation on the site. -GitHub makes it pretty easy to edit Markdown files without having to leave the -browser. By clicking "Edit" on the relevant file, making your change and then -submitting a pull request, someone can then review you change and merge it which -will result in the update appearing on the website. - -More detailed changes can be achieved by checking out the repository and editing -locally, followed by committing and making a pull request manually. The -`README.md` files describes how to host the site locally so that you can see how -your changes are presented. - -Contributions that are most helpful to us at the moment are: - -- Identifying which pages contain stale documentation. Filing an issue in the - issue tracker will let us know that something is broken or old. -- Identifying areas where there is missing documentation or it is confusing. - -## Submitting a contribution - -Contributions can be submitted by pull requests at . - -Please follow the [git commit style guide](https://sel4.systems/Contribute/git-conventions.html). - -### Style - -This repository contains sources in various formats. The general principle is to -follow the same style used in the rest of the file or similar files. - -Languages and style guides that the docsite uses: - -- Markdown: GitHub flavoured markdown, rendered by kramdown. - [Styleguide](https://github.com/slang800/markdown-styleguide). Please wrap - lines at 80 characters. -- HTML: Should be only used for presentation related content. - Use markdown when possible. [Styleguide](https://google.github.io/styleguide/htmlcssguide.html). -- Liquid templating language: We use - [liquid-linter](https://www.npmjs.com/package/liquid-linter-cli) to check for - liquid errors. - -### Code review process - -Someone who is familiar with the source will review your changes. They may -request changes or have questions, or merge the pull request if everything looks -good. - -## Reporting an issue or feature enhancement - -To report an issue, open an issue in the [repository issue tracker][issues]. -Issues can be reporting problems, or ideas for improvement. - -- What is the issue? -- Why is it a issue? - -And if relevant - -- What do you think a good fix or change may be? -- How the fix or change removes the issue? - -[support]: https://sel4.systems/support.html -[contribute]: https://sel4.systems/Contribute/ -[docsite]: ../ -[issues]: https://github.com/seL4/docs/issues diff --git a/processes/git-conventions.html b/processes/git-conventions.html new file mode 100644 index 00000000000..20ced3da938 --- /dev/null +++ b/processes/git-conventions.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/git-conventions.md b/processes/git-conventions.md deleted file mode 100644 index adf39abe544..00000000000 --- a/processes/git-conventions.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Contribute/git-conventions.html ---- diff --git a/processes/index.html b/processes/index.html new file mode 100644 index 00000000000..bee2c51ba95 --- /dev/null +++ b/processes/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/index.md b/processes/index.md deleted file mode 100644 index 9627c6c3c84..00000000000 --- a/processes/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/support.html ---- \ No newline at end of file diff --git a/processes/licenses.html b/processes/licenses.html new file mode 100644 index 00000000000..84ec808cb20 --- /dev/null +++ b/processes/licenses.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/licenses.md b/processes/licenses.md deleted file mode 100644 index 66baf603666..00000000000 --- a/processes/licenses.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Legal/license.html ---- diff --git a/processes/release-process.html b/processes/release-process.html new file mode 100644 index 00000000000..800f56803e9 --- /dev/null +++ b/processes/release-process.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/rfc-process.html b/processes/rfc-process.html new file mode 100644 index 00000000000..8bef45fb59c --- /dev/null +++ b/processes/rfc-process.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/rfc-process.md b/processes/rfc-process.md deleted file mode 100644 index 03ea98c25b9..00000000000 --- a/processes/rfc-process.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Contribute/rfc-process.html ---- diff --git a/processes/roles.html b/processes/roles.html new file mode 100644 index 00000000000..51a3c7eb741 --- /dev/null +++ b/processes/roles.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/roles.md b/processes/roles.md deleted file mode 100644 index 0b77482f892..00000000000 --- a/processes/roles.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Contribute/roles.html ---- diff --git a/processes/style-guide.html b/processes/style-guide.html new file mode 100644 index 00000000000..bc117af1e9c --- /dev/null +++ b/processes/style-guide.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/processes/style-guide.md b/processes/style-guide.md deleted file mode 100644 index 89cf8d6abc0..00000000000 --- a/processes/style-guide.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Contribute/style.html ---- diff --git a/processes/test-status.html b/processes/test-status.html new file mode 100644 index 00000000000..1edc6131a23 --- /dev/null +++ b/processes/test-status.html @@ -0,0 +1,864 @@ + + + + + + + | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + +

seL4 Test Status

+ +

The following list shows the current status of all seL4 GitHub test workflows +on the main branch.

+ +

Main Tests

+ +

seL4Test +Proofs +Proof Sync +seL4Bench +CAmkES +CAmkES VM

+ +
+ +

Main repositories

+ +

seL4

+ +

Compile +C Parser +RefMan +Proof Sync +CI +seL4Test +Trigger +XML

+ +

l4v

+ +

CI +Trigger +External +Weekly Clean +Proofs

+ +

sel4bench

+ +

CI +seL4Bench

+ +

camkes-tool

+ +

CAmkES +CI +Trigger +Unit

+ +

camkes-vm-examples

+ +

Deploy +CI

+ +

capdl

+ +

Build +CI +Trigger

+ +

sel4-tutorials

+ +

CI +Test

+ +

microkit

+ +

CI +SDK

+ +

rust-sel4

+ +

CI

+ +
+ +

All repositories

+ +

cakeml_libs

+ +

CI +Trigger

+ +

camkes

+ +

CI +Trigger

+ +

camkes-manifest

+ +

CI

+ +

camkes-tool

+ +

CAmkES +CI +Trigger +Unit

+ +

camkes-vm

+ +

CI +Trigger

+ +

camkes-vm-examples

+ +

Deploy +CI

+ +

camkes-vm-examples-manifest

+ +

CI

+ +

camkes-vm-images

+ +

CI +Trigger

+ +

camkes-vm-linux

+ +

CI +Trigger

+ +

capdl

+ +

Build +CI +Trigger

+ +

ci-actions

+ +

Deploy CAmkES Test +Deploy CAmkES Unit +Deploy CAmkES VM +Deploy CParser Builder +Deploy CParser Run +Deploy Link Check +Deploy Preprocess Test +Deploy RumpRun +Deploy Proof Run +Deploy seL4 Bench +Deploy seL4 HW +Deploy seL4 Sim +Deploy Tutorial Test +Deploy webserver image +Isabelle Mirror +CI

+ +

docs

+ +

Build +CI

+ +

global-components

+ +

CI +Trigger

+ +

graph-refine

+ +

Binary decompilation +Build +Build +CI +Trigger

+ +

l4v

+ +

CI +Trigger +External +Weekly Clean +Proofs

+ +

mcs-examples

+ +

CI

+ +

microkit

+ +

CI +SDK

+ +

projects_libs

+ +

CI +Trigger

+ +

pruner

+ +

CI +Trigger

+ +

refos

+ +

CI

+ +

rumprun-sel4-demoapps

+ +

CI +Hello World

+ +

rust-microkit-demo

+ +

CI

+ +

rust-microkit-http-server-demo

+ +

CI

+ +

rust-root-task-demo

+ +

CI

+ +

rust-sel4

+ +

CI

+ +

seL4

+ +

Compile +C Parser +RefMan +Proof Sync +CI +seL4Test +Trigger +XML

+ +

seL4-CAmkES-L4v-dockerfiles

+ +

Deploy +CI

+ +

seL4_libs

+ +

CI +seL4Test +Trigger

+ +

seL4_projects_libs

+ +

CI +seL4Test +Trigger

+ +

seL4_tools

+ +

CI +seL4Test +Trigger

+ +

sel4-tutorials

+ +

CI +Test

+ +

sel4-tutorials-manifest

+ +

CI

+ +

sel4bench

+ +

CI +seL4Bench

+ +

sel4bench-manifest

+ +

CI

+ +

sel4runtime

+ +

CI +seL4Test +Trigger

+ +

sel4test

+ +

CI +seL4Test +Trigger

+ +

sel4test-manifest

+ +

CI +seL4Test

+ +

sel4webserver

+ +

CI +Web Server Demo

+ +

sel4webserver-manifest

+ +

CI

+ +

util_libs

+ +

CI +seL4Test Sim +Trigger

+ +

verification-manifest

+ +

CI +Trigger

+ +

website

+ +

CI

+ +

whitepaper

+ +

build PDF +License

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/processes/test-status.md b/processes/test-status.md deleted file mode 100644 index b614e3d0b6c..00000000000 --- a/processes/test-status.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2022 seL4 Project a Series of LF Projects, LLC. -layout: test ---- - - - -# seL4 Test Status - -The following list shows the current status of all seL4 GitHub test workflows -on the main branch. - -## Main Tests - -[![seL4Test](https://github.com/seL4/seL4/actions/workflows/sel4test-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/sel4test-deploy.yml?query=branch%3Amaster) -[![Proofs](https://github.com/seL4/l4v/actions/workflows/proof-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/proof-deploy.yml?query=branch%3Amaster) -[![Proof Sync](https://github.com/seL4/seL4/actions/workflows/preprocess-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/preprocess-deploy.yml?query=branch%3Amaster) -[![seL4Bench](https://github.com/seL4/sel4bench/actions/workflows/sel4bench.yml/badge.svg?branch=master)](https://github.com/seL4/sel4bench/actions/workflows/sel4bench.yml?query=branch%3Amaster) -[![CAmkES](https://github.com/seL4/camkes-tool/actions/workflows/camkes-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/camkes-deploy.yml?query=branch%3Amaster) -[![CAmkES VM](https://github.com/seL4/camkes-vm-examples/actions/workflows/camkes-vm-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-examples/actions/workflows/camkes-vm-deploy.yml?query=branch%3Amaster) - ------ - - -## Main repositories - - -### [seL4](https://github.com/seL4/seL4/) - -[![Compile](https://github.com/seL4/seL4/actions/workflows/compilation-checks.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/compilation-checks.yml?query=branch%3Amaster) -[![C Parser](https://github.com/seL4/seL4/actions/workflows/cparser.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/cparser.yml?query=branch%3Amaster) -[![RefMan](https://github.com/seL4/seL4/actions/workflows/manual.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/manual.yml?query=branch%3Amaster) -[![Proof Sync](https://github.com/seL4/seL4/actions/workflows/preprocess-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/preprocess-deploy.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/seL4/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test](https://github.com/seL4/seL4/actions/workflows/sel4test-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/sel4test-deploy.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/seL4/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/trigger.yml?query=branch%3Amaster) -[![XML](https://github.com/seL4/seL4/actions/workflows/xml_lint.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/xml_lint.yml?query=branch%3Amaster) - -### [l4v](https://github.com/seL4/l4v/) - -[![CI](https://github.com/seL4/l4v/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/l4v/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/trigger.yml?query=branch%3Amaster) -[![External](https://github.com/seL4/l4v/actions/workflows/external.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/external.yml?query=branch%3Amaster) -[![Weekly Clean](https://github.com/seL4/l4v/actions/workflows/weekly-clean.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/weekly-clean.yml?query=branch%3Amaster) -[![Proofs](https://github.com/seL4/l4v/actions/workflows/proof-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/proof-deploy.yml?query=branch%3Amaster) - -### [sel4bench](https://github.com/seL4/sel4bench/) - -[![CI](https://github.com/seL4/sel4bench/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4bench/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Bench](https://github.com/seL4/sel4bench/actions/workflows/sel4bench.yml/badge.svg?branch=master)](https://github.com/seL4/sel4bench/actions/workflows/sel4bench.yml?query=branch%3Amaster) - -### [camkes-tool](https://github.com/seL4/camkes-tool/) - -[![CAmkES](https://github.com/seL4/camkes-tool/actions/workflows/camkes-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/camkes-deploy.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/camkes-tool/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/camkes-tool/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/trigger.yml?query=branch%3Amaster) -[![Unit](https://github.com/seL4/camkes-tool/actions/workflows/unit.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/unit.yml?query=branch%3Amaster) - -### [camkes-vm-examples](https://github.com/seL4/camkes-vm-examples/) - -[![Deploy](https://github.com/seL4/camkes-vm-examples/actions/workflows/camkes-vm-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-examples/actions/workflows/camkes-vm-deploy.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/camkes-vm-examples/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-examples/actions/workflows/push.yml?query=branch%3Amaster) - -### [capdl](https://github.com/seL4/capdl/) - -[![Build](https://github.com/seL4/capdl/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/seL4/capdl/actions/workflows/build.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/capdl/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/capdl/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/capdl/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/capdl/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [sel4-tutorials](https://github.com/seL4/sel4-tutorials/) - -[![CI](https://github.com/seL4/sel4-tutorials/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4-tutorials/actions/workflows/push.yml?query=branch%3Amaster) -[![Test](https://github.com/seL4/sel4-tutorials/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/seL4/sel4-tutorials/actions/workflows/test.yml?query=branch%3Amaster) - -### [microkit](https://github.com/seL4/microkit/) - -[![CI](https://github.com/seL4/microkit/actions/workflows/push.yml/badge.svg?branch=main)](https://github.com/seL4/microkit/actions/workflows/push.yml?query=branch%3Amain) -[![SDK](https://github.com/seL4/microkit/actions/workflows/sdk.yaml/badge.svg?branch=main)](https://github.com/seL4/microkit/actions/workflows/sdk.yaml?query=branch%3Amain) - -### [rust-sel4](https://github.com/seL4/rust-sel4/) - -[![CI](https://github.com/seL4/rust-sel4/actions/workflows/push.yaml/badge.svg?branch=main)](https://github.com/seL4/rust-sel4/actions/workflows/push.yaml?query=branch%3Amain) - ------ - -## All repositories - - -### [cakeml_libs](https://github.com/seL4/cakeml_libs/) - -[![CI](https://github.com/seL4/cakeml_libs/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/cakeml_libs/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/cakeml_libs/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/cakeml_libs/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [camkes](https://github.com/seL4/camkes/) - -[![CI](https://github.com/seL4/camkes/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/camkes/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/camkes/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [camkes-manifest](https://github.com/seL4/camkes-manifest/) - -[![CI](https://github.com/seL4/camkes-manifest/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-manifest/actions/workflows/push.yml?query=branch%3Amaster) - -### [camkes-tool](https://github.com/seL4/camkes-tool/) - -[![CAmkES](https://github.com/seL4/camkes-tool/actions/workflows/camkes-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/camkes-deploy.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/camkes-tool/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/camkes-tool/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/trigger.yml?query=branch%3Amaster) -[![Unit](https://github.com/seL4/camkes-tool/actions/workflows/unit.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-tool/actions/workflows/unit.yml?query=branch%3Amaster) - -### [camkes-vm](https://github.com/seL4/camkes-vm/) - -[![CI](https://github.com/seL4/camkes-vm/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/camkes-vm/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [camkes-vm-examples](https://github.com/seL4/camkes-vm-examples/) - -[![Deploy](https://github.com/seL4/camkes-vm-examples/actions/workflows/camkes-vm-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-examples/actions/workflows/camkes-vm-deploy.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/camkes-vm-examples/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-examples/actions/workflows/push.yml?query=branch%3Amaster) - -### [camkes-vm-examples-manifest](https://github.com/seL4/camkes-vm-examples-manifest/) - -[![CI](https://github.com/seL4/camkes-vm-examples-manifest/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-examples-manifest/actions/workflows/push.yml?query=branch%3Amaster) - -### [camkes-vm-images](https://github.com/seL4/camkes-vm-images/) - -[![CI](https://github.com/seL4/camkes-vm-images/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-images/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/camkes-vm-images/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-images/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [camkes-vm-linux](https://github.com/seL4/camkes-vm-linux/) - -[![CI](https://github.com/seL4/camkes-vm-linux/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-linux/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/camkes-vm-linux/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/camkes-vm-linux/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [capdl](https://github.com/seL4/capdl/) - -[![Build](https://github.com/seL4/capdl/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/seL4/capdl/actions/workflows/build.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/capdl/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/capdl/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/capdl/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/capdl/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [ci-actions](https://github.com/seL4/ci-actions/) - -[![Deploy CAmkES Test](https://github.com/seL4/ci-actions/actions/workflows/deploy-camkes-test.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-camkes-test.yml?query=branch%3Amaster) -[![Deploy CAmkES Unit](https://github.com/seL4/ci-actions/actions/workflows/deploy-camkes-unit.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-camkes-unit.yml?query=branch%3Amaster) -[![Deploy CAmkES VM](https://github.com/seL4/ci-actions/actions/workflows/deploy-camkes-vm.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-camkes-vm.yml?query=branch%3Amaster) -[![Deploy CParser Builder](https://github.com/seL4/ci-actions/actions/workflows/deploy-cparser-builder.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-cparser-builder.yml?query=branch%3Amaster) -[![Deploy CParser Run](https://github.com/seL4/ci-actions/actions/workflows/deploy-cparser-run.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-cparser-run.yml?query=branch%3Amaster) -[![Deploy Link Check](https://github.com/seL4/ci-actions/actions/workflows/deploy-link-check.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-link-check.yml?query=branch%3Amaster) -[![Deploy Preprocess Test](https://github.com/seL4/ci-actions/actions/workflows/deploy-preprocess.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-preprocess.yml?query=branch%3Amaster) -[![Deploy RumpRun](https://github.com/seL4/ci-actions/actions/workflows/deploy-rumprun.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-rumprun.yml?query=branch%3Amaster) -[![Deploy Proof Run](https://github.com/seL4/ci-actions/actions/workflows/deploy-run-proofs.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-run-proofs.yml?query=branch%3Amaster) -[![Deploy seL4 Bench](https://github.com/seL4/ci-actions/actions/workflows/deploy-sel4bench.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-sel4bench.yml?query=branch%3Amaster) -[![Deploy seL4 HW](https://github.com/seL4/ci-actions/actions/workflows/deploy-sel4test-hw.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-sel4test-hw.yml?query=branch%3Amaster) -[![Deploy seL4 Sim](https://github.com/seL4/ci-actions/actions/workflows/deploy-sel4test-sim.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-sel4test-sim.yml?query=branch%3Amaster) -[![Deploy Tutorial Test](https://github.com/seL4/ci-actions/actions/workflows/deploy-tutorials.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-tutorials.yml?query=branch%3Amaster) -[![Deploy webserver image](https://github.com/seL4/ci-actions/actions/workflows/deploy-webserver.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/deploy-webserver.yml?query=branch%3Amaster) -[![Isabelle Mirror](https://github.com/seL4/ci-actions/actions/workflows/isabelle-mirror.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/isabelle-mirror.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/ci-actions/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/ci-actions/actions/workflows/push.yml?query=branch%3Amaster) - -### [docs](https://github.com/seL4/docs/) - -[![Build](https://github.com/seL4/docs/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/seL4/docs/actions/workflows/build.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/docs/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/docs/actions/workflows/push.yml?query=branch%3Amaster) - -### [global-components](https://github.com/seL4/global-components/) - -[![CI](https://github.com/seL4/global-components/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/global-components/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/global-components/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/global-components/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [graph-refine](https://github.com/seL4/graph-refine/) - -[![Binary decompilation](https://github.com/seL4/graph-refine/actions/workflows/binary-decompilation.yml/badge.svg?branch=master)](https://github.com/seL4/graph-refine/actions/workflows/binary-decompilation.yml?query=branch%3Amaster) -[![Build](https://github.com/seL4/graph-refine/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/seL4/graph-refine/actions/workflows/build.yml?query=branch%3Amaster) -[![Build](https://github.com/seL4/graph-refine/actions/workflows/docker-build.yml/badge.svg?branch=master)](https://github.com/seL4/graph-refine/actions/workflows/docker-build.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/graph-refine/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/graph-refine/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/graph-refine/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/graph-refine/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [l4v](https://github.com/seL4/l4v/) - -[![CI](https://github.com/seL4/l4v/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/l4v/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/trigger.yml?query=branch%3Amaster) -[![External](https://github.com/seL4/l4v/actions/workflows/external.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/external.yml?query=branch%3Amaster) -[![Weekly Clean](https://github.com/seL4/l4v/actions/workflows/weekly-clean.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/weekly-clean.yml?query=branch%3Amaster) -[![Proofs](https://github.com/seL4/l4v/actions/workflows/proof-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/l4v/actions/workflows/proof-deploy.yml?query=branch%3Amaster) - -### [mcs-examples](https://github.com/seL4/mcs-examples/) - -[![CI](https://github.com/seL4/mcs-examples/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/mcs-examples/actions/workflows/push.yml?query=branch%3Amaster) - -### [microkit](https://github.com/seL4/microkit/) - -[![CI](https://github.com/seL4/microkit/actions/workflows/push.yml/badge.svg?branch=main)](https://github.com/seL4/microkit/actions/workflows/push.yml?query=branch%3Amain) -[![SDK](https://github.com/seL4/microkit/actions/workflows/sdk.yaml/badge.svg?branch=main)](https://github.com/seL4/microkit/actions/workflows/sdk.yaml?query=branch%3Amain) - -### [projects_libs](https://github.com/seL4/projects_libs/) - -[![CI](https://github.com/seL4/projects_libs/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/projects_libs/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/projects_libs/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/projects_libs/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [pruner](https://github.com/seL4/pruner/) - -[![CI](https://github.com/seL4/pruner/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/pruner/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/pruner/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/pruner/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [refos](https://github.com/seL4/refos/) - -[![CI](https://github.com/seL4/refos/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/refos/actions/workflows/push.yml?query=branch%3Amaster) - -### [rumprun-sel4-demoapps](https://github.com/seL4/rumprun-sel4-demoapps/) - -[![CI](https://github.com/seL4/rumprun-sel4-demoapps/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/rumprun-sel4-demoapps/actions/workflows/push.yml?query=branch%3Amaster) -[![Hello World](https://github.com/seL4/rumprun-sel4-demoapps/actions/workflows/rump-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/rumprun-sel4-demoapps/actions/workflows/rump-deploy.yml?query=branch%3Amaster) - -### [rust-microkit-demo](https://github.com/seL4/rust-microkit-demo/) - -[![CI](https://github.com/seL4/rust-microkit-demo/actions/workflows/push.yaml/badge.svg?branch=main)](https://github.com/seL4/rust-microkit-demo/actions/workflows/push.yaml?query=branch%3Amain) - -### [rust-microkit-http-server-demo](https://github.com/seL4/rust-microkit-http-server-demo/) - -[![CI](https://github.com/seL4/rust-microkit-http-server-demo/actions/workflows/push.yaml/badge.svg?branch=main)](https://github.com/seL4/rust-microkit-http-server-demo/actions/workflows/push.yaml?query=branch%3Amain) - -### [rust-root-task-demo](https://github.com/seL4/rust-root-task-demo/) - -[![CI](https://github.com/seL4/rust-root-task-demo/actions/workflows/push.yaml/badge.svg?branch=main)](https://github.com/seL4/rust-root-task-demo/actions/workflows/push.yaml?query=branch%3Amain) - -### [rust-sel4](https://github.com/seL4/rust-sel4/) - -[![CI](https://github.com/seL4/rust-sel4/actions/workflows/push.yaml/badge.svg?branch=main)](https://github.com/seL4/rust-sel4/actions/workflows/push.yaml?query=branch%3Amain) - -### [seL4](https://github.com/seL4/seL4/) - -[![Compile](https://github.com/seL4/seL4/actions/workflows/compilation-checks.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/compilation-checks.yml?query=branch%3Amaster) -[![C Parser](https://github.com/seL4/seL4/actions/workflows/cparser.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/cparser.yml?query=branch%3Amaster) -[![RefMan](https://github.com/seL4/seL4/actions/workflows/manual.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/manual.yml?query=branch%3Amaster) -[![Proof Sync](https://github.com/seL4/seL4/actions/workflows/preprocess-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/preprocess-deploy.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/seL4/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test](https://github.com/seL4/seL4/actions/workflows/sel4test-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/sel4test-deploy.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/seL4/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/trigger.yml?query=branch%3Amaster) -[![XML](https://github.com/seL4/seL4/actions/workflows/xml_lint.yml/badge.svg?branch=master)](https://github.com/seL4/seL4/actions/workflows/xml_lint.yml?query=branch%3Amaster) - -### [seL4-CAmkES-L4v-dockerfiles](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/) - -[![Deploy](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/actions/workflows/docker-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/actions/workflows/docker-deploy.yml?query=branch%3Amaster) -[![CI](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/actions/workflows/push.yml?query=branch%3Amaster) - -### [seL4_libs](https://github.com/seL4/seL4_libs/) - -[![CI](https://github.com/seL4/seL4_libs/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_libs/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test](https://github.com/seL4/seL4_libs/actions/workflows/sel4test-sim.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_libs/actions/workflows/sel4test-sim.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/seL4_libs/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_libs/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [seL4_projects_libs](https://github.com/seL4/seL4_projects_libs/) - -[![CI](https://github.com/seL4/seL4_projects_libs/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_projects_libs/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test](https://github.com/seL4/seL4_projects_libs/actions/workflows/sel4test-sim.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_projects_libs/actions/workflows/sel4test-sim.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/seL4_projects_libs/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_projects_libs/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [seL4_tools](https://github.com/seL4/seL4_tools/) - -[![CI](https://github.com/seL4/seL4_tools/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_tools/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test](https://github.com/seL4/seL4_tools/actions/workflows/sel4test-sim.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_tools/actions/workflows/sel4test-sim.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/seL4_tools/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/seL4_tools/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [sel4-tutorials](https://github.com/seL4/sel4-tutorials/) - -[![CI](https://github.com/seL4/sel4-tutorials/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4-tutorials/actions/workflows/push.yml?query=branch%3Amaster) -[![Test](https://github.com/seL4/sel4-tutorials/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/seL4/sel4-tutorials/actions/workflows/test.yml?query=branch%3Amaster) - -### [sel4-tutorials-manifest](https://github.com/seL4/sel4-tutorials-manifest/) - -[![CI](https://github.com/seL4/sel4-tutorials-manifest/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4-tutorials-manifest/actions/workflows/push.yml?query=branch%3Amaster) - -### [sel4bench](https://github.com/seL4/sel4bench/) - -[![CI](https://github.com/seL4/sel4bench/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4bench/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Bench](https://github.com/seL4/sel4bench/actions/workflows/sel4bench.yml/badge.svg?branch=master)](https://github.com/seL4/sel4bench/actions/workflows/sel4bench.yml?query=branch%3Amaster) - -### [sel4bench-manifest](https://github.com/seL4/sel4bench-manifest/) - -[![CI](https://github.com/seL4/sel4bench-manifest/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4bench-manifest/actions/workflows/push.yml?query=branch%3Amaster) - -### [sel4runtime](https://github.com/seL4/sel4runtime/) - -[![CI](https://github.com/seL4/sel4runtime/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4runtime/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test](https://github.com/seL4/sel4runtime/actions/workflows/sel4test-sim.yml/badge.svg?branch=master)](https://github.com/seL4/sel4runtime/actions/workflows/sel4test-sim.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/sel4runtime/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/sel4runtime/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [sel4test](https://github.com/seL4/sel4test/) - -[![CI](https://github.com/seL4/sel4test/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4test/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test](https://github.com/seL4/sel4test/actions/workflows/sel4test-sim.yml/badge.svg?branch=master)](https://github.com/seL4/sel4test/actions/workflows/sel4test-sim.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/sel4test/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/sel4test/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [sel4test-manifest](https://github.com/seL4/sel4test-manifest/) - -[![CI](https://github.com/seL4/sel4test-manifest/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4test-manifest/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test](https://github.com/seL4/sel4test-manifest/actions/workflows/sel4test-sim.yml/badge.svg?branch=master)](https://github.com/seL4/sel4test-manifest/actions/workflows/sel4test-sim.yml?query=branch%3Amaster) - -### [sel4webserver](https://github.com/seL4/sel4webserver/) - -[![CI](https://github.com/seL4/sel4webserver/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4webserver/actions/workflows/push.yml?query=branch%3Amaster) -[![Web Server Demo](https://github.com/seL4/sel4webserver/actions/workflows/sel4webserver-deploy.yml/badge.svg?branch=master)](https://github.com/seL4/sel4webserver/actions/workflows/sel4webserver-deploy.yml?query=branch%3Amaster) - -### [sel4webserver-manifest](https://github.com/seL4/sel4webserver-manifest/) - -[![CI](https://github.com/seL4/sel4webserver-manifest/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/sel4webserver-manifest/actions/workflows/push.yml?query=branch%3Amaster) - -### [util_libs](https://github.com/seL4/util_libs/) - -[![CI](https://github.com/seL4/util_libs/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/util_libs/actions/workflows/push.yml?query=branch%3Amaster) -[![seL4Test Sim](https://github.com/seL4/util_libs/actions/workflows/sel4test-sim.yml/badge.svg?branch=master)](https://github.com/seL4/util_libs/actions/workflows/sel4test-sim.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/util_libs/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/util_libs/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [verification-manifest](https://github.com/seL4/verification-manifest/) - -[![CI](https://github.com/seL4/verification-manifest/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/verification-manifest/actions/workflows/push.yml?query=branch%3Amaster) -[![Trigger](https://github.com/seL4/verification-manifest/actions/workflows/trigger.yml/badge.svg?branch=master)](https://github.com/seL4/verification-manifest/actions/workflows/trigger.yml?query=branch%3Amaster) - -### [website](https://github.com/seL4/website/) - -[![CI](https://github.com/seL4/website/actions/workflows/push.yml/badge.svg?branch=master)](https://github.com/seL4/website/actions/workflows/push.yml?query=branch%3Amaster) - -### [whitepaper](https://github.com/seL4/whitepaper/) - -[![build PDF](https://github.com/seL4/whitepaper/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/seL4/whitepaper/actions/workflows/build.yml?query=branch%3Amaster) -[![License](https://github.com/seL4/whitepaper/actions/workflows/license.yaml/badge.svg?branch=master)](https://github.com/seL4/whitepaper/actions/workflows/license.yaml?query=branch%3Amaster) diff --git a/projects/buildsystem/host-dependencies.html b/projects/buildsystem/host-dependencies.html new file mode 100644 index 00000000000..bc393abbfec --- /dev/null +++ b/projects/buildsystem/host-dependencies.html @@ -0,0 +1,738 @@ + + + + + + + Setting up your machine to build seL4 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Setting up your machine to build seL4

+ +

This page describes how to set up your development host machine for building and +running the seL4 kernel. There are additional steps if you are planning to use +CAmkES or Rust on top of seL4. You do not need this step if you are using +the Microkit, because it comes with pre-compiled seL4 binaries.

+ +

Get Google’s Repo tool

+ +

The primary way of obtaining and managing seL4 project sources is through +Google’s repo tool. To start with, get repo by following the +instructions in the section “Install” on the repo +site.

+ +

See the repo cheatsheet page for a quick explanation of how we use repo.

+ +

Docker or native

+ +

To compile and use seL4 you can either:

+ +
    +
  • Recommended: follow the instructions here to use Docker for +isolating the dependencies from your machine, or
    • +
  • install the build dependencies below on your local OS
    • +
+ +

The following instructions describe how to set up the required dependencies on +your local OS. This page assumes you are building in a Linux OS. We however +encourage site contributions for build instructions in other OSes (e.g. +macOS).

+ +

Ubuntu

+ +

These instructions are intended for Ubuntu LTS versions 20.04 and 22.04.

+ +
+
+ + Note +
+
+ +

If you discover any missing dependencies and packages we welcome new +contributions to the page. You can edit this section directly on GitHub.

+ +
+
+ +

Base dependencies

+ +

The basic build package on Ubuntu is the build-essential package. To install run:

+ +
sudo apt-get update
+sudo apt-get install build-essential
+
+ +

Additional base dependencies for building seL4 projects on Ubuntu include installing:

+ +
sudo apt-get install cmake ccache ninja-build cmake-curses-gui
+sudo apt-get install libxml2-utils ncurses-dev
+sudo apt-get install curl git doxygen device-tree-compiler xxd
+sudo apt-get install u-boot-tools
+sudo apt-get install python3-dev python3-pip python-is-python3
+sudo apt-get install protobuf-compiler python3-protobuf
+
+ +

Simulating with QEMU

+ +

In order to run seL4 projects on a simulator you will need QEMU:

+ +
sudo apt-get install qemu-system-arm qemu-system-x86 qemu-system-misc
+
+ +

Cross-compiling for ARM targets

+ +

To build for ARM targets you will need a cross compiler:

+ +
sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
+sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
+
+ +

(you can install the hardware floating point versions as well if you wish)

+ +
sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
+
+ +

Cross-compiling for RISC-V targets

+ +

To build for RISC-V targets you will need a cross compiler:

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building the seL4 manual

+ +

If you would like to build the seL4 manual, you will need the following LaTeX pacakges:

+ +
sudo apt-get install texlive texlive-latex-extra texlive-fonts-extra
+
+ +

Debian

+ +

The dependencies listed in our Docker files +repository will work for +a Debian Bullseye, most likely also for later releases. You can refer to this repository +for an up-to-date list of base build dependencies. Specifically refer to the +dependencies listed in the file here:

+ + + +

Python

+ +

A number of Python packages are required to build seL4 and its manual. To install these you can run:

+ +
pip3 install --user setuptools sel4-deps
+
+ +

(Some distributions use pip for python3, others use pip3. Use the Python 3 version for your distribution)

+ +
+ Error: Python environment is externally managed +
+ +

Some Linux distributions have changed how Python is managed. If you get an error +saying the Python ‘environment is externally managed’ follow the instructions +below. The first two steps are needed only once for setup.

+ + 
python3 -m venv seL4-venv
+./seL4-venv/bin/pip install sel4-deps
+
+ +

The following step is needed every time you start using the build environment +in a new shell.

+ + 
source ./seL4-venv/bin/activate
+
+ +

It is not important where the seL4-venv directory is located.

+
+
+ +

Test

+ +

To test whether your build environment works, we recommend running the seL4 test +suite in qemu. For instance:

+ +
# target directory
+mkdir sel4test
+cd sel4test
+
+# get the sources
+repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+
+# create build directory
+mkdir build
+cd build
+
+# configure build
+../init-build.sh -DSIMULATION=TRUE -DAARCH32=TRUE -DPLATFORM=sabre
+
+# build
+ninja
+
+# run
+./simulate
+
+ +

This should start qemu and run a series of tests. Don’t worry if error +messages appear, they are explicit tests for errors.

+ +

An output of All is well in the universe at the end indicates a successful +test run. To exit qemu, press Ctrl-a, then x.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/buildsystem/host-dependencies.md b/projects/buildsystem/host-dependencies.md deleted file mode 100644 index 2bf59930a5a..00000000000 --- a/projects/buildsystem/host-dependencies.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -redirect_from: - - /HostDependencies -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Setting up your machine to build seL4 - -This page describes how to set up your development host machine for building and -running the seL4 kernel. There are additional steps if you are planning to use -[CAmkES] or [Rust] on top of seL4. You do not need this step if you are using -the Microkit, because it comes with pre-compiled seL4 binaries. - -[CAmKES]: {% link projects/camkes/setting-up.md %} -[Rust]: {% link projects/rust/how-to-use.md %} - -{% include seL4-deps.md %} - -## Test - -To test whether your build environment works, we recommend running the seL4 test -suite in `qemu`. For instance: - -```sh -# target directory -mkdir sel4test -cd sel4test - -# get the sources -repo init -u https://github.com/seL4/sel4test-manifest.git -repo sync - -# create build directory -mkdir build -cd build - -# configure build -../init-build.sh -DSIMULATION=TRUE -DAARCH32=TRUE -DPLATFORM=sabre - -# build -ninja - -# run -./simulate -``` - -This should start `qemu` and run a series of tests. Don't worry if error -messages appear, they are explicit tests for errors. - -An output of `All is well in the universe` at the end indicates a successful -test run. To exit `qemu`, press `Ctrl-a`, then `x`. diff --git a/projects/buildsystem/incorporating.html b/projects/buildsystem/incorporating.html new file mode 100644 index 00000000000..89701d7d921 --- /dev/null +++ b/projects/buildsystem/incorporating.html @@ -0,0 +1,834 @@ + + + + + + + Incorporating into your project | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Incorporating into your project

+ +

This page describes the CMake-based build system in detail, with sufficient +information for integrating it into new projects. There are a few different +pieces that can be fit together in different ways depending on your project’s +needs and desired customisation. This is reflected in the split of CMake files +spread across several repositories.

+ +

Basic structure

+ +

The build system is in two pieces. One piece is in the seL4 kernel +repository, which contains the compiler toolchain +and flags settings as well as helpers for generating configurations. The other +piece is in +seL4_tools/cmake-tool, +which contains helpers for combining libraries and binaries into a final system +image (along with the kernel).

+ +

This structure means that the kernel is completely responsible for building +itself, but exports the settings and binaries for use by the rest of the build +system.

+ +

The cmake-tool directory has the following files of interest:

+ +
    +
  • default-CMakeLists.txt: An example CMakeLists.txt file, which could be +used as the CMakeLists.txt file in the top-level directory of a project. +Simply, this file includes all.cmake, under the assumption of a directory +structure where the cmake-tool repository is in a directory named tools. +To use this file, project +manifests are expected to create +a symbolic link to this file, named CMakeLists.txt, at the top-level project +directory.
    • +
  • all.cmake: A wrapper that includes base.cmake, projects.cmake and +configuration.cmake. This file can be used by projects which do not alter +these three files.
    • +
  • base.cmake: Constructs the basic build targets (kernel, libsel4, and +elfloader-tool), in addition to basic compilation flags and helper routines, +required to build an seL4 project, and can be used as a base for further +targets in a project through the add_subdirectory routine or otherwise.
    • +
  • projects.cmake: Adds build targets through add_subdirectory assuming a +default project layout. Essentially it adds any CMakeLists.txt files it +finds in any subdirectories of the projects directory. +that emulates the legacy autoconf.h header. Since the autoconf.h header
    • +
  • configuration.cmake: Provides a target for a library called Configuration +contained configuration variables for the entire project this rule needs to +come after all other targets and scripts which add to the configuration space.
    • +
  • common.cmake: File included by base.cmake with some generic helper routines.
    • +
  • flags.cmake: File included by base.cmake which sets up build flags and +linker invocations.
    • +
  • init-build.sh: A shell script which performs the initial configuration and +generation for a new CMake build directory.
    • +
  • helpers/*: Helper functions that are commonly imported by common.cmake
    • +
+ +

Kernel directory

+ +

The file base.cmake assumes that the seL4 kernel is in a specific location. +Consider the following example:

+ +
awesome_system/
+├── kernel/
+│   └── CMakeLists.txt
+├── projects/
+│   ├── awesome_system/
+│   │   └── CMakeLists.txt
+│   └── seL4_libs/
+│       └── CMakeLists.txt
+├── tools/
+│   └── cmake-tool/
+│       ├── base.cmake
+│       ├── all.cmake
+│       └── default-CMakeLists.txt
+├── .repo/
+└── CMakeLists.txt -> tools/cmake-tool/default-CMakeLists.txt
+
+ +

When awesome_system/ is used as the root source directory to initialise a +CMake build directory and tools/cmake-tool/all.cmake is used, base.cmake +expects the kernel to be at awesome_system/kernel.

+ +

The kernel can be placed in a different location, as described below.

+ +
awesome_system/
+├── seL4/
+│   └── CMakeLists.txt
+├── projects/
+│   ├── awesome_system/
+│   │   └── CMakeLists.txt
+│   └── seL4_libs/
+│       └── CMakeLists.txt
+├── tools/
+│   └── cmake-tool/
+│       ├── base.cmake
+│       ├── all.cmake
+│       └── default-CMakeLists.txt
+├── .repo/
+└── CMakeLists.txt -> tools/cmake-tool/default-CMakeLists.txt
+
+ +

For the example above, where the kernel is in a directory called seL4, the +default kernel location can be overridden when invoking cmake with +-DKERNEL_PATH=seL4.

+ +

Advanced structures

+ +

Other project layouts can be used. Consider the following example:

+ +
awesome_system/
+├── seL4/
+│   └── CMakeLists.txt
+├── awesome/
+│   └── CMakeLists.txt
+├── seL4_libs/
+│   └── CMakeLists.txt
+├── buildsystem/
+│   └── cmake-tool/
+│       ├── base.cmake
+│       ├── all.cmake
+│       └── default-CMakeLists.txt
+└── .repo/
+
+ +

The example above departs from the default in the following ways:

+ +
    +
  • no CMakeLists.txt file in the root directory,
    • +
  • tools directory has been renamed to buildsystem,
    • +
  • kernel directory has been renamed to seL4,
    • +
  • and the projects directory is omitted.
    • +
+ +

We now describe how to achieve such a project structure:

+ +

To place the CMakeLists.txt in awesome_system/awesome directory then +initialise CMake, assuming a build directory that is also in the +awesome_system directory, do something like:

+ +
sel4@host:~/awesome_directory$ cmake -DCROSS_COMPILER_PREFIX=toolchain-prefix -DCMAKE_TOOLCHAIN_FILE=../seL4/gcc.cmake -DKERNEL_PATH=../seL4 -G Ninja ../awesome
+
+ +

Importantly, the path for CMAKE_TOOLCHAIN_FILE is resolved immediately by +CMake, and so is relative to the build directory, whereas the KERNEL_PATH is +resolved whilst processing awesome_system/awesome/CMakeLists.txt and is +relative to that directory.

+ +

The contents of awesome_system/awesome/CMakeLists.txt would be something like:

+ +
cmake_minimum_required(VERSION 3.7.2)
+include(../buildsystem/cmake-tool/base.cmake)
+add_subdirectory(../seL4_libs seL4_libs)
+include(../buildsystem/cmake-tool/configuration.cmake)
+
+ +

This looks pretty much like all.cmake except that we do not include +projects.cmake as we do not have a projects folder. projects.cmake would be +redundant to include, as it would not resolve any files. all.cmake cannot be +included as we need to include specific subdirectories (in the example +seL4_libs) between setting up the base flags and environment and finalising +the Configuration library. We needed to give an explicit build directory (the +second argument in add_subdirectory) as we are giving a directory that is not +a subdirectory of the root source directory.

+ +

For simplicity, the kernel path can be encoded directly into the projects +top-level CMakeLists.txt. To achieve this the following line:

+ +
set(KERNEL_PATH ../seL4)
+
+ +

should be included before

+ +
include(../buildsystem/cmake-tool/base.cmake)
+
+ +

in awesome_system/awesome/CMakeLists.txt, thus removing the need for +-DKERNEL_PATH in the cmake invocation.

+ +

Configuration

+ +

For compatibility with the legacy build system, various helpers and systems +exist in order to achieve the following:

+ +
    +
  • Automate configuration variables that appear in the cmake-gui with various +kinds of dependencies.
    • +
  • Generate C-style configuration headers that declare these variables in format +similar to the legacy build system.
    • +
  • Generate autoconf.h headers so legacy code using #include <autoconf.h> +works.
    • +
+ +

The following fragment of CMake script demonstrates how these three things fit +together:

+ +
set(configure_string "")
+config_option(EnableAwesome HAVE_AWESOME "Makes library awesome" DEFAULT ON)
+add_config_library(MyLibrary "${configure_string}")
+generate_autoconf(MyLibraryAutoconf "MyLibrary")
+target_link_libraries(MyLibrary PUBLIC MyLibrary_Config)
+target_link_libraries(LegacyApplication PRIVATE MyLibrary MyLibraryAutoconf)
+
+ +

In the above example, line by line:

+ +
    +
  • set(configure_string ""): Initialise configure_string as blank, as various +config_* helpers automatically append to this variable.
    • +
  • config_option(EnableAwesome HAVE_AWESOME "Makes library awesome" DEFAULT + ON): Declare a configuration variable which appears in CMake scripts and the + cmake-gui as EnableAwesome, while appearing in C headers as + CONFIG_HAVE_AWESOME.
    • +
  • add_config_library(MyLibrary "${configure_string}"): Generate a +MyLibrary_Config target, which is an interface +library +that has a generated C header based on the configuration string. Also add +MyLibrary to a global list of configuration libraries, which can be used to +generate a library containing contains “all the configurations in the system” +(autoconf.h in the legacy build system).
    • +
  • generate_autoconf(MyLibraryAutoconf "MyLibrary"): Generates a +MyLibraryAutoconf target, which is an interface +library +that depends upon MyLibrary_Config, and provides an autoconf.h file +including the configuration header from MyLibrary_Config.
    • +
  • target_link_libraries(MyLibrary PUBLIC MyLibrary_Config): Allows MyLibrary + to #include the generated configuration header by doing + #include <MyLibrary/gen_config.h>
    • +
  • target_link_libraries(LegacyApplication PRIVATE MyLibrary MyLibraryAutoconf) + Allows LegacyApplication to #include <autoconf.h> from + MyLibraryAutoconf. The autoconf.h in this case will contain + #include <MyLibrary/gen_config.h>.
    • +
+ +

For more details of the different config_* helpers read the comments on the +functions in +kernel/tools/helpers.cmake.

+ +

Helper functions

+ +

Several CMake functions exist for reuse in seL4 projects, which we now describe.

+ +

Kernel provided helpers

+ +

All of the helper functions described in the above section are provided in +tools/helpers.cmake in the seL4 repository. Other functions in this file are +only useful for the kernel build itself.

+ +

cmake-tool provided helpers

+ +

These helper functions are provided for user-level projects, in common.cmake and +all the files in helpers/. Notable functions are:

+ +
    +
  • DeclareRootserver(rootserver_target): Declares a CMake executable, +rootserver_target, as the root server for the system. This can only be used +once in a project and does the following: +
      +
    • changes build flags for the target,
      • +
    • creates necessary extra targets for chain loading,
      • +
    • creates the rootserver_image target which will create the final binary +images in images.
      • +
    +
    • +
  • MakeCPIO: Declares rules to create a linkable CPIO archive from a list of +input files.
    • +
  • GenerateSimulateScript: Creates a target called simulate_gen which will +generate a ./simulate shell script in the build directory for simulating the +project on QEMU if the target platform is supported. +An application is responsible for ensuring that the system configuration can +be simulated if it uses this function. Other functions are provided such as +SetSimulationScriptProperty to allow the application’s CMake scripts to +customise the simulation command generated.
    • +
  • ApplyCommonSimulationSettings: Attempts to change the kernel system +configuration to disable features that are not compatible with simulation.
    • +
  • ApplyCommonReleaseVerificationSettings(release, verification): Sets flags +for different combinations of ‘release’ (performance optimised builds) and +‘verification’ (verification friendly features) builds. Please see meta +configuration options for more detail +on these options.
    • +
+ +

Other provided helpers

+ +

Projects such as CAmkES, the CAmkES x86 VMM, +and Rumprun may provide +additional helper functions to allow applications to configure themselves. +Generally helper scripts will be called some variant of helpers.cmake, and +should be included in any CMake scripts that use them.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/buildsystem/incorporating.md b/projects/buildsystem/incorporating.md deleted file mode 100644 index 7f73006bcb4..00000000000 --- a/projects/buildsystem/incorporating.md +++ /dev/null @@ -1,290 +0,0 @@ ---- -parent: /projects/buildsystem/ -redirect_from: - - /Developing/Building/Incorporating -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Incorporating into your project - -This page describes the CMake-based build system in detail, with sufficient -information for integrating it into new projects. There are a few different -pieces that can be fit together in different ways depending on your project's -needs and desired customisation. This is reflected in the split of CMake files -spread across several repositories. - -## Basic structure - -The build system is in two pieces. One piece is in the [seL4 kernel -repository](https://github.com/seL4/seL4), which contains the compiler toolchain -and flags settings as well as helpers for generating configurations. The other -piece is in -[seL4_tools/cmake-tool](https://github.com/seL4/seL4_tools/tree/master/cmake-tool), -which contains helpers for combining libraries and binaries into a final system -image (along with the kernel). - -This structure means that the kernel is completely responsible for building -itself, but exports the settings and binaries for use by the rest of the build -system. - -The `cmake-tool` directory has the following files of interest: - -- `default-CMakeLists.txt`: An example `CMakeLists.txt` file, which could be - used as the `CMakeLists.txt` file in the top-level directory of a project. - Simply, this file includes `all.cmake`, under the assumption of a directory - structure where the `cmake-tool` repository is in a directory named `tools`. - To use this file, [project - manifests](repo-cheatsheet.html) are expected to create - a symbolic link to this file, named `CMakeLists.txt`, at the top-level project - directory. -- `all.cmake`: A wrapper that includes `base.cmake`, `projects.cmake` and - `configuration.cmake`. This file can be used by projects which do not alter - these three files. -- `base.cmake`: Constructs the basic build targets (`kernel`, `libsel4`, and - `elfloader-tool`), in addition to basic compilation flags and helper routines, - required to build an seL4 project, and can be used as a base for further - targets in a project through the `add_subdirectory` routine or otherwise. -- `projects.cmake`: Adds build targets through `add_subdirectory` assuming a - default project layout. Essentially it adds any `CMakeLists.txt` files it - finds in any subdirectories of the projects directory. - that emulates the legacy `autoconf.h` header. Since the `autoconf.h` header -- `configuration.cmake`: Provides a target for a library called `Configuration` - contained configuration variables for the *entire* project this rule needs to - come after all other targets and scripts which add to the configuration space. -- `common.cmake`: File included by `base.cmake` with some generic helper routines. -- `flags.cmake`: File included by `base.cmake` which sets up build flags and - linker invocations. -- `init-build.sh`: A shell script which performs the initial configuration and - generation for a new CMake build directory. -- `helpers/*`: Helper functions that are commonly imported by `common.cmake` - -## Kernel directory - -The file `base.cmake` assumes that the seL4 kernel is in a specific location. -Consider the following example: - -```none -awesome_system/ -├── kernel/ -│ └── CMakeLists.txt -├── projects/ -│ ├── awesome_system/ -│ │ └── CMakeLists.txt -│ └── seL4_libs/ -│ └── CMakeLists.txt -├── tools/ -│ └── cmake-tool/ -│ ├── base.cmake -│ ├── all.cmake -│ └── default-CMakeLists.txt -├── .repo/ -└── CMakeLists.txt -> tools/cmake-tool/default-CMakeLists.txt -``` - -When `awesome_system/` is used as the root source directory to initialise a -CMake build directory and `tools/cmake-tool/all.cmake` is used, `base.cmake` -expects the kernel to be at `awesome_system/kernel`. - -The kernel can be placed in a different location, as described below. - -```none -awesome_system/ -├── seL4/ -│ └── CMakeLists.txt -├── projects/ -│ ├── awesome_system/ -│ │ └── CMakeLists.txt -│ └── seL4_libs/ -│ └── CMakeLists.txt -├── tools/ -│ └── cmake-tool/ -│ ├── base.cmake -│ ├── all.cmake -│ └── default-CMakeLists.txt -├── .repo/ -└── CMakeLists.txt -> tools/cmake-tool/default-CMakeLists.txt -``` - -For the example above, where the kernel is in a directory called `seL4`, the -default kernel location can be overridden when invoking `cmake` with -`-DKERNEL_PATH=seL4`. - -## Advanced structures - -Other project layouts can be used. Consider the following example: - -```none -awesome_system/ -├── seL4/ -│ └── CMakeLists.txt -├── awesome/ -│ └── CMakeLists.txt -├── seL4_libs/ -│ └── CMakeLists.txt -├── buildsystem/ -│ └── cmake-tool/ -│ ├── base.cmake -│ ├── all.cmake -│ └── default-CMakeLists.txt -└── .repo/ -``` - -The example above departs from the default in the following ways: - -- no `CMakeLists.txt` file in the root directory, -- `tools` directory has been renamed to `buildsystem`, -- `kernel` directory has been renamed to `seL4`, -- and the `projects` directory is omitted. - -We now describe how to achieve such a project structure: - -To place the `CMakeLists.txt` in `awesome_system/awesome` directory then -initialise CMake, assuming a build directory that is also in the -`awesome_system` directory, do something like: - -```sh -sel4@host:~/awesome_directory$ cmake -DCROSS_COMPILER_PREFIX=toolchain-prefix -DCMAKE_TOOLCHAIN_FILE=../seL4/gcc.cmake -DKERNEL_PATH=../seL4 -G Ninja ../awesome -``` - -Importantly, the path for `CMAKE_TOOLCHAIN_FILE` is resolved immediately by -CMake, and so is relative to the build directory, whereas the `KERNEL_PATH` is -resolved whilst processing `awesome_system/awesome/CMakeLists.txt` and is -relative to that directory. - -The contents of `awesome_system/awesome/CMakeLists.txt` would be something like: - -```cmake -cmake_minimum_required(VERSION 3.7.2) -include(../buildsystem/cmake-tool/base.cmake) -add_subdirectory(../seL4_libs seL4_libs) -include(../buildsystem/cmake-tool/configuration.cmake) -``` - -This looks pretty much like `all.cmake` except that we do not include -`projects.cmake` as we do not have a projects folder. `projects.cmake` would be -redundant to include, as it would not resolve any files. `all.cmake` cannot be -included as we need to include specific subdirectories (in the example -`seL4_libs`) between setting up the base flags and environment and finalising -the Configuration library. We needed to give an explicit build directory (the -second argument in `add_subdirectory`) as we are giving a directory that is not -a subdirectory of the root source directory. - -For simplicity, the kernel path can be encoded directly into the projects -top-level `CMakeLists.txt`. To achieve this the following line: - -```cmake -set(KERNEL_PATH ../seL4) -``` - -should be included before - -```cmake -include(../buildsystem/cmake-tool/base.cmake) -``` - -in `awesome_system/awesome/CMakeLists.txt`, thus removing the need for -`-DKERNEL_PATH` in the `cmake` invocation. - -## Configuration - -For compatibility with the legacy build system, various helpers and systems -exist in order to achieve the following: - -- Automate configuration variables that appear in the `cmake-gui` with various - kinds of dependencies. -- Generate C-style configuration headers that declare these variables in format - similar to the legacy build system. -- Generate `autoconf.h` headers so legacy code using `#include ` - works. - -The following fragment of CMake script demonstrates how these three things fit -together: - -```cmake -set(configure_string "") -config_option(EnableAwesome HAVE_AWESOME "Makes library awesome" DEFAULT ON) -add_config_library(MyLibrary "${configure_string}") -generate_autoconf(MyLibraryAutoconf "MyLibrary") -target_link_libraries(MyLibrary PUBLIC MyLibrary_Config) -target_link_libraries(LegacyApplication PRIVATE MyLibrary MyLibraryAutoconf) -``` - -In the above example, line by line: - -- `set(configure_string "")`: Initialise `configure_string` as blank, as various - `config_*` helpers automatically append to this variable. -- `config_option(EnableAwesome HAVE_AWESOME "Makes library awesome" DEFAULT - ON)`: Declare a configuration variable which appears in CMake scripts and the - `cmake-gui` as `EnableAwesome`, while appearing in C headers as - `CONFIG_HAVE_AWESOME`. -- `add_config_library(MyLibrary "${configure_string}")`: Generate a - `MyLibrary_Config` target, which is an [interface - library](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#interface-libraries) - that has a generated C header based on the configuration string. Also add - `MyLibrary` to a global list of configuration libraries, which can be used to - generate a library containing contains "all the configurations in the system" - (`autoconf.h` in the legacy build system). -- `generate_autoconf(MyLibraryAutoconf "MyLibrary")`: Generates a - `MyLibraryAutoconf` target, which is an [interface - library](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#interface-libraries) - that depends upon `MyLibrary_Config`, and provides an `autoconf.h` file - including the configuration header from `MyLibrary_Config`. -- `target_link_libraries(MyLibrary PUBLIC MyLibrary_Config)`: Allows `MyLibrary` - to `#include` the generated configuration header by doing - `#include ` -- `target_link_libraries(LegacyApplication PRIVATE MyLibrary MyLibraryAutoconf)` - Allows `LegacyApplication` to `#include ` from - `MyLibraryAutoconf`. The `autoconf.h` in this case will contain - `#include `. - -For more details of the different `config_*` helpers read the comments on the -functions in -[kernel/tools/helpers.cmake](https://github.com/seL4/seL4/blob/master/tools/helpers.cmake). - -## Helper functions - -Several CMake functions exist for reuse in seL4 projects, which we now describe. - -### Kernel provided helpers - -All of the helper functions described in the above section are provided in -`tools/helpers.cmake` in the seL4 repository. Other functions in this file are -only useful for the kernel build itself. - -### `cmake-tool` provided helpers - -These helper functions are provided for user-level projects, in `common.cmake` and -all the files in `helpers/`. Notable functions are: - -- `DeclareRootserver(rootserver_target)`: Declares a CMake executable, - `rootserver_target`, as the root server for the system. This can only be used - once in a project and does the following: - - changes build flags for the target, - - creates necessary extra targets for chain loading, - - creates the `rootserver_image` target which will create the final binary - images in `images`. -- `MakeCPIO`: Declares rules to create a linkable CPIO archive from a list of - input files. -- `GenerateSimulateScript`: Creates a target called `simulate_gen` which will - generate a `./simulate` shell script in the build directory for simulating the - project on [QEMU](https://www.qemu.org/) if the target platform is supported. - An application is responsible for ensuring that the system configuration can - be simulated if it uses this function. Other functions are provided such as - `SetSimulationScriptProperty` to allow the application's CMake scripts to - customise the simulation command generated. -- `ApplyCommonSimulationSettings`: Attempts to change the kernel system - configuration to disable features that are not compatible with simulation. -- `ApplyCommonReleaseVerificationSettings(release, verification)`: Sets flags - for different combinations of 'release' (performance optimised builds) and - 'verification' (verification friendly features) builds. Please see [meta - configuration options](using.html#meta-configuration-options) for more detail - on these options. - -### Other provided helpers - -Projects such as [CAmkES](../camkes/), the [CAmkES x86 VMM](../camkes-vm/), -and [Rumprun](https://github.com/seL4/rumprun-sel4-demoapps) may provide -additional helper functions to allow applications to configure themselves. -Generally helper scripts will be called some variant of `helpers.cmake`, and -should be included in any CMake scripts that use them. diff --git a/projects/buildsystem/index.html b/projects/buildsystem/index.html new file mode 100644 index 00000000000..090cb436208 --- /dev/null +++ b/projects/buildsystem/index.html @@ -0,0 +1,612 @@ + + + + + + + System configuration and building | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

System configuration and building

+ +

seL4, CAmkES, and the C support libraries use the CMake +family of tools to implement their build system. The seL4 build system refers to a +collection of CMake scripts that manage:

+ +
    +
  • system configuration: configuration options such as platform flags and application settings,
    • +
  • dependency structures: tracking build order dependencies, and
    • +
  • builds: generating binary artefacts that can then be deployed on hardware.
    • +
+ +

This document covers how to use the seL4 build system to:

+ +
    +
  • perform system configuration and builds,
    • +
  • incorporating the build system into a project, and
    • +
  • produce kernel stand-alone configuration and builds
    • +
+ +

CMake basics

+ +

For a complete guide to CMake see the extensive +documentation, but for the purposes here +we will assume a particular workflow with CMake involving out-of-tree builds.

+ +

CMake is not itself a build tool, but rather is a build generator. This means +that it generates build scripts, typically Makefiles or Ninja scripts, which +will be then used by a tool like Make or Ninja to perform the actual build.

+ +

Pre-requisites

+ +

It is assumed that

+ +
    +
  • CMake of an appropriate version is installed.
    • +
  • You are using the Ninja CMake generator.
    • +
  • You have the required dependencies installed to +build your project and understand how to check out +repo collections.
    • +
+ +

Steps

+ + + +

Interfacing with other build systems

+ +

The page on standalone kernel builds shows how to generate a +bare kernel binary without user-level image or loader, for use in other build +system or in formal verification. The kernel build system produces .json and +.yaml files with information on the configuration that was used to produce the +binary, for consumption in other build systems.

+ +

Gotchas

+ +

List of easy mistakes that can be made when using CMake

+ +
    +
  • Configuration files passed to to cmake with -C must end in .cmake, +otherwise CMake will silently throw away your file
    • +
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/buildsystem/index.md b/projects/buildsystem/index.md deleted file mode 100644 index d33fde8f6a3..00000000000 --- a/projects/buildsystem/index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -redirect_from: - - /Developing/Building/ -project: buildsystem -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# System configuration and building - -seL4, CAmkES, and the C support libraries use the [CMake](https://cmake.org/) -family of tools to implement their build system. The seL4 build system refers to a -collection of CMake scripts that manage: - -- **system configuration:** configuration options such as platform flags and application settings, -- **dependency structures:** tracking build order dependencies, and -- **builds:** generating binary artefacts that can then be deployed on hardware. - -This document covers how to use the seL4 build system to: - -- perform system configuration and builds, -- incorporating the build system into a project, and -- produce kernel stand-alone configuration and builds - -## CMake basics - -For a complete guide to CMake see the [extensive -documentation](https://cmake.org/cmake/help/latest/), but for the purposes here -we will assume a particular workflow with CMake involving out-of-tree builds. - -CMake is not itself a build tool, but rather is a build generator. This means -that it generates build scripts, typically Makefiles or Ninja scripts, which -will be then used by a tool like Make or Ninja to perform the actual build. - -### Pre-requisites - -It is assumed that - -- CMake of an appropriate version is installed. -- You are using the Ninja CMake generator. -- You have the [required dependencies](host-dependencies.html) installed to - build your project and understand how to check out - [repo](repo-cheatsheet.html) collections. - -### Steps - -- [Configuring and building seL4 projects](using.html) -- [Incorporating the build system into a project](incorporating.html) - -## Interfacing with other build systems - -The page on [standalone kernel builds](standalone.html) shows how to generate a -bare kernel binary without user-level image or loader, for use in other build -system or in formal verification. The kernel build system produces `.json` and -`.yaml` files with information on the configuration that was used to produce the -binary, for consumption in other build systems. - -## Gotchas - -List of easy mistakes that can be made when using CMake - -- Configuration files passed to to cmake with `-C` *must* end in `.cmake`, - otherwise CMake will silently throw away your file diff --git a/projects/buildsystem/old/index.html b/projects/buildsystem/old/index.html new file mode 100644 index 00000000000..ad0334a01e5 --- /dev/null +++ b/projects/buildsystem/old/index.html @@ -0,0 +1,1053 @@ + + + + + + + Our old deprecated Build System | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Our old deprecated Build System

+ +

For the new build system see the build system overview.

+ +

Anatomy of the Build System

+

The following files are the components +of a project repository that are part of the build system (as opposed to +code and tools related to the project):

+ +
    +
  • .config - Your current + configuration (auto-generated)
    • +
  • apps/ +
      +
    • Kbuild - Application targets and + dependencies
      • +
    • Kconfig - Applications menu
      • +
    • myapp/ + +
      • +
    +
    • +
  • configs/* - Pre-made configurations for the project
    • +
  • Kconfig - Top-level menu
    • +
  • kernel/Makefile - How to build seL4
    • +
  • libs/ +
      +
    • Kbuild - Library targets and + dependencies
      • +
    • Kconfig - Libraries menu
      • +
    • libfoo/ + +
      • +
    +
    • +
  • Makefile - Top-level build specialisation
    • +
  • Makefile.flags - Top-level build + tuning
    • +
  • tools/common/ +
      +
    • common.mk - Boiler plate for building +applications/libraries
      • +
    • Kconfig - Menu options for toolchains +and other common settings
      • +
    • project-arm.mk - ARM-specific boiler +plate for a top-level build
      • +
    • project-ia32.mk - IA32-specific +boiler plate for a top-level build
      • +
    • project.mk - +Architecture-independent boiler plate for a top-level build
      • +
    • Makefile.flags - Shared build +system tuning
      • +
    • kbuild/* - Kbuild from the Linux source tree. For +documentation, refer to the Kbuild mailing list.
      • +
    +
    • +
+ +

Build configuration

+

Prior to building a project you need to +specify a configuration (settings, components, etc.) that you want to +build. Kconfig is a tool for simplifying and automating this process. In +an seL4 project you can enter make menuconfig in the top level directory +to be presented with a terminal menu for choosing which components to +build. Note that you will need the package libncurses5-dev installed to +display terminal menus. It is possible to select a configuration without +using the terminal menus, but techniques for doing this are not +discussed on this page.

+ +

The menu config interface

+ +

Use arrow keys and Enter to navigate the menu, Space bar to +select/deselect items and Esc-Esc to return to the parent level in the +menu hierarchy. On exiting the menu system you will be asked whether you +wish to save your configuration. If you choose to do so it will be +written to the file .config in the top level directory.

+ +

Many projects will have a default list of configurations for building +common scenarios. These are located in the configs/ directory. You can +load one of these by running make config_file where config_file is the +filename of the configuration you want to load. Whenever you load one of +these pre-made configurations it is usually wise to run make +silentoldconfig. This scans your project for configuration settings that +have changed since the pre-made configuration was created and updates +the configuration with the defaults of these changed settings. This is +not always what you want, but it generally works.

+ +

Your current configuration is stored in the file .config. This file +looks like a Makefile fragment and that is actually exactly how it is +used by build system when it comes time to build your project. One +gotcha to be aware of is that the comments in this file aren’t +completely comments, which you will find out if you try to edit them. +Kconfig parses these comments and will throw all manner of strange +errors if it thinks one is malformed.

+ +

Pre-made configurations are stored in configs/. To make a new +configuration, pick the settings you want in the menus then copy your +.config to configs/. Note that all the configurations in this directory +must end in _defconfig for the build system to identify them correctly.

+ +

The other file(s) you will want to care about is Kconfig. These files +tell Kconfig how to construct the menu hierarchy. A formal description +of the Kconfig options and syntax can be found at +http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt. +Symbols are defined by using the ‘config’ statement. These symbols are +given the prefix ‘CONFIG_’ when the configuration is written to the +.config file.

+ +

.config

+

.config is autogenerated by running +make some_default_config or make menuconfig. In general, you shouldn’t +modify this file manually, but the syntax is pretty obvious if you want +to. As noted below, it is not recommended to touch the comments in this +file. They are parsed by the build system and “malformed” comments can +cause strange and mysterious errors.

+ +

apps/Kbuild

+

apps/Kbuild needs to fill the +apps-y variable with the targets of the applications to be built. To do +this you can reference the CONFIG_-prefixed variables from Kconfig. A +typical apps/Kbuild will look something like the following:

+
apps-$(CONFIG_MY_APP) += myapp
+
+hello: libfoo
+
+

If your application has more complicated dependencies, +for example if it depends on libbar only when the +MYAPP_EXTRA_FUNCTIONALITY variable is selected, you can use the +following pattern:

+
apps-$(CONFIG_MY_APP) += myapp
+
+hello-y = libfoo
+hello-$(CONFIG_MYAPP_EXTRA_FUNCTIONALITY) += libbar
+hello: $(hello-y)
+
+ +

Kconfig

+

The Kconfig files (Kconfig, +apps/Kconfig, apps/myapp/Kconfig, libs/Kconfig, libs/libfoo/Kconfig, +tools/common/Kconfig) describe the structure of the menu you are +presented with when you type make menuconfig. The syntax of these files +is described at +http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt and +they are broken up in the obvious way; that is, apps/Kconfig contains +settings common to all applications in your project, libs/libfoo/Kconfig +contains settings specific to libfoo, … The Kconfig files together +determine the build configuration process that is described in more +detail below.

+ +

apps/myapp/Makefile

+ +

Your application Makefile, +apps/myapp/Makefile, should populate a set of variables and then +include common.mk. It will typically look something like the following:

+
TARGETS := $(notdir $(SOURCE_DIR)).bin
+
+CFILES := $(patsubst $(SOURCE_DIR)/%,%,$(wildcard $(SOURCE_DIR)/src/*.c))
+ASMFILES := $(patsubst $(SOURCE_DIR)/%,%,$(wildcard $(SOURCE_DIR)/crt/arch-$(ARCH)/crt0.S))
+
+LIBS := sel4c sel4 sel4rootserver sel4platsupport
+
+include $(SEL4_COMMON)/common.mk
+
+

TARGETS should contain the list +of output files that this application needs built. CFILES and ASMFILES +list the C and assembly sources of your application, respectively. LIBS +lists the libraries this application will be linked against (without +their “lib” prefix). You can also use your Makefile to modify the flags +that are passed to the compiler or the linker when building your +application. To do this, modify the variables CFLAGS and LDFLAGS, +respectively. For example, you can use “LDFLAGS += -T +path/to/linker.lds” to use a custom linker script for your application +or “CFLAGS := $(filter-out -Wall,$(CFLAGS))” to turn off compiler +warnings for your application. Note that these modifications should be +added after including common.mk.

+ +

libs/Kbuild

+

Like apps/Kbuild describes top-level +application dependencies, libs/Kbuild describes top-level library +dependencies. Similarly, it fills the variable libs-y with the libraries +to be built. A typical libs/Kbuild would look like:

+
libs-$(CONFIG_LIB_FOO) += libfoo
+libs-$(CONFIG_LIB_BAR) += libbar
+
+libfoo: common
+libbar: common libfoo
+
+ +

libs/libfoo/Makefile

+

The Makefile for a particular +library, libs/libfoo/Makefile, should just contain some variable +configuration and then include common.mk. Note that by using generic +environment variables you can often use the following template with no +modification for your library:

+
# Library archive(s) that will be built.
+TARGETS := $(notdir ${SOURCE_DIR}).a
+
+# Source files required to build the target.
+CFILES := $(patsubst $(SOURCE_DIR)/%,%,$(wildcard ${SOURCE_DIR}/src/*.c))
+ASMFILES := $(patsubst $(SOURCE_DIR)/%,%,$(wildcard ${SOURCE_DIR}/src/*.S))
+
+# Header files/directories this library provides.
+HDRFILES := $(wildcard ${SOURCE_DIR}/include/*)
+
+include $(SEL4_COMMON)/common.mk
+
+ +

You can modify the compiler or linker flags applied when building your +library by modifying the NK_CFLAGS or NK_LDFLAGS variable +respectively. The process for doing this is identical to that for +apps/myapp/Makefile described above.

+ +

Makefile

+

Something that may be unexpected at +first is that you don’t need to provide any project-specific targets in +your top-level Makefile. Generally this file just needs to make +app-images the default target and include project.mk. It’s possible you +may want to override the default (by defining a target before including +project.mk) or provide some external targets of your own (after +including project.mk). You will most likely just want to mimic the +content of the file from the reference examples:

+
# app-images is provided in project.mk.
+all: app-images
+
+include tools/common/project.mk
+
+# Extra project-specific targets. simulate-kzm:
+qemu-arm -nographic -M kzm -kernel images/hello-image-arm-imx31
+
+ +

project.mk

+

tools/common/project.mk contains +some generic targets and supporting infrastructure for building the +various components of your system. It is from this Makefile that the +application and library Makefiles are invoked. The architecture specific +elements of this are contained in tools/common/project-arm.mk and +tools/common/project-ia32.mk. Your top-level Makefile should +import tools/common/project.mk to take advantage of the build system +support.

+ +

common.mk

+

tools/common/common.mk is the +equivalent of tools/common/project.mk for the application-/library-level +compilation (as opposed to top-level). This probably won’t make much +sense unless you are familiar with the two-stage build process that is +being invoked when you type “make”, but you generally won’t need to +concern yourself with the inner workings of this file anyway. This file +contains a collection of generic compiler flags and targets shared +between all projects. It has evolved over time (in some instances in +response to bugs in toolchains), so it is possible there are sections of +this file that are deprecated. If you find something incorrect or +deprecated feel free to correct or modify it, but be aware that even +seemingly innocuous changes to this file are quite likely to break other +people’s builds.

+ +

Makefile.flags

+

Makefile.flags and +tools/common/Makefile.flags contain a set of options that are +applied globally at the top level. These generally contain +compiler-specific options to discriminate between your target platforms. +The shared settings in tools/common/Makefile.flags should be more than +sufficient for most projects, but projects with more esoteric build +requirements may need to use Makefile.flags to override or extend the +shared settings. Most projects will have an empty Makefile.flags because +there is almost always a more appropriate place to put an override.

+ +

Build Execution

+

Note: ‘‘If you are accustomed to Kbuild from +the Linux kernel, note that we do not use Kbuild in the same way it is +used in Linux. In particular, components are built with their own +Makefiles, not with the Kbuild generic targets that build object files +at a directory-level granularity. It is best not to assume any behaviour +you may be familiar with from Kbuild.’’

+ +

Where Kconfig handles the configuration of your build process, the +remainder of the build system manages dependencies and rules within a +build. The tools/Kbuild directory itself is a black hole of despair and +I would encourage you not to look in there unless you have a high +tolerance for pain. All other relevant files are covered above.

+ +

Frequently Asked Questions

+

Why do I need to specify the same +list of dependencies in apps/myapp/Makefile, apps/Kbuild and +apps/myapp/Kconfig?

+ +

While these dependency lists appear to serve an identical function, they +actually do not. apps/myapp/Makefile defines the contents of LIBS to be +the libraries that your application is linked against. apps/Kbuild +defines the dependencies (libraries or otherwise) of your applications. +apps/myapp/Kconfig defines the dependency structure of Kconfig menu +items that may or may not map to build targets. In practice, most of our +use cases have an identical list for these three, but they have been +kept separate to allow a finer grained control over the build system +when necessary.

+ +

If this really is a serious irritation to you and your dependencies +really are the same in all three places, you can replace your dependency +line in apps/Kbuild with:

+
myapp: $(shell grep "depends on" $(APPS_ROOT)/myapp/Kconfig | sed -e 's/depends on//g' -e 's/[&_]//g' | tr A-Z a-z)
+
+

and your LIBS line in +apps/myapp/Makefile with:

+
LIBS := $(patsubst lib%,%,$(shell grep "depends on" $(SOURCE_DIR)/Kconfig | sed -e 's/depends on//g' -e 's/[&_]//g' | tr A-Z a-z))
+
+ +

This will make apps/myapp/Kconfig the +canonical source of your dependency information.

+ +
+

Why do I need to pick which libraries get built when this is +determined by my application’s dependencies? Why does deslecting +libraries hide the applications that depend on them?

+ +

This is related to the question above. These options exist in Kconfig so +you can build libraries in isolation from any applications that depend +on them. In general this is not something you want to do, but there are +cases where we do need this functionality available. When you deselect +an item in Kconfig it hides all the items that depend on that item. If +this is not the behaviour you want you should consider using a select +clause instead of a depends on clause.

+ +

Be aware that while select and depends on can express the same +dependency relationship that will correctly apply transitively, they do +not play well together. An automated selection caused by a select will +not take depends on clauses into account and automatic deselection +caused by depends on will not take select clauses into account. Used +exclusively however, either can be used in a given scenario. E.g. a +dependency of FOO on BAR, that depends on MOO can be expressed as:

+ +
config FOO
+    bool "foo"
+    depends on BAR
+
+config BAR
+    bool "bar"
+    depends on MOO
+
+config MOO
+    bool "moo"
+
+ +

or as:

+ +
config FOO
+    bool "foo"
+    select BAR
+
+config BAR
+    bool "bar"
+    select MOO
+
+config MOO
+    bool "moo"
+
+

The difference will be in the behaviour in menuconfig, not in the +actual dependency inferred by Kconfig.

+ +
+

How do I debug what the build system is doing?

+ +

Use make V=2 or make V=3. Be aware that V=3 generates a lot of output.

+ +
+

What is this $(call cc-option… business?

+ +

cc-option is defined in tools/kbuild/Kbuild.include. It is used as +$(call cc-option, flags1, flags2). It passes flags1 to your compiler +($(CC), not $(HOST_CC)) and returns flags1 if they are accepted. If +your compiler returns an error it returns flags2. It is basically a way +of probing what flags your compiler supports.

+ +
+

What is the difference between CFLAGS, HOSTCFLAGS and +NK_CFLAGS?

+ +

There are two compilers in the build system, CC and HOSTCC. CC is the +compiler that is used to build your project, while HOSTCC is the +compiler that is used to build the tools that are used to build your +project. HOSTCC is typically your operating system’s native GCC, while +CC is often a cross-compiler. The contents of HOSTCFLAGS are used when +invoking HOSTCC, while the other two FLAGS variables are used with CC. +The contents of CFLAGS is used when compiling the kernel. NK_CFLAGS +applies to applications and libraries. The terminology stems from Linux, +where there are kernel flags and Non-Kernel flags. To avoid confusion, +the build system treats CFLAGS and NK_CFLAGS identically in your +application/library Makefiles and you can modify either for the same +effect.

+ +
+

How do I dump the contents of Makefile variables? How do I +determine what context my rules are executed in?

+ +
$(foreach var,$(.VARIABLES),$(warning $(var)=$($(var))))
+
+ +
+

Why do some projects’ libs/Kbuild use a sel4libs-y variable?

+ +

This is hangover from a previous abstraction for portability. This extra +level of indirection serves no purpose in the current build system. If +you encounter a libs/Kbuild that looks like the following:

+
sel4libs-$(CONFIG_LIB_FOO) += libfoo
+sel4libs-$(CONFIG_LIB_BAR) += libbar
+...
+
+libs-y += $(sel4libs-y)
+...
+
+

please update it to remove sel4libs-y:

+
libs-$(CONFIG_LIB_FOO) += libfoo
+libs-$(CONFIG_LIB_BAR) += libbar
+...
+
+ +

What does it mean when I get errors like make[1]: *** No rule +to make target ‘-lfoo’, needed by `bar’. Stop.? Why is “-lfoo” a +target?

+ +

Library targets are automatically generated by the build system. This +error usually indicates that your apps/Kbuild or libs/Kbuild does not +correctly describe the dependencies for one of your targets.

+ +
+

Why is the documentation for Kbuild and Kconfig so poor?

+ +

Kbuild and Kconfig exist in the Linux kernel source tree. Attempts have +been made to separate them out and make them independent, but nothing +particularly successful has come from this. As a result the only +reliable and current source of documentation for both is in the Linux +kernel, where maintainers tend to have an attitude of “the source is the +documentation.” Most of the time the best way to determine +Kbuild/Kconfig behaviour is to try something and see what happens.

+ +
+

Why does the build system silently ignore typos in variable +names?

+ +

This is partly related to their origins from Kbuild and Kconfig and +partly a limitation of GNU Make. In many instances variables are +expanded in such a way that the system is provided with no feedback as +to whether the variable was undefined or whether it was set to nothing. +Either way, there’s not much to be done here other than pair program +your Makefiles.

+ +
+

Why do some items in menuconfig get indented for no apparent +reason? E.g. Twinkle library for seL4.

+ +

I have no idea. As near as I can tell it has something to do with the +starting character, but if you manage to get to the bottom of this +please fix.

+ +
+

When trying to compile libsel4muslcsys, why do I get errors like +fatal error: stdio.h: No such file or directory?

+ +

You likely have a configuration line in your libs/Kbuild that causes one +of libmuslc or libsel4muslcsys to depend on the other. In this file +neither should depend on the other.

+ +

There is a circular dependency between libmuslc and libsel4muslcsys. +This is known and intentional; libsel4muslcsys provides the backend seL4 +support for libmuslc’s functionality. This dependency should not be +expressed in the build system or you will experience compilation errors +like the above. When the build system is configured such that neither +library depends on each other, it will correctly stage the libc headers +that libsel4muslcsys is expecting to find and correctly link the symbol +references in libmuslc to the provided symbols in libsel4muslcsys.

+ +
+

I’m trying to do something unusual that is not natively supported +by the build system, so I added my own rules to apps/my_app/Makefile. +Now nothing seems to get built. What’s going on?

+ +

Adding custom rules is fine, but they need to come after the line where +you include common.mk

+ +

An app’s Makefile is invoked with no explicit target (make), so the +first target encountered is built. This is intended to be default, +supplied by common.mk, but if you introduce a rule before including this +file, your target supersedes default. As a side note, it is possibly +worth modifying the parent Makefile to directly call make default to +remove this gotcha.

+ +
+

Kbuild and Kconfig are GPL-ed. Does this mean the code I build with them is automatically GPL-ed?

+ +

No. This is a well-established issue, which has been dealt with in other +projects before. Using a GPL-ed build system or linking against GPL-ed +libraries does not force your project to be GPL-ed.

+ +
+

This build system is terrible. Why aren’t we using <insert some other build system>?

+ +

All build systems suck. The only thing worse than your current build +system is your future build system. Life goes on.</flamebait>

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/buildsystem/old/index.md b/projects/buildsystem/old/index.md deleted file mode 100644 index 9c9c1b013e7..00000000000 --- a/projects/buildsystem/old/index.md +++ /dev/null @@ -1,507 +0,0 @@ ---- -archive: true -redirect_from: - - /Developing/Building/OldBuildSystem -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Our old deprecated Build System - -_For the new build system see the [build system overview](../)._ - -## Anatomy of the Build System - The following files are the components -of a project repository that are part of the build system (as opposed to -code and tools related to the project): - -- **[.config](#config)** - Your current - configuration (auto-generated) -- **apps/** - - **[Kbuild](#appskbuild)** - Application targets and - dependencies - - **[Kconfig](#kconfig)** - Applications menu - - **myapp/** - - **[Kconfig](#kconfig)** - Myapp-specific settings - - **[Makefile](#appsmyappmakefile)** - How to build Myapp -- **configs/*** - Pre-made configurations for the project -- **[Kconfig](#kconfig)** - Top-level menu -- **kernel/Makefile** - How to build seL4 -- **libs/** - - **[Kbuild](#libskbuild)** - Library targets and - dependencies - - **[Kconfig](#kconfig)** - Libraries menu - - **libfoo/** - - **[Kconfig](#kconfig)** - Libfoo-specific settings - - **[Makefile](#libslibfoomakefile)** - How to build Libfoo - -- **[Makefile](#makefile)** - Top-level build specialisation -- **[Makefile.flags](#makefileflags)** - Top-level build - tuning -- **tools/common/** - - **[common.mk](#commonmk)** - Boiler plate for building - applications/libraries - - **[Kconfig](#kconfig)** - Menu options for toolchains - and other common settings - - **[project-arm.mk](#projectmk)** - ARM-specific boiler - plate for a top-level build - - **[project-ia32.mk](#projectmk)** - IA32-specific - boiler plate for a top-level build - - **[project.mk](#projectmk)** - - Architecture-independent boiler plate for a top-level build - - **[Makefile.flags](#makefileflags)** - Shared build - system tuning - - **kbuild/*** - Kbuild from the Linux source tree. For - documentation, refer to the Kbuild mailing list. - -### Build configuration - Prior to building a project you need to -specify a configuration (settings, components, etc.) that you want to -build. Kconfig is a tool for simplifying and automating this process. In -an seL4 project you can enter make menuconfig in the top level directory -to be presented with a terminal menu for choosing which components to -build. Note that you will need the package libncurses5-dev installed to -display terminal menus. It is possible to select a configuration without -using the terminal menus, but techniques for doing this are not -discussed on this page. - -The menu config interface - -Use arrow keys and Enter to navigate the menu, Space bar to -select/deselect items and Esc-Esc to return to the parent level in the -menu hierarchy. On exiting the menu system you will be asked whether you -wish to save your configuration. If you choose to do so it will be -written to the file .config in the top level directory. - -Many projects will have a default list of configurations for building -common scenarios. These are located in the configs/ directory. You can -load one of these by running make config_file where config_file is the -filename of the configuration you want to load. Whenever you load one of -these pre-made configurations it is usually wise to run make -silentoldconfig. This scans your project for configuration settings that -have changed since the pre-made configuration was created and updates -the configuration with the defaults of these changed settings. This is -not always what you want, but it generally works. - -Your current configuration is stored in the file .config. This file -looks like a Makefile fragment and that is actually exactly how it is -used by build system when it comes time to build your project. One -gotcha to be aware of is that the comments in this file aren't -completely comments, which you will find out if you try to edit them. -Kconfig parses these comments and will throw all manner of strange -errors if it thinks one is malformed. - -Pre-made configurations are stored in configs/. To make a new -configuration, pick the settings you want in the menus then copy your -.config to configs/. Note that all the configurations in this directory -must end in \_defconfig for the build system to identify them correctly. - -The other file(s) you will want to care about is Kconfig. These files -tell Kconfig how to construct the menu hierarchy. A formal description -of the Kconfig options and syntax can be found at -. -Symbols are defined by using the 'config' statement. These symbols are -given the prefix 'CONFIG_' when the configuration is written to the -.config file. - -#### .config -**.config** is autogenerated by running -make some_default_config or make menuconfig. In general, you shouldn't -modify this file manually, but the syntax is pretty obvious if you want -to. As noted below, it is not recommended to touch the comments in this -file. They are parsed by the build system and "malformed" comments can -cause strange and mysterious errors. - -#### apps/Kbuild -**apps/Kbuild** needs to fill the -apps-y variable with the targets of the applications to be built. To do -this you can reference the CONFIG_-prefixed variables from Kconfig. A -typical apps/Kbuild will look something like the following: -```make -apps-$(CONFIG_MY_APP) += myapp - -hello: libfoo -``` -If your application has more complicated dependencies, -for example if it depends on libbar only when the -MYAPP_EXTRA_FUNCTIONALITY variable is selected, you can use the -following pattern: -```make -apps-$(CONFIG_MY_APP) += myapp - -hello-y = libfoo -hello-$(CONFIG_MYAPP_EXTRA_FUNCTIONALITY) += libbar -hello: $(hello-y) -``` - -#### Kconfig -The Kconfig files (**Kconfig, -apps/Kconfig, apps/myapp/Kconfig, libs/Kconfig, libs/libfoo/Kconfig, -tools/common/Kconfig**) describe the structure of the menu you are -presented with when you type make menuconfig. The syntax of these files -is described at - and -they are broken up in the obvious way; that is, apps/Kconfig contains -settings common to all applications in your project, libs/libfoo/Kconfig -contains settings specific to libfoo, ... The Kconfig files together -determine the build configuration process that is described in more -detail below. - -#### apps/myapp/Makefile - -Your application Makefile, -**apps/myapp/Makefile**, should populate a set of variables and then -include common.mk. It will typically look something like the following: -```make -TARGETS := $(notdir $(SOURCE_DIR)).bin - -CFILES := $(patsubst $(SOURCE_DIR)/%,%,$(wildcard $(SOURCE_DIR)/src/*.c)) -ASMFILES := $(patsubst $(SOURCE_DIR)/%,%,$(wildcard $(SOURCE_DIR)/crt/arch-$(ARCH)/crt0.S)) - -LIBS := sel4c sel4 sel4rootserver sel4platsupport - -include $(SEL4_COMMON)/common.mk -``` -TARGETS should contain the list -of output files that this application needs built. CFILES and ASMFILES -list the C and assembly sources of your application, respectively. LIBS -lists the libraries this application will be linked against (without -their "lib" prefix). You can also use your Makefile to modify the flags -that are passed to the compiler or the linker when building your -application. To do this, modify the variables CFLAGS and LDFLAGS, -respectively. For example, you can use "LDFLAGS += -T -path/to/linker.lds" to use a custom linker script for your application -or "CFLAGS := $(filter-out -Wall,$(CFLAGS))" to turn off compiler -warnings for your application. Note that these modifications should be -added **after** including common.mk. - -#### libs/Kbuild -Like apps/Kbuild describes top-level -application dependencies, **libs/Kbuild** describes top-level library -dependencies. Similarly, it fills the variable libs-y with the libraries -to be built. A typical libs/Kbuild would look like: -```make -libs-$(CONFIG_LIB_FOO) += libfoo -libs-$(CONFIG_LIB_BAR) += libbar - -libfoo: common -libbar: common libfoo -``` - -#### libs/libfoo/Makefile -The Makefile for a particular -library, **libs/libfoo/Makefile**, should just contain some variable -configuration and then include common.mk. Note that by using generic -environment variables you can often use the following template with no -modification for your library: -```make -# Library archive(s) that will be built. -TARGETS := $(notdir ${SOURCE_DIR}).a - -# Source files required to build the target. -CFILES := $(patsubst $(SOURCE_DIR)/%,%,$(wildcard ${SOURCE_DIR}/src/*.c)) -ASMFILES := $(patsubst $(SOURCE_DIR)/%,%,$(wildcard ${SOURCE_DIR}/src/*.S)) - -# Header files/directories this library provides. -HDRFILES := $(wildcard ${SOURCE_DIR}/include/*) - -include $(SEL4_COMMON)/common.mk -``` - -You can modify the compiler or linker flags applied when building your -library by modifying the NK_CFLAGS or NK_LDFLAGS variable -respectively. The process for doing this is identical to that for -apps/myapp/Makefile described above. - -#### Makefile -Something that may be unexpected at -first is that you don't need to provide any project-specific targets in -your top-level Makefile. Generally this file just needs to make -app-images the default target and include project.mk. It's possible you -may want to override the default (by defining a target before including -project.mk) or provide some external targets of your own (after -including project.mk). You will most likely just want to mimic the -content of the file from the reference examples: -```make -# app-images is provided in project.mk. -all: app-images - -include tools/common/project.mk - -# Extra project-specific targets. simulate-kzm: -qemu-arm -nographic -M kzm -kernel images/hello-image-arm-imx31 -``` - -#### project.mk -**tools/common/project.mk** contains -some generic targets and supporting infrastructure for building the -various components of your system. It is from this Makefile that the -application and library Makefiles are invoked. The architecture specific -elements of this are contained in **tools/common/project-arm.mk** and -**tools/common/project-ia32.mk**. Your top-level Makefile should -import tools/common/project.mk to take advantage of the build system -support. - -#### common.mk -**tools/common/common.mk** is the -equivalent of tools/common/project.mk for the application-/library-level -compilation (as opposed to top-level). This probably won't make much -sense unless you are familiar with the two-stage build process that is -being invoked when you type "make", but you generally won't need to -concern yourself with the inner workings of this file anyway. This file -contains a collection of generic compiler flags and targets shared -between all projects. It has evolved over time (in some instances in -response to bugs in toolchains), so it is possible there are sections of -this file that are deprecated. If you find something incorrect or -deprecated feel free to correct or modify it, but be aware that even -seemingly innocuous changes to this file are quite likely to break other -people's builds. - -#### Makefile.flags -**Makefile.flags** and -**tools/common/Makefile.flags** contain a set of options that are -applied globally at the top level. These generally contain -compiler-specific options to discriminate between your target platforms. -The shared settings in tools/common/Makefile.flags should be more than -sufficient for most projects, but projects with more esoteric build -requirements may need to use Makefile.flags to override or extend the -shared settings. Most projects will have an empty Makefile.flags because -there is almost always a more appropriate place to put an override. - -# Build Execution - **Note:** ''If you are accustomed to Kbuild from -the Linux kernel, note that we do not use Kbuild in the same way it is -used in Linux. In particular, components are built with their own -Makefiles, not with the Kbuild generic targets that build object files -at a directory-level granularity. It is best not to assume any behaviour -you may be familiar with from Kbuild.'' - -Where Kconfig handles the configuration of your build process, the -remainder of the build system manages dependencies and rules within a -build. The tools/Kbuild directory itself is a black hole of despair and -I would encourage you not to look in there unless you have a high -tolerance for pain. All other relevant files are covered above. - -## Frequently Asked Questions - **Why do I need to specify the same -list of dependencies in apps/myapp/Makefile, apps/Kbuild and -apps/myapp/Kconfig?** - -While these dependency lists appear to serve an identical function, they -actually do not. apps/myapp/Makefile defines the contents of LIBS to be -the libraries that your application is linked against. apps/Kbuild -defines the dependencies (libraries or otherwise) of your applications. -apps/myapp/Kconfig defines the dependency structure of Kconfig menu -items that may or may not map to build targets. In practice, most of our -use cases have an identical list for these three, but they have been -kept separate to allow a finer grained control over the build system -when necessary. - -If this really is a serious irritation to you and your dependencies -really are the same in all three places, you can replace your dependency -line in apps/Kbuild with: -```make -myapp: $(shell grep "depends on" $(APPS_ROOT)/myapp/Kconfig | sed -e 's/depends on//g' -e 's/[&_]//g' | tr A-Z a-z) -``` -and your LIBS line in -apps/myapp/Makefile with: -```make -LIBS := $(patsubst lib%,%,$(shell grep "depends on" $(SOURCE_DIR)/Kconfig | sed -e 's/depends on//g' -e 's/[&_]//g' | tr A-Z a-z)) -``` - -This will make apps/myapp/Kconfig the -canonical source of your dependency information. - ----- -**Why do I need to pick which libraries get built when this is -determined by my application's dependencies? Why does deslecting -libraries hide the applications that depend on them?** - -This is related to the question above. These options exist in Kconfig so -you can build libraries in isolation from any applications that depend -on them. In general this is not something you want to do, but there are -cases where we do need this functionality available. When you deselect -an item in Kconfig it hides all the items that depend on that item. If -this is not the behaviour you want you should consider using a select -clause instead of a depends on clause. - -Be aware that while select and depends on can express the same -dependency relationship that will correctly apply transitively, they do -not play well together. An automated selection caused by a select will -not take depends on clauses into account and automatic deselection -caused by depends on will not take select clauses into account. Used -exclusively however, either can be used in a given scenario. E.g. a -dependency of FOO on BAR, that depends on MOO can be expressed as: - -``` -config FOO - bool "foo" - depends on BAR - -config BAR - bool "bar" - depends on MOO - -config MOO - bool "moo" -``` - -or as: - -``` -config FOO - bool "foo" - select BAR - -config BAR - bool "bar" - select MOO - -config MOO - bool "moo" -``` -The difference will be in the behaviour in menuconfig, not in the -actual dependency inferred by Kconfig. - ----- -**How do I debug what the build system is doing?** - -Use make V=2 or make V=3. Be aware that V=3 generates a lot of output. - ----- -**What is this $(call cc-option... business?** - -cc-option is defined in tools/kbuild/Kbuild.include. It is used as -$(call cc-option, flags1, flags2). It passes flags1 to your compiler -($(CC), not $(HOST_CC)) and returns flags1 if they are accepted. If -your compiler returns an error it returns flags2. It is basically a way -of probing what flags your compiler supports. - ----- -**What is the difference between CFLAGS, HOSTCFLAGS and -NK_CFLAGS?** - -There are two compilers in the build system, CC and HOSTCC. CC is the -compiler that is used to build your project, while HOSTCC is the -compiler that is used to build the tools that are used to build your -project. HOSTCC is typically your operating system's native GCC, while -CC is often a cross-compiler. The contents of HOSTCFLAGS are used when -invoking HOSTCC, while the other two FLAGS variables are used with CC. -The contents of CFLAGS is used when compiling the kernel. NK_CFLAGS -applies to applications and libraries. The terminology stems from Linux, -where there are kernel flags and Non-Kernel flags. To avoid confusion, -the build system treats CFLAGS and NK_CFLAGS identically in your -application/library Makefiles and you can modify either for the same -effect. - ----- -**How do I dump the contents of Makefile variables? How do I -determine what context my rules are executed in?** - -```make -$(foreach var,$(.VARIABLES),$(warning $(var)=$($(var)))) -``` - ----- -**Why do some projects' libs/Kbuild use a sel4libs-y variable?** - -This is hangover from a previous abstraction for portability. This extra -level of indirection serves no purpose in the current build system. If -you encounter a libs/Kbuild that looks like the following: -```make -sel4libs-$(CONFIG_LIB_FOO) += libfoo -sel4libs-$(CONFIG_LIB_BAR) += libbar -... - -libs-y += $(sel4libs-y) -... -``` -please update it to remove sel4libs-y: -```make -libs-$(CONFIG_LIB_FOO) += libfoo -libs-$(CONFIG_LIB_BAR) += libbar -... -``` - -**What does it mean when I get errors like make[1]: *** No rule -to make target '-lfoo', needed by \`bar'. Stop.? Why is "-lfoo" a -target?** - -Library targets are automatically generated by the build system. This -error usually indicates that your apps/Kbuild or libs/Kbuild does not -correctly describe the dependencies for one of your targets. - ----- -**Why is the documentation for Kbuild and Kconfig so poor?** - -Kbuild and Kconfig exist in the Linux kernel source tree. Attempts have -been made to separate them out and make them independent, but nothing -particularly successful has come from this. As a result the only -reliable and current source of documentation for both is in the Linux -kernel, where maintainers tend to have an attitude of "the source is the -documentation." Most of the time the best way to determine -Kbuild/Kconfig behaviour is to try something and see what happens. - ----- -**Why does the build system silently ignore typos in variable -names?** - -This is partly related to their origins from Kbuild and Kconfig and -partly a limitation of GNU Make. In many instances variables are -expanded in such a way that the system is provided with no feedback as -to whether the variable was undefined or whether it was set to nothing. -Either way, there's not much to be done here other than pair program -your Makefiles. - ----- -**Why do some items in menuconfig get indented for no apparent -reason? E.g. Twinkle library for seL4.** - -I have no idea. As near as I can tell it has something to do with the -starting character, but if you manage to get to the bottom of this -please fix. - ----- -**When trying to compile libsel4muslcsys, why do I get errors like -fatal error: stdio.h: No such file or directory?** - -You likely have a configuration line in your libs/Kbuild that causes one -of libmuslc or libsel4muslcsys to depend on the other. In this file -neither should depend on the other. - -There is a circular dependency between libmuslc and libsel4muslcsys. -This is known and intentional; libsel4muslcsys provides the backend seL4 -support for libmuslc's functionality. This dependency should not be -expressed in the build system or you will experience compilation errors -like the above. When the build system is configured such that neither -library depends on each other, it will correctly stage the libc headers -that libsel4muslcsys is expecting to find and correctly link the symbol -references in libmuslc to the provided symbols in libsel4muslcsys. - ----- -**I'm trying to do something unusual that is not natively supported -by the build system, so I added my own rules to apps/my_app/Makefile. -Now nothing seems to get built. What's going on?** - -Adding custom rules is fine, but they need to come after the line where -you include common.mk - -An app's Makefile is invoked with no explicit target (make), so the -first target encountered is built. This is intended to be default, -supplied by common.mk, but if you introduce a rule before including this -file, your target supersedes default. As a side note, it is possibly -worth modifying the parent Makefile to directly call make default to -remove this gotcha. - ----- -**Kbuild and Kconfig are GPL-ed. Does this mean the code I build with them is automatically GPL-ed?** - -No. This is a well-established issue, which has been dealt with in other -projects before. Using a GPL-ed build system or linking against GPL-ed -libraries does not force your project to be GPL-ed. - ----- -**This build system is terrible. Why aren't we using \?** - -All build systems suck. The only thing worse than your current build -system is your future build system. Life goes on. diff --git a/projects/buildsystem/repo-cheatsheet.html b/projects/buildsystem/repo-cheatsheet.html new file mode 100644 index 00000000000..cadee5dfdfd --- /dev/null +++ b/projects/buildsystem/repo-cheatsheet.html @@ -0,0 +1,766 @@ + + + + + + + Repo Cheatsheet | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Repo Cheatsheet

+ +

Repo is a tool developed by the Android Open Source Project. We use repo for source dependency management.

+ +

This page describes how we typically structure our manifests and also explains some common repo commands that we use in our workflows.

+ +

Below is a set of example manifests for the sel4test project. They are located at https://github.com/seL4/sel4test-manifest/.

+ +
    +
  • common.xml:
    • +
+ +
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+     Copyright 2018, Data61, CSIRO
+     SPDX-License-Identifier: BSD-2-Clause
+-->
+<manifest>
+<remote name="seL4" fetch="." />
+<remote fetch="../sel4proj" name="sel4proj"/>
+<remote fetch="https://github.com/nanopb" name="nanopb" />
+<remote fetch="https://github.com/riscv" name="opensbi"/>
+
+<default revision="master" remote="seL4" />
+
+<project name="seL4_tools.git" path="tools/seL4">
+    <linkfile src="cmake-tool/init-build.sh" dest="init-build.sh"/>
+    <linkfile src="cmake-tool/griddle" dest="griddle"/>
+</project>
+<project name="sel4runtime.git" path="projects/sel4runtime"/>
+<project name="musllibc.git" path="projects/musllibc" revision="sel4"/>
+<project name="seL4_libs.git" path="projects/seL4_libs"/>
+<project name="util_libs.git" path="projects/util_libs"/>
+<project name="sel4test.git" path="projects/sel4test">
+    <linkfile src="easy-settings.cmake" dest="easy-settings.cmake"/>
+</project>
+<project name="sel4_projects_libs" path="projects/sel4_projects_libs" />
+<project name="opensbi" remote="opensbi" revision="refs/tags/v0.8" path="tools/opensbi"/>
+<project name="nanopb" path="tools/nanopb" revision="refs/tags/0.4.3" upstream="master" remote="nanopb"/>
+</manifest>
+
+ +
    +
  • master.xml:
    • +
+ +
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+     Copyright 2018, Data61, CSIRO
+     SPDX-License-Identifier: BSD-2-Clause
+-->
+<manifest>
+<!-- include all the common repositories, we just want to define the kernel -->
+<include name="common.xml"/>
+<project name="seL4.git" path="kernel"/>
+</manifest>
+
+ +

Manifest layout

+ +

We provide a brief overview of manifests as used in our projects in this section, please find more details in the full description of the manifest layout which can be found here.

+ +
+

<remote name="seL4" fetch="." />

+
+ +

The remote element specifies a remote where git repositories can be found.

+ +
+

<project name="musllibc.git" remote="seL4" path="projects/musllibc" revision="sel4"/>

+
+ +

The project element declares a repository.

+
    +
  • name is the repository name at the remote
    • +
  • path is the repository checkout location relative to the directory the project was initialised in.
    • +
  • revision specifies what version of the repository to use. Branches and revision hashes are supported. Tags are supported but the attribute value must be structured as refs/tags/tagname.
    • +
  • linkfile element specifies a symlink from the repository to somewhere else in the project layout. +
      +
    • src is a path relative to the repository checkout.
      • +
    • dest is a path relative to the project directory.
      • +
    +
    • +
+ +
+

<default revision="master" remote="seL4"/>

+
+ +

The default element specifies attribute defaults that may be ommitted from project elements. +If attributes are ommitted, the values from the default element will be used instead.

+ +

Pinned manifests

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+   Copyright 2021 seL4 Project a Series of LF Projects, LLC
+   SPDX-License-Identifier: BSD-2-Clause
+-->
+<manifest>
+  <remote name="nanopb" fetch="https://github.com/nanopb"/>
+  <remote name="opensbi" fetch="https://github.com/riscv"/>
+  <remote name="seL4" fetch="."/>
+  <remote name="sel4proj" fetch="../sel4proj"/>
+
+  <default remote="seL4" revision="master"/>
+
+  <project name="musllibc.git" path="projects/musllibc" revision="aa82031dd861f7ade4c3738b417de34120b01f15" upstream="sel4" dest-branch="sel4"/>
+  <project name="nanopb" path="tools/nanopb" remote="nanopb" revision="1466e6f953835b191a7f5acf0c06c941d4cd33d9" upstream="master" dest-branch="refs/tags/0.4.3"/>
+  <project name="opensbi" path="tools/opensbi" remote="opensbi" revision="a98258d0b537a295f517bbc8d813007336731fa9" upstream="refs/tags/v0.8" dest-branch="refs/tags/v0.8"/>
+  <project name="seL4.git" path="kernel" revision="a6c29549fce33df65b9018f420d330bca9086712" upstream="master" dest-branch="master"/>
+  <project name="seL4_libs.git" path="projects/seL4_libs" revision="14d3c94f5164c993033a35a5d9e23ba6dcf12f5f" upstream="master" dest-branch="master"/>
+  <project name="seL4_tools.git" path="tools/seL4" revision="553086aab4c9fb9c4869060fe51a3e95c20ce454" upstream="master" dest-branch="master">
+    <linkfile src="cmake-tool/init-build.sh" dest="init-build.sh"/>
+    <linkfile src="cmake-tool/griddle" dest="griddle"/>
+  </project>
+  <project name="sel4_projects_libs" path="projects/sel4_projects_libs" revision="a6fbc13c792ef518e5bcf1da69c8d27b6cd19814" upstream="master" dest-branch="master"/>
+  <project name="sel4runtime.git" path="projects/sel4runtime" revision="c27050513503f615137950cb3918f6f040f34407" upstream="master" dest-branch="master"/>
+  <project name="sel4test.git" path="projects/sel4test" revision="110ad99b32cb94f0604ce9fef796164b595fe6aa" upstream="master" dest-branch="master">
+    <linkfile src="easy-settings.cmake" dest="easy-settings.cmake"/>
+  </project>
+  <project name="util_libs.git" path="projects/util_libs" revision="280f7bb58290ea3d719d86894655a03f36d347e2" upstream="master" dest-branch="master"/>
+</manifest>
+
+ +

A pinned manifest uses pinned git revisions for all of its repositories. It is good practice to create a pinned manifest that refers to a working version of a project. For projects that we maintain, we provide at least two manifests: default.xml and master.xml See the Releases page for more information about what manifests we make available.

+ +

Commands

+ +

init and sync

+ +

repo init and repo sync are the most commonly used commands. Their purpose is for selecting a manifest and downloading all of the repositories and setting up a project directory structure. Often project READMEs will provide the following instructions:

+
mkdir source_dir
+cd source_dir
+repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+
+ +

This will initialise a new directory with the git repos checked out in the locations described by the manifest file.

+ +

init is for selecting a manifest to use, and sync is for checking out that manifest.

+ +

init

+
    +
  • -u git url. Note: GitHub ssh urls do not work using the generated URL they provide: git@github.com:seL4/sel4test-manifest.git has to be changed to ssh://git@github.com/seL4/sel4test-manifest.git
    • +
  • -m manifest name, default is default.xml.
    • +
  • -b branch or revision, or tag if using format refs/tags/tagname. Default is default.xml
    • +
+ +

sync

+ +

This command synchronises your project directory with what the manifest describes. If you have made commits in your branches, this may result in them getting lost as repo switches the HEAD back to what the manifest describes. If this happens, use git reflog to find the untracked commit, or use branches to keep track of commits as branches will remain in your local checkouts.

+ +

sync has several flags for specifying how to checkout from remotes such as -j for parallel checkouts. Use repo sync --help for a list and description.

+ +

diff and status

+ +

These two commands are similar to running git diff or git status in every git repository.

+ +

diffmanifests

+ +

This command allows you to list the commit differences between two manifests of the same project.

+ +
changed projects :
+
+        kernel changed from master to 757c3ac98246afd0593367f1fa19054316a77495
+                [-] 62445b35 x86: Correct labels for port out operations
+                [-] d9780ec7 manual: label object groups in parse_doxygen_xml.py
+                [-] 63c5ac6d manual: use level 3 for syscalls
+                [-] deba85b2 manual: promote sel4_arch API docs level
+                [-] b5ee12f0 manual: group generated API methods by object type
+                [-] da1e73fe manual: use int level in parse_doxygen_xml.py
+                [-] c2212688 x86: IOPort invocation has proper structure
+                [-] 7b8f6106 x86: Consistently compare against PPTR_USER_TOP
+                [-] 1b0a7181 manual: s/Polling Send/Non-Blocking Send
+                [-] 84b065b0 manual: use fontenc package
+
+        projects/tools changed from master to 930b6467eae8404e4a72555b693120ac0d64fc48
+                [-] 121782a CMake add error condition
+
+
+ +

FAQ

+ +

How do I check out a released version of a project such as seL4test?

+ +
+ + 
repo init -u https://github.com/seL4/sel4test-manifest.git -b refs/tags/
+repo sync
+
+
+ +

How do I change manifests of an already checked out project?

+ +
+ + 
repo init -m master.xml
+repo sync
+
+
+ +

This will change from the current manifest to master.xml in the manifest repository

+ +

How do I create a pinned manifest?

+ +
+ + 
repo manifest -r -o pinned.xml
+
+
+ +

Is there a faster way to checkout and sync a project?

+
+ + 
repo init -u https://github.com/seL4/sel4test-manifest.git --no-clone-bundle --depth=1
+repo sync --jobs=8 --fetch-submodules --current-branch --no-clone-bundle
+
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/buildsystem/repo-cheatsheet.md b/projects/buildsystem/repo-cheatsheet.md deleted file mode 100644 index 114856d8077..00000000000 --- a/projects/buildsystem/repo-cheatsheet.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -redirect_from: - - /RepoCheatsheet -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Repo Cheatsheet - -Repo is a tool developed by the Android Open Source Project. We use repo for source dependency management. - -This page describes how we typically structure our manifests and also explains some common repo commands that we use in our workflows. - -Below is a set of example manifests for the sel4test project. They are located at . - -- `common.xml`: - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -- `master.xml`: - -```xml - - - - - - - -``` - - -## Manifest layout - -We provide a brief overview of manifests as used in our projects in this section, please find more details in the full description of the manifest layout which can be found [here](https://gerrit.googlesource.com/git-repo/+/master/docs/manifest-format.md). - -> `` - -The `remote` element specifies a remote where git repositories can be found. - -> `` - -The `project` element declares a repository. -- `name` is the repository name at the `remote` -- `path` is the repository checkout location relative to the directory the project was initialised in. -- `revision` specifies what version of the repository to use. Branches and revision hashes are supported. Tags are supported but the attribute value must be structured as `refs/tags/tagname`. -- `linkfile` element specifies a symlink from the repository to somewhere else in the project layout. - - `src` is a path relative to the repository checkout. - - `dest` is a path relative to the project directory. - -> `` - -The `default` element specifies attribute defaults that may be ommitted from `project` elements. -If attributes are ommitted, the values from the default element will be used instead. - -### Pinned manifests - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -A pinned manifest uses pinned git revisions for all of its repositories. It is good practice to create a pinned manifest that refers to a working version of a project. For projects that we maintain, we provide at least two manifests: default.xml and master.xml See the [Releases](../../releases.html) page for more information about what manifests we make available. - -## Commands - -### `init` and `sync` - -`repo init` and `repo sync` are the most commonly used commands. Their purpose is for selecting a manifest and downloading all of the repositories and setting up a project directory structure. Often project READMEs will provide the following instructions: -``` -mkdir source_dir -cd source_dir -repo init -u https://github.com/seL4/sel4test-manifest.git -repo sync -``` - -This will initialise a new directory with the git repos checked out in the locations described by the manifest file. - -init is for selecting a manifest to use, and sync is for checking out that manifest. - -`init` -- `-u` git url. Note: GitHub `ssh` urls do not work using the generated URL they provide: `git@github.com:seL4/sel4test-manifest.git` has to be changed to `ssh://git@github.com/seL4/sel4test-manifest.git` -- `-m` manifest name, default is default.xml. -- `-b` branch or revision, or tag if using format `refs/tags/tagname`. Default is default.xml - -`sync` - -This command synchronises your project directory with what the manifest describes. If you have made commits in your branches, this may result in them getting _lost_ as repo switches the HEAD back to what the manifest describes. If this happens, use `git reflog` to find the untracked commit, or use branches to keep track of commits as branches will remain in your local checkouts. - -`sync` has several flags for specifying how to checkout from remotes such as `-j` for parallel checkouts. Use `repo sync --help` for a list and description. - -### `diff` and `status` - -These two commands are similar to running git diff or git status in every git repository. - - -### `diffmanifests` - -This command allows you to list the commit differences between two manifests of the same project. - -``` -changed projects : - - kernel changed from master to 757c3ac98246afd0593367f1fa19054316a77495 - [-] 62445b35 x86: Correct labels for port out operations - [-] d9780ec7 manual: label object groups in parse_doxygen_xml.py - [-] 63c5ac6d manual: use level 3 for syscalls - [-] deba85b2 manual: promote sel4_arch API docs level - [-] b5ee12f0 manual: group generated API methods by object type - [-] da1e73fe manual: use int level in parse_doxygen_xml.py - [-] c2212688 x86: IOPort invocation has proper structure - [-] 7b8f6106 x86: Consistently compare against PPTR_USER_TOP - [-] 1b0a7181 manual: s/Polling Send/Non-Blocking Send - [-] 84b065b0 manual: use fontenc package - - projects/tools changed from master to 930b6467eae8404e4a72555b693120ac0d64fc48 - [-] 121782a CMake add error condition - -``` - -## FAQ - -### How do I check out a released version of a project such as seL4test? - -> -``` -repo init -u https://github.com/seL4/sel4test-manifest.git -b refs/tags/{{site.sel4_master}} -repo sync -``` - -### How do I change manifests of an already checked out project? - -> -``` -repo init -m master.xml -repo sync -``` - -This will change from the current manifest to `master.xml` in the manifest repository - -### How do I create a pinned manifest? - -> -``` -repo manifest -r -o pinned.xml -``` - -### Is there a faster way to checkout and sync a project? -> -``` -repo init -u https://github.com/seL4/sel4test-manifest.git --no-clone-bundle --depth=1 -repo sync --jobs=8 --fetch-submodules --current-branch --no-clone-bundle -``` diff --git a/projects/buildsystem/standalone.html b/projects/buildsystem/standalone.html new file mode 100644 index 00000000000..4dfb574f252 --- /dev/null +++ b/projects/buildsystem/standalone.html @@ -0,0 +1,693 @@ + + + + + + + Standalone seL4 builds | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Standalone seL4 builds

+ +

This page contains documentation for building the seL4 kernel as a standalone +binary without any user-level system image or any loaders that run before the +kernel. This is typically used when a project wants to fully control the +user-level image and pre-kernel initialisation. The only standalone kernel +builds the seL4 Foundation currently maintains are for verified configurations. +This page assumes familiarity with using cmake.

+ +
+
+ + Note +
+
+ +

This text assumes that you know what to do with a generated kernel.elf binary. +For an explanation see at the bottom of the page.

+ +
+
+ +

Building a kernel standalone

+ +

Initialising build directory with existing configuration

+ +

Building the kernel standalone requires initialising a CMake build directory +using the seL4 repo as the root CMake project:

+ +
├── seL4/
+│   └── CMakeLists.txt
+├── build/
+
+ +

The build directory is initialised as follows:

+ +
cd build/
+cmake -DCROSS_COMPILER_PREFIX= -DCMAKE_TOOLCHAIN_FILE=../seL4/gcc.cmake -G Ninja -C ../seL4/configs/X64_verified.cmake ../seL4/
+
+ +

The example uses the X64_verified.cmake file for configuration values.

+ +

To find available verified configurations:

+ +
ls ../seL4/configs/*.cmake
+# ../seL4/configs/ARM_HYP_verified.cmake  ../seL4/configs/X64_verified.cmake
+# etc
+
+ +

A typical verified configuration (cat ../seL4/configs/X64_verified.cmake):

+ +
#!/usr/bin/env -S cmake -P
+#
+# Copyright 2020, Data61, CSIRO (ABN 41 687 119 230)
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+# If this file is executed then build the kernel.elf and kernel_all_pp.c file
+include(${CMAKE_CURRENT_LIST_DIR}/../tools/helpers.cmake)
+cmake_script_build_kernel()
+
+set(KernelPlatform "pc99" CACHE STRING "")
+set(KernelSel4Arch "x86_64" CACHE STRING "")
+set(KernelVerificationBuild ON CACHE BOOL "")
+set(KernelMaxNumNodes "1" CACHE STRING "")
+set(KernelOptimisation "-O2" CACHE STRING "")
+set(KernelRetypeFanOutLimit "256" CACHE STRING "")
+set(KernelBenchmarks "none" CACHE STRING "")
+set(KernelDangerousCodeInjection OFF CACHE BOOL "")
+set(KernelFastpath ON CACHE BOOL "")
+set(KernelPrinting OFF CACHE BOOL "")
+set(KernelNumDomains 16 CACHE STRING "")
+set(KernelMaxNumBootinfoUntypedCap 166 CACHE STRING "")
+set(KernelRootCNodeSizeBits 19 CACHE STRING "")
+set(KernelMaxNumBootinfoUntypedCaps 50 CACHE STRING "")
+set(KernelFSGSBase "inst" CACHE STRING "")
+
+ +

At this point you could use ccmake . to browse the configuration.

+ +

Building the kernel target

+ +

To build the kernel target, run

+ +
ninja kernel.elf
+
+ +

Looking in the build directory:

+ +
ls
+# autoconf                            generated                           kernel_bf_gen_target_11_pbf_temp.c
+# build.ninja                         generated_prune                     kernel_bf_gen_target_111_pbf_temp.c
+# circular_includes_valid             kernel_all_copy.c                   kernel.elf
+# cmake_install.cmake                 kernel_all_pp_prune_wrapper_temp.c  libsel4
+# CMakeCache.txt                      kernel_all_pp_prune.c               linker_ld_wrapper_temp.c
+# CMakeFiles                          kernel_all.c                        linker.lds_pp
+# gen_config                          kernel_all.i
+# gen_headers                         kernel_bf_gen_target_1_pbf_temp.c
+
+ +

The kernel.elf can now be used in other build environments.

+ +
file kernel.elf
+# kernel.elf: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped
+
+ +

Note the directory gen_config/ which contains configuration info for this +build as .h, .json and .yaml files for use in further build stages or +other build systems.

+ +

Installing

+ +

The build directory contains many more artefacts than needed to use a standalone +kernel build.

+ +

If you have used -DCMAKE_INSTALL_PREFIX=<install dir> when configuring CMake +and then run cmake --install <build dir>, you can have all the install +artefacts placed in <install dir>. The directory structure is the following:

+ +
├── bin/
+│   └── kernel.elf
+├── libsel4/
+|   ├── include/
+|   |   └── ...
+|   |   └── kernel/
+|   |       └── ...
+|   |       └── gen_config.json
+|   └── src/
+
+ +

Why use stand alone build?

+ +

For CMake-based build environments, the standalone build is usually not needed.

+ +

However, the standalone build is useful when the kernel is being used in a +different environment that does not use CMake. One example for this is the +Microkit which comes with pre-built kernel binaries and config +information. Another example is the formal verification project which uses the +standalone build to produce the source and binary artefacts that the +verification is performed on.

+ +

Other use cases include projects that want to build a non-C root task, for +instance in the Rust support.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/buildsystem/standalone.md b/projects/buildsystem/standalone.md deleted file mode 100644 index 028257e8178..00000000000 --- a/projects/buildsystem/standalone.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -redirect_from: - - /Developing/Building/seL4Standalone -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Standalone seL4 builds - -This page contains documentation for building the seL4 kernel as a standalone -binary without any user-level system image or any loaders that run before the -kernel. This is typically used when a project wants to fully control the -user-level image and pre-kernel initialisation. The only standalone kernel -builds the seL4 Foundation currently maintains are for verified configurations. -This page assumes familiarity with using `cmake`. - -{% include note.html %} -This text assumes that you know what to do with a generated `kernel.elf` binary. -For an explanation see at the bottom of the page. -{% include endnote.html %} - -## Building a kernel standalone - -### Initialising build directory with existing configuration - -Building the kernel standalone requires initialising a CMake build directory -using the seL4 repo as the root CMake project: - -```none -├── seL4/ -│ └── CMakeLists.txt -├── build/ -``` - -The build directory is initialised as follows: - -```sh -cd build/ -cmake -DCROSS_COMPILER_PREFIX= -DCMAKE_TOOLCHAIN_FILE=../seL4/gcc.cmake -G Ninja -C ../seL4/configs/X64_verified.cmake ../seL4/ -``` - -The example uses the `X64_verified.cmake` file for configuration values. - -To find available verified configurations: - -```sh -ls ../seL4/configs/*.cmake -# ../seL4/configs/ARM_HYP_verified.cmake ../seL4/configs/X64_verified.cmake -# etc -``` - -A typical verified configuration (`cat ../seL4/configs/X64_verified.cmake`): - -```cmake -#!/usr/bin/env -S cmake -P -# -# Copyright 2020, Data61, CSIRO (ABN 41 687 119 230) -# -# SPDX-License-Identifier: GPL-2.0-only -# - -# If this file is executed then build the kernel.elf and kernel_all_pp.c file -include(${CMAKE_CURRENT_LIST_DIR}/../tools/helpers.cmake) -cmake_script_build_kernel() - -set(KernelPlatform "pc99" CACHE STRING "") -set(KernelSel4Arch "x86_64" CACHE STRING "") -set(KernelVerificationBuild ON CACHE BOOL "") -set(KernelMaxNumNodes "1" CACHE STRING "") -set(KernelOptimisation "-O2" CACHE STRING "") -set(KernelRetypeFanOutLimit "256" CACHE STRING "") -set(KernelBenchmarks "none" CACHE STRING "") -set(KernelDangerousCodeInjection OFF CACHE BOOL "") -set(KernelFastpath ON CACHE BOOL "") -set(KernelPrinting OFF CACHE BOOL "") -set(KernelNumDomains 16 CACHE STRING "") -set(KernelMaxNumBootinfoUntypedCap 166 CACHE STRING "") -set(KernelRootCNodeSizeBits 19 CACHE STRING "") -set(KernelMaxNumBootinfoUntypedCaps 50 CACHE STRING "") -set(KernelFSGSBase "inst" CACHE STRING "") -``` - -At this point you could use `ccmake .` to browse the configuration. - -### Building the kernel target - -To build the kernel target, run - -```sh -ninja kernel.elf -``` - -Looking in the build directory: - -```sh -ls -# autoconf generated kernel_bf_gen_target_11_pbf_temp.c -# build.ninja generated_prune kernel_bf_gen_target_111_pbf_temp.c -# circular_includes_valid kernel_all_copy.c kernel.elf -# cmake_install.cmake kernel_all_pp_prune_wrapper_temp.c libsel4 -# CMakeCache.txt kernel_all_pp_prune.c linker_ld_wrapper_temp.c -# CMakeFiles kernel_all.c linker.lds_pp -# gen_config kernel_all.i -# gen_headers kernel_bf_gen_target_1_pbf_temp.c -``` - -The `kernel.elf` can now be used in other build environments. - -```sh -file kernel.elf -# kernel.elf: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped -``` - -Note the directory `gen_config/` which contains configuration info for this -build as `.h`, `.json` and `.yaml` files for use in further build stages or -other build systems. - -## Installing - -The build directory contains many more artefacts than needed to use a standalone -kernel build. - -If you have used `-DCMAKE_INSTALL_PREFIX=` when configuring CMake -and then run `cmake --install `, you can have all the install -artefacts placed in ``. The directory structure is the following: - -```none -├── bin/ -│ └── kernel.elf -├── libsel4/ -| ├── include/ -| | └── ... -| | └── kernel/ -| | └── ... -| | └── gen_config.json -| └── src/ -``` - -## Why use stand alone build? - -For CMake-based build environments, the standalone build is usually not needed. - -However, the standalone build is useful when the kernel is being used in a -different environment that does not use CMake. One example for this is the -[Microkit](../microkit/) which comes with pre-built kernel binaries and config -information. Another example is the formal verification project which uses the -standalone build to produce the source and binary artefacts that the -verification is performed on. - -Other use cases include projects that want to build a non-C root task, for -instance in the [Rust support](../rust/). diff --git a/projects/buildsystem/using.html b/projects/buildsystem/using.html new file mode 100644 index 00000000000..84f2120412f --- /dev/null +++ b/projects/buildsystem/using.html @@ -0,0 +1,803 @@ + + + + + + + Configuring and building an seL4 project | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Configuring and building an seL4 project

+ +

This page contains documentation for how to interact with and build a project +that is using this build system. For new project development, see incorporating +the build system.

+ +

Basic build initialisation

+ +

In the root directory of an seL4 CMake-based project, first create a separate +build directory for the output binaries, then initialise CMake:

+ +
mkdir build
+cd build
+cmake -DCROSS_COMPILER_PREFIX=arm-linux-gnueabi- -DCMAKE_TOOLCHAIN_FILE=../kernel/gcc.cmake <OTHER_COMMAND_LINE_OPTIONS_HERE> -G Ninja ..
+
+ +

The components in the above invocation mean the following:

+ +
    +
  • -D defines a variable, in the form X=Y.
    • +
  • CROSS_COMPILER_PREFIX specifies the toolchain for cross-compilation, which +cannot be changed after build directory initialisation. For further details, +please see Cross Compiling below.
    • +
  • CMAKE_TOOLCHAIN_FILE which indicates that CMake should load the specified +file as a ‘toolchain’ file. A toolchain file sets up the C +compiler, linker etc. for building the project. In the example above we assume a +typical project layout where seL4 is in the kernel directory at the top +level. The gcc.cmake’ +file from the seL4 repository sets up C compilers and linkers using the +CROSS_COMPILER_PREFIX.
    • +
  • -G Ninja tells CMake to generate Ninja build scripts as opposed to GNU +Makefiles. Only Ninja scripts are supported by the kernel.
    • +
  • .. is the path to the top-level CMakeLists.txt file describing this + project, which in this case is placed in the root directory of the project.
    • +
+ +

We also provide a shorthand wrapping script which abstracts the above into a +shorter command:

+ +
../init-build -DCROSS_COMPILER_PREFIX=arm-linux-gnueabi- <COMMAND_LINE_OPTIONS_HERE>
+
+ +

After configuration, you can build the project by invoking ninja:

+ +
ninja
+
+ +

After the build has completed, the resulting binaries will be in the images/ +subdirectory.

+ +

Configuration

+ +

Types of Options

+ +

CMake has two types of configuration options:

+ +
    +
  • Boolean options, which are are either ON or OFF,
    • +
  • String options, which can be set to any value, subject to restrictions set +by the project authors.
    • +
+ +

String options can have ‘hints’, which specify can one of several fixed values. +CMake configuration editors respect these and provide a radio selection.

+ +

Selecting Options

+ +

Many projects have some degree of customisation available via configuration +options. Once the build directory is initialised, you can use the following +approaches to bring up a user-interface for option configuration:

+ +
    +
  • An ncurses based configuration:
    • +
+ +
ccmake .
+
+ +
    +
  • Graphical configuration:
    • +
+ +
cmake-gui .
+
+ +

In both cases the path . should resolve to the same directory used in the +build configuration.

+ +

Changing option values

+ +

Any changes to configuration options will not be reflected in the user interface +unless explicitly requested by using (c)onfigure, which may result in changes +to the options available. For example if option A depends on boolean option +B, A will not show up until B is enabled and (c)onfigure is used to +reprocess the CMake files.

+ +

To exit the configuration interface, use (g)enerate and exit or (q)uit +without generation. CMake will not permit generation if the configuration is +incomplete ((c)onfigure must be run and all options set).

+ +

To rebuild after changing configuration options, invoke ninja:

+ +
ninja
+
+ +

Initial configuration

+ +

Many of our projects support multiple configurations, where the following broad +approaches are used to present simple options to the user:

+ +
    +
  • CMake cache scripts: These files can assign initial values to a number of +configuration variables. By combining one or more of these you can configure +an entire system.
    • +
  • Meta configuration options: Meta configuration options are normally +passed as initial -DVAR=FOO command line arguments to CMake and will be +programatically inspected by projects’ CMake scripts to (re)configure the +system.
    • +
+ +

CMake cache scripts

+ +

CMake cache scripts provide subsets of preconfigured options, which allow the +user of a project to avoid manually setting each option. Cache scripts have the +file extension .cmake.

+ +

Projects may provide cache script files which each contain the cache settings +necessary to configure a single feature or option. By combining multiple +.cmake files, a project can be initialised in a specific way. Cache script +configurations are provided by passing -C <file> to cmake when initialising +the build directory. For example, given a typical project structure, one might +invoke cmake or init-build.sh with several of cache scripts as arguments.

+ +

Multiple cached scripts can be specified on the command line, although if the +same option is set twice only one value is used. Consider an example with +several cache scripts for setting the architecture details (arm.cmake, +x86.cmake) and for setting build options (debug.cmake, release.cmake). The +intended usage is that one architectural cache file is used, and one build +options file, as demonstrated below:

+ +
cmake -C../projects/awesome_project/configs/arm.cmake -C../projects/awesome_project/configs/debug.cmake -DCROSS_COMPILER_PREFIX=arm-linux-gnueabi- -DCMAKE_TOOLCHAIN_FILE=../kernel/gcc.cmake -G Ninja ..
+
+ +

While nothing prevents the usage of both arm.cmake and x86.cmake at the same +time, this does not make sense, and only one value for each option will be used. +For projects with multiple cache scripts, check which can be used together.

+ +

Meta configuration options

+ +

Some seL4 projects such as sel4test provide top-level variables which, used +across projects, have standardised behaviour. These options are as follows:

+ +
    +
  • -DPLATFORM=<YOUR_PREFERENCE>: Selects the target system for the resulting +binaries. Valid values for this variable are the first value (preceding the +semicolon) on each line of the config_choice directive for each +architecture: + +
    • +
  • -DRELEASE: Set to 0 or 1: Turning this off compiles a debug build. +Turning it on compiles the project without debugging features enabled.
    • +
  • -DVERIFICATION: Set to 0 or 1: This is used to generate the version of +the seL4 kernel source which is VERIFIABLE. This does not produce a binary +for the verified kernel platform.
    • +
  • -DSMP: Set to 0 or 1: Turns SMP (symmetric multiprocessing) support on or +off. By default it will enable support for up to 4 processors. To explicitly +set the maximum number of supported CPUs, try setting +-DKernelMaxNumNodes=<YOUR_PREFERENCE>.
    • +
  • -DSIMULATION: Set to 0 or 1: This produces a build of the project which + is suited for running in an emulator such as QEMU.
    • +
+ +

Both the seL4test and seL4bench projects follow this form.

+ +

sel4test example

+ +

For more information on configuring, building and running the sel4test +suite, please see the main page on +seL4test.

+ +

Cross compiling

+ +

Cross compilation refers to +compiling a program for a target machine which is different from the machine you +are using to compile the program.

+ +

Generally, in order to cross-compile, a separate compiler is required which +specifically targets the foreign machine.

+ +

For ARM-based targets

+ +

You can use the following command line options when when cross-compiling for an +ARM-based machine:

+ +
    +
  • -DAARCH32=TRUE: Tells the build system that you are building for a 32-bit +ARM target. This will cause the build system to assume that you have a +cross compiler installed which targets a system with the triplet name +arm-linux-gnueabi-.
    • +
  • -DAARCH32HF=TRUE: Tells the build system you’re building for a 32-bit ARM +target which has hardware floating point support. Assumes you have a cross- +compiler installed which targets arm-linux-gnueabihf-.
    • +
  • -DAARCH64=TRUE: Tells the build system you’re building for a 64-bit ARM +target. Assumes you have a cross-compiler installed which targets +aarch64-linux-gnu-.
    • +
+ +

Another option is to explicitly specify the toolchain through +-DCROSS_COMPILER_PREFIX, which can be used to set the prefix of the +cross-compiler to use.

+ +

For RISC-V based targets

+ +

You can use the following options when cross compiling for a RISC-V target:

+ +
    +
  • -DRISCV32=TRUE: Tells the build system that you are building for a 32-bit RISC-V +target. This will cause the build system to assume that you have a cross- +compiler installed which targets a system with the triplet name +riscv32-unknown-elf-.
    • +
  • -DRISCV64=TRUE: Tells the build system you’re building for a 64-bit RISC-V +target. Assumes you have a cross-compiler installed which targets +riscv64-unknown-elf-.
    • +
+ +

Like ARM, you can explicitly specify the toolchain through +-DCROSS_COMPILER_PREFIX, which can be used to set the prefix of the +cross-compiler to use.

+ +

CMAKE_BUILD_TYPE

+ +

The CMAKE_BUILD_TYPE option appears in CMake configuration editors and allows +users to configure that build type (release, debug etc.). Note that this option +is not respected by the seL4 kernel.

+ +

Building with Clang

+ +

The kernel as well as, some other projects, can be built using the +clang compiler. To select this configuration, the +-DTRIPLE variable must be set in the initial configuration step i.e pass in as +an argument to the init-build script.

+ +

The value of the TRIPLE should be the +target +for which you are compiling.

+ +
../init-build -DTRIPLE=x86_64-linux-gnu <COMMAND_LINE_OPTIONS_HERE>
+
+ +

The CROSS_COMPILER_PREFIX argument is unnecessary and ignored when compiling +with clang. When building for arm based targets, the target TRIPLE will be +equal to the CROSS_COMPILER_PREFIX (when using gcc) without the trailing ‘-‘.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/buildsystem/using.md b/projects/buildsystem/using.md deleted file mode 100644 index 7fdfefc0e0b..00000000000 --- a/projects/buildsystem/using.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -redirect_from: - - /Developing/Building/Using -parent: /projects/buildsystem/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Configuring and building an seL4 project - -This page contains documentation for how to interact with and build a project -that is using this build system. For new project development, see [incorporating -the build system](incorporating.html). - -## Basic build initialisation - -In the root directory of an seL4 CMake-based project, first create a separate -build directory for the output binaries, then initialise CMake: - -```sh -mkdir build -cd build -cmake -DCROSS_COMPILER_PREFIX=arm-linux-gnueabi- -DCMAKE_TOOLCHAIN_FILE=../kernel/gcc.cmake -G Ninja .. -``` - -The components in the above invocation mean the following: - -- `-D` defines a variable, in the form `X=Y`. -- `CROSS_COMPILER_PREFIX` specifies the toolchain for cross-compilation, which - cannot be changed after build directory initialisation. For further details, - please see [Cross Compiling](#cross-compiling) below. -- `CMAKE_TOOLCHAIN_FILE` which indicates that CMake should load the specified - file as a 'toolchain' file. A toolchain file sets up the C - compiler, linker etc. for building the project. In the example above we assume a - typical project layout where seL4 is in the `kernel` directory at the top - level. The [gcc.cmake](https://github.com/seL4/seL4/blob/master/gcc.cmake)' - file from the seL4 repository sets up C compilers and linkers using the - `CROSS_COMPILER_PREFIX`. -- `-G Ninja` tells CMake to generate Ninja build scripts as opposed to GNU - Makefiles. Only Ninja scripts are supported by the kernel. -- `..` is the path to the top-level `CMakeLists.txt` file describing this - project, which in this case is placed in the root directory of the project. - -We also provide a shorthand wrapping script which abstracts the above into a -shorter command: - -```sh -../init-build -DCROSS_COMPILER_PREFIX=arm-linux-gnueabi- -``` - -After configuration, you can build the project by invoking ninja: - -```sh -ninja -``` - -After the build has completed, the resulting binaries will be in the `images/` -subdirectory. - -## Configuration - -### Types of Options - -CMake has two types of configuration options: - -- *Boolean options*, which are are either `ON` or `OFF`, -- *String options*, which can be set to any value, subject to restrictions set - by the project authors. - -String options can have 'hints', which specify can one of several fixed values. -CMake configuration editors respect these and provide a radio selection. - -### Selecting Options - -Many projects have some degree of customisation available via configuration -options. Once the build directory is initialised, you can use the following -approaches to bring up a user-interface for option configuration: - -- An `ncurses` based configuration: - -```sh -ccmake . -``` - -- Graphical configuration: - -```sh -cmake-gui . -``` - -In both cases the path `.` should resolve to the same directory used in the -build configuration. - -### Changing option values - -Any changes to configuration options will not be reflected in the user interface -unless explicitly requested by using `(c)onfigure`, which may result in changes -to the options available. For example if option `A` depends on boolean option -`B`, `A` will not show up until `B` is enabled and `(c)onfigure` is used to -reprocess the CMake files. - -To exit the configuration interface, use `(g)enerate and exit` or `(q)uit -without generation`. CMake will not permit generation if the configuration is -incomplete (`(c)onfigure` must be run and all options set). - -To rebuild after changing configuration options, invoke ninja: - -```sh -ninja -``` - -### Initial configuration - -Many of our projects support multiple configurations, where the following broad -approaches are used to present simple options to the user: - -- **CMake cache scripts**: These files can assign initial values to a number of - configuration variables. By combining one or more of these you can configure - an entire system. -- **Meta configuration options**: Meta configuration options are normally - passed as initial `-DVAR=FOO` command line arguments to CMake and will be - programatically inspected by projects' CMake scripts to (re)configure the - system. - -#### CMake cache scripts - -CMake cache scripts provide subsets of preconfigured options, which allow the -user of a project to avoid manually setting each option. Cache scripts have the -file extension `.cmake`. - -Projects may provide cache script files which each contain the cache settings -necessary to configure a single feature or option. By combining multiple -`.cmake` files, a project can be initialised in a specific way. Cache script -configurations are provided by passing `-C ` to `cmake` when initialising -the build directory. For example, given a typical project structure, one might -invoke `cmake` or `init-build.sh` with several of cache scripts as arguments. - -Multiple cached scripts can be specified on the command line, although if the -same option is set twice only one value is used. Consider an example with -several cache scripts for setting the architecture details (`arm.cmake`, -`x86.cmake`) and for setting build options (`debug.cmake`, `release.cmake`). The -intended usage is that one architectural cache file is used, and one build -options file, as demonstrated below: - -```sh -cmake -C../projects/awesome_project/configs/arm.cmake -C../projects/awesome_project/configs/debug.cmake -DCROSS_COMPILER_PREFIX=arm-linux-gnueabi- -DCMAKE_TOOLCHAIN_FILE=../kernel/gcc.cmake -G Ninja .. -``` - -While nothing prevents the usage of both `arm.cmake` and `x86.cmake` at the same -time, this does not make sense, and only one value for each option will be used. -For projects with multiple cache scripts, check which can be used together. - -#### Meta configuration options - -Some seL4 projects such as `sel4test` provide top-level variables which, used -across projects, have standardised behaviour. These options are as follows: - -- `-DPLATFORM=`: Selects the target system for the resulting - binaries. Valid values for this variable are the first value (preceding the - semicolon) on each line of the `config_choice` directive for each - architecture: - - For ARM: [List in source](https://github.com/seL4/seL4/blob/master/src/arch/arm/config.cmake#L21). - - For X86: [List in source](https://github.com/seL4/seL4/blob/master/src/arch/x86/config.cmake#L15). - - For RISC-V: [List in source](https://github.com/seL4/seL4/blob/master/src/arch/riscv/config.cmake#L15). - -- `-DRELEASE`: Set to `0` or `1`: Turning this off compiles a debug build. - Turning it on compiles the project without debugging features enabled. -- `-DVERIFICATION`: Set to `0` or `1`: This is used to generate the version of - the seL4 kernel source which is **VERIFIABLE**. This does not produce a binary - for the **verified** kernel platform. -- `-DSMP`: Set to `0` or `1`: Turns SMP (symmetric multiprocessing) support on or - off. By default it will enable support for up to 4 processors. To explicitly - set the maximum number of supported CPUs, try setting - `-DKernelMaxNumNodes=`. -- `-DSIMULATION`: Set to `0` or `1`: This produces a build of the project which - is suited for running in an emulator such as QEMU. - -Both the [seL4test](../sel4test/) and [seL4bench](../sel4bench/) projects follow this form. - -### sel4test example - -For more information on configuring, building and running the [sel4test -suite](https://github.com/seL4/sel4test), please see the [main page on -seL4test](../sel4test/). - -## Cross compiling - -[Cross compilation](https://en.wikipedia.org/wiki/Cross_compiler) refers to -compiling a program for a target machine which is different from the machine you -are using to compile the program. - -Generally, in order to cross-compile, a separate compiler is required which -specifically targets the foreign machine. - -### For ARM-based targets - -You can use the following command line options when when cross-compiling for an -ARM-based machine: - -- `-DAARCH32=TRUE`: Tells the build system that you are building for a 32-bit - ARM target. This will cause the build system to assume that you have a - cross compiler installed which targets a system with the triplet name - `arm-linux-gnueabi-`. -- `-DAARCH32HF=TRUE`: Tells the build system you're building for a 32-bit ARM - target which has hardware floating point support. Assumes you have a cross- - compiler installed which targets `arm-linux-gnueabihf-`. -- `-DAARCH64=TRUE`: Tells the build system you're building for a 64-bit ARM - target. Assumes you have a cross-compiler installed which targets - `aarch64-linux-gnu-`. - -Another option is to explicitly specify the toolchain through -`-DCROSS_COMPILER_PREFIX`, which can be used to set the prefix of the -cross-compiler to use. - -### For RISC-V based targets - -You can use the following options when cross compiling for a RISC-V target: - -- `-DRISCV32=TRUE`: Tells the build system that you are building for a 32-bit RISC-V - target. This will cause the build system to assume that you have a cross- - compiler installed which targets a system with the triplet name - `riscv32-unknown-elf-`. -- `-DRISCV64=TRUE`: Tells the build system you're building for a 64-bit RISC-V - target. Assumes you have a cross-compiler installed which targets - `riscv64-unknown-elf-`. - -Like ARM, you can explicitly specify the toolchain through -`-DCROSS_COMPILER_PREFIX`, which can be used to set the prefix of the -cross-compiler to use. - -### CMAKE_BUILD_TYPE - -The `CMAKE_BUILD_TYPE` option appears in CMake configuration editors and allows -users to configure that build type (release, debug etc.). Note that this option -is not respected by the seL4 kernel. - -## Building with Clang - -The kernel as well as, some other projects, can be built using the -[clang](https://clang.llvm.org/) compiler. To select this configuration, the -`-DTRIPLE` variable must be set in the initial configuration step i.e pass in as -an argument to the `init-build` script. - -The value of the `TRIPLE` should be the -[target](https://releases.llvm.org/8.0.0/tools/clang/docs/CrossCompilation.html#target-triple) -for which you are compiling. - -```sh -../init-build -DTRIPLE=x86_64-linux-gnu -``` - -The `CROSS_COMPILER_PREFIX` argument is unnecessary and ignored when compiling -with clang. When building for arm based targets, the target `TRIPLE` will be -equal to the `CROSS_COMPILER_PREFIX` (when using gcc) without the trailing '-'. diff --git a/projects/camkes-vm/centos.html b/projects/camkes-vm/centos.html new file mode 100644 index 00000000000..9e1f1ef4b38 --- /dev/null +++ b/projects/camkes-vm/centos.html @@ -0,0 +1,593 @@ + + + + + + + Boot CentOS on the CAmkES VM | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Boot CentOS on the CAmkES VM

+ + + +

CentOS Guest

+ +

Installation

+ +

CentOS should be installed on the 32GiB flash drive of the cma34cr using the entire drive, +i.e. no dual booting etc. It must be an i386 CentOS 7 installation, images of which can be +found at http://mirror.centos.org/altarch/7/isos/i386/

+ +

Kernel Image

+ +

The bzimage and roofs.cpio in this directory are from altarch CentOS-7. They are the +/boot/initramfs-3.10.0-693.5.2.el7.centos.plus.i686.img +/boot/vmlinuz-3.10.0-693.5.2.el7.centos.plus.i686 +From an i386 CentOS-7 installation. You should be able to replace these with the +equivalent files from any i386 CentOS-7 installation, regardless of the precise version, +although you should not need to do this as this kernel/initramfs should be compatible with +any installation.

+ +

Kernel Command Line

+ +

Assuming a default installation of CentOS the command line passed to the Linux kernel. +In the case where you provided a custom name for your root partitions, or if +something changes in later CentOS versions, then this needs to be updated from the +command line in the grub configuration of your actual installation

+ +

Booting the VMM

+ +

After building you will have two files in the images/ directory, a kernel- and a capdl-. +These need to be booted with a multiboot compatible loader, with the capdl- image passed +as a boot module. This can be done with with a PXE based network loader, or by adding to +the grub menu of the installed CentOS.

+ +

Hardware Configuration

+ +

The component specification assumes that the cma34cr is close to its default configuration, +with the exception that the SATA controller has been placed into legacy IDE mode instead of +its default AHCI mode.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes-vm/centos.md b/projects/camkes-vm/centos.md deleted file mode 100644 index 60c1f0607a9..00000000000 --- a/projects/camkes-vm/centos.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -parent: /projects/camkes-vm/ -redirect_from: - - /VM/CAmkESVMCentOS -repo: 'seL4/camkes-vm-examples' -include_file: apps/x86/cma34cr_centos/README.md -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Boot CentOS on the CAmkES VM - -{% include include_github_repo_markdown.md indent_headings=true %} diff --git a/projects/camkes-vm/index.html b/projects/camkes-vm/index.html new file mode 100644 index 00000000000..a3a8a53f692 --- /dev/null +++ b/projects/camkes-vm/index.html @@ -0,0 +1,1213 @@ + + + + + + + CAmkES VMM | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES VMM

+ + + +

camkes-vm-apps

+ +

This project is for running virtualised Linux guests on seL4 for ARM and x86 platforms. The camkes-vm implements +a virtual machine monitor (VMM) server, facilitating the initialisation, booting and run-time management of a guest OS. +You can view the code for the VMMs in the camkes-vm repository under VM_Arm and VM.

+ +

Currently the supported platforms include:

+ +
    +
  • Exynos5 (exynos5410, exynos5422)
    • +
  • TK1
    • +
  • TX1
    • +
  • TX2
    • +
  • QEMU ARM virt machine
    • +
  • ZCU102
    • +
  • x86
    • +
  • x86_64
    • +
+ +

Getting and Building

+ +

Cloning the repository set and preparing a build directory

+ +
repo init -u https://github.com/seL4/camkes-vm-examples-manifest.git
+repo sync
+mkdir build
+cd build
+
+ +

Arm and x86 have slightly differing build instructions. See the sections below.

+ +

Building for Arm

+ +

The following example builds the CAmkES Arm VMM for the TK1. In the build directory, run:

+ +
../init-build.sh -DCAMKES_VM_APP=vm_minimal -DPLATFORM=tk1
+ninja
+
+ +

Note: To buid for another platform you can substitute the value of the -DPLATFORM variable e.g. (exynos5422, tx1, tx2, zcu102, qemu-arm-virt).

+ +

For instance, on QEMU (which only supports AArch64), use:

+ +
../init-build.sh -DCAMKES_VM_APP=vm_minimal -DPLATFORM=qemu-arm-virt -DAARCH64=TRUE
+
+ +

An EFI application file will be left in images/capdl-loader-image-arm-tk1 We normally boot using TFTP, by first copying capdl-loader-image-arm-tk1 to a tftpserver then on the U-Boot serial console doing:

+ +
dhcp
+tftpboot ${loadaddr} /capdl-loader-image-arm-tk1
+bootefi ${loadaddr}
+
+ +

Building for x86

+ +

The following example builds the CAmkES VMM for x64. In the build directory, run:

+ +
../init-build.sh -DCAMKES_VM_APP=minimal_64
+ninja
+
+ +

Boot images/kernel-x86_64-pc99 and images/capdl-loader-image-x86_64-pc99 with the multiboot boot loader of your choice. Use *.ia32-pc99 if built for 32-bit with ../init-build.sh -DCAMKES_VM_APP=minimal.

+ +

CAmkES ARM VMM Applications

+ +

This project contains various reference CAmkES applications that incorporate the VMM component. These applications include:

+ +
    +
  • vm_minimal: A simple VMM application, launching a single guest Linux with a buildroot RAM-based file system
    • +
  • vm_cross_connector: Application demonstrating communication between a Linux guest user-level process and a native seL4 component. This leveraging +cross vm communication channels established between the VMM and the seL4 component.
    • +
  • vm_multi: Application demonstrating running multiple guest VM’s. This is achieved through having multiple VMM components, each managing a single +Linux guest (1-1 model).
    • +
  • vm_serial_server: Application demonstrating the use of Virtio Console, where a VM’s serial I/O is forwarded to/from a serial server.
    • +
  • vm_virtio_net: Application demonstrating the use of Virtio Net, where a virtual network interface is presented to a VM and subsequent network +traffic on the virtual network interface is sent to/from other native seL4 components.
    • +
+ +

See the apps/Arm/ subdirectory for all the supported virtual machine manager apps, their implementations and the platforms they target.

+ +

CAmkES x86 VMM Applications

+ +
    +
  • +

    The minimal application is a simple CAmkES VM application. The application is configured with:

    + +
      +
    • 1 Guest Linux VM: The Linux guest is a buildroot built image sourced from the the camkes-vm repo. The Linux images (rootfs and kernel) are defined in the CMakeLists.txt file of the minimal application. In the CMakeLists.txt file we are able to find that the rootfs and kernel images are added to the FileServer under the names "rootfs.cpio" and "bzimage" respectively.
      • +
    +
    • +
  • +

    The optiplex9020 VM application is configured with:

    + +
      +
    • 2 Guest Linux VM’s: The Linux guests are buildroot built images sourced from the the camkes-vm repo.
      • +
    • +

      Cross VM Connectors: To demo the use of cross-vm connectors a series of shared dataports and events are established between vm0 and the StringReverse component. The StringReverse demo can be invoked from the command-line of vm0:

      + + 
      Welcome to Buildroot
+buildroot login: root
+Password:
+\# string_reverse
+[   19.739028] dataport received mmap for minor 1
+[   19.743337] dataport received mmap for minor 2
+hello
+olleh
+
      +
      • +
    +
    • +
  • +

    The cma34cr_centos application is a more complex CAmkES VM configuration demonstrating the use of passthrough hardware. The cma34cr_centos application is configured with:

    + +
      +
    • 1 Guest Linux VM: The Linux guest images (bzimage and roofs.cpio) are located in the applications directory (cma34cr_centos/centos_linux), originally sourced from an i386 altarch CentOS-7 installation. Additionally the CentosOS installation should be on a flash drive passed-through to the cma34cr application. Further information regarding the Linux installation can be found in the applications README.
      • +
    • Cross VM Connectors: A series of shared dataports and events are established between vm0 and the StringReverse component.
      • +
    • Ethernet Driver, UDPSever, Echo, Firewall: A passthrough ethernet configuration demo. The guest VM is configured to use the Ethernet driver component through a virtio configuration.
      • +
    • Passthrough hardware storage (SATA/USB): A hardware configuration to boot the CentOS installation.
      • +
    +
    • +
  • +

    The zmq_samples application demonstrates messaging between VMs using the ZeroMQ messaging library. +See the README.md in its folder for more information.

    +
    • +
+ +

See the apps/x86/ subdirectory for all the supported virtual machine manager apps, their implementations and the platforms they target.

+ +

Arm Features

+ +

See the below feature matrix for the various features the CAmkES ARM VMM implements/facilitates across the various supported platforms.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlaformGuest ModeSMP SupportMultiple VM SupportVirtio PCIVirtio ConsoleVirtio NetCross VM Connector SupportNotes
exynos542232-bitUnsupportedSupportedSupportedSupportedSupportedSupportedSMP configurations are unsupported due to: * No exynos5422 kernel SMP support * No virtual power device interface to manage VCPU’s at runtime (e.g. core startup)
TK132-bitUnsupportedUnsupportedUnsupportedUnsupportedUnsupportedUnsupportedSMP configurations are unsupported due to: * No TK1 kernel SMP support * No virtual power device interface to manage VCPU’s at runtime (e.g. core startup) Virtio PCI, Console, Net, Cross VM connector support & Multi-VM are untested
TX164-bitSupportedUnsupportedUnsupportedUnsupportedUnsupportedUnsupportedVirtio PCI, Console, Net, Cross VM connector support & Multi-VM are untested
TX264-bitSupportedSupportedSupportedSupportedSupportedUnsupportedCross VM connector support is untested
ZCU10264-bitSupportedSupportedSupportedSupportedSupportedUnsupportedCross VM connector support is untested
QEMU Virt64-bitSupportedUnsupportedSupportedSupportedSupportedSupportedMulti-VM support depends on porting the TimeServer to QEMU (See https://github.com/sel4/global-components/tree/master/components/TimeServer)
+ +

Arm Platform Configuration Notes

+ +

Exynos5422, TX1, TX2, ZCU102, QEMU ARM Virt configuration

+ +

We provide a pre-built Linux image and Buildroot image for our guest VM’s. See the images in the camkes-vm-images repository at https://github.com/sel4/camkes-vm-images. +Feel free also to compile your own Linux and Rootfs images, see the README’s in each platform subdirectory (within camkes-vm-images) for information about our +image build configurations.

+ +

TK1 configuration

+ +

We currently provide two linux binaries and two device tree configurations.

+ +
    +
  • linux-tk1-debian will try and load a debian userspace off of an emmc partition
    • +
  • linux-tk1-initrd will load an included buildroot ramdisk
    • +
  • linux-tk1-secure.dts is a device tree configuration with the devices that aren’t provided to the linux are disabled.
    • +
  • linux-tk1-nonsecured.dts is a device tree configuration with all devices enabled.
    • +
+ +

In the tk1 app configuration there is a boot mode selection option that chooses between the two linux binaries, and +an Insecure option which selects whether to provide all hardware devices to the linux vm or not. If Insecure is not set +then the VM will only be provided a minimal amount of hardware frames and the linux-tk1-secure.dts DTS will be used. If Insecure +is set then the VM will be provided all device frames apart from the Memory controller and the linux-tk1-nonsecured.dts DTS will be used.

+ +

U-Boot is required to initialise the USB devices if linux-tk1-secure.dts is used. This is done by: usb start 0.

+ +

The tk1 currently uses linux binaries constructed using Buildroot 2016.08.1 with the following configs:

+ +
    +
  • buildroot_tk1_initrd_defconfig builds linux with an included ramdisk that will be loaded at boot.
    • +
  • buildroot_tk1_emmc_defconfig builds linux without a ramdisk and it will mount and run /sbin/init /dev/mmcblk0p2
    • +
+ +

To copy the files back into this project, change into the Linux directory and run make for each file as shown below. Note that you can only +update one of linux-tk1-debian or linux-tk1-initrd at a time as they are built from different Buildroot configs:

+ +
cd projects/vm/linux
+LINUX_FILE=linux-tk1-initrd BUILDROOT_DIR=~/workspaces/buildroot-2016.08.1/ make
+LINUX_FILE=linux-tk1-dtb-secure BUILDROOT_DIR=~/workspaces/buildroot-2016.08.1/ make
+
+ +

Both of these configs use the tegra124-jetson-tk1-sel4vm-secure device tree file. +To change to the tegra124-jetson-tk1-sel4vm.dts this will need to be changed in the buildroot make menuconfig. +To change the mounted emmc partition the chosen dts file’s bootargs entry will need to be updated.

+ +

The Linux version used can be found in the seL4 branch of our linux-tegra repo.

+ +

When buildroot starts:

+ +
buildroot login: root
+#
+
+ +

When debian starts:

+ +
Debian GNU/Linux 8 tk1 ttyS0
+tk1 login: root
+Password: root
+root@tk1:~#
+
+ +

Wireless Configuration

+ +

To configure the Ralink 2780 USB wifi dongle:

+ +
ifconfig wlan0 up
+iw wlan0 scan
+wpa_passphrase SSID_NAME >> /etc/wpa_supplicant.conf
+  ENTER_SSID_PASSPHRASE
+wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf
+iw wlan0 link
+dhclient wlan0
+
+ +

TK1 Build Notes

+ +

The default setup does not pass though many devices to the Linux kernel. If you make menuconfig you can set insecure mode in the Applications submenu; this is meant to pass through all devices, but not +everything has been tested and confirmed to work yet. In particular, the SMMU needs to have extra entries added for any DMA-capable devices such as SATA.

+ + + +
    +
  1. CAmkES VM: Adding a Linux Guest
    2. +
  2. CAmkES VM: Cross VM Connectors
    3. +
+ +

Arm FAQ and Implementation Notes

+ +

How do I update camkes-vm-apps to support platform ‘X’

+ +

Whilst large parts of the ARM VMM implementation tries to be platform agnostic, there are a few things to keep in mind and implement in order to correctly run the camkes-arm-vm on your new target platform. +See the below list as as a rough list of items to check off:

+ +
    +
  • Ensure the platform is already supported by seL4 (or you have developed support for the platform prior). See the following page for a list of supported platforms.
    • +
  • The platform supports ARM’s hardware virtualisation features, these being found on ARMv7 (with virtualisation extensions) and ARMv8. +
      +
    • Second to this, the seL4 port to the given platform also supports running with KernelArmHypervisorSupport
      • +
    +
    • +
  • Does your platform use a GICv2 or GICv3? Note: We currently only support a virtual GICV2, with virtual GICV3 support under-development. See the listed features of libsel4vm for further information: https://github.com/sel4/seL4_projects_libs/tree/master/libsel4vm
    • +
  • When porting a VMM application to your platform, say vm_minimal, ensure you provide the following: +
      +
    • A devices.camkes file for your platform. These containing platform specific definitions, see in particular the vm dtb field and the untyped_mmios field (for device passthrough). The values in the aforementioned fields corresponding with those found in the kernel device tree.
      • +
    • A vmlinux.h header for you platform. See the header file for the other supported platforms at components/VM_Arm/plat_include in camkes-vm repository.
      • +
    +
    • +
  • Provide a pre-compiled Linux kernel and initrd image for your platform. Once compiled these are usually linked in through your apps CMakeLists.txt. See apps/Arm/vm_minimal/CMakeLists.txt for examples of how other platforms link in their images.
    • +
+ +

Feel free to contact the team for further support on porting the camkes-arm-vm to your desired platform. We are also always open to contributions for new platforms.

+ +

Can a single VMM component support running multiple VM’s?

+ +

Currently, No. A VMM component only creates and manages a single VM instance. +To support multiple VM’s, you can run multiple VMM components, each managing its own VM. See apps/vm_multi for an example of this configuration.

+ +

How do I enable SMP support for a VM instance?

+ +

To configure your VM with multiple VCPU’s, you can set the VM instance attribute num_vcpus in your camkes configuration. See here for an example. +In addition, when initialising your build, ensure the KernelMaxNumNodes configuration option is set to your desired value. You can also initialise your build with variable -DNUM_NODES variable e.g.

+ +
../init-build.sh -DCAMKES_VM_APP=vm_minimal -DPLATFORM=tx2 -DNUM_NODES=4
+
+ +

Note: ensure your platform supports SMP configurations through the above feature matrix

+ + + +

CAmkES x86 VM

+ +

Prerequisites

+ +
    +
  • Get the dependencies for building CAmkES by following [the setup instructions] +(../camkes/setting-up.html)
    • +
  • Your host machine has to have a CPU that supports Vt-x virtualization + (for Intel CPUs), or AMD-V (for AMD CPUs, but that wasn’t tested). Any +newer i7 core should have Vt-x. Note that you might have to enable it +first from BIOS. You can always check by lscpu and look for vmx flag.
    • +
+ +

Tutorials

+ +

Use the following tutorials to learn about the VM:

+ +
    +
  1. CAmkES VM Linux using Linux as a guest in the CAmkES VM
    2. +
+ +

Examples

+ + + +

Booting from hard drive

+ +

These instructions are for ubuntu. For CentOS instructions, see +CAmkES VM CentOS.

+ +

So far we’ve only run a tiny linux on a ram disk. What if we want to run +Ubuntu booting off a hard drive? This section will explain the changes +we need to make to our VM app to allow it to boot into a Ubuntu +environment installed on the hard drive. Thus far these examples should +have been compatible with most modern x86 machines. The rest of this +tutorial will focus on a particular machine: +the cma34cr +single board computer

+ +

The first step is to install ubuntu natively on the cma34cr. It’s +currently required that guests of the camkes vm run in 32-bit mode, so +install 32-bit ubuntu. These examples will use ubuntu-16.04.

+ +

The plan will be to give the guest passthrough access to the hard drive, +and use a ubuntu initrd as our initial root filesystem, replacing the +buildroot one used thus far. We’ll use the same kernel image as before, +as our vm requires that PAE be turned off, and it’s on by default in the +ubuntu kernel.

+ +

Getting the initrd image

+ +

We need to generate a root filesystem image suitable for ubuntu. Ubuntu +ships with a tool called mkinitramfs which generates root filesystem +images. Let’s use it to generate a root filesystem image compatible with +the linux kernel we’ll be using. Boot ubuntu natively on the cma34cr and +run the following command:

+
$ mkinitramfs -o rootfs.cpio 4.8.16
+WARNING: missing /lib/modules/4.8.16
+Ensure all necessary drivers are built into the linux image!
+depmod: ERROR: could not open directory /lib/modules/4.8.16: No such file or directory
+depmod: FATAL: could not search modules: No such file or directory
+depmod: WARNING: could not open /var/tmp/mkinitramfs_H9SRHb/lib/modules/4.8.16/modules.order: No such file or directory
+depmod: WARNING: could not open /var/tmp/mkinitramfs_H9SRHb/lib/modules/4.8.16/modules.builtin: No such file or directory
+
+ +

The kernel we’ll be using has all the necessary drivers built in, so +feel free to ignore those warnings and errors. You should now have a +file called rootfs.cpio on the cma34cr. Transfer that file to your dev +machine, and put it in projects/vm/minimal. Now we need to tell the +build system to take that rootfs image rather than the default buildroot +one. Edit projects/vm-examples/minimal/CMakeLists.txt. Change this line:

+ +
AddToFileServer("rootfs.cpio" ${rootfs_file})
+
+

to

+
AddToFileServer("rootfs.cpio" <ROOTFS_FILENAME>)
+
+

where <ROOTFS_FILENAME> is replaced with the filename of the rootfs file you +added in projects/vm/minimal.

+ +

Since we’ll be using a real hard drive, we need to change the boot +command line we give to the guest linux. Open +projects/vm-examples/minimal/minimal.camkes, and change the +definition of VM_GUEST_CMDLINE to:

+
#define VM_GUEST_CMDLINE "earlyprintk=ttyS0,115200 console=ttyS0,115200 i8042.nokbd=y i8042.nomux=y i8042.noaux=y io_delay=udelay noisapnp pci=nomsi debug root=/dev/sda1 rdinit=/init 2"
+
+ +

Try building and running after this change:

+
BusyBox v1.22.1 (Ubuntu 1:1.22.0-15ubuntu1) built-in shell (ash)
+Enter 'help' for a list of built-in commands.
+
+(initramfs)
+
+ +

You should get dropped into a shell inside the root filesystem. You can +run commands from here:

+
(initramfs) pwd
+/
+(initramfs) ls
+dev      run      init     scripts  var      usr      sys      tmp
+root     sbin     etc      bin      lib      conf     proc
+
+ +

If you look inside /dev, you’ll notice the lack of sda device. Linux +can’t find the hard drive because we haven’t passed it through yet. +Let’s do that now!

+ +

We’re going to give the guest passthrough access to the sata controller. +The sata controller will be in one of two modes: AHCI or IDE. The mode +can be set when configuring BIOS. By default it should be AHCI. The next +part has some minor differences depending on the mode. I’ll show both. +Open projects/vm-examples/minimal/minimal.camkes and add the following to the +configuration section:

+ +

For AHCI:

+
configuration {
+    ...
+
+    vm0_config.pci_devices_iospace = 1;
+
+
+    vm0_config.ioports = [
+        {"start":0x4088, "end":0x4090, "pci_device":0x1f, "name":"SATA"},
+        {"start":0x4094, "end":0x4098, "pci_device":0x1f, "name":"SATA"},
+        {"start":0x4080, "end":0x4088, "pci_device":0x1f, "name":"SATA"},
+        {"start":0x4060, "end":0x4080, "pci_device":0x1f, "name":"SATA"},
+    ];
+
+    vm0_config.pci_devices = [
+        {
+            "name":"SATA",
+            "bus":0,
+            "dev":0x1f,
+            "fun":2,
+            "irq":"SATA",
+            "memory":[
+                {"paddr":0xc0713000, "size":0x800, "page_bits":12},
+            ],
+        },
+    ];
+
+    vm0_config.irqs = [
+        {"name":"SATA", "source":19, "level_trig":1, "active_low":1, "dest":11},
+    ];
+}
+
+ +

For IDE:

+
configuration {
+    ...
+
+    vm0_config.pci_devices_iospace = 1
+
+    vm0_config.ioports = [
+        {"start":0x4080, "end":0x4090, "pci_device":0x1f, "name":"SATA"},
+        {"start":0x4090, "end":0x40a0, "pci_device":0x1f, "name":"SATA"},
+        {"start":0x40b0, "end":0x40b8, "pci_device":0x1f, "name":"SATA"},
+        {"start":0x40b8, "end":0x40c0, "pci_device":0x1f, "name":"SATA"},
+        {"start":0x40c8, "end":0x40cc, "pci_device":0x1f, "name":"SATA"},
+        {"start":0x40cc, "end":0x40d0, "pci_device":0x1f, "name":"SATA"},
+    ];
+
+    vm0_config.pci_devices = [
+        {
+            "name":"SATA",
+            "bus":0,
+            "dev":0x1f,
+            "fun":2,
+            "irq":"SATA",
+            "memory":[],
+        },
+    ];
+
+    vm0_config.irqs = [
+        {"name":"SATA", "source":19, "level_trig":1, "active_low":1, "dest":11},
+    ];
+}
+
+ +

Now rebuild and run:

+
Ubuntu 16.04.1 LTS ertos-CMA34CR ttyS0
+
+ertos-CMA34CR login:
+
+ +

You should be able to log in and use the system largely as normal.

+ +

Passthrough Ethernet

+ +

The ethernet device is not accessible to the guest:

+
$ ip addr
+1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1
+    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+    inet 127.0.0.1/8 scope host lo
+       valid_lft forever preferred_lft forever
+    inet6 ::1/128 scope host
+       valid_lft forever preferred_lft forever
+2: sit0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN group default qlen 1
+    link/sit 0.0.0.0 brd 0.0.0.0
+
+ +

An easy way to give the guest network access is to give it passthrough +access to the ethernet controller. This is done much in the same way as +enabling passthrough access to the sata controller. In the configuration +section in projects/vm-examples/minimal/minimal.camkes, add to the list of io +ports, pci devices and irqs to pass through:

+
vm0_config.ioports = [
+    {"start":0x4080, "end":0x4090, "pci_device":0x1f, "name":"SATA"},
+    {"start":0x4090, "end":0x40a0, "pci_device":0x1f, "name":"SATA"},
+    {"start":0x40b0, "end":0x40b8, "pci_device":0x1f, "name":"SATA"},
+    {"start":0x40b8, "end":0x40c0, "pci_device":0x1f, "name":"SATA"},
+    {"start":0x40c8, "end":0x40cc, "pci_device":0x1f, "name":"SATA"},
+    {"start":0x40cc, "end":0x40d0, "pci_device":0x1f, "name":"SATA"},
+    {"start":0x3000, "end":0x3020, "pci_device":0, "name":"Ethernet5"}, // <--- Add this entry
+];
+
+vm0_config.pci_devices = [
+    {
+        "name":"SATA",
+        "bus":0,
+        "dev":0x1f,
+        "fun":2,
+        "irq":"SATA",
+        "memory":[],
+    },
+
+    // Add this entry:
+    {
+        "name":"Ethernet5",
+        "bus":5,
+        "dev":0,
+        "fun":0,
+        "irq":"Ethernet5",
+        "memory":[
+            {"paddr":0xc0500000, "size":0x20000, "page_bits":12},
+            {"paddr":0xc0520000, "size":0x4000, "page_bits":12},
+        ],
+    },
+];
+
+vm0_config.irqs = [
+    {"name":"SATA", "source":19, "level_trig":1, "active_low":1, "dest":11},
+    {"name":"Ethernet5", "source":0x11, "level_trig":1, "active_low":1, "dest":10}, // <--- Add this entry
+];
+
+ +

You should have added a new entry to each of the three lists that +describe passthrough devices. Building and running:

+
$ ip addr
+1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1
+    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+    inet 127.0.0.1/8 scope host lo
+       valid_lft forever preferred_lft forever
+    inet6 ::1/128 scope host
+       valid_lft forever preferred_lft forever
+2: enp0s2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
+    link/ether 00:d0:81:09:0c:7d brd ff:ff:ff:ff:ff:ff
+    inet 10.13.1.87/23 brd 10.13.1.255 scope global dynamic enp0s2
+       valid_lft 14378sec preferred_lft 14378sec
+    inet6 2402:1800:4000:1:90b3:f9d:ae22:33b7/64 scope global temporary dynamic
+       valid_lft 86390sec preferred_lft 14390sec
+    inet6 2402:1800:4000:1:aa67:5925:2cbc:928f/64 scope global mngtmpaddr noprefixroute dynamic
+       valid_lft 86390sec preferred_lft 14390sec
+    inet6 fe80::cc47:129d:bdff:a2da/64 scope link
+       valid_lft forever preferred_lft forever
+3: sit0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN group default qlen 1
+    link/sit 0.0.0.0 brd 0.0.0.0
+$ ping google.com
+PING google.com (172.217.25.142) 56(84) bytes of data.
+64 bytes from syd15s03-in-f14.1e100.net (172.217.25.142): icmp_seq=1 ttl=51 time=2.17 ms
+64 bytes from syd15s03-in-f14.1e100.net (172.217.25.142): icmp_seq=2 ttl=51 time=1.95 ms
+64 bytes from syd15s03-in-f14.1e100.net (172.217.25.142): icmp_seq=3 ttl=51 time=1.99 ms
+64 bytes from syd15s03-in-f14.1e100.net (172.217.25.142): icmp_seq=4 ttl=51 time=2.20 ms
+
+ +

Figuring out information about PCI devices

+ +

To add a new passthrough device, or access a pci device in general, we +need to know which io ports it uses, which interrupts it’s associated +with, and the physical addresses of any memory-mapped io regions it +uses. The easiest way to find this information is to boot linux +natively, and run the command lspci -vv.

+ +

Configuring a Linux kernel build

+ +

We provide a custom kernel image with our CAmkES VM project, found here. +This kernel image is produced from building Linux 4.8.16, specifically configured with the following .config file.

+ +

However you may decide to build your own Linux kernel image (which may be a different version). When doing so, it is important to ensure the build is configured with the following Kbuild settings:

+ +
# General kernel settings
+CONFIG_X86_32=y
+CONFIG_X86=y
+CONFIG_X86_32_SMP=n
+CONFIG_SMP=n
+CONFIG_NOHIGHMEM=y
+CONFIG_PCI_MSI=n
+CONFIG_X86_UP_APIC=n
+# Power management and ACPI settings
+CONFIG_SUSPEND=n
+CONFIG_HIBERNATION=n
+CONFIG_PM=n
+CONFIG_ACPI=n
+# Virtio Settings
+CONFIG_VIRTIO=y
+CONFIG_VIRTIO_PCI=y
+CONFIG_VIRTIO_NET=y
+
+ +

You can configure these settings by either manually editing your kernel .config file in the root project directory or by interactively running make menuconfig.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes-vm/index.md b/projects/camkes-vm/index.md deleted file mode 100644 index 14737b00778..00000000000 --- a/projects/camkes-vm/index.md +++ /dev/null @@ -1,347 +0,0 @@ ---- -redirect_from: - - /VM/CAmkESX86VM -project: camkes-vm -repo: seL4/camkes-vm-examples -include_file: README.md -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# CAmkES VMM - -{% include include_github_repo_markdown.md %} - - - -## CAmkES x86 VM - -### Prerequisites - -- Get the dependencies for building CAmkES by following [the setup instructions] - (../camkes/setting-up.html) -- Your host machine has to have a CPU that supports Vt-x virtualization - (for Intel CPUs), or AMD-V (for AMD CPUs, but that wasn't tested). Any - newer i7 core should have Vt-x. Note that you might have to enable it - first from BIOS. You can always check by `lscpu` and look for **vmx** flag. - -### Tutorials - -Use the following tutorials to learn about the VM: - -{% assign tutorials = site.pages | where_exp: 'page', 'page.tutorial' | sort: 'tutorial-order' %} -{%- for t in tutorials %} -{%- if t.tutorial-order contains 'vm' %} -1. [{{t.title}}]({{t.url}}) {{t.description}} -{%- endif %} -{%- endfor %} - - -### Examples - -- [Centos](centos.md) -- [zmq_samples](zmq-samples.md) - - -### Booting from hard drive - - -These instructions are for ubuntu. For CentOS instructions, see -[CAmkES VM CentOS](centos.md). - -So far we've only run a tiny linux on a ram disk. What if we want to run -Ubuntu booting off a hard drive? This section will explain the changes -we need to make to our VM app to allow it to boot into a Ubuntu -environment installed on the hard drive. Thus far these examples should -have been compatible with most modern x86 machines. The rest of this -tutorial will focus on a particular machine: -[the cma34cr -single board computer](https://www.rtd.com/PC104/CM/CMA34CR/CMA34CR.htm) - -The first step is to install ubuntu natively on the cma34cr. It's -currently required that guests of the camkes vm run in 32-bit mode, so -install 32-bit ubuntu. These examples will use ubuntu-16.04. - -The plan will be to give the guest passthrough access to the hard drive, -and use a ubuntu initrd as our initial root filesystem, replacing the -buildroot one used thus far. We'll use the same kernel image as before, -as our vm requires that PAE be turned off, and it's on by default in the -ubuntu kernel. - -#### Getting the initrd image - - -We need to generate a root filesystem image suitable for ubuntu. Ubuntu -ships with a tool called mkinitramfs which generates root filesystem -images. Let's use it to generate a root filesystem image compatible with -the linux kernel we'll be using. Boot ubuntu natively on the cma34cr and -run the following command: -``` -$ mkinitramfs -o rootfs.cpio 4.8.16 -WARNING: missing /lib/modules/4.8.16 -Ensure all necessary drivers are built into the linux image! -depmod: ERROR: could not open directory /lib/modules/4.8.16: No such file or directory -depmod: FATAL: could not search modules: No such file or directory -depmod: WARNING: could not open /var/tmp/mkinitramfs_H9SRHb/lib/modules/4.8.16/modules.order: No such file or directory -depmod: WARNING: could not open /var/tmp/mkinitramfs_H9SRHb/lib/modules/4.8.16/modules.builtin: No such file or directory -``` - -The kernel we'll be using has all the necessary drivers built in, so -feel free to ignore those warnings and errors. You should now have a -file called rootfs.cpio on the cma34cr. Transfer that file to your dev -machine, and put it in `projects/vm/minimal`. Now we need to tell the -build system to take that rootfs image rather than the default buildroot -one. Edit `projects/vm-examples/minimal/CMakeLists.txt`. Change this line: - -```cmake -AddToFileServer("rootfs.cpio" ${rootfs_file}) -``` -to -```cmake -AddToFileServer("rootfs.cpio" ) -``` -where `` is replaced with the filename of the rootfs file you -added in `projects/vm/minimal`. - -Since we'll be using a real hard drive, we need to change the boot -command line we give to the guest linux. Open -`projects/vm-examples/minimal/minimal.camkes`, and change the -definition of `VM_GUEST_CMDLINE` to: -``` -#define VM_GUEST_CMDLINE "earlyprintk=ttyS0,115200 console=ttyS0,115200 i8042.nokbd=y i8042.nomux=y i8042.noaux=y io_delay=udelay noisapnp pci=nomsi debug root=/dev/sda1 rdinit=/init 2" -``` - -Try building and running after this change: -``` -BusyBox v1.22.1 (Ubuntu 1:1.22.0-15ubuntu1) built-in shell (ash) -Enter 'help' for a list of built-in commands. - -(initramfs) -``` - -You should get dropped into a shell inside the root filesystem. You can -run commands from here: -``` -(initramfs) pwd -/ -(initramfs) ls -dev run init scripts var usr sys tmp -root sbin etc bin lib conf proc -``` - -If you look inside `/dev`, you'll notice the lack of sda device. Linux -can't find the hard drive because we haven't passed it through yet. -Let's do that now! - -We're going to give the guest passthrough access to the sata controller. -The sata controller will be in one of two modes: AHCI or IDE. The mode -can be set when configuring BIOS. By default it should be AHCI. The next -part has some minor differences depending on the mode. I'll show both. -Open `projects/vm-examples/minimal/minimal.camkes` and add the following to the -configuration section: - -For AHCI: -```c -configuration { - ... - - vm0_config.pci_devices_iospace = 1; - - - vm0_config.ioports = [ - {"start":0x4088, "end":0x4090, "pci_device":0x1f, "name":"SATA"}, - {"start":0x4094, "end":0x4098, "pci_device":0x1f, "name":"SATA"}, - {"start":0x4080, "end":0x4088, "pci_device":0x1f, "name":"SATA"}, - {"start":0x4060, "end":0x4080, "pci_device":0x1f, "name":"SATA"}, - ]; - - vm0_config.pci_devices = [ - { - "name":"SATA", - "bus":0, - "dev":0x1f, - "fun":2, - "irq":"SATA", - "memory":[ - {"paddr":0xc0713000, "size":0x800, "page_bits":12}, - ], - }, - ]; - - vm0_config.irqs = [ - {"name":"SATA", "source":19, "level_trig":1, "active_low":1, "dest":11}, - ]; -} -``` - -For IDE: -```c -configuration { - ... - - vm0_config.pci_devices_iospace = 1 - - vm0_config.ioports = [ - {"start":0x4080, "end":0x4090, "pci_device":0x1f, "name":"SATA"}, - {"start":0x4090, "end":0x40a0, "pci_device":0x1f, "name":"SATA"}, - {"start":0x40b0, "end":0x40b8, "pci_device":0x1f, "name":"SATA"}, - {"start":0x40b8, "end":0x40c0, "pci_device":0x1f, "name":"SATA"}, - {"start":0x40c8, "end":0x40cc, "pci_device":0x1f, "name":"SATA"}, - {"start":0x40cc, "end":0x40d0, "pci_device":0x1f, "name":"SATA"}, - ]; - - vm0_config.pci_devices = [ - { - "name":"SATA", - "bus":0, - "dev":0x1f, - "fun":2, - "irq":"SATA", - "memory":[], - }, - ]; - - vm0_config.irqs = [ - {"name":"SATA", "source":19, "level_trig":1, "active_low":1, "dest":11}, - ]; -} -``` - -Now rebuild and run: -``` -Ubuntu 16.04.1 LTS ertos-CMA34CR ttyS0 - -ertos-CMA34CR login: -``` - -You should be able to log in and use the system largely as normal. - -### Passthrough Ethernet - - -The ethernet device is not accessible to the guest: -``` -$ ip addr -1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 - inet 127.0.0.1/8 scope host lo - valid_lft forever preferred_lft forever - inet6 ::1/128 scope host - valid_lft forever preferred_lft forever -2: sit0@NONE: mtu 1480 qdisc noop state DOWN group default qlen 1 - link/sit 0.0.0.0 brd 0.0.0.0 -``` - -An easy way to give the guest network access is to give it passthrough -access to the ethernet controller. This is done much in the same way as -enabling passthrough access to the sata controller. In the configuration -section in `projects/vm-examples/minimal/minimal.camkes`, add to the list of io -ports, pci devices and irqs to pass through: -```c -vm0_config.ioports = [ - {"start":0x4080, "end":0x4090, "pci_device":0x1f, "name":"SATA"}, - {"start":0x4090, "end":0x40a0, "pci_device":0x1f, "name":"SATA"}, - {"start":0x40b0, "end":0x40b8, "pci_device":0x1f, "name":"SATA"}, - {"start":0x40b8, "end":0x40c0, "pci_device":0x1f, "name":"SATA"}, - {"start":0x40c8, "end":0x40cc, "pci_device":0x1f, "name":"SATA"}, - {"start":0x40cc, "end":0x40d0, "pci_device":0x1f, "name":"SATA"}, - {"start":0x3000, "end":0x3020, "pci_device":0, "name":"Ethernet5"}, // <--- Add this entry -]; - -vm0_config.pci_devices = [ - { - "name":"SATA", - "bus":0, - "dev":0x1f, - "fun":2, - "irq":"SATA", - "memory":[], - }, - - // Add this entry: - { - "name":"Ethernet5", - "bus":5, - "dev":0, - "fun":0, - "irq":"Ethernet5", - "memory":[ - {"paddr":0xc0500000, "size":0x20000, "page_bits":12}, - {"paddr":0xc0520000, "size":0x4000, "page_bits":12}, - ], - }, -]; - -vm0_config.irqs = [ - {"name":"SATA", "source":19, "level_trig":1, "active_low":1, "dest":11}, - {"name":"Ethernet5", "source":0x11, "level_trig":1, "active_low":1, "dest":10}, // <--- Add this entry -]; -``` - -You should have added a new entry to each of the three lists that -describe passthrough devices. Building and running: -``` -$ ip addr -1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 - inet 127.0.0.1/8 scope host lo - valid_lft forever preferred_lft forever - inet6 ::1/128 scope host - valid_lft forever preferred_lft forever -2: enp0s2: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 - link/ether 00:d0:81:09:0c:7d brd ff:ff:ff:ff:ff:ff - inet 10.13.1.87/23 brd 10.13.1.255 scope global dynamic enp0s2 - valid_lft 14378sec preferred_lft 14378sec - inet6 2402:1800:4000:1:90b3:f9d:ae22:33b7/64 scope global temporary dynamic - valid_lft 86390sec preferred_lft 14390sec - inet6 2402:1800:4000:1:aa67:5925:2cbc:928f/64 scope global mngtmpaddr noprefixroute dynamic - valid_lft 86390sec preferred_lft 14390sec - inet6 fe80::cc47:129d:bdff:a2da/64 scope link - valid_lft forever preferred_lft forever -3: sit0@NONE: mtu 1480 qdisc noop state DOWN group default qlen 1 - link/sit 0.0.0.0 brd 0.0.0.0 -$ ping google.com -PING google.com (172.217.25.142) 56(84) bytes of data. -64 bytes from syd15s03-in-f14.1e100.net (172.217.25.142): icmp_seq=1 ttl=51 time=2.17 ms -64 bytes from syd15s03-in-f14.1e100.net (172.217.25.142): icmp_seq=2 ttl=51 time=1.95 ms -64 bytes from syd15s03-in-f14.1e100.net (172.217.25.142): icmp_seq=3 ttl=51 time=1.99 ms -64 bytes from syd15s03-in-f14.1e100.net (172.217.25.142): icmp_seq=4 ttl=51 time=2.20 ms -``` - -### Figuring out information about PCI devices - - -To add a new passthrough device, or access a pci device in general, we -need to know which io ports it uses, which interrupts it's associated -with, and the physical addresses of any memory-mapped io regions it -uses. The easiest way to find this information is to boot linux -natively, and run the command `lspci -vv`. - -### Configuring a Linux kernel build - -We provide a custom kernel image with our CAmkES VM project, found [here](https://github.com/seL4/camkes-vm-linux/tree/master/images/kernel). -This kernel image is produced from building Linux 4.8.16, specifically configured with the following [.config file](https://github.com/seL4/camkes-vm-linux/tree/master/linux_configs/4.8.16). - -However you may decide to build your own Linux kernel image (which may be a different version). When doing so, it is important to ensure the build is configured with the following Kbuild settings: - -``` -# General kernel settings -CONFIG_X86_32=y -CONFIG_X86=y -CONFIG_X86_32_SMP=n -CONFIG_SMP=n -CONFIG_NOHIGHMEM=y -CONFIG_PCI_MSI=n -CONFIG_X86_UP_APIC=n -# Power management and ACPI settings -CONFIG_SUSPEND=n -CONFIG_HIBERNATION=n -CONFIG_PM=n -CONFIG_ACPI=n -# Virtio Settings -CONFIG_VIRTIO=y -CONFIG_VIRTIO_PCI=y -CONFIG_VIRTIO_NET=y -``` - -You can configure these settings by either manually editing your kernel `.config` file in the root project directory or by interactively running `make menuconfig`. diff --git a/projects/camkes-vm/zmq-samples.html b/projects/camkes-vm/zmq-samples.html new file mode 100644 index 00000000000..2c45ed4a045 --- /dev/null +++ b/projects/camkes-vm/zmq-samples.html @@ -0,0 +1,796 @@ + + + + + + + ZeroMQ examples | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

ZeroMQ cross-vm communication example

+ +

The zmq_samples application demonstrates messaging between VMs using the ZeroMQ messaging library. Each VM contains a VirtNet +ethernet device eth0 which is connected to the eth0 devices in the other VMs. Ethernet packets sent from a VM over this +interface will be transmitted to another VM if the correct macaddress is used. Broadcasting is supported which enables ARP to facilitate Macaddress discovery from an IP.

+ +

There are three ZeroMQ application scenarios. They can be found in zmq_samples/src/user:

+
    +
  • Client/server: A client program that connects to a server program over a network connection and performs a series of requests
    • +
  • Publish/subscribe: A publish program that publishes information to a network address, and a subscribe program that connects to this address and receives published information
    • +
  • pipeline: 3 programs, a source, worker and sink, that generate, process and acumulate computational tasks.
    • +
+ +

The CMakeLists.txt file in zmq_samples builds libzmq (likely found in tools/libzmq) for a linux 32bit target environment, builds the above apps, and installs them into the buildroot rootfs using CMake functions declared found in camkes-vm-linux. +An custom init script is installed for each of the VMs that run each of the scenarios on a single VM, and then accross all 3 VMs, before providing the login prompt for each of them. Currently if all of the scenarios are run correctly, Finished running all scenarios will be printed, otherwise Exited with error on an error. If one of the VMs appear to have hung, this could indicate an incorrect network address.

+ +

Each network interface is configured as follows:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
vmIPMACIF
vm0192.168.1.102:00:00:00:AA:01eth0
vm1192.168.1.202:00:00:00:AA:02eth0
vm2192.168.1.302:00:00:00:AA:03eth0
+ +

Checkout and build

+ +

See Setting up your machine for instructions on how to set up your host machine.

+ +
repo init -u https://github.com/sel4/camkes-vm-examples-manifest.git -b tipc-stage
+
+repo sync
+
+mkdir build-zmq
+
+cd build-zmq
+
+../init-build.sh -DCAMKES_VM_APP=zmq_samples
+
+ninja
+
+

Then it should be able to be run on a haswell-like machine.

+ +

The working output is below.

+ +
Running 3 scenarios on one vm
+emul_raw_tx@virtio_net_vswitch.c:146Running client server scenario
+ Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+message size: 1 [B]
+roundtrip count: 10000
+average latency: 20.153 [us]
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:ff:0:aa:3. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+Running pub/sub scenario
+6
+Collecting updates from weather server…
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:16. Dropping frame.
+temp: 93901 -25 36 1
+temp: 95278 -19 30 2
+temp: 52299 34 29 3
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+temp: 94794 33 10 4
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+temp: 65265 16 46 5
+Average temperature for zipcode was 7F
+Running pipeline scenario
+Sending tasks to workers…
+Total expected cost: 5021 msec
+10.69.81.9.49.:...86..5..13..11..4..77..91.:97..38..74..10..94..89..64..53..15..32.:50..85..34..42..69..emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+emul_raw_tx@virtio_net_vswitch.c:146 Unreachable dest macaddr 33:33:0:0:0:2. Dropping frame.
+86..98..79..8..72.:47..89..80..96..74..85..8..85..88..84.:75..84..22..48..94..15..36..57..68..51.:88..17..36..22..58..5..7..56..83..15.:28..30..3..8..25..77..92..32..61..80.:16..35..64..37..83..57..52..19..14..19.:69..2..36..5..23..93..9..30..49..92.:44..76..21..47..83..46..23..74...Total elapsed time: 5364 msec
+Running 3 scenarios accross 3 vms
+Running client server scenario
+[   15.529525] random: crng init done
+[   16.555934] random: crng init done
+message size: 1 [B]
+roundtrip count: 10000
+average latency: 87.514 [us]
+Collecting updates from weather server…
+Running pub/sub scenario
+6
+temp: 74943 -21 27 1
+temp: 37849 -33 59 2
+temp: 30536 67 51 3
+temp: 98210 -11 30 4
+temp: 56436 -39 20 5
+Average temperature for zipcode was -7F
+
+Welcome to Buildroot
+buildroot login: Running pipeline scenario
+Sending tasks to workers…
+Total expected cost: 5494 msec
+
+Welcome to Buildroot
+buildroot login: 98.42.49.79.40.29.40.32.90.97.63.18.78.25.29.56.84.32.59.46.84.38.4.35.22.57.70.55.95.51.30.48.94.58.72.53.99.83.61.4.90.32.46.58.22.10.33.46.49.75.100.95.:.........:.........:.........:.........:.........39.8.82.88.50.77.66.81.21.36.47.93.50.10.22.52.18.91.63.32.41.79.40.94.60.73.97.18.53.36.78.53.:.........:.........:.........:.........:.........Total elapsed time: 3282 msec
+Finished running all scenarios
+
+Welcome to Buildroot
+buildroot login:
+
+ +

Changing connection topology

+ +

The topology definition can be found in zmq_samples.camkes.

+
    +
  • To change the macaddress of a vm, VM[ID]_MACADDRESS needs to be updated
    • +
  • To change what vms a vm connects to: the vms need to be removed for each other’s topology_def
    • +
  • To create partitioned topologies, a separate topology_def needs to be created and separate calls to each of the macros in the file will need to be added
    • +
  • For VMs that are in the same topology, it may be possible for vms to read ethernet frames meant for other vms in the same topology.
    • +
  • If a vm is used in more than one topology it will still only have one network interface, but vms from one topology won’t be able to read frames sent over a separate topology.
    • +
  • It is not currently possible for two vms to be connected to each other in more than one topology. It is intended that this +will be changed if a topology becomes tied to a separate network interface in the future.
    • +
+ +
// VM0 is connected to vm1 and vm2
+#define VM0_topology_def(f) f(0,1,2)
+
+// VM1 is connected to vm0 and vm2
+#define VM1_topology_def(f) f(1,0,2)
+
+// VM2 is connected to vm0 and vm1
+#define VM2_topology_def(f) f(2,0,1)
+
+// topology_def is passed into all of the macros below
+#define topology_def(f) \
+    VM0_topology_def(f) \
+    VM1_topology_def(f) \
+    VM2_topology_def(f)
+
+// MAC Addresses that each eth0 will have.
+#define VM0_MACADDRESS "02:00:00:00:AA:01"
+#define VM1_MACADDRESS "02:00:00:00:AA:02"
+#define VM2_MACADDRESS "02:00:00:00:AA:03"
+
+component Init0 {
+    VM_INIT_DEF()
+
+    // This declares the send and receive interfaces for each connection from vm0
+    // This needs to be called in each Init* component that is referred to in the topology_def
+    VM_CONNECTION_COMPONENT_DEF(0,topology_def)
+}
+
+// A dummy component to serve as the to side of the connection that we create.
+component virtqueueinit {
+    provides VirtQueue q;
+}
+
+// ... Other component declarations
+
+assembly {
+    composition {
+        // ... The rest of the composition
+
+        // The instance of the dummy component
+        component virtqueueinit init;
+
+        // The connection that connects all of the interfaces together.
+        VM_CONNECTION_CONNECT_VMS(init.q, topology_def)
+
+    }
+
+    configuration {
+        // Specific configuration
+        VM_CONNECTION_CONFIG(init.q, topology_def)
+
+        vm0.init_cons = [
+            /* Initialise VirtNet eth0 device in vm0 */
+            VM_CONNECTION_INIT_HANDLER,
+        ];
+        // ... The rest of the configuration
+
+    }
+}
+
+
+ +

Underlying implementation

+

The underlying mechanisms/interfaces used to implement cross vm communication are:

+
    +
  • projects/vm/components/VM/configurations/connections.h: Contains the macro API used in zmq_samples.camkes
    • +
  • projects/projects_libs/libvirtqueue: Virtqueue implementation that takes buffers from a restricted address space.
    • +
  • projects/projects_libs/libvswitch: A library that resolves macaddresses to virtqueues with broadcast support.
    • +
  • projects/vm/components/Init/virtio_net_vswitch.c: VirtioNet vmm device. Uses libvirtqueue, libvswitch and libsel4camkes +to implement cross component communication
    • +
  • projects/vm/templates/seL3VirtQueues-from.template.c: Camkes template for a virtqueue connection end.
    • +
  • tools/camkes/libsel4camkes: Provides camkes bindings for libvirtqueue virtqueues backed by Camkes connector objects.
    • +
+ +

CakeML Filter Variant

+ +

A variant of this app that uses a CakeML component in place of the 3rd VM can +be built by providing an additional option to the build script:

+ +
$ ../init-build.sh -DCAMKES_VM_APP=zmq_samples -DCAKEML_FILTER=TRUE -DCAKEMLDIR=/path/to/cakeml
+
+ +

The CakeML component sits between the two VMs and proxies their traffic to each +other. Presently it doesn’t do any filtering.

+ +

The following versions of CakeML and HOL are known to work:

+ +
    +
  • CakeML: 66a35311787bb43f72e8e758209a4745f288cdfe
    • +
  • CakeML Binary Compiler: 1bb8663a0aeb377eb22aeb600de4bc536e647744
    • +
  • HOL: 7323105f50960bdec1b33c513576e5d1d313b62f
    • +
+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes-vm/zmq-samples.md b/projects/camkes-vm/zmq-samples.md deleted file mode 100644 index 6a0e3847396..00000000000 --- a/projects/camkes-vm/zmq-samples.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -parent: /projects/camkes-vm/ -title: ZeroMQ examples -repo: 'seL4/camkes-vm-examples' -include_file: 'apps/x86/zmq_samples/README.md' -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -{% include include_github_repo_markdown.md %} diff --git a/projects/camkes/cli.html b/projects/camkes/cli.html new file mode 100644 index 00000000000..bd30b2e2244 --- /dev/null +++ b/projects/camkes/cli.html @@ -0,0 +1,591 @@ + + + + + + + CAmkES CLI | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES CLI

+ +

The CAmkES CLI is a command line tool for initialising and managing CAmkES +projects. It is loosely based on the rust build tool “cargo”. It is structured +as a command line tool with various subcommands. Usage for each can be viewed +with camkes-cli <subcommand> --help.

+ +

For an example project that can be managed by the CLI, see: +https://github.com/sel4proj/camkes-cli-example

+ +

Examples

+ +

Create a new project from a template

+ +

This creates new directory named hello.

+ +
camkes-cli new hello --template hello_world
+
+ +

Initialise a fresh checkout of existing project

+ +
git clone https://github.com/sel4proj/camkes-cli-example
+cd camkes-cli-example
+camkes-cli init
+
+ +

Build a project for x86

+ +

Run from inside project directory:

+ +
camkes-cli build x86
+
+ +

Run a project in qemu-system-i386 (builds first)

+ +
camkes-cli run x86
+
+ +

Generate boilerplate for a component

+ +

Generate boilerplate for a component named BlahServer with some interfaces:

+ +
camkes-cli component BlahServer --dataport Buf b --consumes Signal sig
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/cli.md b/projects/camkes/cli.md deleted file mode 100644 index 8cb5718c119..00000000000 --- a/projects/camkes/cli.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -parent: /projects/camkes/ -redirect_from: - - /CAmkESCLI -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# CAmkES CLI - -The CAmkES CLI is a command line tool for initialising and managing CAmkES -projects. It is loosely based on the rust build tool "cargo". It is structured -as a command line tool with various subcommands. Usage for each can be viewed -with `camkes-cli --help`. - -For an example project that can be managed by the CLI, see: - - -## Examples - -### Create a new project from a template - - -This creates new directory named `hello`. - -```sh -camkes-cli new hello --template hello_world -``` - -### Initialise a fresh checkout of existing project - -```sh -git clone https://github.com/sel4proj/camkes-cli-example -cd camkes-cli-example -camkes-cli init -``` - -### Build a project for x86 - -Run from inside project directory: - -```sh -camkes-cli build x86 -``` - -### Run a project in qemu-system-i386 (builds first) - -```sh -camkes-cli run x86 -``` - -### Generate boilerplate for a component - -Generate boilerplate for a component named BlahServer with some interfaces: - -```sh -camkes-cli component BlahServer --dataport Buf b --consumes Signal sig -``` diff --git a/projects/camkes/components.html b/projects/camkes/components.html new file mode 100644 index 00000000000..f5f91e284c0 --- /dev/null +++ b/projects/camkes/components.html @@ -0,0 +1,2259 @@ + + + + + + + CAmkES Components | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Components

+ +

Example Applications

+ +

Most of these examples can be found on the examples & demos +page.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
adder
+
+
+

A simple ‘Hello world’ CAmkES application which demonstrates some basics of the CAmkES framework.

+ +
+
+ 
aeroplage
+
+
+

A CAmkES application which implements a prototype of a previous multi-level terminal for seL4.

+ +
+
+ 
alignment
+
+
+

A CAmkES application which tests if the stack is aligned properly by crashing on an unaligned stack.

+ +
+
+ 
attributes
+
+
+

A CAmkES application which demonstrates the use of aliasing attributes.

+ +
+
+ 
binary-semaphore
+
+
+

A CAmkES application which demonstrates how to use a binary semaphore to turn an asynchronous interface into a synchronous one.

+ +
+
+ 
cakeml_hello
+
+
+

A ‘Hello world’ CAmkES application which demonstrates the ability to run CakeML-based CAmkES components inside CAmkES.

+ +
+
+ 
cakeml_regex
+
+
+

A CAmkES application which demonstrates the use of CakeML to implement a CAmkES component which filters data between two different components.

+ +
+
+ 
cakeml_tipc
+
+
+

A CAmkES application which demonstrates the Transparent IPC protocol (TIPC) and the use of CakeML to implement a CAmkES component to filter data between two different CAmkES components.

+ +
+
+ 
cms-donate
+
+
+

A CAmkES application which demonstrates the donation of a scheduling context between a client and server via an intermediary under a Mixed Criticality Scheduling (MCS) environment.

+ +
+
+ 
cs-donate
+
+
+

A CAmkES application which demonstrates the donation of a scheduling context between a client and server under a Mixed Criticality Scheduling (MCS) environment.

+ +
+
+ 
cs-nodonate
+
+
+

A CAmkES application which demonstrates two CAmkES components running using their own scheduling contexts under a Mixed Criticality Scheduling (MCS) environment.

+ +
+
+ 
dataport
+
+
+

A CAmkES application which demonstrates an example of the usage of CAmkES dataports.

+ +
+
+ 
debug-simple
+
+
+

A CAmkES application which demonstrates the use of the seL4GDB connector to debug CAmkES components.

+ +
+
+ 
dhcp
+
+
+

A CAmkES application which demonstrates an example DHCP server.

+ +
+
+ 
dma-example
+
+
+

A CAmkES application which demonstrates the use of a CAmKES-allocated DMA pool.

+ +
+
+ 
epit
+
+
+

A CAmkES application which demonstrates a simple hardware driver CAmkES component for the EPIT timers on the KZM platform.

+ +
+
+ 
event
+
+
+

A CAmkES application which demonstrates an example of CAmkES events.

+ +
+
+ 
event-driven
+
+
+

A CAmkES application which demonstrates an example of a CAmkES event-driven application.

+ +
+
+ 
exchangestring
+
+
+

A CAmkES application which demonstrates how to pass string arguments between CAmkES components.

+ +
+
+ 
fdtgen
+
+
+

A CAmkES application which demonstrates an example on how to include a DTB blob and how to modify it.

+ +
+
+ 
filter
+
+
+

A CAmkES application which demonstrates the use of a CAmkES component to filter communication between two other CAmkES components.

+ +
+
+ 
global-imports
+
+
+

A CAmkES application which demonstrates an example of allowing CAmkES components to be globally imported using specific CMake macros.

+ +
+
+ 
hellorust
+
+
+

A CAmkES application which demonstrates an example of running a Rust application inside CAmkES.

+ +
+
+ 
hierarchical-attributes
+
+
+

A CAmkES application which demonstrates an example of hierarchical attributes in CAmKES.

+ +
+
+ 
hierarchical-components
+
+
+

A CAmkES application which demonstrates an example of hierarhical CAmkES components in CAmkES.

+ +
+
+ 
keyboard
+
+
+

A CAmkES application which demonstrates an example keyboard driver for x86 platforms.

+ +
+
+ 
lockserver
+
+
+

A CAmkES application which demonstrates an example system which contains a CAmkES component that manages a lock.

+ +
+
+ 
mcs-donate
+
+
+

A CAmkES application which demonstrates the donation of scheduling contexts betwen two clients and a server under a Mixed Criticality Scheduling (MCS) environment.

+ +
+
+ 
mcs-nodonate
+
+
+

A CAmkES application which demonstrates the three CAmkES components running using their own scheduling contexts under a Mixed Criticality Scheduling (MCS) environment.

+ +
+
+ 
multiassembly
+
+
+

A CAmkES application which demonstrates the ability to have two different ‘assembly’ blocks.

+ +
+
+ 
multiclient
+
+
+

A CAmkES application which demonstrates the ability to allow multiple clients to share one connection.

+ +
+
+ 
multiplier
+
+
+

A CAmkES application which demonstrates an example of using arrays as arguments for RPC functions between CAmkES components.

+ +
+
+ 
mutex
+
+
+

A CAmkES application which demonstrates the use of user-defined connectors in CAmkES to implement a lock.

+ +
+
+ 
periodic
+
+
+

A CAmkES application which demonstrates the periodic timeslices of CAmkES components under a Mixed Criticality Scheduling (MCS) environment.

+ +
+
+ 
picoserver
+
+
+

A CAmkES application which demonstrates a simple networking example which uses the PicoServer in the global-components repository.

+ +
+
+ 
pit
+
+
+

A CAmkES application which demonstrates a timer driver CAmkES component for the Programmable Interval Timer on x86 platforms.

+ +
+
+ 
reversestring
+
+
+

A CAmkES application which demonstrates dataport release and acquire semantics.

+ +
+
+ 
rotate
+
+
+

A CAmkES application which demonstrates the use of user-defined types as arguments of a RPC interface.

+ +
+
+ 
RPCOverMultiSharedData
+
+
+

A CAmkES application which demonstrates the use of the seL4RPCOverMultiSharedData connector to perform RPC using shared memory buffers between the client and server.

+ +
+
+ 
rumprun_ethernet
+
+
+

A CAmkES application which demonstrates a single TCP echo program that runs in a Rumprun unikernel instance on CAmkES.

+ +
+
+ 
rumprun_pthreads
+
+
+

A CAmKES application which demonstrates a simple pthreads program that runs in a Rumprun unikernel instance on CAmKES.

+ +
+
+ 
rumprun_rust
+
+
+

A CAmkES application which demonstrates a simple Rust ‘Hello world’ program that runs in a Rumprun unikernel instance on CAmkES.

+ +
+
+ 
serialserver
+
+
+

A CAmkES application which demonstrates the use of the SerialServer component in the global-components repository.

+ +
+
+ 
serialserver_loopback
+
+
+

A CAmkES application which demonstrates the use of the SerialServer component in the global-components repository looping back characters that it reads in from the serial device.

+ +
+
+ 
simple
+
+
+

A CAmkES application which demonstrates an example of a CAmkES RPC connection.

+ +
+
+ 
simplesingleaddressspace
+
+
+

A CAmkES application which demonstrates an example of a single address space CAmkES system which contains a RPC connection between its two components.

+ +
+
+ 
socket
+
+
+

A CAmkES application which demonstrates a user-defined dataport.

+ +
+
+ 
structs
+
+
+

A CAmkES application which demonstrates the use of structs and arrays for CAmkES component attribute types.

+ +
+
+ 
swapcounter
+
+
+

A CAmkES application which was used for demonstration purposes for a paper submission to Formal Methods 2015 but has since been modified.

+ +
+
+ 
terminal
+
+
+

A CAmkES application which serves as a prototype for a secure terminal system.

+ +
+
+ 
testbufvariant
+
+
+

A CAmkES application which is used to test dataports.

+ +
+
+ 
testcamkes438
+
+
+

A CAmkES application that is used to test a specific function of the CAmkES framework.

+ +
+
+ 
testcontrolname
+
+
+

A CAmkES application that is used to test if interfaces could be named with a particular suffix.

+ +
+
+ 
testdataportbifurcate
+
+
+

A CAmkES application that tests if we can have multiple dataports within a single component that maps to the same underlying physical memory.

+ +
+
+ 
testdataportmux
+
+
+

A CAmkES application that tests the ability to have multiple CAmkES components connected to the same dataport.

+ +
+
+ 
testdataportmuxflat
+
+
+

A CAmkES application that tests the ability to have N-to-M dataport connections in a single address space.

+ +
+
+ 
testdataportptrwrap
+
+
+

A CAmkES application that tests if dataport pointer wrapping and unwrapping functionality works on multiplexed dataports.

+ +
+
+ 
testdataportrpc
+
+
+

A CAmkES application that tests if we can back an seL4RPCCall connection with various types of dataports.

+ +
+
+ 
testfaulthandlers
+
+
+

A CAmkES application that tests if the fault handlers work correctly as intended.

+ +
+
+ 
testgrouping
+
+
+

A CAmkES application which tests for the various edge cases in grouping CAmkES components into single address spaces.

+ +
+
+ 
testgroupingcontrol
+
+
+

A CAmkES application which tests whether CAmkES components with a control thread work correctly when grouped in a single address spaces.

+ +
+
+ 
testhardwareinterrupt
+
+
+

A CAmkES application which tests if an application containing an seL4HardwareInterrupt successfully compiles.

+ +
+
+ 
testhwdataportlrgpages
+
+
+

A CAmkES application which tests whether or not large pages will be used to back a large dataport.

+ +
+
+ 
testnto1mmio
+
+
+

A CAmkES application that tests if an N-to-1 MMIO connection to a piece of hardware functions correctly.

+ +
+
+ 
testnto1overload
+
+
+

A CAmKES application that tests if N-to-1 connections involving multiple ends from a single CAmkES component uses distinct caps.

+ +
+
+ 
testrefin
+
+
+

A CAmKES application that tests the ‘refin’ parameter function in CAmkES procedure interfaces.

+ +
+
+ 
testreplycapprotection
+
+
+

A CAmkES application that tests the reply cap protection functionality.

+ +
+
+ 
testsel4notification
+
+
+

A CAmkES application that tests the seL4Notification connector.

+ +
+
+ 
testsingleaddressspaceheap
+
+
+

A CAmkES application that tests that the heaps of CAmkES components that share a single address space do not overlap.

+ +
+
+ 
teststringarrays
+
+
+

A CAmkES application that tests some unusual usages of string array parameters in procedure interfaces.

+ +
+
+ 
testsyscalls
+
+
+

A CAmkES application that serves as a testing sandbox for POSIX syscall functionality on CAmkES.

+ +
+
+ 
testunderscorename
+
+
+

A CAmkES application that tests if CAmkES components can have interface names prefixed with an underscore.

+ +
+
+ 
timeserver
+
+
+

A CAmkES application which demonstrates the use of the TimeServer componen fromthe global-components repository.

+ +
+
+ 
uart
+
+
+

A CAmkES application which demonstrates a UART driver CAmkES component for the KZM platform.

+ +
+
+ 
vgatest
+
+
+

A CAmkES application which demonstrates a minimal implementation for a text mode VGA terminal.

+ +
+ +

Reusable components

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
ClockServer
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to clock devices on a platform.

+ +
+
+ 
Ethdriver
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to an Ethernet device.

+ +
+
+ 
FileServer
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to a CPIO-based file system.

+ +
+
+ 
GPIOMUXServer
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to a GPIO and pin multiplexer controller.

+ +
+
+ 
PCIConfigIO
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to the PCI configuration space of a platform.

+ +
+
+ 
PicoServer
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to an IP stack, specifically, the PicoTCP TCP/IP stack.

+ +
+
+ 
ResetServer
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to a reset line controller.

+ +
+
+ 
RTC
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to a real-time clock device.

+ +
+
+ 
SerialServer
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to a serial device.

+ +
+
+ 
TimeServer
+
+
+

A CAmkES component which abstracts over and multiplexes client accesses to a timer device.

+ +
+
+ 
VirtQueue
+
+
+

A stub CAmkES component which is used to help initialise virtqueue connections.

+ +
+
+ 
Serial
+
+
+

Stub hardware CAmkES component that abstracts over a pc99-based serial device.

+ +
+
+ 
PIT
+
+
+

Stub hardware CAmkES component that abstracts over the x86 Programmable Interval Timer.

+ +
+ +

CAmkES Connectors

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
seL4Ethdriver
+
+
+

CAmkES connector which is used to connect clients to the Ethdriver component’s procedure interface.

+ +
+
+ Supported +
+
+ 
seL4GlobalAsynchCallback
+
+
+

CAmkES connector which is used to make the underlying seL4 notificationcapability available to the consuming side of the Event interface. This also allows the coupling of callback function that is called uponreceiving an Event.

+ +
+
+ Supported +
+
+ 
seL4GlobalAsync
+
+
+

CAmkES connector which is used to make the underlying seL4 notification capability available to the consuming side of the Event interface.

+ +
+
+ Supported +
+
+ 
seL4MessageQueue
+
+
+

CAmkES connector which allows the sending and queueing of user-defined messages from one component to another.

+ +
+
+ Supported +
+
+ 
seL4MultiSharedData
+
+
+

CAmkES connector which allows multiple dataports to be connected to a single components and also provides multiplexed access across the dataports.

+ +
+
+ Supported +
+
+ 
seL4RPCCallSignal
+
+
+

CAmkES connector which bundles a procedure interface with an event interface.

+ +
+
+ Supported +
+
+ 
seL4RPCDataport
+
+
+

CAmkES connector which bundles a procedure interface with a dataport interface.

+ +
+
+ Supported +
+
+ 
seL4RPCDataportSignal
+
+
+

CAmkES connector which bundles a procedure interface, event interface, and a dataport interface.

+ +
+
+ Supported +
+
+ 
seL4RPCOverMultiSharedData
+
+
+

CAmkES connector which uses shared memory to transfer data instead of the IPC buffer for procedure interfaces.

+ +
+
+ Supported +
+
+ 
seL4SharedDataWithCaps
+
+
+

CAmkES connector which allocates a shared memory region between components and also exposes the underlying frame caps.

+ +
+
+ Supported +
+
+ 
seL4VirtQueues
+
+
+

CAmkES connector which initialises a virtqueue connection between two components.

+ +
+
+ Supported +
+
+ 
seL4DirectCall
+
+
+

Used for RPC interfaces between grouped components. Each call becomes a direct function call.

+ +
+
+ Supported +
+
+ 
seL4Notification
+
+
+

Event connector where an seL4 Notification object is used for sending events. On the receiving end, a callback handler can be registerd or a thread can block waiting for events.

+ +
+
+ Supported +
+
+ 
seL4NotificationBind
+
+
+

Similar event connector to seL4Notification but the receiver has bound the Notification to its TCB.

+ +
+
+ Supported +
+
+ 
seL4NotificationNative
+
+
+

Similar event connector to seL4Notification but the receiver end can only call Poll or Wait on notification object.

+ +
+
+ Supported +
+
+ 
seL4NotificationQueue
+
+
+

seL4Endpoint object is used to queue notifications so that if the sender is sending faster than the receiver is receiving, unreceived events will accumulate in a counter.

+ +
+
+ Supported +
+
+ 
seL4RPCCall
+
+
+

Used for RPC interfaces where parameters will be marshalled into and out of IPC buffers and calls ocurr over seL4Endpoint objects.

+ +
+
+ Supported. There is also a CakeML implementation for the receiving end. +
+
+ 
seL4DTBHardware
+
+
+

Hardware connector to hardware component specified by a Device tree node. This will extract MMIO and potentially IRQ information for creating connections to the component.

+ +
+
+ Supported +
+
+ 
seL4RPCCallNoType
+
+
+

seL4 RPCCall connector but without requirement of single procedure interface. This allows a single receiver thread to handle multiple senders with different interfaces.

+ +
+
+ Supported +
+
+ 
seL4SharedData
+
+
+

seL4 Dataport connector. Creates a shared memory connection between components.

+ +
+
+ Supported +
+
+ 
seL4HardwareMMIO
+
+
+

seL4 Dataport connector to MMIO region. Creates a MMIO mapping for device registers into a component.

+ +
+
+ Supported +
+
+ 
seL4HardwareIOPort
+
+
+

seL4 Procedure connector for x86 IOPorts. Provides functions for performing IOPort instructions via seL4 invocations.

+ +
+
+ Supported +
+
+ 
seL4HardwareInterrupt
+
+
+

seL4 event connector for hardware interrupts. Provides interface for polling or blocking on interrupts and also for acknowledging IRQs.

+ +
+
+ Supported +
+
+ 
seL4IOAPICHardwareInterrupt
+
+
+

seL4 event connector for IOAPIC hardware interrupts. Specialised connector for dealing with IOAPIC interrupts.

+ +
+
+ Supported on x86 +
+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/components.md b/projects/camkes/components.md deleted file mode 100644 index 05dca7589de..00000000000 --- a/projects/camkes/components.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -parent: /projects/camkes/ -project: camkes -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- - - -# CAmkES Components - -## Example Applications - -Most of these examples can be found on the [examples & demos -page](../../examples.html). - -{% include component_list.md project='camkes' type='camkes-application' no_status=true %} - -## Reusable components - -{% include component_list.md project='camkes' type='camkes-component' no_status=true %} - -## CAmkES Connectors - -{% include component_list.md project='camkes' type='camkes-connector' %} diff --git a/projects/camkes/differences.html b/projects/camkes/differences.html new file mode 100644 index 00000000000..de4cb9285f9 --- /dev/null +++ b/projects/camkes/differences.html @@ -0,0 +1,778 @@ + + + + + + + Differences between CAmkES 2 and 3 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Differences between CAmkES 2 and 3

+ +

Rich Types for Settings

+ +

Previously all attribute settings were treated as strings by templates. +Settings are now interpreted as an appropriate python type.

+
// list
+foo.bar = [0x60, 0x64];
+
+// boolean
+moo.cow = true;
+
+// string
+baz.qux = "hello";
+
+// dict
+crazy.stuff = { "key" : ["polymorphic", 42, "list",
+                 {"hello":true} ] };
+
+// appropriate numeric type
+arithmetic.expressions = 1 << (2 ** 2) == 3 ? -2 : 0x9;
+
+ +

Arbitrary ids are no longer allowed as setting values:

+
a.b = c; // error
+
+ +

Parametrised Buf Type

+ +

The Buf dataport type can now be optionally parametrised by the +size (in bytes) of the dataport. The syntax for this is Buf(size). +If left unspecified, the default size is 4096 bytes.

+ +

It is an error to connect dataport interfaces of different sizes.

+ +

E.g.

+
component Foo {
+    dataport Buf(8192) dp;
+}
+
+component Bar {
+    dataport Buf(8192) dp;
+}
+
+assembly {
+    composition {
+        component Foo foo;
+        component Bar bar;
+        connection seL4SharedData conn(from foo.dp, to bar.dp);
+    }
+}
+
+ +

Asynch Connector Renamed

+ +

The seL4Asynch connector has been renamed to +seL4Notification.

+ +

Non-Volatile Dataports

+ +

Previously, c symbols used to access dataports had volatile pointer +types. Users were encouraged to use volatile pointers to prevent the +compiler optimizing away, or re-ordering, accesses to shared memory.

+ +

This is no longer the case. The c symbols referring to dataports are +regular (ie. non-volatile) pointer types, and programmers are required +to explicitly “acquire” and “release” dataports to prevent harmful +re-ordering (at both compile time and runtime). The motivations for this +change are: * Treating dataports as always volatile prevents the +compiler from re-ordering any accesses to them, even in cases where it +won’t affect the correctness of programs. Using non-volatile dataports +allows the compiler to make better optimizations. * Preventing compiler +reordering (ie. with volatile) is not sufficient to make shared memory +coherent in a multicore environment. Changes made to shared memory by +one core may become visible to other cores in a different order. * +Using functions from the standard library on dataports (e.g. passing a +string in a dataport to strlen) requires casting from a volatile +pointer to a regular pointer - an undefined operation in c.

+ +

For a dataport interface foo, a component has access to +foo_acquire() and foo_release() functions (they may +instead be macros). Call foo_acquire() between multiple reads +from a dataport, where the correct behaviour of the program depends on +the contents of the dataport possibly changing between reads. Call +foo_release() between multiple writes to a dataport, where the +correct behaviour of the program depends on writes preceding the +foo_release() in the program code being performed strictly before +the writes following it.

+ +

Many-to-Many Connections

+ +

There is new syntax for connections with multiple from/to sides. The +following fragments are equivalent (except for connection names):

+
connection seL4RPCCall foo(from a.x, to c.z);
+connection seL4RPCCall bar(from b.y, to c.z);
+
+
connection seL4RPCCall foobar(from a.x, from b.y, to c.z);
+
+ +

Both syntaxes are supported by CAmkES 3.

+ +

Hardware Component Configuration Attributes

+ +

The attributes for configuring hardware components have changed. Below +is a CAmkES 2 spec, followed by the equivalent CAmkES 3 spec. These +changes are not backwards compatible.

+ +

These component definitions are the same in CAmkES 2 and 3:

+
component Device {
+  hardware;
+  dataport Buf registers;
+  emits Interrupt interrupt;
+  provides IOPort port;
+}
+
+component Driver {
+    dataport Buf registers; consumes Interrupt interrupt; uses IOPort
+    port;
+}
+
+ +

The composition section of the spec is the same for CAmkES 2 and 3:

+
assembly {
+  composition {
+    component Device device;
+    component Driver driver;
+
+    connection seL4HardwareMMIO mmio(from driver.registers, to device.registers);
+    connection seL4HardwareInterrupt interrupt(from device.interrupt, to driver.interrupt);
+    connection seL4HardwareIOPort ioport(from driver.port, to device.port);
+  }
+  configuration {
+    // see below
+  }
+
+}
+
+ +

CAmkES 2 configuration:

+
configuration {
+  device.registers_attributes = "0x12345000:0x1000"; // string in format "paddr:size"
+  device.interrupt_attributes = 27;                  // irq number
+  device.port_attributes = "0x40:0x40";              // string in format "start_port:end_port"
+}
+
+ +

CAmkES 3 configuration:

+
configuration {
+  device.registers_paddr = 0x12345000;  // separate attribute for paddr and size
+  device.registers_size = 0x1000;
+  device.interrupt_irq_number = 27;     // attribute name has changed
+  device.port_attributes = "0x40:0x40"; // unchanged
+}
+
+ +

Interrupt API

+ +

In CAmkES 2, interrupts were abstracted as CAmkES events, emitted from a +hardware component. For a component with an interface foo +connected to an interrupt, components could call foo_wait(), +foo_poll(), and foo_reg_callback(), as with a regular +event.

+ +

In CAmkES 3, interrupts are still abstracted as events in the ADL +(CAmkES spec). Component implementations however, use a different +interface for interacting with interrupts than with regular event +interfaces. More specifically, a component with an interface foo +connected with the seL4HardwareInterrupt connection has access to +foo_acknowledge() which acknowledges the associated interrupt to +the kernel. In addition, the component implementation must provide a +definition of a function void foo_handler(void). The standard +event methods (foo_wait(), foo_poll(), and foo_reg_callback()) are not implemented for interrupts.

+ +

The user-provided function foo_handler() will be called by a +dedicated interrupt-handling thread (one thread per interface connected +with seL4HardwareInterrupt). Unlike callbacks registered with +*_reg_callback, interrupt handlers do not need to be explicitly +registered, and do not become unregistered after calling.

+ +

Hierarchical Components

+ +

The syntax for defining hierarchical components has changed in CAmkES 3. +CAmkES 2 had special connectors used to export an interface of a +sub-component:

+
component Serial {
+
+  // interface of this component
+  provides UartIface serial;
+
+  composition {
+
+    // internal components
+    component UartDevice uart_device;
+    component UartDriver uart_driver;
+
+    // internal connection
+    connection seL4HardwareMMIO conn(from uart_device.regs, to uart_driver.regs);
+
+    // export interface of driver component as interface of this component
+    connection ExportRPC exp(from uart_driver.uart, to serial);
+
+  }
+}
+
+ +

CAmkES 3 introduces special syntax for exposing interfaces of +sub-components:

+
component Serial {
+
+  // interface of this component
+  provides UartIface serial;
+
+  composition {
+
+    // internal components
+    component UartDevice uart_device;
+    component UartDriver uart_driver;
+
+    // internal connection
+    connection seL4HardwareMMIO conn(from uart_device.regs, to uart_driver.regs);
+
+    // export interface of driver component as interface of this component
+    export uart_driver.uart -> serial;
+
+  }
+}
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/differences.md b/projects/camkes/differences.md deleted file mode 100644 index cdb99645cc5..00000000000 --- a/projects/camkes/differences.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -parent: /projects/camkes/ -redirect_from: - - /CAmkESDifferences -archive: true -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- -# Differences between CAmkES 2 and 3 - - -## Rich Types for Settings - - -Previously all attribute settings were treated as strings by templates. -Settings are now interpreted as an appropriate python type. -```c -// list -foo.bar = [0x60, 0x64]; - -// boolean -moo.cow = true; - -// string -baz.qux = "hello"; - -// dict -crazy.stuff = { "key" : ["polymorphic", 42, "list", - {"hello":true} ] }; - -// appropriate numeric type -arithmetic.expressions = 1 << (2 ** 2) == 3 ? -2 : 0x9; -``` - -Arbitrary ids are no longer allowed as setting values: -```c -a.b = c; // error -``` - -## Parametrised Buf Type - - -The `Buf` dataport type can now be optionally parametrised by the -size (in bytes) of the dataport. The syntax for this is `Buf(size)`. -If left unspecified, the default size is 4096 bytes. - -It is an error to connect dataport interfaces of different sizes. - -E.g. -```c -component Foo { - dataport Buf(8192) dp; -} - -component Bar { - dataport Buf(8192) dp; -} - -assembly { - composition { - component Foo foo; - component Bar bar; - connection seL4SharedData conn(from foo.dp, to bar.dp); - } -} -``` - -## Asynch Connector Renamed - - -The `seL4Asynch` connector has been renamed to -`seL4Notification`. - -## Non-Volatile Dataports - - -Previously, c symbols used to access dataports had volatile pointer -types. Users were encouraged to use volatile pointers to prevent the -compiler optimizing away, or re-ordering, accesses to shared memory. - -This is no longer the case. The c symbols referring to dataports are -regular (ie. non-volatile) pointer types, and programmers are required -to explicitly "acquire" and "release" dataports to prevent harmful -re-ordering (at both compile time and runtime). The motivations for this -change are: * Treating dataports as always volatile prevents the -compiler from re-ordering any accesses to them, even in cases where it -won't affect the correctness of programs. Using non-volatile dataports -allows the compiler to make better optimizations. * Preventing compiler -reordering (ie. with volatile) is not sufficient to make shared memory -coherent in a multicore environment. Changes made to shared memory by -one core may become visible to other cores in a different order. * -Using functions from the standard library on dataports (e.g. passing a -string in a dataport to `strlen`) requires casting from a volatile -pointer to a regular pointer - an undefined operation in c. - -For a dataport interface `foo`, a component has access to -`foo_acquire()` and `foo_release()` functions (they may -instead be macros). Call `foo_acquire()` between multiple reads -from a dataport, where the correct behaviour of the program depends on -the contents of the dataport possibly changing between reads. Call -`foo_release()` between multiple writes to a dataport, where the -correct behaviour of the program depends on writes preceding the -`foo_release()` in the program code being performed strictly before -the writes following it. - -## Many-to-Many Connections - - -There is new syntax for connections with multiple from/to sides. The -following fragments are equivalent (except for connection names): -```c -connection seL4RPCCall foo(from a.x, to c.z); -connection seL4RPCCall bar(from b.y, to c.z); -``` -```c -connection seL4RPCCall foobar(from a.x, from b.y, to c.z); -``` - -Both syntaxes are supported by CAmkES 3. - -## Hardware Component Configuration Attributes - - -The attributes for configuring hardware components have changed. Below -is a CAmkES 2 spec, followed by the equivalent CAmkES 3 spec. These -changes are not backwards compatible. - -These component definitions are the same in CAmkES 2 and 3: -```c -component Device { - hardware; - dataport Buf registers; - emits Interrupt interrupt; - provides IOPort port; -} - -component Driver { - dataport Buf registers; consumes Interrupt interrupt; uses IOPort - port; -} -``` - -The composition section of the spec is the same for CAmkES 2 and 3: -```c -assembly { - composition { - component Device device; - component Driver driver; - - connection seL4HardwareMMIO mmio(from driver.registers, to device.registers); - connection seL4HardwareInterrupt interrupt(from device.interrupt, to driver.interrupt); - connection seL4HardwareIOPort ioport(from driver.port, to device.port); - } - configuration { - // see below - } - -} -``` - -CAmkES 2 configuration: -```c -configuration { - device.registers_attributes = "0x12345000:0x1000"; // string in format "paddr:size" - device.interrupt_attributes = 27; // irq number - device.port_attributes = "0x40:0x40"; // string in format "start_port:end_port" -} -``` - -CAmkES 3 configuration: -```c -configuration { - device.registers_paddr = 0x12345000; // separate attribute for paddr and size - device.registers_size = 0x1000; - device.interrupt_irq_number = 27; // attribute name has changed - device.port_attributes = "0x40:0x40"; // unchanged -} -``` - -## Interrupt API - - -In CAmkES 2, interrupts were abstracted as CAmkES events, emitted from a -hardware component. For a component with an interface `foo` -connected to an interrupt, components could call `foo_wait()`, -`foo_poll()`, and `foo_reg_callback()`, as with a regular -event. - -In CAmkES 3, interrupts are still abstracted as events in the ADL -(CAmkES spec). Component implementations however, use a different -interface for interacting with interrupts than with regular event -interfaces. More specifically, a component with an interface `foo` -connected with the `seL4HardwareInterrupt` connection has access to -`foo_acknowledge()` which acknowledges the associated interrupt to -the kernel. In addition, the component implementation must provide a -definition of a function `void foo_handler(void)`. The standard -event methods (`foo_wait()`, `foo_poll()`, and `foo_reg_callback()`) are not implemented for interrupts. - -The user-provided function `foo_handler()` will be called by a -dedicated interrupt-handling thread (one thread per interface connected -with `seL4HardwareInterrupt`). Unlike callbacks registered with -`*_reg_callback`, interrupt handlers do not need to be explicitly -registered, and do not become unregistered after calling. - -## Hierarchical Components - - -The syntax for defining hierarchical components has changed in CAmkES 3. -CAmkES 2 had special connectors used to export an interface of a -sub-component: -```c -component Serial { - - // interface of this component - provides UartIface serial; - - composition { - - // internal components - component UartDevice uart_device; - component UartDriver uart_driver; - - // internal connection - connection seL4HardwareMMIO conn(from uart_device.regs, to uart_driver.regs); - - // export interface of driver component as interface of this component - connection ExportRPC exp(from uart_driver.uart, to serial); - - } -} -``` - -CAmkES 3 introduces special syntax for exposing interfaces of -sub-components: -```c -component Serial { - - // interface of this component - provides UartIface serial; - - composition { - - // internal components - component UartDevice uart_device; - component UartDriver uart_driver; - - // internal connection - connection seL4HardwareMMIO conn(from uart_device.regs, to uart_driver.regs); - - // export interface of driver component as interface of this component - export uart_driver.uart -> serial; - - } -} -``` diff --git a/projects/camkes/features.html b/projects/camkes/features.html new file mode 100644 index 00000000000..7476052adca --- /dev/null +++ b/projects/camkes/features.html @@ -0,0 +1,947 @@ + + + + + + + CAmkES Features | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Features

+ +

CAmkES Architecture Description Language (ADL)

+ +

Features of the CAmkES ADL are listed below. Features that are more experimental +may not be compatible with the CDL-refinement CAmkES tooling. The Status field for +each feature aims to indicate any known compatibility issues related to a feature.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
Assembly
+
+
+

An assembly is a top level component system description. It contains a complete description of a full system.

+ +
+
+ Supported +
+
+
Composition
+
+
+

A container for the component and connector instantiations that form a system.

+ +
+
+ Supported +
+
+
Configuration
+
+
+

A container for describing settings. This is a syntactic element to hold the assignment of attributes for a given system.It is expressed inside an assembly block.

+ +
+
+ Supported +
+
+
Component definition
+
+
+

A type of functional entity. ‘Component’ is used colloquially to refer to both types and instances, but in a formal sense ‘component’ refers only to the type.

+ +
+
+ Supported +
+
+
Hierarchical components
+
+
+

A component can contain its own composition and configuration sections that can define components and connections that are in a different namespace from the toplevel composition and configuration namespaces. Each component instance is still a separate component. The top level component type can then select internal interfaces to export as its own interfaces.

+ +
+
+ Mostly supported. There are some known template bugs where a component exporting dataport interfaces is also required to have a connection to the dataport. +
+
+
Component Groups
+
+
+

A Group combines components into a single underlying process so they share an address space. This can reduce communication costs due to reduced context switching requirements, but components in a group are required to mutually trust each other.

+ +
+
+ Mostly supported. Connector implementations need to be aware that they are being used in a group component context. There are also issues with variable storage as some global variables will be defined for each component instance in the group, and threads that call across component boundaries may access incorrect variable instances. +
+
+
Hardware components
+
+
+

A hardware component represents an interface to hardware in the form of a component. Declaring a component with the hardware keyword creates a hardware component.

+ +
+
+ Supported +
+
+
Component Interfaces
+
+
+

An abstract exposed interaction point of a component. The subcategories of interface are procedure, event and dataport.

+ +
+
+ Supported +
+
+
Exported Interfaces
+
+
+

An interface of a compound component that is not implemented by that component, but is an alias for internal instance’s interface.

+ +
+
+ Supported +
+
+
Optional Interfaces
+
+
+

Interfaces of components can be made optional using the maybe keyword. Optional interfaces do not need to be connected to any other interfaces.

+ +
+
+ Supported +
+
+
Procedure IDL
+
+
+

An interface with function call semantics use procedures which consist of a series of methods that can be invoked independently. Procedures are defined within the ADL which has a IDL subset for defining methods and parameters.

+ +
+
+ Supported +
+
+
Attributes
+
+
+

An attribute is a configuration option that can be set on a component, connection or procedure definition. It is used to pass configuration information through to the underlying implementations.

+ +
+
+ Supported +
+
+
Structured attributes
+
+
+

Attribute types support struct- and array-like declarations that support bundling and variable length attribute definitions.

+ +
+
+ Supported +
+
+
Default attribute values
+
+
+

Attribute definitions can also provide default settings. These defaults are used in the absence attribute settings.

+ +
+
+ Supported for component and connection attributes +
+
+
Synchronization Primitives
+
+
+

CAmkES provides three primitives for intra-component mutual exclusion and synchronization. Mutexes, semaphores, and binary semaphores are declared similarly to attributes of a component definition.

+ +
+
+ Supported +
+
+
`include` statements
+
+
+

include statements are used to declare source language include dependencies on component and procedure definitions. These are used when CAmkES is using types defined by another language.

+ +
+
+ Supported, but only used with C header files. +
+
+
Connector definitions
+
+
+

A type of link between instances. A connector implements the transportation for the interfaces it is connected between.

+ +
+
+ Supported. +
+
+
Connections
+
+
+

An instantiation of a connector. Connections connect two or more instances together via their interfaces.

+ +
+
+ Supported. +
+
+
Imports
+
+
+

import statements are used to define an assembly over multiple .camkes files and combine them together into a single AST.

+ +
+
+ Supported. It is possible to provide an import path argument to the camkes tool for where to search for files to import. +
+
+
C-Preprocessed ADL files
+
+
+

The C Preprocessor is run over the ADL files before the parser starts parsing them.

+ +
+
+ Supported. Because of the C-Preprocessor, the ADL ignores lines starting with #. This is not a valid comment syntax. +
+
+
Query syntax and plugins
+
+
+

The parser supports adding plugins that can provide configuration values via a setting querying syntax. A plugin is able to respond to a query with a valid configuration value.

+ +
+
+ Supported. Currently only 1 plugin exists, fdtQueryEngine, for querying values out of a Flattened device tree (FDT). +
+ +

See also the list of CAmkES components.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/features.md b/projects/camkes/features.md deleted file mode 100644 index 09e6c12cd6c..00000000000 --- a/projects/camkes/features.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -parent: /projects/camkes/ -project: camkes -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- - -# CAmkES Features - -### CAmkES Architecture Description Language (ADL) - -Features of the CAmkES ADL are listed below. Features that are more experimental -may not be compatible with the CDL-refinement CAmkES tooling. The Status field for -each feature aims to indicate any known compatibility issues related to a feature. - -{% include component_list.md project='camkes' list='features' type='adl-feature' code=false %} - -See also the list of [CAmkES components](components.html). diff --git a/projects/camkes/hardware.html b/projects/camkes/hardware.html new file mode 100644 index 00000000000..8dbe340abbd --- /dev/null +++ b/projects/camkes/hardware.html @@ -0,0 +1,551 @@ + + + + + + + Supported platforms | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Supported platforms

+ +

The CAmkES component platform is supported by all seL4-supported +platforms.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/hardware.md b/projects/camkes/hardware.md deleted file mode 100644 index eb86219c9c5..00000000000 --- a/projects/camkes/hardware.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- -# Supported platforms - -The CAmkES component platform is supported by all [seL4-supported -platforms](../../Hardware/index.html). \ No newline at end of file diff --git a/projects/camkes/imgs b/projects/camkes/imgs deleted file mode 120000 index 0c57936981b..00000000000 --- a/projects/camkes/imgs +++ /dev/null @@ -1 +0,0 @@ -../../_repos/sel4/camkes-tool/docs/imgs/ \ No newline at end of file diff --git a/projects/camkes/imgs/assembly.png b/projects/camkes/imgs/assembly.png new file mode 100644 index 00000000000..f854d032273 Binary files /dev/null and b/projects/camkes/imgs/assembly.png differ diff --git a/projects/camkes/imgs/attribute.png b/projects/camkes/imgs/attribute.png new file mode 100644 index 00000000000..0b19cf992a9 Binary files /dev/null and b/projects/camkes/imgs/attribute.png differ diff --git a/projects/camkes/imgs/component.png b/projects/camkes/imgs/component.png new file mode 100644 index 00000000000..d9d3997b0d2 Binary files /dev/null and b/projects/camkes/imgs/component.png differ diff --git a/projects/camkes/imgs/composition.png b/projects/camkes/imgs/composition.png new file mode 100644 index 00000000000..4db4bad9ce9 Binary files /dev/null and b/projects/camkes/imgs/composition.png differ diff --git a/projects/camkes/imgs/connection.png b/projects/camkes/imgs/connection.png new file mode 100644 index 00000000000..d765b3162e3 Binary files /dev/null and b/projects/camkes/imgs/connection.png differ diff --git a/projects/camkes/imgs/dataport.png b/projects/camkes/imgs/dataport.png new file mode 100644 index 00000000000..f46faf26c61 Binary files /dev/null and b/projects/camkes/imgs/dataport.png differ diff --git a/projects/camkes/imgs/direction.png b/projects/camkes/imgs/direction.png new file mode 100644 index 00000000000..cf13ba24300 Binary files /dev/null and b/projects/camkes/imgs/direction.png differ diff --git a/projects/camkes/imgs/echo.svg b/projects/camkes/imgs/echo.svg new file mode 100644 index 00000000000..f696b1116d4 --- /dev/null +++ b/projects/camkes/imgs/echo.svg @@ -0,0 +1,106 @@ + + + + + + + + + + + echo + client + + + + + + diff --git a/projects/camkes/imgs/event.png b/projects/camkes/imgs/event.png new file mode 100644 index 00000000000..9264b89530e Binary files /dev/null and b/projects/camkes/imgs/event.png differ diff --git a/projects/camkes/imgs/instance.png b/projects/camkes/imgs/instance.png new file mode 100644 index 00000000000..06682cbdf8c Binary files /dev/null and b/projects/camkes/imgs/instance.png differ diff --git a/projects/camkes/imgs/method.png b/projects/camkes/imgs/method.png new file mode 100644 index 00000000000..14c65d32a90 Binary files /dev/null and b/projects/camkes/imgs/method.png differ diff --git a/projects/camkes/imgs/parameter.png b/projects/camkes/imgs/parameter.png new file mode 100644 index 00000000000..d02f500c8e3 Binary files /dev/null and b/projects/camkes/imgs/parameter.png differ diff --git a/projects/camkes/imgs/procedure.png b/projects/camkes/imgs/procedure.png new file mode 100644 index 00000000000..29463199fcd Binary files /dev/null and b/projects/camkes/imgs/procedure.png differ diff --git a/projects/camkes/imgs/setting.png b/projects/camkes/imgs/setting.png new file mode 100644 index 00000000000..fdf3d5324a9 Binary files /dev/null and b/projects/camkes/imgs/setting.png differ diff --git a/projects/camkes/imgs/type.png b/projects/camkes/imgs/type.png new file mode 100644 index 00000000000..496c965d7c4 Binary files /dev/null and b/projects/camkes/imgs/type.png differ diff --git a/projects/camkes/index.html b/projects/camkes/index.html new file mode 100644 index 00000000000..eb072ea2358 --- /dev/null +++ b/projects/camkes/index.html @@ -0,0 +1,613 @@ + + + + + + + CAmkES | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES

+ +

CAmkES stands for component architecture for microkernel-based embedded systems. +It is a software development and runtime framework for quickly and reliably +building microkernel-based multi-server (operating) systems. It follows a +component-based software engineering approach, resulting in a system that is +modelled as a set of interacting software components. These software components +have explicit interaction interfaces and a system design that explicitly details +the connections between the components.

+ +

The development framework provides:

+ +
    +
  • a language to describe component interfaces, components, and whole +component-based systems
    • +
  • a tool that processes these descriptions to combine programmer-provided +component code with generated scaffolding and glue code to build a complete, +bootable, system image
    • +
  • full integration in the seL4 environment and build system
    • +
+ +

Overview

+ +

To get started with CAmkES we recommend following the CAmkES +tutorial.

+ +

The following additional resources are available:

+ + + +

Get CAmkES

+ + + +
mkdir camkes-project
+cd camkes-project
+repo init -u https://github.com/seL4/camkes-manifest.git
+repo sync
+
+ +

Build and run simple application

+ +

The following will configure, build, and run a simple example CAmkES +system:

+ +
cd camkes-project
+mkdir build
+cd build
+../init-build.sh -DPLATFORM=sabre -DAARCH32=1 -DCAMKES_APP=adder -DSIMULATION=1
+ninja
+./simulate
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/index.md b/projects/camkes/index.md deleted file mode 100644 index cb6c20d8427..00000000000 --- a/projects/camkes/index.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -redirect_from: - - /CAmkES/ -project: camkes -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# CAmkES - -CAmkES stands for component architecture for microkernel-based embedded systems. -It is a software development and runtime framework for quickly and reliably -building microkernel-based multi-server (operating) systems. It follows a -component-based software engineering approach, resulting in a system that is -modelled as a set of interacting software components. These software components -have explicit interaction interfaces and a system design that explicitly details -the connections between the components. - -The development framework provides: - -- a language to describe component interfaces, components, and whole - component-based systems -- a tool that processes these descriptions to combine programmer-provided - component code with generated scaffolding and glue code to build a complete, - bootable, system image -- full integration in the seL4 environment and build system - -## Overview - -To get started with CAmkES we recommend following the [CAmkES -tutorial](../../Tutorials/hello-camkes-0.html). - -The following additional resources are available: - -- [Terminology and Glossary](manual.md#terminology) -- [CAmkES Manual](manual.md) -- List of [CAmkES features](features.md) -- List of pre-build [CAmkES components](components.md) -- [Virtual Machines](../virtualization/index.md) as CAmkES components -- [Visual CAmkES](visual-camkes/), a tool for visualising the components and - connections making up an application -- [Command Line Interface](cli.md) of the CAmkES tool -- [Implementation](internals.md) - -## Get CAmkES - -- Make sure that you already have the tools to [build seL4 and - CAmkES](../buildsystem/host-dependencies.html). -- Download CAmkES: - -```sh -mkdir camkes-project -cd camkes-project -repo init -u https://github.com/seL4/camkes-manifest.git -repo sync -``` - -## Build and run simple application - -The following will configure, build, and run a simple example CAmkES -system: - -```sh -cd camkes-project -mkdir build -cd build -../init-build.sh -DPLATFORM=sabre -DAARCH32=1 -DCAMKES_APP=adder -DSIMULATION=1 -ninja -./simulate -``` \ No newline at end of file diff --git a/projects/camkes/internals.html b/projects/camkes/internals.html new file mode 100644 index 00000000000..9d487e87882 --- /dev/null +++ b/projects/camkes/internals.html @@ -0,0 +1,762 @@ + + + + + + + CAmkES Internals | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Internals

+ +

Overview

+ +

From the top, the CAmkES tool (typically found in “tools/camkes/camkes.sh”) is a program that generates a single file that makes up part of the source of an seL4 application. There are a variety of types of files it can generate:

+ +
    +
  • a capdl spec describing the cap distribution of the entire + CAmkES spec
    • +
  • a C file containing generated glue code for a component or + connector
    • +
  • a Makefile that knows how to invoke the CAmkES tool to generate + all the files required to compile the application (besides the + Makefile itself)
    • +
+ +

A typical build of a CAmkES application looks like:

+ +
    +
  1. +

    Generate makefile (this file will be called “camkes-gen.mk”)

    +
    2. +
  2. +

    Invoke generated makefile

    + +
      +
    1. Copy sources into build directory
      2. +
    2. Generated glue code for components and connectors
      3. +
    3. Compile each component
      4. +
    4. Run CapDL filters
      5. +
    5. Generate CapDL spec
      6. +
    6. Compile CapDL loader
      7. +
    +
    3. +
+ +

Caching

+ +

Remember that the CAmkES tool only generates one file each time it’s +run, and in a single build it’s typically run many times. This means, +all the input files must be parsed again for each output file. The CapDL +database is built up by logic in the templates that generate glue code, +which means that when the capdl spec is generated, all the templates +must be re-instantiated to get the spec into the right state. This all +seems to unnecessarily repeat a lot of work.

+ +

To get around this, CAmkES contains several caches:

+ +

CAmkES Accelerator

+ +

Output files are cached with keys computed from hashes of the CAmkES +spec. This prevents re-generating most files during a single build of a +CAmkES app.

+ +

Data Structure Cache

+ +

This stores the AST and CapDL database persistently (using pickle) +across each invocation of the CAmkES tool in a single build of a CAmkES +app. This removes the need to parse the CAmkES spec multiple times in a +single build, and also removes the need to re-instantiate component and +connector templates to re-build the CapDL database.

+ +

Creating Component Address Spaces

+ +

CAmkES creates a CapDL spec representing the entire application (ie. all +components and connections). Part of the spec is the hierarchy of paging +objects comprising the address space of each component. This is actually +done by the python CapDL library. After each component is compiled, but +before the CapDL Filters (see below) are applied, +the python capdl library is invoked (search for get_spec) to inspect +the ELF file produced by compiling the component and create all the +paging structures it needs.

+ +

Collapse Shared Frames

+ +

Dataport connections in CAmkES establish a region of shared memory +between components. When a pair of components share memory, there must +be common frames mapped into both of their address spaces. When each +component gets compiled, any dataports are just treated as an +appropriately sized buffer. We need a way to inform the system +initializer (the CapDL Loader) that when setting up these components’ +address spaces, to make the vaddr of the symbol associated with the +dataport in each component map to the same physical memory. During +template instantiation, a database of shared memory regions is +populated. The dataport templates all update this database with the +regions of shared memory they require. The “Collapse Shared Frames” +filter queries this database to find all the regions of shared memory, +then updates the CapDL database, changing memory mappings in the address +space of one component, so it points to the frames already mapped into +the address space of the other component. The frames in the first +component are then removed from the spec.

+ +

Remove TCB Caps

+ +

CAmkES has the option to prevent components from being given a cap to +their own TCB. This is implemented as a CapDL Filter, which examines the +cspace (CNode hierarchy) of each component (really each TCB, as +components may have several threads), and removes any caps to any TCBs +that are part of that component.

+ +

Guard Pages

+ +

This filter adds guard pages around the stacks of all threads. For each +thread in the system, the ELF that contains the program that will run on +that thread contains a symbol identifying the stack for that thread. +This filter looks up the vaddr and size of that symbol in the ELF, and +modifies the CapDL spec to make sure there’s no frame mapped in +immediately before or after the stack.

+ +

Template Context

+ +

The python-looking functions called from within templates (e.g. +alloc_cap, register_shared_variable) are actually keys in a dict +defined here: +https://github.com/seL4/camkes-tool/blob/master/camkes/runner/Context.py. +There are even some values (such as seL4_EndpointObject), modules (such +as sys), and seemingly built-in functions (e.g. zip) passed through +using this dict. You can update this dict to add new functions to the +template context. Some of these functions are called “in the context” of +the template they are instantiating. That is, for component and +connector templates, the generated code will be part of a single +component (each connector has a separate template for each side of the +connection). The most common example of this is when allocating a cap, +the cnode/cspace that will contain the cap isn’t passed to alloc_cap in +the template code, but rather implied by the component for which the +template is being instantiated.

+ +

Object Space and Cap Space

+ +

A template context is created with an “object space” and “cap space”. +These are terms from the python CapDL library. An object space tracks +all the objects that will exist in the system the CapDL spec describes. +There is a single object space for an entire CAmkES application. A cap +space tracks all the caps that will be placed in a particular cspace. +There is one cap space for each component. When calling alloc_cap in a +template on behalf of a component, the cap is placed in that component’s +cap space. The resulting CapDL spec will include in one of that +component’s CNodes, an entry for the allocated cap.

+ +

Template Functions

+ +

Here are some of the complicated functions in the template context:

+ +

alloc_obj(name, type)

+ +

Updates the CapDL database to contain a new object with a given name and +type, returning a (python) reference to that object. Doesn’t create any +caps.

+ +
/*- set ep = alloc_obj("my_ep", seL4_EndpointObject) -*/
+
+ +

alloc_cap(name, object)

+ +

Updates the CapDL database, adding a named cap to a given object to the +current component’s cap space, returning the CPtr of the cap.

+
// continues from above
+/*- set ep_cap = alloc_cap("my_ep_cap", ep) -*/
+seL4_Wait(/*? ep_cap ?*/);
+
+ +

alloc(name, type)

+ +

Effectively equivalent to alloc_cap(name, alloc_obj(name, type))

+ +

Simple

+ +

Simple is an interface in the seL4 libraries for accessing information +about your environment, typically about which capabilities are +available. CAmkES has an implementation of simple which a component can +use to access (some of) its caps. It’s implemented as a jinja template: +https://github.com/seL4/camkes-tool/blob/master/camkes/templates/component.simple.c

+ +

A component instance can be built with this simple implementation by +adding the following to the assembly:

+
configuration {
+   instance_name.simple = true;
+}
+
+ +

Template Instantiation Order

+ +

CAmkES instantiates templates in the following order: makefile, +components, connections, simple, capdl. The makefile has to come first +since it defines the build rules that instantiate all the other +templates. Simple must come after components and connections as it needs +to generate code to give access to caps allocated in component and +connection templates. Capdl must be last as it needs to be run after +compiling all components (including code generated by the simple +template). Since each template may be instantiated while producing any +output file, in order for caching to work correctly, the order of +template instantiation must be deterministic, at least in a single +invocation of the CAmKES-tool.

+ +

Note that components and connections will be instantiated in arbitrary +(but deterministic) order. An implication of this, is that if multiple +components want a cap to the same object (e.g. an endpoint which two +components use to communicate), each template that needs to talk about a +cap to the object must first allocate it unless it’s already allocated. +This is because you can’t talk about a cap to an object until that +object has been allocated. Typically in such a situation, you’ll see the +following template code on both sides of the connection:

+
/*- set ep = alloc_obj('ep_obj_name', seL4_EndpointObject) -*/
+/*- set ep_cap = alloc_cap('this_components_ep_cap', ep) -*/
+
+// do something with ep_cap
+
+ +

Looking at the code, it appears the endpoint will be allocated twice, as +both sides of the connection will call alloc_obj. Digging deeper into +the implementation of alloc_obj, we see it calls a function called +guard. guard is a bit of a misnomer. A more appropriate name might be +allocate_unless_already_allocated. It checks whether there’s already +an object by the given name, returns the object if it exists, otherwise +allocates and returns it.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/internals.md b/projects/camkes/internals.md deleted file mode 100644 index 15b4120106f..00000000000 --- a/projects/camkes/internals.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -parent: /projects/camkes/ -redirect_from: - - /CAmkESInternals -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# CAmkES Internals - -## Overview - - -From the top, the CAmkES tool (typically found in "tools/camkes/camkes.sh") is a program that generates a **single** file that makes up part of the source of an seL4 application. There are a variety of types of files it can generate: - -- a capdl spec describing the cap distribution of the entire - CAmkES spec -- a C file containing generated glue code for a component or - connector -- a Makefile that knows how to invoke the CAmkES tool to generate - all the files required to compile the application (besides the - Makefile itself) - -A typical build of a CAmkES application looks like: - -1. Generate makefile (this file will be called "camkes-gen.mk") - -2. Invoke generated makefile - - 1. Copy sources into build directory - 2. Generated glue code for components and connectors - 3. Compile each component - 4. Run CapDL filters - 5. Generate CapDL spec - 6. Compile CapDL loader - -## Caching - - -Remember that the CAmkES tool only generates one file each time it's -run, and in a single build it's typically run many times. This means, -all the input files must be parsed again for each output file. The CapDL -database is built up by logic in the templates that generate glue code, -which means that when the capdl spec is generated, all the templates -must be re-instantiated to get the spec into the right state. This all -seems to unnecessarily repeat a lot of work. - -To get around this, CAmkES contains several caches: - -### CAmkES Accelerator - - -Output files are cached with keys computed from hashes of the CAmkES -spec. This prevents re-generating most files during a single build of a -CAmkES app. - -### Data Structure Cache - - -This stores the AST and CapDL database persistently (using pickle) -across each invocation of the CAmkES tool in a single build of a CAmkES -app. This removes the need to parse the CAmkES spec multiple times in a -single build, and also removes the need to re-instantiate component and -connector templates to re-build the CapDL database. - -## Creating Component Address Spaces - - -CAmkES creates a CapDL spec representing the entire application (ie. all -components and connections). Part of the spec is the hierarchy of paging -objects comprising the address space of each component. This is actually -done by the python CapDL library. After each component is compiled, but -before the CapDL Filters (see below) are applied, -[the python capdl library is invoked (search for get_spec)](https://github.com/seL4/camkes-tool/blob/master/camkes/runner/__main__.py) to inspect -the ELF file produced by compiling the component and create all the -paging structures it needs. - - -### Collapse Shared Frames - - -Dataport connections in CAmkES establish a region of shared memory -between components. When a pair of components share memory, there must -be common frames mapped into both of their address spaces. When each -component gets compiled, any dataports are just treated as an -appropriately sized buffer. We need a way to inform the system -initializer (the CapDL Loader) that when setting up these components' -address spaces, to make the vaddr of the symbol associated with the -dataport in each component map to the same physical memory. During -template instantiation, a database of shared memory regions is -populated. The dataport templates all update this database with the -regions of shared memory they require. The "Collapse Shared Frames" -filter queries this database to find all the regions of shared memory, -then updates the CapDL database, changing memory mappings in the address -space of one component, so it points to the frames already mapped into -the address space of the other component. The frames in the first -component are then removed from the spec. - -### Remove TCB Caps - - -CAmkES has the option to prevent components from being given a cap to -their own TCB. This is implemented as a CapDL Filter, which examines the -cspace (CNode hierarchy) of each component (really each TCB, as -components may have several threads), and removes any caps to any TCBs -that are part of that component. - -### Guard Pages - - -This filter adds guard pages around the stacks of all threads. For each -thread in the system, the ELF that contains the program that will run on -that thread contains a symbol identifying the stack for that thread. -This filter looks up the vaddr and size of that symbol in the ELF, and -modifies the CapDL spec to make sure there's no frame mapped in -immediately before or after the stack. - -## Template Context - - -The python-looking functions called from within templates (e.g. -`alloc_cap`, `register_shared_variable`) are actually keys in a dict -defined here: -. -There are even some values (such as `seL4_EndpointObject`), modules (such -as `sys`), and seemingly built-in functions (e.g. `zip`) passed through -using this dict. You can update this dict to add new functions to the -template context. Some of these functions are called "in the context" of -the template they are instantiating. That is, for component and -connector templates, the generated code will be part of a single -component (each connector has a separate template for each side of the -connection). The most common example of this is when allocating a cap, -the cnode/cspace that will contain the cap isn't passed to `alloc_cap` in -the template code, but rather implied by the component for which the -template is being instantiated. - -### Object Space and Cap Space - - -A template context is created with an "object space" and "cap space". -These are terms from the python CapDL library. An object space tracks -all the objects that will exist in the system the CapDL spec describes. -There is a single object space for an entire CAmkES application. A cap -space tracks all the caps that will be placed in a particular cspace. -There is one cap space for each component. When calling `alloc_cap` in a -template on behalf of a component, the cap is placed in that component's -cap space. The resulting CapDL spec will include in one of that -component's CNodes, an entry for the allocated cap. - -### Template Functions - - -Here are some of the complicated functions in the template context: - -#### alloc_obj(name, type) - - -Updates the CapDL database to contain a new object with a given name and -type, returning a (python) reference to that object. Doesn't create any -caps. - -``` -/*- set ep = alloc_obj("my_ep", seL4_EndpointObject) -*/ -``` - -#### alloc_cap(name, object) - - -Updates the CapDL database, adding a named cap to a given object to the -current component's cap space, returning the CPtr of the cap. -``` -// continues from above -/*- set ep_cap = alloc_cap("my_ep_cap", ep) -*/ -seL4_Wait(/*? ep_cap ?*/); -``` - -#### alloc(name, type) - - -Effectively equivalent `to alloc_cap(name, alloc_obj(name, type))` - -## Simple - - -Simple is an interface in the seL4 libraries for accessing information -about your environment, typically about which capabilities are -available. CAmkES has an implementation of simple which a component can -use to access (some of) its caps. It's implemented as a jinja template: - - -A component instance can be built with this simple implementation by -adding the following to the assembly: -``` -configuration { - instance_name.simple = true; -} -``` - -## Template Instantiation Order - - -CAmkES instantiates templates in the following order: makefile, -components, connections, simple, capdl. The makefile has to come first -since it defines the build rules that instantiate all the other -templates. Simple must come after components and connections as it needs -to generate code to give access to caps allocated in component and -connection templates. Capdl must be last as it needs to be run after -compiling all components (including code generated by the simple -template). Since each template may be instantiated while producing any -output file, in order for caching to work correctly, the order of -template instantiation must be deterministic, at least in a single -invocation of the CAmKES-tool. - -Note that components and connections will be instantiated in arbitrary -(but deterministic) order. An implication of this, is that if multiple -components want a cap to the same object (e.g. an endpoint which two -components use to communicate), each template that needs to talk about a -cap to the object must first allocate it unless it's already allocated. -This is because you can't talk about a cap to an object until that -object has been allocated. Typically in such a situation, you'll see the -following template code on both sides of the connection: -``` -/*- set ep = alloc_obj('ep_obj_name', seL4_EndpointObject) -*/ -/*- set ep_cap = alloc_cap('this_components_ep_cap', ep) -*/ - -// do something with ep_cap -``` - -Looking at the code, it appears the endpoint will be allocated twice, as -both sides of the connection will call `alloc_obj`. Digging deeper into -the implementation of `alloc_obj`, we see it calls a function called -`guard`. `guard` is a bit of a misnomer. A more appropriate name might be -`allocate_unless_already_allocated`. It checks whether there's already -an object by the given name, returns the object if it exists, otherwise -allocates and returns it. diff --git a/projects/camkes/manual.html b/projects/camkes/manual.html new file mode 100644 index 00000000000..1565ef7d061 --- /dev/null +++ b/projects/camkes/manual.html @@ -0,0 +1,4253 @@ + + + + + + + CAmkES Manual | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Manual

+ + + +

This document describes the structure and functionality of CAmkES, a platform +for building componentised systems for embedded platforms. The documentation is +broken into sections for users, template authors and developers. The +Usage section is for people wanting to develop systems +using CAmkES as a platform. The Templating section is +for people wanting to write their own CAmkES templates and use more complex +functionality. Finally the Developers section is for +people wanting to modify the internals of CAmkES itself. If you are modifying +the internals of CAmkES, it is recommended that you read the entirety of this +documentation. Regardless of which section is most relevant for you, you should +at least familiarise yourself with the Terminology section.

+ +

CAmkES’ primary target platform is the +seL4 microkernel. The seL4 kernel and its functionality +are not discussed in this document. It is assumed that the reader has read the +seL4 programming references and is familiar with how this kernel operates and +the mechanisms it provides.

+ +

Terminology

+ +

Throughout this document some domain specific terminology is used that may have +connotations outside CAmkES/component systems. To avoid confusion the meanings +of these terms are made explicit below.

+ +

Abstract Syntax Tree (AST)

+ +
+

An internal representation of the results of parsing a generalised grammar. + More thorough definitions of ASTs are provided + elsewhere, but this is + noted here because the abbreviation ‘AST’ is used heavily in this + documentation.

+
+ +

Architecture Description Language (ADL)

+ +
+

The CAmkES syntax for describing a component system. Most component platforms + have their own architecture description language for describing a set of + components and how they are wired together, but the term ‘ADL’ will be used + in this documentation to exclusively refer to the CAmkES input specification + language.

+
+ +

Assembly

+ +
+

A top-level element that encapsulates a component system description. An + assembly can be thought of as a complete description of a full system. + A system must contain at least one assembly. A system with more than one + assembly is equivalent to a system with one assembly whose composition + and configuration sections are the concatenation of the composition and + configuration sections of each assembly.

+
+ +

Attribute

+ +
+

Components and connectors can have extra data of an arbitrary type associated + with them. These are referred to as attributes. The description of a + component/connector must describe the name of the attribute and its type. The + value of the attribute itself is unspecified. It is assigned when the entity + is instantiated, and this assignment is referred to as a setting. Attributes + are generally used to specialise or differentiate a component at runtime. + The types of attributes can be constructed as a collection or struct of + any of the basic CAmkES types: int, unsigned int, char, unsigned char, string. + It is possible to give an attribute a default value when it is declared. If + there are no settings for an attribute, the default setting will be used. If + an attribute is aliased to a different attribute that also has a default, + then the different attribute’s default will override the original default.

+
+ +

Component

+ +
+

A type of functional entity. It is important to stress this distinction. + ‘Component’ is used colloquially to refer to both types and instances, but in + a formal sense ‘component’ refers only to the type. To make this more + concrete, the statement component foo f describes a component instance f, + whose type is foo.

+
+ +

Composition

+ +
+

A container for the component and connector instantiations that form a system. + This is essentially a syntactic element for delimiting sections in a + specification. It is contained by an assembly block, along with an optional + configuration.

+
+ +

Compound Component

+ +
+

A component with a composition section, and optionally a configuration section.

+
+ +

Configuration

+ +
+

A container for describing settings. This is a syntactic element to hold the + assignment of attributes for a given system. It is expressed inside an + assembly block.

+
+ +

Connection

+ +
+

An instantiation of a connector. Connections connect two instances. Because + the instantiation of a connector does not really specialise the connector in + any particular way, it is easy to conflate the two. However, the sources make + important distinctions between connectors and connections.

+
+ +

Connector

+ +
+

A type of link between instances. The distinction between ‘connector’ and + ‘connection’ is the same as that between ‘component’ and ‘instance,’ i.e. a + connection is an instantiation of a particular connector.

+
+ +

Consumes

+ +
+

Event interfaces that are accepted by a component. If a component consumes a + particular event it means that it is expecting to receive and handle that + event.

+
+ +

Dataport

+ +
+

Port interfaces that are used by a component. A component’s dataports + are expected to be available to it at runtime as shared memory regions.

+
+ +

Direction

+ +
+

The flow of a parameter of a procedure method. The only possible directions + are ‘in’ (caller to callee), ‘out’ (callee to caller), ‘inout’ + (bidirectional) and ‘refin’ (identical to ‘in’ except for the C backend where + this is optimised to pass-by-reference).

+
+ +

Emits

+ +
+

Event interfaces that are expressed by a component. If a component emits a + given event it means that it produces events of this type.

+
+ +

Event

+ +
+

An asynchronous signal interface of a component. Events are defined completely + by their identifier, a numerical value. It may be helpful to think of this + value as mapping to something like an interrupt number or a signal type, + although they do not necessarily represent hardware messages.

+
+ +

Exported Interface

+ +
+

An interface of an internal instance that is presented under the name of an + identically typed interface in its containing component. The purpose of + exported interfaces is to expose a coherent outward-facing set of interfaces + from a component, while potentially implementing those interfaces within + nested components.

+
+ +

Instance

+ +
+

An instantiation of a component type. Of course ‘instance’ can be used to + refer to an instantiation of any type, but when you see the term ‘instance’ in + the sources it is generally referring to the instantiation of a component. To + give a concrete example, in the statement component foo f f is an instance.

+
+ +

Interface

+ +
+

An abstract exposed interaction point of a component. There could be a + distinction made here between type and instance of one of these interaction + points, but in practice this is not necessary and ambiguity rarely arises. The + subcategories of interface are procedure, event and port.

+
+ +

Internal Instance

+ +
+

A component instance declared inside a compound component’s composition section.

+
+ +

Internal Connection

+ +
+

A connection declared inside a compound component which connects two internal + instance interfaces. That is, any connection declared inside a compound + component.

+
+ +

Maybe

+ +
+

Interfaces of components can be made optional using the maybe keyword. Optional + interfaces do not need to be connected to any other interfaces. C symbols associated + with optional interfaces (functions and dataport pointers) are declared as weak + symbols. If nothing is connected to an optional interface, its associated symbols + lack definitions. That is, functions and dataport pointers associated with unconnected + optional interfaces take the value NULL at runtime.

+
+ +

Method

+ +
+

An item of a procedure. When targeting a conventional programming language, + methods usually map directly to generated functions.

+
+ +

Parameter

+ +
+

A piece of data referenced by a procedure method. This can be thought of as an + argument to a function.

+
+ +

Port

+ +
+

The interface type that represents shared memory semantics.

+
+ +

Procedure

+ +
+

An interface with function call semantics. Procedures consist of a series of + methods that can be invoked independently.

+
+ +

Provides

+ +
+

Procedure interfaces implemented by a component. When targeting a conventional + programming language this typically means that the component contains + functions that are implementations of each method in the procedures provided.

+
+ +

Setting

+ +
+

An assignment of an attribute to a specific value. A setting does not specify + the type of the attribute, because this has already been described by the + attribute as specified in the component/connector description.

+
+ +

Struct

+ +
+

A collection of named attribute fields that can be used as an attribute type + for a component attribute.

+
+ +

Type

+ +
+

A procedure method’s return type or parameter type. This information does not + include the direction of a parameter. An example type is something like + ‘string.’

+
+ +

Uses

+ +
+

Procedure interfaces that are invoked by a component. When targeting a + conventional programming language this typically means that the component + contains calls to functions that are expected to implement each method in the + procedures used.

+
+ +

Virtual Interface

+ +
+

An interface of a compound component that is not implemented by that + component, but is an alias for internal instance’s interface.

+
+ +

A concrete example:

+ +
struct cat {
+    int paws;
+    string name;
+}
+
+procedure thing {
+  int func(in int x);
+}
+
+component foo {
+  control;
+  uses thing t1;
+  emits sig s1;
+  dataport buffer b1;
+  attribute cat kitty;
+}
+
+component bar {
+  provides thing t2;
+  consumes sig s2;
+  dataport buffer b2;
+}
+
+assembly {
+  composition {
+    component foo f;
+    component bar b;
+
+    connection RPC c1(from f.t1, to b.t2);
+    connection Notification c2(from f.s1, to b.s2);
+    connection SharedData c3(from f.b1, to b.b2);
+  }
+  configuration {
+      f.kitty = {"name": "meows", "paws": 4};
+  }
+}
+
+ +
    +
  • thing is a procedure
    • +
  • int is a type
    • +
  • func is a method
    • +
  • in is a direction
    • +
  • x is a parameter
    • +
  • sig is an event
    • +
  • buffer is a port
    • +
  • foo and bar are components
    • +
  • t1 is a uses
    • +
  • s1 is a emits
    • +
  • b1 and b2 are dataports
    • +
  • t2 is a provides
    • +
  • s2 is a consumes
    • +
  • assembly { ... } is an assembly
    • +
  • composition { ... } is a composition
    • +
  • f and b are instances
    • +
  • RPC, Notification and SharedData are connectors
    • +
  • c1, c2 and c3 are connections
    • +
  • cat is a struct
    • +
  • kitty is an attribute
    • +
  • f.kitty is a setting
    • +
+ +

Usage

+ +

This section is targeted at people building systems on top of the CAmkES +platform. It assumes a basic knowledge of C programming.

+ +

Dependencies

+ +

Please see the +docsite +for information about dependencies.

+ +

To check you have the appropriate dependencies installed:

+ +
./tools/check_deps.py
+
+ +

Tutorial

+ +

This section is aimed at getting you up and running with CAmkES applications +and increase your familiarity with the CAmkES environment. We assume you are +working in the CAmkES project repository for this.

+ +

Running a Simple Example

+ +

There’s an example application under apps/simple that involves two components, +echo and client, communicating over a single interface.

+ +

Simple system

+ +

To build this example, from the top-level directory run:

+ +
mkdir build
+cd build
+../init-build.sh -DPLATFORM=sabre -DCAMKES_APP=simple -DSIMULATION=1
+ninja
+
+ +

This produces an image images/capdl-loader-image-arm-imx6. To run this image in +qemu:

+ +
./simulate
+
+ +

You should see debugging output from the system initialisation, followed by:

+ +
echo_int: 42 -> 42
+echo_float: 273421.437500 -> 273421.437500
+echo_double: 273421.427400 -> 273421.427400
+echo_mix: 273421.427400 -> 273421
+echo_string: "hello world" -> "hello world"
+echo_parameter: 123 -> 123 (returned = 123)
+increment_parameter: 100 -> 101
+After the client
+
+ +

To understand what this example is doing, open the files +apps/simple/components/Echo/src/echo.c and +apps/simple/components/Client/src/client.c. The implementations of the echo +functions are in echo.c and they are called from client.c. The function call +itself happens over a seL4 endpoint. The connection between the two components +is described in apps/simple/simple.camkes, and the functional interface that +echo is providing is described in apps/simple/interfaces/Simple.idl4.

+ +

If you want to run this example on IA32, repeat the above procedure with a new build +directory, replacing the configuration line with the following:

+ +
../init-build.sh -DPLATFORM=ia32 -DCAMKES_APP=simple -DSIMULATION=1
+
+ +

Creating An Application

+ +

Let’s create some simple hello world applications using the different interface +types available in CAmkES. Create a new application directory with two component +types:

+ +
mkdir -p apps/helloworld/components/Hello
+mkdir -p apps/helloworld/components/Client
+
+ +

Functional interfaces, referred to as procedures, are made up of a set of +methods. Define an interface that the components will communicate over and save +this under apps/helloworld/interfaces/MyInterface.idl4:

+ +
/* apps/helloworld/interfaces/MyInterface.idl4 */
+
+procedure MyInterface {
+  void print(in string message);
+}
+
+ +

This interface consists of a single method, print that takes an input parameter +of type string. Note that, although we are planning to implement this component +in C, interfaces are defined with abstract types that have equivalents in all +target languages. In the case of C, string maps to char*. Each component +needs a description of the interfaces it exposes or needs in so-called +Architecture Description Language. Create these in +apps/helloworld/components/Hello/Hello.camkes and +apps/helloworld/components/Client/Client.camkes.

+ +
/* apps/helloworld/components/Hello/Hello.camkes */
+
+import "../../interfaces/MyInterface.idl4";
+
+component Hello {
+  provides MyInterface inf;
+}
+
+/* apps/helloworld/components/Client/Client.camkes */
+
+import "../../interfaces/MyInterface.idl4";
+
+component Client {
+  control;
+  uses MyInterface iface;
+}
+
+ +

Note that each component description needs to import the interface file we +created above from apps/helloworld/interfaces. Import statements function +similar to C’s #include, in that they can be enclosed in double quotes and +are relative to the source file, or enclosed in angle brackets and refer to a +built-in file. The Hello component is to contain an implementation of +MyInterface and the Client component will expect to be provided with an +implementation of MyInterface. The control keyword indicates that Client is +what is called an active component. This means it will contain a main function +(prototyped as run) and have an active thread of control.

+ +

Create a file to describe the instantiation and structure of the system at +apps/helloworld/helloworld.camkes.

+ +
/* apps/helloworld/helloworld.camkes */
+
+import <std_connector.camkes>;
+import "components/Hello/Hello.camkes";
+import "components/Client/Client.camkes";
+
+assembly {
+  composition {
+    component Hello h;
+    component Client c;
+    connection seL4RPCCall conn(from c.iface, to h.inf);
+  }
+}
+
+ +

This file begins with several import statements that reference other files. +Hello.camkes and Client.camkes are the files we created above, while +std_connector.camkes is a built-in file that defines the standard CAmkES +connector types. The body of the system description instantiates each component +once, h of type Hello and c of type Client. The components’ interfaces +are connected via a connection, conn, of type seL4RPCCall.

+ +

Now for the implementation of the components. Create a single source file for +Hello as apps/helloworld/components/Hello/src/hello.c:

+ +
/* apps/helloworld/components/Hello/src/hello.c */
+
+#include <camkes.h>
+#include <stdio.h>
+
+void inf__init(void) {
+}
+
+void inf_print(const char *message) {
+  printf("Client says: %s\n", message);
+}
+
+ +

The header camkes.h is generated by the CAmkES build system and contains +prototypes for functions related to MyInterface that this component needs to +implement. Note that the actual implementations of interface functions are +prefixed with the component-local name of the interface (inf from Hello.camkes +above) and an underscore. The function inf__init is for this component to do +any required initialisation. In the case of this example we have no +initialisation to perform.

+ +

Create a source file for Client as +apps/helloworld/components/Client/src/client.c that calls these functions as if +they are directly available to it:

+ +
/* apps/helloworld/components/Client/src/client.c */
+
+#include <camkes.h>
+
+int run(void) {
+  const char *s = "hello world";
+  iface_print(s);
+  return 0;
+}
+
+ +

The entry point of a CAmkES component is run.

+ +

The final thing is to add some build system boiler plate to be able to build +the system. +Copy one of the CMakeLists.txt files from another application or create +apps/helloworld/CMakeLists.txt from scratch:

+ +
cmake_minimum_required(VERSION 3.16.0)
+
+project(helloworld C)
+
+DeclareCAmkESComponent(Client SOURCES components/Client/src/client.c)
+DeclareCAmkESComponent(Hello SOURCES components/Hello/src/hello.c)
+
+DeclareCAmkESRootserver(helloworld.camkes)
+
+ +

You’re now ready to compile and run this application, by entering the CAMKES_APP value in the cmake configuration GUI:

+ +
cd build
+cmake . -DCAMKES_APP=helloworld # set `helloworld` as CAMKES_APP
+ninja
+./simulate
+
+ +

If all goes well you should see:

+ +
Client says: hello world
+
+ +

Congratulations, you’ve just made your first CAmkES application.

+ +

Under the Hood

+ +

We basically just wrote a verbose and roundabout Hello World example, so what +benefit is CAmkES providing here? Note how the function call between the two +components looks just like a normal function invocation in C, even though the +two components are actually in different address spaces. During compilation +so-called glue code is generated to connect the two components via a seL4 +endpoint and transparently pass the function invocation and return over this +channel. The communication itself is abstracted in the ADL description in +apps/helloworld/helloworld.camkes. The connection type we used was seL4RPCCall, but +it is possible to use another connection type here without modifying the code of +the components themselves.

+ +

CAmkES provides some interface types for other modes of interaction than +function calls. Events can be used for asynchronous communication and dataports +for shared memory.

+ +

An Example of Events

+ +

Events are the CAmkES interface type for modelling asynchronous communication +between components. Like procedures, events connect a single component to +another single component, but the receiver of an event (called consumer in +CAmkES parlance) has several ways of receiving the event. The following walks +through an example demonstrating these.

+ +

Create a new application directory with two components:

+ +
mkdir -p apps/helloevent/components/Emitter
+mkdir -p apps/helloevent/components/Consumer
+
+ +

Events, unlike procedures, do not need to be defined in a separate IDL file. You +can simply refer to the event type in your component ADL files and CAmkES will +infer an event type. Create the following description for Emitter:

+ +
/* apps/helloevent/components/Emitter/Emitter.camkes */
+
+component Emitter {
+  control;
+  emits MyEvent e;
+}
+
+ +

This description says Emitter is an active component (the control keyword) and +it emits a single event called e of type MyEvent. Create some basic source code +for the component that does nothing except emit the event itself:

+ +
/* apps/helloevent/components/Emitter/src/main.c */
+
+#include <camkes.h>
+
+int run(void) {
+  while (1) {
+    e_emit();
+  }
+  return 0;
+}
+
+ +

CAmkES provides an emit function to send the event.

+ +

Now let’s create a description of the Consumer that will handle this event:

+ +
/* apps/helloevent/components/Consumer/Consumer.camkes */
+
+component Consumer {
+  control;
+  consumes MyEvent s;
+}
+
+ +

Note that this component consumes (handles) an event of the same type. Let’s +instantiate and connect these components together using another ADL file:

+ +
/* apps/helloevent/helloevent.camkes */
+
+import <std_connector.camkes>;
+import "components/Emitter/Emitter.camkes";
+import "components/Consumer/Consumer.camkes";
+
+assembly {
+  composition {
+    component Emitter source;
+    component Consumer sink;
+    connection seL4Notification channel(from source.e, to sink.s);
+  }
+}
+
+ +

In this file, seL4Notification is a seL4 specific connector for transmitting +asynchronous signals. The two instantiated components, source and sink are +connected over the connection channel.

+ +

As mentioned above, there are several ways for a component to receive an event. +The consumer can register a callback function to be invoked when the event is +received, they can call a blocking function that will return when the event is +received or they can call a polling function that returns whether an event has +arrived or not. Let’s add some source code that uses all three:

+ +
#include <camkes.h>
+#include <stdio.h>
+
+static void handler(void) {
+  static int fired = 0;
+  printf("Callback fired!\n");
+  if (!fired) {
+    fired = 1;
+    s_reg_callback(&handler);
+  }
+}
+
+int run(void) {
+  printf("Registering callback...\n");
+  s_reg_callback(&handler);
+
+  printf("Polling...\n");
+  if (s_poll()) {
+    printf("We found an event!\n");
+  } else {
+    printf("We didn't find an event\n");
+  }
+
+  printf("Waiting...\n");
+  s_wait();
+  printf("Unblocked by an event!\n");
+
+  return 0;
+}
+
+ +

Note that we re-register the callback during the first execution of the handler. +Callbacks are deregistered when invoked, so if you want the callback to fire +again when another event arrives you need to explicitly re-register it.

+ +

We now have everything we need to run this system.

+ +

Create the appropriate apps/helloevent/CMakeLists.txt as for the previous example. Compile the system and +run it with the simulate script as per the previous example. If all goes well you +should see something like the following:

+ +
Registering callback...
+Callback fired!
+Polling...
+We didn't find an event
+Waiting...
+Unblocked by an event!
+Callback fired!
+
+ +

Whether you find an event during polling will be a matter of the schedule that +seL4 uses to run the components. This covers all the functionality available +when using events. One final point that may not be obvious from the example is +that callbacks will always be fired in preference to polling/waiting. That is, +if a component registers a callback and then waits on an event to arrive, the +callback will be fired when the first instance of the event arrives and the wait +will return when/if the second instance of the event arrives.

+ +

An Example of Dataports

+ +

Dataports are CAmkES’ abstraction of shared memory. All +components participating in a connection involving dataports get read/write +access to the dataport by default. The default dataport type is +Buf, which is implemented as a byte array in C of size PAGE_SIZE. +Alternatively you can specify a user-defined type for the shared memory region. +This example will demonstrate both.

+ +

Create two components that will use a pair of dataports for communication:

+ +
mkdir -p apps/hellodataport/components/Ping
+mkdir -p apps/hellodataport/components/Pong
+
+ +

Let’s define a struct that will be used as one of the dataports:

+ +
/* apps/hellodataport/include/porttype.h */
+
+#ifndef _PORTTYPE_H_
+#define _PORTTYPE_H_
+
+typedef struct MyData {
+  char data[10];
+  bool ready;
+} MyData_t;
+
+#endif
+
+ +

Now let’s create an ADL description of the Ping component:

+ +
/* apps/hellodataport/components/Ping/Ping.camkes */
+
+component Ping {
+  include "porttype.h";
+  control;
+  dataport Buf d1;
+  dataport MyData_t d2;
+}
+
+ +

Note that we need to include the C header in the ADL. CAmkES does not actually +parse this header, but it needs to know to #include it whenever it references +the MyData_t type. Add a similar description for Pong:

+ +
/* apps/hellodataport/components/Pong/Pong.camkes */
+
+component Pong {
+  include "porttype.h";
+  control;
+  dataport Buf s1;
+  dataport MyData_t s2;
+}
+
+ +

Now we’ll create some basic code for each component to use the dataports:

+ +
/* apps/components/Ping/src/main.c */
+
+#include <camkes.h>
+#include <porttype.h>
+#include <stdio.h>
+#include <string.h>
+
+// index in d1 to use to signal pong
+#define D1_READY_IDX 20
+
+int run(void) {
+  char *hello = "hello";
+
+  printf("Ping: sending %s...\n", hello);
+  strncpy((char*)d1, hello, D1_READY_IDX - 1);
+
+  d1_release(); // ensure the assignment below occurs after the strcpy above
+  ((char*)d1)[D1_READY_IDX] = 1;
+
+  /* Wait for Pong to reply. We can assume d2_data is
+   * zeroed on startup by seL4.
+   */
+  while (!d2->ready) {
+    d2_acquire(); // ensure d2 is read from in each iteration
+  }
+
+  printf("Ping: received %s.\n", d2->data);
+
+  return 0;
+}
+
+ +
/* apps/components/Pong/src/main.c */
+
+#include <camkes.h>
+#include <porttype.h>
+#include <stdio.h>
+#include <string.h>
+
+// index in s1 to use to signal ping
+#define S1_READY_IDX 20
+
+int run(void) {
+  char *world = "world";
+
+  /* Wait for Ping to message us. We can assume s1_data is
+   * zeroed on startup by seL4.
+   */
+  while (!((char*)s1)[S1_READY_IDX]) {
+    s1_acquire(); // ensure s1 is read from in each iteration
+  }
+
+  printf("Pong: received %s\n", (char*)s1);
+
+  printf("Pong: sending %s...\n", world);
+  strcpy(s2->data, world);
+
+  s2_release(); // ensure the assignment below occurs after the strcpy above
+  s2->ready = true;
+
+  return 0;
+}
+
+ +

Note the use of *_acquire() and *_release() functions. These are used to maintain +coherency of shared memory between components. Call *_acquire() between multiple +reads from a dataport, where the correct behaviour of the program depends on the +contents of the dataport possibly changing between reads. Call *_release() between +multiple writes to a dataport, where the correct behaviour of the program depends +on writes preceding the *_release() in the program code being performed strictly +before the writes following it.

+ +

Typically, a real system would have a more complete communication protocol between +the two components, but for the purposes of this example spinning until a byte +changes is good enough. We’re ready to connect all these sources together with a +top-level ADL file:

+ +
/* apps/hellodataport/hellodataport.camkes */
+
+import <std_connector.camkes>;
+import "components/Ping/Ping.camkes";
+import "components/Pong/Pong.camkes";
+
+assembly {
+  composition {
+    component Ping ping;
+    component Pong pong;
+
+    connection seL4SharedData channel1(from ping.d1, to pong.s1);
+    connection seL4SharedData channel2(from ping.d2, to pong.s2);
+  }
+}
+
+ +

Add the now familiar apps/hellodataport/CMakeLists.txt:

+ +
cmake_minimum_required(VERSION 3.16.0)
+
+project(hellodataport C)
+
+# Interface library for our dataport
+add_library(MyData INTERFACE)
+target_include_directories(MyData INTERFACE "${CMAKE_CURRENT_LIST_DIR}/include")
+
+DeclareCAmkESComponent(Ping SOURCES components/Ping/src/main.c LIBS MyData)
+DeclareCAmkESComponent(Pong SOURCES components/Pong/src/main.c LIBS MyData)
+
+DeclareCAmkESRootserver(hellodataport.camkes)
+
+
+

We added an interface library containing the shared header file. The LIBS field in DeclareCAmkESComponent can be +used to specify any argument that can be ordinarily given to CMake’s target_link_libraries().

+ +

If you now compile and run the resulting +image you should see some output like the following:

+ +
Ping: sending hello...
+Pong: received hello
+Pong: sending world...
+Ping: received world.
+
+

An example of structs and arrays for collections

+ +

A struct can be defined with the struct keyword. The attributes that make +up the struct are listed in a type name format (similar to C).

+ +

Arrays are specified by appending the attribute name with a []. The size of +an array is set at code generation time when the setting for the attribute is +specified.

+ +

This is an example of a valid camkes specification. The corresponding C file +is shown after. To find a size of an attribute array, the sizeof macro can be +used as shown in the example.

+ +
struct client_config {
+    string name;
+    int age;
+    int height;
+}
+struct cat {
+    int b[];
+    int c;
+}
+
+component Client {
+    control;
+    attribute client_config config;
+    attribute cat array_in_struct;
+}
+
+assembly {
+    composition {
+        component Client client;
+    }
+
+    configuration {
+        client.config = {"name": "Zed","age": 39, "height": 34+4};
+        client.array_in_struct = {"b": [3,4,5,6], "c": 4};
+    }
+}
+
+
+ +
#include <camkes.h>
+#include <stdio.h>
+
+int run(void)
+{
+    printf("struct: %s: height plus age is %d\n", config.name, config.age + config.height);
+    printf("array_in_struct: array length: %d, first element %d\n", sizeof(array_in_struct.b) / sizeof(array_in_struct.b[0]), array_in_struct.b[0]);
+    return 0;
+}
+
+ +

Tutorial Summary

+ +

You should now have a reasonably comprehensive understanding of the basic +connector functionality available in CAmkES. The other apps in the CAmkES +project repository provide some more diverse system examples.

+ +

Overview

+ +

The various parts that comprise CAmkES can be used in several ways, including +executing a standalone tool as an end user or importing a Python module to +perform programmatic operations. These two uses are broken up into the sections +below. Command Line Arguments describes how to invoke +standalone CAmkES functionality, and Modules describes how to import +and use the various functional units. Importing CAmkES functionality as a module +is strictly more powerful than running the command line tool, but usage +is more complicated. Note that these sections only describe external +interaction with these artefacts. If you are interested in the internals of +these you will need to refer to the Developers section.

+ +

Command Line Arguments

+ +

This section discusses the standalone tool that is part of the CAmkES +ecosystem. This can be run from the command line with a shell script wrapper +that checks its dependencies:

+ +
camkes.sh args...
+
+ +

The following command line arguments are available.

+ +

–cache, -c +–cache-dir

+ +
+

In a complicated system, the compilation itself can be quite time intensive. + CAmkES implements a template cache that reduces recompilation time within and + across builds. The –cache option enables it.

+
+ +

–cpp +–nocpp

+ +
+

Whether or not to run the C pre-processor over the ADL input specification + before processing it. The ADL input specification, strictly, is not C source + code, but sometimes it can be useful to have the ability to pre-process it as + if it was. The CAmkES ADL grammar is sufficiently similar to C that you are + unlikely to run into any problems in this respect.

+
+ +

-D, –debug +-q, –quiet +-v, –verbose

+ +
+

Set the level of information and error reporting emitted. The last one of + these options encountered on the command line takes precedence. Note that + there is no option to set the default verbosity (which is more than –quiet, + but less than –verbose). The verbosity setting is applied globally during + execution. For example, applying –debug to inspect a parsing problem in the + runner will also generate debugging output from the lexing phase.

+
+ +

–default-priority

+ +
+

Threads in a seL4 system are all configured with an initial priority. This + can be tuned via attributes, but otherwise threads inherit a global default. + This parameter allows you to set the global default.

+
+ +

–default-affinity

+ +
+

Threads and sched-contexts in a seL4 system are all configured with an initial + affinity. This can be tuned via attributes, but otherwise threads inherit a + global default, which is CPU index 0.

+
+ +

–elf, -E

+ +
+

Pass an ELF file that is to contribute to the final CapDL specification of a + system. This parameter allows you to pass in the compiled ELF binary of one of + your component instances. The CAmkES build system should take care of passing + this option.

+
+ +

-f FILE, –file FILE

+ +
+

This argument sets FILE as the input to parse. This argument is required and + only a single input file is supported.

+
+ +

-h, –help

+ +
+

Shows usage information and then exits.

+
+ +

-I PATH, –import-path

+ +
+

CAmkES specifications can contain import statements that are either + relative or builtin. Analogously to C pre-processor #include directives, + builtin import statements use angle brackets, import &lt;foo.camkes&gt;. + This option is similar to the C compiler flag, -I, and adds a directory to be + searched for these builtin files. When resolving imports, directories will be + searched in the order in which they are specified on the command line with + the first match taking preference. Note, unlike the C pre-processor this + option only affects searches for builtin imports. Relative imports are + always relative to the location they are included from.

+
+ +

–item, -T

+ +
+

Specify the output you wish the runner to generate. The available options + here are dependent on your input specification and it is best to look at + examples to see what is expected following this option.

+
+ +

–largeframe

+ +
+

Back large virtual address space regions with large frames when possible. On + ARM and IA32 platforms, multiple frame sizes are supported for mapping + physical memory into address spaces. It is more efficient to use a single + large frame to cover a region than many small frames. This flag controls + whether this promotion to large frames happens automatically. Note that this + does not affect DMA pools, for which mappings are controlled by the + –largeframe-dma option below.

+
+ +

–largeframe-dma

+ +
+

Back components’ DMA pools with large frames when possible. This works + entirely independently to the –largeframe option. The reason for this + separation is that large frame promotion of a DMA pool on ARM can be a + little complicated to achieve. For more information, see + Efficient DMA.

+
+ +

–platform, -p

+ +
+

The target output platform. This determines some aspects of the environment + that the template being rendered is expected to function in. This option is + only relevant to the runner. Valid platforms are “architecture-semantics”, + “autocorres”, “CIMP”, “GraphViz” and “seL4”. The “GraphViz” option is for + producing visual representations of a system and the “seL4” option is for + producing binaries. All other platforms are verification frameworks.

+
+ +

–templates, -t

+ +
+

You can use this option to add an extra directory to search for templates + before the built-in location. This can allow you to extend the available + templates or even override the built-in templates.

+
+ +

–version

+ +
+

Print basic version information and then exit.

+
+ +

The following options are all related to runtime optimisations within the +templates. Note that most of these are highly seL4 specific and would make no +sense in the context of another platform.

+ +

–frpc-lock-elision +–fno-rpc-lock-elision

+ +
+

Locks are used within the seL4RPC connector templates to prevent threads + interfering with each other’s execution. When this option is enabled, CAmkES + will determine when this lock is not required and remove it at compile-time.

+
+ +

–fcall-leave-reply-cap +–fno-call-leave-reply-cap

+ +
+

The seL4RPCCall connector needs to save a so-called reply cap on the + receiver’s side to prevent accidental deletion in the presence of + interference from other interfaces. In certain circumstances there is + actually no risk of the reply cap being deleted. With this option enabled, + CAmkES will detect these scenarios and operate on the reply cap in place to + avoid extra syscalls.

+
+ +

The following options are all related to verification of templates outputs.

+ +

–fprovide-tcb-caps +–fno-provide-tcb-caps

+ +
+

By default each thread gets a cap to its own TCB. The only purpose of this is + to allow it to suspend itself when it exits. These TCBs can complicate + reasoning about a generated CapDL specification. This option elides these TCB + caps at the cost of threads messily VM faulting when they exit.

+
+ +

Modules

+ +

Each subset of CAmkES functionality is encapsulated in a Python module that +defines exactly what functions and variables are exported. The APIs of these +are described below and usage should be reasonably straightforward. To import +any of these modules the top-level directory of this distribution should be in +your PYTHONPATH environment variable. The available modules are:

+ +

camkes.ast

+ +
+

Definitions of objects that can appear in the result of parsing a CAmkES + specification. If you want to reference the types of objects in a resulting + AST you will need to import this.

+
+ +

camkes.internal

+ +
+

Functionality used by other CAmkES modules. You should not import this + module.

+
+ +

camkes.parser

+ +
+

To parse an input specification in memory or to do post-processing + manipulations on a specification-derived AST you will need to import this + module. The runner imports this module to perform its job.

+
+ +

camkes.runner

+ +
+

This module is available, but does not export any symbols. You should never + need to import it.

+
+ +

camkes.templates

+ +
+

If you need to lookup builtin templates you will need to import this module. + Note that this module does not contain any template instantiation logic.

+
+ +

camkes.ast

+ +

The result of parsing a CAmkES specification is an Abstract Syntax Tree (AST), +representing the input as a set of interconnected nodes. When using the default +parser, the object returned is of type, LiftedAST, which is defined in this +module. LiftedAST and its children all inherit from a base type, ASTObject, +that provides common functionality like traversal and comparison.

+ +

One of the AST objects is a class, Reference. Objects of this class are used +in the AST to represent symbols that refer to entities that are defined +elsewhere. During parsing, references are removed from the AST as they are +resolved to the entities to which they refer. In particular, if you are using +the default parser, the returned AST will never contain any Reference +objects.

+ +

In the code and in this document there is some discussion of ‘collapsing’ AST +references. This is meant to refer to replacing the Reference object in the +AST by the entity to which it refers. Note that this needs to be done by +reference so that you still only end up with a single copy of the entity, but +multiple pointers to it.

+ +

If you are not using the default CAmkES parser, but are assembling your own +from the parser module, it is important to note that objects +of the classes in the AST module are only created in the stage 3 parser. If you +are inspecting the output of any low-level parser prior to stage 3, you will +not see objects from camkes.ast.

+ +

camkes.parser

+ +

If you need to manipulate the AST, rather than just simply printing it +out, you will want to import the parser as a module into your own code. After +importing this module, you can interact with the parser through the following +high-level API.

+ +

parse_file(filename, options=None)

+ +
+

Parse a file into a LiftedAST. The options arguments is expected to be a + namespace as constructed by the runner. If you have non-standard parsing + requirements, you may find this function is insufficiently flexible for your + needs. In this case, you will need to compose the low-level parsers. You can + see a rough guide of how to do this in camkes/parser/parser.py.

+
+ +

parse_string(string, options=None)

+ +
+

Parse a string into a LiftedAST. This function works identically to the + previous in all respects, except obviously you will not have accurate + filename information.

+
+ +

camkes.templates

+ +

This module contains functionality for looking up builtin templates. The +templates themselves are actually stored in this directory (camkes/templates) +as well to reduce confusion. The description below only describes the externally +facing behaviour of this module. If you need to understand how template lookups +actually work you will need to read the source code and comments.

+ +

The API only contains a single class through which all access is intended to +flow.

+ +

Templates.__init__(self, platform)

+ +
+

Create a new template store in which templates can later be looked up. The + category of templates that are available from this store is specialised via + platform. At time of writing the valid values of platform are + ‘seL4’, ‘CIMP’ and ‘GraphViz’.

+
+ +

Templates.add_root(self, root)

+ +
+

Add a directory to be searched for templates when performing lookups. This + directory is added before existing directories, which allows you to + overwrite builtin templates if you wish.

+
+ +

Templates.get_roots(self)

+ +
+

Return the list of directories that are searched for templates. Note that if + you are the only client operating on this Templates object you will know + the contents of this list anyway, but this function is provided for + convenience.

+
+ +

Templates.add(self, connector_name, path, template)

+ +
+

Add a template to the lookup dictionary, such that it can later be returned + in a template lookup. Only connector templates can be added currently (i.e. + component templates and top-level templates cannot be added). The caller + provides the connector_name this template applies to (e.g. + ‘seL4MyConnector’), a partial lookup path to the template (e.g. + ‘from.source’) and a roots-relative path to the template itself. Again, + this function is sufficiently complicated that it may be easier to comprehend + its usage from reading camkes/runner/__main__.py.

+
+ +

Templates.lookup(self, path, entity=None)

+ +
+

Locate and return a template. The path provided should be a full lookup + path from the second-level of the lookup dictionary (i.e. not including the + platform prefix). For example, a valid path might be + ‘seL4RPCCall.from.source’. If you provide an entity this is used as a guard + on the lookup. The guards come into play when looking up connector templates. + In this situation the connector type of the connection you pass in as + entity will be used to determine if a given template matches your + lookup. This function returns None if a matching template can’t be found.

+
+ +

Runtime API

+ +

This section describes the environment in which you, as a user, will find +yourself writing code. Standard C library functionality is available, but as a +CAmkES application, there is also extra functionality provided by generated +code and supporting libraries. This extra functionality is what is documented +in this section.

+ +

Parts of the functionality discussed below are provided by the library, +libsel4camkes. In a typical seL4 project the user would need to specify that +they want to link against this library. This is not required in CAmkES as it is +assumed you always want to link against this library. For more information from +a CAmkES developer’s point of view, see Core Libraries. The +API is bidirectional in a sense, in that some of the functions below are called +by CAmkES code and expected to be provided by the user. This is noted in their +descriptions.

+ +

The following types are available at runtime from the C context of a component:

+ +

Buf (#include <camkes/dataport.h>)

+ +
+

The underlying type of a dataport. A user is never expected to instantiate + one of these manually, but they are free to do so if they wish.

+
+ +

camkes_error_handler_t (#include <camkes/error.h>)

+
+

The type of an error handler for dealing with errors originating in glue + code. For more information about this see + Error Handling.

+
+ +

camkes_tls_t (#include <camkes/tls.h>)

+ +
+

Thread-local storage metadata. This captures some necessary information for + constructing a thread context inside templates. A user is never expected to + instantiate or deal with one of these, but they are free to do so if they + wish.

+
+ +

dataport_ptr_t (#include <camkes/dataport.h>)

+ +
+

A component-independent representation of a pointer into a dataport. This is + intended to be an opaque type to the user that is only ever used via the + dataport_wrap_ptr and dataport_unwrap_ptr functions.

+
+ +

The following variables are available:

+ +

dataport (#include <camkes.h>)

+ +
+

If a component has a dataport they will be provided with a symbol of the + dataport’s name that is a pointer of the type they specified in their CAmkES + specification. As mentioned previously, the default type is Buf.

+
+ +

The following functions are available at runtime:

+ +

camkes_error_handler_t camkes_register_error_handler(camkes_error_handler_t handler) (#include <camkes/error.h>) +camkes_error_handler_t  interface_register_error_handler(camkes_error_handler_t handler) (#include <camkes/error.h>)

+ +
+

Register a component-wide or interface-specific error handler, respectively. + These functions return the previous error handler or NULL if there was no + previously installed error handler. For more information see + Error Handling.

+
+ +

dataport_ptr_t dataport_wrap_ptr(void *ptr) (#include <camkes/dataport.h>) +void *dataport_unwrap_ptr(dataport_ptr_t ptr) (#include <camkes/dataport.h>)

+ +
+

Utility functions for creating and destroying a component-independent + representation of a pointer into a dataport. This dataport_ptr_t can be + passed over a procedure interface to be unwrapped by the receiving component. + Unwrapping will fail if the underlying pointer is not into a dataport that is + shared with the receiver. dataport_unwrap_ptr returns NULL on failure.

+
+ +

void dataport_acquire(void)

+ +
+

An acquire memory fence. Any read from the dataport preceding this fence in + program order will take place before any read or write following this fence in + program order. In uniprocessor environments, this is always a compiler memory + fence. In multiprocessor environments, memory barrier instructions will be + emitted if necessary, depending on the affinities of component instances + connected by the dataport.

+
+ +

void dataport_release(void)

+ +
+

A release memory fence. Any write to the dataport following this fence in + program order will take place after any read or write preceding this fence in + program order. In uniprocessor environments, this is always a compiler memory + fence. In multiprocessor environments, memory barrier instructions will be + emitted if necessary, depending on the affinities of component instances + connected by the dataport.

+
+ +

size_t dataport_get_size(void)

+ +
+

Returns the size for the specific dataport this function gets called for. In + addition to this function, every component that has a dataport will be + provided with a macro dataport_size that is defined to the size of the + invdividual dataport. This macro allows declaring fixed size arrays, as the + C language requires a constant-expression for this.

+
+ +

void *camkes_dma_alloc(size_t size, int align) (#include <camkes/dma.h>) +void camkes_dma_free(void *ptr, size_t size) (#include <camkes/dma.h>)

+ +
+

Allocator for DMA device operations. These are closely linked with the DMA + pool functionality, as the allocation is backed by this pool.

+
+ +

uintptr_t camkes_dma_get_paddr(void *ptr) (#include <camkes/dma.h>)

+ +
+

Translate a pointer into a DMA region into a physical address. This function + assumes that the pointer you are passing in is to a byte within a region + allocated to you by camkes_dma_alloc_page. The reason for needing to obtain + the physical address of a pointer is typically to pass to a device that is + going to access this region outside of the scope of the MMU. For more + information, see the DMA section below.

+
+ +

void *camkes_io_map(void *cookie, uintptr_t paddr, size_t size, int cached, ps_mem_flags_t flags) (#include <camkes/io.h>)

+ +
+

Lookup the translation to virtual address from the physical address of a + memory-mapped IO device. This function is primarily to ease interaction with + libplatsupport infrastructure, so refer to its documentation where + appropriate.

+
+ +

int camkes_io_mapper(ps_io_mapper_t *mapper) (#include <camkes/io.h>)

+ +
+

Construct an IO mapping structure to pass to libplatsupport. See source + comments for more information about how to use this.

+
+ +

int camkes_io_ops(ps_io_ops_t *ops) (#include <camkes/io.h>)

+ +
+

Construct an IO operations structure to pass to libplatsupport. See source + comments for more information about how to use this.

+
+ +

int camkes_io_port_in(void *cookie, uint32_t port, int io_size, uint32_t *result) (#include <camkes/io.h>) +int camkes_io_port_out(void *cookie, uint32_t port, int io_size, uint32_t val) (#include <camkes/io.h>)

+ +
+

Read from or write to a hardware IO port. This function is primarily to ease + interaction with libplatsupport infrastructure, so refer to its documentation + where appropriate.

+
+ +

int camkes_io_port_ops(ps_io_port_ops_t *ops) (#include <camkes/io.h>)

+ +
+

Construct an IO port access structure to pass to libplatsupport. See source + comments for more information about how to use this.

+
+ +

const char *get_instance_name(void) (#include <camkes.h>)

+ +
+

Returns the name of this component instance. This can be helpful if you want + to write component functionality that has different behaviour depending on + which instance it is.

+
+ +

int instance_main(int thread_id)

+ +
+

A component instance’s entry point. This is generated by the platform and + invokes the user’s run function when complete.

+
+ +

int main(int thread_id) (in libsel4camkes.a)

+ +
+

This function — the C entry point to a component — is provided by + the platform. Components should not provide their own main.

+
+ +

int run(void)

+ +
+

This function is expected to be provided by the user in a control component. + It is invoked by main after component initialisation is complete.

+
+ +

NORETURN _start(int thread_id) (in libsel4camkes.a)

+ +
+

This function provides the assembly entry point of a component and consists + of a brief trampoline to main. The user can override this if they wish, but + it is unwise to do this unless you have a deep understanding of the runtime + environment.

+
+ +

void pre_init(void)

+ +
+

This function can be optionally provided by the user. If it is present, it + will be invoked before the component’s interfaces’ init functions have + executed. Be aware that you will not have full runtime support in this + function. For example, interfaces cannot be expected to be accessible.

+
+ +

void interface__init(void)

+ +
+

For each incoming or outgoing interface a user can optionally provide this + function. If it is present it will be invoked after the component’s + pre-init function, but before its post-init function. The same caveats about + the runtime environment from above are applicable here.

+
+ +

void post_init(void)

+ +
+

This function can be optionally provided by the user. If it is present, it + will be invoked after the component’s pre-init function and after all + interfaces’ init functions, but before any interface enters its run + function.

+
+ +

int interface__run(void)

+ +
+

This function can be provided for any incoming or outgoing interface. If it + is present, it will be invoked after all pre- and post-init functions have + run.

+
+ +

return procedure_method(args...) (#include <camkes.h>)

+ +
+

In a component that provides a procedure interface, things are somewhat + reversed and the implementation calls functions that you are expected to + provide. For each method in the procedure you are expected to provide a + matching implementation. In a component that uses a procedure interface, + functions of this form are available for you to call.

+
+ +

void event_emit(void) (#include <camkes.h>)

+ +
+

In a component that emits an event a function prefixed with the event’s name + is available that causes the event to be sent.

+
+ +

void event_poll(void) (#include <camkes.h>)

+ +
+

In a component that consumes an event a function prefixed with the event’s + name is available that returns whether there is a pending event. Note, this + function never blocks.

+
+ +

int event_reg_callback(void (*callback)(void*), void *arg) (#include <camkes.h>)

+ +
+

In a component that consumes an event a function prefixed with the event’s + name is available for registering a callback for this event. When the event + is received, the provided function will be invoked with the argument provided + when registering the callback. Note that registered + callbacks take precedence over threads blocked on calls to event_wait. + event_reg_callback returns 0 on success and non-zero if the callback + could not be registered.

+
+ +

void event_wait(void) (#include <camkes.h>)

+ +
+

In a component that consumes an event a function prefixed with the event’s + name is available that blocks until the event is received.

+
+ +

Synchronization Primitives

+ +

CAmkES provides three primitives for intra-component mutual exclusion and synchronization. +Mutexes, semaphores, and binary semaphores are declared similarly to properties of a component definition:

+ +
component Foo {
+  has mutex m;
+  has semaphore s;
+  has binary_semaphore b;
+}
+
+ +

By default semaphores have a count (initial value) of 1, and binary semaphores have an initial value +of 0. This can be adjusted using an attribute:

+ +
assembly {
+  composition {
+    component Foo f;
+    ...
+  }
+  configuration {
+    f.s_value = 4;
+    f.b_value = 1; // must be either 0 or 1
+    ...
+  }
+}
+
+ +

An application can lock or unlock a declared mutex and call post or wait on a +declared semaphore or binary semaphore. For example, for the above declarations, the following +functions are available at runtime:

+ +
/* Lock mutex m */
+int m_lock(void);
+
+/* Unlock mutex m */
+int m_unlock(void);
+
+/* Wait on semaphore s */
+int s_wait(void);
+
+/* Try to wait on semaphore s */
+int s_trywait(void);
+
+/* Post to semaphore s */
+int s_post(void);
+
+/* Wait on a binary semaphore b */
+int b_wait(void);
+
+/* Post to a binary semaphore b */
+int b_post(void);
+
+ +

The CAmkES mutexes and semaphores have the behaviour you would expect from an +seL4 or pthreads implementation.

+ +

There is no native support for inter-component locks. However, it is possible +to construct these on top of the CAmkES platform. An example of how you would +do this is shown in the lockserver example application in the CAmkES project +repository.

+ +

Direct Memory Access

+ +

Direct Memory Access (DMA) is a hardware feature that allows devices to read +and write memory without going via the CPU. It is intended to give a fast I/O +path to devices, for which memory access is usually the bottleneck.

+ +

This only has specific relevance in the context of CAmkES because on platforms +without an IOMMU devices perform DMA +accesses on physical memory, rather than virtual memory. The implications of +this are that, when a device is being directed to perform I/O by a driver, it +needs to know the physical address(es) of the memory it is about to access. On +seL4 reversing a virtual memory mapping requires specific capability operations +and thus CAmkES needs to be aware of any memory region which you intend to use +for DMA transfers.

+ +

To allocate some memory for DMA within a specific component instance you +describe a DMA pool with a size in bytes. For example,

+ +
assembly {
+  composition {
+    component Foo f;
+    ...
+  }
+  configuration {
+    f.dma_pool = 8192;
+  }
+}
+
+ +

This declares an 8KB pool of memory that is available for DMA operations. +Within the component you must allocate and release pointers into this region +with the camkes_dma_alloc and camkes_dma_free functions described above. +The allocation function accepts a size and alignment constraint, but be aware +that allocation may not be efficient or guaranteed when requesting more than +4Kb. Note that if you declare a DMA pool that is not page-aligned (4K on the +platforms we support) it will automatically be rounded up.

+ +

Efficient DMA

+ +

For components that need to perform large DMA operations, you will need to +allocate a large DMA pool. Backing the virtual address space mappings for such +a pool with 4KB frames can lead to performance issues. For this reason, you may +wish to use the command line option –largeframe-dma to back DMA pools with +large frames.

+ +

This is relatively straightforward on IA32, but on an ARM platform you may run +into a limitation of the GNU Assembler that prevents the large alignments +required by the DMA pool. Support for working around this is provided by the +CAmkES build system, but is a little complicated, so the precise steps for +achieving this in a CAmkES project are documented below.

+ +

Enable large frame promotion for the DMA pool in your build configuration:

+ +
cmake . -DCAmkESDMALargeFramePromotion=ON
+
+ +

On older versions of binutils, if you were using a large enough DMA pool +to get promoted to large frames with an alignment constraint that was rejected +by the GNU Assembler, you should see output like the following:

+ +
/tmp/ccfGhK5Z.s: Assembler messages:
+/tmp/ccfGhK5Z.s:1483: Error: alignment too large: 15 assumed
+
+

Updating binutils should fix this issue.

+ +

Error Handling

+ +

Some runtime conditions can lead to an error in the glue code. For example, if +an interface accepts a string parameter and the caller passes a string that is +too large to fit in the IPC buffer. Errors can also arise in glue code if your +user code is not well-behaved and attempts to operate directly on capabilities. +The glue code attempts to handle all errors occurring from user mistakes and +malicious user code, to the best of its abilities. It also attempts to handle +errors that occur as a result of unexpected runtime conditions. For example, +accesses to a device that unexpectedly is not found at runtime.

+ +

The mode of error handling can be configured at compile-time, but the default +mode is generally the only relevant one you will need. It allows for runtime +handling of errors. By default, all errors cause a diagnostic message and a +system halt on a debug kernel. To alter this behaviour, user code can call the +function camkes_register_error_handler (described in +Runtime API) and provide their own error handling function. +The user’s error handling will thenceforth be invoked by glue code whenever an +error is detected. The error handling function should return one of the +following values, documented further in camkes/error.h, that indicate to the +glue code how it should proceed:

+ +
    +
  • +

    CEA_DISCARD — Ignore whatever message or request was currently being +handled and return to the original calling function of the user or an event +loop as appropriate. This is typically the failure mode you want for servers +that are intended to be robust against denial-of-service attacks from +malicious clients.

    +
    • +
  • +

    CEA_IGNORE — Pretend the error was not detected and continue executing. +This is almost never the response you want to take, but it can be useful for +debugging or masking spurious errors.

    +
    • +
  • +

    CEA_ABORT — Terminate the current thread with failure status. This is a +fail-stop response, though note it will not halt the rest of the system. If +the glue code is currently handling a request on behalf of a client, the +client will likely end up stuck blocked waiting for a response.

    +
    • +
  • +

    CEA_HALT — Halt the entire system. This is only possible on a debug +kernel. On a release kernel it will act identically to CEA_ABORT.

    +
    • +
+ +

To conditionally determine which response to return, the error handler is +passed a structure that describes the error that was detected. For details on +this structure, refer to camkes/error.h.

+ +

The mechanism just described allows for handling errors at a component-wide +level. In a more complicated component, there are often notional subsystems +that want to be able to handle their own errors independently. For this there +are interface-specific error handlers. Each interface has its own error handler +registration function as interface_register_error_handler. Any interface that +does not have a registered interface-specific error handler will default to the +component-wide error handler.

+ +

Custom Attributes

+ +

CAmkES allows the programmer to define arbitrary attributes of components.

+ +
component Foo {
+  attribute string a;
+  attribute int b;
+}
+
+ +

These attributes are set in the configuration section of the assembly:

+ +
assembly {
+  composition {
+    component Foo f;
+    ...
+  }
+  configuration {
+    f.a = "Hello, World!";
+    f.b = 42;
+    ...
+  }
+}
+
+ +

This results in the specified values being available as global variables +in the glue code with the same name as the attribute.

+ +
const char * a = "Hello, World!";
+const int b = 42;
+
+ +

Attribute’s conversion to literal

+ +

Unfortunately, the C language (in contrast to C++) does not support using +lvalues as literals (e.g. when declaring an array), even if declared as const, +so we need to introduce a “mechanism” for converting CAmkES attributes to +literals.

+ +

The CAMKES_CONST_ATTR macro has been introduced for that purpose.

+ +

Actually, the macro does not really convert arbitrary variables, but rather +CAmkES declares a const variable and also adds a respective macro to the code, +which is then used for that purpose.

+ +

Usage example is presented below:

+ +
/* main.camkes */
+assembly {
+    composition {
+        component FOO foo;
+    }
+    configuration {
+        foo.lenData  = 16;
+    }
+}
+
+/* Foo.c */
+const int foo[CAMKES_CONST_ATTR(lenData)] = { 0 };
+
+int run()
+{
+#if CAMKES_CONST_ATTR(lenData) < 0xF0
+    return 0;
+#else
+    return 1;
+#endif
+}
+
+ +

Hardware Components

+ +

A hardware component represents an interface to hardware in the form of a component. +Declaring a component with the hardware keyword creates a hardware component.

+ +
component Device {
+  hardware;
+
+  provides IOPort io_port;
+  emits Interrupt irq;
+  dataport Buf mem;
+}
+
+ +

When an interface of a device component instance is connected to a regular +component, that component gets access to that device via some +hardware interface (interface here refers to a means of interacting with +hardware - not a CAmkES interface). +The type of hardware interface depends on the type of CAmkES interface, +and the connector used. Available connectors for hardware, and their +corresponding hardware interfaces are listed below.

+ +

Interface: procedure
+Keyword: provides
+Connector: seL4HardwareIOPort
+Description: +When using IOPort as the interface type, this provides access to IO ports. The connected +component gets access to the methods in the IOPort interface, which allow sending and receiving +data over IO ports. This is specific to the IA32 architecture.

+ +

Interface: event
+Keyword: emits
+Connector: seL4HardwareInterrupt
+Description: +An event is emitted when an interrupt occurs.

+ +

Interface: port
+Keyword: dataport
+Connector: seL4HardwareMMIO
+Description: +Memory mapped registers can be accessed via the shared memory.

+ +

The following shows an example of connecting a hardware component to a driver +component. Note the order of arguments to the connection. seL4HardwareInterrupt requires +the hardware interface on the from side of the connection, whereas the other connectors +require the hardware interface on the to side.

+ +
component Driver {
+  uses IOPort io_port;
+  consumes Interrupt irq;
+  dataport Buf mem;
+}
+
+assembly {
+  composition {
+    component Device dev;
+    component Driver drv;
+    ...
+    connection seL4HardwareIOPort ioport_c(from drv.io_port, to dev.io_port);
+    connection seL4HardwareInterrupt irq_c(from dev.irq, to drv.irq);
+    connection seL4HardwareMMIO mmio_c(from drv.mem, to dev.mem);
+  }
+}
+
+ +

Configuration

+ +

Each type of hardware component interface has some configuration required for it +to work. This is done by setting attributes of instances of device components.

+ +
MMIO
+ +

The physical address of the memory, and size (in bytes) to make available +to a connected component must be specified. The example below specifies that +the port named mem of the component instance d is a 0x1000 byte region +starting at physical address 0xE0000000.

+ +
component Device {
+  hardware;
+
+  dataport Buf mem;
+  ...
+}
+
+assembly {
+  composition {
+    component Device d;
+    ...
+  }
+  configuration {
+    d.mem_paddr = 0xE0000000;
+    d.mem_size = 0x1000;
+    ...
+  }
+}
+
+ +
Interrupts
+ +

Depending on the platform different information needs to specified to +connect a hardware interrupt source with a components interrupt handler.

+ +

On ARM and if you are using the legacy x86 PIC controller then simply an +interrupt number must be specified. The example below specifies that +the event will be emitted when interrupt number 2 is received.

+ +
component Device {
+  hardware;
+
+  emits Interrupt irq;
+  ...
+}
+
+assembly {
+  composition {
+    component Device d;
+    ...
+  }
+  configuration {
+    d.irq_irq_number = 2;
+    ...
+  }
+}
+
+ +

If using the newer I/O APIC controller on x86 then you need to describe +the I/O APIC source and provide a destination vector. An I/O APIC source +is described in terms of

+ +
    +
  • Physical I/O APIC controller indexed starting at 0. Typically a system +only has one of these
    • +
  • Pin, ranging from 0 to 23, on the I/O APIC controller that the interrupt +will come in on
    • +
  • The trigger mode and polarity of the interrupt
    • +
+ +

The destination vector is a number in the range of 0 to 107 and must be unique +across all destination vectors defined in an assembly.

+ +

Selecting between edge and level trigger modes is done by setting the +*_irq_ioapic_level attribute where a value of 1 means level triggered and +0 means edge triggered. Similarly the active polarity is configured by +the *_irq_ioapic_polarity attribute where a value of 1 means active +low and 0 means active high.

+ +

To change the previous example to connect an interrupt on I/O APIC 0, pin 2 +that is edge triggered with active high polarity you would change

+ +
d.irq_irq_number = 2;
+
+ +

To become

+ +
d.irq_irq_type = "ioapic";
+d.irq_irq_ioapic = 0;
+d.irq_irq_ioapic_pin = 2;
+d.irq_irq_ioapic_polarity = 0;
+d.irq_irq_ioapic_level = 0;
+d.irq_irq_vector = 42;
+
+ +

With the vector being arbitrarily chosen as 42

+ +

An interrupt that is edge triggered and active high can be more concisely +declared as an ISA interrupt by

+ +
d.irq_irq_type = "isa";
+d.irq_irq_ioapic = 0;
+d.irq_irq_ioapic_pin = 2;
+d.irq_irq_vector = 42;
+
+ +

Similarly if this interrupt were to be level triggered and active low it +could be declared as a PCI interrupt by

+ +
d.irq_irq_type = "pci";
+d.irq_irq_ioapic = 0;
+d.irq_irq_ioapic_pin = 2;
+d.irq_irq_vector = 42;
+
+ +
IO Ports
+ +

The allowable range of IO Ports must be specified. +The example below specifies that the hardware component instance +d may access IO ports greater than or equal to 0x60, and less +than 0x64.

+ +
component Device {
+  hardware;
+
+  provides IOPort io_port;
+  ...
+}
+
+assembly {
+  composition {
+    component Device d;
+    ...
+  }
+  configuration {
+    d.io_port_attributes = "0x60:0x64";
+    ...
+  }
+}
+
+ +

Port Privileges

+ +

CAmkES allows the programmer to specify access rights that instances have over +the ports connecting them to other instances. This is done by setting the +*_access attribute of the port. The value of the attribute must be a string +containing the letters “R”, “W” and “X”, giving the port read, write and execute +privileges, respectively. If left unspecified, full access will be given.

+ +

In the example below, instance f has read-only access to port_a, and +instance b has read/write access to port_a. Instance b has read-only +access to port_b. Instance a has read/write/execute access to port_b even +though it’s not explicitly stated, as this is the default.

+ +
component Foo {
+  dataport Buf data_a;
+  dataport Buf data_b;
+}
+
+component Bar {
+  dataport Buf data_a;
+  dataport Buf data_b;
+}
+
+assembly {
+  composition {
+    component Foo f;
+    component Bar b;
+    ...
+    connection seL4SharedData port_a(from f.data_a, to b.data_a);
+    connection seL4SharedData port_b(from f.data_b, to b.data_b);
+    ...
+  }
+  configuration {
+    f.data_a_access = "R";
+    b.data_a_access = "RW;
+    f.data_b_access = "R";
+    ...
+  }
+}
+
+ +

Thread Model

+ +

CAmkES components are typically multithreaded and, to prevent race conditions, +it is often necessary to understand what threads exist in your system.

+ +

Firstly there is a single active thread. This is the thread of control that +calls the component’s entry point for components declared control. This +thread is present even in non-control components in order to perform +initialisation actions.

+ +

Each interface your component interacts with, either as an incoming or outgoing +interface, induces another thread within the component. Initial synchronisation +of these threads and their various setup activities is all handled by generated +code. Note that this per-interface thread is present even for interfaces that +you may think of as passive. For example, dataports. This is merely an +implementation artefact and may change in future.

+ +

One thing that may not be intuitive for users is that you have no guarantee as +to which thread will invoke an event callback. If you have registered a +callback for an event you are receiving, you should not assume that any +thread-local state persists between invocations. This is because the thread +which invokes a callback may not be the same thread as was used last time the +callback was invoked.

+ +

Thread Priorities

+ +

Each thread in a CAmkES system has a priority that determines how it is +scheduled by seL4. These priorities default to a value given by the +--default-priority command-line argument to the runner. The higher number, +the higher thread’s priority, that is, a thread with priority 100 will be +executed before a thread with priority 90.

+ +

In a given system, it it possible to adjust the priority of a specific thread +with an attribute that has specific semantics. To adjust the priority of the +control thread (the thread that calls run), use the _priority attribute:

+ +
assembly {
+  composition {
+    component Foo f;
+    ...
+  }
+  configuration {
+    f._priority = 100;
+  }
+}
+
+ +

To adjust the priority of an interface thread, use an attribute named with the +name of the interface and the suffix ``_priority’’:

+ +
component Foo {
+  uses MyInterface i;
+}
+
+assembly {
+  composition {
+    component Foo f;
+    ...
+  }
+  configuration {
+    f.i_priority = 100;
+  }
+}
+
+ +

If you want to adjust the priority of every thread within a given component +instance, you can use a general component attribute:

+ +
configuration {
+  f.priority = 100;
+}
+
+ +

For more information about the specifics of the seL4 scheduler, please refer to +the seL4 documentation.

+ +

Thread CPU affinity

+ +

Each thread in a CAmkES system also has a processor affinity. This affinity will +by default bind all threads to CPU index 0, bootstrap-processor. In a system +where seL4 is built without multicore, setting this value above 0 is illegal.

+ +
component Mycomponent {
+    /* ... */
+    uses Myinterface i;
+}
+
+assembly {
+    composition {
+        component Mycomponent c;
+    }
+    configuration {
+        /* Run all threads in "c" on CPU 1 */
+        c.affinity = 1;
+    }
+}
+
+ +

Alternatively:

+ +
configuration {
+    /* Run only the control thread on CPU 1, but run the rest of the threads
+     * in this component on the "default" CPU (index 0).
+     */
+    c._affinity = 1;
+}
+
+ +

Or perhaps:

+ +
configuration {
+    /* Run only the interface thread for "i" on CPU 1, but run the rest of the
+     * threads in this component on the "default" CPU (index 0).
+     */
+    c.i_affinity = 1;
+}
+
+ +

Thread Stacks

+ +

Each CAmkES thread has a stack provided for it for use at runtime, as is +typical. Stack size defaults to 4K, but this default can be adjusted through +the relevant build system configuration option. Additionally the stacks of +individual threads within a component can be set with attributes:

+ +
configuration {
+
+  // Assign foo's control thread an 8K stack
+  foo._stack_size = 8192;
+
+  // Assign the interface thread for inf in foo a 16K stack
+  foo.inf_stack_size = 16384;
+
+}
+
+ +

Note that stacks must have a size that is 4K aligned, so if you assign a thread +a stack size that is not 4K aligned it will be rounded up. Stacks have a 4K +unmapped “guard page” either side of them. This is a debugging aid to force a +virtual memory fault when threads underrun or overrun their stacks.

+ +

Scheduling Domains

+ +

In CAmkES, it is possible to specify the domain each thread belongs to, by setting attributes. +Each interface of each component instance will have an associated thread, and +there will be an additional thread per-component to perform initialisation and +optionally act as the control thread. For interface threads, their domain can be +specified by setting the attribute <interface>_domain of the instance. For +control threads, the attribute _domain of the instance can be set.

+ +
component Foo {
+  control;
+  uses iface i;
+}
+
+component Bar {
+  provides iface o;
+}
+
+assembly {
+  composition {
+    component Foo f;
+    component Bar b;
+    connection seL4RPCCall c(from f.i, to b.o);
+    ...
+  }
+  configuration {
+    f._domain = 0;  // domain of control thread of f
+    b.o_domain = 1; // domain of o interface of b
+    ...
+  }
+}
+
+ +

Userspace RPC Transfer Buffers

+ +

By default, the majority of RPC connectors exchange data through a +kernel-managed IPC buffer. RPC communication involving longer messages can be +optimised by exchanging data through userspace buffers instead of the IPC +buffer. To achieve this, set up an seL4SharedData connection and assign a +custom attribute:

+ +
component Foo {
+  uses iface i;
+  dataport Buf d;
+}
+
+component Bar {
+  provides iface j;
+  dataport Buf e;
+}
+
+assembly {
+  composition {
+    component Foo foo;
+    component Bar bar;
+
+    connection seL4RPCCall conn(from foo.i, to bar.j);
+    connection seL4SharedData ubuf(from foo.d, to bar.e);
+  }
+  configuration {
+    conn.buffer = "ubuf";
+  }
+}
+
+ +

There are a few limitations to be aware of when using this technique. The only +RPC connector that supports this style of userspace communication at time of +writing is seL4RPCCall. The RPC connection must be 1-to-1 and the +seL4SharedData connection must connect the same two component instances. The +size of the buffer (determined by the dataports’ type) is flexible, but if you +use a buffer that is too small to accommodate RPC data you will trigger runtime +errors during parameter marshalling.

+ +

Multi-Assembly Applications

+ +

CAmkES allows programmers to define an arbitrary number of assemblies for their application. +Different assemblies may appear in different files, provided that they are appropriately +included in the main ADL file. At compile time, the bodies of each +assembly are merged together, with all declared names remaining the same. +Thus, naming conflicts can occur on items declared in different assemblies.

+ +
assembly {
+  composition {
+    component Foo f;
+  }
+}
+
+assembly {
+  composition {
+    component Bar b;
+    connection seL4RPCCall c(from f.a, to b.a);
+  }
+  configuration {
+    f.some_attribute = 0;
+  }
+}
+
+ +

The example above is equivalent to:

+ +
assembly {
+  composition {
+    component Foo f;
+    component Bar b;
+    connection seL4RPCCall c(from f.a, to b.a);
+  }
+  configuration {
+    f.some_attribute = 0;
+  }
+}
+
+ +

Hierarchical Components

+ +

Syntax

+ +

A component definition may include a composition and configuration section. +The composition and configuration sections must be the last items in the component definition. +The composition and configuration sections may appear in any order. A composition section +can be included without a configuration, however a configuration section is only allowed +if there is a composition.

+ +
component Foo_Impl {
+  provides iface_a a_impl;
+  attribute string str;
+}
+
+component Foo {
+  provides iface_a a;
+
+  composition {
+    component Foo_Impl fi;
+    export fi.a_impl -> a;
+  }
+  configuration {
+    fi.str = "Hello, World!";
+  }
+}
+
+component Bar {
+  control;
+  uses iface_a a;
+}
+
+assembly {
+  composition {
+    component Foo f;
+    component Bar b;
+    connection seL4RPCCall c(from b.a, to f.a);
+  }
+}
+
+ +

In the example above, the component Foo exposes a virtual interface a, +which is exported from the interface a_impl of the component instance fi of type Foo_Impl.

+ +

Hierarchy Resolution

+ +

Prior to compilation, the AST representing the system is transformed to remove all +hierarchical components. For each instance of a compound component, any internal instances +and internal connections declared +inside the component are copied into the top-level assembly with the compound component instance’s +name prepended to their own. +Each appearance of a virtual interface of some compound component instance +in a connection in the top-level assembly, is replaced +with the exported interface of the internal instance copied into the top-level assembly +while resolving that compound component instance. +Then, for each compound component, all virtual interfaces are removed. +If this results in any components with no interfaces, these components, and all instances +of such components, are removed from the specification.

+ +

The example above would be converted into the following:

+ +
component Foo_Impl {
+  provides iface_a a_impl;
+  attribute string str;
+}
+
+component Bar {
+  control;
+  uses iface_a a;
+}
+assembly {
+  composition {
+    component Bar b;
+    component Foo_Impl f.fi;
+    connection seL4RPCCall c(from b.a, to f.fi.a_impl);
+  }
+  configuration {
+    f.fi.str = "Hello, World!";
+  }
+}
+
+ +

Examples

+ +
Connecting multiple compound components
+ +

It’s possible for both sides of a connection to be virtual interfaces:

+ +
component Foo_Impl {
+  provides iface_a a_impl;
+}
+
+component Bar_Impl {
+  uses iface_a a_usage;
+}
+
+component Foo {
+  provides iface_a a;
+
+  composition {
+    component Foo_Impl fi;
+    export fi.a_impl -> a;
+  }
+}
+
+component Bar {
+  uses iface_a a;
+
+  composition {
+    component Bar_Impl bi;
+    export bi.a_usage -> a;
+  }
+}
+
+assembly {
+  composition {
+    component Foo f;
+    component Bar b;
+    connection seL4RPCCall c(from b.a, to f.a);
+  }
+}
+
+ +

This example compiles to:

+ +
component Foo_Impl {
+  provides iface_a a_impl;
+}
+
+component Bar_Impl {
+  uses iface_a a_usage;
+}
+
+assembly {
+  composition {
+    component Foo_Impl f.fi;
+    component Bar_Impl b.bi;
+    connection seL4RPCCall c(from b.bi.a_usage, to f.fi.a_impl);
+  }
+}
+
+ +
Compound component with non-virtual interfaces
+ +

A component can have both virtual and implemented interfaces:

+ +
component Foo_Impl {
+  provides iface_a a_impl;
+}
+
+component Foo {
+  provides iface_a a;
+  provides iface_b b;
+
+  composition {
+    component Foo_Impl fi;
+    export fi.a_impl -> a;
+  }
+}
+
+component Bar {
+  uses iface_a a;
+  uses iface_b b;
+}
+
+assembly {
+  composition {
+    component Foo f;
+    component Bar b;
+    connection seL4RPCCall c(from b.a, to f.a);
+    connection seL4RPCCall c(from b.b, to f.b);
+  }
+}
+
+ +

This example compiles to:

+ +
component Foo_Impl {
+  provides iface_a a_impl;
+}
+
+component Foo {
+  provides iface_b b;
+}
+
+component Bar {
+  uses iface_a a;
+  uses iface_b b;
+}
+
+assembly {
+  composition {
+    component Foo f;
+    component Bar b;
+    component Foo_Impl f.fi;
+    connection seL4RPCCall c(from b.a, to f.fi.a_impl);
+    connection seL4RPCCall c(from b.b, to f.b);
+  }
+}
+
+ +
Deeper Hierarchy
+ +

So far, each example has had a compound component containing only non-compound component instances. +It’s possible to have a hierarchy of components of an arbitrary depth.

+ +
component A_Piece1 {
+  provides a_piece ap;
+}
+
+component A_Piece2 {
+  uses a_piece ap;
+  provides iface_a a_impl;
+}
+
+component Foo_Impl {
+  provides iface_a a_impl;
+
+  composition {
+    component A_Piece1 a1;
+    component A_Piece2 a2;
+    connection seL4RPCCall c(from a1.ap, to a2.ap);
+    export a2.a_impl -> a_impl;
+  }
+}
+
+component Foo {
+  provides iface_a a;
+
+  composition {
+    component Foo_Impl fi;
+    export fi.a_impl -> a;
+  }
+}
+
+component Bar {
+  uses iface_a a;
+}
+
+assembly {
+  composition {
+    component Foo f;
+    component Bar b;
+    connection seL4RPCCall c(from b.a, to f.a);
+  }
+}
+
+ +

This example compiles to:

+ +
component A_Piece1 {
+  provides a_piece ap;
+}
+
+component A_Piece2 {
+  uses a_piece ap;
+  provides iface_a a_impl;
+}
+
+component Bar {
+  uses iface_a a;
+}
+
+assembly {
+  composition {
+    component Bar b;
+
+    component A_Piece1 f.fi.a1;
+    component A_Piece2 f.fi.a2;
+
+    connection seL4RPCCall f.fi.c(from f.fi.a1.ap, to f.fi.a2.ap);
+    connection seL4RPCCall c(from b.a, to f.fi.a2.a_impl);
+  }
+}
+
+ +

Hierarchical Attributes

+ +

Attributes of internal instances and internal connections declared in the composition section +of a compound component may be set to refer to attributes of that compound component. During +hierarchy resolution, values of referring attributes are set to copies of the values of +their corresponding referent attributes.

+ +

Syntax

+ +

The <- operator is used to set an attribute to refer to another. Lines of the following form +may appear in the configuration section of a compound component:

+ +
entity_name.attribute_name <- local_attribute_name;
+
+ +

Here, entity_name is the name of a component instance or connection declared in the component’s +composition section, attribute_name is the name of an attribute of the entity, and +local_attribute_name is the name of an attribute of the composition component.

+ +

Example

+ +
component B {
+  ...
+  attribute string b_str;
+}
+
+component A {
+  ...
+  attribute string a_str;
+
+  composition {
+    ...
+    component B b;
+  }
+  configuration {
+    ...
+    b.b_str <- a_str;
+  }
+}
+
+assembly {
+  composition {
+    ...
+    component A a;
+  }
+  configuration {
+    ...
+    a.a_str = "Hello, World!";
+  }
+}
+
+ +

This example is resolved to the following:

+ +
component B {
+  ...
+  attribute string b_str;
+}
+
+component A {
+  ...
+  attribute string a_str;
+}
+
+assembly {
+  composition {
+    ...
+    component A a;
+    component B a_b;
+  }
+  configuration {
+    ...
+    a.a_str = "Hello, World!";
+    a_b.b_str = "Hello, World!";
+  }
+}
+
+ +

Custom Data Types

+ +

CAmkES allows the definition of custom data types for procedure method arguments and ports. +Data types can be defined in C header files by typedefing a struct, enum or built-in type. +Sections of the application that refer to custom types must include the header file.

+ +

Procedures

+ +

Assume a data type Vector is defined in the file vector.h in the top level include directory of the application:

+ +
#ifndef _VECTOR_H_
+#define _VECTOR_H_
+
+typedef struct {
+  double x;
+  double y;
+} Vector;
+
+#endif
+
+ +

A procedural interface could then be defined to use the type:

+ +
procedure algebra_iface {
+  include <vector.h>;
+  Vector add(Vector a, Vector b);
+}
+
+ +

C source files that need access to this data type can include the file with:

+ +
#include <vector.h>
+
+ +

To make the build system aware of the header file, for each component that uses it, the following must be added +to the application’s CMakeLists.txt (replacing the name Component with the name of the component):

+ +
DeclareCAmkESComponent(Component INCLUDES include/vector.h)
+
+ +

Ports

+ +

Assume a data type IntArray is defined in int_array.h in the top level include directory of the application:

+ +
#ifndef _INT_ARRAY_H_
+#define _INT_ARRAY_H_
+
+typedef struct {
+  int data[1024];
+} IntArray;
+
+#endif
+
+ +

A component could declare a port of this type:

+ +
component A {
+  control;
+
+  include "int_array.h";
+  dataport IntArray int_arr;
+}
+
+ +

This would give the implementation access to a global pointer, which points to +an appropriately large region of memory for the data type:

+ +
extern volatile IntArray * int_arr;
+
+ +

Single Address Space Components (Groups)

+ +

By default, each component instance in an application is given its own address +space. This is ideal for isolation, but this separation does not come for free +and inter-address space communication is necessarily more expensive than local +communication. To colocate two component instances in a single address space, +they can be grouped together:

+ +
assembly {
+  composition {
+    group my_group {
+      component Foo foo;
+      component Bar bar;
+    }
+  }
+}
+
+ +

Any references to such instances now need to be qualified by their group name. +For example, to connect the above two instances:

+ +
...
+connection seL4RPCCall conn(from my_group.foo.inf1,
+  to my_group.bar.inf2);
+...
+
+ +

When component instances are colocated, another connector becomes available. +The seL4DirectCall connector collapses RPC communication into a direct +function call. Its usage is identical to other connectors:

+ +
...
+connection seL4DirectCall conn(from my_group.foo.inf1,
+  to my_group.bar.inf2);
+...
+
+ +

Using this connector between two components that are not colocated is incorrect +and will trigger an error.

+ +

Caveats

+ +

When colocating component instances in a single address space, the intent is +for the environment of the instances to be as close to indistinguishable as +possible (with the exception of performance characteristics) from full +separation. This abstraction is not perfect and there are some mechanisms that +have slightly different semantics when used in a single address space scenario +and in an isolated scenario.

+ +

Parameters of direction out of certain types are typically heap-located in an +isolated component instance. This is still true in a colocated environment, but +when using the seL4DirectCall connector, these are located in the callee’s +heap, not the caller’s as may be otherwise expected. Freeing one of these +pointers to the incorrect heap will result in heap corruption and should be +avoided. Conversely, not freeing this pointer will leak memory and should also +be avoided. The recommended technique to work around this is to introduce a back +channel to the callee when necessary:

+ +
procedure my_proc {
+  /* The following procedure will return a parameter, `x`,
+   * that is a pointer into the callee's heap. It cannot
+   * be directly freed by the caller and needs to be
+   * passed back to the callee.
+   */
+  void foo(out string x);
+
+  /* We provide a back channel for this. */
+  include <stdint.h>;
+  void remote_free(uintptr_t p);
+}
+
+component Caller {
+  control;
+  uses my_proc f;
+}
+
+component Callee {
+  provides my_proc g;
+}
+
+assembly {
+  composition {
+    component Caller caller;
+    component Callee callee;
+
+    connection seL4DirectCall conn(from caller.f, to callee.g);
+  }
+}
+
+ +

It is then possible to implement both components’ code in such a way that +memory is always freed to the correct heap:

+ +
/* Caller.c */
+
+int run(void) {
+  char *x;
+  f_foo(&x);
+  printf("received %s\n", x);
+  f_remote_free((uintptr_t)x);
+  return 0;
+}
+
+ +
/* Callee.c */
+
+void g_foo(char **x) {
+  *x = strdup("hello world");
+}
+
+void g_remote_free(uintptr_t p) {
+  free((void*)p);
+}
+
+ +

This is cumbersome, but at least allows one to write safe code. In a +continually evolving project, it may not be known in advance whether +seL4DirectCall will be used. In these situations, it is recommended to use a +free wrapper that detects where a pointer is hosted. In the case of a simple +static heap region (the default), a wrapper can be constructed as follows:

+ +
/* Caller.c */
+
+static void safe_free(void *p) {
+  /* These symbols are defined by generated code and
+   * specify the bounds of the heap.
+   */
+  extern char *morecore_area;
+  extern size_t morecore_size;
+
+  if ((uintptr_t)p >= (uintptr_t)morecore_area &&
+      (uintptr_t)p < (uintptr_t)morecore_area + morecore_size) {
+    /* The pointer is in our heap. */
+    free(p);
+  } else {
+    /* The pointer is in the callee's heap. */
+    f_remote_free((uintptr_t)p);
+  }
+}
+
+int run(void) {
+  char *x;
+  f_foo(&x);
+  printf("received %s\n", x);
+  safe_free(x);
+  return 0;
+}
+
+ +

The preceding discussion dealt with out parameters, but note that the same +issue exists on both sides of an seL4DirectCall connection using inout +parameters. That is, the argument to the callee and the final value to the +caller are both pointers that would normally point into a local heap, but now +potentially point into a remote heap.

+ +

As a result of toolchain limitations, +link-time optimisations cannot +be applied to a component group. If you have LTO enabled in your build settings +it will be ignored for component groups.

+ +

Global Include Directories

+ +

CAmkES allows users to define a list of directories that will be searched +when resolving imports of .camkes files (components and interfaces). +CAmkESAddImportPath(interfaces) will append a directory to this search path. +There is an additional path for templates which can be modified by calling +CAmkESAddTemplatesPath(templates). The repository global-components repository +is an example of these mechanisms being used to import components, interfaces +and templates into a project. The target project simply needs to include +global-components.cmake to enable these modules to be referred to from within +the project’s camkes files. Below is an example of importing global-components:

+
find_file(GLOBAL_COMPONENTS_PATH global-components.cmake PATHS ${CMAKE_SOURCE_DIR}/projects/global-components/ CMAKE_FIND_ROOT_PATH_BOTH)
+mark_as_advanced(FORCE GLOBAL_COMPONENTS_PATH)
+if("${GLOBAL_COMPONENTS_PATH}" STREQUAL "GLOBAL_COMPONENTS_PATH-NOTFOUND")
+    message(FATAL_ERROR "Failed to find global-components.cmake. Consider cmake -DGLOBAL_COMPONENTS_PATH=/path/to/global-components.cmake")
+endif()
+include(${GLOBAL_COMPONENTS_PATH})
+
+
+ +

This allows one to place common components and interfaces in a central location +rather than duplicating them inside the application directory of each +application that uses them. Components and interfaces defined in global include +directories are known as Global Components and Global Interfaces. +When the distinction is necessary, non-global components and interfaces are +known as Local Components and Local Interfaces.

+ + + +

Generally, a component should be created as a global component unless there’s +some good reason not to. Applications should consist of a (usually) small number +of control components, and possibly some application specific utility components. +When possible, utility components should be generalised and placed in a global +component repository.

+ +

All procedural interfaces used or provided by global components should be +global interfaces. Applications containing multiple local components which +communicate over procedural interfaces should define these interfaces locally, +unless it would make sense for these interfaces to generalise to other components +in the future, in which case they should be global interfaces.

+ +

Regarding header files defining custom data types, if the data type is specific to +a particular component or procedural interface, the header file should be placed +in the directory of that component or interface. Otherwise, header files should +be placed in a well known top-level subdirectory of the component repository so +they may be reused between components and interfaces.

+ +

It is possible that between global components, there is some shared functionality +such as commonly used algorithms and data structures. Rather than duplicating this +code across multiple global components, it should be placed in source/header files +in a well known top-level subdirectory of the component repository.

+ +

Cached Hardware Dataports

+ +

By default, memory backing hardware dataports (seL4HardwareMMIO) is mapped uncached. +Typically such a dataport will be backed by a device’s memory mapped registers rather +than main memory. In such cases it’s generally desired that after writing to a register +the effect of the write is felt immediately, and changes to device registers are observable +as soon as they occur, so mapping this memory uncached makes sense. There are however, +cases where it is preferable to map this memory cached instead.

+ +

For example, consider a system that updates a large memory mapped frame buffer for +a display, by writing to it one word at a time. If this buffer was mapped uncached, +each word written to the buffer would incur the full time taken to write to memory. +If instead, the buffer was mapped cached, each word would be written to the cache, +incurring a much shorter write time. Cache lines would then be written back to memory +at a later point. This optimization works on the assumption that the throughput of +the cache being written back to memory is higher than that of the CPU writing +directly to memory a word at a time. After all the data has been written to the buffer, +the cache must be flushed to ensure the data is actually in the buffer.

+ +

CAmkES provides a mechanism for flushing the cache, but currently it is a no-op +on all architectures other than ARM. On x86, the DMA engine is cache-coherent, +so there’s no reason to explicitly flush the cache after writing to a cached +hardware dataport.

+ +

Marking a hardware dataport as cached

+ +

To map a hardware dataport cached, set the <instance>.<interface>_hardware_cached attribute to true:

+ +
component DisplayDevice {
+  hardware;
+  dataport FrameBuffer framebuffer;
+}
+
+component DisplayDriver {
+  ...
+  dataport FrameBuffer framebuffer;
+}
+
+assembly {
+  composition {
+    component DisplayDevice display_device;
+    component DisplayDriver display_driver;
+    ...
+
+    connection seL4HardwareMMIO fbconn(
+      from display_driver.framebuffer,
+      to display_device.framebuffer
+    );
+  }
+  configuration {
+    ...
+    display_device.framebuffer_hardware_cached = true; /* <-- set this attribute
+                                               *     to mark dataport
+                                               *     as cached
+                                               */
+  }
+}
+
+ +

Manipulating the cache

+ +

After writing to a cached hardware dataport, or potentially prior to reading from it, +it is necessary to manipulate the cache to ensure a consistent view of the memory +between the CPU and any devices. CAmkES provides a function for each hardware dataport +for doing cache operations on the range of addresses inside the dataport.

+ +

For a dataport interface named framebuffer, the function that operates on the cache +will be

+ +
int framebuffer_cache_op(size_t start_offset, size_t size, dma_cache_op_t cache_op)
+
+ +

start_offset and size are the offset in bytes into the dataport to start flushing, +and the number of bytes to flush respectively. cache_op is one of the three defined +cache operations: DMA_CACHE_OP_CLEAN, DMA_CACHE_OP_INVALIDATE, DMA_CACHE_OP_CLEAN_INVALIDATE. +The function returns 0 on success and non-zero on error

+ +

Templating

+ +

CAmkES glue code, code automatically introduced into your component system at +compile time, is driven by a set of templates. These templates are instantiated +with values determined from your input ADL specification. CAmkES templates are +written as C code with Python snippets embedded in comments. This is all driven +by the Jinja2 templating engine. You can see +examples of existing templates in camkes/templates/.

+ +

The remainder of this section gives advice for people intending to implement +their own templates or modify existing templates. If you are attempting to +modify the template context itself, you should instead refer to the +Template Context section.

+ +

Template Writing

+ +

Inside a template you write C code as you would normally, but use the following +special comments to run Python code:

+ +
    +
  • /*- execute code -*/ (equivalent of Python’s exec)
    • +
  • /*? execute code and replace with result -*/ (equivalent of Python’s eval)
    • +
  • /*# a comment to be removed at instantiation #*/
    • +
+ +

In general, when writing code in a template, refer to the Jinja documentation +syntax and functionality. Note that the default Jinja delimiters have been modified +to /* and */ to let syntax highlighting in C work more naturally.

+ +

Within a given template you have a variable me that functions like native +Python’s self. It refers to the object of relevance to the current template. +So, for example, during instantiation of the component source file, it refers +to the component instance being instantiated. In certain general “top-level” +templates, there is no particular “subject.” In these templates, for example +camkes-gen.cmake, me will be None.

+ +

The template context is a limited subset of Python. It is relatively easy +to extend, and if you intend to do this you can see how in the +Template Context section. Some statements in +Python could not be cleanly exposed and so have instead become functions. In +particular, be aware of quirks in assertions, lambdas and exceptions. assert +is available as a function. So instead of writing assert foo == 1 you would +write assert(foo == 1).

+ +

Lambdas are perhaps more confusing. Instead of writing +lambda x: x.startswith('hello') you would write +lambda('x: x.startswith(\'hello\')'. Note that you lose some type safety and +expressivity here, but there did not seem to be a nicer way to expose this. +Exceptions are now also raised by function. So instead of writing +raise Exception('foo') you would write raise(Exception('foo')).

+ +

For the specific functionality available in the template context, it may be +helpful to refer to the file camkes/runner/Context.py. Note that in the +template context you also have access to the command line options via options +as well.

+ +

Idioms

+ +

There are certain common operations you may wish to perform inside a template +context, for which idioms have developed. This section documents some of these +snippets of code that may look unusual when you first encounter them.

+ +

Passing Information Between Templates

+ +

You often wish to do this with two related templates. For example, in the +templates that form each side of a connection you often wish to talk about the +same object on both sides. None of the templates currently call the low-level +helper functions that enable this directly, but if you do want to invoke them, +they are stash and pop. stash lets you save a Python object under a given +key name and pop retrieves a previously saved Python object by key. Note that +these are only usable for passing objects between templates that share related +me references.

+ +

Generating Symbol Names

+ +

Within a C template you sometimes need a temporary variable in a context in +which user-provided variables may be in scope. That is, you need a named symbol +but you need to ensure it doesn’t collide with any existing user symbols. To do +this you can call the function c_symbol. This generates a pseudo-unique name +that you can use from then on. For example,

+ +
/*- set my_var = c_symbol() -*/
+int /*? my_var ?*/ = 42;
+...
+
+ +

c_symbol takes an optional string argument that will make that string part of +the resulting symbol name. This is helpful for debugging purposes if you want +to give someone looking at the instantiated template a visual clue as to the +purpose of a temporary variable.

+ +

Subverting Scoping

+ +

Jinja has some unusual and often counter-intuitive variable scoping rules. +Occasionally templates wish to conditionally assign to a variable within the +context of a loop or other Jinja block. In these circumstances it can be tricky +to get the write to propagate outside the loop. You may see a temporary array +and a do construct used in these situations:

+ +
/*- set temp = [None] -*/
+/*- for .... -*/
+  ...
+  /*- if ... -*/
+    /*- do temp.__setitem__(0, True) -*/
+  /*- else -*/
+    /*- do temp.__setitem__(0, False) -*/
+  /*- endif -*/
+  ...
+/*- endfor -*/
+/*- set variable_we_want_to_set = temp[0] -*/
+
+ +

Reply Capabilities

+ +

The seL4 system call, seL4_Call, generates transient capabilities called +reply capabilities (see the seL4 documentation for more specific details). Care +must be taken when writing template code in order to avoid interfering with the +functionality of another piece of template code that may have created reply +capabilities. If you are not using reply capabilities yourself, there is a +simple rule to remember:

+ +
    +
  • always call camkes_protect_reply_cap() before performing an operation that +would cause a wait on a synchronous endpoint.
    • +
+ +

This call is idempotent (you can call it multiple times in sequence with no ill +effects), though be aware it may modify the contents of your IPC buffer. You +do not need to perform this operation when sending on a synchronous endpoint or +waiting on a notification, however it is necessary when performing +batched system calls like seL4_ReplyRecv or seL4_Call on a synchronous +endpoint.

+ +

If you are receiving reply capabilities in your own template and calling +external functionality before using them, you need to be aware that they can be +overwritten when execution is outside your template. To safe guard yourself +against this, there is a complementary rule:

+ +
    +
  • always call camkes_declare_reply_cap(...) when you have just received a +reply capability.
    • +
+ +

Note that you need to pass this function an empty capability slot into which to +save the reply capability if it is about to be overwritten. In order to support +saving of this reply capability on demand, CAmkES needs a capability to the +current thread’s CNode. This needs to be setup by your template code. Some +variant of the following code needs to be executed for each thread that could +receive a reply capability:

+ +
/*# Allocate a cap to our own CNode. #*/
+/*- set cnode = alloc_cap('cnode', my_cnode) -*/
+/* Configure a TLS pointer to our own CNode cap. */
+camkes_get_tls()->cnode_cap = /*? cnode ?*/;
+
+ +

When you need to use a reply capability you have protected, you should check +the reply_cap_in_tcb member of the CAmkES TLS structure and, if the capability +is no longer in your TCB, call camkes_unprotect_reply_cap() and deal with any +possible error that may have occurred. The functional API for dealing with +reply capabilities is provided below. Though this is technically part of the +runtime API, it is included here because user code is never +expected to call these functions.

+ +

int camkes_declare_reply_cap(seL4_CPtr shadow_slot) (#include <camkes/tls.h>)

+ +
+

Identify to the CAmkES library that you are in possession of a reply + capability in your TCB. CAmkES only handles a single reply capability + currently and, as such, you should not call this function when you have + previously declared a pending reply capability you have not yet discarded. + This essentially says to CAmkES, “I have a reply cap in my TCB; please save + it to shadow_slot if it is in risk of being deleted.”

+
+ +

void camkes_protect_reply_cap(void) (#include <camkes/tls.h>)

+ +
+

Guard any potential pending reply capability against deletion by saving it + now. Note that this function accepts no arguments and returns nothing. It is + designed to be called unconditionally from generated code that believes it + may be about to overwrite a reply capability. There is no point providing a + result to the caller because the caller is not the conceptual “owner” of + the capability and does not know how to deal with a failure to protect it. + You should always call this code in your template if you believe a reply + capability could be present and the operation you are about to perform has a + chance of deleting it.

+
+ +

seL4_Error camkes_unprotect_reply_cap(void) (#include <camkes/tls.h>)

+ +
+

Discard any information relating to a current pending reply capability. This + is designed to be called by the original declarer of a reply capability when + it is about to use (or discard) that capability. Note that this returns a + potential error that was encountered when some intermediate code tried to + protect the capability and it failed. The return value is essentially a + result from seL4_CNode_SaveCaller. This should only be called when you + know the reply cap you need is no longer in your TCB. That is, you should + check the reply_cap_in_tcb member of the CAmkES TLS structure to determine + if calling this function is necessary.

+
+ +

To get a more concrete idea of how these functions are used, you can refer to +the seL4RPCCall connector that uses this mechanism.

+ +

One final thing to note is that this functionality assumes cooperative +templates. There is nothing to prevent a malicious template omitting a call to +camkes_protect_reply_cap() and wilfully destroying pending reply +capabilities.

+ +

Template Debugging

+ +

If you are writing complicated template logic and need to debug during +instantiation, you can insert breakpoints into your template. These can be +inserted as either /*- breakpoint() -*/ or /*? breakpoint() ?*/. When +encountered during instantiation they will drop you into the Python +interpreter, from where you can explore me and other local variables.

+ +

When prototyping or debugging more complicated problems it can be helpful to +have the ability to run arbitrary Python in the template context. There is some +limited support for this, with the functions exec and eval. These operate +like the native Python exec and eval, but may be a little more fragile. +Note that exec is a function in this context, not a statement. So where you +would normally write exec 'print \'hello\'' you would write +exec('print \'hello\'').

+ +

Although never advisable in a proper implementation, it is possible to pass +arbitrary information between unrelated templates. Similar to the stash and +pop functions described above, there are lower level versions, _stash and +_pop that let you write to and read from a context that propagates across all +templates. Note that you can only use this to pass information “forwards” to +templates that are instantiated after the one you are calling _stash from.

+ +

Developers

+ +

This section is targeted at those intending to modify the CAmkES implementation +itself. The information below assumes you are familiar with the features and +functionality of CAmkES.

+ +

If you are modifying the actual sources of any of the CAmkES modules I’ve +attempted +to leave helpful comments. I’ve occasionally used tags in the comments that +may help you when grepping and whatnot. They mean:

+ +

FIXME

+ +
+

This is a stop gap piece of functionality that should be replaced + with something more feature complete when time permits. This could also refer + to an existing bug that cannot currently be easily remedied.

+
+ +

HACK

+ +
+

This code is a bit dubious, but is intentionally written this way to + work around limitations in some other tool outside our control.

+
+ +

MOVE

+ +
+

This is the wrong place for this piece of functionality. It should + be refactored somewhere else.

+
+ +

PERF

+ +
+

This code is structured in a counter-intuitive or non-obvious way for + performance reasons. Refactor if you wish, but be aware it may have a + significant impact on runtime.

+
+ +

SLOW

+ +
+

This code is known to be inefficient, but was deliberately written + this way for simplicity. If you are hitting performance problems and looking + for optimisation opportunities try grepping for this.

+
+ +

TODO

+ +
+

Some part of the functionality in this section has not yet been + implemented or the code could be improved in some way.

+
+ +

XXX

+ +
+

There is something out of the ordinary about this piece of code that + should probably be fixed. This is often in cases where I didn’t have time to + write a proper FIXME or TODO comment.

+
+ +

Parser Internals

+ +
    +
  • camkes/parser/*
    • +
+ +

The previous section, camkes.parser, describes the high-level +interface to the CAmkES parser. This parser is assembled from a pipeline of +lower-level parsers. These are each described as a “stage” in parsing. To +understand them, it is necessary to understand a few variants of Abstract +Syntax Tree representations that are referred to in the source code. The +following representations are described in order from least to most abstract:

+ +
    +
  • Augmented input This is not an AST, as such, but rather a tuple of source +data and a set of read files.
    • +
  • Raw AST This is a tree of plyplus.strees.
    • +
  • Augmented AST This is a list of plyplus.strees with attached +information about their original source data and the file they came from.
    • +
  • Lifted AST This is the most abstract programmatic representation of an +input specification and the form developers will come to be most familiar +with. It is a tree of objects from camkes.ast.
    • +
+ +

The various low-level parsers are each responsible for a specific AST +transformation, with the high-level parser stringing them all together for ease +of use. The low-level parsers are:

+ +
    +
  • Stage 0 Reads an input file and optionally runs the C pre-processor over +it. This “parser” is really just a more full featured version of the open +call.
    • +
  • Stage 1 Parses input using plyplus. Note that this is where the CAmkES +grammar (camkes/parser/camkes.g) comes into play.
    • +
  • Stage 2 Resolves import statements. This parser repeatedly calls back +into the stage 1 parser to parse further sources. Note that from here on, +import statements do not appear in the AST.
    • +
  • Stage 3 Lifts the plyplus AST into the objects of +camkes.ast. This is generally the most intensive parse phase +and inherently the most fragile as it encodes much of the semantics of the +CAmkES input language.
    • +
  • Stage 4 Resolves semantic references. From here on, no +camkes.ast.References remain in the AST.
    • +
  • Stage 5 Collapses groups. The group keyword is used to colocate +component instances into a single address space. This stage removes groups +from the AST, assigning the same address space to their contained instances.
    • +
  • Stage 6 Combines multiple assemblies. It is possible for more than one +assembly block to be specified in a CAmkES input specification, in which +case the intended assembly is the concatenation of all of them. This stage +performs that concatenation.
    • +
  • Stage 7 Flattens component hierarchies. Component instances that are +nested inside other components are hoisted to the top-level assembly by this +stage.
    • +
  • Stage 8 Resolves attribute references. Settings can be given a value that +references another attribute (using the <- operator). This stage resolves +these references to concrete values.
    • +
  • Stage 9 Freezes the AST. This stage transforms various AST internal data +structures into optimised forms and makes AST modification from this point on +impossible.
    • +
+ +

With this information, looking back at the high-level parser, one can see that +it simply chains these stages together. It is possible to programmatically +construct a differing or partial parser by composing the low-level parsers in a +different manner.

+ +

Pre-Compiled Templates

+ +
    +
  • camkes/runner/Renderer.py
    • +
+ +

The Jinja templating engine works by compiling template code to native Python +code, which it then runs to produce the generated output. This compilation to +Python code is normally performed in each execution. To speed up this process, +when caching is enabled, the templates are compiled to the cache directory. In +future executions, template rendering optimistically fetches pre-compiled +templates from this cache. On a cache miss, it falls back to the original +template sources.

+ +

Template Context

+ +

The code that renders the templates themselves is all contained under the +runner directory in the CAmkES module. While the rendering itself is driven +from Renderer.py, the more relevant file is actually Context.py. The +new_context function returns a dictionary that defines the template +environment, that is, what local variables are present in the template at +instantiation time.

+ +

There is some fairly complex functionality here aimed at providing nice +abstractions to template authors. In particular, alloc_obj, alloc_cap, +stash, pop and guard are intended to provide an abstraction for the +template author to pass variables between templates. Refer to the comments in +this file to understand more about the template context.

+ +

Extending the context can be done by adding more items to this dictionary and +there aren’t many gotchas here. If you’re doing something more complicated than +exposing an existing built-in and having difficulty you may find the +implementations of breakpoint or exec informative as examples.

+ +

Core Libraries

+ +

CAmkES has a notion of “core libraries” as the set of seL4 libraries that may +be relied on to be available from within the template context. These are +defined within the camkes-gen.cmake template. This set of libraries has been extended on demand to cover all +base seL4 infrastructure. This can be freely expanded to cover more libraries +with no expected surprises.

+ +

Be aware that these libraries will be unconditionally depended upon and linked +into all CAmkES components. That is, the user’s lists of libraries defined in +their application CMakeLists.txt will all be silently extended to include the core +libraries.

+ +

Testing

+ +

CAmkES has a set of unit tests and a set of integration tests. The unit tests +are structured per-module, with each module’s tests in a subdirectory of its +source:

+ +
    +
  • camkes/ast/tests
    • +
  • camkes/internal/tests
    • +
  • camkes/parser/tests
    • +
  • camkes/runner/tests
    • +
  • camkes/templates/tests
    • +
+ +

The unit tests use Python’s +unittest framework. The +simplest way to execute them is from the top-level wrapper script:

+ +
./alltests.py
+
+ +

Alternatively, any finer granularity of test cases may be selected:

+ +
# Run all AST unit tests
+./camkes/ast/tests/runall.py
+
+# Run only AST hashing assumption tests
+./camkes/ast/tests/runall.py TestHashingAssumptions
+
+# Run only the specific test for hashing None
+./camkes/ast/tests/runall.py TestHashingAssumptions.test_none
+
+ +

The integration tests are contained in the CAmkES project repository under the +directory tests/. Again, the simplest way to execute these is with a wrapper +script:

+ +
./tests/run-all.py
+
+ +

Alternatively, you can run individual integration tests:

+ +
# Test simple RPC
+./tests/arm-simple.tcl
+
+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/camkes/manual.md b/projects/camkes/manual.md deleted file mode 100644 index a09b9dbc97f..00000000000 --- a/projects/camkes/manual.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -toc: true -repo: seL4/camkes-tool -include_file: docs/index.md -redirect_from: - - /CAmkES/Terminology - - /projects/camkes/terminology.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# CAmkES Manual - -{% include include_github_repo_markdown.md %} diff --git a/projects/camkes/next.html b/projects/camkes/next.html new file mode 100644 index 00000000000..ed2f796897a --- /dev/null +++ b/projects/camkes/next.html @@ -0,0 +1,652 @@ + + + + + + + CAmkES Next | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

CAmkES Next

+ +

CAmkES Next refers to the next branch of camkes-tools. It is the +active development branch of camkes.

+ +
+
+ + Note +
+
+ +

This branch was used before the release of CAmkES 3. The current development +branch is master and contains all previous work from the next branch. The +latest release is camkes-3.11.1.

+ +
+
+ +

Github: https://github.com/seL4/camkes-tool/tree/next

+ +

Main CAmkES page: CAmkES

+ +

Summary of differences between CAmkES next and CAmkES master: +differences

+ +

Setting up your machine

+ +

The following commands were tested on a fresh installation of Ubuntu +16.04. This will install the tools and libraries required to build seL4 +and CAmkES Next. Note that the dependencies are different from those of +the “master” branch of CAmkES.

+
apt-get install git repo libncurses-dev python-pip libxml2-utils cmake ninja-build clang libssl-dev libsqlite3-dev \
+libcunit1-dev gcc-multilib expect qemu-system-x86 qemu-system-arm gcc-arm-none-eabi binutils-arm-none-eabi
+
+pip install six plyplus pyelftools orderedset jinja2
+
+curl -sSL https://get.haskellstack.org/ | sh
+
+ +

If you are using Ubuntu 14.04, then you will need to install some extra +packages and update your compiler. Instead of the above do the following +(the main changes are: replace repo with phablet-tools, add python-dev, +and install gcc-5 and gcc-5-multilib from the PPA and set it as the +default gcc):

+
add-apt-repository ppa:ubuntu-toolchain-r/test
+apt-get update
+apt-get install git phablet-tools libncurses-dev python-dev python-pip libxml2-utils cmake ninja-build clang libssl-dev \
+libsqlite3-dev libcunit1-dev gcc-multilib expect qemu-system-x86 qemu-system-arm gcc-arm-none-eabi binutils-arm-none-eabi \
+gcc-5 gcc-5-multilib
+update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-5 60
+
+pip install camkes-deps
+
+curl -sSL https://get.haskellstack.org/ | sh
+
+ +

On Archlinux:

+
pacman -S binutils gcc-multilib arm-none-eabi-binutils arm-none-eabi-gcc ccache clang moreutils cpio python python-pip expect \
+cmake ninja m4 automake autoconf pkg-config valgrind cppcheck python-pylint qemu qemu-arch-extra openssl bcunit
+
+yaourt -S bcunit-cunit-compat spin
+
+pip install camkes-deps
+
+curl -sSL https://get.haskellstack.org/ | sh
+
+ +

If you are using Debian, or Ubuntu 16.10 or higher, you’ll need to +modify the compiler/linker flags for building ghc. Modify +~/.stack/programs/x86_64-linux/ghc-8.0.1/lib/ghc-8.0.1/settings. +Replace the lines:

+
 ("C compiler flags", " -fno-stack-protector"),
+ ("C compiler link flags", ""),
+
+

with

+
 ("C compiler flags", " -fno-PIE  -fPIC -fno-stack-protector"),
+ ("C compiler link flags", "-no-pie -fPIC"),
+
+ +

See this stack issue on GitHub for more information.

+ +

Download and build example CAmkES app

+ +

Create and enter an empty working directory before running the commands +below.

+
# Download CAmkES, seL4, user libraries and example apps
+repo init -u https://github.com/seL4/camkes-manifest.git -m next.xml
+repo sync
+
+# Select an app to build (build configs for example apps can be found in the "configs" directory)
+make arm_simple_defconfig
+
+# Compile it
+make
+
+# Run the app in qemu
+qemu-system-arm -M kzm -nographic -kernel images/capdl-loader-experimental-image-arm-imx31
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/next.md b/projects/camkes/next.md deleted file mode 100644 index 175f74705f3..00000000000 --- a/projects/camkes/next.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -redirect_from: - - /CAmkESNext -archive: true -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# CAmkES Next - -CAmkES Next refers to the `next` branch of camkes-tools. It is the -active development branch of camkes. - -{% include note.html %} -This branch was used before the release of CAmkES 3. The current development -branch is `master` and contains all previous work from the `next` branch. The -latest release is {{site.camkes}}. -{% include endnote.html %} - -Github: - -Main CAmkES page: [CAmkES](./) - -Summary of differences between CAmkES next and CAmkES master: -[differences](differences.html) - -## Setting up your machine - - -The following commands were tested on a fresh installation of Ubuntu -16.04. This will install the tools and libraries required to build seL4 -and CAmkES Next. Note that the dependencies are different from those of -the "master" branch of CAmkES. -``` -apt-get install git repo libncurses-dev python-pip libxml2-utils cmake ninja-build clang libssl-dev libsqlite3-dev \ -libcunit1-dev gcc-multilib expect qemu-system-x86 qemu-system-arm gcc-arm-none-eabi binutils-arm-none-eabi - -pip install six plyplus pyelftools orderedset jinja2 - -curl -sSL https://get.haskellstack.org/ | sh -``` - -If you are using Ubuntu 14.04, then you will need to install some extra -packages and update your compiler. Instead of the above do the following -(the main changes are: replace repo with phablet-tools, add python-dev, -and install gcc-5 and gcc-5-multilib from the PPA and set it as the -default gcc): -``` -add-apt-repository ppa:ubuntu-toolchain-r/test -apt-get update -apt-get install git phablet-tools libncurses-dev python-dev python-pip libxml2-utils cmake ninja-build clang libssl-dev \ -libsqlite3-dev libcunit1-dev gcc-multilib expect qemu-system-x86 qemu-system-arm gcc-arm-none-eabi binutils-arm-none-eabi \ -gcc-5 gcc-5-multilib -update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-5 60 - -pip install camkes-deps - -curl -sSL https://get.haskellstack.org/ | sh -``` - -On Archlinux: -``` -pacman -S binutils gcc-multilib arm-none-eabi-binutils arm-none-eabi-gcc ccache clang moreutils cpio python python-pip expect \ -cmake ninja m4 automake autoconf pkg-config valgrind cppcheck python-pylint qemu qemu-arch-extra openssl bcunit - -yaourt -S bcunit-cunit-compat spin - -pip install camkes-deps - -curl -sSL https://get.haskellstack.org/ | sh -``` - -If you are using Debian, or Ubuntu 16.10 or higher, you'll need to -modify the compiler/linker flags for building ghc. Modify -`~/.stack/programs/x86_64-linux/ghc-8.0.1/lib/ghc-8.0.1/settings`. -Replace the lines: -``` - ("C compiler flags", " -fno-stack-protector"), - ("C compiler link flags", ""), -``` -with -``` - ("C compiler flags", " -fno-PIE -fPIC -fno-stack-protector"), - ("C compiler link flags", "-no-pie -fPIC"), -``` - -See [this stack issue on GitHub](https://github.com/commercialhaskell/stack/issues/2712) for more information. - -## Download and build example CAmkES app - - -Create and enter an empty working directory before running the commands -below. -```bash -# Download CAmkES, seL4, user libraries and example apps -repo init -u https://github.com/seL4/camkes-manifest.git -m next.xml -repo sync - -# Select an app to build (build configs for example apps can be found in the "configs" directory) -make arm_simple_defconfig - -# Compile it -make - -# Run the app in qemu -qemu-system-arm -M kzm -nographic -kernel images/capdl-loader-experimental-image-arm-imx31 -``` diff --git a/projects/camkes/releases.md b/projects/camkes/releases.md deleted file mode 100644 index 88b6eb07792..00000000000 --- a/projects/camkes/releases.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -permalink: /releases/camkes.html -redirect_from: - - /camkes_release -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# CAmkES releases - -{% assign coll = site['releases'] | where: "project", "camkes" %} -{% comment %} -Sort sorts by string sorting so a version of 2.3.0 is higher than 10.0.0. -Because of this we need to split the list into two before sorting. -{% endcomment %} -{% assign releases_1 = coll | where_exp:"item", "item.version_digits != 2" | sort: "version" %} -{% assign releases_2 = coll | where_exp:"item", "item.version_digits == 2" | sort: "version" %} -{% assign releases = releases_1 | concat: releases_2 %} - -{% for release in releases reversed %} -{%- assign seL4_link = '[' | append: release.seL4 | append: '](' | - append: '/releases/sel4/' | append: release.seL4 | - append: '.html)' %} -- Release [{{ release.title }}]({{ release.url | relative_url }}), for seL4 {{seL4_link}} {% if forloop.first %}(latest){% endif %} -{% endfor %} diff --git a/projects/camkes/seL4SharedDataWithCaps.html b/projects/camkes/seL4SharedDataWithCaps.html new file mode 100644 index 00000000000..7439d52c7d0 --- /dev/null +++ b/projects/camkes/seL4SharedDataWithCaps.html @@ -0,0 +1,585 @@ + + + + + + + seL4SharedDataWithCaps | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

seL4SharedDataWithCaps

+ +

seL4SharedDataWithCaps is a CAmkES connector for connecting dataport +interfaces, where one side of the interface has caps to the frames +backing the dataport. This is different from the common dataport +connector seL4SharedData, in which neither side has caps to the frames. +seL4SharedData is used in the CAmkES VM to implement Cross VM Dataports, +which require the VMM to map memory backing a dataport into the VM’s +address space - an operation which requires caps to the frames.

+ +

The templates and connector definition for seL4SharedDataWithCaps is in +global-components.

+ +

For an example of this connector in action, see the +CAmkES VM.

+ +

Usage

+ +

Connect a pair of dataport interfaces, as with seL4SharedData. The to +component instance on the side of the connection will have caps to the +dataport frames in its cspace. The connector implements the following +interface, which provides access to the caps mapping the dataport: +dataport_caps.h.

+ +

The interface on the to side of each seL4SharedDataWithCaps connection +must be configured with a unique id and size:

+
<instance>.<interface>_id = <unique integer >= 1>;
+<instance>.<interface>_size = <integer size>;
+
+ +

Specifying a non-unique or non-positive id is an error. Specifying a +size other than the size of the type of the dataport is an error. +Omitting this configuration for an interface connected with +seL4SharedDataWithCaps is an error.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/seL4SharedDataWithCaps.md b/projects/camkes/seL4SharedDataWithCaps.md deleted file mode 100644 index 0a036e0c49d..00000000000 --- a/projects/camkes/seL4SharedDataWithCaps.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -archive: true -parent: /projects/camkes/ -redirect_from: - - /seL4SharedDataWithCaps -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4SharedDataWithCaps - - -`seL4SharedDataWithCaps` is a CAmkES connector for connecting dataport -interfaces, where one side of the interface has caps to the frames -backing the dataport. This is different from the common dataport -connector `seL4SharedData`, in which neither side has caps to the frames. -`seL4SharedData` is used in the CAmkES VM to implement Cross VM Dataports, -which require the VMM to map memory backing a dataport into the VM's -address space - an operation which requires caps to the frames. - -The templates and connector definition for `seL4SharedDataWithCaps` is in -[global-components](https://github.com/seL4/global-components). - -For an example of this connector in action, see the -[CAmkES VM](https://github.com/seL4/camkes-vm-examples/blob/master/apps/x86/optiplex9020/optiplex9020.camkes#L46). - -### Usage - - -Connect a pair of dataport interfaces, as with `seL4SharedData`. The `to` -component instance on the side of the connection will have caps to the -dataport frames in its cspace. The connector implements the following -interface, which provides access to the caps mapping the dataport: -[dataport_caps.h](https://github.com/seL4/camkes-vm/blob/3883770209ba2bfb4f85ed2b7d387731e2601b7d/common/include/dataport_caps.h). - -The interface on the `to` side of each `seL4SharedDataWithCaps` connection -must be configured with a unique id and size: -``` -._id = = 1>; -._size = ; -``` - -Specifying a non-unique or non-positive id is an error. Specifying a -size other than the size of the type of the dataport is an error. -Omitting this configuration for an interface connected with -`seL4SharedDataWithCaps` is an error. diff --git a/projects/camkes/setting-up.html b/projects/camkes/setting-up.html new file mode 100644 index 00000000000..6009cd46000 --- /dev/null +++ b/projects/camkes/setting-up.html @@ -0,0 +1,817 @@ + + + + + + + Setting up your machine to use CAmkES | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Setting up your machine to use CAmkES

+ +

This page describes how to set up your development host machine for building and +using the CAmkES component system on top of seL4. The first steps are the build +dependencies for the seL4 kernel. You will need these, including Google’s repo +tool. The steps are repeated below for convenience. In addition, projects using +CAmkES need Haskell and some extra Python libraries. Instructions for these +are underneath.

+ +

Get Google’s Repo tool

+ +

The primary way of obtaining and managing seL4 project sources is through +Google’s repo tool. To start with, get repo by following the +instructions in the section “Install” on the repo +site.

+ +

See the repo cheatsheet page for a quick explanation of how we use repo.

+ +

Docker or native

+ +

To compile and use seL4 you can either:

+ +
    +
  • Recommended: follow the instructions here to use Docker for +isolating the dependencies from your machine, or
    • +
  • install the build dependencies below on your local OS
    • +
+ +

The following instructions describe how to set up the required dependencies on +your local OS. This page assumes you are building in a Linux OS. We however +encourage site contributions for build instructions in other OSes (e.g. +macOS).

+ +

Ubuntu

+ +

These instructions are intended for Ubuntu LTS versions 20.04 and 22.04.

+ +
+
+ + Note +
+
+ +

If you discover any missing dependencies and packages we welcome new +contributions to the page. You can edit this section directly on GitHub.

+ +
+
+ +

Base dependencies

+ +

The basic build package on Ubuntu is the build-essential package. To install run:

+ +
sudo apt-get update
+sudo apt-get install build-essential
+
+ +

Additional base dependencies for building seL4 projects on Ubuntu include installing:

+ +
sudo apt-get install cmake ccache ninja-build cmake-curses-gui
+sudo apt-get install libxml2-utils ncurses-dev
+sudo apt-get install curl git doxygen device-tree-compiler xxd
+sudo apt-get install u-boot-tools
+sudo apt-get install python3-dev python3-pip python-is-python3
+sudo apt-get install protobuf-compiler python3-protobuf
+
+ +

Simulating with QEMU

+ +

In order to run seL4 projects on a simulator you will need QEMU:

+ +
sudo apt-get install qemu-system-arm qemu-system-x86 qemu-system-misc
+
+ +

Cross-compiling for ARM targets

+ +

To build for ARM targets you will need a cross compiler:

+ +
sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
+sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
+
+ +

(you can install the hardware floating point versions as well if you wish)

+ +
sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
+
+ +

Cross-compiling for RISC-V targets

+ +

To build for RISC-V targets you will need a cross compiler:

+ +

It is recommended to build the toolchain from source.

+ +
git clone https://github.com/riscv/riscv-gnu-toolchain.git
+cd riscv-gnu-toolchain
+git submodule update --init --recursive
+export RISCV=/opt/riscv
+./configure --prefix="${RISCV}" --enable-multilib
+make linux
+
+ +

After it is built, add the $RISCV/bin folder to your PATH. The built +toolchain works for both 32-bit and 64-bit.

+ +

Alternatively, any pre-built toolchain with multilib enabled should work.

+ +

Building the seL4 manual

+ +

If you would like to build the seL4 manual, you will need the following LaTeX pacakges:

+ +
sudo apt-get install texlive texlive-latex-extra texlive-fonts-extra
+
+ +

Debian

+ +

The dependencies listed in our Docker files +repository will work for +a Debian Bullseye, most likely also for later releases. You can refer to this repository +for an up-to-date list of base build dependencies. Specifically refer to the +dependencies listed in the file here:

+ + + +

Python

+ +

A number of Python packages are required to build seL4 and its manual. To install these you can run:

+ +
pip3 install --user setuptools sel4-deps
+
+ +

(Some distributions use pip for python3, others use pip3. Use the Python 3 version for your distribution)

+ +
+ Error: Python environment is externally managed +
+ +

Some Linux distributions have changed how Python is managed. If you get an error +saying the Python ‘environment is externally managed’ follow the instructions +below. The first two steps are needed only once for setup.

+ + 
python3 -m venv seL4-venv
+./seL4-venv/bin/pip install sel4-deps
+
+ +

The following step is needed every time you start using the build environment +in a new shell.

+ + 
source ./seL4-venv/bin/activate
+
+ +

It is not important where the seL4-venv directory is located.

+
+
+ +

CAmkES Build Dependencies

+ +

More Python

+ +

The Python dependencies required by the CAmkES build toolchain can be installed via pip:

+ +
pip3 install --user camkes-deps
+
+ +
+ Error: Python environment is externally managed +
+ +

Some Linux distributions have changed how Python is managed. If you get an error +saying the Python ‘environment is externally managed’ follow the instructions +below. The first two steps are needed only once for setup.

+ + 
python3 -m venv seL4-venv
+./seL4-venv/bin/pip install camkes-deps
+
+ +

The following step is needed every time you start using the build environment +in a new shell.

+ + 
source ./seL4-venv/bin/activate
+
+ +

It is not important where the seL4-venv directory is located.

+
+
+ +

Haskell Dependencies

+ +

The CAmkES build toolchain additionally requires Haskell. You can install the +Haskell stack on your distribution by running:

+ +
curl -sSL https://get.haskellstack.org/ | sh
+
+ +

If you prefer not to bypass your distribution’s package manager, you can do

+ +
sudo apt-get install haskell-stack
+
+ +

Build Dependencies

+ +
+
+ + + + + + + + + + + +
+ +

CAmkES repository collection checkout

+ +

To check out a consistent collection of CAmkEs, tools, libraries, and kernel +from the camkes-manifest repository, run the following:

+ +
mkdir camkes-project
+cd camkes-project
+repo init -u https://github.com/seL4/camkes-manifest.git
+repo sync
+
+ +

To run a simple demo example:

+ +
cd camkes-project
+mkdir build
+cd build
+../init-build.sh -DPLATFORM=sabre -DAARCH32=1 -DCAMKES_APP=adder -DSIMULATION=1
+ninja
+./simulate
+
+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/setting-up.md b/projects/camkes/setting-up.md deleted file mode 100644 index e861a067910..00000000000 --- a/projects/camkes/setting-up.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Setting up your machine to use CAmkES - -This page describes how to set up your development host machine for building and -using the CAmkES component system on top of seL4. The first steps are the build -dependencies for the seL4 kernel. You will need these, including Google's repo -tool. The steps are repeated below for convenience. In addition, projects using -CAmkES need Haskell and some extra Python libraries. Instructions for these -are underneath. - -{% include seL4-deps.md %} - - -## CAmkES Build Dependencies - -### More Python - -The Python dependencies required by the CAmkES build toolchain can be installed via pip: - -```sh -pip3 install --user camkes-deps -``` - -{% include pip-instructions.md %} - -### Haskell Dependencies - -The CAmkES build toolchain additionally requires Haskell. You can install the -[Haskell stack](https://haskellstack.org) on your distribution by running: - -```sh -curl -sSL https://get.haskellstack.org/ | sh -``` - -If you prefer not to bypass your distribution's package manager, you can do - -```sh -sudo apt-get install haskell-stack -``` - -### Build Dependencies - -{% include tabs.html %} - -{% include tab.html title="Ubuntu" %} - -These instructions are intended for Ubuntu LTS version 22.04. - -Install the following packages: - -```sh -sudo apt-get install clang gdb -sudo apt-get install libssl-dev libclang-dev libcunit1-dev libsqlite3-dev -sudo apt-get install qemu-kvm -``` - -{% include endtab.html %} - -{% include tab.html title="Debian" %} - -The dependencies listed in our docker files -[repository](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles) will work for -a Debian Bullseye installation or later. You can refer to this repository for an -up-to-date list of base build dependencies. Specifically refer to the -dependencies listed in the [CAmkES -docker setup](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles/blob/master/scripts/camkes.sh). - -{% include endtab.html %} - -{% include endtabs.html %} - - -### CAmkES repository collection checkout - -To check out a consistent collection of CAmkEs, tools, libraries, and kernel -from the `camkes-manifest` repository, run the following: - -```sh -mkdir camkes-project -cd camkes-project -repo init -u https://github.com/seL4/camkes-manifest.git -repo sync -``` - -To run a simple demo example: - -```sh -cd camkes-project -mkdir build -cd build -../init-build.sh -DPLATFORM=sabre -DAARCH32=1 -DCAMKES_APP=adder -DSIMULATION=1 -ninja -./simulate -``` diff --git a/projects/camkes/status.html b/projects/camkes/status.html new file mode 100644 index 00000000000..29bd2a2d0d8 --- /dev/null +++ b/projects/camkes/status.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/camkes/terminology.html b/projects/camkes/terminology.html new file mode 100644 index 00000000000..eb437e0aa76 --- /dev/null +++ b/projects/camkes/terminology.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/camkes/visual-camkes/index.html b/projects/camkes/visual-camkes/index.html new file mode 100644 index 00000000000..d45eecaa012 --- /dev/null +++ b/projects/camkes/visual-camkes/index.html @@ -0,0 +1,808 @@ + + + + + + + VisualCAmkES | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

VisualCAmkES

+ +

VisualCAmkES, also known as Visualisation of CAmkES, is a tool that allows one +to visually understand a CAmkES system, how it works and how the different +components are connected together. This makes understanding easier and more +intuitive than traversing CAmkES code. An example of a graph generated by this +tool is shown below

+ +

Example Output from VisualCAmkES

+ +

Currently this program loads in a top-level camkes file and generates a graph +from it. It also lets the user interact with the graph (zoom, pan and move +nodes). The tool is a foundation for a CAmkES IDE. To create a CAmkES IDE, one + must first be able to display a current CAmkES system and allow interaction. +And that is what this project does. Since it was clear that this project should +become an IDE in the future, the code has been written with that in mind.

+ +

The tool is written in python, for two reason. Python provides cross-platform +compatibility, which doesn’t require heavy, insecure Java virtual machine. The +tool uses the CAmkES Ast and Parser API, and since this was written in python, +this tool was also written in python.

+ +

How to Install

+ +

Follow the setup instructions for CAmkES to obtain a +repository collection checkout. The tool should is found in +projects/camkes-tool/camkes/visualCAmkES/.

+ +

Running the tool requires a few added dependencies: Graphviz and Qt. Qt is a +framework, which includes GUI, Network, Concurrency and other things. This +installation procedure assumes you have the rest of CAmkES working.

+ +

Installing Qt

+ +

For Debian/Ubuntu users, there are two ways to install this. The easy way is to +apt-get the items. The “long” way is to build from source. For Mac, use homebrew.

+ +

Qt is quite big, and the majority of it is unnecessary for VisualCAmkES. So we +recommend to build from source for personal computers.

+ +

From apt-get

+ +
sudo apt-get install python-pyqt5
+sudo apt-get install python-pyqt5.qtsvg
+
+ +

From source

+ +
cd /some/temp/directory/like/Downloads
+git clone https://github.com/qt/qt5.git
+cd qt5
+git checkout 5.5
+./init-repository --no-webkit --module-subset=qtbase,qtsvg
+
+# Check where Qt will install - needed for PyQt5
+./configure --help
+# Have a look at where qt will be installed, for me it was installed in /usr/local/Qt-5.5.1
+
+./configure -release -nomake examples -nomake tests -opensource -confirm-license # add "-qt-xcb" for linux
+
+make -j4 # This takes a long time (1-3 hrs)
+make install
+
+ +

Installing Graphviz

+ +

For Linux:

+ +
sudo apt-get install graphviz
+sudo pip install graphviz
+sudo pip install pydotplus
+
+ +

For Mac:

+ +
brew install graphviz
+
+ +

Installing other dependencies

+ +
sudo pip install ansi2html
+
+ +

How to use

+ +

This program is easy to use, yet quite powerful. To start the application, from +the root of the repository collection checkout, run:

+ +
python projects/camkes-tool/camkes/visualCAmkES/visualCAmkES
+
+ +

Opening a File

+ +

To open a file, click File->Open. Then select a top-level +camkes file. Your graph will load.

+ +

Manipulating the graph

+ +

In the right, you have a few buttons:

+ +

VisualCAmkES Corner UI buttons

+ +

The button’s name should be self-explanatory. Autolayout will use graphviz to +reposition the nodes into a “nice” format. In my experience, graphviz never +gives a nice layout, but it does give a good starting point for you.

+ +

You can move the instances around by click & dragging each box. The +connections will continually redraw as you move the box. There is a +minimum distance to see the symbol for each connection.

+ +

Exporting and Saving

+ +

As you change the graph, the program automatically saves a .layout file, +which contains the current +position of each box. This means that you can close the python +application, and when you reopen it, your latest layout will appear.

+ +

You can export an image, into either PNG or SVG.

+ +
    +
  1. Clicking Save Image or File->Export Image.
    2. +
  2. Choose either PNG or SVG from the combo-box (first input). + a. For PNG, resolutions is mandatory. + b. For SVG, no input is mandatory.
    3. +
  3. Click OK.
    4. +
  4. Choose a place to save your file, and name your picture.
    5. +
+ +

Import Paths

+ +

In some cases, users may have external import paths which is usually a +parameter to the camkes parser. In order to visualise these camkes +projects, the user can add import paths by doing the following:

+ +
    +
  1. +

    Click Edit -> Add import paths

    +
    2. +
  2. +

    In the dialog box, type (or paste) your import paths. These need to be +absolute paths. To add many paths, have spaces between your paths. + - /home/someUser/camkes-next/projects/FileExtender /home/someUser/camkes-next/projects/common

    +
    3. +
+ +

A keyboard shortcut is also implemented, Cmd + I or Cmd + I .

+ +

Key-mappings

+ +

The key-mappings are as follows:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskLinux/WindowsMac
OpenCtrl + OCmd + O
AutolayoutCtrl + LCmd + L
Export (Save) ImageCtrl + ECmd + E
Zoom InCtrl + =Cmd + =
Zoom OutCtrl + -Cmd + -
Add Import PathsCtrl + ICmd + I
+ +

How it works

+ +

High-level overview

+ +

UML Diagram of VisualCAmkES

+ +

The above is quick UML class diagram. A few other classes isn’t shown like +SaveOptionDialog - but these are helper classes.

+ +

The program is written in object-oriented style, Model-View-Controller +(MVC) paradigm. If you don’t know what MVC is, its pretty much: Model +represents the data, the backend; View represents the front-end, what +the user sees; Controller keeps the Model and View in sync. Qt works on +a Model-View paradigm, which is very similar - except the Controller and +View are the same thing.

+ +
    +
  1. GraphController is the QMainWindow - and starts of the program. It +takes the chosen file from the user, gets an AST presentation from +the ASTModel, and passes it on to the GraphWidget (the view).
    2. +
  2. GraphWidget will traverse the AST, creating InstanceWidget for +Instances and ConnectionWidget for Connections.
    3. +
  3. GraphWidget is a QGraphicsView - containing QGraphicsScene. +InstanceWidget and ConnectionWidget are QGraphicWidget and +QGraphicItem respectively. QGraphicScene handles the placements of +QGraphicItems, and has functions for scaling (i.e. zoom), panning, +moving of nodes etc.
    4. +
  4. The program primary works by events. Events are like mouse clicks, +button presses etc.
    5. +
+ +

Throughout my code, I use lazy instantiation. Most (if not all) global +variables are declared as properties. Lazy instantiation is when +properties are created only when they are first called. Lazy +instantiation is done because subclasses might have different +expectation of properties’s class.

+ +

The getters and settings may trigger other events such as updating the +screen. Furthermore - it seems that when a property is passed down the +different classes, say from GraphWidget to ConnectionWidget, the getter +from GraphWidget is invoked. Hence, events can be triggered in +GraphWidget when ConnectionWidget access the properties.

+ +

Layout

+ +

In order to save the layout information - the program saves a +.visualCAmkES.layout file. It starts with a . because it is purposefully hidden +(which won’t work on windows …). This file is a json file containing +dictionaries. The key is the instance name, the value is another dictionary. The +latter dictionary contains the position and whether it was hidden. Feel free to +view the .layout file, but changing it can risk losing the layout.

+ +

Additional implementation details

+ +
    +
  • When connection widgets are deleted, ConnectionWidget.delete() + must be called on the object. This is because connection widget + is tracked by the from and to instance widgets, so it needs to + delete itself from them.
    • +
  • Context menu is a bit weirdly implemented. This is what I mean + by weird: normally you would just create the menu and it all + works - including closing of the menu. However this doesn’t work + with QGraphicScenes. So the solution is to add the context menu + to the scene, and manually close it if the mouse was clicked + anywhere outside the context menu.
    • +
+ +

Traversing the code using PyCharm IDE is highly recommended.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/camkes/visual-camkes/index.md b/projects/camkes/visual-camkes/index.md deleted file mode 100644 index a0b7339df07..00000000000 --- a/projects/camkes/visual-camkes/index.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -parent: /projects/camkes/ -redirect_from: - - /VisualCAmkES/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# VisualCAmkES - -VisualCAmkES, also known as Visualisation of CAmkES, is a tool that allows one -to visually understand a CAmkES system, how it works and how the different -components are connected together. This makes understanding easier and more -intuitive than traversing CAmkES code. An example of a graph generated by this -tool is shown below - -Example Output from VisualCAmkES - -Currently this program loads in a top-level camkes file and generates a graph -from it. It also lets the user interact with the graph (zoom, pan and move -nodes). The tool is a foundation for a CAmkES IDE. To create a CAmkES IDE, one - must first be able to display a current CAmkES system and allow interaction. -And that is what this project does. Since it was clear that this project should -become an IDE in the future, the code has been written with that in mind. - -The tool is written in python, for two reason. Python provides cross-platform -compatibility, which doesn’t require heavy, insecure Java virtual machine. The -tool uses the CAmkES Ast and Parser API, and since this was written in python, -this tool was also written in python. - -## How to Install - -Follow the [setup instructions for CAmkES](../setting-up.md) to obtain a -repository collection checkout. The tool should is found in -`projects/camkes-tool/camkes/visualCAmkES/`. - -Running the tool requires a few added dependencies: Graphviz and Qt. Qt is a -framework, which includes GUI, Network, Concurrency and other things. This -installation procedure assumes you have the rest of CAmkES working. - -### Installing Qt - -For Debian/Ubuntu users, there are two ways to install this. The easy way is to -apt-get the items. The "long" way is to build from source. For Mac, use homebrew. - -Qt is quite big, and the majority of it is unnecessary for VisualCAmkES. So we -recommend to build from source for personal computers. - -#### From apt-get - -```bash -sudo apt-get install python-pyqt5 -sudo apt-get install python-pyqt5.qtsvg -``` - -#### From source - -```bash -cd /some/temp/directory/like/Downloads -git clone https://github.com/qt/qt5.git -cd qt5 -git checkout 5.5 -./init-repository --no-webkit --module-subset=qtbase,qtsvg - -# Check where Qt will install - needed for PyQt5 -./configure --help -# Have a look at where qt will be installed, for me it was installed in /usr/local/Qt-5.5.1 - -./configure -release -nomake examples -nomake tests -opensource -confirm-license # add "-qt-xcb" for linux - -make -j4 # This takes a long time (1-3 hrs) -make install -``` - -### Installing Graphviz - -For Linux: - -```bash -sudo apt-get install graphviz -sudo pip install graphviz -sudo pip install pydotplus -``` - -For Mac: - -```bash -brew install graphviz -``` - -### Installing other dependencies - -```bash -sudo pip install ansi2html -``` - -## How to use - -This program is easy to use, yet quite powerful. To start the application, from -the root of the repository collection checkout, run: - -```bash -python projects/camkes-tool/camkes/visualCAmkES/visualCAmkES -``` - -### Opening a File - -To open a file, click File->Open. Then select a **top-level -camkes file**. Your graph will load. - -### Manipulating the graph - -In the right, you have a few buttons: - -VisualCAmkES Corner UI buttons - -The button's name should be self-explanatory. Autolayout will use graphviz to -reposition the nodes into a "nice" format. In my experience, graphviz never -gives a nice layout, but it does give a good starting point for you. - -You can move the instances around by click & dragging each box. The -connections will continually redraw as you move the box. There is a -minimum distance to see the symbol for each connection. - -### Exporting and Saving - -As you change the graph, **the program automatically saves a .layout file**, -which contains the current -position of each box. This means that you can close the python -application, and when you reopen it, your latest layout will appear. - -You can export an image, into either PNG or SVG. - -1. Clicking Save Image or File->Export Image. -2. Choose either PNG or SVG from the combo-box (first input). - a. For PNG, resolutions is mandatory. - b. For SVG, no input is mandatory. -3. Click OK. -4. Choose a place to save your file, and name your picture. - -### Import Paths - -In some cases, users may have external import paths which is usually a -parameter to the camkes parser. In order to visualise these camkes -projects, the user can add import paths by doing the following: - - 1. Click Edit -> Add import paths - - 2. In the dialog box, type (or paste) your import paths. These need to be - absolute paths. To add many paths, have spaces between your paths. - - `/home/someUser/camkes-next/projects/FileExtender /home/someUser/camkes-next/projects/common` - -A keyboard shortcut is also implemented, Cmd + I or Cmd + I . - -### Key-mappings - -The key-mappings are as follows: - -|Task |Linux/Windows|Mac | -|--------------------|-------------|-------| -|Open |Ctrl + O |Cmd + O| -|Autolayout |Ctrl + L |Cmd + L| -|Export (Save) Image |Ctrl + E |Cmd + E| -|Zoom In |Ctrl + = |Cmd + =| -|Zoom Out |Ctrl + - |Cmd + -| -|Add Import Paths |Ctrl + I |Cmd + I| - -## How it works - -### High-level overview - -UML Diagram of VisualCAmkES - -The above is quick UML class diagram. A few other classes isn't shown like -SaveOptionDialog - but these are helper classes. - -The program is written in object-oriented style, Model-View-Controller -(MVC) paradigm. If you don't know what MVC is, its pretty much: Model -represents the data, the backend; View represents the front-end, what -the user sees; Controller keeps the Model and View in sync. Qt works on -a Model-View paradigm, which is very similar - except the Controller and -View are the same thing. - - 1. GraphController is the QMainWindow - and starts of the program. It - takes the chosen file from the user, gets an AST presentation from - the ASTModel, and passes it on to the GraphWidget (the view). - 2. GraphWidget will traverse the AST, creating InstanceWidget for - Instances and ConnectionWidget for Connections. - 3. GraphWidget is a QGraphicsView - containing QGraphicsScene. - InstanceWidget and ConnectionWidget are QGraphicWidget and - QGraphicItem respectively. QGraphicScene handles the placements of - QGraphicItems, and has functions for scaling (i.e. zoom), panning, - moving of nodes etc. - 4. The program primary works by events. Events are like mouse clicks, - button presses etc. - -Throughout my code, I use lazy instantiation. Most (if not all) global -variables are declared as properties. Lazy instantiation is when -properties are created only when they are first called. Lazy -instantiation is done because subclasses might have different -expectation of properties's class. - -The getters and settings may trigger other events such as updating the -screen. Furthermore - it seems that when a property is passed down the -different classes, say from GraphWidget to ConnectionWidget, the getter -from GraphWidget is invoked. Hence, events can be triggered in -GraphWidget when ConnectionWidget access the properties. - -### Layout - -In order to save the layout information - the program saves a -.visualCAmkES.layout file. It starts with a . because it is purposefully hidden -(which won't work on windows ...). This file is a json file containing -dictionaries. The key is the instance name, the value is another dictionary. The -latter dictionary contains the position and whether it was hidden. Feel free to -view the .layout file, but changing it can risk losing the layout. - -### Additional implementation details - -- When connection widgets are deleted, ConnectionWidget.delete() - must be called on the object. This is because connection widget - is tracked by the from and to instance widgets, so it needs to - delete itself from them. -- Context menu is a bit weirdly implemented. This is what I mean - by weird: normally you would just create the menu and it all - works - including closing of the menu. However this doesn't work - with QGraphicScenes. So the solution is to add the context menu - to the scene, and manually close it if the mouse was clicked - anywhere outside the context menu. - -Traversing the code using PyCharm IDE is highly recommended. diff --git a/projects/capdl/c-loader-app.html b/projects/capdl/c-loader-app.html new file mode 100644 index 00000000000..082accc14af --- /dev/null +++ b/projects/capdl/c-loader-app.html @@ -0,0 +1,601 @@ + + + + + + + capDL Loader | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

capDL Loader

+ +

The capDL loader is a C program that is intended to run as the initial root task +in a system. It creates seL4 kernel objects and capabilities according to a +declarative capDL specification.

+ +

Formal Correctness

+ +

The capDL loader is an implementation of an algorithm that is formally specified +and proved correct (on the model level, but not the implementation level) in the +theorem prover Isabelle/HOL.

+ +

The correctness statement is that the loader will bring the system into a state +that contains only the capabilities and objects in the capDL specification in +addition to capabilities that remain inert in the loader’s capability space +after it has terminated. The input capDL specification must satisfy certain +wellformedness criteria for this theorem to hold. They are documented in the +formal definition in the verification repository.

+ +

The formal model for the capDL initialiser is documented in a research publication +by Boyton et al (2013), as well as in Boyton’s PhD thesis (2014).

+ +

The Isabelle formalisation is part of the seL4 proofs that are continually +updated and maintained in the l4v repository.

+ +

Implementation and use

+ +

The implementation of the capDL loader is comparatively small. It consists entirely +of the following three source files:

+ + + +

The capDL loader expects to be linked against an object file that contains the +input capDL specification for the symbol extern CDL_Model capdl_spec. +Typically, this would be a C file that is generated by the capDL translator +tool from a textual or XML capDL specification.

+ +

The C loader contains more features than the formal model allows in wellformed +specifications. The formal verification does not hold for these features, but +they remain usable. For instance, they can be used for debugging and prototyping +or for systems that do not require formal verification.

+ +

The capDL loader is used in CAmkES applications as the system initialisation +task, and is invoked as part of the CAmkES build in all of the CAmkES examples.

+ +

Expecting to be linked against the specification can be limiting for some build +system setups, because the specification must be compiled against the capDL loader +sources. We would welcome contributions that allow providing the specification +at runtime instead.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/capdl/c-loader-app.md b/projects/capdl/c-loader-app.md deleted file mode 100644 index 41793deaf32..00000000000 --- a/projects/capdl/c-loader-app.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -repo_link: https://github.com/seL4/capdl/blob/master/capdl-loader-app/ ---- - -# capDL Loader - -The capDL loader is a C program that is intended to run as the initial root task -in a system. It creates seL4 kernel objects and capabilities according to a -declarative [capDL specification](lang-spec.html). - - -## Formal Correctness - -The capDL loader is an implementation of an algorithm that is formally specified -and proved correct (on the model level, but not the implementation level) in the -theorem prover Isabelle/HOL. - -The correctness statement is that the loader will bring the system into a state -that contains only the capabilities and objects in the capDL specification in -addition to capabilities that remain inert in the loader's capability space -after it has terminated. The input capDL specification must satisfy certain -wellformedness criteria for this theorem to hold. They are documented in the -formal definition in the [verification repository][wellformed]. - -The formal model for the capDL initialiser is documented in a research publication -by [Boyton et al (2013)], as well as in [Boyton's PhD thesis (2014)]. - -The Isabelle formalisation is part of the seL4 proofs that are continually -updated and maintained in the [l4v repository][sys-init]. - -## Implementation and use - -The implementation of the capDL loader is comparatively small. It consists entirely -of the following three source files: - -* [`src/main.c`]({{page.repo_link}}/src/main.c): The implementation of the initialiser. -* [`include/capdl.h`]({{page.repo_link}}/include/capdl.h): C type definitions for capDL specifications. -* [`include/capdl_spec.h`]({{page.repo_link}}/include/capdl_spec.h): Interface link point for the input capDL spec. - -The capDL loader expects to be linked against an object file that contains the -input capDL specification for the symbol `extern CDL_Model capdl_spec`. -Typically, this would be a C file that is generated by the [capDL translator -tool](index.html#capdl-translator) from a textual or XML capDL specification. - -The C loader contains more features than the formal model allows in wellformed -specifications. The formal verification does not hold for these features, but -they remain usable. For instance, they can be used for debugging and prototyping -or for systems that do not require formal verification. - -The capDL loader is used in CAmkES applications as the system initialisation -task, and is invoked as part of the CAmkES build in all of the CAmkES examples. - -Expecting to be linked against the specification can be limiting for some build -system setups, because the specification must be compiled against the capDL loader -sources. We would welcome contributions that allow providing the specification -at runtime instead. - - -[wellformed]: https://github.com/seL4/l4v/blob/master/sys-init/WellFormed_SI.thy -[sys-init]: https://github.com/seL4/l4v/tree/master/sys-init - -[Boyton et al (2013)]: https://trustworthy.systems/publications/nicta_full_text/7047.pdf "Formally Verified System Initialisation" -[Boyton's PhD thesis (2014)]: https://trustworthy.systems/publications/nicta_full_text/9141.pdf "Secure architectures on a verified microkernel" diff --git a/projects/capdl/cdl-utils.html b/projects/capdl/cdl-utils.html new file mode 100644 index 00000000000..29e533e19a4 --- /dev/null +++ b/projects/capdl/cdl-utils.html @@ -0,0 +1,573 @@ + + + + + + + cdl_utils | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

cdl_utils

+ +

This directory provides a collection of utility scripts relating to capDL.

+ +

capdl_linker.py

+ +

The capdl_linker.py generates a final capDL spec from a input list of ELF files, +and a record of which resources via objects and capabilities that the ELF file +applications require. This then produces a capDL file (.cdl) that can be given +to the translator tool for translating into different formats.

+ +

untyped_gen.py

+ +

This takes a description of the memory layout in a system from a seL4 build system +artifact and generates the list of untyped objects that the kernel is expected to +create. This relies on knowledge of which policies that the kernel will use for +generating the initial untyped objects. The output of this script is typically +used for performing more exact allocation of objects in a capDL specification.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/capdl/cdl-utils.md b/projects/capdl/cdl-utils.md deleted file mode 100644 index 9005cd6ed3b..00000000000 --- a/projects/capdl/cdl-utils.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -parent: /projects/capdl/ -title: cdl_utils -repo: 'seL4/capdl' -include_file: 'cdl_utils/README.md' -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -{% include include_github_repo_markdown.md %} diff --git a/projects/capdl/index.html b/projects/capdl/index.html new file mode 100644 index 00000000000..090831611a2 --- /dev/null +++ b/projects/capdl/index.html @@ -0,0 +1,686 @@ + + + + + + + Capability Distribution Language (capDL) | seL4 docs + + + + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Capability Distribution Language (capDL)

+ +

capDL stands for capability distribution language. It is used to describe the +kernel objects an seL4 application needs and the distribution of capabilities in +the system. This defines which parts of the system have capabilities to which +other parts of the system, and therefore defines the access control boundaries +of the system for integrity and confidentiality.

+ +

capDL specifications provide a clean interface for system initialisation and +capability reasoning. Their key feature is that they describe the desired state +of the system declaratively. That means, creating such system states via seL4 +system calls is done by a separate loader application that can be formally +verified once. In addition, capability distributions in seL4 determine what +future states of the system are possible. This allows formal reasoning tools to, +directly from a capDL specification, decide questions such as +“Can component X ever gain access to resource Y in the future?”.

+ +

The next few sections give an overview of the tools and +libraries that are available and show an example capDL +specification.

+ +

Sources for the capDL tools and libraries are available here: +https://github.com/sel4/capdl

+ +

See the research paper by Kuz et al (2010) for more in-depth information on +the purpose and design of capDL.

+ +

capDL Translator

+ +

This program transforms a capDL spec into several formats:

+ +
    +
  • a C header file for linking against the capDL Loader to create a program that +instantiates the system described by the spec
    • +
  • a dot file for visualisation with graphviz
    • +
  • an XML file for further manipulation
    • +
  • an formal model in the Isabelle/HOL proof assistant for use in proofs about +the system described by the spec
    • +
+ +

The tool is written Haskell and can be used as a stand-alone binary. See the +repository README for information on +how to build and run the tool.

+ +

capDL Loader

+ +

The capDL Loader is a program that initialises the seL4 user-level environment +to match the system described by a capDL spec, and loads programs from ELFs in a +provided cpio archive. It is intended to be run as the root task, that is, the +first user-level thread, which has access to all resources.

+ +

The capDL Loader must be linked against a capDL spec - the C output of the capDL +Translator. It must also be linked against a cpio archive containing ELF images. +It creates objects and distributes caps as per the spec (if enough resources are +available), and then loads programs into memory at locations specified by the +spec. Finally, it starts all the threads it created and sleeps forever.

+ +

See also the separate capDL loader page.

+ +

Python capDL Library

+ +

This library is useful for building up a representation of a capDL state +programmatically in memory and then writing that as a specification to disk. It +allows the programmer to incrementally add information about kernel objects and +capability distribution. The library is used by CAmkES to build up a +spec describing the entire system, covering all components and connections.

+ +

See the repository README +for information on this library.

+ +

There is also a cmake target for generating object sizes and various utilities +for using capDL in build scrips available in the repository.

+ +

Example Spec

+ +

Below is an example capDL specification that describes an AArch32 system +with five kernel objects: a TCB, a CNode of size $2^3$, one 4K Frame with a +specified physical address, one page table, and one page directory. The +caps section of the spec describes the content of those objects in terms +of references (capabilities) to other objects.

+ +

The capDL translator tool can transform this specification into other formats, +for instance for consumption by the capDL loader. These specifications do not +need to be written manually, they are typically generated from other tools, for +instance with the help of the Python capDL library.

+ +

For more detail on how these specification work, see also the language +specification for capDL.

+ +
arch ia32
+
+objects {
+  my_tcb = tcb
+  my_cnode = cnode (3 bits)
+  my_frame = frame (4k, paddr: 0x12345000) // paddr is optional
+  my_page_table = pt
+  my_page_directory = pd
+}
+
+caps {
+
+  // Specify cap addresses (ie. CPtrs) in cnodes.
+  my_cnode {
+    1: my_tcb
+    2: my_frame
+    3: my_page_table
+    4: my_page_directory
+  }
+
+  // Specify address space layout.
+  // With 4gb page directories, 4mb page tables, and 4kb frames,
+  // the frame at paddr 0x12345000 will be mapped at vaddr 0xABCDE000.
+  my_pd {
+    0x2AF: my_pt
+  }
+  my_pt {
+    0xDE: my_frame
+  }
+
+  // Specify root cnode and root paging structure of thread.
+  my_tcb {
+    vspace: my_pd
+    cspace: my_cnode
+  }
+
+}
+
+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/capdl/index.md b/projects/capdl/index.md deleted file mode 100644 index 7ce8a0c81db..00000000000 --- a/projects/capdl/index.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -redirect_from: - - /CapDL - -project: capdl -repo_link: https://github.com/sel4/capdl/blob/master -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -mathjax: true ---- - -# Capability Distribution Language (capDL) - -capDL stands for *capability distribution language*. It is used to describe the -kernel objects an seL4 application needs and the distribution of capabilities in -the system. This defines which parts of the system have capabilities to which -other parts of the system, and therefore defines the access control boundaries -of the system for integrity and confidentiality. - -capDL specifications provide a clean interface for system initialisation and -capability reasoning. Their key feature is that they describe the desired state -of the system declaratively. That means, creating such system states via seL4 -system calls is done by a separate loader application that can be formally -verified once. In addition, capability distributions in seL4 determine what -future states of the system are possible. This allows formal reasoning tools to, -directly from a capDL specification, decide questions such as -*"Can component X ever gain access to resource Y in the future?"*. - -The next few sections give an overview of the [tools and -libraries](#capdl-translator) that are available and show an [example capDL -specification](#example-spec). - -Sources for the capDL tools and libraries are available here: - - -See the research paper by [Kuz et al (2010)] for more in-depth information on -the purpose and design of capDL. - -## capDL Translator - -This program transforms a capDL spec into several formats: - -- a C header file for linking against the capDL Loader to create a program that - instantiates the system described by the spec -- a dot file for visualisation with `graphviz` -- an XML file for further manipulation -- an formal model in the Isabelle/HOL proof assistant for use in proofs about - the system described by the spec - -The tool is written Haskell and can be used as a stand-alone binary. See the -repository [README]({{page.repo_link}}/translator/README.md) for information on -how to build and run the tool. - -## capDL Loader - -The capDL Loader is a program that initialises the seL4 user-level environment -to match the system described by a capDL spec, and loads programs from ELFs in a -provided `cpio` archive. It is intended to be run as the root task, that is, the -first user-level thread, which has access to all resources. - -The capDL Loader must be linked against a capDL spec - the C output of the capDL -Translator. It must also be linked against a cpio archive containing ELF images. -It creates objects and distributes caps as per the spec (if enough resources are -available), and then loads programs into memory at locations specified by the -spec. Finally, it starts all the threads it created and sleeps forever. - -See also the separate [capDL loader page](c-loader-app.html). - -## Python capDL Library - -This library is useful for building up a representation of a capDL state -programmatically in memory and then writing that as a specification to disk. It -allows the programmer to incrementally add information about kernel objects and -capability distribution. The library is used by [CAmkES](../camkes/) to build up a -spec describing the entire system, covering all components and connections. - -See the repository [README]({{page.repo_link}}/python-capdl-tool/README.md) -for information on this library. - -There is also a `cmake` target for generating object sizes and various utilities -for using capDL in build scrips available in the [repository](https://github.com/sel4/capdl). - - -## Example Spec - -Below is an example capDL specification that describes an AArch32 system -with five kernel objects: a TCB, a CNode of size $2^3$, one 4K Frame with a -specified physical address, one page table, and one page directory. The -`caps` section of the spec describes the content of those objects in terms -of references (capabilities) to other objects. - -The capDL translator tool can transform this specification into other formats, -for instance for consumption by the capDL loader. These specifications do not -need to be written manually, they are typically generated from other tools, for -instance with the help of the Python capDL library. - -For more detail on how these specification work, see also the [language -specification for capDL](lang-spec.html). - -```capdl -arch ia32 - -objects { - my_tcb = tcb - my_cnode = cnode (3 bits) - my_frame = frame (4k, paddr: 0x12345000) // paddr is optional - my_page_table = pt - my_page_directory = pd -} - -caps { - - // Specify cap addresses (ie. CPtrs) in cnodes. - my_cnode { - 1: my_tcb - 2: my_frame - 3: my_page_table - 4: my_page_directory - } - - // Specify address space layout. - // With 4gb page directories, 4mb page tables, and 4kb frames, - // the frame at paddr 0x12345000 will be mapped at vaddr 0xABCDE000. - my_pd { - 0x2AF: my_pt - } - my_pt { - 0xDE: my_frame - } - - // Specify root cnode and root paging structure of thread. - my_tcb { - vspace: my_pd - cspace: my_cnode - } - -} -``` - -[Kuz et al (2010)]: https://trustworthy.systems/publications/nicta_full_text/3679.pdf "capDL: A language for describing capability-based systems" diff --git a/projects/capdl/lang-spec.html b/projects/capdl/lang-spec.html new file mode 100644 index 00000000000..fd810fbcf8e --- /dev/null +++ b/projects/capdl/lang-spec.html @@ -0,0 +1,1144 @@ + + + + + + + capDL Language Specification | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

capDL Language Specification

+ + + + + +

This document defines capDL revision 1.0, a language for capability +distributions.

+ +

Background and Purpose

+ +

The purpose of capDL is describing snapshots of a system running on the +seL4 microkernel. In particular, it can be used to describe which +entities have access to which seL4 capabilities.

+ +

The main objectives are to use these descriptions for specifying +systems, for security analysis of systems, as input for automated +bootstrapping of systems, and for debugging applications running on +seL4. A capDL specification can be complete, i.e. give a full picture of +all capabilities in the system, or the system can be underspecified, +showing only the capabilities accessible to a particular component. It +is possible to describe system states in capDL that are not reachable +via actual system executions. It is also possible to leave out details +in a system specification that for instance are not important for a +security analysis (e.g. because the relevant authority is already +represented otherwise), but that would be necessary for an actual +implementation of the system.

+ +

Syntax

+ +

This section gives a complete definition of the capDL syntax in BNF.

+ +

Lexical Tokens

+ +

The lexical tokens of capDL are numbers (number), identifiers +(identifier), and verbatim symbols and operators typeset between +quotes ” in the syntax section below.

+ +

Numbers are in decimal, hexadecimal (with prefix 0x), or octal (with +prefix 0) form. Identifiers start with a letter [a-zA-Z], followed by +a sequence of letters [a-zA-Z], numbers [0-9], the underscore +character _, or a @ character.

+ +

The language is case sensitive.

+ +

Comments can occur between any two tokens and can be nested. A +potentially multiline comment starts with the two characters /* and +ends with */. A one-line comment starts with –. All characters after +– up to the end of the same line are ignored.

+ +

Whitespace (a sequence of space, newline and tab characters) can occur +between any two tokens and is ignored.

+ +

Syntax

+ +

This section describes the concrete syntax of capDL using the tokens +defined above. The main syntactic entity of a file is module defined +in section Modules.

+ +

Names and Ranges

+ +
  name ::= identifier
+
+  num ::= '[' number ']'
+  range ::= number '..' number  | '..' number  | number  '..' | number
+  ranges ::=  '[' ']' | '[' range (',' range)* ']'
+
+  name_ref ::= name ranges?
+  qname ::= name_ref ('/' name_ref)*
+
+ +

Object Declarations

+ +
  obj_decls ::= 'objects' '{' obj_decl* '}'
+
+  obj_decl ::= qname '=' object
+
+  object ::= object_type object_params? opt_obj_decls?
+
+  object_type ::= 'ep'  | 'notification' | 'tcb' | 'cnode' | 'ut' | 'irq' |
+                  'asid_pool' | 'pt' | 'pd' | 'frame' | 'io_ports' |
+                  'io_device' | 'io_pt' | 'vcpu'
+
+  object_params ::= '(' (object_param (',' object_param)*)? ')'
+
+  object_param   ::= obj_bit_size | obj_vm_size | io_pt_level | obj_ports_size |
+                     init_arguments | tcb_dom | obj_paddr | domain_id |
+                     pci_device
+  obj_bit_size   ::= number 'bits'
+  obj_vm_size    ::= number ('k' | 'M')
+  io_pt_level    ::= 'level' ':' number
+  obj_ports_size ::= number 'k' 'ports'
+  init_arguments ::= 'init' ':' '[' (number (',' number)*)? ']'
+  tcb_dom        ::= 'dom' ':' number
+  obj_paddr      ::= 'paddr' ':' number
+  domain_id      ::= 'domainID' ':' number
+  pci_device     ::= number ':' number '.' number
+
+  opt_obj_decls ::= '{' ((obj_decl | name_ref) ','?)* '}'
+
+ +

Capability Declarations

+ +
  cap_decls ::= 'caps' '{' (cap_name_decl | cap_decl)* '}'
+
+  cap_name_decl ::= name '=' '(' name_ref ',' slot ')'
+
+  slot ::= number | symbolic_slot
+  symbolic_slot ::= 'cspace' | 'vspace' | 'reply_slot' | 'caller_slot' |
+                    'ipc_buffer_slot'
+
+  cap_decl ::= name_ref '{' (cap_mapping_or_ref ';'?)* '}'
+
+  cap_mapping_or_ref ::= (slot ':')? cap_name? (cap_mapping | cap_name_ref)
+
+  cap_name    ::= name_ref '='
+  cap_mapping ::= name_ref cap_params? parent?
+  cap_params  ::= '(' cap_param (',' cap_param)* ')'
+
+  cap_param ::= right+
+              | 'masked' ':' right+
+              | 'guard' ':' number
+              | 'guard_size' ':' number
+              | 'badge' ':' number
+              | 'ports'  ':' ranges
+              | 'reply'
+              | 'master_reply'
+              | 'asid' ':' asid
+              | 'cached'
+              | 'uncached'
+
+  right ::= 'R' | 'W' | 'G' | 'X'
+  asid ::= '(' number ',' number ')'
+
+  parent ::= '- child_of' slot_ref
+
+  slot_ref ::= '(' name_ref ',' slot ')' | name_ref
+
+  cap_name_ref ::= '<' name_ref '>' cap_params? parent?
+
+ +

IRQ Declarations

+ +
  irq_decls ::='irq_maps' '{' (irq_mapping ';'?)* '}'
+
+  irq_mapping ::= (number ':')? name_ref
+
+ +

CDT Declarations

+ +
  cdt_decls ::='cdt' '{' cdt_decl* '}'
+
+  cdt_decl ::= slot_ref '{' ((slot_ref | cdt_decl) ';'?)* '}'
+
+ +

Modules

+ +
  arch ::= 'arch' ('ia32' | 'arm11')
+
+  module ::= arch (obj_decls | cap_decls | irq_decls | cdt_decls)+
+
+ +

Semantics

+ +

In this section we show the semi-formal semantics of capDL in the form +of its underlying data model in Haskell and give a brief rationale for +its contents. This data model can be made fully formal by mapping it +directly into the Isabelle theorem prover via Data61’s existing +Haskell-to-Isabelle translation tool. The data model can also be mapped +into various output formats.

+ +

After describing the data model below, we outline a semi-formal +definition of the semantics: mapping the capDL syntax into the capDL +data model.

+ +

Data Model

+ +

Rationale

+

The purpose of capDL is describing a snapshot of the capability +distribution in a system running on the seL4 microkernel. For this +purpose, we need to know which objects exist in the system and which +capabilities they have access to. The second purpose of capDL is to +serve as sufficiently detailed input to automated code generation +tools. Therefore we need to include all information about capability +arguments that such implementations will need. Some of this information +will not be relevant for security analysis. For instance, for a +security analysis it may be necessary to know which frames of physical +memory an entity in the system can access via virtual memory, but it is +not necessary to know under which virtual address each of these +physical addresses is visible to the process. For a concrete +implementation of a bootstrapping component on the other hand, this +latter information is crucial.

+ +

The Model

+ +

We refer to objects by name. This name could be of any type; for +convenience we either use a plain string or a string with an index. We +use the Maybe type of Haskell to express this.

+ +
types ObjID = (String, Maybe Word)
+
+ +

With this the capability state of a system is fully described by a map +from ObjID to Object. Since not all objects and capabilities are +supported by seL4 on all machine architectures, we also store which +architecture the system is intended for.

+ +
data Model =  Model {
+                  arch :: Arch,
+                  objects :: Map ObjID Object
+              }
+
+data Arch = IA32 | ARM11
+
+ +

Objects are described by the following data type. We are mainly +interested in what capabilities an object contains. We also store +information that is relevant for creating an object such as its type and +its size when the size is configurable. This means in contrast to the +security model, where we only talk about abstract entities, we give more +detailed information in capDL.

+ +
types CapMap = Map Word Cap
+
+data Object = Endpoint
+            | Notification
+            | TCB { slots :: CapMap, initArguments :: [Word] }
+            | CNode { slots :: CapMap, sizeBits :: Word }
+            | Untyped { maybeSizeBits :: Maybe Word }
+
+            | ASIDPool { slots :: CapMap }
+            | PT { slots :: CapMap }
+            | PD { slots :: CapMap }
+            | Frame { vmSizeBits :: Word }
+            | IOPorts { size :: Word }
+            | IOPT { slots :: CapMap, level :: Word }
+            | IODevice { slots :: CapMap }
+
+ +

The first two objects, communication endpoints and notifications, do not +store any capabilities and have a fixed size. Thread Control Blocks +(TCB) contain a small number of capability registers, modelled by the +field slots, a map from a machine word (the slot/register number) to +the capability that is stored in that slot. Slots may be empty. CNode +objects are the main capability storage object in seL4. They have +configurable size. Untyped objects are conceptual containers for +dynamically created objects. They cover a set of objects referred to by +their ObjID. This set is called the covering set. In the +implementation untyped objects must have a size, but in capDL +specifications we often want to leave the size unspecified (as large as +necessary).

+ +

The next batch of objects in the data type above are architecture +dependent. Most of these data structures and devices do not store actual +capabilities in the kernel and hardware implementation. Instead they +store pointers or mappings to other resources in the system. Since these +resources are already represented as objects, we use capabilities to +model these mappings and to express the access, for instance, a device +may have to physical memory. In detail, the architecture dependent +objects are as follows. ASID pools store which page directories (PD) can +be activated by the machine. As mentioned, we represent this mapping as +a capability in the model. Analogously, we model the mappings in virtual +memory objects page directory (PD) and page table (PT). Physical memory +frames (Frame) come in different sizes, depending on architecture, but +do not contain further capabilities. IOMMU page tables (IOPT) come in +multiple levels and again store mappings to frames or further page +tables. Finally, hardware devices are represented by the object type +IODevice. Again, we model the access hardware may have to resources in +the system as capabilities. Specifically, IODevices may have a +capability to a CNode for IRQ delivery, potentially multiple +capabilities to physical memory frames for memory mapped device +registers, and one capability for the root IOMMU space.

+ +

To conclude the description of the capDL data model, it remains to +define the data type of capabilities Cap. Almost all capabilities in +seL4 refer to one specific object. Some may refer to a set of objects or +implicitly to all objects of a given type. Many of the capabilities +store explicit access rights. These are modelled as follows:

+ +
data Rights = Read | Write | Grant | GrantReply
+types CapRights = Set Right
+
+ +

Again in contrast to the security model of seL4, we explicitly +distinguish different types of capabilities in capDL and store slightly +different kinds of additional information with each. As a side effect, +we do not need an explicit representation of the create right. The +create right is conferred by the possession of an untyped capability.

+ +
data Cap = NullCap
+         | UntypedCap { capObj :: ObjID }
+         | EndpointCap { capObj :: ObjID, capBadge :: Word,
+                         capRights :: CapRights }
+         | NotificationCap { capObj :: ObjID, capBadge :: Word,
+                             capRights :: CapRights }
+         | ReplyCap { capObj :: ObjID }
+         | MasterReplyCap { capObj :: ObjID }
+         | CNodeCap { capObj :: ObjID, capGuard :: Word,
+                      capGuardSize :: Word }
+         | TCBCap { capObj :: ObjID }
+         | IRQControlCap
+         | IRQHandlerCap { capObj :: ObjID }
+         | FrameCap { capObj :: ObjID, capRights :: CapRights }
+         | PTCap { capObj :: ObjID }
+         | PDCap { capObj :: ObjID }
+         | ASIDControlCap
+         | ASIDPoolCap { capObj :: ObjID }
+         | IOPortsCap { capObjs :: Set Word }
+         | IOSpaceMasterCap
+         | IOSpaceCap { capObj :: ObjID }
+         | IOPTCap { capObj :: ObjID }
+
+ +

In detail, the capabilities are as follows. We go through the list of +capabilities and give a brief indication of the authority they convey. +The NullCap is occasionally used to represent the absence of a +capability. An untyped capability points to an untyped object and +confers the right to issue create/retype and revoke/delete operations. +Endpoint and notification capabilities point to their respective object +types. They explicitly store which Read/Write/Grant access is conferred +to the communications channel and they may carry one machine word of +additional information, called the badge. CNode capabilities in addition +to their CNode object reference carry information that influences the +lookup of capabilities in the node they point to. This information +consists of a guard in the sense of guarded page tables, the size of +that guard, and finally the rights to the CNode object itself. A TCB cap +gives authority over one TCB object with given access rights. The +IRQControl capability gives authority to create specific IRQHandler +capabilities. Each device may have a special CNode associated with it +that may contain a notification which in turn is used to deliver +interrupts to user level. IRQHandler caps in capDL point to these +specific CNodes. It confers the authority to change which endpoint the +interrupt is delivered to. Frame capabilities confer authority to map +and unmap physical memory frames into and from a page directory or page +table with the specified access rights. PT caps give authority to +map/unmap page tables into/from page directories and PD caps give the +authority to map/unmap page directories into ASID pools and to install +them as virtual memory space of a process. The ASIDControlCap together +with an Untyped cap confers authority to create new ASID pools. Only a +limited, fixed number can be created in the system. ASIDPool caps give +the authority to map/unmap page directories into/from the ASID pool. +Mapping a frame into a page table for instance, needs the frame cap to +specify which frame to map with which rights and the PT cap to specify +in which page table. The IOPorts capability gives access to a set of +IOPorts on the ia32 architecture. The IOSpaceMasterCap confers the +authority to create IOSpace caps for specific devices. IOSpaceCaps point +to IODevices and confer the authority to set the root IOPageTable for +that device. IOPTCaps are the IOMMU analogue to PT and PD caps in normal +virtual memory.

+ +

Semantics

+ +

In this section, we define a mapping from the syntax of capDL to the +data model of capDL. The mapping is defined by going over the relevant +productions in the capDL grammar and describing the corresponding model.

+ +

Names and Ranges

+ +
  name ::= identifier
+
+ +

Names are mapped to ObjIDs in the model. A name without index maps to +(name, Nothing). Qualified names will be defined in the object +declaration section.

+ +
  num ::= '[' number ']'
+
+ +

This production maps to a single index and is used to either declare a +set of objects, in which case the number is the number of objects, or to +refer to a specific index. The term name[x] maps to the ObjID +(name, Just x).

+ +
  range ::= number '..' number  | '..' number  | number  '..' | number
+  ranges ::=  '[' ']' | '[' range (',' range)* ']'
+  name_ref ::= name ranges?
+
+ +

Ranges stand for sets of ObjIDs. For a set declared as name[n], the +following mappings apply:

+ +
    +
  • +

    name[..b] refers to name[0], name[1], .., name[b]

    +
    • +
  • +

    name[a..] refers to name[a], name[a+1], .., name[n]

    +
    • +
  • +

    name[a..b] refers to name[a], name[a+1], .., name[b]

    +
    • +
  • +

    name[] refers to name[0], name[1], .., name[n]

    +
    • +
+ +

A list of ranges name[r1,r2,..r3] refers to the union of the ranges +name[r1], name[r2], .., name[r3].

+ +

Module

+ +
  arch ::= 'arch' ('ia32' | 'arm11')
+  module ::= arch (obj_decls | cap_decls)+
+
+ +

A module maps to a full Model in the data model. Its Arch component +is determined by arch, its mapping from ObjID to Object by the +object and capability declarations described below.

+ +

Object Declarations

+ +
  obj_decls ::= 'objects' obj_decl*
+
+ +

An object declaration section defines a set of objects. Each object name +of typed objects should be declared only once. The covering set of +untyped objects may be declared multiple times. The total covering set +is the union of all covering sets mentioned for that object.

+ +
  obj_decl ::= qname '=' object
+
+ +

An object declaration has a potentially qualified name and dimension on +the left hand side and an object content declaration on the right hand +side. A qualified name name1/name2/name3[n] implicitly declares the +untyped objects name1 and name2. It also declares that name2 is +covered by name1 and name3 covered by name2. Giving a dimension +[n] means that n objects (name3, Just 0) to (name3, Just (n-1)) +are declared, each with the same content described on the right hand +side of the equation.

+ +

The right hand side is defined by the following syntax productions:

+ +
  object ::= object_type object_params? obj_decls?
+
+  object_type ::= 'ep'  | 'notification' | 'tcb' | 'cnode' | 'ut' |
+                  'asid_pool' | 'pt' | 'pd' | 'frame' | 'io_ports' |
+                  'io_device' | 'io_pt'
+
+  object_params ::= '(' object_param (',' object_param)* ')'
+
+  object_param   ::= obj_bit_size | obj_vm_size | io_pt_level | obj_ports_size
+  obj_bit_size   ::= number 'bits'
+  obj_vm_size    ::= number ('k' | 'M')
+  io_pt_level    ::= 'level' ':' ('1' | '2' | '3')
+  obj_ports_size ::= number 'k' 'ports'
+
+  obj_decls ::= '{' ((obj_decl | name_ref) ','?)* '}'
+
+ +

The object content is given by the type of the object mapping to its +corresponding object type in the data model. Some of the object types in +the model require a size parameter, given in bits (where n bits means a +size of 2^n entries). Frames’ sizes are specified directly as are the +levels of IOMMU page tables. Untyped objects can be followed by a nested +object declaration. Writing

+ +
name1 = ut {
+  name2/name3 [n] = object
+  name2/name4 = object
+ ...
+}
+
+ +

is equivalent to writing

+ +
name1/name2/name3 [n] = object
+name1/name2/name4 = object
+...
+
+ +

Capability Declarations

+ +

The capability content of objects is declared in its own section, +separately from the list of objects itself.

+ +
  cap_decls = 'caps' (cap_name_decl | cap_decl)*
+
+  cap_name_decl ::= name '=' '(' name_ref ',' slot ')'
+  slot ::= number | symbolic_slot
+  symbolic_slot ::= 'cspace' | 'vspace'
+
+ +

Next to capability content declarations, there are name declarations for +capability slots. A capability slot is defined by the container object, +referred to by a name reference (mapping to a single ObjID) and a slot +inside the container specified by its slot number. The symbolic slot +names cspace, vspace stand for slot numbers 0 and 1.

+ +

A capability declaration starts with a set of container objects, each of +which is declared to contain the capability mappings specified on the +right hand side. Container objects may occur more than once in a +specification. Their mappings are the union of all mappings for that +container object.

+ +
  cap_decl ::= name_ref '{' (cap_mapping_or_ref ';'?)* '}'
+
+ +

A cap mapping is specified by its slot and its capability and +potentially an inline name declaration for the specified slot in the +specified container.

+ +
  cap_mapping_or_ref ::= slot ':' cap_name? (cap_mapping | cap_name_ref)
+
+  cap_name    ::= name '='
+  cap_mapping ::= name_ref cap_params?
+  cap_params  ::= '(' cap_param (',' cap_param)* ')'
+
+  cap_param ::= right+
+              | 'masked' ':' right+
+              | 'guard' ':' number
+              | 'guard_size' ':' number
+              | 'irq'
+              | 'badge' ':' number
+              | 'reply'
+              | 'master_reply'
+
+  right ::= 'R' | 'W' | 'G'
+
+  cap_name_ref ::= '<' name_ref '>' cap_params?
+
+ +

The capability declaration is either a cap_mapping or cap_name_ref. +In the latter case the mapping is a copy of the capability in the slot +referred to by name (possibly masked with an access rights mask). In +the former case, a cap is defined by the object it points to, together +with optional parameters depending on the type of the object in the data +model. For instance, an endpoint cap is specified if the ObjID given +in the cap declaration refers to an endpoint object. If no parameters +are mentioned, default parameters are substituted if possible. These +defaults are: empty set of rights for access rights, full set of rights +for rights masks, guard 0, guard size 0, and badge 0. The IRQControl cap +is specified using the reserved ObjID irq_control, similarly +ASIDControlCap is specified by asid_control and IOSpaceMasterCap by +io_space_master.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/capdl/lang-spec.md b/projects/capdl/lang-spec.md deleted file mode 100644 index 5876d9479ca..00000000000 --- a/projects/capdl/lang-spec.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -toc: true -repo: seL4/capdl -include_file: 'capDL-tool/doc/capDL.md' -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC. ---- - -# capDL Language Specification - -{% include include_github_repo_markdown.md indent_headings=true %} diff --git a/projects/capdl/object-sizes.html b/projects/capdl/object-sizes.html new file mode 100644 index 00000000000..0f21545cc2f --- /dev/null +++ b/projects/capdl/object-sizes.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/capdl/object-sizes.md b/projects/capdl/object-sizes.md deleted file mode 100644 index 431de7ed56b..00000000000 --- a/projects/capdl/object-sizes.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: https://github.com/seL4/capdl/tree/master/object_sizes/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/projects/capdl/python-tool.html b/projects/capdl/python-tool.html new file mode 100644 index 00000000000..9a09648e61b --- /dev/null +++ b/projects/capdl/python-tool.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/capdl/python-tool.md b/projects/capdl/python-tool.md deleted file mode 100644 index 35778bdef37..00000000000 --- a/projects/capdl/python-tool.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: https://github.com/seL4/capdl/tree/master/python-capdl-tool -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/projects/capdl/releases.md b/projects/capdl/releases.md deleted file mode 100644 index 5ddef9e44a5..00000000000 --- a/projects/capdl/releases.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -permalink: /releases/capDL.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# capDL Releases - -{% assign coll = site['releases'] | where: "project", "capdl" %} - -{% for release in coll reversed %} -{%- assign seL4_link = '[' | append: release.seL4 | append: '](' | - append: '/releases/sel4/' | append: release.seL4 | - append: '.html)' %} -- capDL Release [{{ release.title }}]({{ release.url | relative_url }}) for seL4 {{seL4_link}} {% if forloop.first %}(latest){% endif %} -{% endfor %} diff --git a/projects/capdl/translator.html b/projects/capdl/translator.html new file mode 100644 index 00000000000..151cf01fbef --- /dev/null +++ b/projects/capdl/translator.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/capdl/translator.md b/projects/capdl/translator.md deleted file mode 100644 index d3401751ef7..00000000000 --- a/projects/capdl/translator.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: https://github.com/seL4/capdl/tree/master/capDL-tool/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/projects/dockerfiles/index.html b/projects/dockerfiles/index.html new file mode 100644 index 00000000000..9e167516e9c --- /dev/null +++ b/projects/dockerfiles/index.html @@ -0,0 +1,685 @@ + + + + + + + Using Docker for seL4, Microkit, and CAmkES | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Using Docker for seL4, Microkit, and CAmkES

+ +

This page provides instructions on how to quickly set up your machine for +building the seL4 kernel and related projects.

+ +

Requirements

+ +

These instructions assume you are using Debian or a derivative, such as Ubuntu, +and are using Bash for your shell. However, it should be informative enough for +users of other distributions/shells to adapt.

+ +

To begin, you will need at least these two programs:

+ +
    +
  • make (sudo apt install make)
    • +
  • docker (See here or +here for installation +instructions)
    • +
+ +

For convenience, add your account to the Docker group:

+ +
sudo usermod -aG docker $(whoami)
+
+ +

Note that after doing so you may have to logout of your account and log back in +for the change to have affect.

+ +

Setting up a build environment

+ +

To get a running build environment for seL4, run:

+ +
git clone https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles.git
+cd seL4-CAmkES-L4v-dockerfiles
+make user
+
+ +

This will give you a terminal inside a container that has all the relevant tools +to build, simulate, and test seL4 and related projects.

+ +

The first time you run this, docker will fetch the relevant images, which may +take a while.

+ +

To map a particular directory into the container:

+ +
make user HOST_DIR=/scratch/seL4_stuff  # as an example
+# Now /host in the container maps to /scratch/seL4_stuff
+
+ +

To make this easier to type, you can setup a bash alias such as this:

+ +
echo $'alias container=\'make -C /<path>/<to>/seL4-CAmkES-L4v-dockerfiles user HOST_DIR=$(pwd)\'' >> ~/.bashrc
+# now open a new terminal, or run `source ~/.bashrc`
+
+ +

Replace /<path>/<to>/ to match where you cloned the git repo of the docker +files. This then allows you to run:

+ +
container
+
+ +

to start the container in the current directory you are in.

+ +

An example workflow:

+ +

A good workflow is to run two terminals:

+ +
    +
  • terminal A is a normal terminal, and is used for git and editing +(e.g., vim, emacs, vscode).
    • +
  • terminal B is running a Docker container, and is only used for compilation.
    • +
+ +

This gives you the flexibility to use all the tools you are used to, +while having the seL4 dependencies separated from your machine.

+ +

Compiling seL4 test

+ +

Start two terminals, terminal A (host) and terminal B (docker).

+ +

In terminal A, run these commands:

+ +
jblogs@host:~$ mkdir ~/seL4test
+jblogs@host:~$ cd ~/seL4test
+jblogs@host:~/seL4test$ repo init -u https://github.com/seL4/seL4test-manifest.git
+jblogs@host:~/seL4test$ repo sync
+
+ +

In terminal B, run these commands:

+ +
jblogs@host:~$ cd ~/seL4test
+jblogs@host:~/seL4test$ container  # using the bash alias defined above
+jblogs@in-container:/host$ mkdir build-x86
+jblogs@in-container:/host$ cd build-x86
+jblogs@in-container:/host/build-x86$ ../init-build.sh -DPLATFORM=x86_64 -DSIMULATION=TRUE
+jblogs@in-container:/host/build-x86$ ninja
+
+ +

If you need to make any code modifications or commit things to git, use terminal +A. If you need to recompile or simulate an image, use terminal B.

+ +
+
+ + Note +
+
+ +

If QEMU fails when trying to simulate the image, try configuring your +Docker host to give the container more memory.

+ +
+
+ +

Adding dependencies

+ +

To add more software inside the container, modify the extras.dockerfile. It +contains an apt-get command which can be added to. After the first +modification, docker will rebuild the extras image, and cache it after that.

+ +

Available images

+ +

All the prebuilt docker images are available on DockerHub +here These images are used by the +Trustworthy Systems Continuous Integration (CI) software, and so represent a +standard software setup we use.

+ +

The CI software always uses the latest docker image, but images are also +tagged with the date they were built.

+ +

More information

+ +

You can find the docker files and supporting Makefile in the +repository

+ +

Pull-requests and issues are welcome.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/dockerfiles/index.md b/projects/dockerfiles/index.md deleted file mode 100644 index d26539f6d46..00000000000 --- a/projects/dockerfiles/index.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -redirect_from: - - /Docker -project: dockerfiles -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Using Docker for seL4, Microkit, and CAmkES - -This page provides instructions on how to quickly set up your machine for -building the seL4 kernel and related projects. - -## Requirements - -These instructions assume you are using Debian or a derivative, such as Ubuntu, -and are using Bash for your shell. However, it should be informative enough for -users of other distributions/shells to adapt. - -To begin, you will need at least these two programs: - -* make (`sudo apt install make`) -* docker (See [here](https://get.docker.com) or - [here](https://docs.docker.com/engine/installation) for installation - instructions) - -For convenience, add your account to the Docker group: - -```bash -sudo usermod -aG docker $(whoami) -``` - -Note that after doing so you may have to logout of your account and log back in -for the change to have affect. - -## Setting up a build environment - -To get a running build environment for seL4, run: - -```bash -git clone https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles.git -cd seL4-CAmkES-L4v-dockerfiles -make user -``` - -This will give you a terminal inside a container that has all the relevant tools -to build, simulate, and test seL4 and related projects. - -The first time you run this, docker will fetch the relevant images, which may -take a while. - -To map a particular directory into the container: - -```bash -make user HOST_DIR=/scratch/seL4_stuff # as an example -# Now /host in the container maps to /scratch/seL4_stuff -``` - -To make this easier to type, you can setup a bash alias such as this: - -```bash -echo $'alias container=\'make -C ///seL4-CAmkES-L4v-dockerfiles user HOST_DIR=$(pwd)\'' >> ~/.bashrc -# now open a new terminal, or run `source ~/.bashrc` -``` - -Replace `///` to match where you cloned the git repo of the docker -files. This then allows you to run: - -```bash -container -``` - -to start the container in the current directory you are in. - -## An example workflow: - -A good workflow is to run two terminals: - -* terminal A is a normal terminal, and is used for git and editing - (e.g., vim, emacs, vscode). -* terminal B is running a Docker container, and is only used for compilation. - -This gives you the flexibility to use all the tools you are used to, -while having the seL4 dependencies separated from your machine. - -### Compiling seL4 test - -Start two terminals, terminal A (host) and terminal B (docker). - -In terminal A, run these commands: - -```bash -jblogs@host:~$ mkdir ~/seL4test -jblogs@host:~$ cd ~/seL4test -jblogs@host:~/seL4test$ repo init -u https://github.com/seL4/seL4test-manifest.git -jblogs@host:~/seL4test$ repo sync -``` - -In terminal B, run these commands: - -```bash -jblogs@host:~$ cd ~/seL4test -jblogs@host:~/seL4test$ container # using the bash alias defined above -jblogs@in-container:/host$ mkdir build-x86 -jblogs@in-container:/host$ cd build-x86 -jblogs@in-container:/host/build-x86$ ../init-build.sh -DPLATFORM=x86_64 -DSIMULATION=TRUE -jblogs@in-container:/host/build-x86$ ninja -``` - -If you need to make any code modifications or commit things to git, use terminal -A. If you need to recompile or simulate an image, use terminal B. - -{% include note.html %} -If QEMU fails when trying to simulate the image, try configuring your -Docker host to give the container more memory. -{% include endnote.html %} - -## Adding dependencies - -To add more software inside the container, modify the `extras.dockerfile`. It -contains an `apt-get` command which can be added to. After the first -modification, docker will rebuild the extras image, and cache it after that. - -## Available images - -All the prebuilt docker images are available on [DockerHub -here](https://hub.docker.com/u/trustworthysystems) These images are used by the -Trustworthy Systems Continuous Integration (CI) software, and so represent a -standard software setup we use. - -The CI software always uses the `latest` docker image, but images are also -tagged with the date they were built. - -## More information - -You can find the docker files and supporting Makefile in the -[repository](https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles) - -Pull-requests and issues are [welcome](https://sel4.systems/Contribute/). diff --git a/projects/driver_framework/AddressingOtherDevices.html b/projects/driver_framework/AddressingOtherDevices.html new file mode 100644 index 00000000000..f38bd949f10 --- /dev/null +++ b/projects/driver_framework/AddressingOtherDevices.html @@ -0,0 +1,595 @@ + + + + + + + seL4 Driver API Persistent Device Naming Scheme | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

seL4 Driver API Persistent Device Naming Scheme

+ +

Recommended prior reading for this page is the seL4 Driver API’s +location-based device addressing scheme.

+ +

Constants

+ +

Functions

+
seL4drv_connection_t *seL4drv_external_connect();
+
+

Data structures

+
typedef void seL4drv_connection_t;
+
+ +

Description

+ +

The seL4 Driver API requires the use of a persistent naming scheme which +forms the basis of the IPC connection system between device instances. +It is through this naming scheme that a device instance can call to its +parent devices, and communicate with devices with which it has lateral +dependencies.

+ +

Devices’ addressable names are generated by the parent driver that +enumerates them. Child device enumeration is discussed in detail in the +Child Enumeration article.

+ +

A driver connects to an external device that it depends on by calling +seL4drv_external_connect(), passing in the addressable name of the +particular device that it wishes to connect to. The environment shall +search its device tree for a device which has that name, and return a +handle of type seL4drv_connection_t *. Notice that +seL4drv_connection_t is of type void (see above): +this is because it is an opaque handle, and the +driver is not meant to dereference this handle after receiving it. This +handle is meant to be passed to subsequent function calls to the +particular API that was connected to in order to maintain context +between the driver and the target device.

+ +

If the environment is unable to locate a device whose addressable name +matches the one supplied in the call to seL4drv_external_connect(), it +shall return NULL. The calling driver shall take this to mean that +the device is trying to connect to does not exist, or that it exists but +the environment does not have a driver that can drive it, and so is +unusable.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/driver_framework/AddressingOtherDevices.md b/projects/driver_framework/AddressingOtherDevices.md deleted file mode 100644 index b0b2e089e87..00000000000 --- a/projects/driver_framework/AddressingOtherDevices.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -archive: true -redirect_from: - - /seL4DriverAPI/AddressingOtherDevices -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4 Driver API Persistent Device Naming Scheme - - -Recommended prior reading for this page is the seL4 Driver API's -[location-based device addressing scheme](ChildEnumeration.html#addressing-names). - -## Constants - - -## Functions -```c -seL4drv_connection_t *seL4drv_external_connect(); -``` -## Data structures -```c -typedef void seL4drv_connection_t; -``` - -## Description - - -The seL4 Driver API requires the use of a persistent naming scheme which -forms the basis of the IPC connection system between device instances. -It is through this naming scheme that a device instance can call to its -parent devices, and communicate with devices with which it has lateral -dependencies. - -Devices' addressable names are generated by the parent driver that -enumerates them. Child device enumeration is discussed in detail in the -[Child Enumeration](ChildEnumeration.html#addressing-names) article. - -A driver connects to an external device that it depends on by calling -`seL4drv_external_connect()`, passing in the addressable name of the -particular device that it wishes to connect to. The environment shall -search its device tree for a device which has that name, and return a -handle of type `seL4drv_connection_t *`. Notice that -`seL4drv_connection_t` is of type `void` (see [above](#data-structures)): -this is because it is an opaque handle, and the -driver is not meant to dereference this handle after receiving it. This -handle is meant to be passed to subsequent function calls to the -particular API that was connected to in order to maintain context -between the driver and the target device. - -If the environment is unable to locate a device whose addressable name -matches the one supplied in the call to `seL4drv_external_connect()`, it -shall return **NULL**. The calling driver shall take this to mean that -the device is trying to connect to does not exist, or that it exists but -the environment does not have a driver that can drive it, and so is -unusable. diff --git a/projects/driver_framework/ChildEnumeration.html b/projects/driver_framework/ChildEnumeration.html new file mode 100644 index 00000000000..06cdb8c4e51 --- /dev/null +++ b/projects/driver_framework/ChildEnumeration.html @@ -0,0 +1,756 @@ + + + + + + + Child enumeration model for the seL4 Driver API: | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Child enumeration model for the seL4 Driver API:

+ +

Constants

+
#define SEL4DRV_DEVATTR_NAME_MAXLEN (32)
+
+ +

Functions

+
seL4drv_mgmt_enumerate_get_num_children():
+seL4drv_mgmt_enumerate_children();
+seL4drv_mgmt_enumerate_hotplug_subscribe();
+uint16_t seL4drv_mgmt_query_device_match();
+
+ +

Structures

+
typedef struct seL4drv_child_attribute_ {
+   char attr_name[SEL4DRV_DEVATTR_NAME_MAXLEN];
+   uint32_t attr_value;
+} seL4drv_child_attribute_t;
+
+ +

Child IDs

+

Each driver whose device is capable of enumerating child +devices must generate a unique child ID for each such child. The child +ID is not required to be globally unique, but it must be unique with +respect to all of of that child’s sibling devices.

+ +

The Child-ID need not be persistently unique across executions of the +driver either. The same child device may be assigned a different +child-ID if the driver is killed and then re-initialized. The purpose of +the child-ID is to form a “relational key” (to borrow a database +software term) between the driver and the environment. The same physical +child device may be given different child-IDs by its parent even within +the same execution of that parent if, for example, that child is +unplugged from the computer, and then plugged back in as a hot-plug +event; the parent driver may assign that child device a different +child-ID when it is plugged back in.

+ +

The Environment and the host OS may choose to use some other internal +representation of such child IDs that best suits its device tree, but +this child ID shall be passed back to the driver exactly as originally +given by the driver, for any API call into the driver that requires a +child ID.

+ +

Addressing Names

+

Each driver whose device is capable of +enumerating child devices must also generate a unique addressing name +for each of the children. This name does not need to be globally unique, +but it is expected to be unique with respect to all of that child +device’s siblings. This addressing name must target the device by its +location relative to its parent bus technology.

+ +

This persistent name must always uniquely identify the same device +microcontroller relative to its parent’s bus technology. For example, if +on an ISA bus, there are 4 ATA/IDE disks, and the parent ISA bus driver +wishes to generate a persistent name for each of the disks, it should +name them by their persistent locations on the ATA wire. Perhaps they +might be “ATA0-master”, “ATA0-slave”, “ATA1-master” and “ATA1-slave”.

+ +

NB: the intention is not to uniquely identify the attached, removable +peripheral DISK that is attached to the ATA/IDE microcontroller, but to +identify the ATA/IDE microcontroller itself, which is wired onto the +silicon. The swappable disk that happens to be attached to the +interfacing microcontroller will be persistently named by the Operating +System according to that OS’s own convention. That is beyond the scope +of this specification.

+ +

In the case of a PCI device, the persistent name might be the +location-based <Bus+Device+Function> combination which would +uniquely, and persistently identify a particular PCI unit across +executions. Again, the intention is not to identify the particular +peripheral that is connected on that PCI <bus+device+function>. +The recognition of a particular PCI peripheral card such as a specific +graphics card, should be left up to the higher layer Operating System +which will name that peripheral according to its own convention.

+ +

In the case of a USB device, the persistent name might be an 8-bit +location-based hub-relative identifier for the USB port, starting from +the root hub down the tree of hubs to that USB port. The actual port’s +persistent name might be a simple 8-bit integer that identifies that +port’s hub, concatenated with that port’s address on that hub. The +parent hub might have been named by the root hub. Once again, the +generation of a persistent name for a specific USB flash disk that +happens to be plugged into any particular USB port will be handled by +the host Operating System, and is not the focus of this naming scheme. +The addressable naming scheme is attempting to determine the +bus-relative location, and not the particular peripheral that is +attached to that location/port.

+ +

Procedural flow

+

The intention of the enumeration API is to enable +the environment to both build and maintain its “device tree”, which it +uses to track the status and availability of hardware. The enumeration +API enables initial discovery of hardware devices, as well as dynamic +discovery and removal of devices from the tree as they appear and +disappear.

+ +

The environment should begin an enumeration sequence by calling +seL4drv_mgmt_enumerate_get_num_children() on the target device +instance, in order to ask the driver to tell it how many child devices +it currently has. The parent driver shall report all such +child devices, regardless of whether or not they are powered on. All +devices which are operationally viable and functional should be reported +to the environment. By implication, faulty or malfunctioning devices, if +they can be recognized as such (e.g., if the firmware informs the driver +that a device is faulty) should be omitted.

+ +

After that, the environment should call +seL4drv_mgmt_enumerate_children() to actually get information on all +the target device instance’s children. The environment shall pass to +this function a block of memory that is suitably sized to enable the +driver to fill out the childrens’ information. Please see the +description of seL4drv_mgmt_enumerate_get_num_children() in its +section below to understand how to determine how much memory to allocate +when requesting child device information.

+ +

The driver will then fill out this information for each child device, +and return the information to the environment.

+ +

Hotplug device enumeration

+

The API supports hotplug device +enumeration through the means of a “subscription” function. The driver +does not initiate a notification to the environment. Rather, the +environment posts an indication of interest (subscription notification), +along with an asynchronous context preserving cookie. The driver shall +keep this context cookie until a hotplug event occurs (whether the +addition or removal of a device), and at such a time, it shall generate +the asynchronous callback that completes the asynchronous roundtrip for +the “subscription” invocation.

+ +

When the environment finally gets such a callback, it shall simply +refresh its information about the children of the target device, by once +again calling seL4drv_mgmt_enumerate_get_num_children(), and doing +a re-run of seL4drv_mgmt_enumerate_children(). The environment can +then compare the Child IDs of the newly returned list of devices +with those that it previously had in its device tree, and perform an +update of its device tree.

+ +

When the driver completes the asynchronous roundtrip, it shall return +the same memory that was originally passed to it by the environment. The +environment is then free to either re-subscribe to such notifications by +calling seL4drv_mgmt_enumerate_hotplug_subscribe_ind() again, or to +choose to indicate that it is no longer interested in subscribing to +such notifications by not calling it again.

+ +

API

+ +

seL4drv_mgmt_enumerate_get_num_children(): Sync

+

This +function allows the environment to know how much memory it should +allocate for its subsequent calls to +seL4drv_mgmt_enumerate_children().

+ +

There are two values returned by this function:

+ +
    +
  1. The number of child devices that the driver instance is +aware of. Let this value be N_children.
    2. +
  2. The number of attributes required to describe each child device. +Let this value be N_attrs_per_child.
    3. +
+ +

The environment is expected to allocate memory equal to +N_attrs_per_child * sizeof(seL4drv_child_attribute_t) for each +child device.

+ +

If seL4drv_mgmt_enumerate_get_num_children() reports that there are +multiple child devices, the environment is expected to allocate memory +equal to +N_attrs_per_child * sizeof(seL4drv_child_attribute_t) * N_children.

+ +

This amount of memory shall then be passed to +seL4drv_mgmt_enumerate_children().

+ +

seL4drv_mgmt_enumerate_children(): Sync

+

This function shall +cause the driver to return a list of child devices and their attributes, +as well as Child IDs for each of the children, according to the its +discretion, deferring to the constraints outlined above.

+ +

seL4drv_mgmt_enumerate_hotplug_subscribe(): Async

+

This +function shall transfer to the driver a block of memory which shall be +kept by the driver until a hotplug event occurs. When such an event +occurs, the driver shall complete the asynchronous roundtrip by calling +back to the environment, returning the memory to the environment in so +doing.

+ +

seL4drv_mgmt_identify_device(): Sync

+

This function shall take +a list of attributes that describe a device, and return an unsigned +integer which states whether or not the driver can handle the device +that is described by those attributes.

+ +

If the driver determines that the passed attributes do not describe a +device that it can manage, the driver shall return integer 0 +(zero). If the driver determines that the passed attributes describe a +device that it is equipped to handle, it shall return a positive +integer 1.

+ +

It is recommended that drivers which return a value greater than 0 +should return 1 for now, since in the future, significance will be +ascribed to the values returned. At present, there is no significance +attached to the particular value returned, but for future compatibility +since values above 1 will carry significance, drivers must return 1 for +now.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/driver_framework/ChildEnumeration.md b/projects/driver_framework/ChildEnumeration.md deleted file mode 100644 index b4292d12727..00000000000 --- a/projects/driver_framework/ChildEnumeration.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -archive: true -redirect_from: - - /seL4DriverAPI/ChildEnumeration -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Child enumeration model for the seL4 Driver API: - - -## Constants -```c -#define SEL4DRV_DEVATTR_NAME_MAXLEN (32) -``` - -## Functions -```c -seL4drv_mgmt_enumerate_get_num_children(): -seL4drv_mgmt_enumerate_children(); -seL4drv_mgmt_enumerate_hotplug_subscribe(); -uint16_t seL4drv_mgmt_query_device_match(); -``` - -## Structures -```c -typedef struct seL4drv_child_attribute_ { - char attr_name[SEL4DRV_DEVATTR_NAME_MAXLEN]; - uint32_t attr_value; -} seL4drv_child_attribute_t; -``` - -## Child IDs - Each driver whose device is capable of enumerating child -devices must generate a unique child ID for each such child. The child -ID is not required to be globally unique, but it must be unique with -respect to all of of that child's sibling devices. - -The Child-ID need not be persistently unique across executions of the -driver either. The same child device may be assigned a different -child-ID if the driver is killed and then re-initialized. The purpose of -the child-ID is to form a "relational key" (to borrow a database -software term) between the driver and the environment. The same physical -child device may be given different child-IDs by its parent even within -the same execution of that parent if, for example, that child is -unplugged from the computer, and then plugged back in as a hot-plug -event; the parent driver may assign that child device a different -child-ID when it is plugged back in. - -The Environment and the host OS may choose to use some other internal -representation of such child IDs that best suits its device tree, but -this child ID shall be passed back to the driver exactly as originally -given by the driver, for any API call into the driver that requires a -child ID. - -## Addressing Names - Each driver whose device is capable of -enumerating child devices must also generate a unique addressing name -for each of the children. This name does not need to be globally unique, -but it is expected to be unique with respect to all of that child -device's siblings. This addressing name must target the device by its -**location** relative to its parent bus technology. - -This persistent name must always uniquely identify the same device -microcontroller relative to its parent's bus technology. For example, if -on an ISA bus, there are 4 ATA/IDE disks, and the parent ISA bus driver -wishes to generate a persistent name for each of the disks, it should -name them by their persistent locations on the ATA wire. Perhaps they -might be "ATA0-master", "ATA0-slave", "ATA1-master" and "ATA1-slave". - -NB: the intention is not to uniquely identify the attached, removable -peripheral DISK that is attached to the ATA/IDE microcontroller, but to -identify the ATA/IDE microcontroller itself, which is wired onto the -silicon. The swappable disk that happens to be attached to the -interfacing microcontroller will be persistently named by the Operating -System according to that OS's own convention. That is beyond the scope -of this specification. - -In the case of a PCI device, the persistent name might be the -location-based combination which would -uniquely, and persistently identify a particular PCI unit across -executions. Again, the intention is not to identify the particular -peripheral that is connected on that PCI . -The recognition of a particular PCI peripheral card such as a specific -graphics card, should be left up to the higher layer Operating System -which will name that peripheral according to its own convention. - -In the case of a USB device, the persistent name might be an 8-bit -location-based hub-relative identifier for the USB port, starting from -the root hub down the tree of hubs to that USB port. The actual port's -persistent name might be a simple 8-bit integer that identifies that -port's hub, concatenated with that port's address on that hub. The -parent hub might have been named by the root hub. Once again, the -generation of a persistent name for a specific USB flash disk that -happens to be plugged into any particular USB port will be handled by -the host Operating System, and is not the focus of this naming scheme. -The addressable naming scheme is attempting to determine the -bus-relative location, and not the particular peripheral that is -attached to that location/port. - -## Procedural flow - The intention of the enumeration API is to enable -the environment to both build and maintain its "device tree", which it -uses to track the status and availability of hardware. The enumeration -API enables initial discovery of hardware devices, as well as dynamic -discovery and removal of devices from the tree as they appear and -disappear. - -The environment should begin an enumeration sequence by calling -`seL4drv_mgmt_enumerate_get_num_children()` on the target device -instance, in order to ask the driver to tell it how many child devices -it **currently** has. The parent driver shall report **all** such -child devices, regardless of whether or not they are powered on. All -devices which are operationally viable and functional should be reported -to the environment. By implication, faulty or malfunctioning devices, if -they can be recognized as such (e.g., if the firmware informs the driver -that a device is faulty) should be omitted. - -After that, the environment should call -`seL4drv_mgmt_enumerate_children()` to actually get information on all -the target device instance's children. The environment shall pass to -this function a block of memory that is suitably sized to enable the -driver to fill out the childrens' information. Please see the -description of `seL4drv_mgmt_enumerate_get_num_children()` in its -section below to understand how to determine how much memory to allocate -when requesting child device information. - -The driver will then fill out this information for each child device, -and return the information to the environment. - -## Hotplug device enumeration - The API supports hotplug device -enumeration through the means of a "subscription" function. The driver -does not initiate a notification to the environment. Rather, the -environment posts an indication of interest (subscription notification), -along with an asynchronous context preserving cookie. The driver shall -keep this context cookie until a hotplug event occurs (whether the -addition or removal of a device), and at such a time, it shall generate -the asynchronous callback that completes the asynchronous roundtrip for -the "subscription" invocation. - -When the environment finally gets such a callback, it shall simply -refresh its information about the children of the target device, by once -again calling `seL4drv_mgmt_enumerate_get_num_children()`, and doing -a re-run of `seL4drv_mgmt_enumerate_children()`. The environment can -then compare the **Child IDs** of the newly returned list of devices -with those that it previously had in its device tree, and perform an -update of its device tree. - -When the driver completes the asynchronous roundtrip, it shall return -the same memory that was originally passed to it by the environment. The -environment is then free to either re-subscribe to such notifications by -calling `seL4drv_mgmt_enumerate_hotplug_subscribe_ind()` again, or to -choose to indicate that it is no longer interested in subscribing to -such notifications by not calling it again. - -## API - - -### seL4drv_mgmt_enumerate_get_num_children(): Sync - This -function allows the environment to know how much memory it should -allocate for its subsequent calls to -`seL4drv_mgmt_enumerate_children()`. - -There are two values returned by this function: - -1. The number of child devices that the driver instance is - aware of. *Let this value be N_children*. -2. The number of attributes required to describe each child device. - *Let this value be N_attrs_per_child*. - -The environment is expected to allocate memory equal to -`N_attrs_per_child * sizeof(seL4drv_child_attribute_t)` for each -child device. - -If `seL4drv_mgmt_enumerate_get_num_children()` reports that there are -multiple child devices, the environment is expected to allocate memory -equal to -`N_attrs_per_child * sizeof(seL4drv_child_attribute_t) * N_children`. - -This amount of memory shall then be passed to -`seL4drv_mgmt_enumerate_children()`. - -### seL4drv_mgmt_enumerate_children(): Sync - This function shall -cause the driver to return a list of child devices and their attributes, -as well as Child IDs for each of the children, according to the its -discretion, deferring to the constraints outlined above. - -### seL4drv_mgmt_enumerate_hotplug_subscribe(): Async - This -function shall transfer to the driver a block of memory which shall be -kept by the driver until a hotplug event occurs. When such an event -occurs, the driver shall complete the asynchronous roundtrip by calling -back to the environment, returning the memory to the environment in so -doing. - -### seL4drv_mgmt_identify_device(): Sync - This function shall take -a list of attributes that describe a device, and return an unsigned -integer which states whether or not the driver can handle the device -that is described by those attributes. - -If the driver determines that the passed attributes do not describe a -device that it can manage, the driver **shall** return integer `0` -(zero). If the driver determines that the passed attributes describe a -device that it is equipped to handle, it **shall** return a positive -integer `1`. - -*It is recommended that drivers which return a value greater than `0` -should return `1` for now, since in the future, significance will be -ascribed to the values returned. At present, there is no significance -attached to the particular value returned, but for future compatibility -since values above `1` will carry significance, drivers must return `1` for -now.* diff --git a/projects/driver_framework/DriverManagement.html b/projects/driver_framework/DriverManagement.html new file mode 100644 index 00000000000..824f410e61c --- /dev/null +++ b/projects/driver_framework/DriverManagement.html @@ -0,0 +1,687 @@ + + + + + + + Power management commands for the seL4 Driver API | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Power management commands for the seL4 Driver API

+ +

Constants

+
/* Driver power states supported by the API.
+ * These are used by both seL4drv_mgmt_power()
+ * and seL4drv_mgmt_power_features().
+ */
+#define SEL4DRV_MGMT_POWER_BOOT       (1<<0)
+#define SEL4DRV_MGMT_POWER_WAKEUP     (1<<1)
+#define SEL4DRV_MGMT_POWER_SLEEP      (1<<2)
+#define SEL4DRV_MGMT_POWER_DEEP_SLEEP (1<<3)
+#define SEL4DRV_MGMT_POWER_SHUTDOWN   (1<<4)
+#define SEL4DRV_MGMT_POWER_KILL       (1<<5)
+
+ +

Functions

+
void seL4drv_mgmt_critical_event_subscription_ind();
+void seL4drv_mgmt_power();
+void seL4drv_mgmt_power_features(uint32_t *features_bitmap);
+void seL4drv_mgmt_enumerate_children();
+
+ +

Power state specifications

+ +
    +
  • SEL4DRV_MGMT_POWER_BOOT: Support for this power management + command is required of all drivers. This is actually the global + entry point for a driver, and it will be called only once during + a particular device instance’s lifetime. After the driver + returns from this function call, the environment will assume + that the device has been initialized and is ready to + accept requests.
    • +
  • SEL4DRV_MGMT_POWER_WAKEUP: Support for this power management + command is required of all drivers which support the SLEEP or + DEEP_SLEEP commands. Instructs the driver to resume operation + after a SLEEP or DEEP_SLEEP command. The driver is expected to + do any necessary re-initialization of the hardware to get the + driver back into an operational state. If there were + asynchronous requests outstanding before the device was put into + a low-power mode, the driver should re-trigger and resume the + normal processing of such requests.
    • +
  • SEL4DRV_MGMT_POWER_SLEEP: Indicates to the driver that the + device is about to be placed into a light sleep state. In such a + state, the caches of its underlying and dependent hardware are + guaranteed not to be flushed, and there will be no need to + reinitialize the buses after wakeup. If the device does not + support such a light sleep mode, the device shall return an + error code.
    • +
  • SEL4DRV_MGMT_POWER_DEEP_SLEEP: Indicates to the driver that + the environment would like to place the device into a sleep + state in which there is no guarantee that hardware caches and + buffers will be preserved. Furthermore, there is no guarantee + that bus configuration will hold across this transition. The + driver shall cleanly commit the effect of all current + operations, and place any unsatisfied asynchronous requests on + hold, before putting the device into a state that is compatible + with this sleep state.
    • +
  • SEL4DRV_MGMT_POWER_SHUTDOWN: Support for this power + management command is required of all drivers. Indicates that + the device should be placed into a state in which it would be + safe to cut off power to the device. Such a state should at + least guarantee that all clients’ data is quickly cleaned out to + permanent storage, and that all effects requested by clients + are committed. If it is possible to satisfy any outstanding + asynchronous requests the driver should commit to completing + them, but it should reject all future requests from that + point onward.
    • +
  • SEL4DRV_MGMT_POWER_KILL: Support for this power management + command is required of all drivers. Indicates that the + environment wants to kill the device, NOW. Any outstanding + asynchronous requests should be canceled and the driver should + then place itself into a state that is compatible with the + SEL4DRV_MGMT_POWER_SHUTDOWN command.
    • +
+ +

API

+ +

seL4drv_mgmt_critical_event_subscription_ind(): Async

+

This +function enables the environment to call into the driver, and give it an +asynchronous context block which it should hold on to. If at any point +the driver encounters a situation which requires it to ask the +environment to shut it down, it can asynchronously callback into the +environment to make such a request.

+ +

The reason for this function is to enable the driver to report to the +environment when it has found itself in an invalid operational state +which it cannot recover from. This is not a necessary function to +implement, and it is likely to be a blank function for most +implementations.

+ +

seL4drv_mgmt_power(): Async

+

This operation is called by the +environment to place the device instance into one of the power states +outlined above. It is important to note that SEL4DRV_MGMT_POWER_BOOT +is actually just a global entry point into the driver.

+ +

When it comes to placing devices into low power states, the environment +must understand that it is not the responsibility of the driver to +communicate the power management request to its children. If the +environment would like to place an entire hardware bus in a low-power +mode, then the environment must walk its own internal device tree, and +for each descendant of the target bus, it must manually ask that +descendent to enter a power state that is compatible with the power +state it wishes to place the bus into. That is, parent devices are not +responsible for recursing downward and calling their children to +instruct them to enter power states on behalf of the environment.

+ +

The same applies for waking devices up from power states. If the +environment wishes to wake a particular child device, it must manually +ensure that all of that device’s parents are in a suitable power state +to enable operation.

+ +

seL4drv_mgmt_power_features(): Sync

+

This function returns a +bitmap of the supported driver power states (See #constants). +All drivers are required to support at minimum, the following states:

+
    +
  • SEL4DRV_MGMT_POWER_BOOT
    • +
  • SEL4DRV_MGMT_POWER_SHUTDOWN
    • +
  • SEL4DRV_MGMT_POWER_KILL
    • +
+ +

If any of these is not supported by the driver, the environment is free +to respond in an implementation specific manner, including refusing to +load the driver.

+ +

The driver is only required to support the SEL4DRV_MGMT_POWER_WAKEUP +command if either the SEL4DRV_MGMT_POWER_SLEEP or +SEL4DRV_MGMT_POWER_DEEP_SLEEP command is supported. If either the +SLEEP or DEEP_SLEEP command is supported and there is no support for +the SEL4DRV_MGMT_POWER_WAKEUP command, the environment should assume +that the SLEEP or DEEP_SLEEP operations are not adequately supported.

+ +

Child enumeration

+

See the main article:

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/driver_framework/DriverManagement.md b/projects/driver_framework/DriverManagement.md deleted file mode 100644 index 776e969cdd7..00000000000 --- a/projects/driver_framework/DriverManagement.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -archive: true -redirect_from: - - /seL4DriverAPI/DriverManagement -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Power management commands for the seL4 Driver API - - -## Constants -```c -/* Driver power states supported by the API. - * These are used by both seL4drv_mgmt_power() - * and seL4drv_mgmt_power_features(). - */ -#define SEL4DRV_MGMT_POWER_BOOT (1<<0) -#define SEL4DRV_MGMT_POWER_WAKEUP (1<<1) -#define SEL4DRV_MGMT_POWER_SLEEP (1<<2) -#define SEL4DRV_MGMT_POWER_DEEP_SLEEP (1<<3) -#define SEL4DRV_MGMT_POWER_SHUTDOWN (1<<4) -#define SEL4DRV_MGMT_POWER_KILL (1<<5) -``` - -## Functions -```c -void seL4drv_mgmt_critical_event_subscription_ind(); -void seL4drv_mgmt_power(); -void seL4drv_mgmt_power_features(uint32_t *features_bitmap); -void seL4drv_mgmt_enumerate_children(); -``` - -## Power state specifications - - -- SEL4DRV_MGMT_POWER_BOOT: Support for this power management - command is required of all drivers. This is actually the global - entry point for a driver, and it will be called only once during - a particular device instance's lifetime. After the driver - returns from this function call, the environment will assume - that the device has been initialized and is ready to - accept requests. -- SEL4DRV_MGMT_POWER_WAKEUP: Support for this power management - command is required of all drivers which support the SLEEP or - DEEP_SLEEP commands. Instructs the driver to resume operation - after a SLEEP or DEEP_SLEEP command. The driver is expected to - do any necessary re-initialization of the hardware to get the - driver back into an operational state. If there were - asynchronous requests outstanding before the device was put into - a low-power mode, the driver should re-trigger and resume the - normal processing of such requests. -- SEL4DRV_MGMT_POWER_SLEEP: Indicates to the driver that the - device is about to be placed into a light sleep state. In such a - state, the caches of its underlying and dependent hardware are - guaranteed not to be flushed, and there will be no need to - reinitialize the buses after wakeup. If the device does not - support such a light sleep mode, the device shall return an - error code. -- SEL4DRV_MGMT_POWER_DEEP_SLEEP: Indicates to the driver that - the environment would like to place the device into a sleep - state in which there is no guarantee that hardware caches and - buffers will be preserved. Furthermore, there is no guarantee - that bus configuration will hold across this transition. The - driver shall cleanly commit the effect of all current - operations, and place any unsatisfied asynchronous requests on - hold, before putting the device into a state that is compatible - with this sleep state. -- SEL4DRV_MGMT_POWER_SHUTDOWN: Support for this power - management command is required of all drivers. Indicates that - the device should be placed into a state in which it would be - safe to cut off power to the device. Such a state should at - least guarantee that all clients' data is quickly cleaned out to - permanent storage, and that all effects requested by clients - are committed. If it is possible to satisfy any outstanding - asynchronous requests the driver should commit to completing - them, but it should reject all future requests from that - point onward. -- SEL4DRV_MGMT_POWER_KILL: Support for this power management - command is required of all drivers. Indicates that the - environment wants to kill the device, NOW. Any outstanding - asynchronous requests should be canceled and the driver should - then place itself into a state that is compatible with the - SEL4DRV_MGMT_POWER_SHUTDOWN command. - -## API - - -### seL4drv_mgmt_critical_event_subscription_ind(): Async - This -function enables the environment to call into the driver, and give it an -asynchronous context block which it should hold on to. If at any point -the driver encounters a situation which requires it to ask the -environment to shut it down, it can asynchronously callback into the -environment to make such a request. - -The reason for this function is to enable the driver to report to the -environment when it has found itself in an invalid operational state -which it cannot recover from. This is not a necessary function to -implement, and it is likely to be a blank function for most -implementations. - -### seL4drv_mgmt_power(): Async - This operation is called by the -environment to place the device instance into one of the power states -outlined above. It is important to note that SEL4DRV_MGMT_POWER_BOOT -is actually just a global entry point into the driver. - -When it comes to placing devices into low power states, the environment -must understand that it is not the responsibility of the driver to -communicate the power management request to its children. If the -environment would like to place an entire hardware bus in a low-power -mode, then the environment must walk its own internal device tree, and -for each descendant of the target bus, it must manually ask that -descendent to enter a power state that is compatible with the power -state it wishes to place the bus into. That is, parent devices are not -responsible for recursing downward and calling their children to -instruct them to enter power states on behalf of the environment. - -The same applies for waking devices up from power states. If the -environment wishes to wake a particular child device, it must manually -ensure that all of that device's parents are in a suitable power state -to enable operation. - -### seL4drv_mgmt_power_features(): Sync - This function returns a -bitmap of the supported driver power states (See [#constants](#constants)). -All drivers are required to support at minimum, the following states: -- SEL4DRV_MGMT_POWER_BOOT -- SEL4DRV_MGMT_POWER_SHUTDOWN -- SEL4DRV_MGMT_POWER_KILL - -If any of these is not supported by the driver, the environment is free -to respond in an implementation specific manner, including refusing to -load the driver. - -The driver is only required to support the SEL4DRV_MGMT_POWER_WAKEUP -command if either the SEL4DRV_MGMT_POWER_SLEEP or -SEL4DRV_MGMT_POWER_DEEP_SLEEP command is supported. If either the -SLEEP or DEEP_SLEEP command is supported and there is no support for -the SEL4DRV_MGMT_POWER_WAKEUP command, the environment should assume -that the SLEEP or DEEP_SLEEP operations are not adequately supported. - -## Child enumeration - See the main article: diff --git a/projects/elfloader/index.html b/projects/elfloader/index.html new file mode 100644 index 00000000000..c4bdba2853b --- /dev/null +++ b/projects/elfloader/index.html @@ -0,0 +1,696 @@ + + + + + + + Elfloader | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + +

Elfloader

+ +

The elfloader is responsible for preparing the hardware for seL4 on ARM +and RISC-V. It loads the kernel and user image from an embedded CPIO archive, +initialises secondary cores (if SMP is enabled), and sets up an initial set of page +tables for the kernel.

+ +

ARM

+ +

On ARM platforms, the elfloader supports being booted in four ways: as a binary image, +as a u-boot uImage, as an ELF file, and as an EFI executable. Each of these methods differs slightly. +It can also provide seL4 with a DTB - either from the bootloader or included in the embedded CPIO archive.

+ +
    +
  1. (EFI only) Elfloader is entered at _gnuefi_start entry point.
    2. +
  2. (EFI only) Elfloader relocates itself
    3. +
  3. Elfloader _start is called. This is in arch-arm/<arch_bitness>/crt0.S.
    4. +
  4. Elfloader initialises the driver framework, which enables UART/printf.
    5. +
  5. Elfloader loads the kernel, user image, and DTB, determining where the kernel needs to be mapped in memory.
    6. +
  6. If the kernel window overlaps the elfloader’s code: +
      +
    • (AArch32 EFI only) the elfloader relocates itself. + See relocate_below_kernel for a detailed explanation of the relocation logic.
      • +
    • (Other platforms) the elfloader aborts.
      • +
    +
    7. +
  7. The elfloader resumes booting. If it relocated itself, it will re-initialise the driver model.
    8. +
  8. If the elfloader is in HYP mode but seL4 is not configured to support HYP, it will leave HYP mode.
    9. +
  9. The elfloader sets up the initial page tables for the kernel (see init_hyp_boot_vspace or init_boot_vspace).
    10. +
  10. If SMP is enabled, the elfloader boots all secondary cores.
    11. +
  11. The elfloader enables the MMU.
    12. +
  12. The elfloader launches seL4, passing information about the user image and the DTB.
    13. +
+ +

Binary

+ +

The elfloader expects to be executed with a base address as generated by the shoehorn utility. +You can determine the correct address for a given image by running

+
aarch64-linux-gnu-objdump -t elfloader/elfloader | grep _text
+
+

from the kernel build directory. The first field in the output contains the base address.

+ +

On aarch64, the elfloader will try and move itself to the right address, however, this will fail +if the load address and the correct address are too close, as the relocation code will be overwritten.

+ +

It is also possible to override shoehorn and hardcode a load address by setting IMAGE_START_ADDR in CMake.

+ +

U-Boot

+ +

The elfloader can be booted according to the Linux kernel’s booting convention for ARM/ARM64. +The DTB, if provided, will be passed to seL4 (which will then pass it to the root task).

+ +

ELF

+ +

The elfloader supports being executed as an ELF image (via bootelf in U-Boot or similar).

+ +

EFI

+ +

The elfloader integrates EFI support based on the gnu-efi project. It will relocate itself as appropriate, +and supports loading a DTB from the EFI implementation.

+ +

RISC-V

+ +

The elfloader on RISC-V basically follows the ARM platforms. However, due to the +lack of available platforms, only two ways are currently supported actively: +building it as ELF file or binary image. In both cases the platform must provide +a SBI implementation, which will be +used by the elfloader for the log output channel and the multicore boot. The +seL4 build system allows building OpenSBI +with the elfloader as payload. The bbl +Support has been dropped, because it is superseded by OpenSBI.

+ +

Driver framework

+ +

The elfloader provides a driver framework to reduce code duplication between platforms. +Currently the driver framework is only used for UART output, however it is designed with extensibility in mind. +In practice, this is currently only used on ARM, as RISC-V uses SBI for UART, and SBI has no device tree entries. +However, in the future it may become useful on RISC-V.

+ +

The driver framework uses a header file containing a list of devices generated by the hardware_gen.py utility +included in seL4. Currently, this header only includes the UART specified by the stdout-path property in the DTB. +Each device in the list has a compatible string (compat), and a list of addresses (region_bases[]) which correspond to the regions specified +by the reg property in the DTB.

+ +

Each driver in the elfloader has a list of compatible strings, matching those found in the device tree. +For instance, the 8250 UART driver, used on Tegra and TI platforms has the following:

+ +
static const struct dtb_match_table uart_8250_matches[] = {
+    { .compatible = "nvidia,tegra20-uart" },
+    { .compatible = "ti,omap3-uart" },
+    { .compatible = "snps,dw-apb-uart" },
+    { .compatible = NULL /* sentinel */ },
+};
+
+ +

Each driver also has a ‘type’. Currently the only type supported is DRIVER_UART. The type +indicates the type of struct that is found in the ops pointer of each driver object, +and provides type-specific functionality. +(For instance, UART drivers have a elfloader_uart_ops struct which contains a putc function). +Finally, drivers also provide an init function, which is called when the driver is matched with a device, +and can be used to perform device-specific setup (e.g. setting the device as the UART output).

+ +

Finally, each driver has a struct elfloader_driver and a corresponding ELFLOADER_DRIVER statement. +Taking the 8250 UART driver as an example again:

+ +
static const struct elfloader_driver uart_8250 = {
+    .match_table = uart_8250_matches,
+    .type = DRIVER_UART,
+    .init = &uart_8250_init,
+    .ops = &uart_8250_ops,
+};
+
+ELFLOADER_DRIVER(uart_8250);
+
+ +

UART

+ +

The driver framework provides a “default” (__attribute__((weak))) implementation of plat_console_putchar, which calls +the putc function for the elfloader device provided to uart_set_out - discarding all characters +that are given to it before uart_set_out is called. This can be overridden if you do not wish to use +the driver framework (e.g. for very early debugging).

+ +

Porting the elfloader

+ +

To ARM

+ +

Once a kernel port has been started (and a DTB provided), porting the elfloader to a platform is reasonably +straightforward.

+ +

Most platform-specific information is extracted from a DTB, including available physical memory ranges. If the +platform uses a UART compatible with another platform, even the UART will work out of the box. In other cases, +it might be necessary to add a new dtb_match_table entry to an existing driver, or add a new driver +(which is fairly trivial - only the match_table and putchar functions from an existing driver would +need to be changed).

+ +

An appropriate image type needs to be selected. By default ElfloaderImage is set to elf, however, +various platform-specific overrides exist and can be found in ApplyData61ElfLoaderSettings in this repo, at +cmake-tool/helpers/application_settings.cmake.

+ +

To RISC-V

+ +

TODO - it seems there’s not actually that much that needs to be done on the elfloader side.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/elfloader/index.md b/projects/elfloader/index.md deleted file mode 100644 index 1705b03cfab..00000000000 --- a/projects/elfloader/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Elfloader -project: elfloader -repo: 'seL4/sel4_tools' -include_file: 'elfloader-tool/README.md' -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -{% include include_github_repo_markdown.md %} diff --git a/projects/hardware_hacks/index.html b/projects/hardware_hacks/index.html new file mode 100644 index 00000000000..3610e40ed48 --- /dev/null +++ b/projects/hardware_hacks/index.html @@ -0,0 +1,587 @@ + + + + + + + Hardware Hacks | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Hardware Hacks

+

We have built various bits and pieces to enable easier use of our +hardware. Some of these are documented here in case others might find +them useful. The issue is that we want our embedded hardware to be +shareable between multiple users and an automated test harness. The +manufacturers of most of our gadgets assume we’re going to be using a +TTL to USB serial converter and Fastboot; this doesn’t scale, as when +you have several plugged in, the enumeration order is not fixed, so +there’s no way to tell which of many gadgets you are talking to.

+ +

The general approach we take is:

+ +
    +
  1. As far as possible, boot everything on power-up via DHCP and +TFTP
    2. +
  2. Connect a debug serial port via a Level Converter to a Lantronix +serial concentrator. An ETS16P for example provides 16 +RS422/RS232 ports, and can be obtained for less than $100 +on eBay.
    3. +
  3. Connect power for each device via a network-controllable switch. +For most of our gadgets we’re using a cubieTruck and an pair of +arduino-connected 8-way relay boards, hooked up to an old AT +power supply top give 5V or 12V depending on each +board’s requirements. It doesn’t matter much provided that via +the network, one can turn on, turn off, and query the power +state of a particular port.
    4. +
+ +

We use a set of MachineQueue scripts to arbitrate access to the various +gadgets.

+ +

A few machines already have a base-management-controller; if they have +it we use it.

+ +

One machine, the CMA34D, needed some extras; they are documented on +CMA34DBMC.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/hardware_hacks/index.md b/projects/hardware_hacks/index.md deleted file mode 100644 index 6170456afe5..00000000000 --- a/projects/hardware_hacks/index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -archive: true -redirect_from: - - /HardwareHacks -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Hardware Hacks -We have built various bits and pieces to enable easier use of our -hardware. Some of these are documented here in case others might find -them useful. The issue is that we want our embedded hardware to be -shareable between multiple users and an automated test harness. The -manufacturers of most of our gadgets assume we're going to be using a -TTL to USB serial converter and Fastboot; this doesn't scale, as when -you have several plugged in, the enumeration order is not fixed, so -there's no way to tell which of many gadgets you are talking to. - -The general approach we take is: - -1. As far as possible, boot everything on power-up via DHCP and - TFTP -2. Connect a debug serial port via a [Level Converter](level-converter) to a Lantronix - serial concentrator. An ETS16P for example provides 16 - RS422/RS232 ports, and can be obtained for less than $100 - on eBay. -3. Connect power for each device via a network-controllable switch. - For most of our gadgets we're using a cubieTruck and an pair of - arduino-connected 8-way relay boards, hooked up to an old AT - power supply top give 5V or 12V depending on each - board's requirements. It doesn't matter much provided that via - the network, one can turn on, turn off, and query the power - state of a particular port. - -We use a set of MachineQueue scripts to arbitrate access to the various -gadgets. - -A few machines already have a base-management-controller; if they have -it we use it. - -One machine, the CMA34D, needed some extras; they are documented on -[CMA34DBMC](../../CMA34DBMC/). diff --git a/projects/hardware_hacks/level-converter/index.html b/projects/hardware_hacks/level-converter/index.html new file mode 100644 index 00000000000..3acb99d8307 --- /dev/null +++ b/projects/hardware_hacks/level-converter/index.html @@ -0,0 +1,569 @@ + + + + + + + Level Converter | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+
+

This page is archived and is no longer receiving updates.

+

It remains here because some of the content may still be useful.

+
+ +
+

Level Converter

+ +

Most of our gadgets have serial ports that work at 1V8 or 3V3 +single-ended; our serial concentrator expects true RS422 or RS232, at +±12 to ±25V. So we need to provide a level converter/driver to convert +between the low level single-ended signals on the boards, and the +high-level differential voltages for transmission to the serial +concentrator.

+ +

We used the suggested circuit in the +Manufacturer’s Datasheet, laid out on a piece of perfboard.

+ +

Image of Level convertor circuit on prototype board

+ +

This picture shows one wired to convert a single channel; because most +of our gadgets need only a three-wire interface, you can convert two +channels with one chip. The converter is powered from the gadget: +provide 1V8 or 3V3 depending on the signalling level.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/hardware_hacks/level-converter/index.md b/projects/hardware_hacks/level-converter/index.md deleted file mode 100644 index f401ea5de33..00000000000 --- a/projects/hardware_hacks/level-converter/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -archive: true -redirect_from: - - /LevelConverter -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Level Converter - -Most of our gadgets have serial ports that work at 1V8 or 3V3 -single-ended; our serial concentrator expects true RS422 or RS232, at -±12 to ±25V. So we need to provide a level converter/driver to convert -between the low level single-ended signals on the boards, and the -high-level differential voltages for transmission to the serial -concentrator. - -We used the suggested circuit in the -[Manufacturer's Datasheet](http://datasheets.maximintegrated.com/en/ds/MAX218.pdf), laid out on a piece of perfboard. - -Image of Level convertor circuit on prototype board - -

This picture shows one wired to convert a single channel; because most -of our gadgets need only a three-wire interface, you can convert two -channels with one chip. The converter is powered from the gadget: -provide 1V8 or 3V3 depending on the signalling level.

diff --git a/projects/index.html b/projects/index.html index 7d912ec0b9f..65bed999cda 100644 --- a/projects/index.html +++ b/projects/index.html @@ -1,7 +1,11 @@ ---- -redirect_to: / -layout: default -title: Projects -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/l4v/index.html b/projects/l4v/index.html index 7f917922965..1247e6e8c6f 100644 --- a/projects/l4v/index.html +++ b/projects/l4v/index.html @@ -1,5 +1,11 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Verification/ ---- + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/microkit/index.html b/projects/microkit/index.html new file mode 100644 index 00000000000..407c356f2b6 --- /dev/null +++ b/projects/microkit/index.html @@ -0,0 +1,698 @@ + + + + + + + The seL4 Microkit | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

The seL4 Microkit

+ +

The seL4 Microkit is an operating system framework on top of seL4. It provides a +small set of simple abstractions that ease the design and implementation of +statically structured systems on seL4, leveraging the kernel’s benefits of +security and performance.

+ +

The Microkit is distributed as an SDK that integrates with the build system of +your choice, significantly reducing the barrier to entry for new users of seL4.

+ +
+ +
+ +
+ +
+ +
+ +
+ +
+

+ Tutorial +

+
+ Learn how to use Microkit and its concepts to make a system. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ Manual +

+
+ User's manual for the Microkit SDK. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ Releases +

+
+ SDK downloads and release notes. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ Sources +

+
+ If you are planning to make contributions to the Microkit, this is + where to start. +
+
+ Learn more + + +
+
+
+ + +
+ +

The seL4 Microkit is part of the repositories managed by the seL4 Foundation. It +is currently mainly maintained and developed by the Trustworthy Systems research +group at UNSW. See also the Microkit project page there.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/microkit/index.md b/projects/microkit/index.md deleted file mode 100644 index 3a16de197fe..00000000000 --- a/projects/microkit/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# The seL4 Microkit - -The seL4 Microkit is an operating system framework on top of seL4. It provides a -small set of simple abstractions that ease the design and implementation of -statically structured systems on seL4, leveraging the kernel’s benefits of -security and performance. - -The Microkit is distributed as an SDK that integrates with the build system of -your choice, significantly reducing the barrier to entry for new users of seL4. - -
- - {% include card.html - icon="arrow-right-end-on-rectangle" - title="Tutorial" - body="Learn how to use Microkit and its concepts to make a system." - link="/projects/microkit/tutorial/welcome.html" - %} - - {% include card.html - icon="book-open" - title="Manual" - body="User's manual for the Microkit SDK." - link="/projects/microkit/manual/latest/" - %} - - {% include card.html - icon="arrow-down-tray" - title="Releases" - body="SDK downloads and release notes." - link="/releases/microkit.html" - %} - - {% include card.html - icon="other/github" - title="Sources" - body="If you are planning to make contributions to the Microkit, this is - where to start." - link="https://github.com/seL4/microkit/" - %} - -
- - -The seL4 Microkit is part of the repositories managed by the seL4 Foundation. It -is currently mainly maintained and developed by the Trustworthy Systems research -group at UNSW. See also the [Microkit project page] there. - - -[Microkit project page]: https://trustworthy.systems/projects/microkit diff --git a/projects/microkit/manual/2.0.1/index.html b/projects/microkit/manual/2.0.1/index.html new file mode 100644 index 00000000000..18299689559 --- /dev/null +++ b/projects/microkit/manual/2.0.1/index.html @@ -0,0 +1,2056 @@ + + + + + + + Microkit User Manual (v2.0.1) | seL4 docs + + + + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit User Manual (v2.0.1)

+ +

This is a web version of the manual, you can find a PDF here as well as in the +SDK at doc/microkit_user_manual.pdf.

+ +

Introduction

+ +

The seL4 Microkit is a small and simple operating system (OS) built on the seL4 microkernel. +Microkit is designed for building system with a static architecture. +A static architecture is one where system resources are assigned up-front at system initialisation time.

+ +

Purpose

+ +

The Microkit is intended to:

+ +
    +
  • provide a small and simple OS for a wide range of IoT, cyberphysical and other embedded use cases;
    • +
  • provide a reasonable degree of application portability appropriate for the targeted use cases;
    • +
  • make seL4-based systems easy to develop and deploy within the target areas;
    • +
  • leverage seL4’s strong isolation properties to support a near-minimal trusted computing base (TCB);
    • +
  • retain seL4’s trademark performance for systems built with it;
    • +
  • be, in principle, amenable to formal analysis of system safety and security properties (although such analysis is beyond the initial scope).
    • +
+ +

Overview

+ +

A Microkit system is built from a set of individual programs that are isolated from each other, and the system, in protection domains. +Protection domains can interact by calling protected procedures or sending notifications.

+ +

Microkit is distributed as a software development kit (SDK). +The SDK includes the tools, libraries and binaries required to build a Microkit system. +The Microkit source is also available which allows you to customize or extend Microkit and produce your own SDK.

+ +

To build a Microkit system you will write some programs that use libmicrokit. +Microkit programs are a little different to a typical process on a Linux-like operating system. +Rather than a single main entry point, a program has four distinct entry points: init, notified and, potentially, protected, fault.

+ +

The individual programs are combined to produce a single bootable system image. +The format of the image is suitable for loading by the target board’s bootloader. +The Microkit tool, which is provided as part of the SDK, is used to generate the system image.

+ +

The Microkit tool takes a system description as input. +The system description is an XML file that specifies all the objects that make up the system.

+ +

Note: Microkit does not impose any specific build system; you are free to choose the build system that works best for you.

+ +

Document Structure

+ +

The Concepts chapter describes the various concepts that make up Microkit. +It is recommended that you familiarise yourself with these concepts before trying to build a system.

+ +

The SDK chapter describes the software development kit, including its components and system requirements for use.

+ +

The Microkit tool chapter describes the host system tool used for generating a system image from the system description and user-programs.

+ +

The libmicrokit chapter describes the interfaces to the Microkit library.

+ +

The System Description File chapter describes the format of the system description XML file.

+ +

The Board Support Packages chapter describes each of the board support packages included in the SDK.

+ +

The Rationale chapter documents the rationale for some of the key design choices of in Microkit.

+ +

The Internals chapter documents some of the internal details for how Microkit works.

+ +

Concepts

+ +

This chapter describes the key concepts provided by Microkit.

+ +

As with any set of concepts there are words that take on special meanings. +This document attempts to clearly describe all of these terms, however as the concepts are inter-related it is sometimes necessary to use a term prior to its formal introduction.

+ + + +

System

+ +

At the most basic level Microkit provides the platform for running a system on a specific board. +As a user of Microkit you use the platform to create a software system that implements your use case. +The system is described in a declarative configuration file, and the Microkit tool takes this system description as an input and produces an appropriate system image that can be loaded on the target board.

+ +

The key elements that make up a system are protection domains, memory regions and channels.

+ +

Protection Domains

+ +

A protection domain (PD) is the fundamental runtime abstraction in Microkit. +It is analogous, but very different in detail, to a process on a UNIX system.

+ +

A PD provides a thread of control that executes within a fixed virtual address space. +The isolation provided by the virtual address space is enforced by the underlying hardware MMU.

+ +

The virtual address space for a PD has mappings for the PD’s program image along with any memory regions that the PD can access. +The program image is an ELF file containing the code and data which implements the isolated component.

+ +

Microkit supports a maximum of 63 protection domains.

+ +

Entry points

+ +

Although a protection domain is somewhat analogous to a process, it has a considerably different program structure and life-cycle. +A process on a typical operating system will have a main function which is invoked by the system when the process is created. +When the main function returns the process is destroyed.

+ +

By comparison a protection domain has up to four entry points:

+ +
    +
  • init, notified which are required.
    • +
  • protected which is optional.
    • +
  • fault which is required if the PD has children.
    • +
+ +

When a Microkit system is booted, all PDs in the system execute the init entry point.

+ +

A PD will not execute any other entry point until init has finished.

+ +

If a PD is currently executing an entry point, it will not execute any other entry point +until the current entry point has finished.

+ +

The notified entry point will be invoked whenever the protection domain receives a notification on a channel. +The protected entry point is invoked when a PD’s protected procedure is called by another PD. +A PD does not have to provide a protected procedure, therefore the protected entry point is optional.

+ +

The fault entry point is invoked when a PD that is a child of another PD causes a fault. +A PD does not have to have child PDs, therefore the fault entry point is only required for a parent PD.

+ +

These entry points are described in more detail in subsequent sections.

+ +

Note: The processing of init entry points is not synchronised across protection domains. +Specifically, it is possible for a high priority PD’s notified or protected entry point to be called prior to the completion of a low priority PD’s init entry point.

+ +

The overall computational model for a Microkit system is a set of isolated components reacting to incoming events.

+ +

Scheduling

+ +

The PD has a number of scheduling attributes that are configured in the system description:

+ +
    +
  • priority (0 – 254)
    • +
  • period (microseconds)
    • +
  • budget (microseconds)
    • +
  • passive (boolean)
    • +
+ +

The budget and period bound the fraction of CPU time that a PD can consume. +Specifically, the budget specifies the amount of time for which the PD is allowed to execute. +Once the PD has consumed its budget, it is no longer runnable until the budget is replenished; replenishment happens once every period and resets the budget to its initial value. +This means that the maximum fraction of CPU time the PD can consume is $\frac{budget}{period}$.

+ +

The budget cannot be larger than the period. +A budget that equals the period (aka. a “full” budget) behaves like a traditional time slice: After executing for a full period, the PD is preempted and put at the end of the scheduling queue of its priority. In other words, PDs with equal priorities and full budgets are scheduled round-robin with a time slice defined by the period.

+ +

The priority determines which of the runnable PDs to schedule. A PD is runnable if one of its entry points has been invoked and it has budget remaining in the current period. +Runnable PDs of the same priority are scheduled in a round-robin manner.

+ +

Passive determines whether the PD is passive. A passive PD will have its scheduling context revoked after initialisation and then bound instead to the PD’s notification object. This means the PD will be scheduled on receiving a notification, whereby it will run on the notification’s scheduling context. When the PD receives a protected procedure by another PD or a fault caused by a child PD, the passive PD will run on the scheduling context of the callee.

+ +

Virtual Machines

+ +

A virtual machine (VM) is a runtime abstraction for running guest operating systems in Microkit. It is similar +to a protection domain in that it provides a thread of control that executes within an isolated virtual address space.

+ +

The main difference between a VM and a PD is that VMs have a higher privilege level such that they may function as a +guest operations and have their own user-space programs at a separate exception level.

+ +

The virtual machine is always a child of a PD. Exceptions caused by the virtual machine are delivered to the parent PD +through the fault entry point.

+ +

Each virtual machine has a number of ‘virtual CPU’s associated with it. Each virtual CPU (vCPU) that belongs to a +virtual machine has its own thread of execution. A vCPU also has an identifier which is used to know which vCPU caused +the invocation of the fault entry point.

+ +

The parent PD is responsible for starting and managing the virtual machine. Microkit provides the abstractions in +order to manage the virtual machine through seL4 but there is typically a non-trivial amount +of supporting code/infrastructure to properly start and manage a VM.

+ +

To keep the (potentially untrusted) virtual machine isolated from the rest of the system, Microkit enforces that a +protection domain can only ever manage a single virtual machine.

+ +

Memory Regions

+ +

A memory region is a contiguous range of physical memory. +A memory region may have a fixed physical address. +For memory regions without a fixed physical address, the physical address is allocated as part of the build process. +Typically, memory regions with a fixed physical address represent memory-mapped device registers.

+ +

Memory regions that are within main memory are zero-initialised.

+ +

The size of a memory region must be a multiple of a supported page size. +The supported page sizes are architecture dependent. +For example, on AArch64 architectures, Microkit support 4KiB and 2MiB pages. +The page size for a memory region may be specified explicitly in the system description. +If page size is not specified, the smallest supported page size is used.

+ +

Note: The page size also restricts the alignment of the memory region’s physical address. +A fixed physical address must be a multiple of the specified page size.

+ +

A memory region can be mapped into one or more protection domains. +The mapping has a number of attributes, which include:

+ +
    +
  • the virtual address at which the region is mapped in the PD
    • +
  • caching attributes (mostly relevant for device memory)
    • +
  • permissions (read, write and execute)
    • +
+ +

Note: When a memory region is mapped into multiple protection +domains, the attributes used for different mappings may vary.

+ +

Channels

+ +

A channel enables two protection domains to interact using protected procedures or notifications. +Each connects exactly two PDs; there are no multi-party channels.

+ +

When a channel is created between two PDs, a channel identifier is configured for each PD. +The channel identifier is used by the PD to reference the channel. +Each PD can refer to the channel with a different identifier. +For example if PDs A and B are connected by a channel, A may refer to the channel using an identifier of 37 while B may use 42 to refer to the same channel.

+ +

Note: There is no way for a PD to directly refer to another PD in the system. +PDs can only refer to other PDs indirectly if there is a channel between them. +In this case, the channel identifier is effectively a proxy identifier for the other PD. +So, to extend the prior example, A can indirectly refer to B via the channel identifier 37. +Similarly, B can refer to A via the channel identifier 42.

+ +

The system supports a maximum of 63 channels and interrupts per protection domain.

+ +

Protected procedures

+ +

A protection domain may provide a protected procedure (PP) which can be invoked from another protection domain. +Up to 64 words of data may be passed as arguments when calling a protected procedure. +The protected procedure return value may also be up to 64 words.

+ +

When a protection domain calls a protected procedure, the procedure executes within the context of the providing protection domain.

+ +

A protected call is only possible if the callee has strictly higher priority than the caller. +Transitive calls are possible, and as such a PD may call a protected procedure in another PD from a protected entry point. +However the overall call graph between PDs must form a directed, acyclic graph. +It follows that a PD can not call itself, even indirectly. +For example, A calls B calls C is valid (subject to the priority constraint), while A calls B calls A is not valid.

+ +

When a protection domain is called, the protected entry point is invoked. +The control returns to the caller when the protected entry point returns.

+ +

The caller is blocked until the callee returns. +Protected procedures must execute in bounded time. +It is intended that a future version of Microkit will enforce this condition through static analysis. +In the present version the caller must trust the callee to conform.

+ +

In general, PPs are provided by services for use by clients that trust the protection domain to provide that service.

+ +

To call a PP, a PD calls microkit_ppcall passing the channel identifier and a message structure. +A message structure is returned from this function.

+ +

When a PD’s protected procedure is invoked, the protected entry point is invoked with the channel identifier and message structure passed as arguments. +The protected entry point must return a message structure.

+ +

Notifications

+ +

A notification is a (binary) semaphore-like synchronisation mechanism. +For example, a PD can notify another PD to indicate availability of data in a shared memory region if they share a channel.

+ +

To notify another PD, a PD calls microkit_notify, passing the channel identifier. +When a PD receives a notification, the notified entry point is invoked with the appropriate channel identifier passed as an argument.

+ +

Unlike protected procedures, notifications can be sent in either direction on a channel regardless of priority.

+ +

Note: Notifications provide a mechanism for synchronisation between PDs, however this is not a blocking operation. +If a PD notifies another PD, that PD will become scheduled to run (if it is not already), but the current PD does not block. +Of course, if the notified PD has a higher priority than the current PD, then the current PD will be preempted (but not blocked) by the other PD.

+ +

Depending on the scheduling, one PD could notify another multiple times without it being scheduled, resulting +in a single execution of the notified entry point. For example, if PD A notifies PD B three times on the +same channel without PD B ever executing, once PD B is scheduled it would only see one notification and hence +only enter notified once for that channel.

+ +

Interrupts

+ +

Hardware interrupts can be used to notify a protection domain. +The system description specifies if a protection domain receives notifications for any hardware interrupt sources. +Each hardware interrupt is assigned a channel identifier. +In this way the protection domain can distinguish the hardware interrupt from other notifications. +A specific hardware interrupt can only be associated with at most one protection domain. It should be noted that once a +hardware interrupt has been received, it will not be received again until microkit_irq_ack is called. The seL4 kernel +will mask the hardware interrupt until it has been acknowledged.

+ +

Microkit does not provides timers, nor any sleep API. +After initialisation, activity in the system is initiated by an interrupt causing a notified entry point to be invoked. +That notified function may in turn notify or call other protection domains that cause other system activity, but eventually all activity indirectly initiated from that interrupt will complete, at which point the system is inactive again until another interrupt occurs.

+ +

Faults

+ +

Faults such as an invalid memory access or illegal instruction are delivered to the seL4 kernel which then forwards them to +a designated ‘fault handler’. By default, all faults caused by protection domains go to the system fault handler which +simply prints out details about the fault in a debug configuration.

+ +

When a protection domain is a child of another protection domain, the designated fault handler for the child is the parent +protection domain. The same applies for a virtual machine.

+ +

This means that whenever a fault is caused by a child, it will be delivered to the parent PD instead of the system fault +handler via the fault entry point. It is then up to the parent to decide how the fault is handled.

+ +

The default system fault handler (aka the monitor) has the highest priority and so will +execute and handle faults immediately after they occur. For child PDs that have their faults +delivered to another PD, the fault being handled depends on when the parent PD is scheduled.

+ +

SDK

+ +

Microkit is distributed as a software development kit (SDK).

+ +

The SDK includes support for one or more boards. +Three configurations are supported for each board: debug, release, and benchmark. +See the Configurations section for more details.

+ +

The SDK contains:

+ +
    +
  • Microkit user manual (this document)
    • +
  • Microkit tool
    • +
+ +

Additionally, for each supported board configuration the following are provided:

+ +
    +
  • libmicrokit
    • +
  • loader.elf
    • +
  • kernel.elf
    • +
  • monitor.elf
    • +
+ +

There are also examples provided in the example directory.

+ +

The Microkit SDK does not provide, nor require, any specific build system. +The user is free to build their system using whatever build system is deemed most appropriate for their specific use case.

+ +

The Microkit tool should be invoked by the system build process to transform a system description (and any referenced program images) into an image file which can be loaded by the target board’s bootloader.

+ +

The ELF files provided as program images should be standard ELF files and have been linked against the provided libmicrokit.

+ +

Configurations

+ +

Debug

+ +

The debug configuration includes a debug build of the seL4 kernel to allow console debug output using the kernel’s UART driver.

+ +

Release

+ +

The release configuration is a release build of the seL4 kernel and is intended for production builds. The loader, monitor, and +kernel do not perform any serial output.

+ +

Benchmark

+ +

The benchmark configuration uses a build of the seL4 kernel that exports the hardware’s performance monitoring unit (PMU) to PDs. +The kernel also tracks information about CPU utilisation. This benchmark configuration exists due a limitation of the seL4 kernel +and is intended to be removed once RFC-16 is implemented.

+ +

System Requirements

+ +

The Microkit tool requires Linux (x86-64 or AArch64), macOS (x86-64 or AArch64).

+ +

On Linux, the Microkit tool is statically linked and should run on any distribution.

+ +

On macOS, the Microkit tool should run on macOS 10.12 (Sierra) or higher.

+ +

The Microkit tool does not depend on any additional system binaries.

+ +

Microkit Tool

+ +

The Microkit tool is available in bin/microkit.

+ +

The Microkit tool takes as input a system description. +The format of the system description is described in a subsequent chapter.

+ +

Usage:

+ +
microkit [-h] [-o OUTPUT] [-r REPORT] --board [BOARD] --config CONFIG
+         [--search-path [SEARCH_PATH ...]] system
+
+ +

The path to the system description file, board to build the system for, and configuration to build for must be provided.

+ +

The search paths provided tell the tool where to find any program images specified in the system description file.

+ +

In the case of errors, a diagnostic message shall be output to stderr and a non-zero code returned.

+ +

In the case of success, a loadable image file and a report shall be produced. +The output paths for these can be specified by -o and -r respectively. +The default output paths are loader.img and report.txt.

+ +

The loadable image will be a binary that can be loaded by the board’s bootloader.

+ +

The report is a plain text file describing important information about the system. +The report can be useful when debugging potential system problems. +This report does not have a fixed format and may change between versions. +It is not intended to be machine readable.

+ +

Language Support

+ +

There are native APIs for C/C++ and Rust.

+ +

libmicrokit exports a C API and so can be used in any language +that supports C FFI.

+ +

For Rust, native bindings exist but are not included in the SDK itself. They are +available at rust-sel4.

+ +

libmicrokit

+ +

All program images should link against libmicrokit.a.

+ +

The library provides the C runtime for the protection domain, along with interfaces for the Microkit APIs.

+ +

The component must provide the following functions:

+ +
void init(void);
+void notified(microkit_channel ch);
+
+ +

If the protection domain provides a protected procedure it must also implement:

+ +
microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo);
+
+ +

If the protection domain has children it must also implement:

+ +
seL4_Bool fault(microkit_child child, microkit_msginfo msginfo,
+                microkit_msginfo *reply_msginfo);
+
+ +

libmicrokit provides the following functions:

+ +
microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo);
+void microkit_notify(microkit_channel ch);
+microkit_msginfo microkit_msginfo_new(seL4_Word label, seL4_Uint16 count);
+seL4_Word microkit_msginfo_get_label(microkit_msginfo msginfo);
+seL4_Word microkit_msginfo_get_count(microkit_msginfo msginfo);
+void microkit_irq_ack(microkit_channel ch);
+void microkit_deferred_notify(microkit_channel ch);
+void microkit_deferred_irq_ack(microkit_channel ch);
+void microkit_pd_restart(microkit_child pd, seL4_Word entry_point);
+void microkit_pd_stop(microkit_child pd);
+void microkit_mr_set(seL4_Uint8 mr, seL4_Word value);
+seL4_Word microkit_mr_get(seL4_Uint8 mr);
+void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point);
+void microkit_vcpu_stop(microkit_child vcpu);
+void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq,
+                                  seL4_Uint8 priority, seL4_Uint8 group,
+                                  seL4_Uint8 index);
+void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq);
+seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg);
+void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value);
+void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response);
+
+ +

void init(void)

+ +

Every PD must expose an init entry point. +This is called by the system at boot time.

+ +

void notified(microkit_channel ch)

+ +

The notified entry point is called by the system when a PD has received a notification on a channel.

+ +

ch identifies the channel which has been notified (and indirectly the PD that performed the notification).

+ +

Note: ch could identify an interrupt.

+ +

Channel identifiers are specified in the system configuration.

+ +

microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo)

+ +

The protected entry point is optional. +This is invoked when another PD calls microkit_ppcall on a channel shared with the PD.

+ +

The ch argument identifies the channel on which the PP was invoked. +Indirectly this identifies the PD performing the call. +Channel identifiers are specified in the system configuration. +Note: The channel argument is passed by the system and is unforgeable.

+ +

The msginfo argument is the argument passed to the PP and is provided by the calling PD. +The contents of the message is up to a pre-arranged protocol between the PDs. +The message contents are opaque to the system. +Note: The message is copied from the caller.

+ +

The returned microkit_msginfo is the return value of the protected procedure. +As with arguments, this is copied to the caller.

+ +

seL4_Bool fault(microkit_child child, microkit_msginfo msginfo, microkit_msginfo *reply_msginfo)

+ +

The fault entry point being invoked depends on whether the given PD has children. +It is invoked when a child PD or VM causes a fault.

+ +

The child argument identifies the child that caused the fault.

+ +

The msginfo argument is given by the seL4 kernel when a fault occurs and contains information +as to what fault occurred.

+ +

The reply_msginfo argument is given by libmicrokit and can be used to reply to the fault.

+ +

The returned seL4_Bool is whether or not to reply to the fault with the message reply_msginfo. +Returning seL4_True will reply to the fault. Returning seL4_False will not reply to the fault.

+ +

You can use microkit_msginfo_get_label on msginfo to deduce what kind of fault happened +(for example, whether it was a user exception or a virtual memory fault).

+ +

Whether or not you reply to the fault depends on the type of fault that has occurred and how you want +to handle it.

+ +

To find the full list of possible faults that could occur and details regarding to replying to a particular +kind of fault, please see the ‘Faults’ section of the +seL4 reference manual.

+ +

microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo)

+ +

Performs a call to a protected procedure in a different PD. +The ch argument identifies the protected procedure to be called. +msginfo is passed as argument to the protected procedure. +Channel identifiers are specified in the system configuration.

+ +

The protected procedure’s return data is returned in the microkit_msginfo.

+ +

void microkit_notify(microkit_channel ch)

+ +

Notify the channel ch. +Channel identifiers are specified in the system configuration.

+ +

void microkit_irq_ack(microkit_channel ch)

+ +

Acknowledge the interrupt identified by the specified channel.

+ +

void microkit_deferred_notify(microkit_channel ch)

+ +

The same as microkit_notify but will instead not actually perform the notify until +the entry point where microkit_deferred_notify was called returns.

+ +

It is important to note that only a single ‘deferred’ API call can be made within the +same entry point.

+ +

The purpose of this API is for performance critical code as this API saves +a kernel system call.

+ +

void microkit_deferred_irq_ack(microkit_channel ch)

+ +

The same as microkit_irq_ack but will instead not actually perform the IRQ acknowledge +until the entry point where microkit_deferred_irq_ack was called returns.

+ +

It is important to note that only a single ‘deferred’ API call can be made within the +same entry point.

+ +

The purpose of this API is for performance critical code as this API saves +a kernel system call.

+ +

void microkit_pd_restart(microkit_child pd, uintptr_t entry_point)

+ +

Restart the execution of a child protection domain with ID pd at the given entry_point. +This will set the program counter of the child protection domain to entry_point.

+ +

void microkit_pd_stop(microkit_child pd)

+ +

Stop the execution of the child protection domain with ID pd.

+ +

microkit_msginfo microkit_msginfo_new(uint64_t label, uint16_t count)

+ +

Creates a new message structure.

+ +

The message can be passed to microkit_ppcall or returned from protected.

+ +

uint64_t microkit_msginfo_get_label(microkit_msginfo msginfo)

+ +

Returns the label from a message.

+ +

uint64_t microkit_msginfo_get_count(microkit_msginfo msginfo)

+ +

Returns the count of message registers in the message.

+ +

uint64_t microkit_mr_get(uint8_t mr)

+ +

Get a message register.

+ +

void microkit_mr_set(uint8_t mr, uint64_t value)

+ +

Set a message register.

+ +

void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point)

+ +

Restart the execution of a VM’s virtual CPU with ID vcpu at the given entry point. +This will set the program counter of the vCPU to entry_point.

+ +

void microkit_vcpu_stop(microkit_child vcpu)

+ +

Stop the execution of the VM’s virtual CPU with ID vcpu.

+ +

`void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq,

+

seL4_Uint8 priority, seL4_Uint8 group, +seL4_Uint8 index)`

+ +

Inject a virtual ARM interrupt for a virtual CPU vcpu with IRQ number irq. +The priority (0-31) determines what ARM GIC (generic interrupt controller) +priority level the virtual IRQ will be injected as. The group determines whether +the virtual IRQ will be injected into secure world (1) or non-secure world (0). +The index is the index of the virtual GIC list register.

+ +

void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq)

+ +

Acknowledge a ARM virtual Private Peripheral Interrupt (PPI) with IRQ number irq +for a VM’s vCPU with ID vcpu.

+ +

seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg)

+ +

Read a register for a given virtual CPU with ID vcpu. The reg argument is the index of the +register that is read. The list of registers is defined by the enum seL4_VCPUReg +in the seL4 source code.

+ +

void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value)

+ +

Write to a register for a given virtual CPU with ID vcpu. The reg argument is the index of the +register that is written to. The value argument is what the register will be set to. +The list of registers is defined by the enum seL4_VCPUReg in the seL4 source code.

+ +

void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response)

+ +

This API is available only on ARM and only when seL4 has been configured to enable the +KernelAllowSMCCalls option.

+ +

The API takes in arguments for a Secure Monitor Call which will be performed by seL4. Any +response values will be placed into the response structure.

+ +

The seL4_ARM_SMCContext structure contains fields for registers x0 to x7.

+ +

System Description File

+ +

This section describes the format of the System Description File (SDF).

+ +

The system description file is an XML file that is provided as input to the +microkit tool.

+ +

The root element of the XML file is system.

+ +

Within the system root element the following child elements are supported:

+ +
    +
  • protection_domain
    • +
  • memory_region
    • +
  • channel
    • +
+ +

protection_domain

+ +

The protection_domain element describes a protection domain.

+ +

It supports the following attributes:

+ +
    +
  • name: A unique name for the protection domain
    • +
  • priority: The priority of the protection domain (integer 0 to 254).
    • +
  • budget: (optional) The PD’s budget in microseconds; defaults to 1,000.
    • +
  • period: (optional) The PD’s period in microseconds; must not be smaller than the budget; defaults to the budget.
    • +
  • passive: (optional) Indicates that the protection domain will be passive and thus have its scheduling context removed after initialisation; defaults to false.
    • +
  • stack_size: (optional) Number of bytes that will be used for the PD’s stack. +Must be be between 4KiB and 16MiB and be 4K page-aligned. Defaults to 4KiB.
    • +
  • smc: (optional, only on ARM) Allow the PD to give an SMC call for the kernel to perform. Only available when the kernel has been configured with KernelAllowSMCCalls. Defaults to false.
    • +
+ +

Additionally, it supports the following child elements:

+ +
    +
  • program_image: (exactly one) Describes the program image for the protection domain.
    • +
  • map: (zero or more) Describes mapping of memory regions into the protection domain.
    • +
  • irq: (zero or more) Describes hardware interrupt associations.
    • +
  • setvar: (zero or more) Describes variable rewriting.
    • +
  • protection_domain: (zero or more) Describes a child protection domain.
    • +
  • virtual_machine: (zero or one) Describes a child virtual machine.
    • +
+ +

The program_image element has a single path attribute describing the path to an ELF file.

+ +

The map element has the following attributes:

+ +
    +
  • mr: Identifies the memory region to map.
    • +
  • vaddr: Identifies the virtual address at which to map the memory region.
    • +
  • perms: Identifies the permissions with which to map the memory region. Can be a combination of r (read), w (write), and x (eXecute), with the exception of a write-only mapping (just w).
    • +
  • cached: (optional) Determines if mapped with caching enabled or disabled. Defaults to true.
    • +
  • setvar_vaddr: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the virtual address of the memory region.
    • +
  • setvar_size: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the size of the memory region.
    • +
+ +

The irq element has the following attributes:

+ +
    +
  • irq: The hardware interrupt number.
    • +
  • id: The channel identifier. Must be at least 0 and less than 63.
    • +
  • trigger: (optional) Whether the IRQ is edge triggered (“edge”) or level triggered (“level”). Defaults to “level”.
    • +
+ +

The setvar element has the following attributes:

+ +
    +
  • symbol: Name of a symbol in the ELF file.
    • +
  • region_paddr: Name of an MR. The symbol’s value shall be updated to this MR’s physical address.
    • +
+ +

The protection_domain element has the same attributes as any other protection domain as well as:

+ +
    +
  • id: The ID of the child for the parent to refer to.
    • +
+ +

The virtual_machine element has the following attributes:

+ +
    +
  • name: A unique name for the virtual machine
    • +
  • priority: The priority of the virtual machine (integer 0 to 254).
    • +
  • budget: (optional) The VM’s budget in microseconds; defaults to 1,000.
    • +
  • period: (optional) The VM’s period in microseconds; must not be smaller than the budget; defaults to the budget.
    • +
+ +

Additionally, it supports the following child elements:

+ +
    +
  • vcpu: (one or more) Describes the virtual CPU that will be tied to the virtual machine.
    • +
  • map: (zero or more) Describes mapping of memory regions into the virtual machine.
    • +
+ +

The vcpu element has a single id attribute defining the identifier used for the virutal machine’s vCPU.

+ +

The map element has the same attributes as the protection domain with the exception of setvar_vaddr.

+ +

memory_region

+ +

The memory_region element describes a memory region.

+ +

It supports the following attributes:

+ +
    +
  • name: A unique name for the memory region
    • +
  • size: Size of the memory region in bytes (must be a multiple of the page size)
    • +
  • page_size: (optional) Size of the pages used in the memory region; must be a supported page size if provided. Defaults to the largest page size for the target architecture that the memory region is aligned to.
    • +
  • phys_addr: (optional) The physical address for the start of the memory region (must be a multiple of the page size).
    • +
+ +

The memory_region element does not support any child elements.

+ +

Page sizes by architecture

+ +

Below are the available page sizes for each architecture that Microkit supports.

+ +
AArch64
+ +
    +
  • 0x1000 (4KiB)
    • +
  • 0x200000 (2MiB)
    • +
+ +
RISC-V 64-bit
+ +
    +
  • 0x1000 (4KiB)
    • +
  • 0x200000 (2MiB)
    • +
+ +

channel

+ +

The channel element has exactly two end children elements for specifying the two PDs associated with the channel.

+ +

The end element has the following attributes:

+ +
    +
  • pd: Name of the protection domain for this end.
    • +
  • id: Channel identifier in the context of the named protection domain. Must be at least 0 and less than 63.
    • +
  • pp: (optional) Indicates that the protection domain for this end can perform a protected procedure call to the other end; defaults to false. + Protected procedure calls can only be to PDs of strictly higher priority.
    • +
  • notify: (optional) Indicates that the protection domain for this end can send a notification to the other end; defaults to true.
    • +
+ +

The id is passed to the PD in the notified and protected entry points. +The id should be passed to the microkit_notify and microkit_ppcall functions.

+ +

Board Support Packages

+ +

This chapter describes the board support packages that are available in the SDK.

+ +

Ariane (CVA6)

+ +

Initial support is available for the CVA6 (formerly Ariane) core design +on the Digilent Genesys2 board. CVA6 is an open-source RISC-V (rv64i) processor.

+ +

Microkit support expects that a compatible RISC-V SBI (e.g OpenSBI) has executed before +jumping to the beginning of the loader image.

+ +

Note that the loader link address is 0x90000000 and this is where the binary must +be located and where OpenSBI (or U-Boot) should begin execution.

+ +

You may compile OpenSBI with the Microkit image as a payload, or alternately install +OpenSBI (with U-Boot optionally) to the SD card.

+ +

If you are booting from U-Boot, use the following command to start the system image: + => go 0x90000000

+ +

Note that the OpenSBI version from the CVA6 SDK at the time of writing has issues when +booting. It is recommended to use the mainline OpenSBI.

+ +

Cheshire

+ +

Support is available for Cheshire. +It is an SoC design based on the CVA6 core, implementing a 64-bit RISC-V CPU.

+ +

Microkit outputs a raw binary for this device. Several steps are required in order to boot.

+ +

A custom version of OpenSBI is required. It can be found +here. +Build the firmware payload using platform fpga/cheshire.

+ +

Using U-Boot

+ +

With a system pre-configured with the Cheshire ZSBL, OpenSBI and U-boot:

+ +
=> go 0x90000000
+
+ +

Raw systerm with no bootloader

+ +

Without any firmware present on the SD card, it is still possible to boot Cheshire with a Microkit system.

+ +

Using a GDB prompt via openOCD:

+ +
    +
  1. +

    Reset board

    + +

    => monitor reset halt

    +
    2. +
  2. +

    Load a device tree blob (DTS available in Cheshire repo or seL4) to memory and set the a0 and a1 registers to point at it:

    + +
    +

    restore /path/to/cheshire.dtb binary 0xa0000000

    +
    +
    3. +
+ +

(tell OpenSBI where DTB is)

+ +
> set $a0=0xa0000000
+
+ +

(tell OpenSBI that the default hart is #0)

+ +
> set $a1=0
+
+ +
    +
  1. +

    Load OpenSBI

    + +
    +

    load /path/to/opensbi/fw_payload.elf

    +
    +
    2. +
  2. +

    Allow OpenSBI to boot, and interrupt it once the line Test payload running is emitted on serial.

    + +
    +

    continue

    +
    +
    3. +
+ +

(wait for output)

+ +
> (Ctrl+C)
+
+ +
    +
  1. +

    Load Microkit image and execute

    + +
    +

    restore /path/to/loader.img binary 0x90000000

    +
    +
    2. +
+ +

(execute)

+ +
> continue
+
+ +

i.MX8MM-EVK

+ +

Microkit produces a raw binary file, so when using U-Boot you must execute the image using:

+ +
=> go 0x41000000
+
+ +

i.MX8MP-EVK

+ +

Microkit produces a raw binary file, so when using U-Boot you must execute the image using:

+ +
=> go 0x41000000
+
+ +

i.MX8MQ-EVK

+ +

Microkit produces a raw binary file, so when using U-Boot you must execute the image using:

+ +
=> go 0x41000000
+
+ +

MaaXBoard

+ +

The MaaXBoard is a low-cost ARM SBC based on the NXP i.MX8MQ system-on-chip.

+ +

Microkit produces a raw binary file, so when using U-Boot you must execute the image using:

+ +
=> go 0x50000000
+
+ +

Odroid-C2

+ +

The HardKernel Odroid-C2 is an ARM SBC based on the Amlogic Meson S905 system-on-chip. It +should be noted that the Odroid-C2 is no longer available for purchase but its successor, +the Odroid-C4, is readily available at the time of writing.

+ +

Microkit produces a raw binary file, so when using U-Boot you must execute the image using:

+ +
=> go 0x20000000
+
+ +

Odroid-C4

+ +

The HardKernel Odroid-C4 is an ARM SBC based on the Amlogic Meson S905X3 system-on-chip.

+ +

Microkit produces a raw binary file, so when using U-Boot you must execute the image using:

+ +
=> go 0x20000000
+
+ +

QEMU virt (AArch64)

+ +

Support is available for the virtual AArch64 QEMU platform. This is a platform that is not based +on any specific SoC or hardware platform and is intended for simulating systems for +development or testing.

+ +

It should be noted that the platform support is configured with 2GB of main memory and a single +Cortex-A53 CPU.

+ +

You can use the following command to simulate a Microkit system:

+ +
$ qemu-system-aarch64 \
+    -machine virt,virtualization=on \
+    -cpu cortex-a53 \
+    -nographic \
+    -serial mon:stdio \
+    -device loader,file=[SYSTEM IMAGE],addr=0x70000000,cpu-num=0 \
+    -m size=2G
+
+ +

You can find more about the QEMU virt platform in the +QEMU documentation.

+ +

QEMU virt (RISC-V 64-bit)

+ +

Support is available for the virtual RISC-V (64-bit) QEMU platform. +This is a platform that is not based on any specific SoC or hardware platform +and is intended for simulating systems for development or testing.

+ +

It should be noted that the platform support is configured with 2GB of main memory.

+ +

You can use the following command to simulate a Microkit system:

+ +
$ qemu-system-riscv64 \
+    -machine virt \
+    -nographic \
+    -serial mon:stdio \
+    -kernel [SYSTEM IMAGE] \
+    -m size=2G
+
+ +

QEMU will start the system image using its packaged version of OpenSBI.

+ +

You can find more about the QEMU virt platform in the +QEMU documentation.

+ +

Raspberry Pi 4B

+ +

Support is available for the Raspberry Pi 4 Model B. There are multiple models of the +Rasberry Pi 4B that have different amounts of RAM, we target the 1GB model in Microkit. +If you require more than 1GB, please file an issue or pull request to add support for +models with larger amounts of memory.

+ +

For initial board setup, please see the instructions on the +seL4 website.

+ +

When getting into the U-Boot console you want to load the Microkit binary image to +address 0x10000000 and then run go 0x10000000.

+ +

For example, if you were to load the image via the MMC you would run the following +U-Boot commands:

+ +
 => fatload mmc 0 0x10000000 <SYSTEM IMAGE>
+ => go 0x10000000
+
+ +

Pine64 ROCKPro64

+ +

Microkit produces a raw binary file, so when using U-Boot you must execute the image using:

+ +
=> go 0x30000000
+
+ +

Pine64 Star64

+ +

Support is available for the Pine64 Star64 platform which is based on the +StarFive JH7110 SoC.

+ +

The platform has a 4GB and 8GB model, we assume the 4GB model.

+ +

The default boot flow of the Star64 is:

+
    +
  1. OpenSBI
    2. +
  2. U-Boot
    3. +
  3. Operating System
    4. +
+ +

This means that the system image that Microkit produces does not need to be explicitly +packaged with an SBI implementation such as OpenSBI.

+ +

To execute the system image produced by Microkit, execute the following command in U-Boot:

+ +
=> go 0x60000000
+
+ +

TQMa8XQP 1GB

+ +

The TQMa8XQP is a system-on-module designed by TQ-Systems GmbH. +The modules incorporates an NXP i.MX8X Quad Plus system-on-chip and 1GiB ECC memory.

+ +

TQ-Systems provide the MBa8Xx carrier board for development purposes. +The instructions provided assume the use of the MBa8Xx carrier board. +If you are using a different carrier board please refer to the appropriate documentation.

+ +

Note: There are different configured of the TQMa8Xx board which include different NXP SoCs +and different memory configurations. Such modules are not supported.

+ +

The MBa8Xx provides access to the TQMa8XQP UART via UART-USB bridge. +To access the UART connect a USB micro cable to port X13. +The UART-USB bridge supports 4 individual UARTs; the UART is connected to the 2nd port.

+ +

By default the SoM will autoboot using U-Boot. +Hit any key during the boot process to stop the autoboot.

+ +

A new board will autoboot to Linux. +You will likely want to disable autoboot:

+ +
=> env set bootdelay -1
+=> env save
+
+ +

The board can be reset by pressing switch S4 (located next to the Ethernet port). +Alternatively, you can use the reset command from the U-Boot prompt.

+ +

During development the most convenient way to boot a Microkit image is via network booting. +U-Boot support booting via the tftp protocol. +To support this you’ll want to configure the network. +U-Boot supports DHCP, however it is often more reliable to explicitly set an IP address. +For example:

+ +
=> env set ipaddr 10.1.1.2
+=> env set netmask 255.255.255.0
+=> env set serverip 10.1.1.1
+=> env save
+
+ +

To use tftp you also need to set the file to load and the memory address to load it to:

+ +
=> env set bootfile loader.img
+=> env set loadaddr 0x80280000
+=> env save
+
+ +

The system image generated by the Microkit tool is a raw binary file.

+ +

An example sequence of commands for booting is:

+ +
=> tftpboot
+=> dcache flush
+=> icache flush
+=> go ${loadaddr}
+
+ +

Rather than typing these each time you can create a U-Boot script:

+ +
=> env set microkit 'tftpboot; dcache flush; icache flush; go ${loadaddr}'
+=> env save
+=> run microkit
+
+ +

When debugging is enabled the kernel will use the same UART as U-Boot.

+ +

ZCU102

+ +

The ZCU102 can run on a physical board or on an appropriate QEMU based emulator.

+ +

Microkit produces a raw binary file, so when using U-Boot you must execute the image using:

+ +
=> go 0x40000000
+
+ +

For simulating the ZCU102 using QEMU, use the following command:

+ +
$ qemu-system-aarch64 \
+   -m size=4G  \
+   -machine xlnx-zcu102,virtualization=on \
+   -nographic \
+   -device loader,file=[SYSTEM IMAGE],addr=0x40000000,cpu-num=0 \
+   -serial mon:stdio
+
+ +

It should be noted that when using U-Boot to load and run a Microkit system image, +that there may be additional setup needed.

+ +

For the ZynqMP class of platforms, which the ZCU102 is apart of, U-Boot does not start +the Microkit system Exception Level 2 (EL2) which is necessary for Microkit to start +(this is because seL4 is configured as a hypervisor).

+ +

You can see that when using the go command, U-Boot is +unconditionally always dropping down to EL1.

+ +

To avoid this behaviour, the call to armv8_switch_to_el1 should be replaced with +armv8_switch_to_el2 in this do_go_exec function.

+ +

Adding Platform Support

+ +

The following section is a guide for adding support for a new platform to Microkit.

+ +

Prerequisites

+ +

Before you can start with adding platform support to Microkit, the platform must be supported by the seL4 kernel. +You can find information on how to do so here.

+ +

Getting Microkit Components Working

+ +

The first step to adding Microkit support is to modify the build_sdk.py script in order to build the required +artefacts for the new platform. This involves adding to the SUPPORTED_BOARDS list with the BoardInfo options +containing the platform specific attributes. This should be fairly self-explanatory by looking at the existing +entries with the exception of the loader_link_address.

+ +

The loader_link_address parameter specifies the physical address of where the bootloader for Microkit (which +is responsible for setting up the system before seL4 starts) is going to be loaded. This address needs to +match where in main memory the final system image is actually loaded (e.g where a previous bootloader such as U-Boot +loads the image to). This means that the address is restricted to the platform’s main memory region.

+ +

The other component of Microkit that is platform dependent is the loader itself. The loader will attempt to access +the UART for debug output which requires a basic putc implementation. The UART device used in the loader should be +the same as what is used for the seL4 kernel debug output.

+ +

It should be noted that on RISC-V platforms, the SBI will be used for putc so no porting is necessary.

+ +

Once you have patched the loader and the SDK build script, there should be no other changes required to have a working +platform port. It is a good idea at this point to boot a hello world system to confirm the port is working.

+ +

If there are issues with porting the platform, please open an issue on GitHub.

+ +

Contributing Platform Support

+ +

Once you believe that the port works, you can open a pull request with required +changes as well as documentation in the manual about the platform and how to run Microkit images on it.

+ +

Rationale

+ +

This section describes the rationales driving the Microkit design choices.

+ +

Overview

+ +

The seL4 microkernel provides a set of powerful and flexible mechanisms that can be used for building almost arbitrary systems. +While minimising constraints on the nature of system designs and scope of deployments, this flexibility makes it challenging to design the best system for a particular use case, requiring extensive seL4 experience from developers.

+ +

The Microkit addresses this challenge by constraining the +system architecture to one that provides enough features and power for +its target usage class (IoT, cyberphysical and other embedded systems +with a static architecture), enabling a much simpler set of developer-visible abstractions.

+ +

Protection Domains

+ +

PDs are single-threaded to keep the programming model and implementations simple, and because this serves the needs of most present use cases in the target domains. +Extending the model to multithreaded applications (clients) is straightforward and can be done if needed. +Extending to multithreaded services is possible but requires additional infrastructure for which we see no need in the near future.

+ +

Protected Procedure Priorities

+ +

The restriction of only calling to higher priority prevents deadlocks and reflects the notion that the callee operates on behalf of the caller, and it should not be possible to preempt execution of the callee unless the caller could be preempted as well.

+ +

This greatly simplifies reasoning about real-time properties in the system; in particular, it means that PPs can be used to implement resource servers, where shared resources are encapsulated in a component that ensures mutual exclusion, while avoiding unbounded priority inversions through the immediate priority ceiling protocol.

+ +

While it would be possible to achieve the same by allowing PPs between PDs of the same priority, this would be much harder to statically analyse for loop-freedom (and thus deadlock-freedom). +The drawback is that we waste a part of the priority space where a logical entity is split into multiple PDs, eg to separate out a particularly critical component to formally verify it, when the complete entity would be too complex for formal verification. +For the kinds of systems targeted by the Microkit, this reduction of the usable priority space is unlikely to cause problems.

+ +

Protected Procedure Argument Size

+ +

The limitation on the size of by-value arguments is forced by the (architecture-dependent) limits on the payload size of the underlying seL4 operations, as well as by efficiency considerations. +The protected procedure payload should be considered as analogous to function arguments in the C language; similar limitations exist in the C ABIs (Application Binary Interfaces) of various platforms.

+ +

Limits

+ +

The limitation on the number of protection domains in the system is relatively arbitrary. +Based on experience with the system and the types of systems being built it is possible for this to be increased in the future.

+ +

The limitation on the number of channels for a protection domain is based on the size of the notification word in seL4. +Changing this to be larger than 64 would most likely require changes to seL4. The reason for why the limit is not a +power of two is due to part of the notification word being for internal libmicrokit use.

+ +

Internals

+ +

The following section describes internal details for how the Microkit works +and all the components of Microkit. As a user of Microkit, it is not necessary +know this information, however, there is no harm in having a greater +understanding of the tools that you are using.

+ +

Microkit flow

+ +

The diagram above aims to show the general flow of a Microkit system from +build-time to run-time.

+ +

The user provides the SDF (System Description File) and the ELFs that +correspond to PD program images to the Microkit tool which is responsible to +for packaging everything together into a single bootable image for the target +platform.

+ +

This final image contains a couple different things:

+ +
    +
  • the Microkit loader
    • +
  • seL4
    • +
  • the Monitor (and associated invocation data)
    • +
  • the images for all the user’s PDs
    • +
+ +

When booting the image, the Microkit loader starts, jumps to the kernel, which +starts the monitor, which then sets up the entire system and starts all the PDs.

+ +

Now, we will go into a bit more detail about each of these stages of the +booting process as well as what exactly the Microkit tool is doing.

+ +

Loader

+ +

The loader starts first, it has two main jobs:

+ +
    +
  1. Unpack all the parts of the system (kernel, monitor, PD images, etc) into +their expected locations within main memory.
    2. +
  2. Finish initialising the hardware such that the rest of the system can start.
    3. +
+ +

Unpacking the system image is fairly straight-forward, as all the information +about what parts of the system image need to go where is figured out by the +tool and embedded into the loader at build-time so when it starts it just goe +through an array and copies data into the right locations.

+ +

Before the Microkit loader starts, there would most likely have been some other +bootloader such as U-Boot or firmware on the target that did its own hardware +initialisation before starting Microkit.

+ +

However, there are certain things that seL4 expects to be initialised +that will not be done by a previous booting stage, such as:

+ +
    +
  • changing to the right exception level
    • +
  • enabling the MMU (seL4 expects the MMU to be on when it starts)
    • +
  • interrupt controller setup
    • +
+ +

Once this is all completed, the loader jumps to seL4 which starts executing. +The loader will never be executed again.

+ +

Monitor

+ +

Once the kernel has done its own initialisation, it will begin the +‘initial task’. On seL4, this is a thread that contains all the initial +capabilities to resources that are used to setup the rest of the system.

+ +

Within a Microkit environment, we call the initial task the ‘monitor’.

+ +

The monitor has two main jobs:

+ +
    +
  1. Setup all system resources (memory regions, channels, interrupts) and start +the user’s protection domains.
    2. +
  2. Receive any faults caused by protection domains crashing or causing +exceptions.
    3. +
+ +

At build-time, the Microkit tool embeds all the system calls that the monitor +needs to make in order to setup the user’s system. More details about how +this is done is in the section on the Microkit tool below. But from the +monitor’s perspective, it just iterates over an array of system calls to make +and performs each one.

+ +

After the system has been setup, the monitor goes to sleep and waits for any +faults from protection domains. On debug mode, this results in a message about +which PD caused an exception and details on the PD’s state at the time of the fault.

+ +

Other than printing fault details, the monitor does not do anything to handle +the fault, it will simply go back to sleep waiting for any other faults.

+ +

libmicrokit

+ +

Unlike the previous sections, libmicrokit is not its own program but it is worth +a mention since it makes up the core of each protection domain in a system.

+ +

When each PD starts, we enter libmicrokit’s starting point which does some initial +setup and calls the init entry point specified by the user. Once that completes, +the PD will enter libmicrokit’s event handler which sleeps until it receives events.

+ +

These events could be notifies (from other PDs or from an interrupt), PPCs, and faults. +For each event, the appropriate user-specified entry point is called and then when it +returns the PD goes back to sleep, waiting on any more events.

+ +

Microkit tool

+ +

The Microkit tool’s ultimate job is to take in the description of the user’s system, +the SDF, and convert into an seL4 system that boots and executes.

+ +

There are obvious steps such as parsing the SDF and PD ELFs but the majority of +the work done by the tool is converting the system description into a list of +seL4 system calls that need to happen.

+ +

In order to do this however, the Microkit tool needs to perform o a decent amount of +‘emulation’ to know exactly what system calls and with which arguments to make. +This requires keeping track of what memory is allocated and where, the layout of +each capability space, what the initial untypeds list will look like, etc.

+ +

While this is non-trivial to do, it comes with the useful property that if the tool +produces a valid image, there should be no errors upon initialising the system +If there are any errors with configuring the system (e.g running out of memory), +they will be caught at build-time. This can only reasonably be done due to the +static-architecture of Microkit systems.

+ +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/microkit/manual/2.0.1/index.md b/projects/microkit/manual/2.0.1/index.md deleted file mode 100644 index 8fd82776b46..00000000000 --- a/projects/microkit/manual/2.0.1/index.md +++ /dev/null @@ -1,1254 +0,0 @@ ---- -parent: /projects/microkit/manual/latest/ -toc: true -SPDX-FileCopyrightText: 2021, Breakaway Consulting Pty. Ltd. -SPDX-License-Identifier: CC-BY-SA-4.0 -mathjax: true ---- - -# Microkit User Manual (v2.0.1) - -This is a web version of the manual, you can find a PDF [here](microkit_user_manual.pdf) as well as in the -SDK at `doc/microkit_user_manual.pdf`. - -## Introduction - -The seL4 Microkit is a small and simple operating system (OS) built on the seL4 microkernel. -Microkit is designed for building system with a *static architecture*. -A static architecture is one where system resources are assigned up-front at system initialisation time. - -### Purpose - -The Microkit is intended to: - -* provide a small and simple OS for a wide range of IoT, cyberphysical and other embedded use cases; -* provide a reasonable degree of application portability appropriate for the targeted use cases; -* make seL4-based systems easy to develop and deploy within the target areas; -* leverage seL4's strong isolation properties to support a near-minimal *trusted computing base* (TCB); -* retain seL4's trademark performance for systems built with it; -* be, in principle, amenable to formal analysis of system safety and security properties (although such analysis is beyond the initial scope). - -### Overview - -A Microkit system is built from a set of individual programs that are isolated from each other, and the system, in *protection domains*. -Protection domains can interact by calling *protected procedures* or sending *notifications*. - -Microkit is distributed as a software development kit (SDK). -The SDK includes the tools, libraries and binaries required to build a Microkit system. -The Microkit source is also available which allows you to customize or extend Microkit and produce your own SDK. - -To build a Microkit system you will write some programs that use `libmicrokit`. -Microkit programs are a little different to a typical process on a Linux-like operating system. -Rather than a single `main` entry point, a program has four distinct entry points: `init`, `notified` and, potentially, `protected`, `fault`. - -The individual programs are combined to produce a single bootable *system image*. -The format of the image is suitable for loading by the target board's bootloader. -The Microkit tool, which is provided as part of the SDK, is used to generate the system image. - -The Microkit tool takes a *system description* as input. -The system description is an XML file that specifies all the objects that make up the system. - -*Note*: Microkit does **not** impose any specific build system; you are free to choose the build system that works best for you. - -### Document Structure - -The [Concepts](#concepts) chapter describes the various concepts that make up Microkit. -It is recommended that you familiarise yourself with these concepts before trying to build a system. - -The [SDK](#sdk) chapter describes the software development kit, including its components and system requirements for use. - -The [Microkit tool](#tool) chapter describes the host system tool used for generating a system image from the system description and user-programs. - -The [libmicrokit](#libmicrokit) chapter describes the interfaces to the Microkit library. - -The [System Description File](#sysdesc) chapter describes the format of the system description XML file. - -The [Board Support Packages](#bsps) chapter describes each of the board support packages included in the SDK. - -The [Rationale](#rationale) chapter documents the rationale for some of the key design choices of in Microkit. - -The [Internals](#internals) chapter documents some of the internal details for how Microkit works. - -## Concepts {#concepts} - -This chapter describes the key concepts provided by Microkit. - -As with any set of concepts there are words that take on special meanings. -This document attempts to clearly describe all of these terms, however as the concepts are inter-related it is sometimes necessary to use a term prior to its formal introduction. - -* [system](#system) -* [protection domain (PD)](#pd) -* [virtual machine (VM)](#vm) -* [memory region](#mr) -* [channel](#channels) -* [protected procedure](#pp) -* [notification](#notification) -* [interrupt](#irq) -* [fault](#fault) - -### System {#system} - -At the most basic level Microkit provides the platform for running a *system* on a specific board. -As a *user* of Microkit you use the platform to create a software system that implements your use case. -The system is described in a declarative configuration file, and the Microkit tool takes this system description as an input and produces an appropriate system image that can be loaded on the target board. - -The key elements that make up a system are *protection domains*, *memory regions* and *channels*. - -### Protection Domains {#pd} - -A **protection domain** (PD) is the fundamental runtime abstraction in Microkit. -It is analogous, but very different in detail, to a process on a UNIX system. - -A PD provides a thread of control that executes within a fixed virtual address space. -The isolation provided by the virtual address space is enforced by the underlying hardware MMU. - -The virtual address space for a PD has mappings for the PD's *program image* along with any memory regions that the PD can access. -The program image is an ELF file containing the code and data which implements the isolated component. - -Microkit supports a maximum of 63 protection domains. - -#### Entry points - -Although a protection domain is somewhat analogous to a process, it has a considerably different program structure and life-cycle. -A process on a typical operating system will have a `main` function which is invoked by the system when the process is created. -When the `main` function returns the process is destroyed. - -By comparison a protection domain has up to four entry points: - -* `init`, `notified` which are required. -* `protected` which is optional. -* `fault` which is required if the PD has children. - -When a Microkit system is booted, all PDs in the system execute the `init` entry point. - -A PD will not execute any other entry point until `init` has finished. - -If a PD is currently executing an entry point, it will not execute any other entry point -until the current entry point has finished. - -The `notified` entry point will be invoked whenever the protection domain receives a *notification* on a *channel*. -The `protected` entry point is invoked when a PD's *protected procedure* is called by another PD. -A PD does not have to provide a protected procedure, therefore the `protected` entry point is optional. - -The `fault` entry point is invoked when a PD that is a child of another PD causes a fault. -A PD does not have to have child PDs, therefore the `fault` entry point is only required for a parent PD. - -These entry points are described in more detail in subsequent sections. - -**Note:** The processing of `init` entry points is **not** synchronised across protection domains. -Specifically, it is possible for a high priority PD's `notified` or `protected` entry point to be called prior to the completion of a low priority PD's `init` entry point. - -The overall computational model for a Microkit system is a set of isolated components reacting to incoming events. - -#### Scheduling - -The PD has a number of scheduling attributes that are configured in the system description: - -* priority (0 -- 254) -* period (microseconds) -* budget (microseconds) -* passive (boolean) - -The budget and period bound the fraction of CPU time that a PD can consume. -Specifically, the **budget** specifies the amount of time for which the PD is allowed to execute. -Once the PD has consumed its budget, it is no longer runnable until the budget is replenished; replenishment happens once every **period** and resets the budget to its initial value. -This means that the maximum fraction of CPU time the PD can consume is $\frac{budget}{period}$. - -The budget cannot be larger than the period. -A budget that equals the period (aka. a "full" budget) behaves like a traditional time slice: After executing for a full period, the PD is preempted and put at the end of the scheduling queue of its priority. In other words, PDs with equal priorities and full budgets are scheduled round-robin with a time slice defined by the period. - -The **priority** determines which of the runnable PDs to schedule. A PD is runnable if one of its entry points has been invoked and it has budget remaining in the current period. -Runnable PDs of the same priority are scheduled in a round-robin manner. - -**Passive** determines whether the PD is passive. A passive PD will have its scheduling context revoked after initialisation and then bound instead to the PD's notification object. This means the PD will be scheduled on receiving a notification, whereby it will run on the notification's scheduling context. When the PD receives a *protected procedure* by another PD or a *fault* caused by a child PD, the passive PD will run on the scheduling context of the callee. - -### Virtual Machines {#vm} - -A *virtual machine* (VM) is a runtime abstraction for running guest operating systems in Microkit. It is similar -to a protection domain in that it provides a thread of control that executes within an isolated virtual address space. - -The main difference between a VM and a PD is that VMs have a higher privilege level such that they may function as a -guest operations and have their own user-space programs at a separate exception level. - -The virtual machine is always a child of a PD. Exceptions caused by the virtual machine are delivered to the parent PD -through the `fault` entry point. - -Each virtual machine has a number of 'virtual CPU's associated with it. Each virtual CPU (vCPU) that belongs to a -virtual machine has its own thread of execution. A vCPU also has an identifier which is used to know which vCPU caused -the invocation of the `fault` entry point. - -The parent PD is responsible for starting and managing the virtual machine. Microkit provides the abstractions in -order to manage the virtual machine through seL4 but there is typically a non-trivial amount -of supporting code/infrastructure to properly start and manage a VM. - -To keep the (potentially untrusted) virtual machine isolated from the rest of the system, Microkit enforces that a -protection domain can only ever manage a single virtual machine. - -### Memory Regions {#mr} - -A *memory region* is a contiguous range of physical memory. -A memory region may have a *fixed* physical address. -For memory regions without a fixed physical address, the physical address is allocated as part of the build process. -Typically, memory regions with a fixed physical address represent memory-mapped device registers. - -Memory regions that are within main memory are zero-initialised. - -The size of a memory region must be a multiple of a supported page size. -The supported page sizes are architecture dependent. -For example, on AArch64 architectures, Microkit support 4KiB and 2MiB pages. -The page size for a memory region may be specified explicitly in the system description. -If page size is not specified, the smallest supported page size is used. - -*Note:* The page size also restricts the alignment of the memory region's physical address. -A fixed physical address must be a multiple of the specified page size. - -A memory region can be *mapped* into one or more protection domains. -The mapping has a number of attributes, which include: - -* the virtual address at which the region is mapped in the PD -* caching attributes (mostly relevant for device memory) -* permissions (read, write and execute) - -**Note:** When a memory region is mapped into multiple protection -domains, the attributes used for different mappings may vary. - -### Channels {#channels} - -A *channel* enables two protection domains to interact using protected procedures or notifications. -Each connects exactly two PDs; there are no multi-party channels. - -When a channel is created between two PDs, a *channel identifier* is configured for each PD. -The *channel identifier* is used by the PD to reference the channel. -Each PD can refer to the channel with a different identifier. -For example if PDs **A** and **B** are connected by a channel, **A** may refer to the channel using an identifier of **37** while **B** may use **42** to refer to the same channel. - -**Note:** There is no way for a PD to directly refer to another PD in the system. -PDs can only refer to other PDs indirectly if there is a channel between them. -In this case, the channel identifier is effectively a proxy identifier for the other PD. -So, to extend the prior example, **A** can indirectly refer to **B** via the channel identifier **37**. -Similarly, **B** can refer to **A** via the channel identifier **42**. - -The system supports a maximum of 63 channels and interrupts per protection domain. - -#### Protected procedures {#pp} - -A protection domain may provide a *protected procedure* (PP) which can be invoked from another protection domain. -Up to 64 words of data may be passed as arguments when calling a protected procedure. -The protected procedure return value may also be up to 64 words. - -When a protection domain calls a protected procedure, the procedure executes within the context of the providing protection domain. - -A protected call is only possible if the callee has strictly higher priority than the caller. -Transitive calls are possible, and as such a PD may call a *protected procedure* in another PD from a `protected` entry point. -However the overall call graph between PDs must form a directed, acyclic graph. -It follows that a PD can not call itself, even indirectly. -For example, `A calls B calls C` is valid (subject to the priority constraint), while `A calls B calls A` is not valid. - -When a protection domain is called, the `protected` entry point is invoked. -The control returns to the caller when the `protected` entry point returns. - -The caller is blocked until the callee returns. -Protected procedures must execute in bounded time. -It is intended that a future version of Microkit will enforce this condition through static analysis. -In the present version the caller must trust the callee to conform. - -In general, PPs are provided by services for use by clients that trust the protection domain to provide that service. - -To call a PP, a PD calls `microkit_ppcall` passing the channel identifier and a *message* structure. -A *message* structure is returned from this function. - -When a PD's protected procedure is invoked, the `protected` entry point is invoked with the channel identifier and message structure passed as arguments. -The `protected` entry point must return a message structure. - -#### Notifications {#notification} - -A notification is a (binary) semaphore-like synchronisation mechanism. -For example, a PD can *notify* another PD to indicate availability of data in a shared memory region if they share a channel. - -To notify another PD, a PD calls `microkit_notify`, passing the channel identifier. -When a PD receives a notification, the `notified` entry point is invoked with the appropriate channel identifier passed as an argument. - -Unlike protected procedures, notifications can be sent in either direction on a channel regardless of priority. - -**Note:** Notifications provide a mechanism for synchronisation between PDs, however this is not a blocking operation. -If a PD notifies another PD, that PD will become scheduled to run (if it is not already), but the current PD does **not** block. -Of course, if the notified PD has a higher priority than the current PD, then the current PD will be preempted (but not blocked) by the other PD. - -Depending on the scheduling, one PD could notify another multiple times without it being scheduled, resulting -in a single execution of the `notified` entry point. For example, if PD A notifies PD B three times on the -same channel without PD B ever executing, once PD B is scheduled it would only see one notification and hence -only enter `notified` once for that channel. - -### Interrupts {#irq} - -Hardware interrupts can be used to notify a protection domain. -The system description specifies if a protection domain receives notifications for any hardware interrupt sources. -Each hardware interrupt is assigned a channel identifier. -In this way the protection domain can distinguish the hardware interrupt from other notifications. -A specific hardware interrupt can only be associated with at most one protection domain. It should be noted that once a -hardware interrupt has been received, it will not be received again until `microkit_irq_ack` is called. The seL4 kernel -will mask the hardware interrupt until it has been acknowledged. - -Microkit does not provides timers, nor any *sleep* API. -After initialisation, activity in the system is initiated by an interrupt causing a `notified` entry point to be invoked. -That notified function may in turn notify or call other protection domains that cause other system activity, but eventually all activity indirectly initiated from that interrupt will complete, at which point the system is inactive again until another interrupt occurs. - -### Faults {#fault} - -Faults such as an invalid memory access or illegal instruction are delivered to the seL4 kernel which then forwards them to -a designated 'fault handler'. By default, all faults caused by protection domains go to the system fault handler which -simply prints out details about the fault in a debug configuration. - -When a protection domain is a child of another protection domain, the designated fault handler for the child is the parent -protection domain. The same applies for a virtual machine. - -This means that whenever a fault is caused by a child, it will be delivered to the parent PD instead of the system fault -handler via the `fault` entry point. It is then up to the parent to decide how the fault is handled. - -The default system fault handler (aka the monitor) has the highest priority and so will -execute and handle faults immediately after they occur. For child PDs that have their faults -delivered to another PD, the fault being handled depends on when the parent PD is scheduled. - -## SDK {#sdk} - -Microkit is distributed as a software development kit (SDK). - -The SDK includes support for one or more *boards*. -Three *configurations* are supported for each board: *debug*, *release*, and *benchmark*. -See [the Configurations section](#config) for more details. - -The SDK contains: - -* Microkit user manual (this document) -* Microkit tool - -Additionally, for each supported board configuration the following are provided: - -* `libmicrokit` -* `loader.elf` -* `kernel.elf` -* `monitor.elf` - -There are also examples provided in the `example` directory. - -The Microkit SDK does **not** provide, nor require, any specific build system. -The user is free to build their system using whatever build system is deemed most appropriate for their specific use case. - -The Microkit tool should be invoked by the system build process to transform a system description (and any referenced program images) into an image file which can be loaded by the target board's bootloader. - -The ELF files provided as program images should be standard ELF files and have been linked against the provided libmicrokit. - -### Configurations {#config} - -### Debug - -The *debug* configuration includes a debug build of the seL4 kernel to allow console debug output using the kernel's UART driver. - -### Release - -The *release* configuration is a release build of the seL4 kernel and is intended for production builds. The loader, monitor, and -kernel do *not* perform any serial output. - -### Benchmark - -The *benchmark* configuration uses a build of the seL4 kernel that exports the hardware's performance monitoring unit (PMU) to PDs. -The kernel also tracks information about CPU utilisation. This benchmark configuration exists due a limitation of the seL4 kernel -and is intended to be removed once [RFC-16 is implemented](https://github.com/seL4/rfcs/pull/22). - -### System Requirements - -The Microkit tool requires Linux (x86-64 or AArch64), macOS (x86-64 or AArch64). - -On Linux, the Microkit tool is statically linked and should run on any distribution. - -On macOS, the Microkit tool should run on macOS 10.12 (Sierra) or higher. - -The Microkit tool does not depend on any additional system binaries. - -## Microkit Tool {#tool} - -The Microkit tool is available in `bin/microkit`. - -The Microkit tool takes as input a system description. -The format of the system description is described in a subsequent chapter. - -Usage: - - microkit [-h] [-o OUTPUT] [-r REPORT] --board [BOARD] --config CONFIG - [--search-path [SEARCH_PATH ...]] system - -The path to the system description file, board to build the system for, and configuration to build for must be provided. - -The search paths provided tell the tool where to find any program images specified in the system description file. - -In the case of errors, a diagnostic message shall be output to `stderr` and a non-zero code returned. - -In the case of success, a loadable image file and a report shall be produced. -The output paths for these can be specified by `-o` and `-r` respectively. -The default output paths are `loader.img` and `report.txt`. - -The loadable image will be a binary that can be loaded by the board's bootloader. - -The report is a plain text file describing important information about the system. -The report can be useful when debugging potential system problems. -This report does not have a fixed format and may change between versions. -It is not intended to be machine readable. - -## Language Support - -There are native APIs for C/C++ and Rust. - -[libmicrokit](#libmicrokit) exports a C API and so can be used in any language -that supports C FFI. - -For Rust, native bindings exist but are not included in the SDK itself. They are -available at [rust-sel4](https://github.com/seL4/rust-sel4). - -## libmicrokit {#libmicrokit} - -All program images should link against `libmicrokit.a`. - -The library provides the C runtime for the protection domain, along with interfaces for the Microkit APIs. - -The component must provide the following functions: - - void init(void); - void notified(microkit_channel ch); - -If the protection domain provides a protected procedure it must also implement: - - microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo); - -If the protection domain has children it must also implement: - - seL4_Bool fault(microkit_child child, microkit_msginfo msginfo, - microkit_msginfo *reply_msginfo); - -`libmicrokit` provides the following functions: - - microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo); - void microkit_notify(microkit_channel ch); - microkit_msginfo microkit_msginfo_new(seL4_Word label, seL4_Uint16 count); - seL4_Word microkit_msginfo_get_label(microkit_msginfo msginfo); - seL4_Word microkit_msginfo_get_count(microkit_msginfo msginfo); - void microkit_irq_ack(microkit_channel ch); - void microkit_deferred_notify(microkit_channel ch); - void microkit_deferred_irq_ack(microkit_channel ch); - void microkit_pd_restart(microkit_child pd, seL4_Word entry_point); - void microkit_pd_stop(microkit_child pd); - void microkit_mr_set(seL4_Uint8 mr, seL4_Word value); - seL4_Word microkit_mr_get(seL4_Uint8 mr); - void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point); - void microkit_vcpu_stop(microkit_child vcpu); - void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq, - seL4_Uint8 priority, seL4_Uint8 group, - seL4_Uint8 index); - void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq); - seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg); - void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value); - void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response); - - -### `void init(void)` - -Every PD must expose an `init` entry point. -This is called by the system at boot time. - -### `void notified(microkit_channel ch)` - -The `notified` entry point is called by the system when a PD has received a notification on a channel. - -`ch` identifies the channel which has been notified (and indirectly the PD that performed the notification). - -**Note:** `ch` could identify an interrupt. - -Channel identifiers are specified in the system configuration. - -### `microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo)` - -The `protected` entry point is optional. -This is invoked when another PD calls `microkit_ppcall` on a channel shared with the PD. - -The `ch` argument identifies the channel on which the PP was invoked. -Indirectly this identifies the PD performing the call. -Channel identifiers are specified in the system configuration. -**Note:** The channel argument is passed by the system and is unforgeable. - -The `msginfo` argument is the argument passed to the PP and is provided by the calling PD. -The contents of the message is up to a pre-arranged protocol between the PDs. -The message contents are opaque to the system. -Note: The message is *copied* from the caller. - -The returned `microkit_msginfo` is the return value of the protected procedure. -As with arguments, this is *copied* to the caller. - -### `seL4_Bool fault(microkit_child child, microkit_msginfo msginfo, microkit_msginfo *reply_msginfo)` - -The `fault` entry point being invoked depends on whether the given PD has children. -It is invoked when a child PD or VM causes a fault. - -The `child` argument identifies the child that caused the fault. - -The `msginfo` argument is given by the seL4 kernel when a fault occurs and contains information -as to what fault occurred. - -The `reply_msginfo` argument is given by libmicrokit and can be used to reply to the fault. - -The returned `seL4_Bool` is whether or not to reply to the fault with the message `reply_msginfo`. -Returning `seL4_True` will reply to the fault. Returning `seL4_False` will not reply to the fault. - -You can use `microkit_msginfo_get_label` on `msginfo` to deduce what kind of fault happened -(for example, whether it was a user exception or a virtual memory fault). - -Whether or not you reply to the fault depends on the type of fault that has occurred and how you want -to handle it. - -To find the full list of possible faults that could occur and details regarding to replying to a particular -kind of fault, please see the 'Faults' section of the -[seL4 reference manual](https://sel4.systems/Info/Docs/seL4-manual-latest.pdf). - -### `microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo)` - -Performs a call to a protected procedure in a different PD. -The `ch` argument identifies the protected procedure to be called. -`msginfo` is passed as argument to the protected procedure. -Channel identifiers are specified in the system configuration. - -The protected procedure's return data is returned in the `microkit_msginfo`. - -### `void microkit_notify(microkit_channel ch)` - -Notify the channel `ch`. -Channel identifiers are specified in the system configuration. - -### `void microkit_irq_ack(microkit_channel ch)` - -Acknowledge the interrupt identified by the specified channel. - -### `void microkit_deferred_notify(microkit_channel ch)` - -The same as `microkit_notify` but will instead not actually perform the notify until -the entry point where `microkit_deferred_notify` was called returns. - -It is important to note that only a single 'deferred' API call can be made within the -same entry point. - -The purpose of this API is for performance critical code as this API saves -a kernel system call. - -### `void microkit_deferred_irq_ack(microkit_channel ch)` - -The same as `microkit_irq_ack` but will instead not actually perform the IRQ acknowledge -until the entry point where `microkit_deferred_irq_ack` was called returns. - -It is important to note that only a single 'deferred' API call can be made within the -same entry point. - -The purpose of this API is for performance critical code as this API saves -a kernel system call. - -### `void microkit_pd_restart(microkit_child pd, uintptr_t entry_point)` - -Restart the execution of a child protection domain with ID `pd` at the given `entry_point`. -This will set the program counter of the child protection domain to `entry_point`. - -### `void microkit_pd_stop(microkit_child pd)` - -Stop the execution of the child protection domain with ID `pd`. - -### `microkit_msginfo microkit_msginfo_new(uint64_t label, uint16_t count)` - -Creates a new message structure. - -The message can be passed to `microkit_ppcall` or returned from `protected`. - -### `uint64_t microkit_msginfo_get_label(microkit_msginfo msginfo)` - -Returns the label from a message. - -### `uint64_t microkit_msginfo_get_count(microkit_msginfo msginfo)` - -Returns the count of message registers in the message. - -### `uint64_t microkit_mr_get(uint8_t mr)` - -Get a message register. - -### `void microkit_mr_set(uint8_t mr, uint64_t value)` - -Set a message register. - -### `void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point)` - -Restart the execution of a VM's virtual CPU with ID `vcpu` at the given `entry point`. -This will set the program counter of the vCPU to `entry_point`. - -### `void microkit_vcpu_stop(microkit_child vcpu)` - -Stop the execution of the VM's virtual CPU with ID `vcpu`. - -### `void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq, -seL4_Uint8 priority, seL4_Uint8 group, -seL4_Uint8 index)` - -Inject a virtual ARM interrupt for a virtual CPU `vcpu` with IRQ number `irq`. -The `priority` (0-31) determines what ARM GIC (generic interrupt controller) -priority level the virtual IRQ will be injected as. The `group` determines whether -the virtual IRQ will be injected into secure world (1) or non-secure world (0). -The `index` is the index of the virtual GIC list register. - -### `void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq)` - -Acknowledge a ARM virtual Private Peripheral Interrupt (PPI) with IRQ number `irq` -for a VM's vCPU with ID `vcpu`. - -### `seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg)` - -Read a register for a given virtual CPU with ID `vcpu`. The `reg` argument is the index of the -register that is read. The list of registers is defined by the enum `seL4_VCPUReg` -in the seL4 source code. - -### `void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value)` - -Write to a register for a given virtual CPU with ID `vcpu`. The `reg` argument is the index of the -register that is written to. The `value` argument is what the register will be set to. -The list of registers is defined by the enum `seL4_VCPUReg` in the seL4 source code. - -### `void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response)` - -This API is available only on ARM and only when seL4 has been configured to enable the -`KernelAllowSMCCalls` option. - -The API takes in arguments for a Secure Monitor Call which will be performed by seL4. Any -response values will be placed into the `response` structure. - -The `seL4_ARM_SMCContext` structure contains fields for registers x0 to x7. - -## System Description File {#sysdesc} - -This section describes the format of the System Description File (SDF). - -The system description file is an XML file that is provided as input to the -`microkit` tool. - -The root element of the XML file is `system`. - -Within the `system` root element the following child elements are supported: - -* `protection_domain` -* `memory_region` -* `channel` - -### `protection_domain` - -The `protection_domain` element describes a protection domain. - -It supports the following attributes: - -* `name`: A unique name for the protection domain -* `priority`: The priority of the protection domain (integer 0 to 254). -* `budget`: (optional) The PD's budget in microseconds; defaults to 1,000. -* `period`: (optional) The PD's period in microseconds; must not be smaller than the budget; defaults to the budget. -* `passive`: (optional) Indicates that the protection domain will be passive and thus have its scheduling context removed after initialisation; defaults to false. -* `stack_size`: (optional) Number of bytes that will be used for the PD's stack. - Must be be between 4KiB and 16MiB and be 4K page-aligned. Defaults to 4KiB. -* `smc`: (optional, only on ARM) Allow the PD to give an SMC call for the kernel to perform. Only available when the kernel has been configured with `KernelAllowSMCCalls`. Defaults to false. - -Additionally, it supports the following child elements: - -* `program_image`: (exactly one) Describes the program image for the protection domain. -* `map`: (zero or more) Describes mapping of memory regions into the protection domain. -* `irq`: (zero or more) Describes hardware interrupt associations. -* `setvar`: (zero or more) Describes variable rewriting. -* `protection_domain`: (zero or more) Describes a child protection domain. -* `virtual_machine`: (zero or one) Describes a child virtual machine. - -The `program_image` element has a single `path` attribute describing the path to an ELF file. - -The `map` element has the following attributes: - -* `mr`: Identifies the memory region to map. -* `vaddr`: Identifies the virtual address at which to map the memory region. -* `perms`: Identifies the permissions with which to map the memory region. Can be a combination of `r` (read), `w` (write), and `x` (eXecute), with the exception of a write-only mapping (just `w`). -* `cached`: (optional) Determines if mapped with caching enabled or disabled. Defaults to `true`. -* `setvar_vaddr`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the virtual address of the memory region. -* `setvar_size`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the size of the memory region. - -The `irq` element has the following attributes: - -* `irq`: The hardware interrupt number. -* `id`: The channel identifier. Must be at least 0 and less than 63. -* `trigger`: (optional) Whether the IRQ is edge triggered ("edge") or level triggered ("level"). Defaults to "level". - -The `setvar` element has the following attributes: - -* `symbol`: Name of a symbol in the ELF file. -* `region_paddr`: Name of an MR. The symbol's value shall be updated to this MR's physical address. - -The `protection_domain` element has the same attributes as any other protection domain as well as: - -* `id`: The ID of the child for the parent to refer to. - -The `virtual_machine` element has the following attributes: - -* `name`: A unique name for the virtual machine -* `priority`: The priority of the virtual machine (integer 0 to 254). -* `budget`: (optional) The VM's budget in microseconds; defaults to 1,000. -* `period`: (optional) The VM's period in microseconds; must not be smaller than the budget; defaults to the budget. - -Additionally, it supports the following child elements: - -* `vcpu`: (one or more) Describes the virtual CPU that will be tied to the virtual machine. -* `map`: (zero or more) Describes mapping of memory regions into the virtual machine. - -The `vcpu` element has a single `id` attribute defining the identifier used for the virutal machine's vCPU. - -The `map` element has the same attributes as the protection domain with the exception of `setvar_vaddr`. - -### `memory_region` - -The `memory_region` element describes a memory region. - -It supports the following attributes: - -* `name`: A unique name for the memory region -* `size`: Size of the memory region in bytes (must be a multiple of the page size) -* `page_size`: (optional) Size of the pages used in the memory region; must be a supported page size if provided. Defaults to the largest page size for the target architecture that the memory region is aligned to. -* `phys_addr`: (optional) The physical address for the start of the memory region (must be a multiple of the page size). - -The `memory_region` element does not support any child elements. - -#### Page sizes by architecture - -Below are the available page sizes for each architecture that Microkit supports. - -##### AArch64 - -* 0x1000 (4KiB) -* 0x200000 (2MiB) - -##### RISC-V 64-bit - -* 0x1000 (4KiB) -* 0x200000 (2MiB) - -### `channel` - -The `channel` element has exactly two `end` children elements for specifying the two PDs associated with the channel. - -The `end` element has the following attributes: - -* `pd`: Name of the protection domain for this end. -* `id`: Channel identifier in the context of the named protection domain. Must be at least 0 and less than 63. -* `pp`: (optional) Indicates that the protection domain for this end can perform a protected procedure call to the other end; defaults to false. - Protected procedure calls can only be to PDs of strictly higher priority. -* `notify`: (optional) Indicates that the protection domain for this end can send a notification to the other end; defaults to true. - -The `id` is passed to the PD in the `notified` and `protected` entry points. -The `id` should be passed to the `microkit_notify` and `microkit_ppcall` functions. - -## Board Support Packages {#bsps} - -This chapter describes the board support packages that are available in the SDK. - -### Ariane (CVA6) {#ariane} - -Initial support is available for the CVA6 (formerly Ariane) core design -on the Digilent Genesys2 board. CVA6 is an open-source RISC-V (rv64i) processor. - -Microkit support expects that a compatible RISC-V SBI (e.g OpenSBI) has executed before -jumping to the beginning of the loader image. - -Note that the loader link address is 0x90000000 and this is where the binary must -be located and where OpenSBI (or U-Boot) should begin execution. - -You may compile OpenSBI with the Microkit image as a payload, or alternately install -OpenSBI (with U-Boot optionally) to the SD card. - -If you are booting from U-Boot, use the following command to start the system image: - => go 0x90000000 - -Note that the OpenSBI version from the CVA6 SDK at the time of writing has issues when -booting. It is recommended to use the mainline OpenSBI. - -### Cheshire {#cheshire} - -Support is available for [Cheshire](https://github.com/pulp-platform/cheshire). -It is an SoC design based on the CVA6 core, implementing a 64-bit RISC-V CPU. - -Microkit outputs a raw binary for this device. Several steps are required in order to boot. - -A custom version of OpenSBI is required. It can be found -[here](https://github.com/pulp-platform/opensbi/tree/cheshire). -Build the firmware payload using platform `fpga/cheshire`. - -#### Using U-Boot - -With a system pre-configured with the Cheshire ZSBL, OpenSBI and U-boot: - - => go 0x90000000 - -#### Raw systerm with no bootloader - -Without any firmware present on the SD card, it is still possible to boot Cheshire with a Microkit system. - -Using a GDB prompt via openOCD: - -1. Reset board - - => monitor reset halt - -2. Load a device tree blob (DTS available in Cheshire repo or seL4) to memory and set the a0 and a1 registers to point at it: - - > restore /path/to/cheshire.dtb binary 0xa0000000 - -(tell OpenSBI where DTB is) - - > set $a0=0xa0000000 - -(tell OpenSBI that the default hart is #0) - - > set $a1=0 - -3. Load OpenSBI - - > load /path/to/opensbi/fw_payload.elf - -4. Allow OpenSBI to boot, and interrupt it once the line `Test payload running` is emitted on serial. - - > continue - -(wait for output) - - > (Ctrl+C) - -5. Load Microkit image and execute - - > restore /path/to/loader.img binary 0x90000000 - -(execute) - - > continue - -### i.MX8MM-EVK {#imx8mm_evk} - -Microkit produces a raw binary file, so when using U-Boot you must execute the image using: - - => go 0x41000000 - -### i.MX8MP-EVK {#imx8mp_evk} - -Microkit produces a raw binary file, so when using U-Boot you must execute the image using: - - => go 0x41000000 - -### i.MX8MQ-EVK {#imx8mq_evk} - -Microkit produces a raw binary file, so when using U-Boot you must execute the image using: - - => go 0x41000000 - -### MaaXBoard {#maaxboard} - -The MaaXBoard is a low-cost ARM SBC based on the NXP i.MX8MQ system-on-chip. - -Microkit produces a raw binary file, so when using U-Boot you must execute the image using: - - => go 0x50000000 - -### Odroid-C2 {#odroidc2} - -The HardKernel Odroid-C2 is an ARM SBC based on the Amlogic Meson S905 system-on-chip. It -should be noted that the Odroid-C2 is no longer available for purchase but its successor, -the Odroid-C4, is readily available at the time of writing. - -Microkit produces a raw binary file, so when using U-Boot you must execute the image using: - - => go 0x20000000 - -### Odroid-C4 {#odroidc4} - -The HardKernel Odroid-C4 is an ARM SBC based on the Amlogic Meson S905X3 system-on-chip. - -Microkit produces a raw binary file, so when using U-Boot you must execute the image using: - - => go 0x20000000 - -### QEMU virt (AArch64) {#qemu_virt_aarch64} - -Support is available for the virtual AArch64 QEMU platform. This is a platform that is not based -on any specific SoC or hardware platform and is intended for simulating systems for -development or testing. - -It should be noted that the platform support is configured with 2GB of main memory and a single -Cortex-A53 CPU. - -You can use the following command to simulate a Microkit system: - - $ qemu-system-aarch64 \ - -machine virt,virtualization=on \ - -cpu cortex-a53 \ - -nographic \ - -serial mon:stdio \ - -device loader,file=[SYSTEM IMAGE],addr=0x70000000,cpu-num=0 \ - -m size=2G - -You can find more about the QEMU virt platform in the -[QEMU documentation](https://www.qemu.org/docs/master/system/target-arm.html). - -### QEMU virt (RISC-V 64-bit) {#qemu_virt_riscv64} - -Support is available for the virtual RISC-V (64-bit) QEMU platform. -This is a platform that is not based on any specific SoC or hardware platform -and is intended for simulating systems for development or testing. - -It should be noted that the platform support is configured with 2GB of main memory. - -You can use the following command to simulate a Microkit system: - - $ qemu-system-riscv64 \ - -machine virt \ - -nographic \ - -serial mon:stdio \ - -kernel [SYSTEM IMAGE] \ - -m size=2G - -QEMU will start the system image using its packaged version of OpenSBI. - -You can find more about the QEMU virt platform in the -[QEMU documentation](https://www.qemu.org/docs/master/system/target-riscv.html). - -### Raspberry Pi 4B {#rpi4b_1gb} - -Support is available for the Raspberry Pi 4 Model B. There are multiple models of the -Rasberry Pi 4B that have different amounts of RAM, we target the 1GB model in Microkit. -If you require more than 1GB, please file an issue or pull request to add support for -models with larger amounts of memory. - -For initial board setup, please see the instructions on the -[seL4 website](https://docs.sel4.systems/Hardware/Rpi4.html). - -When getting into the U-Boot console you want to load the Microkit binary image to -address 0x10000000 and then run `go 0x10000000`. - -For example, if you were to load the image via the MMC you would run the following -U-Boot commands: - - => fatload mmc 0 0x10000000 - => go 0x10000000 - -### Pine64 ROCKPro64 {#rockpro64} - -Microkit produces a raw binary file, so when using U-Boot you must execute the image using: - - => go 0x30000000 - -### Pine64 Star64 {#star64} - -Support is available for the Pine64 Star64 platform which is based on the -StarFive JH7110 SoC. - -The platform has a 4GB and 8GB model, we assume the 4GB model. - -The default boot flow of the Star64 is: -1. OpenSBI -2. U-Boot -3. Operating System - -This means that the system image that Microkit produces does not need to be explicitly -packaged with an SBI implementation such as OpenSBI. - -To execute the system image produced by Microkit, execute the following command in U-Boot: - - => go 0x60000000 - -### TQMa8XQP 1GB {#tqma8xqp1gb} - -The TQMa8XQP is a system-on-module designed by TQ-Systems GmbH. -The modules incorporates an NXP i.MX8X Quad Plus system-on-chip and 1GiB ECC memory. - -TQ-Systems provide the MBa8Xx carrier board for development purposes. -The instructions provided assume the use of the MBa8Xx carrier board. -If you are using a different carrier board please refer to the appropriate documentation. - -Note: There are different configured of the TQMa8Xx board which include different NXP SoCs -and different memory configurations. Such modules are not supported. - -The MBa8Xx provides access to the TQMa8XQP UART via UART-USB bridge. -To access the UART connect a USB micro cable to port **X13**. -The UART-USB bridge supports 4 individual UARTs; the UART is connected to the 2nd port. - -By default the SoM will autoboot using U-Boot. -Hit any key during the boot process to stop the autoboot. - -A new board will autoboot to Linux. -You will likely want to disable autoboot: - - => env set bootdelay -1 - => env save - -The board can be reset by pressing switch **S4** (located next to the Ethernet port). -Alternatively, you can use the `reset` command from the U-Boot prompt. - -During development the most convenient way to boot a Microkit image is via network booting. -U-Boot support booting via the *tftp* protocol. -To support this you'll want to configure the network. -U-Boot supports DHCP, however it is often more reliable to explicitly set an IP address. -For example: - - => env set ipaddr 10.1.1.2 - => env set netmask 255.255.255.0 - => env set serverip 10.1.1.1 - => env save - -To use tftp you also need to set the file to load and the memory address to load it to: - - => env set bootfile loader.img - => env set loadaddr 0x80280000 - => env save - -The system image generated by the Microkit tool is a raw binary file. - -An example sequence of commands for booting is: - - => tftpboot - => dcache flush - => icache flush - => go ${loadaddr} - -Rather than typing these each time you can create a U-Boot script: - - => env set microkit 'tftpboot; dcache flush; icache flush; go ${loadaddr}' - => env save - => run microkit - -When debugging is enabled the kernel will use the same UART as U-Boot. - -### ZCU102 {#zcu102} - -The ZCU102 can run on a physical board or on an appropriate QEMU based emulator. - -Microkit produces a raw binary file, so when using U-Boot you must execute the image using: - - => go 0x40000000 - -For simulating the ZCU102 using QEMU, use the following command: - - $ qemu-system-aarch64 \ - -m size=4G \ - -machine xlnx-zcu102,virtualization=on \ - -nographic \ - -device loader,file=[SYSTEM IMAGE],addr=0x40000000,cpu-num=0 \ - -serial mon:stdio - -It should be noted that when using U-Boot to load and run a Microkit system image, -that there may be additional setup needed. - -For the ZynqMP class of platforms, which the ZCU102 is apart of, U-Boot does not start -the Microkit system Exception Level 2 (EL2) which is necessary for Microkit to start -(this is because seL4 is configured as a hypervisor). - -You can see that when using the `go` command, U-Boot is -[unconditionally always dropping down to EL1](https://github.com/u-boot/u-boot/blob/8937bb265a7f2251c1bd999784a4ef10e9c6080d/board/xilinx/zynqmp/zynqmp.c#L234). - -To avoid this behaviour, the call to `armv8_switch_to_el1` should be replaced with -`armv8_switch_to_el2` in this `do_go_exec` function. - -### Adding Platform Support - -The following section is a guide for adding support for a new platform to Microkit. - -#### Prerequisites - -Before you can start with adding platform support to Microkit, the platform must be supported by the seL4 kernel. -You can find information on how to do so [here](https://docs.sel4.systems/projects/sel4/porting.html). - -#### Getting Microkit Components Working - -The first step to adding Microkit support is to modify the `build_sdk.py` script in order to build the required -artefacts for the new platform. This involves adding to the `SUPPORTED_BOARDS` list with the `BoardInfo` options -containing the platform specific attributes. This should be fairly self-explanatory by looking at the existing -entries with the exception of the `loader_link_address`. - -The `loader_link_address` parameter specifies the physical address of where the bootloader for Microkit (which -is responsible for setting up the system before seL4 starts) is going to be loaded. This address needs to -match where in main memory the final system image is actually loaded (e.g where a previous bootloader such as U-Boot -loads the image to). This means that the address is restricted to the platform's main memory region. - -The other component of Microkit that is platform dependent is the loader itself. The loader will attempt to access -the UART for debug output which requires a basic `putc` implementation. The UART device used in the loader should be -the same as what is used for the seL4 kernel debug output. - -It should be noted that on RISC-V platforms, the SBI will be used for `putc` so no porting is necessary. - -Once you have patched the loader and the SDK build script, there should be no other changes required to have a working -platform port. It is a good idea at this point to boot a hello world system to confirm the port is working. - -If there are issues with porting the platform, please [open an issue on GitHub](https://github.com/sel4/microkit). - -#### Contributing Platform Support - -Once you believe that the port works, you can [open a pull request](https://github.com/seL4/microkit/pulls) with required -changes as well as documentation in the manual about the platform and how to run Microkit images on it. - -## Rationale - -This section describes the rationales driving the Microkit design choices. - -### Overview - -The seL4 microkernel provides a set of powerful and flexible mechanisms that can be used for building almost arbitrary systems. -While minimising constraints on the nature of system designs and scope of deployments, this flexibility makes it challenging to design the best system for a particular use case, requiring extensive seL4 experience from developers. - -The Microkit addresses this challenge by constraining the -system architecture to one that provides enough features and power for -its target usage class (IoT, cyberphysical and other embedded systems -with a static architecture), enabling a much simpler set of developer-visible abstractions. - -### Protection Domains - -PDs are single-threaded to keep the programming model and implementations simple, and because this serves the needs of most present use cases in the target domains. -Extending the model to multithreaded applications (clients) is straightforward and can be done if needed. -Extending to multithreaded services is possible but requires additional infrastructure for which we see no need in the near future. - -### Protected Procedure Priorities - -The restriction of only calling to higher priority prevents deadlocks and reflects the notion that the callee operates on behalf of the caller, and it should not be possible to preempt execution of the callee unless the caller could be preempted as well. - -This greatly simplifies reasoning about real-time properties in the system; in particular, it means that PPs can be used to implement *resource servers*, where shared resources are encapsulated in a component that ensures mutual exclusion, while avoiding unbounded priority inversions through the *immediate priority ceiling protocol*. - -While it would be possible to achieve the same by allowing PPs between PDs of the same priority, this would be much harder to statically analyse for loop-freedom (and thus deadlock-freedom). -The drawback is that we waste a part of the priority space where a logical entity is split into multiple PDs, eg to separate out a particularly critical component to formally verify it, when the complete entity would be too complex for formal verification. -For the kinds of systems targeted by the Microkit, this reduction of the usable priority space is unlikely to cause problems. - -### Protected Procedure Argument Size - -The limitation on the size of by-value arguments is forced by the (architecture-dependent) limits on the payload size of the underlying seL4 operations, as well as by efficiency considerations. -The protected procedure payload should be considered as analogous to function arguments in the C language; similar limitations exist in the C ABIs (Application Binary Interfaces) of various platforms. - -### Limits - -The limitation on the number of protection domains in the system is relatively arbitrary. -Based on experience with the system and the types of systems being built it is possible for this to be increased in the future. - -The limitation on the number of channels for a protection domain is based on the size of the notification word in seL4. -Changing this to be larger than 64 would most likely require changes to seL4. The reason for why the limit is not a -power of two is due to part of the notification word being for internal libmicrokit use. - -## Internals - -The following section describes internal details for how the Microkit works -and all the components of Microkit. As a user of Microkit, it is not necessary -know this information, however, there is no harm in having a greater -understanding of the tools that you are using. - -![Microkit flow](assets/microkit_flow.svg) - -The diagram above aims to show the general flow of a Microkit system from -build-time to run-time. - -The user provides the SDF (System Description File) and the ELFs that -correspond to PD program images to the Microkit tool which is responsible to -for packaging everything together into a single bootable image for the target -platform. - -This final image contains a couple different things: - -* the Microkit loader -* seL4 -* the Monitor (and associated invocation data) -* the images for all the user's PDs - -When booting the image, the Microkit loader starts, jumps to the kernel, which -starts the monitor, which then sets up the entire system and starts all the PDs. - -Now, we will go into a bit more detail about each of these stages of the -booting process as well as what exactly the Microkit tool is doing. - -### Loader - -The loader starts first, it has two main jobs: - -1. Unpack all the parts of the system (kernel, monitor, PD images, etc) into - their expected locations within main memory. -2. Finish initialising the hardware such that the rest of the system can start. - -Unpacking the system image is fairly straight-forward, as all the information -about what parts of the system image need to go where is figured out by the -tool and embedded into the loader at build-time so when it starts it just goe -through an array and copies data into the right locations. - -Before the Microkit loader starts, there would most likely have been some other -bootloader such as U-Boot or firmware on the target that did its own hardware -initialisation before starting Microkit. - -However, there are certain things that seL4 expects to be initialised -that will not be done by a previous booting stage, such as: - -* changing to the right exception level -* enabling the MMU (seL4 expects the MMU to be on when it starts) -* interrupt controller setup - -Once this is all completed, the loader jumps to seL4 which starts executing. -The loader will never be executed again. - -### Monitor - -Once the kernel has done its own initialisation, it will begin the -'initial task'. On seL4, this is a thread that contains all the initial -capabilities to resources that are used to setup the rest of the system. - -Within a Microkit environment, we call the initial task the 'monitor'. - -The monitor has two main jobs: - -1. Setup all system resources (memory regions, channels, interrupts) and start - the user's protection domains. -2. Receive any faults caused by protection domains crashing or causing - exceptions. - -At build-time, the Microkit tool embeds all the system calls that the monitor -needs to make in order to setup the user's system. More details about *how* -this is done is in the section on the Microkit tool below. But from the -monitor's perspective, it just iterates over an array of system calls to make -and performs each one. - -After the system has been setup, the monitor goes to sleep and waits for any -faults from protection domains. On debug mode, this results in a message about -which PD caused an exception and details on the PD's state at the time of the fault. - -Other than printing fault details, the monitor does not do anything to handle -the fault, it will simply go back to sleep waiting for any other faults. - -### libmicrokit {#libmicrokit_internals} - -Unlike the previous sections, libmicrokit is not its own program but it is worth -a mention since it makes up the core of each protection domain in a system. - -When each PD starts, we enter libmicrokit's starting point which does some initial -setup and calls the `init` entry point specified by the user. Once that completes, -the PD will enter libmicrokit's event handler which sleeps until it receives events. - -These events could be notifies (from other PDs or from an interrupt), PPCs, and faults. -For each event, the appropriate user-specified entry point is called and then when it -returns the PD goes back to sleep, waiting on any more events. - -### Microkit tool - -The Microkit tool's ultimate job is to take in the description of the user's system, -the SDF, and convert into an seL4 system that boots and executes. - -There are obvious steps such as parsing the SDF and PD ELFs but the majority of -the work done by the tool is converting the system description into a list of -seL4 system calls that need to happen. - -In order to do this however, the Microkit tool needs to perform o a decent amount of -'emulation' to know exactly what system calls and with which arguments to make. -This requires keeping track of what memory is allocated and where, the layout of -each capability space, what the initial untypeds list will look like, etc. - -While this is non-trivial to do, it comes with the useful property that if the tool -produces a valid image, there should be no errors upon initialising the system -If there are any errors with configuring the system (e.g running out of memory), -they will be caught at build-time. This can only reasonably be done due to the -static-architecture of Microkit systems. diff --git a/projects/microkit/manual/2.1.0/index.html b/projects/microkit/manual/2.1.0/index.html new file mode 100644 index 00000000000..f56fa245305 --- /dev/null +++ b/projects/microkit/manual/2.1.0/index.html @@ -0,0 +1,2641 @@ + + + + + + + Microkit User Manual (v2.1.0) | seL4 docs + + + + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit User Manual (v2.1.0)

+ +

This is a web version of the manual, you can find a PDF here as well as in the +SDK at doc/microkit_user_manual.pdf.

+ +

Introduction

+ +

The seL4 Microkit is a small and simple operating system (OS) built on the seL4 microkernel. +Microkit is designed for building system with a static architecture. +A static architecture is one where system resources are assigned up-front at system initialisation time.

+ +

Purpose

+ +

The Microkit is intended to:

+ +
    +
  • provide a small and simple OS for a wide range of IoT, cyberphysical and other embedded use cases;
    • +
  • provide a reasonable degree of application portability appropriate for the targeted use cases;
    • +
  • make seL4-based systems easy to develop and deploy within the target areas;
    • +
  • leverage seL4’s strong isolation properties to support a near-minimal trusted computing base (TCB);
    • +
  • retain seL4’s trademark performance for systems built with it;
    • +
  • be, in principle, amenable to formal analysis of system safety and security properties (although such analysis is beyond the initial scope).
    • +
+ +

Overview

+ +

A Microkit system is built from a set of individual programs that are isolated from each other, and the system, in protection domains. +Protection domains can interact by calling protected procedures or sending notifications.

+ +

Microkit is distributed as a software development kit (SDK). +The SDK includes the tools, libraries and binaries required to build a Microkit system. +The Microkit source is also available which allows you to customize or extend Microkit and produce your own SDK.

+ +

To build a Microkit system you will write some programs that use libmicrokit. +Microkit programs are a little different to a typical process on a Linux-like operating system. +Rather than a single main entry point, a program has four distinct entry points: init, notified and, potentially, protected, fault.

+ +

On ARM and RISC-V, the individual programs are combined to produce a single bootable system image. +The format of the image is suitable for loading by the target board’s bootloader.

+ +

On x86-64, there are two ELF images invovled. One for the seL4 kernel, and one for the initialiser that +setups up the Microkit system. These are loaded by a Multiboot 2 compliant bootloader.

+ +

The Microkit tool, which is provided as part of the SDK, is used to generate the system image(s).

+ +

The Microkit tool takes a system description as input. +The system description is an XML file that specifies all the objects that make up the system.

+ +

Note: Microkit does not impose any specific build system; you are free to choose the build system that works best for you.

+ +

Document Structure

+ +

The Concepts chapter describes the various concepts that make up Microkit. +It is recommended that you familiarise yourself with these concepts before trying to build a system.

+ +

The SDK chapter describes the software development kit, including its components and system requirements for use.

+ +

The Microkit tool chapter describes the host system tool used for generating a system image from the system description and user-programs.

+ +

The libmicrokit chapter describes the interfaces to the Microkit library.

+ +

The System Description File chapter describes the format of the system description XML file.

+ +

The Board Support Packages chapter describes each of the board support packages included in the SDK.

+ +

The Rationale chapter documents the rationale for some of the key design choices of Microkit.

+ +

The Internals chapter documents some of the internal details for how Microkit works.

+ +

Concepts

+ +

This chapter describes the key concepts provided by Microkit.

+ +

As with any set of concepts there are words that take on special meanings. +This document attempts to clearly describe all of these terms, however as the concepts are inter-related it is sometimes necessary to use a term prior to its formal introduction.

+ + + +

System

+ +

At the most basic level Microkit provides the platform for running a system on a specific board. +As a user of Microkit you use the platform to create a software system that implements your use case. +The system is described in a declarative configuration file, and the Microkit tool takes this system description as an input and produces an appropriate system image that can be loaded on the target board.

+ +

The key elements that make up a system are protection domains, memory regions and channels.

+ +

Protection Domains

+ +

A protection domain (PD) is the fundamental runtime abstraction in Microkit. +It is analogous, but very different in detail, to a process on a UNIX system.

+ +

A PD provides a thread of control that executes within a fixed virtual address space. +The isolation provided by the virtual address space is enforced by the underlying hardware MMU.

+ +

The virtual address space for a PD has mappings for the PD’s program image along with any memory regions that the PD can access. +The program image is an ELF file containing the code and data which implements the isolated component.

+ +

Microkit supports a maximum of 63 protection domains.

+ +

Entry points

+ +

Although a protection domain is somewhat analogous to a process, it has a considerably different program structure and life-cycle. +A process on a typical operating system will have a main function which is invoked by the system when the process is created. +When the main function returns the process is destroyed.

+ +

By comparison a protection domain has up to four entry points:

+ +
    +
  • init, notified which are required.
    • +
  • protected which is optional.
    • +
  • fault which is required if the PD has children.
    • +
+ +

When a Microkit system is booted, all PDs in the system execute the init entry point.

+ +

A PD will not execute any other entry point until init has finished.

+ +

If a PD is currently executing an entry point, it will not execute any other entry point +until the current entry point has finished.

+ +

The notified entry point will be invoked whenever the protection domain receives a notification on a channel. +The protected entry point is invoked when a PD’s protected procedure is called by another PD. +A PD does not have to provide a protected procedure, therefore the protected entry point is optional.

+ +

The fault entry point is invoked when a PD that is a child of another PD causes a fault. +A PD does not have to have child PDs, therefore the fault entry point is only required for a parent PD.

+ +

These entry points are described in more detail in subsequent sections.

+ +

Note: The processing of init entry points is not synchronised across protection domains. +Specifically, it is possible for a high priority PD’s notified or protected entry point to be called prior to the completion of a low priority PD’s init entry point.

+ +

The overall computational model for a Microkit system is a set of isolated components reacting to incoming events.

+ +

Scheduling

+ +

The PD has a number of scheduling attributes that are configured in the system description:

+ +
    +
  • priority (0 – 254)
    • +
  • period (microseconds)
    • +
  • budget (microseconds)
    • +
  • passive (boolean)
    • +
+ +

The budget and period bound the fraction of CPU time that a PD can consume. +Specifically, the budget specifies the amount of time for which the PD is allowed to execute. +Once the PD has consumed its budget, it is no longer runnable until the budget is replenished; replenishment happens once every period and resets the budget to its initial value. +This means that the maximum fraction of CPU time the PD can consume is $\frac{budget}{period}$.

+ +

The budget cannot be larger than the period. +A budget that equals the period (aka. a “full” budget) behaves like a traditional time slice: After executing for a full period, the PD is preempted and put at the end of the scheduling queue of its priority. In other words, PDs with equal priorities and full budgets are scheduled round-robin with a time slice defined by the period.

+ +

The priority determines which of the runnable PDs to schedule. A PD is runnable if one of its entry points has been invoked and it has budget remaining in the current period. +Runnable PDs of the same priority are scheduled in a round-robin manner.

+ +

Passive determines whether the PD is passive. A passive PD will have its scheduling context revoked after initialisation and then bound instead to the PD’s notification object. This means the PD will be scheduled on receiving a notification, whereby it will run on the notification’s scheduling context. When the PD receives a protected procedure by another PD or a fault caused by a child PD, the passive PD will run on the scheduling context of the callee.

+ +

Virtual Machines

+ +

A virtual machine (VM) is a runtime abstraction for running guest operating systems in Microkit. It is similar +to a protection domain in that it provides a thread of control that executes within an isolated virtual address space.

+ +

The main difference between a VM and a PD is that VMs have a higher privilege level such that they may function as a +guest operations and have their own user-space programs at a separate exception level.

+ +

The virtual machine is always a child of a PD. Exceptions caused by the virtual machine are delivered to the parent PD +through the fault entry point.

+ +

Each virtual machine has a number of ‘virtual CPU’s associated with it. Each virtual CPU (vCPU) that belongs to a +virtual machine has its own thread of execution. A vCPU also has an identifier which is used to know which vCPU caused +the invocation of the fault entry point.

+ +

The parent PD is responsible for starting and managing the virtual machine. Microkit provides the abstractions in +order to manage the virtual machine through seL4 but there is typically a non-trivial amount +of supporting code/infrastructure to properly start and manage a VM.

+ +

To keep the (potentially untrusted) virtual machine isolated from the rest of the system, Microkit enforces that a +protection domain can only ever manage a single virtual machine.

+ +

Memory Regions

+ +

A memory region is a contiguous range of physical memory. +A memory region may have a fixed physical address. +For memory regions without a fixed physical address, the physical address is allocated as part of the build process. +Typically, memory regions with a fixed physical address represent memory-mapped device registers.

+ +

Memory regions that are within main memory are zero-initialised.

+ +

The size of a memory region must be a multiple of a supported page size. +The supported page sizes are architecture dependent. +For example, on AArch64 architectures, Microkit support 4KiB and 2MiB pages. +The page size for a memory region may be specified explicitly in the system description. +If page size is not specified, the largest supported page size is used.

+ +

Note: The page size also restricts the alignment of the memory region’s physical address. +A fixed physical address must be a multiple of the specified page size.

+ +

A memory region can be mapped into one or more protection domains. +The mapping has a number of attributes, which include:

+ +
    +
  • the virtual address at which the region is mapped in the PD
    • +
  • caching attributes (mostly relevant for device memory)
    • +
  • permissions (read, write and execute)
    • +
+ +

Note: When a memory region is mapped into multiple protection +domains, the attributes used for different mappings may vary.

+ +

Channels

+ +

A channel enables two protection domains to interact using protected procedures or notifications. +Each connects exactly two PDs; there are no multi-party channels.

+ +

When a channel is created between two PDs, a channel identifier is configured for each PD. +The channel identifier is used by the PD to reference the channel. +Each PD can refer to the channel with a different identifier. +For example if PDs A and B are connected by a channel, A may refer to the channel using an identifier of 37 while B may use 42 to refer to the same channel.

+ +

Note: There is no way for a PD to directly refer to another PD in the system. +PDs can only refer to other PDs indirectly if there is a channel between them. +In this case, the channel identifier is effectively a proxy identifier for the other PD. +So, to extend the prior example, A can indirectly refer to B via the channel identifier 37. +Similarly, B can refer to A via the channel identifier 42.

+ +

The system supports a maximum of 63 channels and interrupts per protection domain.

+ +

Protected procedures

+ +

A protection domain may provide a protected procedure (PP) which can be invoked from another protection domain. +Up to 64 words of data may be passed as arguments when calling a protected procedure. +The protected procedure return value may also be up to 64 words.

+ +

When a protection domain calls a protected procedure, the procedure executes within the context of the providing protection domain.

+ +

A protected call is only possible if the callee has strictly higher priority than the caller. +Transitive calls are possible, and as such a PD may call a protected procedure in another PD from a protected entry point. +However the overall call graph between PDs must form a directed, acyclic graph. +It follows that a PD can not call itself, even indirectly. +For example, A calls B calls C is valid (subject to the priority constraint), while A calls B calls A is not valid.

+ +

When a protection domain is called, the protected entry point is invoked. +The control returns to the caller when the protected entry point returns.

+ +

The caller is blocked until the callee returns. +Protected procedures must execute in bounded time. +It is intended that a future version of Microkit will enforce this condition through static analysis. +In the present version the caller must trust the callee to conform.

+ +

In general, PPs are provided by services for use by clients that trust the protection domain to provide that service.

+ +

To call a PP, a PD calls microkit_ppcall passing the channel identifier and a message structure. +A message structure is returned from this function.

+ +

When a PD’s protected procedure is invoked, the protected entry point is invoked with the channel identifier and message structure passed as arguments. +The protected entry point must return a message structure.

+ +

Notifications

+ +

A notification is a (binary) semaphore-like synchronisation mechanism. +For example, a PD can notify another PD to indicate availability of data in a shared memory region if they share a channel.

+ +

To notify another PD, a PD calls microkit_notify, passing the channel identifier. +When a PD receives a notification, the notified entry point is invoked with the appropriate channel identifier passed as an argument.

+ +

Unlike protected procedures, notifications can be sent in either direction on a channel regardless of priority.

+ +

Note: Notifications provide a mechanism for synchronisation between PDs, however this is not a blocking operation. +If a PD notifies another PD, that PD will become scheduled to run (if it is not already), but the current PD does not block. +Of course, if the notified PD has a higher priority than the current PD, then the current PD will be preempted (but not blocked) by the other PD.

+ +

Depending on the scheduling, one PD could notify another multiple times without it being scheduled, resulting +in a single execution of the notified entry point. For example, if PD A notifies PD B three times on the +same channel without PD B ever executing, once PD B is scheduled it would only see one notification and hence +only enter notified once for that channel.

+ +

Interrupts

+ +

Hardware interrupts can be used to notify a protection domain. +The system description specifies if a protection domain receives notifications for any hardware interrupt sources. +Each hardware interrupt is assigned a channel identifier. +In this way the protection domain can distinguish the hardware interrupt from other notifications. +A specific hardware interrupt can only be associated with at most one protection domain. It should be noted that once a +hardware interrupt has been received, it will not be received again until microkit_irq_ack is called. The seL4 kernel +will mask the hardware interrupt until it has been acknowledged.

+ +

Microkit does not provides timers, nor any sleep API. +After initialisation, activity in the system is initiated by an interrupt causing a notified entry point to be invoked. +That notified function may in turn notify or call other protection domains that cause other system activity, but eventually all activity indirectly initiated from that interrupt will complete, at which point the system is inactive again until another interrupt occurs.

+ +

Faults

+ +

Faults such as an invalid memory access or illegal instruction are delivered to the seL4 kernel which then forwards them to +a designated ‘fault handler’. By default, all faults caused by protection domains go to the system fault handler which +simply prints out details about the fault in a debug configuration.

+ +

When a protection domain is a child of another protection domain, the designated fault handler for the child is the parent +protection domain. The same applies for a virtual machine.

+ +

This means that whenever a fault is caused by a child, it will be delivered to the parent PD instead of the system fault +handler via the fault entry point. It is then up to the parent to decide how the fault is handled.

+ +

The default system fault handler (aka the monitor) has the highest priority and so will +execute and handle faults immediately after they occur. For child PDs that have their faults +delivered to another PD, the fault being handled depends on when the parent PD is scheduled.

+ +

I/O Ports

+ +

I/O ports are x86 mechanisms to access certain physical devices (e.g. PC serial ports or PCI) using the in and out CPU instructions. The system description specifies if a protection domain have access to certain port address ranges. These accesses will be executed by seL4 and the result returned to protection domains.

+ +

SDK

+ +

Microkit is distributed as a software development kit (SDK).

+ +

The SDK includes support for one or more boards. +Three configurations are supported for each board: debug, release, and benchmark. +See the Configurations section for more details.

+ +

The SDK contains:

+ +
    +
  • Microkit user manual (this document)
    • +
  • Microkit tool
    • +
+ +

Additionally, for each supported board configuration the following are provided:

+ +
    +
  • libmicrokit.a
    • +
  • initialiser.elf
    • +
  • monitor.elf
    • +
  • seL4 kernel image +
      +
    • On ARM/RISC-V: sel4.elf
      • +
    • On x86-64: sel4_64.elf (64-bit) and sel4_32.elf (32-bit)
      • +
    +
    • +
+ +

On ARM and RISC-V, an additional loader.elf is provided, which acts as the system’s bootloader.

+ +

On x86-64, 32-bit/64-bit variants of the kernel are provided as even on 64-bit platforms (e.g QEMU), +a 32-bit kernel is required.

+ +

There are also examples provided in the example directory.

+ +

The Microkit SDK does not provide, nor require, any specific build system. +The user is free to build their system using whatever build system is deemed most appropriate for their specific use case.

+ +

The Microkit tool should be invoked by the system build process to transform a system description (and any referenced program images) into an image file which can be loaded by the target board’s bootloader.

+ +

The ELF files provided as program images should be standard ELF files and have been linked against the provided libmicrokit.a.

+ +

Configurations

+ +

Debug

+ +

The debug configuration includes a debug build of the seL4 kernel to allow console debug output using the kernel’s UART driver.

+ +

Release

+ +

The release configuration is a release build of the seL4 kernel and is intended for production builds. The loader, monitor, initialiser and +kernel do not perform any serial output.

+ +
Proofs
+ +

The formal verification of seL4 applies to a specific set of seL4 configuration only. This means that making a release build +of a Microkit system does not imply that the seL4 kernel being used is verified.

+ +

Currently Microkit always uses the MCS configuration of seL4 which is still undergoing verification, scheduled to complete +for RISC-V in 2026 and AArch64 in 2027. The design proofs for MCS are done but the work to show that the kernel code conforms +to the design is still undergoing.

+ +

You can find more information about what verified seL4 configurations do exist +here

+ +

A roadmap for upcoming verification is available here.

+ +

Benchmark

+ +

The benchmark configuration uses a build of the seL4 kernel that exports the hardware’s performance monitoring unit (PMU) to PDs. +The kernel also tracks information about CPU utilisation. This benchmark configuration exists due a limitation of the seL4 kernel +and is intended to be removed once RFC-16 is implemented.

+ +

Multi-core (SMP) configurations

+ +

The configurations listed above default to using the uni-core configuration of seL4/Microkit. +Currently we do not want to default to using the multi-core configuration of the kernel so +separate configurations exist for users wanting to use multi-core.

+ +

The multi-core configurations are the same as the configurations listed above, except with the +smp- prefix. For example, smp-debug for the multi-core variant of debug.

+ +

On ARM/RISC-V, the number of cores available defaults to the number of cores the target board has.

+ +

On x86-64, the number of cores available depends on how many are detected at run-time. Right now +there is a fixed upper limit, see the board-specific documentation for details.

+ +

System Requirements

+ +

The Microkit tool requires Linux (x86-64 or AArch64), macOS (x86-64 or AArch64).

+ +

On Linux, the Microkit tool is statically linked and should run on any distribution.

+ +

On macOS, the Microkit tool should run on macOS 10.12 (Sierra) or higher.

+ +

The Microkit tool does not depend on any additional system binaries.

+ +

Microkit Tool

+ +

The Microkit tool is available in bin/microkit.

+ +

The Microkit tool takes as input a system description. +The format of the system description is described in a subsequent chapter.

+ +

Usage:

+ +
microkit [-h] [-o OUTPUT] [-r REPORT] [--capdl-json CAPDL_SPEC] [--image-type {binary,elf,uimage}]
+          --board [BOARD] --config CONFIG [--search-path [SEARCH_PATH ...]] system
+
+ +

The path to the system description file, board to build the system for, and configuration to build for must be provided.

+ +

The search paths provided tell the tool where to find any program images specified in the system description file.

+ +

In the case of errors, a diagnostic message shall be output to stderr and a non-zero code returned.

+ +

In the case of success, a loadable image file and a report shall be produced. The +type of image is specified by the --image-type argument. +The output paths for these can be specified by -o and -r respectively. +The default output paths are loader.img and report.txt.

+ +

The report is a plain text file describing important information about the system. +The report can be useful when debugging potential system problems. +This report does not have a fixed format and may change between versions. +It is not intended to be machine readable.

+ +

Image format

+ +

ARM

+ +

On ARM, the Microkit tool will produce either a raw binary that is intended to be loaded and jumped or +an ELF. By default, the tool will produce a raw binary unless the format is specified using the --image-type argument.

+ +

For the raw binary format, there is a specified entry point of the image that is documented in the board-specific +instructions in this manual, under Board Support Packages. If the image is not loaded at this address +it should still work by relocating itself upon boot.

+ +

This image is expected to be loaded via a previous bootloader, typically U-Boot using the go command for +the binary image format and the bootelf command for ELFs. Note when using bootelf you may need to set +the autostart environment variable with setenv autostart yes to have the image executed after bootelf.

+ +

See the board-specific instructions for more details.

+ +

RISC-V

+ +

On RISC-V, the Microkit tool can produce either a raw binary that is intended to be loaded and jumped, +a uImage with the Linux header or an ELF. Typically the tool will produce a uImage by default, for +board-specific details see Board Support Packages.

+ +

For the raw binary format, there is a specified entry point of the image that is documented in the board-specific +instructions in this manual, under Board Support Packages. If the image is not loaded at this address +it should still work by relocating itself upon boot.

+ +

For the uImage format. You may load this image anywhere in memory along with your platform’s DTB, then use +the bootm command in U-Boot. It will copy the loader to the correct location in memory and jump to it.

+ +

x86-64

+ +

On x86-64, the image format is always ELF, it is expected to be loaded as a Multiboot boot module.

+ +

See x86-64 generic support for more details.

+ +

Language Support

+ +

There are native APIs for C/C++ and Rust.

+ +

libmicrokit exports a C API and so can be used in any language +that supports C FFI.

+ +

For Rust, native bindings exist but are not included in the SDK itself. They are +available at rust-sel4.

+ +

libmicrokit

+ +

All program images should link against libmicrokit.a.

+ +

The library provides the C runtime for the protection domain, along with interfaces for the Microkit APIs.

+ +

The component must provide the following functions:

+ +
void init(void);
+void notified(microkit_channel ch);
+
+ +

If the protection domain provides a protected procedure it must also implement:

+ +
microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo);
+
+ +

If the protection domain has children it must also implement:

+ +
seL4_Bool fault(microkit_child child, microkit_msginfo msginfo,
+                microkit_msginfo *reply_msginfo);
+
+ +

libmicrokit provides the following functions:

+ +
microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo);
+void microkit_notify(microkit_channel ch);
+microkit_msginfo microkit_msginfo_new(seL4_Word label, seL4_Uint16 count);
+seL4_Word microkit_msginfo_get_label(microkit_msginfo msginfo);
+seL4_Word microkit_msginfo_get_count(microkit_msginfo msginfo);
+void microkit_irq_ack(microkit_channel ch);
+void microkit_deferred_notify(microkit_channel ch);
+void microkit_deferred_irq_ack(microkit_channel ch);
+void microkit_pd_restart(microkit_child pd, seL4_Word entry_point);
+void microkit_pd_stop(microkit_child pd);
+void microkit_mr_set(seL4_Uint8 mr, seL4_Word value);
+seL4_Word microkit_mr_get(seL4_Uint8 mr);
+void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point);
+void microkit_vcpu_stop(microkit_child vcpu);
+void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq,
+                                  seL4_Uint8 priority, seL4_Uint8 group,
+                                  seL4_Uint8 index);
+void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq);
+seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg);
+void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value);
+void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response);
+void microkit_x86_ioport_write_8(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data);
+void microkit_x86_ioport_write_16(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data);
+void microkit_x86_ioport_write_32(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data);
+seL4_Uint8 microkit_x86_ioport_read_8(microkit_ioport ioport_id, seL4_Word port_addr);
+seL4_Uint16 microkit_x86_ioport_read_16(microkit_ioport ioport_id, seL4_Word port_addr);
+seL4_Uint32 microkit_x86_ioport_read_32(microkit_ioport ioport_id, seL4_Word port_addr);
+seL4_Word microkit_vcpu_x86_read_vmcs(microkit_child vcpu, seL4_Word field);
+void microkit_vcpu_x86_write_vmcs(microkit_child vcpu, seL4_Word field, seL4_Word value);
+seL4_Word microkit_vcpu_x86_read_msr(microkit_child vcpu, seL4_Word field);
+void microkit_vcpu_x86_write_msr(microkit_child vcpu, seL4_Word field, seL4_Word value);
+void microkit_vcpu_x86_enable_ioport(microkit_child vcpu, microkit_ioport ioport_id,
+                                     seL4_Word port_addr, seL4_Word length);
+void microkit_vcpu_x86_disable_ioport(microkit_child vcpu, seL4_Word port_addr, seL4_Word length);
+void microkit_vcpu_x86_write_regs(microkit_child vcpu, seL4_VCPUContext *regs);
+
+ +

void init(void)

+ +

Every PD must expose an init entry point. +This is called by the system at boot time.

+ +

void notified(microkit_channel ch)

+ +

The notified entry point is called by the system when a PD has received a notification on a channel.

+ +

ch identifies the channel which has been notified (and indirectly the PD that performed the notification).

+ +

Note: ch could identify an interrupt.

+ +

Channel identifiers are specified in the system configuration.

+ +

microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo)

+ +

The protected entry point is optional. +This is invoked when another PD calls microkit_ppcall on a channel shared with the PD.

+ +

The ch argument identifies the channel on which the PP was invoked. +Indirectly this identifies the PD performing the call. +Channel identifiers are specified in the system configuration. +Note: The channel argument is passed by the system and is unforgeable.

+ +

The msginfo argument is the argument passed to the PP and is provided by the calling PD. +The contents of the message is up to a pre-arranged protocol between the PDs. +The message contents are opaque to the system. +Note: The message is copied from the caller.

+ +

The returned microkit_msginfo is the return value of the protected procedure. +As with arguments, this is copied to the caller.

+ +

seL4_Bool fault(microkit_child child, microkit_msginfo msginfo, microkit_msginfo *reply_msginfo)

+ +

The fault entry point being invoked depends on whether the given PD has children. +It is invoked when a child PD or VM causes a fault.

+ +

The child argument identifies the child that caused the fault.

+ +

The msginfo argument is given by the seL4 kernel when a fault occurs and contains information +as to what fault occurred.

+ +

The reply_msginfo argument is given by libmicrokit and can be used to reply to the fault.

+ +

The returned seL4_Bool is whether or not to reply to the fault with the message reply_msginfo. +Returning seL4_True will reply to the fault. Returning seL4_False will not reply to the fault.

+ +

You can use microkit_msginfo_get_label on msginfo to deduce what kind of fault happened +(for example, whether it was a user exception or a virtual memory fault).

+ +

Whether or not you reply to the fault depends on the type of fault that has occurred and how you want +to handle it.

+ +

To find the full list of possible faults that could occur and details regarding to replying to a particular +kind of fault, please see the ‘Faults’ section of the +seL4 reference manual.

+ +

microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo)

+ +

Performs a call to a protected procedure in a different PD. +The ch argument identifies the protected procedure to be called. +msginfo is passed as argument to the protected procedure. +Channel identifiers are specified in the system configuration.

+ +

The protected procedure’s return data is returned in the microkit_msginfo.

+ +

void microkit_notify(microkit_channel ch)

+ +

Notify the channel ch. +Channel identifiers are specified in the system configuration.

+ +

void microkit_irq_ack(microkit_channel ch)

+ +

Acknowledge the interrupt identified by the specified channel.

+ +

void microkit_deferred_notify(microkit_channel ch)

+ +

The same as microkit_notify but will instead not actually perform the notify until +the entry point where microkit_deferred_notify was called returns.

+ +

It is important to note that only a single ‘deferred’ API call can be made within the +same entry point.

+ +

The purpose of this API is for performance critical code as this API saves +a kernel system call.

+ +

void microkit_deferred_irq_ack(microkit_channel ch)

+ +

The same as microkit_irq_ack but will instead not actually perform the IRQ acknowledge +until the entry point where microkit_deferred_irq_ack was called returns.

+ +

It is important to note that only a single ‘deferred’ API call can be made within the +same entry point.

+ +

The purpose of this API is for performance critical code as this API saves +a kernel system call.

+ +

void microkit_pd_restart(microkit_child pd, uintptr_t entry_point)

+ +

Restart the execution of a child protection domain with ID pd at the given entry_point. +This will set the program counter of the child protection domain to entry_point.

+ +

void microkit_pd_stop(microkit_child pd)

+ +

Stop the execution of the child protection domain with ID pd.

+ +

microkit_msginfo microkit_msginfo_new(uint64_t label, uint16_t count)

+ +

Creates a new message structure.

+ +

The message can be passed to microkit_ppcall or returned from protected.

+ +

uint64_t microkit_msginfo_get_label(microkit_msginfo msginfo)

+ +

Returns the label from a message.

+ +

uint64_t microkit_msginfo_get_count(microkit_msginfo msginfo)

+ +

Returns the count of message registers in the message.

+ +

uint64_t microkit_mr_get(uint8_t mr)

+ +

Get a message register.

+ +

void microkit_mr_set(uint8_t mr, uint64_t value)

+ +

Set a message register.

+ +

void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point)

+ +

Restart the execution of a VM’s virtual CPU with ID vcpu at the given entry point. +This will set the program counter of the vCPU to entry_point.

+ +

void microkit_vcpu_stop(microkit_child vcpu)

+ +

Stop the execution of the VM’s virtual CPU with ID vcpu.

+ +

`void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq,

+

seL4_Uint8 priority, seL4_Uint8 group, +seL4_Uint8 index)`

+ +

Inject a virtual ARM interrupt for a virtual CPU vcpu with IRQ number irq. +The priority (0-31) determines what ARM GIC (generic interrupt controller) +priority level the virtual IRQ will be injected as. The group determines whether +the virtual IRQ will be injected into secure world (1) or non-secure world (0). +The index is the index of the virtual GIC list register.

+ +

void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq)

+ +

Acknowledge a ARM virtual Private Peripheral Interrupt (PPI) with IRQ number irq +for a VM’s vCPU with ID vcpu.

+ +

seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg)

+ +

Read a register for a given virtual CPU with ID vcpu. The reg argument is the index of the +register that is read. The list of registers is defined by the enum seL4_VCPUReg +in the seL4 source code.

+ +

void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value)

+ +

Write to a register for a given virtual CPU with ID vcpu. The reg argument is the index of the +register that is written to. The value argument is what the register will be set to. +The list of registers is defined by the enum seL4_VCPUReg in the seL4 source code.

+ +

void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response)

+ +

The API takes in arguments for a Secure Monitor Call which will be performed by seL4. Any +response values will be placed into the response structure.

+ +

The seL4_ARM_SMCContext structure contains fields for registers x0 to x7.

+ +

Note that this API is only available when the PD making the call has been configured to +have SMC enabled in the SDF. Note that when the kernel makes the actual SMC, it cannot +pre-empt the Secure Monitor and therefore any kernel WCET properties are no longer guaranteed.

+ +

void microkit_x86_ioport_write_(8|16|32)(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data)

+ +

Write an 8, 16, or 32 bits value at port address port_addr to I/O Port with ID ioport_id.

+ +

seL4_Uint(8|16|32) microkit_x86_ioport_read_(8|16|32)(microkit_ioport ioport_id, seL4_Word port_addr)

+ +

Read an 8, 16, or 32 bits value at port address port_addr from I/O Port with ID ioport_id.

+ +

seL4_Word microkit_vcpu_x86_read_vmcs(microkit_child vcpu, seL4_Word field)

+ +

Read a Virtual Machine Control Structure field specified by field for a given virtual CPU +with ID vcpu using the vmread instruction.

+ +

All the VMCS fields are listed in the seL4 source at include/arch/x86/arch/object/vcpu.h.

+ +

The following fields can be read from:

+ +
    +
  • VMX_GUEST_RIP
    • +
  • VMX_GUEST_RSP
    • +
  • VMX_GUEST_ES_SELECTOR
    • +
  • VMX_GUEST_CS_SELECTOR
    • +
  • VMX_GUEST_SS_SELECTOR
    • +
  • VMX_GUEST_DS_SELECTOR
    • +
  • VMX_GUEST_FS_SELECTOR
    • +
  • VMX_GUEST_GS_SELECTOR
    • +
  • VMX_GUEST_LDTR_SELECTOR
    • +
  • VMX_GUEST_TR_SELECTOR
    • +
  • VMX_GUEST_DEBUGCTRL
    • +
  • VMX_GUEST_PAT
    • +
  • VMX_GUEST_EFER
    • +
  • VMX_GUEST_PERF_GLOBAL_CTRL
    • +
  • VMX_GUEST_PDPTE0
    • +
  • VMX_GUEST_PDPTE1
    • +
  • VMX_GUEST_PDPTE2
    • +
  • VMX_GUEST_PDPTE3
    • +
  • VMX_GUEST_ES_LIMIT
    • +
  • VMX_GUEST_CS_LIMIT
    • +
  • VMX_GUEST_SS_LIMIT
    • +
  • VMX_GUEST_DS_LIMIT
    • +
  • VMX_GUEST_FS_LIMIT
    • +
  • VMX_GUEST_GS_LIMIT
    • +
  • VMX_GUEST_LDTR_LIMIT
    • +
  • VMX_GUEST_TR_LIMIT
    • +
  • VMX_GUEST_GDTR_LIMIT
    • +
  • VMX_GUEST_IDTR_LIMIT
    • +
  • VMX_GUEST_ES_ACCESS_RIGHTS
    • +
  • VMX_GUEST_CS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_SS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_DS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_FS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_GS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_LDTR_ACCESS_RIGHTS
    • +
  • VMX_GUEST_TR_ACCESS_RIGHTS
    • +
  • VMX_GUEST_INTERRUPTABILITY
    • +
  • VMX_GUEST_ACTIVITY
    • +
  • VMX_GUEST_SMBASE
    • +
  • VMX_GUEST_SYSENTER_CS
    • +
  • VMX_GUEST_PREEMPTION_TIMER_VALUE
    • +
  • VMX_GUEST_ES_BASE
    • +
  • VMX_GUEST_CS_BASE
    • +
  • VMX_GUEST_SS_BASE
    • +
  • VMX_GUEST_DS_BASE
    • +
  • VMX_GUEST_FS_BASE
    • +
  • VMX_GUEST_GS_BASE
    • +
  • VMX_GUEST_LDTR_BASE
    • +
  • VMX_GUEST_TR_BASE
    • +
  • VMX_GUEST_GDTR_BASE
    • +
  • VMX_GUEST_IDTR_BASE
    • +
  • VMX_GUEST_DR7
    • +
  • VMX_GUEST_RFLAGS
    • +
  • VMX_GUEST_PENDING_DEBUG_EXCEPTIONS
    • +
  • VMX_GUEST_SYSENTER_ESP
    • +
  • VMX_GUEST_SYSENTER_EIP
    • +
  • VMX_CONTROL_CR0_MASK
    • +
  • VMX_CONTROL_CR4_MASK
    • +
  • VMX_CONTROL_CR0_READ_SHADOW
    • +
  • VMX_CONTROL_CR4_READ_SHADOW
    • +
  • VMX_DATA_INSTRUCTION_ERROR
    • +
  • VMX_DATA_EXIT_INTERRUPT_INFO
    • +
  • VMX_DATA_EXIT_INTERRUPT_ERROR
    • +
  • VMX_DATA_IDT_VECTOR_INFO
    • +
  • VMX_DATA_IDT_VECTOR_ERROR
    • +
  • VMX_DATA_EXIT_INSTRUCTION_LENGTH
    • +
  • VMX_DATA_EXIT_INSTRUCTION_INFO
    • +
  • VMX_DATA_GUEST_PHYSICAL
    • +
  • VMX_DATA_IO_RCX
    • +
  • VMX_DATA_IO_RSI
    • +
  • VMX_DATA_IO_RDI
    • +
  • VMX_DATA_IO_RIP
    • +
  • VMX_DATA_GUEST_LINEAR_ADDRESS
    • +
  • VMX_CONTROL_ENTRY_INTERRUPTION_INFO
    • +
  • VMX_CONTROL_PIN_EXECUTION_CONTROLS
    • +
  • VMX_CONTROL_PRIMARY_PROCESSOR_CONTROLS
    • +
  • VMX_CONTROL_EXCEPTION_BITMAP
    • +
  • VMX_CONTROL_EXIT_CONTROLS
    • +
  • VMX_GUEST_CR0
    • +
  • VMX_GUEST_CR3
    • +
  • VMX_GUEST_CR4
    • +
+ +

void microkit_vcpu_x86_write_vmcs(microkit_child vcpu, seL4_Word field, seL4_Word value)

+ +

Write a Virtual Machine Control Structure field specified by field for a given virtual CPU +with ID vcpu using the vmwrite instruction. The value may be modified to ensure any bits +that are fixed in the hardware are correct, and that any features required for kernel correctness +are not disabled.

+ +

All the VMCS fields are listed in the seL4 source at include/arch/x86/arch/object/vcpu.h.

+ +

The following fields can be written to:

+ +
    +
  • VMX_GUEST_RIP
    • +
  • VMX_GUEST_RSP
    • +
  • VMX_GUEST_ES_SELECTOR
    • +
  • VMX_GUEST_CS_SELECTOR
    • +
  • VMX_GUEST_SS_SELECTOR
    • +
  • VMX_GUEST_DS_SELECTOR
    • +
  • VMX_GUEST_FS_SELECTOR
    • +
  • VMX_GUEST_GS_SELECTOR
    • +
  • VMX_GUEST_LDTR_SELECTOR
    • +
  • VMX_GUEST_TR_SELECTOR
    • +
  • VMX_GUEST_DEBUGCTRL
    • +
  • VMX_GUEST_PAT
    • +
  • VMX_GUEST_EFER
    • +
  • VMX_GUEST_PERF_GLOBAL_CTRL
    • +
  • VMX_GUEST_PDPTE0
    • +
  • VMX_GUEST_PDPTE1
    • +
  • VMX_GUEST_PDPTE2
    • +
  • VMX_GUEST_PDPTE3
    • +
  • VMX_GUEST_ES_LIMIT
    • +
  • VMX_GUEST_CS_LIMIT
    • +
  • VMX_GUEST_SS_LIMIT
    • +
  • VMX_GUEST_DS_LIMIT
    • +
  • VMX_GUEST_FS_LIMIT
    • +
  • VMX_GUEST_GS_LIMIT
    • +
  • VMX_GUEST_LDTR_LIMIT
    • +
  • VMX_GUEST_TR_LIMIT
    • +
  • VMX_GUEST_GDTR_LIMIT
    • +
  • VMX_GUEST_IDTR_LIMIT
    • +
  • VMX_GUEST_ES_ACCESS_RIGHTS
    • +
  • VMX_GUEST_CS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_SS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_DS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_FS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_GS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_LDTR_ACCESS_RIGHTS
    • +
  • VMX_GUEST_TR_ACCESS_RIGHTS
    • +
  • VMX_GUEST_INTERRUPTABILITY
    • +
  • VMX_GUEST_ACTIVITY
    • +
  • VMX_GUEST_SMBASE
    • +
  • VMX_GUEST_SYSENTER_CS
    • +
  • VMX_GUEST_PREEMPTION_TIMER_VALUE
    • +
  • VMX_GUEST_ES_BASE
    • +
  • VMX_GUEST_CS_BASE
    • +
  • VMX_GUEST_SS_BASE
    • +
  • VMX_GUEST_DS_BASE
    • +
  • VMX_GUEST_FS_BASE
    • +
  • VMX_GUEST_GS_BASE
    • +
  • VMX_GUEST_LDTR_BASE
    • +
  • VMX_GUEST_TR_BASE
    • +
  • VMX_GUEST_GDTR_BASE
    • +
  • VMX_GUEST_IDTR_BASE
    • +
  • VMX_GUEST_DR7
    • +
  • VMX_GUEST_RFLAGS
    • +
  • VMX_GUEST_PENDING_DEBUG_EXCEPTIONS
    • +
  • VMX_GUEST_SYSENTER_ESP
    • +
  • VMX_GUEST_SYSENTER_EIP
    • +
  • VMX_CONTROL_CR0_MASK
    • +
  • VMX_CONTROL_CR4_MASK
    • +
  • VMX_CONTROL_CR0_READ_SHADOW
    • +
  • VMX_CONTROL_CR4_READ_SHADOW
    • +
  • VMX_CONTROL_EXCEPTION_BITMAP
    • +
  • VMX_CONTROL_ENTRY_INTERRUPTION_INFO
    • +
  • VMX_CONTROL_ENTRY_EXCEPTION_ERROR_CODE
    • +
  • VMX_CONTROL_PIN_EXECUTION_CONTROLS
    • +
  • VMX_CONTROL_PRIMARY_PROCESSOR_CONTROLS
    • +
  • VMX_CONTROL_SECONDARY_PROCESSOR_CONTROLS
    • +
  • VMX_CONTROL_EXIT_CONTROLS
    • +
  • VMX_GUEST_CR3
    • +
  • VMX_GUEST_CR0
    • +
  • VMX_GUEST_CR4
    • +
+ +

seL4_Word microkit_vcpu_x86_read_msr(microkit_child vcpu, seL4_Word field)

+ +

Read a 64-bit Model Specific Register of a given virtual CPU with ID vcpu specified by +field from hardware using the rdmsr instruction. The following registers can be written to:

+ +
    +
  • IA32_LSTAR_MSR
    • +
  • IA32_STAR_MSR
    • +
  • IA32_CSTAR_MSR
    • +
  • IA32_FMASK_MSR
    • +
+ +

void microkit_vcpu_x86_write_msr(microkit_child vcpu, seL4_Word field, seL4_Word value)

+ +

Write a 64-bit Model Specific Register of a given virtual CPU with ID vcpu specified by +field to hardware using the wrmsr instruction. The following registers can be read from:

+ +
    +
  • IA32_LSTAR_MSR
    • +
  • IA32_STAR_MSR
    • +
  • IA32_CSTAR_MSR
    • +
  • IA32_FMASK_MSR
    • +
+ +

void microkit_vcpu_x86_enable_ioport(microkit_child vcpu, microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word length)

+ +

Enable I/O port range [port_addr..port_addr + length) of I/O Port with ID ioport_id +in the execution environment of a given virtual CPU with ID vcpu.

+ +

void microkit_vcpu_x86_disable_ioport(microkit_child vcpu, seL4_Word port_addr, seL4_Word length)

+ +

Disable I/O port range [port_addr..port_addr + length) in the execution environment of a given +virtual CPU with ID vcpu.

+ +

void microkit_vcpu_x86_write_regs(microkit_child vcpu, seL4_VCPUContext *regs)

+ +

Write the registers of a given virtual CPU with ID vcpu. The regs argument is the pointer to +the struct of registers seL4_VCPUContext that are written from.

+ +

System Description File

+ +

This section describes the format of the System Description File (SDF).

+ +

The system description file is an XML file that is provided as input to the +microkit tool.

+ +

The root element of the XML file is system.

+ +

Within the system root element the following child elements are supported:

+ +
    +
  • protection_domain
    • +
  • memory_region
    • +
  • channel
    • +
+ +

protection_domain

+ +

The protection_domain element describes a protection domain.

+ +

It supports the following attributes:

+ +
    +
  • name: A unique name for the protection domain
    • +
  • priority: The priority of the protection domain (integer 0 to 254).
    • +
  • budget: (optional) The PD’s budget in microseconds; defaults to 1,000.
    • +
  • period: (optional) The PD’s period in microseconds; must not be smaller than the budget; defaults to the budget.
    • +
  • passive: (optional) Indicates that the protection domain will be passive and thus have its scheduling context removed after initialisation; defaults to false.
    • +
  • stack_size: (optional) Number of bytes that will be used for the PD’s stack. +Must be be between 4KiB and 16MiB and be 4K page-aligned. Defaults to 8KiB.
    • +
  • cpu: (optional) set the physical CPU core this PD will run on. Defaults to zero.
    • +
  • smc: (optional, only on ARM) Allow the PD to give an SMC call for the kernel to perform.. Defaults to false.
    • +
+ +

Additionally, it supports the following child elements:

+ +
    +
  • program_image: (exactly one) Describes the program image for the protection domain.
    • +
  • map: (zero or more) Describes mapping of memory regions into the protection domain.
    • +
  • irq: (zero or more) Describes hardware interrupt associations.
    • +
  • setvar: (zero or more) Describes variable rewriting.
    • +
  • protection_domain: (zero or more) Describes a child protection domain.
    • +
  • virtual_machine: (zero or one) Describes a child virtual machine.
    • +
+ +

The program_image element has a single path attribute describing the path to an ELF file.

+ +

The map element has the following attributes:

+ +
    +
  • mr: Identifies the memory region to map.
    • +
  • vaddr: Identifies the virtual address at which to map the memory region.
    • +
  • perms: Identifies the permissions with which to map the memory region. Can be a combination of r (read), w (write), and x (eXecute), with the exception of a write-only mapping (just w).
    • +
  • cached: (optional) Determines if mapped with caching enabled or disabled. Defaults to true.
    • +
  • setvar_vaddr: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the virtual address of the memory region.
    • +
  • setvar_size: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the size of the memory region.
    • +
+ +

The irq element has the following attributes on ARM and RISC-V:

+ +
    +
  • irq: The hardware interrupt number.
    • +
  • id: The channel identifier. Must be at least 0 and less than 63.
    • +
  • trigger: (optional) Whether the IRQ is edge triggered (“edge”) or level triggered (“level”). Defaults to “level”.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ.
    • +
+ +

The irq element has the following attributes when registering X86_64 IOAPIC interrupts:

+ +
    +
  • id: The channel identifier. Must be at least 0 and less than 63.
    • +
  • pin: IOAPIC pin that generates the interrupt.
    • +
  • vector: CPU vector to deliver the interrupt to.
    • +
  • ioapic: (optional) Zero based index of the IOAPIC to get the interrupt from. Defaults to 0.
    • +
  • level: (optional) Whether the IRQ is level triggered (1) or edge triggered (0). Defaults to level (1).
    • +
  • polarity: (optional) Whether the line polarity is high (1) or low (0). Defaults to high (1).
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ.
    • +
+ +

The irq element has the following attributes when registering X86_64 MSI interrupts:

+ +
    +
  • id: The channel identifier. Must be at least 0 and less than 63.
    • +
  • pcidev: The PCI device address of the device that will generate the interrupt, in BUS:DEV:FUNC notation (e.g. 01:1f:2).
    • +
  • handle: Value of the handle programmed into the data portion of the MSI.
    • +
  • vector: CPU vector to deliver the interrupt to.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ.
    • +
+ +

The ioport element has the following attributes:

+ +
    +
  • id: The I/O port identifier. Must be at least 0 and less than 63.
    • +
  • addr: The base address of the I/O port.
    • +
  • size: The size in bytes of the I/O port region.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the I/O port identifier.
    • +
  • setvar_addr: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the base address of the I/O port.
    • +
+ +

The setvar element has the following attributes:

+ +
    +
  • symbol: Name of a symbol in the ELF file.
    • +
  • region_paddr: Name of an MR. The symbol’s value shall be updated to this MR’s physical address. + Note that on x86-64 platforms this MR must have a specified physical address. + This restriction is due to x86-64 physical memory layout not being known at build-time.
    • +
+ +

The protection_domain element has the same attributes as any other protection domain as well as:

+ +
    +
  • id: The ID of the child for the parent to refer to.
    • +
  • setvar_id: (optional) Specifies a symbol in the parent program image. This symbol will be rewritten with the ID of the child.
    • +
+ +

The virtual_machine element has the following attributes:

+ +
    +
  • name: A unique name for the virtual machine
    • +
  • priority: The priority of the virtual machine (integer 0 to 254).
    • +
  • budget: (optional) The VM’s budget in microseconds; defaults to 1,000.
    • +
  • period: (optional) The VM’s period in microseconds; must not be smaller than the budget; defaults to the budget.
    • +
+ +

Additionally, it supports the following child elements:

+ +
    +
  • vcpu: (one or more) Describes the virtual CPU that will be tied to the virtual machine.
    • +
  • map: (zero or more) Describes mapping of memory regions into the virtual machine.
    • +
+ +

The vcpu element has the following attributes:

+ +
    +
  • id: The vCPU identifier. Must be at least 0 and less than 62.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the vCPU identifier.
    • +
+ +

The map element has the same attributes as the protection domain with the exception of setvar_vaddr.

+ +

memory_region

+ +

The memory_region element describes a memory region.

+ +

It supports the following attributes:

+ +
    +
  • name: A unique name for the memory region
    • +
  • size: Size of the memory region in bytes (must be a multiple of the page size)
    • +
  • page_size: (optional) Size of the pages used in the memory region; must be a supported page size if provided. Defaults to the largest page size for the target architecture that the memory region is aligned to.
    • +
  • phys_addr: (optional) The physical address for the start of the memory region (must be a multiple of the page size).
    • +
+ +

The memory_region element does not support any child elements.

+ +

Page sizes by architecture

+ +

Below are the available page sizes for each architecture that Microkit supports.

+ +
AArch64
+ +
    +
  • 0x1000 (4KiB)
    • +
  • 0x200000 (2MiB)
    • +
+ +
RISC-V 64-bit
+ +
    +
  • 0x1000 (4KiB)
    • +
  • 0x200000 (2MiB)
    • +
+ +
x86-64
+ +
    +
  • 0x1000 (4KiB)
    • +
  • 0x200000 (2MiB)
    • +
+ +

channel

+ +

The channel element has exactly two end children elements for specifying the two PDs associated with the channel.

+ +

The end element has the following attributes:

+ +
    +
  • pd: Name of the protection domain for this end.
    • +
  • id: Channel identifier in the context of the named protection domain. Must be at least 0 and less than 63.
    • +
  • pp: (optional) Indicates that the protection domain for this end can perform a protected procedure call to the other end; defaults to false. + Protected procedure calls can only be to PDs of strictly higher priority.
    • +
  • notify: (optional) Indicates that the protection domain for this end can send a notification to the other end; defaults to true.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier.
    • +
+ +

The id is passed to the PD in the notified and protected entry points. +The id should be passed to the microkit_notify and microkit_ppcall functions.

+ +

Board Support Packages

+ +

This chapter describes the board support packages that are available in the SDK.

+ +

The currently supported platforms are:

+
    +
  • ariane
    • +
  • cheshire
    • +
  • hifive_p550
    • +
  • imx8mm_evk
    • +
  • imx8mp_evk
    • +
  • imx8mp_iotgate
    • +
  • imx8mq_evk
    • +
  • maaxboard
    • +
  • odroidc2
    • +
  • odroidc4
    • +
  • qemu_virt_aarch64
    • +
  • qemu_virt_riscv64
    • +
  • rockpro64
    • +
  • rpi4b_1gb
    • +
  • rpi4b_2gb
    • +
  • rpi4b_4gb
    • +
  • rpi4b_8gb
    • +
  • serengeti
    • +
  • star64
    • +
  • tqma8xqp1gb
    • +
  • ultra96v2
    • +
  • x86_64_generic
    • +
  • x86_64_generic_vtx
    • +
  • zcu102
    • +
+ +

Ariane (CVA6)

+ +

Initial support is available for the CVA6 (formerly Ariane) core design +on the Digilent Genesys2 board. CVA6 is an open-source RISC-V (rv64i) processor.

+ +

Microkit support expects that a compatible RISC-V SBI (e.g OpenSBI) has executed before +jumping to the beginning of the loader image.

+ +

Microkit outputs an ELF for this platform.

+ +

You may compile OpenSBI with the Microkit image as a payload, or alternately install +OpenSBI (with U-Boot optionally) to the SD card.

+ +

If you are booting from U-Boot, use the following command to start the system image:

+ +
=> bootelf ${image_addr}
+
+ +

Where image_addr is the load address of the ELF image.

+ +

Note that the OpenSBI version from the CVA6 SDK at the time of writing has issues when +booting. It is recommended to use the mainline OpenSBI.

+ +

Compulab IOT-GATE-IMX8MPLUS

+ +

The IOT-GATE-IMX8PLUS is based on the NXP i.MX8MP SoC.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x50000000
+
+ +

Cheshire

+ +

Support is available for Cheshire. +It is an SoC design based on the CVA6 core, implementing a 64-bit RISC-V CPU.

+ +

Microkit outputs an ELF for this platform. Several steps are required in order to boot.

+ +

A custom version of OpenSBI is required. It can be found +here. +Build the firmware payload using platform fpga/cheshire.

+ +

To boot a Microkit image, use a GDB prompt via openOCD per seL4 Docs:

+ +
    +
  1. +

    Reset board

    + + 
     (gdb) monitor reset halt
+
    +
    2. +
  2. +

    Set the a0 and a1 registers for OpenSBI

    + + 
     # tell OpenSBI where DTB is (there is none)
+ (gdb) set $a0=0
+ # tell OpenSBI that the default hart is #0
+ (gdb) set $a1=0
+
    +
    3. +
  3. +

    Load OpenSBI’s FW_JUMP payload targeted at 0x90000000, implicitly setting the program counter.

    + + 
     (gdb) load /path/to/opensbi/fw_jump.elf
+
    +
    4. +
  4. +

    Load the Microkit image:

    + + 
    (gdb) restore /path/to/loader.img
+
    +
    5. +
  5. +

    Allow OpenSBI and Microkit to boot:

    + + 
     (gdb) continue
+
    +
    6. +
+ +

i.MX8MM-EVK

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x41000000
+
+ +

i.MX8MP-EVK

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x41000000
+
+ +

i.MX8MQ-EVK

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x41000000
+
+ +

MaaXBoard

+ +

The MaaXBoard is a low-cost ARM SBC based on the NXP i.MX8MQ system-on-chip.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x50000000
+
+ +

Odroid-C2

+ +

The HardKernel Odroid-C2 is an ARM SBC based on the Amlogic Meson S905 system-on-chip. It +should be noted that the Odroid-C2 is no longer available for purchase but its successor, +the Odroid-C4, is readily available at the time of writing.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x20000000
+
+ +

Odroid-C4

+ +

The HardKernel Odroid-C4 is an ARM SBC based on the Amlogic Meson S905X3 system-on-chip.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x20000000
+
+ +

Serengeti

+ +

Serengeti is a fork of the Cheshire platform by Trustworthy Systems. More +information on the hardware platform can be found here.

+ +

Right now Serengeti is a superset of Cheshire by offering more peripherals than Cheshire +has.

+ +

For running on Serengeti, please see Cheshire for instructions.

+ +

SiFive Premier P550

+ +

The SiFive Premier P550 is a development board based on the ESWIN EIC7700X system-on-chip.

+ +

Microkit will produce a uImage. To load the image you will need to use +the bootm command. bootm expects an address of where +the Device Tree Blob (DTB) will be as well as the image.

+ +

If you do not have a DTB for this platform you can obtain it from the seL4 source code with:

+
dtc -I dts -O dtb seL4/tools/dts/hifive-p550.dts > hifive-p550.dtb
+
+ +

Now you can load the images into U-Boot at the appropriate addresses, for example via TFTP:

+ +
=> setenv imgaddr "0xB0000000"
+=> setenv dtbaddr "0xA0000000"
+=> tftpboot ${imgaddr} /path/to/loader.img
+=> tftpboot ${dtbaddr} /path/to/hifive-p550.dtb
+=> bootm ${imgaddr} - ${dtbaddr}
+
+ +

imgaddr and dtbaddr are arbitrarily chosen addresses in main memory for this platform, +you can load the image and DTB at another address.

+ +

QEMU virt (AArch64)

+ +

Support is available for the virtual AArch64 QEMU platform. This is a platform that is not based +on any specific SoC or hardware platform and is intended for simulating systems for +development or testing.

+ +

It should be noted that the platform support is configured with 2GB of main memory and the +Cortex-A53 CPU. seL4 needs to know the memory layout and CPU at build-time so if +you want to change these parameters (e.g to allow more memory), you will have to change the kernel +options for qemu_virt_aarch64 in build_sdk.py.

+ +

You can use the following command to simulate a Microkit system:

+ +
$ qemu-system-aarch64 \
+    -machine virt,virtualization=on \
+    -cpu cortex-a53 \
+    -nographic \
+    -serial mon:stdio \
+    -device loader,file=[SYSTEM IMAGE],addr=0x70000000,cpu-num=0 \
+    -m size=2G
+
+ +

When using the SMP configurations add the -smp 4 argument to the QEMU command.

+ +

You can find more about the QEMU virt platform in the +QEMU documentation.

+ +

QEMU virt (RISC-V 64-bit)

+ +

Support is available for the virtual RISC-V (64-bit) QEMU platform. +This is a platform that is not based on any specific SoC or hardware platform +and is intended for simulating systems for development or testing.

+ +

It should be noted that the platform support is configured with 2GB of main memory. +seL4 has a static amount of memory at build-time, if you want allow for more memory, +you will have to change the kernel options for qemu_virt_riscv64 in build_sdk.py.

+ +

You can use the following command to simulate a Microkit system:

+ +
$ qemu-system-riscv64 \
+    -machine virt \
+    -nographic \
+    -serial mon:stdio \
+    -kernel [SYSTEM IMAGE] \
+    -m size=2G
+
+ +

When using the SMP configurations add the -smp 4 argument to the QEMU command.

+ +

QEMU will start the system image using its packaged version of OpenSBI.

+ +

You can find more about the QEMU virt platform in the +QEMU documentation.

+ +

Raspberry Pi 4B

+ +

Support is available for the Raspberry Pi 4 Model B. There are multiple models of the +Raspberry Pi 4B that have different amounts of RAM, we have support for the 1GB, +2GB, 4GB and 8GB models. Because the amount of RAM must be known statically by +seL4, the Microkit board names differ for each model:

+ +
    +
  • rpi4b_1gb for 1GB of RAM.
    • +
  • rpi4b_2gb for 2GB of RAM.
    • +
  • rpi4b_4gb for 4GB of RAM.
    • +
  • rpi4b_8gb for 8GB of RAM.
    • +
+ +

For initial board setup, please see the instructions on the +seL4 website.

+ +

When getting into the U-Boot console you want to load the Microkit binary image to +address 0x10000000 and then run go 0x10000000.

+ +

For example, if you were to load the image via the MMC you would run the following +U-Boot commands:

+ +
 => fatload mmc 0 0x10000000 <SYSTEM IMAGE>
+ => go 0x10000000
+
+ +

Pine64 ROCKPro64

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x30000000
+
+ +

Pine64 Star64

+ +

Support is available for the Pine64 Star64 platform which is based on the +StarFive JH7110 SoC.

+ +

The platform has a 4GB and 8GB model, we assume the 4GB model.

+ +

The default boot flow of the Star64 is:

+
    +
  1. OpenSBI
    2. +
  2. U-Boot
    3. +
  3. Operating System
    4. +
+ +

This means that the system image that Microkit produces does not need to be explicitly +packaged with an SBI implementation such as OpenSBI.

+ +

Microkit will produce a uImage. To load the image you will need to use +the bootm command. bootm expects an address of where +the Device Tree Blob (DTB) will be as well as the image.

+ +

If you do not have a DTB for this platform you can obtain it from the seL4 source code with:

+
dtc -I dts -O dtb seL4/tools/dts/star64.dts > star64.dtb
+
+ +

Now you can load the images into U-Boot at the appropriate addresses, for example via TFTP:

+ +
=> setenv imgaddr "0xE0000000"
+=> setenv dtbaddr "0xD0000000"
+=> tftpboot ${imgaddr} /path/to/loader.img
+=> tftpboot ${dtbaddr} /path/to/star64.dtb
+=> bootm ${imgaddr} - ${dtbaddr}
+
+ +

imgaddr and dtbaddr are arbitrarily chosen addresses in main memory for this platform, +you can load the image and DTB at another address.

+ +

TQMa8XQP 1GB

+ +

The TQMa8XQP is a system-on-module designed by TQ-Systems GmbH. +The modules incorporates an NXP i.MX8X Quad Plus system-on-chip and 1GiB ECC memory.

+ +

TQ-Systems provide the MBa8Xx carrier board for development purposes. +The instructions provided assume the use of the MBa8Xx carrier board. +If you are using a different carrier board please refer to the appropriate documentation.

+ +

Note: There are different configured of the TQMa8Xx board which include different NXP SoCs +and different memory configurations. Such modules are not supported.

+ +

The MBa8Xx provides access to the TQMa8XQP UART via UART-USB bridge. +To access the UART connect a USB micro cable to port X13. +The UART-USB bridge supports 4 individual UARTs; the UART is connected to the 2nd port.

+ +

By default the SoM will autoboot using U-Boot. +Hit any key during the boot process to stop the autoboot.

+ +

A new board will autoboot to Linux. +You will likely want to disable autoboot:

+ +
=> env set bootdelay -1
+=> env save
+
+ +

The board can be reset by pressing switch S4 (located next to the Ethernet port). +Alternatively, you can use the reset command from the U-Boot prompt.

+ +

During development the most convenient way to boot a Microkit image is via network booting. +U-Boot support booting via the tftp protocol. +To support this you’ll want to configure the network. +U-Boot supports DHCP, however it is often more reliable to explicitly set an IP address. +For example:

+ +
=> env set ipaddr 10.1.1.2
+=> env set netmask 255.255.255.0
+=> env set serverip 10.1.1.1
+=> env save
+
+ +

To use tftp you also need to set the file to load and the memory address to load it to:

+ +
=> env set bootfile loader.img
+=> env set loadaddr 0x80280000
+=> env save
+
+ +

The system image generated by the Microkit tool by default is a raw binary file.

+ +

An example sequence of commands for booting is:

+ +
=> tftpboot
+=> dcache flush
+=> icache flush
+=> go ${loadaddr}
+
+ +

Rather than typing these each time you can create a U-Boot script:

+ +
=> env set microkit 'tftpboot; dcache flush; icache flush; go ${loadaddr}'
+=> env save
+=> run microkit
+
+ +

When debugging is enabled the kernel will use the same UART as U-Boot.

+ +

Ultra96V2

+ +

To run the built image on the board, you have to use properly patched U-Boot - please see the section for ZCU102, for the details.

+ +

You have to load the binary file into memory and run it:

+
ZynqMP> tftpboot 0x40000000 loader.img
+...
+ZynqMP> go 0x40000000
+
+ +

x86-64 generic

+ +

This board supports x86-64 platforms with generic microarchitecture and no virtualisation.

+ +

Up to 16 CPU cores are supported. If your platform’s CPU count exceeds the maximum, the excess CPUs +are ignored by seL4. This limitation is due to a build-time config option of seL4, to increase the +limit, see the board configuration in build_sdk.py.

+ +

On x86-64, Microkit produces 3 ELF images in the output directory:

+ +
    +
  • sel4.elf, seL4 kernel (64-bit ELF)
    • +
  • sel4_32.elf, seL4 kernel (32-bit ELF)
    • +
  • Initial Task image (Multiboot Boot Module ELF)
    • +
+ +

The filename of the initial task image is specified with the -o option, and defaults to loader.img. +Both kernel ELF files are written to the same directory as the initial task image.

+ +

Although this target is for x86-64, your bootloader may require a 32-bit kernel ELF.

+ +

When using QEMU, you must use the 32-bit kernel ELF, for example:

+ +
$ qemu-system-x86_64 \
+	-cpu qemu64,+fsgsbase,+pdpe1gb,+xsaveopt,+xsave \
+	-m "1G" \
+	-display none \
+	-serial mon:stdio \
+	-kernel sel4_32.elf \
+	-initrd loader.img
+
+ +

Unlike Microkit’s qemu_virt_aarch64 and qemu_virt_riscv64, the amount of memory provided to QEMU +is configurable at run time with the -m option, rather than at build time.

+ +

QEMU currently does not support 64-bit kernel ELFs and gives the following error:

+
qemu-system-x86_64: Cannot load x86-64 image, give a 32bit one.
+
+ +

To obtain a bootable ISO image, a Multiboot 2-compliant bootloader must be used. Please refer to your +bootloader’s documentations.

+ +

x86_64 generic

+ +

This board supports x86-64 platforms with generic microarchitecture and virtualisation.

+ +

This configuration assumes Intel VT-x support. Currently, only 1 vCPU is supported per virtual machine +on x86-64.

+ +

The boot process is identical to x86-64 generic.

+ +

This configuration exists because some x86 emulators (for example, QEMU on macOS on Apple Silicon) do +not emulate Intel VT-x.

+ +

If you see the following message at boot:

+
vt-x: not supported
+
+

Consider using the non VT-x configuration: x86-64 generic, or switch to a x86 emulator that +emulates Intel VT-x, such as Bochs.

+ +

ZCU102

+ +

The ZCU102 can run on a physical board or on an appropriate QEMU based emulator.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x40000000
+
+ +

For simulating the ZCU102 using QEMU, use the following command:

+ +
$ qemu-system-aarch64 \
+   -m size=4G  \
+   -machine xlnx-zcu102,virtualization=on \
+   -nographic \
+   -device loader,file=[SYSTEM IMAGE],addr=0x40000000,cpu-num=0 \
+   -serial mon:stdio
+
+ +

When using the SMP configurations add the -smp 4 argument to the QEMU command.

+ +

It should be noted that when using U-Boot to load and run a Microkit system image, +that there may be additional setup needed.

+ +

For the ZynqMP class of platforms, which the ZCU102 is apart of, U-Boot does not start +the Microkit system Exception Level 2 (EL2) which is necessary for Microkit to start +(this is because seL4 is configured as a hypervisor).

+ +

You can see that when using the go command, U-Boot is +unconditionally always dropping down to EL1.

+ +

To avoid this behaviour, the call to armv8_switch_to_el1 should be replaced with +armv8_switch_to_el2 in this do_go_exec function.

+ +

Adding Platform Support

+ +

The following section is a guide for adding support for a new ARM or RISC-V platform to Microkit.

+ +

Prerequisites

+ +

Before you can start with adding platform support to Microkit, the platform must be supported by the seL4 kernel. +You can find information on how to do so here.

+ +

Getting Microkit Components Working

+ +
build_sdk.py
+ +

The first step to adding Microkit support is to modify the build_sdk.py script in order to build the required +artefacts for the new platform. This involves adding to the SUPPORTED_BOARDS list with the BoardInfo options +containing the platform specific attributes. This should be fairly self-explanatory by looking at the existing +entries with the exception of the loader_link_address.

+ +

The loader_link_address parameter specifies the physical address of where the bootloader for Microkit (which +is responsible for setting up the system before seL4 starts) is going to be loaded. This address needs to +match where in main memory the final system image is actually loaded (e.g where a previous bootloader such as U-Boot +loads the image to). This means that the address is restricted to the platform’s main memory region.

+ +
Loader
+ +
UART
+ +

The other component of Microkit that is platform dependent is the loader itself. The loader will attempt to access +the UART for debug output which requires a basic putc implementation. The UART device used in the loader should be +the same as what is used for the seL4 kernel debug output.

+ +

It should be noted that on RISC-V platforms, the SBI will be used for putc so no porting is necessary.

+ +
CPU configuration
+ +

For supporting multi-core systems on Microkit, the loader needs to know the platform-specific CPU identifiers +that we want to make use of.

+ +

For ARM platforms, a psci_target_cpus array needs to be defined which contains the PSCI target_cpu value for +each CPU. This value can be found by looking at the reg field for each CPU in the Device Tree.

+ +

For RISC-V platforms, a hart_ids array needs to be defined which contains the Hart ID for +each CPU. This value can be found by looking at the reg field for each CPU in the Device Tree. The first value +must be the same as FIRST_HART_ID defined in seL4.

+ +
Next steps
+ +

Once you have patched the loader and the SDK build script, there should be no other changes required to have a working +platform port. It is a good idea at this point to boot a hello world system to confirm the port is working.

+ +

If there are issues with porting the platform, please open an issue on GitHub.

+ +

Contributing Platform Support

+ +

Once you believe that the port works, you can open a pull request with required +changes as well as documentation in the manual about the platform and how to run Microkit images on it.

+ +

Please also update the platforms.yml file, you can find more information at the top of the file.

+ +

Rationale

+ +

This section describes the rationales driving the Microkit design choices.

+ +

Overview

+ +

The seL4 microkernel provides a set of powerful and flexible mechanisms that can be used for building almost arbitrary systems. +While minimising constraints on the nature of system designs and scope of deployments, this flexibility makes it challenging to design the best system for a particular use case, requiring extensive seL4 experience from developers.

+ +

The Microkit addresses this challenge by constraining the +system architecture to one that provides enough features and power for +its target usage class (IoT, cyberphysical and other embedded systems +with a static architecture), enabling a much simpler set of developer-visible abstractions.

+ +

Protection Domains

+ +

PDs are single-threaded to keep the programming model and implementations simple, and because this serves the needs of most present use cases in the target domains. +Extending the model to multithreaded applications (clients) is straightforward and can be done if needed. +Extending to multithreaded services is possible but requires additional infrastructure for which we see no need in the near future.

+ +

Protected Procedure Priorities

+ +

The restriction of only calling to higher priority prevents deadlocks and reflects the notion that the callee operates on behalf of the caller, and it should not be possible to preempt execution of the callee unless the caller could be preempted as well.

+ +

This greatly simplifies reasoning about real-time properties in the system; in particular, it means that PPs can be used to implement resource servers, where shared resources are encapsulated in a component that ensures mutual exclusion, while avoiding unbounded priority inversions through the immediate priority ceiling protocol.

+ +

While it would be possible to achieve the same by allowing PPs between PDs of the same priority, this would be much harder to statically analyse for loop-freedom (and thus deadlock-freedom). +The drawback is that we waste a part of the priority space where a logical entity is split into multiple PDs, eg to separate out a particularly critical component to formally verify it, when the complete entity would be too complex for formal verification. +For the kinds of systems targeted by the Microkit, this reduction of the usable priority space is unlikely to cause problems.

+ +

Protected Procedure Argument Size

+ +

The limitation on the size of by-value arguments is forced by the (architecture-dependent) limits on the payload size of the underlying seL4 operations, as well as by efficiency considerations. +The protected procedure payload should be considered as analogous to function arguments in the C language; similar limitations exist in the C ABIs (Application Binary Interfaces) of various platforms.

+ +

Limits

+ +

The limitation on the number of protection domains in the system is relatively arbitrary. +Based on experience with the system and the types of systems being built it is possible for this to be increased in the future.

+ +

The limitation on the number of channels for a protection domain is based on the size of the notification word in seL4. +Changing this to be larger than 64 would most likely require changes to seL4. The reason for why the limit is not a +power of two is due to part of the notification word being for internal libmicrokit use.

+ +

Internals

+ +

The following section describes internal details for how the Microkit works +and all the components of Microkit. As a user of Microkit, it is not necessary +know this information, however, there is no harm in having a greater +understanding of the tools that you are using.

+ +

Microkit flow

+ +

The diagram above aims to show the general flow of a Microkit system from +build-time to run-time.

+ +

The user provides the SDF (System Description File) and the ELFs that +correspond to PD program images to the Microkit tool which is responsible +for packaging everything together into a single image for the target +platform.

+ +

ARM and RISC-V

+ +

The final image is a bootable image which contains a couple different things:

+ +
    +
  • the Microkit loader
    • +
  • seL4
    • +
  • the capDL initialiser (and associated capDL specification)
    • +
+ +

When booting the image, the Microkit loader starts, jumps to the kernel, which +starts the capDL initialiser, which then sets up the entire system and starts +all the PDs, including the Monitor.

+ +

x86

+ +

The tool produces the kernel image and boot module image that contains the capDL initialiser. +You must bring your own Multiboot 2 compliant bootloader which then loads the kernel and boot module.

+ +

Now, we will go into a bit more detail about each of these stages of the +booting process as well as what exactly the Microkit tool is doing.

+ +

Loader (ARM and RISC-V)

+ +

The loader starts first, it has two main jobs:

+ +
    +
  1. Unpack all the parts of the system (kernel and initialiser) into +their expected locations within main memory.
    2. +
  2. Finish initialising the hardware such that the rest of the system can start.
    3. +
+ +

Before the Microkit loader starts, there would most likely have been some other +bootloader such as U-Boot or firmware on the target that did its own hardware +initialisation before starting Microkit.

+ +

However, there are certain things that seL4 expects to be initialised +that will not be done by a previous booting stage, such as:

+ +
    +
  • changing to the right exception level
    • +
  • enabling the MMU (seL4 expects the MMU to be on when it starts)
    • +
  • interrupt controller setup
    • +
+ +

Once this is all completed, the loader jumps to seL4 which starts executing. +The loader will never be executed again.

+ +

capDL Initialiser

+ +

Once the kernel has done its own initialisation, it will begin the +‘initial task’. On seL4, this is a thread that contains all the initial +capabilities to resources and free memory that are used to setup the rest of the system.

+ +

Within a Microkit environment, the ‘initial task’ is the capDL initialiser. Its main +job is to initialises and starts the system in conformance with the capDL specification.

+ +

At build-time, the Microkit tool embeds the capDL specification that describe +all kernel objects that needs to be created. Then for each kernel object, the spec +describe what state they need to be in and what capabilities exist to that object +(i.e. who has access to this kernel object). For example, the spec would specify the:

+
    +
  • starting Instruction Pointer (IP), Stack Pointer (SP) and IPC buffer pointer of a Thread Control Block (TCB),
    • +
  • page table structure and mapping attributes of an address space (VSpace),
    • +
  • interrupts (IRQ),
    • +
  • scheduling parameters (Scheduling Context),
    • +
  • and so on…
    • +
+ +

Monitor

+ +

The Monitor is a special PD that executes at the highest priority. It’s job +is to receive any faults caused by protection domains crashing or causing exceptions.

+ +

After the monitor initialises itself, goes to sleep and waits for any +faults from protection domains. On debug mode, this results in a message about +which PD caused an exception and details on the PD’s state at the time of the fault.

+ +

Other than printing fault details, the monitor does not do anything to handle +the fault, it will simply go back to sleep waiting for any other faults.

+ +

libmicrokit

+ +

Unlike the previous sections, libmicrokit is not its own program but it is worth +a mention since it makes up the core of each protection domain in a system.

+ +

When each PD starts, we enter libmicrokit’s starting point which does some initial +setup and calls the init entry point specified by the user. Once that completes, +the PD will enter libmicrokit’s event handler which sleeps until it receives events.

+ +

These events could be notifies (from other PDs or from an interrupt), PPCs, and faults. +For each event, the appropriate user-specified entry point is called and then when it +returns the PD goes back to sleep, waiting on any more events.

+ +

Microkit tool

+ +

The Microkit tool’s ultimate job is to take in the description of the user’s system, +the SDF, and convert into an seL4 system that boots and executes.

+ +

There are obvious steps such as parsing the SDF and PD ELFs. But the majority of +the work done by the tool is converting the system description into the capDL specification +then embedding it into the capDL initialiser image.

+ +

ARM & RISC-V specific

+

Since the physical memory layout of ARM and RISC-V platforms can be determined at boot +time by reading the device tree. The Microkit tool goes one step further and statically +check that the produced capDL specification is bootable on the target board. For example, +we check that there are no frames outside of device or normal memory, and that there are +enough memory to create all required kernel objects.

+ +

In order to do this however, the Microkit tool needs to emulate how the seL4 kernel boot +to obtain the list of free untyped objects that the kernel would give to the initial task.

+ +

While this is non-trivial to do, it comes with the useful property that if the tool +produces a valid image, there should be no errors upon initialising the system +If there are any errors with configuring the system (e.g running out of memory), +they will be caught at build-time. This can only reasonably be done due to the +static-architecture of Microkit systems.

+ +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/microkit/manual/2.1.0/index.md b/projects/microkit/manual/2.1.0/index.md deleted file mode 100644 index caf06466a10..00000000000 --- a/projects/microkit/manual/2.1.0/index.md +++ /dev/null @@ -1,1785 +0,0 @@ ---- -parent: /projects/microkit/manual/latest/ -toc: true -SPDX-FileCopyrightText: 2021, Breakaway Consulting Pty. Ltd. -SPDX-License-Identifier: CC-BY-SA-4.0 -mathjax: true ---- - -# Microkit User Manual (v2.1.0) - -This is a web version of the manual, you can find a PDF [here](microkit_user_manual.pdf) as well as in the -SDK at `doc/microkit_user_manual.pdf`. - -## Introduction - -The seL4 Microkit is a small and simple operating system (OS) built on the seL4 microkernel. -Microkit is designed for building system with a *static architecture*. -A static architecture is one where system resources are assigned up-front at system initialisation time. - -### Purpose - -The Microkit is intended to: - -* provide a small and simple OS for a wide range of IoT, cyberphysical and other embedded use cases; -* provide a reasonable degree of application portability appropriate for the targeted use cases; -* make seL4-based systems easy to develop and deploy within the target areas; -* leverage seL4's strong isolation properties to support a near-minimal *trusted computing base* (TCB); -* retain seL4's trademark performance for systems built with it; -* be, in principle, amenable to formal analysis of system safety and security properties (although such analysis is beyond the initial scope). - -### Overview - -A Microkit system is built from a set of individual programs that are isolated from each other, and the system, in *protection domains*. -Protection domains can interact by calling *protected procedures* or sending *notifications*. - -Microkit is distributed as a software development kit (SDK). -The SDK includes the tools, libraries and binaries required to build a Microkit system. -The Microkit source is also available which allows you to customize or extend Microkit and produce your own SDK. - -To build a Microkit system you will write some programs that use `libmicrokit`. -Microkit programs are a little different to a typical process on a Linux-like operating system. -Rather than a single `main` entry point, a program has four distinct entry points: `init`, `notified` and, potentially, `protected`, `fault`. - -On ARM and RISC-V, the individual programs are combined to produce a single bootable *system image*. -The format of the image is suitable for loading by the target board's bootloader. - -On x86-64, there are two ELF images invovled. One for the seL4 kernel, and one for the initialiser that -setups up the Microkit system. These are loaded by a Multiboot 2 compliant bootloader. - -The Microkit tool, which is provided as part of the SDK, is used to generate the system image(s). - -The Microkit tool takes a *system description* as input. -The system description is an XML file that specifies all the objects that make up the system. - -*Note*: Microkit does **not** impose any specific build system; you are free to choose the build system that works best for you. - -### Document Structure - -The [Concepts](#concepts) chapter describes the various concepts that make up Microkit. -It is recommended that you familiarise yourself with these concepts before trying to build a system. - -The [SDK](#sdk) chapter describes the software development kit, including its components and system requirements for use. - -The [Microkit tool](#tool) chapter describes the host system tool used for generating a system image from the system description and user-programs. - -The [libmicrokit](#libmicrokit) chapter describes the interfaces to the Microkit library. - -The [System Description File](#sysdesc) chapter describes the format of the system description XML file. - -The [Board Support Packages](#bsps) chapter describes each of the board support packages included in the SDK. - -The [Rationale](#rationale) chapter documents the rationale for some of the key design choices of Microkit. - -The [Internals](#internals) chapter documents some of the internal details for how Microkit works. - -## Concepts {#concepts} - -This chapter describes the key concepts provided by Microkit. - -As with any set of concepts there are words that take on special meanings. -This document attempts to clearly describe all of these terms, however as the concepts are inter-related it is sometimes necessary to use a term prior to its formal introduction. - -* [system](#system) -* [protection domain (PD)](#pd) -* [virtual machine (VM)](#vm) -* [memory region](#mr) -* [channel](#channels) -* [protected procedure](#pp) -* [notification](#notification) -* [interrupt](#irq) -* [fault](#fault) -* [ioport](#ioport) - -### System {#system} - -At the most basic level Microkit provides the platform for running a *system* on a specific board. -As a *user* of Microkit you use the platform to create a software system that implements your use case. -The system is described in a declarative configuration file, and the Microkit tool takes this system description as an input and produces an appropriate system image that can be loaded on the target board. - -The key elements that make up a system are *protection domains*, *memory regions* and *channels*. - -### Protection Domains {#pd} - -A **protection domain** (PD) is the fundamental runtime abstraction in Microkit. -It is analogous, but very different in detail, to a process on a UNIX system. - -A PD provides a thread of control that executes within a fixed virtual address space. -The isolation provided by the virtual address space is enforced by the underlying hardware MMU. - -The virtual address space for a PD has mappings for the PD's *program image* along with any memory regions that the PD can access. -The program image is an ELF file containing the code and data which implements the isolated component. - -Microkit supports a maximum of 63 protection domains. - -#### Entry points - -Although a protection domain is somewhat analogous to a process, it has a considerably different program structure and life-cycle. -A process on a typical operating system will have a `main` function which is invoked by the system when the process is created. -When the `main` function returns the process is destroyed. - -By comparison a protection domain has up to four entry points: - -* `init`, `notified` which are required. -* `protected` which is optional. -* `fault` which is required if the PD has children. - -When a Microkit system is booted, all PDs in the system execute the `init` entry point. - -A PD will not execute any other entry point until `init` has finished. - -If a PD is currently executing an entry point, it will not execute any other entry point -until the current entry point has finished. - -The `notified` entry point will be invoked whenever the protection domain receives a *notification* on a *channel*. -The `protected` entry point is invoked when a PD's *protected procedure* is called by another PD. -A PD does not have to provide a protected procedure, therefore the `protected` entry point is optional. - -The `fault` entry point is invoked when a PD that is a child of another PD causes a fault. -A PD does not have to have child PDs, therefore the `fault` entry point is only required for a parent PD. - -These entry points are described in more detail in subsequent sections. - -**Note:** The processing of `init` entry points is **not** synchronised across protection domains. -Specifically, it is possible for a high priority PD's `notified` or `protected` entry point to be called prior to the completion of a low priority PD's `init` entry point. - -The overall computational model for a Microkit system is a set of isolated components reacting to incoming events. - -#### Scheduling - -The PD has a number of scheduling attributes that are configured in the system description: - -* priority (0 -- 254) -* period (microseconds) -* budget (microseconds) -* passive (boolean) - -The budget and period bound the fraction of CPU time that a PD can consume. -Specifically, the **budget** specifies the amount of time for which the PD is allowed to execute. -Once the PD has consumed its budget, it is no longer runnable until the budget is replenished; replenishment happens once every **period** and resets the budget to its initial value. -This means that the maximum fraction of CPU time the PD can consume is $\frac{budget}{period}$. - -The budget cannot be larger than the period. -A budget that equals the period (aka. a "full" budget) behaves like a traditional time slice: After executing for a full period, the PD is preempted and put at the end of the scheduling queue of its priority. In other words, PDs with equal priorities and full budgets are scheduled round-robin with a time slice defined by the period. - -The **priority** determines which of the runnable PDs to schedule. A PD is runnable if one of its entry points has been invoked and it has budget remaining in the current period. -Runnable PDs of the same priority are scheduled in a round-robin manner. - -**Passive** determines whether the PD is passive. A passive PD will have its scheduling context revoked after initialisation and then bound instead to the PD's notification object. This means the PD will be scheduled on receiving a notification, whereby it will run on the notification's scheduling context. When the PD receives a *protected procedure* by another PD or a *fault* caused by a child PD, the passive PD will run on the scheduling context of the callee. - -### Virtual Machines {#vm} - -A *virtual machine* (VM) is a runtime abstraction for running guest operating systems in Microkit. It is similar -to a protection domain in that it provides a thread of control that executes within an isolated virtual address space. - -The main difference between a VM and a PD is that VMs have a higher privilege level such that they may function as a -guest operations and have their own user-space programs at a separate exception level. - -The virtual machine is always a child of a PD. Exceptions caused by the virtual machine are delivered to the parent PD -through the `fault` entry point. - -Each virtual machine has a number of 'virtual CPU's associated with it. Each virtual CPU (vCPU) that belongs to a -virtual machine has its own thread of execution. A vCPU also has an identifier which is used to know which vCPU caused -the invocation of the `fault` entry point. - -The parent PD is responsible for starting and managing the virtual machine. Microkit provides the abstractions in -order to manage the virtual machine through seL4 but there is typically a non-trivial amount -of supporting code/infrastructure to properly start and manage a VM. - -To keep the (potentially untrusted) virtual machine isolated from the rest of the system, Microkit enforces that a -protection domain can only ever manage a single virtual machine. - -### Memory Regions {#mr} - -A *memory region* is a contiguous range of physical memory. -A memory region may have a *fixed* physical address. -For memory regions without a fixed physical address, the physical address is allocated as part of the build process. -Typically, memory regions with a fixed physical address represent memory-mapped device registers. - -Memory regions that are within main memory are zero-initialised. - -The size of a memory region must be a multiple of a supported page size. -The supported page sizes are architecture dependent. -For example, on AArch64 architectures, Microkit support 4KiB and 2MiB pages. -The page size for a memory region may be specified explicitly in the system description. -If page size is not specified, the largest supported page size is used. - -*Note:* The page size also restricts the alignment of the memory region's physical address. -A fixed physical address must be a multiple of the specified page size. - -A memory region can be *mapped* into one or more protection domains. -The mapping has a number of attributes, which include: - -* the virtual address at which the region is mapped in the PD -* caching attributes (mostly relevant for device memory) -* permissions (read, write and execute) - -**Note:** When a memory region is mapped into multiple protection -domains, the attributes used for different mappings may vary. - -### Channels {#channels} - -A *channel* enables two protection domains to interact using protected procedures or notifications. -Each connects exactly two PDs; there are no multi-party channels. - -When a channel is created between two PDs, a *channel identifier* is configured for each PD. -The *channel identifier* is used by the PD to reference the channel. -Each PD can refer to the channel with a different identifier. -For example if PDs **A** and **B** are connected by a channel, **A** may refer to the channel using an identifier of **37** while **B** may use **42** to refer to the same channel. - -**Note:** There is no way for a PD to directly refer to another PD in the system. -PDs can only refer to other PDs indirectly if there is a channel between them. -In this case, the channel identifier is effectively a proxy identifier for the other PD. -So, to extend the prior example, **A** can indirectly refer to **B** via the channel identifier **37**. -Similarly, **B** can refer to **A** via the channel identifier **42**. - -The system supports a maximum of 63 channels and interrupts per protection domain. - -#### Protected procedures {#pp} - -A protection domain may provide a *protected procedure* (PP) which can be invoked from another protection domain. -Up to 64 words of data may be passed as arguments when calling a protected procedure. -The protected procedure return value may also be up to 64 words. - -When a protection domain calls a protected procedure, the procedure executes within the context of the providing protection domain. - -A protected call is only possible if the callee has strictly higher priority than the caller. -Transitive calls are possible, and as such a PD may call a *protected procedure* in another PD from a `protected` entry point. -However the overall call graph between PDs must form a directed, acyclic graph. -It follows that a PD can not call itself, even indirectly. -For example, `A calls B calls C` is valid (subject to the priority constraint), while `A calls B calls A` is not valid. - -When a protection domain is called, the `protected` entry point is invoked. -The control returns to the caller when the `protected` entry point returns. - -The caller is blocked until the callee returns. -Protected procedures must execute in bounded time. -It is intended that a future version of Microkit will enforce this condition through static analysis. -In the present version the caller must trust the callee to conform. - -In general, PPs are provided by services for use by clients that trust the protection domain to provide that service. - -To call a PP, a PD calls `microkit_ppcall` passing the channel identifier and a *message* structure. -A *message* structure is returned from this function. - -When a PD's protected procedure is invoked, the `protected` entry point is invoked with the channel identifier and message structure passed as arguments. -The `protected` entry point must return a message structure. - -#### Notifications {#notification} - -A notification is a (binary) semaphore-like synchronisation mechanism. -For example, a PD can *notify* another PD to indicate availability of data in a shared memory region if they share a channel. - -To notify another PD, a PD calls `microkit_notify`, passing the channel identifier. -When a PD receives a notification, the `notified` entry point is invoked with the appropriate channel identifier passed as an argument. - -Unlike protected procedures, notifications can be sent in either direction on a channel regardless of priority. - -**Note:** Notifications provide a mechanism for synchronisation between PDs, however this is not a blocking operation. -If a PD notifies another PD, that PD will become scheduled to run (if it is not already), but the current PD does **not** block. -Of course, if the notified PD has a higher priority than the current PD, then the current PD will be preempted (but not blocked) by the other PD. - -Depending on the scheduling, one PD could notify another multiple times without it being scheduled, resulting -in a single execution of the `notified` entry point. For example, if PD A notifies PD B three times on the -same channel without PD B ever executing, once PD B is scheduled it would only see one notification and hence -only enter `notified` once for that channel. - -### Interrupts {#irq} - -Hardware interrupts can be used to notify a protection domain. -The system description specifies if a protection domain receives notifications for any hardware interrupt sources. -Each hardware interrupt is assigned a channel identifier. -In this way the protection domain can distinguish the hardware interrupt from other notifications. -A specific hardware interrupt can only be associated with at most one protection domain. It should be noted that once a -hardware interrupt has been received, it will not be received again until `microkit_irq_ack` is called. The seL4 kernel -will mask the hardware interrupt until it has been acknowledged. - -Microkit does not provides timers, nor any *sleep* API. -After initialisation, activity in the system is initiated by an interrupt causing a `notified` entry point to be invoked. -That notified function may in turn notify or call other protection domains that cause other system activity, but eventually all activity indirectly initiated from that interrupt will complete, at which point the system is inactive again until another interrupt occurs. - -### Faults {#fault} - -Faults such as an invalid memory access or illegal instruction are delivered to the seL4 kernel which then forwards them to -a designated 'fault handler'. By default, all faults caused by protection domains go to the system fault handler which -simply prints out details about the fault in a debug configuration. - -When a protection domain is a child of another protection domain, the designated fault handler for the child is the parent -protection domain. The same applies for a virtual machine. - -This means that whenever a fault is caused by a child, it will be delivered to the parent PD instead of the system fault -handler via the `fault` entry point. It is then up to the parent to decide how the fault is handled. - -The default system fault handler (aka the monitor) has the highest priority and so will -execute and handle faults immediately after they occur. For child PDs that have their faults -delivered to another PD, the fault being handled depends on when the parent PD is scheduled. - -### I/O Ports {#ioport} - -I/O ports are x86 mechanisms to access certain physical devices (e.g. PC serial ports or PCI) using the `in` and `out` CPU instructions. The system description specifies if a protection domain have access to certain port address ranges. These accesses will be executed by seL4 and the result returned to protection domains. - -## SDK {#sdk} - -Microkit is distributed as a software development kit (SDK). - -The SDK includes support for one or more *boards*. -Three *configurations* are supported for each board: *debug*, *release*, and *benchmark*. -See [the Configurations section](#config) for more details. - -The SDK contains: - -* Microkit user manual (this document) -* Microkit tool - -Additionally, for each supported board configuration the following are provided: - -* `libmicrokit.a` -* `initialiser.elf` -* `monitor.elf` -* seL4 kernel image - * On ARM/RISC-V: `sel4.elf` - * On x86-64: `sel4_64.elf` (64-bit) and `sel4_32.elf` (32-bit) - -On ARM and RISC-V, an additional `loader.elf` is provided, which acts as the system's bootloader. - -On x86-64, 32-bit/64-bit variants of the kernel are provided as even on 64-bit platforms (e.g QEMU), -a 32-bit kernel is required. - -There are also examples provided in the `example` directory. - -The Microkit SDK does **not** provide, nor require, any specific build system. -The user is free to build their system using whatever build system is deemed most appropriate for their specific use case. - -The Microkit tool should be invoked by the system build process to transform a system description (and any referenced program images) into an image file which can be loaded by the target board's bootloader. - -The ELF files provided as program images should be standard ELF files and have been linked against the provided `libmicrokit.a`. - -### Configurations {#config} - -#### Debug - -The *debug* configuration includes a debug build of the seL4 kernel to allow console debug output using the kernel's UART driver. - -#### Release - -The *release* configuration is a release build of the seL4 kernel and is intended for production builds. The loader, monitor, initialiser and -kernel do *not* perform any serial output. - -##### Proofs - -The formal verification of seL4 applies to a specific set of seL4 configuration only. This means that making a *release* build -of a Microkit system does not imply that the seL4 kernel being used is verified. - -Currently Microkit always uses the MCS configuration of seL4 which is still undergoing verification, scheduled to complete -for RISC-V in 2026 and AArch64 in 2027. The design proofs for MCS are done but the work to show that the kernel code conforms -to the design is still undergoing. - -You can find more information about what verified seL4 configurations do exist -[here](https://docs.sel4.systems/projects/sel4/verified-configurations.html) - -A roadmap for upcoming verification is available [here](https://sel4.systems/roadmap.html). - -#### Benchmark - -The *benchmark* configuration uses a build of the seL4 kernel that exports the hardware's performance monitoring unit (PMU) to PDs. -The kernel also tracks information about CPU utilisation. This benchmark configuration exists due a limitation of the seL4 kernel -and is intended to be removed once [RFC-16 is implemented](https://github.com/seL4/rfcs/pull/22). - -#### Multi-core (SMP) configurations {#multicore_config} - -The configurations listed above default to using the uni-core configuration of seL4/Microkit. -Currently we do not want to default to using the multi-core configuration of the kernel so -separate configurations exist for users wanting to use multi-core. - -The multi-core configurations are the same as the configurations listed above, except with the -*smp-* prefix. For example, *smp-debug* for the multi-core variant of *debug*. - -On ARM/RISC-V, the number of cores available defaults to the number of cores the target board has. - -On x86-64, the number of cores available depends on how many are detected at run-time. Right now -there is a fixed upper limit, see the board-specific documentation for details. - -### System Requirements - -The Microkit tool requires Linux (x86-64 or AArch64), macOS (x86-64 or AArch64). - -On Linux, the Microkit tool is statically linked and should run on any distribution. - -On macOS, the Microkit tool should run on macOS 10.12 (Sierra) or higher. - -The Microkit tool does not depend on any additional system binaries. - -## Microkit Tool {#tool} - -The Microkit tool is available in `bin/microkit`. - -The Microkit tool takes as input a system description. -The format of the system description is described in a subsequent chapter. - -Usage: - - microkit [-h] [-o OUTPUT] [-r REPORT] [--capdl-json CAPDL_SPEC] [--image-type {binary,elf,uimage}] - --board [BOARD] --config CONFIG [--search-path [SEARCH_PATH ...]] system - -The path to the system description file, board to build the system for, and configuration to build for must be provided. - -The search paths provided tell the tool where to find any program images specified in the system description file. - -In the case of errors, a diagnostic message shall be output to `stderr` and a non-zero code returned. - -In the case of success, a loadable image file and a report shall be produced. The -type of image is specified by the `--image-type` argument. -The output paths for these can be specified by `-o` and `-r` respectively. -The default output paths are `loader.img` and `report.txt`. - -The report is a plain text file describing important information about the system. -The report can be useful when debugging potential system problems. -This report does not have a fixed format and may change between versions. -It is not intended to be machine readable. - -### Image format - -#### ARM - -On ARM, the Microkit tool will produce either a raw binary that is intended to be loaded and jumped or -an ELF. By default, the tool will produce a raw binary unless the format is specified using the `--image-type` argument. - -For the raw binary format, there is a specified entry point of the image that is documented in the board-specific -instructions in this manual, under [Board Support Packages](#bsps). If the image is not loaded at this address -it should still work by relocating itself upon boot. - -This image is expected to be loaded via a previous bootloader, typically U-Boot using the `go` command for -the binary image format and the `bootelf` command for ELFs. Note when using `bootelf` you may need to set -the `autostart` environment variable with `setenv autostart yes` to have the image executed after `bootelf`. - -See the board-specific instructions for more details. - -#### RISC-V - -On RISC-V, the Microkit tool can produce either a raw binary that is intended to be loaded and jumped, -a uImage with the Linux header or an ELF. Typically the tool will produce a uImage by default, for -board-specific details see [Board Support Packages](#bsps). - -For the raw binary format, there is a specified entry point of the image that is documented in the board-specific -instructions in this manual, under [Board Support Packages](#bsps). If the image is not loaded at this address -it should still work by relocating itself upon boot. - -For the uImage format. You may load this image anywhere in memory along with your platform's DTB, then use -the `bootm` command in U-Boot. It will copy the loader to the correct location in memory and jump to it. - -#### x86-64 - -On x86-64, the image format is always ELF, it is expected to be loaded as a Multiboot boot module. - -See [x86-64 generic support](#x86_64_generic) for more details. - -## Language Support - -There are native APIs for C/C++ and Rust. - -[libmicrokit](#libmicrokit) exports a C API and so can be used in any language -that supports C FFI. - -For Rust, native bindings exist but are not included in the SDK itself. They are -available at [rust-sel4](https://github.com/seL4/rust-sel4). - -## libmicrokit {#libmicrokit} - -All program images should link against `libmicrokit.a`. - -The library provides the C runtime for the protection domain, along with interfaces for the Microkit APIs. - -The component must provide the following functions: - - void init(void); - void notified(microkit_channel ch); - -If the protection domain provides a protected procedure it must also implement: - - microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo); - -If the protection domain has children it must also implement: - - seL4_Bool fault(microkit_child child, microkit_msginfo msginfo, - microkit_msginfo *reply_msginfo); - -`libmicrokit` provides the following functions: - - microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo); - void microkit_notify(microkit_channel ch); - microkit_msginfo microkit_msginfo_new(seL4_Word label, seL4_Uint16 count); - seL4_Word microkit_msginfo_get_label(microkit_msginfo msginfo); - seL4_Word microkit_msginfo_get_count(microkit_msginfo msginfo); - void microkit_irq_ack(microkit_channel ch); - void microkit_deferred_notify(microkit_channel ch); - void microkit_deferred_irq_ack(microkit_channel ch); - void microkit_pd_restart(microkit_child pd, seL4_Word entry_point); - void microkit_pd_stop(microkit_child pd); - void microkit_mr_set(seL4_Uint8 mr, seL4_Word value); - seL4_Word microkit_mr_get(seL4_Uint8 mr); - void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point); - void microkit_vcpu_stop(microkit_child vcpu); - void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq, - seL4_Uint8 priority, seL4_Uint8 group, - seL4_Uint8 index); - void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq); - seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg); - void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value); - void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response); - void microkit_x86_ioport_write_8(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data); - void microkit_x86_ioport_write_16(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data); - void microkit_x86_ioport_write_32(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data); - seL4_Uint8 microkit_x86_ioport_read_8(microkit_ioport ioport_id, seL4_Word port_addr); - seL4_Uint16 microkit_x86_ioport_read_16(microkit_ioport ioport_id, seL4_Word port_addr); - seL4_Uint32 microkit_x86_ioport_read_32(microkit_ioport ioport_id, seL4_Word port_addr); - seL4_Word microkit_vcpu_x86_read_vmcs(microkit_child vcpu, seL4_Word field); - void microkit_vcpu_x86_write_vmcs(microkit_child vcpu, seL4_Word field, seL4_Word value); - seL4_Word microkit_vcpu_x86_read_msr(microkit_child vcpu, seL4_Word field); - void microkit_vcpu_x86_write_msr(microkit_child vcpu, seL4_Word field, seL4_Word value); - void microkit_vcpu_x86_enable_ioport(microkit_child vcpu, microkit_ioport ioport_id, - seL4_Word port_addr, seL4_Word length); - void microkit_vcpu_x86_disable_ioport(microkit_child vcpu, seL4_Word port_addr, seL4_Word length); - void microkit_vcpu_x86_write_regs(microkit_child vcpu, seL4_VCPUContext *regs); - - -### `void init(void)` - -Every PD must expose an `init` entry point. -This is called by the system at boot time. - -### `void notified(microkit_channel ch)` - -The `notified` entry point is called by the system when a PD has received a notification on a channel. - -`ch` identifies the channel which has been notified (and indirectly the PD that performed the notification). - -**Note:** `ch` could identify an interrupt. - -Channel identifiers are specified in the system configuration. - -### `microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo)` - -The `protected` entry point is optional. -This is invoked when another PD calls `microkit_ppcall` on a channel shared with the PD. - -The `ch` argument identifies the channel on which the PP was invoked. -Indirectly this identifies the PD performing the call. -Channel identifiers are specified in the system configuration. -**Note:** The channel argument is passed by the system and is unforgeable. - -The `msginfo` argument is the argument passed to the PP and is provided by the calling PD. -The contents of the message is up to a pre-arranged protocol between the PDs. -The message contents are opaque to the system. -Note: The message is *copied* from the caller. - -The returned `microkit_msginfo` is the return value of the protected procedure. -As with arguments, this is *copied* to the caller. - -### `seL4_Bool fault(microkit_child child, microkit_msginfo msginfo, microkit_msginfo *reply_msginfo)` - -The `fault` entry point being invoked depends on whether the given PD has children. -It is invoked when a child PD or VM causes a fault. - -The `child` argument identifies the child that caused the fault. - -The `msginfo` argument is given by the seL4 kernel when a fault occurs and contains information -as to what fault occurred. - -The `reply_msginfo` argument is given by libmicrokit and can be used to reply to the fault. - -The returned `seL4_Bool` is whether or not to reply to the fault with the message `reply_msginfo`. -Returning `seL4_True` will reply to the fault. Returning `seL4_False` will not reply to the fault. - -You can use `microkit_msginfo_get_label` on `msginfo` to deduce what kind of fault happened -(for example, whether it was a user exception or a virtual memory fault). - -Whether or not you reply to the fault depends on the type of fault that has occurred and how you want -to handle it. - -To find the full list of possible faults that could occur and details regarding to replying to a particular -kind of fault, please see the 'Faults' section of the -[seL4 reference manual](https://sel4.systems/Info/Docs/seL4-manual-latest.pdf). - -### `microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo)` - -Performs a call to a protected procedure in a different PD. -The `ch` argument identifies the protected procedure to be called. -`msginfo` is passed as argument to the protected procedure. -Channel identifiers are specified in the system configuration. - -The protected procedure's return data is returned in the `microkit_msginfo`. - -### `void microkit_notify(microkit_channel ch)` - -Notify the channel `ch`. -Channel identifiers are specified in the system configuration. - -### `void microkit_irq_ack(microkit_channel ch)` - -Acknowledge the interrupt identified by the specified channel. - -### `void microkit_deferred_notify(microkit_channel ch)` - -The same as `microkit_notify` but will instead not actually perform the notify until -the entry point where `microkit_deferred_notify` was called returns. - -It is important to note that only a single 'deferred' API call can be made within the -same entry point. - -The purpose of this API is for performance critical code as this API saves -a kernel system call. - -### `void microkit_deferred_irq_ack(microkit_channel ch)` - -The same as `microkit_irq_ack` but will instead not actually perform the IRQ acknowledge -until the entry point where `microkit_deferred_irq_ack` was called returns. - -It is important to note that only a single 'deferred' API call can be made within the -same entry point. - -The purpose of this API is for performance critical code as this API saves -a kernel system call. - -### `void microkit_pd_restart(microkit_child pd, uintptr_t entry_point)` - -Restart the execution of a child protection domain with ID `pd` at the given `entry_point`. -This will set the program counter of the child protection domain to `entry_point`. - -### `void microkit_pd_stop(microkit_child pd)` - -Stop the execution of the child protection domain with ID `pd`. - -### `microkit_msginfo microkit_msginfo_new(uint64_t label, uint16_t count)` - -Creates a new message structure. - -The message can be passed to `microkit_ppcall` or returned from `protected`. - -### `uint64_t microkit_msginfo_get_label(microkit_msginfo msginfo)` - -Returns the label from a message. - -### `uint64_t microkit_msginfo_get_count(microkit_msginfo msginfo)` - -Returns the count of message registers in the message. - -### `uint64_t microkit_mr_get(uint8_t mr)` - -Get a message register. - -### `void microkit_mr_set(uint8_t mr, uint64_t value)` - -Set a message register. - -### `void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point)` - -Restart the execution of a VM's virtual CPU with ID `vcpu` at the given `entry point`. -This will set the program counter of the vCPU to `entry_point`. - -### `void microkit_vcpu_stop(microkit_child vcpu)` - -Stop the execution of the VM's virtual CPU with ID `vcpu`. - -### `void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq, -seL4_Uint8 priority, seL4_Uint8 group, -seL4_Uint8 index)` - -Inject a virtual ARM interrupt for a virtual CPU `vcpu` with IRQ number `irq`. -The `priority` (0-31) determines what ARM GIC (generic interrupt controller) -priority level the virtual IRQ will be injected as. The `group` determines whether -the virtual IRQ will be injected into secure world (1) or non-secure world (0). -The `index` is the index of the virtual GIC list register. - -### `void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq)` - -Acknowledge a ARM virtual Private Peripheral Interrupt (PPI) with IRQ number `irq` -for a VM's vCPU with ID `vcpu`. - -### `seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg)` - -Read a register for a given virtual CPU with ID `vcpu`. The `reg` argument is the index of the -register that is read. The list of registers is defined by the enum `seL4_VCPUReg` -in the seL4 source code. - -### `void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value)` - -Write to a register for a given virtual CPU with ID `vcpu`. The `reg` argument is the index of the -register that is written to. The `value` argument is what the register will be set to. -The list of registers is defined by the enum `seL4_VCPUReg` in the seL4 source code. - -### `void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response)` - -The API takes in arguments for a Secure Monitor Call which will be performed by seL4. Any -response values will be placed into the `response` structure. - -The `seL4_ARM_SMCContext` structure contains fields for registers x0 to x7. - -Note that this API is only available when the PD making the call has been configured to -have SMC enabled in the SDF. Note that when the kernel makes the actual SMC, it cannot -pre-empt the Secure Monitor and therefore any kernel WCET properties are no longer guaranteed. - -### `void microkit_x86_ioport_write_(8|16|32)(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data)` - -Write an 8, 16, or 32 bits value at port address `port_addr` to I/O Port with ID `ioport_id`. - -### `seL4_Uint(8|16|32) microkit_x86_ioport_read_(8|16|32)(microkit_ioport ioport_id, seL4_Word port_addr)` - -Read an 8, 16, or 32 bits value at port address `port_addr` from I/O Port with ID `ioport_id`. - -### `seL4_Word microkit_vcpu_x86_read_vmcs(microkit_child vcpu, seL4_Word field)` - -Read a Virtual Machine Control Structure field specified by `field` for a given virtual CPU -with ID `vcpu` using the `vmread` instruction. - -All the VMCS fields are listed in the seL4 source at `include/arch/x86/arch/object/vcpu.h`. - -The following fields can be read from: - -* `VMX_GUEST_RIP` -* `VMX_GUEST_RSP` -* `VMX_GUEST_ES_SELECTOR` -* `VMX_GUEST_CS_SELECTOR` -* `VMX_GUEST_SS_SELECTOR` -* `VMX_GUEST_DS_SELECTOR` -* `VMX_GUEST_FS_SELECTOR` -* `VMX_GUEST_GS_SELECTOR` -* `VMX_GUEST_LDTR_SELECTOR` -* `VMX_GUEST_TR_SELECTOR` -* `VMX_GUEST_DEBUGCTRL` -* `VMX_GUEST_PAT` -* `VMX_GUEST_EFER` -* `VMX_GUEST_PERF_GLOBAL_CTRL` -* `VMX_GUEST_PDPTE0` -* `VMX_GUEST_PDPTE1` -* `VMX_GUEST_PDPTE2` -* `VMX_GUEST_PDPTE3` -* `VMX_GUEST_ES_LIMIT` -* `VMX_GUEST_CS_LIMIT` -* `VMX_GUEST_SS_LIMIT` -* `VMX_GUEST_DS_LIMIT` -* `VMX_GUEST_FS_LIMIT` -* `VMX_GUEST_GS_LIMIT` -* `VMX_GUEST_LDTR_LIMIT` -* `VMX_GUEST_TR_LIMIT` -* `VMX_GUEST_GDTR_LIMIT` -* `VMX_GUEST_IDTR_LIMIT` -* `VMX_GUEST_ES_ACCESS_RIGHTS` -* `VMX_GUEST_CS_ACCESS_RIGHTS` -* `VMX_GUEST_SS_ACCESS_RIGHTS` -* `VMX_GUEST_DS_ACCESS_RIGHTS` -* `VMX_GUEST_FS_ACCESS_RIGHTS` -* `VMX_GUEST_GS_ACCESS_RIGHTS` -* `VMX_GUEST_LDTR_ACCESS_RIGHTS` -* `VMX_GUEST_TR_ACCESS_RIGHTS` -* `VMX_GUEST_INTERRUPTABILITY` -* `VMX_GUEST_ACTIVITY` -* `VMX_GUEST_SMBASE` -* `VMX_GUEST_SYSENTER_CS` -* `VMX_GUEST_PREEMPTION_TIMER_VALUE` -* `VMX_GUEST_ES_BASE` -* `VMX_GUEST_CS_BASE` -* `VMX_GUEST_SS_BASE` -* `VMX_GUEST_DS_BASE` -* `VMX_GUEST_FS_BASE` -* `VMX_GUEST_GS_BASE` -* `VMX_GUEST_LDTR_BASE` -* `VMX_GUEST_TR_BASE` -* `VMX_GUEST_GDTR_BASE` -* `VMX_GUEST_IDTR_BASE` -* `VMX_GUEST_DR7` -* `VMX_GUEST_RFLAGS` -* `VMX_GUEST_PENDING_DEBUG_EXCEPTIONS` -* `VMX_GUEST_SYSENTER_ESP` -* `VMX_GUEST_SYSENTER_EIP` -* `VMX_CONTROL_CR0_MASK` -* `VMX_CONTROL_CR4_MASK` -* `VMX_CONTROL_CR0_READ_SHADOW` -* `VMX_CONTROL_CR4_READ_SHADOW` -* `VMX_DATA_INSTRUCTION_ERROR` -* `VMX_DATA_EXIT_INTERRUPT_INFO` -* `VMX_DATA_EXIT_INTERRUPT_ERROR` -* `VMX_DATA_IDT_VECTOR_INFO` -* `VMX_DATA_IDT_VECTOR_ERROR` -* `VMX_DATA_EXIT_INSTRUCTION_LENGTH` -* `VMX_DATA_EXIT_INSTRUCTION_INFO` -* `VMX_DATA_GUEST_PHYSICAL` -* `VMX_DATA_IO_RCX` -* `VMX_DATA_IO_RSI` -* `VMX_DATA_IO_RDI` -* `VMX_DATA_IO_RIP` -* `VMX_DATA_GUEST_LINEAR_ADDRESS` -* `VMX_CONTROL_ENTRY_INTERRUPTION_INFO` -* `VMX_CONTROL_PIN_EXECUTION_CONTROLS` -* `VMX_CONTROL_PRIMARY_PROCESSOR_CONTROLS` -* `VMX_CONTROL_EXCEPTION_BITMAP` -* `VMX_CONTROL_EXIT_CONTROLS` -* `VMX_GUEST_CR0` -* `VMX_GUEST_CR3` -* `VMX_GUEST_CR4` - -### `void microkit_vcpu_x86_write_vmcs(microkit_child vcpu, seL4_Word field, seL4_Word value)` - -Write a Virtual Machine Control Structure field specified by `field` for a given virtual CPU -with ID `vcpu` using the `vmwrite` instruction. The value may be modified to ensure any bits -that are fixed in the hardware are correct, and that any features required for kernel correctness -are not disabled. - -All the VMCS fields are listed in the seL4 source at `include/arch/x86/arch/object/vcpu.h`. - -The following fields can be written to: - -* `VMX_GUEST_RIP` -* `VMX_GUEST_RSP` -* `VMX_GUEST_ES_SELECTOR` -* `VMX_GUEST_CS_SELECTOR` -* `VMX_GUEST_SS_SELECTOR` -* `VMX_GUEST_DS_SELECTOR` -* `VMX_GUEST_FS_SELECTOR` -* `VMX_GUEST_GS_SELECTOR` -* `VMX_GUEST_LDTR_SELECTOR` -* `VMX_GUEST_TR_SELECTOR` -* `VMX_GUEST_DEBUGCTRL` -* `VMX_GUEST_PAT` -* `VMX_GUEST_EFER` -* `VMX_GUEST_PERF_GLOBAL_CTRL` -* `VMX_GUEST_PDPTE0` -* `VMX_GUEST_PDPTE1` -* `VMX_GUEST_PDPTE2` -* `VMX_GUEST_PDPTE3` -* `VMX_GUEST_ES_LIMIT` -* `VMX_GUEST_CS_LIMIT` -* `VMX_GUEST_SS_LIMIT` -* `VMX_GUEST_DS_LIMIT` -* `VMX_GUEST_FS_LIMIT` -* `VMX_GUEST_GS_LIMIT` -* `VMX_GUEST_LDTR_LIMIT` -* `VMX_GUEST_TR_LIMIT` -* `VMX_GUEST_GDTR_LIMIT` -* `VMX_GUEST_IDTR_LIMIT` -* `VMX_GUEST_ES_ACCESS_RIGHTS` -* `VMX_GUEST_CS_ACCESS_RIGHTS` -* `VMX_GUEST_SS_ACCESS_RIGHTS` -* `VMX_GUEST_DS_ACCESS_RIGHTS` -* `VMX_GUEST_FS_ACCESS_RIGHTS` -* `VMX_GUEST_GS_ACCESS_RIGHTS` -* `VMX_GUEST_LDTR_ACCESS_RIGHTS` -* `VMX_GUEST_TR_ACCESS_RIGHTS` -* `VMX_GUEST_INTERRUPTABILITY` -* `VMX_GUEST_ACTIVITY` -* `VMX_GUEST_SMBASE` -* `VMX_GUEST_SYSENTER_CS` -* `VMX_GUEST_PREEMPTION_TIMER_VALUE` -* `VMX_GUEST_ES_BASE` -* `VMX_GUEST_CS_BASE` -* `VMX_GUEST_SS_BASE` -* `VMX_GUEST_DS_BASE` -* `VMX_GUEST_FS_BASE` -* `VMX_GUEST_GS_BASE` -* `VMX_GUEST_LDTR_BASE` -* `VMX_GUEST_TR_BASE` -* `VMX_GUEST_GDTR_BASE` -* `VMX_GUEST_IDTR_BASE` -* `VMX_GUEST_DR7` -* `VMX_GUEST_RFLAGS` -* `VMX_GUEST_PENDING_DEBUG_EXCEPTIONS` -* `VMX_GUEST_SYSENTER_ESP` -* `VMX_GUEST_SYSENTER_EIP` -* `VMX_CONTROL_CR0_MASK` -* `VMX_CONTROL_CR4_MASK` -* `VMX_CONTROL_CR0_READ_SHADOW` -* `VMX_CONTROL_CR4_READ_SHADOW` -* `VMX_CONTROL_EXCEPTION_BITMAP` -* `VMX_CONTROL_ENTRY_INTERRUPTION_INFO` -* `VMX_CONTROL_ENTRY_EXCEPTION_ERROR_CODE` -* `VMX_CONTROL_PIN_EXECUTION_CONTROLS` -* `VMX_CONTROL_PRIMARY_PROCESSOR_CONTROLS` -* `VMX_CONTROL_SECONDARY_PROCESSOR_CONTROLS` -* `VMX_CONTROL_EXIT_CONTROLS` -* `VMX_GUEST_CR3` -* `VMX_GUEST_CR0` -* `VMX_GUEST_CR4` - -### `seL4_Word microkit_vcpu_x86_read_msr(microkit_child vcpu, seL4_Word field)` - -Read a 64-bit Model Specific Register of a given virtual CPU with ID `vcpu` specified by -`field` from hardware using the `rdmsr` instruction. The following registers can be written to: - -* `IA32_LSTAR_MSR` -* `IA32_STAR_MSR` -* `IA32_CSTAR_MSR` -* `IA32_FMASK_MSR` - -### `void microkit_vcpu_x86_write_msr(microkit_child vcpu, seL4_Word field, seL4_Word value)` - -Write a 64-bit Model Specific Register of a given virtual CPU with ID `vcpu` specified by -`field` to hardware using the `wrmsr` instruction. The following registers can be read from: - -* `IA32_LSTAR_MSR` -* `IA32_STAR_MSR` -* `IA32_CSTAR_MSR` -* `IA32_FMASK_MSR` - -### `void microkit_vcpu_x86_enable_ioport(microkit_child vcpu, microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word length)` - -Enable I/O port range `[port_addr..port_addr + length)` of I/O Port with ID `ioport_id` -in the execution environment of a given virtual CPU with ID `vcpu`. - -### `void microkit_vcpu_x86_disable_ioport(microkit_child vcpu, seL4_Word port_addr, seL4_Word length)` - -Disable I/O port range `[port_addr..port_addr + length)` in the execution environment of a given -virtual CPU with ID `vcpu`. - -### `void microkit_vcpu_x86_write_regs(microkit_child vcpu, seL4_VCPUContext *regs)` - -Write the registers of a given virtual CPU with ID `vcpu`. The `regs` argument is the pointer to -the struct of registers `seL4_VCPUContext` that are written from. - -## System Description File {#sysdesc} - -This section describes the format of the System Description File (SDF). - -The system description file is an XML file that is provided as input to the -`microkit` tool. - -The root element of the XML file is `system`. - -Within the `system` root element the following child elements are supported: - -* `protection_domain` -* `memory_region` -* `channel` - -### `protection_domain` - -The `protection_domain` element describes a protection domain. - -It supports the following attributes: - -* `name`: A unique name for the protection domain -* `priority`: The priority of the protection domain (integer 0 to 254). -* `budget`: (optional) The PD's budget in microseconds; defaults to 1,000. -* `period`: (optional) The PD's period in microseconds; must not be smaller than the budget; defaults to the budget. -* `passive`: (optional) Indicates that the protection domain will be passive and thus have its scheduling context removed after initialisation; defaults to false. -* `stack_size`: (optional) Number of bytes that will be used for the PD's stack. - Must be be between 4KiB and 16MiB and be 4K page-aligned. Defaults to 8KiB. -* `cpu`: (optional) set the physical CPU core this PD will run on. Defaults to zero. -* `smc`: (optional, only on ARM) Allow the PD to give an SMC call for the kernel to perform.. Defaults to false. - -Additionally, it supports the following child elements: - -* `program_image`: (exactly one) Describes the program image for the protection domain. -* `map`: (zero or more) Describes mapping of memory regions into the protection domain. -* `irq`: (zero or more) Describes hardware interrupt associations. -* `setvar`: (zero or more) Describes variable rewriting. -* `protection_domain`: (zero or more) Describes a child protection domain. -* `virtual_machine`: (zero or one) Describes a child virtual machine. - -The `program_image` element has a single `path` attribute describing the path to an ELF file. - -The `map` element has the following attributes: - -* `mr`: Identifies the memory region to map. -* `vaddr`: Identifies the virtual address at which to map the memory region. -* `perms`: Identifies the permissions with which to map the memory region. Can be a combination of `r` (read), `w` (write), and `x` (eXecute), with the exception of a write-only mapping (just `w`). -* `cached`: (optional) Determines if mapped with caching enabled or disabled. Defaults to `true`. -* `setvar_vaddr`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the virtual address of the memory region. -* `setvar_size`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the size of the memory region. - -The `irq` element has the following attributes on ARM and RISC-V: - -* `irq`: The hardware interrupt number. -* `id`: The channel identifier. Must be at least 0 and less than 63. -* `trigger`: (optional) Whether the IRQ is edge triggered ("edge") or level triggered ("level"). Defaults to "level". -* `setvar_id`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ. - -The `irq` element has the following attributes when registering X86_64 IOAPIC interrupts: - -* `id`: The channel identifier. Must be at least 0 and less than 63. -* `pin`: IOAPIC pin that generates the interrupt. -* `vector`: CPU vector to deliver the interrupt to. -* `ioapic`: (optional) Zero based index of the IOAPIC to get the interrupt from. Defaults to 0. -* `level`: (optional) Whether the IRQ is level triggered (1) or edge triggered (0). Defaults to level (1). -* `polarity`: (optional) Whether the line polarity is high (1) or low (0). Defaults to high (1). -* `setvar_id`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ. - -The `irq` element has the following attributes when registering X86_64 MSI interrupts: - -* `id`: The channel identifier. Must be at least 0 and less than 63. -* `pcidev`: The PCI device address of the device that will generate the interrupt, in BUS:DEV:FUNC notation (e.g. 01:1f:2). -* `handle`: Value of the handle programmed into the data portion of the MSI. -* `vector`: CPU vector to deliver the interrupt to. -* `setvar_id`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ. - -The `ioport` element has the following attributes: - -* `id`: The I/O port identifier. Must be at least 0 and less than 63. -* `addr`: The base address of the I/O port. -* `size`: The size in bytes of the I/O port region. -* `setvar_id`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the I/O port identifier. -* `setvar_addr`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the base address of the I/O port. - -The `setvar` element has the following attributes: - -* `symbol`: Name of a symbol in the ELF file. -* `region_paddr`: Name of an MR. The symbol's value shall be updated to this MR's physical address. - Note that on x86-64 platforms this MR must have a specified physical address. - This restriction is due to x86-64 physical memory layout not being known at build-time. - -The `protection_domain` element has the same attributes as any other protection domain as well as: - -* `id`: The ID of the child for the parent to refer to. -* `setvar_id`: (optional) Specifies a symbol in the parent program image. This symbol will be rewritten with the ID of the child. - -The `virtual_machine` element has the following attributes: - -* `name`: A unique name for the virtual machine -* `priority`: The priority of the virtual machine (integer 0 to 254). -* `budget`: (optional) The VM's budget in microseconds; defaults to 1,000. -* `period`: (optional) The VM's period in microseconds; must not be smaller than the budget; defaults to the budget. - -Additionally, it supports the following child elements: - -* `vcpu`: (one or more) Describes the virtual CPU that will be tied to the virtual machine. -* `map`: (zero or more) Describes mapping of memory regions into the virtual machine. - -The `vcpu` element has the following attributes: - -* `id`: The vCPU identifier. Must be at least 0 and less than 62. -* `setvar_id`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the vCPU identifier. - -The `map` element has the same attributes as the protection domain with the exception of `setvar_vaddr`. - -### `memory_region` - -The `memory_region` element describes a memory region. - -It supports the following attributes: - -* `name`: A unique name for the memory region -* `size`: Size of the memory region in bytes (must be a multiple of the page size) -* `page_size`: (optional) Size of the pages used in the memory region; must be a supported page size if provided. Defaults to the largest page size for the target architecture that the memory region is aligned to. -* `phys_addr`: (optional) The physical address for the start of the memory region (must be a multiple of the page size). - -The `memory_region` element does not support any child elements. - -#### Page sizes by architecture - -Below are the available page sizes for each architecture that Microkit supports. - -##### AArch64 - -* 0x1000 (4KiB) -* 0x200000 (2MiB) - -##### RISC-V 64-bit - -* 0x1000 (4KiB) -* 0x200000 (2MiB) - -##### x86-64 - -* 0x1000 (4KiB) -* 0x200000 (2MiB) - -### `channel` - -The `channel` element has exactly two `end` children elements for specifying the two PDs associated with the channel. - -The `end` element has the following attributes: - -* `pd`: Name of the protection domain for this end. -* `id`: Channel identifier in the context of the named protection domain. Must be at least 0 and less than 63. -* `pp`: (optional) Indicates that the protection domain for this end can perform a protected procedure call to the other end; defaults to false. - Protected procedure calls can only be to PDs of strictly higher priority. -* `notify`: (optional) Indicates that the protection domain for this end can send a notification to the other end; defaults to true. -* `setvar_id`: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier. - -The `id` is passed to the PD in the `notified` and `protected` entry points. -The `id` should be passed to the `microkit_notify` and `microkit_ppcall` functions. - -## Board Support Packages {#bsps} - -This chapter describes the board support packages that are available in the SDK. - -The currently supported platforms are: -* ariane -* cheshire -* hifive_p550 -* imx8mm_evk -* imx8mp_evk -* imx8mp_iotgate -* imx8mq_evk -* maaxboard -* odroidc2 -* odroidc4 -* qemu_virt_aarch64 -* qemu_virt_riscv64 -* rockpro64 -* rpi4b_1gb -* rpi4b_2gb -* rpi4b_4gb -* rpi4b_8gb -* serengeti -* star64 -* tqma8xqp1gb -* ultra96v2 -* x86_64_generic -* x86_64_generic_vtx -* zcu102 - -### Ariane (CVA6) {#ariane} - -Initial support is available for the CVA6 (formerly Ariane) core design -on the Digilent Genesys2 board. CVA6 is an open-source RISC-V (rv64i) processor. - -Microkit support expects that a compatible RISC-V SBI (e.g OpenSBI) has executed before -jumping to the beginning of the loader image. - -Microkit outputs an ELF for this platform. - -You may compile OpenSBI with the Microkit image as a payload, or alternately install -OpenSBI (with U-Boot optionally) to the SD card. - -If you are booting from U-Boot, use the following command to start the system image: - - => bootelf ${image_addr} - -Where `image_addr` is the load address of the ELF image. - -Note that the OpenSBI version from the CVA6 SDK at the time of writing has issues when -booting. It is recommended to use the mainline OpenSBI. - -### Compulab IOT-GATE-IMX8MPLUS {#imx8mp_iotgate} - -The IOT-GATE-IMX8PLUS is based on the NXP i.MX8MP SoC. - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x50000000 - -### Cheshire {#cheshire} - -Support is available for [Cheshire](https://github.com/pulp-platform/cheshire). -It is an SoC design based on the CVA6 core, implementing a 64-bit RISC-V CPU. - -Microkit outputs an ELF for this platform. Several steps are required in order to boot. - -A custom version of OpenSBI is required. It can be found -[here](https://github.com/pulp-platform/opensbi/tree/cheshire). -Build the firmware payload using platform `fpga/cheshire`. - -To boot a Microkit image, use a GDB prompt via openOCD per [seL4 Docs](https://docs.sel4.systems/Hardware/cheshire.html): - -1. Reset board - - (gdb) monitor reset halt - -2. Set the `a0` and `a1` registers for OpenSBI - - # tell OpenSBI where DTB is (there is none) - (gdb) set $a0=0 - # tell OpenSBI that the default hart is #0 - (gdb) set $a1=0 - -3. Load OpenSBI's FW_JUMP payload targeted at `0x90000000`, implicitly setting the program counter. - - (gdb) load /path/to/opensbi/fw_jump.elf - -4. Load the Microkit image: - - (gdb) restore /path/to/loader.img - -4. Allow OpenSBI and Microkit to boot: - - (gdb) continue - - -### i.MX8MM-EVK {#imx8mm_evk} - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x41000000 - -### i.MX8MP-EVK {#imx8mp_evk} - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x41000000 - -### i.MX8MQ-EVK {#imx8mq_evk} - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x41000000 - -### MaaXBoard {#maaxboard} - -The MaaXBoard is a low-cost ARM SBC based on the NXP i.MX8MQ system-on-chip. - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x50000000 - -### Odroid-C2 {#odroidc2} - -The HardKernel Odroid-C2 is an ARM SBC based on the Amlogic Meson S905 system-on-chip. It -should be noted that the Odroid-C2 is no longer available for purchase but its successor, -the Odroid-C4, is readily available at the time of writing. - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x20000000 - -### Odroid-C4 {#odroidc4} - -The HardKernel Odroid-C4 is an ARM SBC based on the Amlogic Meson S905X3 system-on-chip. - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x20000000 - -### Serengeti {#serengeti} - -Serengeti is a fork of the [Cheshire](#cheshire) platform by Trustworthy Systems. More -information on the hardware platform can be found [here](https://github.com/au-ts/serengeti). - -Right now Serengeti is a superset of Cheshire by offering more peripherals than Cheshire -has. - -For running on Serengeti, please see [Cheshire](#cheshire) for instructions. - -### SiFive Premier P550 {#hifive_p550} - -The SiFive Premier P550 is a development board based on the ESWIN EIC7700X system-on-chip. - -Microkit will produce a uImage. To load the image you will need to use -the `bootm` command. `bootm` expects an address of where -the Device Tree Blob (DTB) will be as well as the image. - -If you do not have a DTB for this platform you can obtain it from the seL4 source code with: -```sh -dtc -I dts -O dtb seL4/tools/dts/hifive-p550.dts > hifive-p550.dtb -``` - -Now you can load the images into U-Boot at the appropriate addresses, for example via TFTP: - - => setenv imgaddr "0xB0000000" - => setenv dtbaddr "0xA0000000" - => tftpboot ${imgaddr} /path/to/loader.img - => tftpboot ${dtbaddr} /path/to/hifive-p550.dtb - => bootm ${imgaddr} - ${dtbaddr} - -`imgaddr` and `dtbaddr` are arbitrarily chosen addresses in main memory for this platform, -you can load the image and DTB at another address. - -### QEMU virt (AArch64) {#qemu_virt_aarch64} - -Support is available for the virtual AArch64 QEMU platform. This is a platform that is not based -on any specific SoC or hardware platform and is intended for simulating systems for -development or testing. - -It should be noted that the platform support is configured with 2GB of main memory and the -Cortex-A53 CPU. seL4 needs to know the memory layout and CPU at build-time so if -you want to change these parameters (e.g to allow more memory), you will have to change the kernel -options for `qemu_virt_aarch64` in `build_sdk.py`. - -You can use the following command to simulate a Microkit system: - - $ qemu-system-aarch64 \ - -machine virt,virtualization=on \ - -cpu cortex-a53 \ - -nographic \ - -serial mon:stdio \ - -device loader,file=[SYSTEM IMAGE],addr=0x70000000,cpu-num=0 \ - -m size=2G - -When using the [SMP configurations](#multicore_config) add the `-smp 4` argument to the QEMU command. - -You can find more about the QEMU virt platform in the -[QEMU documentation](https://www.qemu.org/docs/master/system/target-arm.html). - -### QEMU virt (RISC-V 64-bit) {#qemu_virt_riscv64} - -Support is available for the virtual RISC-V (64-bit) QEMU platform. -This is a platform that is not based on any specific SoC or hardware platform -and is intended for simulating systems for development or testing. - -It should be noted that the platform support is configured with 2GB of main memory. -seL4 has a static amount of memory at build-time, if you want allow for more memory, -you will have to change the kernel options for `qemu_virt_riscv64` in `build_sdk.py`. - -You can use the following command to simulate a Microkit system: - - $ qemu-system-riscv64 \ - -machine virt \ - -nographic \ - -serial mon:stdio \ - -kernel [SYSTEM IMAGE] \ - -m size=2G - -When using the [SMP configurations](#multicore_config) add the `-smp 4` argument to the QEMU command. - -QEMU will start the system image using its packaged version of OpenSBI. - -You can find more about the QEMU virt platform in the -[QEMU documentation](https://www.qemu.org/docs/master/system/target-riscv.html). - -### Raspberry Pi 4B {#rpi4b_1gb} - -Support is available for the Raspberry Pi 4 Model B. There are multiple models of the -Raspberry Pi 4B that have different amounts of RAM, we have support for the 1GB, -2GB, 4GB and 8GB models. Because the amount of RAM must be known statically by -seL4, the Microkit board names differ for each model: - -* `rpi4b_1gb` for 1GB of RAM. -* `rpi4b_2gb` for 2GB of RAM. -* `rpi4b_4gb` for 4GB of RAM. -* `rpi4b_8gb` for 8GB of RAM. - -For initial board setup, please see the instructions on the -[seL4 website](https://docs.sel4.systems/Hardware/Rpi4.html). - -When getting into the U-Boot console you want to load the Microkit binary image to -address 0x10000000 and then run `go 0x10000000`. - -For example, if you were to load the image via the MMC you would run the following -U-Boot commands: - - => fatload mmc 0 0x10000000 - => go 0x10000000 - -### Pine64 ROCKPro64 {#rockpro64} - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x30000000 - -### Pine64 Star64 {#star64} - -Support is available for the Pine64 Star64 platform which is based on the -StarFive JH7110 SoC. - -The platform has a 4GB and 8GB model, we assume the 4GB model. - -The default boot flow of the Star64 is: -1. OpenSBI -2. U-Boot -3. Operating System - -This means that the system image that Microkit produces does not need to be explicitly -packaged with an SBI implementation such as OpenSBI. - -Microkit will produce a uImage. To load the image you will need to use -the `bootm` command. `bootm` expects an address of where -the Device Tree Blob (DTB) will be as well as the image. - -If you do not have a DTB for this platform you can obtain it from the seL4 source code with: -```sh -dtc -I dts -O dtb seL4/tools/dts/star64.dts > star64.dtb -``` - -Now you can load the images into U-Boot at the appropriate addresses, for example via TFTP: - - => setenv imgaddr "0xE0000000" - => setenv dtbaddr "0xD0000000" - => tftpboot ${imgaddr} /path/to/loader.img - => tftpboot ${dtbaddr} /path/to/star64.dtb - => bootm ${imgaddr} - ${dtbaddr} - -`imgaddr` and `dtbaddr` are arbitrarily chosen addresses in main memory for this platform, -you can load the image and DTB at another address. - -### TQMa8XQP 1GB {#tqma8xqp1gb} - -The TQMa8XQP is a system-on-module designed by TQ-Systems GmbH. -The modules incorporates an NXP i.MX8X Quad Plus system-on-chip and 1GiB ECC memory. - -TQ-Systems provide the MBa8Xx carrier board for development purposes. -The instructions provided assume the use of the MBa8Xx carrier board. -If you are using a different carrier board please refer to the appropriate documentation. - -Note: There are different configured of the TQMa8Xx board which include different NXP SoCs -and different memory configurations. Such modules are not supported. - -The MBa8Xx provides access to the TQMa8XQP UART via UART-USB bridge. -To access the UART connect a USB micro cable to port **X13**. -The UART-USB bridge supports 4 individual UARTs; the UART is connected to the 2nd port. - -By default the SoM will autoboot using U-Boot. -Hit any key during the boot process to stop the autoboot. - -A new board will autoboot to Linux. -You will likely want to disable autoboot: - - => env set bootdelay -1 - => env save - -The board can be reset by pressing switch **S4** (located next to the Ethernet port). -Alternatively, you can use the `reset` command from the U-Boot prompt. - -During development the most convenient way to boot a Microkit image is via network booting. -U-Boot support booting via the *tftp* protocol. -To support this you'll want to configure the network. -U-Boot supports DHCP, however it is often more reliable to explicitly set an IP address. -For example: - - => env set ipaddr 10.1.1.2 - => env set netmask 255.255.255.0 - => env set serverip 10.1.1.1 - => env save - -To use tftp you also need to set the file to load and the memory address to load it to: - - => env set bootfile loader.img - => env set loadaddr 0x80280000 - => env save - -The system image generated by the Microkit tool by default is a raw binary file. - -An example sequence of commands for booting is: - - => tftpboot - => dcache flush - => icache flush - => go ${loadaddr} - -Rather than typing these each time you can create a U-Boot script: - - => env set microkit 'tftpboot; dcache flush; icache flush; go ${loadaddr}' - => env save - => run microkit - -When debugging is enabled the kernel will use the same UART as U-Boot. - -### Ultra96V2 {#ultra96v2} - -To run the built image on the board, you have to use properly patched U-Boot - please see the section for ZCU102, for the details. - -You have to load the binary file into memory and run it: -``` -ZynqMP> tftpboot 0x40000000 loader.img -... -ZynqMP> go 0x40000000 -``` - -### x86-64 generic {#x86_64_generic} - -This board supports x86-64 platforms with generic microarchitecture and no virtualisation. - -Up to 16 CPU cores are supported. If your platform's CPU count exceeds the maximum, the excess CPUs -are ignored by seL4. This limitation is due to a build-time config option of seL4, to increase the -limit, see the board configuration in `build_sdk.py`. - -On x86-64, Microkit produces 3 ELF images in the output directory: - -- `sel4.elf`, seL4 kernel (64-bit ELF) -- `sel4_32.elf`, seL4 kernel (32-bit ELF) -- Initial Task image (Multiboot Boot Module ELF) - -The filename of the initial task image is specified with the `-o` option, and defaults to loader.img. -Both kernel ELF files are written to the same directory as the initial task image. - -Although this target is for x86-64, your bootloader may require a 32-bit kernel ELF. - -When using QEMU, you must use the 32-bit kernel ELF, for example: - - $ qemu-system-x86_64 \ - -cpu qemu64,+fsgsbase,+pdpe1gb,+xsaveopt,+xsave \ - -m "1G" \ - -display none \ - -serial mon:stdio \ - -kernel sel4_32.elf \ - -initrd loader.img - -Unlike Microkit’s `qemu_virt_aarch64` and `qemu_virt_riscv64`, the amount of memory provided to QEMU -is configurable at run time with the `-m` option, rather than at build time. - -QEMU currently does not support 64-bit kernel ELFs and gives the following error: -``` -qemu-system-x86_64: Cannot load x86-64 image, give a 32bit one. -``` - -To obtain a bootable ISO image, a Multiboot 2-compliant bootloader must be used. Please refer to your -bootloader's documentations. - -### x86_64 generic {#x86_64_generic_vtx} - -This board supports x86-64 platforms with generic microarchitecture and virtualisation. - -This configuration assumes Intel VT-x support. Currently, only 1 vCPU is supported per virtual machine -on x86-64. - -The boot process is identical to [x86-64 generic](#x86_64_generic). - -This configuration exists because some x86 emulators (for example, QEMU on macOS on Apple Silicon) do -not emulate Intel VT-x. - -If you see the following message at boot: -``` -vt-x: not supported -``` -Consider using the non VT-x configuration: [x86-64 generic](#x86_64_generic), or switch to a x86 emulator that -emulates Intel VT-x, such as [Bochs](https://bochs.sourceforge.io/). - -### ZCU102 {#zcu102} - -The ZCU102 can run on a physical board or on an appropriate QEMU based emulator. - -Microkit will produce a raw binary file by default, so when using U-Boot run the following command: - - => go 0x40000000 - -For simulating the ZCU102 using QEMU, use the following command: - - $ qemu-system-aarch64 \ - -m size=4G \ - -machine xlnx-zcu102,virtualization=on \ - -nographic \ - -device loader,file=[SYSTEM IMAGE],addr=0x40000000,cpu-num=0 \ - -serial mon:stdio - -When using the [SMP configurations](#multicore_config) add the `-smp 4` argument to the QEMU command. - -It should be noted that when using U-Boot to load and run a Microkit system image, -that there may be additional setup needed. - -For the ZynqMP class of platforms, which the ZCU102 is apart of, U-Boot does not start -the Microkit system Exception Level 2 (EL2) which is necessary for Microkit to start -(this is because seL4 is configured as a hypervisor). - -You can see that when using the `go` command, U-Boot is -[unconditionally always dropping down to EL1](https://github.com/u-boot/u-boot/blob/8937bb265a7f2251c1bd999784a4ef10e9c6080d/board/xilinx/zynqmp/zynqmp.c#L234). - -To avoid this behaviour, the call to `armv8_switch_to_el1` should be replaced with -`armv8_switch_to_el2` in this `do_go_exec` function. - -### Adding Platform Support - -The following section is a guide for adding support for a new ARM or RISC-V platform to Microkit. - -#### Prerequisites - -Before you can start with adding platform support to Microkit, the platform must be supported by the seL4 kernel. -You can find information on how to do so [here](https://docs.sel4.systems/projects/sel4/porting.html). - -#### Getting Microkit Components Working - -##### build_sdk.py - -The first step to adding Microkit support is to modify the `build_sdk.py` script in order to build the required -artefacts for the new platform. This involves adding to the `SUPPORTED_BOARDS` list with the `BoardInfo` options -containing the platform specific attributes. This should be fairly self-explanatory by looking at the existing -entries with the exception of the `loader_link_address`. - -The `loader_link_address` parameter specifies the physical address of where the bootloader for Microkit (which -is responsible for setting up the system before seL4 starts) is going to be loaded. This address needs to -match where in main memory the final system image is actually loaded (e.g where a previous bootloader such as U-Boot -loads the image to). This means that the address is restricted to the platform's main memory region. - -##### Loader - -###### UART - -The other component of Microkit that is platform dependent is the loader itself. The loader will attempt to access -the UART for debug output which requires a basic `putc` implementation. The UART device used in the loader should be -the same as what is used for the seL4 kernel debug output. - -It should be noted that on RISC-V platforms, the SBI will be used for `putc` so no porting is necessary. - -###### CPU configuration - -For supporting multi-core systems on Microkit, the loader needs to know the platform-specific CPU identifiers -that we want to make use of. - -For ARM platforms, a `psci_target_cpus` array needs to be defined which contains the PSCI `target_cpu` value for -each CPU. This value can be found by looking at the `reg` field for each CPU in the Device Tree. - -For RISC-V platforms, a `hart_ids` array needs to be defined which contains the Hart ID for -each CPU. This value can be found by looking at the `reg` field for each CPU in the Device Tree. The first value -must be the same as `FIRST_HART_ID` defined in seL4. - -##### Next steps - -Once you have patched the loader and the SDK build script, there should be no other changes required to have a working -platform port. It is a good idea at this point to boot a hello world system to confirm the port is working. - -If there are issues with porting the platform, please [open an issue on GitHub](https://github.com/sel4/microkit). - -#### Contributing Platform Support - -Once you believe that the port works, you can [open a pull request](https://github.com/seL4/microkit/pulls) with required -changes as well as documentation in the manual about the platform and how to run Microkit images on it. - -Please also update the `platforms.yml` file, you can find more information at the top of the file. - -## Rationale - -This section describes the rationales driving the Microkit design choices. - -### Overview - -The seL4 microkernel provides a set of powerful and flexible mechanisms that can be used for building almost arbitrary systems. -While minimising constraints on the nature of system designs and scope of deployments, this flexibility makes it challenging to design the best system for a particular use case, requiring extensive seL4 experience from developers. - -The Microkit addresses this challenge by constraining the -system architecture to one that provides enough features and power for -its target usage class (IoT, cyberphysical and other embedded systems -with a static architecture), enabling a much simpler set of developer-visible abstractions. - -### Protection Domains - -PDs are single-threaded to keep the programming model and implementations simple, and because this serves the needs of most present use cases in the target domains. -Extending the model to multithreaded applications (clients) is straightforward and can be done if needed. -Extending to multithreaded services is possible but requires additional infrastructure for which we see no need in the near future. - -### Protected Procedure Priorities - -The restriction of only calling to higher priority prevents deadlocks and reflects the notion that the callee operates on behalf of the caller, and it should not be possible to preempt execution of the callee unless the caller could be preempted as well. - -This greatly simplifies reasoning about real-time properties in the system; in particular, it means that PPs can be used to implement *resource servers*, where shared resources are encapsulated in a component that ensures mutual exclusion, while avoiding unbounded priority inversions through the *immediate priority ceiling protocol*. - -While it would be possible to achieve the same by allowing PPs between PDs of the same priority, this would be much harder to statically analyse for loop-freedom (and thus deadlock-freedom). -The drawback is that we waste a part of the priority space where a logical entity is split into multiple PDs, eg to separate out a particularly critical component to formally verify it, when the complete entity would be too complex for formal verification. -For the kinds of systems targeted by the Microkit, this reduction of the usable priority space is unlikely to cause problems. - -### Protected Procedure Argument Size - -The limitation on the size of by-value arguments is forced by the (architecture-dependent) limits on the payload size of the underlying seL4 operations, as well as by efficiency considerations. -The protected procedure payload should be considered as analogous to function arguments in the C language; similar limitations exist in the C ABIs (Application Binary Interfaces) of various platforms. - -### Limits - -The limitation on the number of protection domains in the system is relatively arbitrary. -Based on experience with the system and the types of systems being built it is possible for this to be increased in the future. - -The limitation on the number of channels for a protection domain is based on the size of the notification word in seL4. -Changing this to be larger than 64 would most likely require changes to seL4. The reason for why the limit is not a -power of two is due to part of the notification word being for internal libmicrokit use. - -## Internals - -The following section describes internal details for how the Microkit works -and all the components of Microkit. As a user of Microkit, it is not necessary -know this information, however, there is no harm in having a greater -understanding of the tools that you are using. - -![Microkit flow](assets/microkit_flow.svg) - -The diagram above aims to show the general flow of a Microkit system from -build-time to run-time. - -The user provides the SDF (System Description File) and the ELFs that -correspond to PD program images to the Microkit tool which is responsible -for packaging everything together into a single image for the target -platform. - -#### ARM and RISC-V - -The final image is a bootable image which contains a couple different things: - -* the Microkit loader -* seL4 -* the capDL initialiser (and associated capDL specification) - -When booting the image, the Microkit loader starts, jumps to the kernel, which -starts the capDL initialiser, which then sets up the entire system and starts -all the PDs, including the Monitor. - -#### x86 - -The tool produces the kernel image and boot module image that contains the capDL initialiser. -You must bring your own Multiboot 2 compliant bootloader which then loads the kernel and boot module. - -Now, we will go into a bit more detail about each of these stages of the -booting process as well as what exactly the Microkit tool is doing. - -### Loader (ARM and RISC-V) - -The loader starts first, it has two main jobs: - -1. Unpack all the parts of the system (kernel and initialiser) into - their expected locations within main memory. -2. Finish initialising the hardware such that the rest of the system can start. - -Before the Microkit loader starts, there would most likely have been some other -bootloader such as U-Boot or firmware on the target that did its own hardware -initialisation before starting Microkit. - -However, there are certain things that seL4 expects to be initialised -that will not be done by a previous booting stage, such as: - -* changing to the right exception level -* enabling the MMU (seL4 expects the MMU to be on when it starts) -* interrupt controller setup - -Once this is all completed, the loader jumps to seL4 which starts executing. -The loader will never be executed again. - -### capDL Initialiser - -Once the kernel has done its own initialisation, it will begin the -'initial task'. On seL4, this is a thread that contains all the initial -capabilities to resources and free memory that are used to setup the rest of the system. - -Within a Microkit environment, the 'initial task' is the capDL initialiser. Its main -job is to initialises and starts the system in conformance with the capDL specification. - -At build-time, the Microkit tool embeds the capDL specification that describe -all kernel objects that needs to be created. Then for each kernel object, the spec -describe what state they need to be in and what capabilities exist to that object -(i.e. who has access to this kernel object). For example, the spec would specify the: -- starting Instruction Pointer (IP), Stack Pointer (SP) and IPC buffer pointer of a Thread Control Block (TCB), -- page table structure and mapping attributes of an address space (VSpace), -- interrupts (IRQ), -- scheduling parameters (Scheduling Context), -- and so on... - -### Monitor - -The Monitor is a special PD that executes at the highest priority. It's job -is to receive any faults caused by protection domains crashing or causing exceptions. - -After the monitor initialises itself, goes to sleep and waits for any -faults from protection domains. On debug mode, this results in a message about -which PD caused an exception and details on the PD's state at the time of the fault. - -Other than printing fault details, the monitor does not do anything to handle -the fault, it will simply go back to sleep waiting for any other faults. - -### libmicrokit {#libmicrokit_internals} - -Unlike the previous sections, libmicrokit is not its own program but it is worth -a mention since it makes up the core of each protection domain in a system. - -When each PD starts, we enter libmicrokit's starting point which does some initial -setup and calls the `init` entry point specified by the user. Once that completes, -the PD will enter libmicrokit's event handler which sleeps until it receives events. - -These events could be notifies (from other PDs or from an interrupt), PPCs, and faults. -For each event, the appropriate user-specified entry point is called and then when it -returns the PD goes back to sleep, waiting on any more events. - -### Microkit tool - -The Microkit tool's ultimate job is to take in the description of the user's system, -the SDF, and convert into an seL4 system that boots and executes. - -There are obvious steps such as parsing the SDF and PD ELFs. But the majority of -the work done by the tool is converting the system description into the capDL specification -then embedding it into the capDL initialiser image. - -#### ARM & RISC-V specific -Since the physical memory layout of ARM and RISC-V platforms can be determined at boot -time by reading the device tree. The Microkit tool goes one step further and statically -check that the produced capDL specification is bootable on the target board. For example, -we check that there are no frames outside of device or normal memory, and that there are -enough memory to create all required kernel objects. - -In order to do this however, the Microkit tool needs to emulate how the seL4 kernel boot -to obtain the list of free untyped objects that the kernel would give to the initial task. - -While this is non-trivial to do, it comes with the useful property that if the tool -produces a valid image, there should be no errors upon initialising the system -If there are any errors with configuring the system (e.g running out of memory), -they will be caught at build-time. This can only reasonably be done due to the -static-architecture of Microkit systems. diff --git a/projects/microkit/manual/latest b/projects/microkit/manual/latest deleted file mode 120000 index 50aea0e7aba..00000000000 --- a/projects/microkit/manual/latest +++ /dev/null @@ -1 +0,0 @@ -2.1.0 \ No newline at end of file diff --git a/projects/microkit/manual/latest/assets/microkit_flow.pdf b/projects/microkit/manual/latest/assets/microkit_flow.pdf new file mode 100644 index 00000000000..3e81338977d Binary files /dev/null and b/projects/microkit/manual/latest/assets/microkit_flow.pdf differ diff --git a/projects/microkit/manual/latest/assets/microkit_flow.svg b/projects/microkit/manual/latest/assets/microkit_flow.svg new file mode 100644 index 00000000000..38182873b6c --- /dev/null +++ b/projects/microkit/manual/latest/assets/microkit_flow.svg @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/projects/microkit/manual/latest/index.html b/projects/microkit/manual/latest/index.html new file mode 100644 index 00000000000..0d52e84cb58 --- /dev/null +++ b/projects/microkit/manual/latest/index.html @@ -0,0 +1,2641 @@ + + + + + + + Microkit User Manual (v2.1.0) | seL4 docs + + + + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit User Manual (v2.1.0)

+ +

This is a web version of the manual, you can find a PDF here as well as in the +SDK at doc/microkit_user_manual.pdf.

+ +

Introduction

+ +

The seL4 Microkit is a small and simple operating system (OS) built on the seL4 microkernel. +Microkit is designed for building system with a static architecture. +A static architecture is one where system resources are assigned up-front at system initialisation time.

+ +

Purpose

+ +

The Microkit is intended to:

+ +
    +
  • provide a small and simple OS for a wide range of IoT, cyberphysical and other embedded use cases;
    • +
  • provide a reasonable degree of application portability appropriate for the targeted use cases;
    • +
  • make seL4-based systems easy to develop and deploy within the target areas;
    • +
  • leverage seL4’s strong isolation properties to support a near-minimal trusted computing base (TCB);
    • +
  • retain seL4’s trademark performance for systems built with it;
    • +
  • be, in principle, amenable to formal analysis of system safety and security properties (although such analysis is beyond the initial scope).
    • +
+ +

Overview

+ +

A Microkit system is built from a set of individual programs that are isolated from each other, and the system, in protection domains. +Protection domains can interact by calling protected procedures or sending notifications.

+ +

Microkit is distributed as a software development kit (SDK). +The SDK includes the tools, libraries and binaries required to build a Microkit system. +The Microkit source is also available which allows you to customize or extend Microkit and produce your own SDK.

+ +

To build a Microkit system you will write some programs that use libmicrokit. +Microkit programs are a little different to a typical process on a Linux-like operating system. +Rather than a single main entry point, a program has four distinct entry points: init, notified and, potentially, protected, fault.

+ +

On ARM and RISC-V, the individual programs are combined to produce a single bootable system image. +The format of the image is suitable for loading by the target board’s bootloader.

+ +

On x86-64, there are two ELF images invovled. One for the seL4 kernel, and one for the initialiser that +setups up the Microkit system. These are loaded by a Multiboot 2 compliant bootloader.

+ +

The Microkit tool, which is provided as part of the SDK, is used to generate the system image(s).

+ +

The Microkit tool takes a system description as input. +The system description is an XML file that specifies all the objects that make up the system.

+ +

Note: Microkit does not impose any specific build system; you are free to choose the build system that works best for you.

+ +

Document Structure

+ +

The Concepts chapter describes the various concepts that make up Microkit. +It is recommended that you familiarise yourself with these concepts before trying to build a system.

+ +

The SDK chapter describes the software development kit, including its components and system requirements for use.

+ +

The Microkit tool chapter describes the host system tool used for generating a system image from the system description and user-programs.

+ +

The libmicrokit chapter describes the interfaces to the Microkit library.

+ +

The System Description File chapter describes the format of the system description XML file.

+ +

The Board Support Packages chapter describes each of the board support packages included in the SDK.

+ +

The Rationale chapter documents the rationale for some of the key design choices of Microkit.

+ +

The Internals chapter documents some of the internal details for how Microkit works.

+ +

Concepts

+ +

This chapter describes the key concepts provided by Microkit.

+ +

As with any set of concepts there are words that take on special meanings. +This document attempts to clearly describe all of these terms, however as the concepts are inter-related it is sometimes necessary to use a term prior to its formal introduction.

+ + + +

System

+ +

At the most basic level Microkit provides the platform for running a system on a specific board. +As a user of Microkit you use the platform to create a software system that implements your use case. +The system is described in a declarative configuration file, and the Microkit tool takes this system description as an input and produces an appropriate system image that can be loaded on the target board.

+ +

The key elements that make up a system are protection domains, memory regions and channels.

+ +

Protection Domains

+ +

A protection domain (PD) is the fundamental runtime abstraction in Microkit. +It is analogous, but very different in detail, to a process on a UNIX system.

+ +

A PD provides a thread of control that executes within a fixed virtual address space. +The isolation provided by the virtual address space is enforced by the underlying hardware MMU.

+ +

The virtual address space for a PD has mappings for the PD’s program image along with any memory regions that the PD can access. +The program image is an ELF file containing the code and data which implements the isolated component.

+ +

Microkit supports a maximum of 63 protection domains.

+ +

Entry points

+ +

Although a protection domain is somewhat analogous to a process, it has a considerably different program structure and life-cycle. +A process on a typical operating system will have a main function which is invoked by the system when the process is created. +When the main function returns the process is destroyed.

+ +

By comparison a protection domain has up to four entry points:

+ +
    +
  • init, notified which are required.
    • +
  • protected which is optional.
    • +
  • fault which is required if the PD has children.
    • +
+ +

When a Microkit system is booted, all PDs in the system execute the init entry point.

+ +

A PD will not execute any other entry point until init has finished.

+ +

If a PD is currently executing an entry point, it will not execute any other entry point +until the current entry point has finished.

+ +

The notified entry point will be invoked whenever the protection domain receives a notification on a channel. +The protected entry point is invoked when a PD’s protected procedure is called by another PD. +A PD does not have to provide a protected procedure, therefore the protected entry point is optional.

+ +

The fault entry point is invoked when a PD that is a child of another PD causes a fault. +A PD does not have to have child PDs, therefore the fault entry point is only required for a parent PD.

+ +

These entry points are described in more detail in subsequent sections.

+ +

Note: The processing of init entry points is not synchronised across protection domains. +Specifically, it is possible for a high priority PD’s notified or protected entry point to be called prior to the completion of a low priority PD’s init entry point.

+ +

The overall computational model for a Microkit system is a set of isolated components reacting to incoming events.

+ +

Scheduling

+ +

The PD has a number of scheduling attributes that are configured in the system description:

+ +
    +
  • priority (0 – 254)
    • +
  • period (microseconds)
    • +
  • budget (microseconds)
    • +
  • passive (boolean)
    • +
+ +

The budget and period bound the fraction of CPU time that a PD can consume. +Specifically, the budget specifies the amount of time for which the PD is allowed to execute. +Once the PD has consumed its budget, it is no longer runnable until the budget is replenished; replenishment happens once every period and resets the budget to its initial value. +This means that the maximum fraction of CPU time the PD can consume is $\frac{budget}{period}$.

+ +

The budget cannot be larger than the period. +A budget that equals the period (aka. a “full” budget) behaves like a traditional time slice: After executing for a full period, the PD is preempted and put at the end of the scheduling queue of its priority. In other words, PDs with equal priorities and full budgets are scheduled round-robin with a time slice defined by the period.

+ +

The priority determines which of the runnable PDs to schedule. A PD is runnable if one of its entry points has been invoked and it has budget remaining in the current period. +Runnable PDs of the same priority are scheduled in a round-robin manner.

+ +

Passive determines whether the PD is passive. A passive PD will have its scheduling context revoked after initialisation and then bound instead to the PD’s notification object. This means the PD will be scheduled on receiving a notification, whereby it will run on the notification’s scheduling context. When the PD receives a protected procedure by another PD or a fault caused by a child PD, the passive PD will run on the scheduling context of the callee.

+ +

Virtual Machines

+ +

A virtual machine (VM) is a runtime abstraction for running guest operating systems in Microkit. It is similar +to a protection domain in that it provides a thread of control that executes within an isolated virtual address space.

+ +

The main difference between a VM and a PD is that VMs have a higher privilege level such that they may function as a +guest operations and have their own user-space programs at a separate exception level.

+ +

The virtual machine is always a child of a PD. Exceptions caused by the virtual machine are delivered to the parent PD +through the fault entry point.

+ +

Each virtual machine has a number of ‘virtual CPU’s associated with it. Each virtual CPU (vCPU) that belongs to a +virtual machine has its own thread of execution. A vCPU also has an identifier which is used to know which vCPU caused +the invocation of the fault entry point.

+ +

The parent PD is responsible for starting and managing the virtual machine. Microkit provides the abstractions in +order to manage the virtual machine through seL4 but there is typically a non-trivial amount +of supporting code/infrastructure to properly start and manage a VM.

+ +

To keep the (potentially untrusted) virtual machine isolated from the rest of the system, Microkit enforces that a +protection domain can only ever manage a single virtual machine.

+ +

Memory Regions

+ +

A memory region is a contiguous range of physical memory. +A memory region may have a fixed physical address. +For memory regions without a fixed physical address, the physical address is allocated as part of the build process. +Typically, memory regions with a fixed physical address represent memory-mapped device registers.

+ +

Memory regions that are within main memory are zero-initialised.

+ +

The size of a memory region must be a multiple of a supported page size. +The supported page sizes are architecture dependent. +For example, on AArch64 architectures, Microkit support 4KiB and 2MiB pages. +The page size for a memory region may be specified explicitly in the system description. +If page size is not specified, the largest supported page size is used.

+ +

Note: The page size also restricts the alignment of the memory region’s physical address. +A fixed physical address must be a multiple of the specified page size.

+ +

A memory region can be mapped into one or more protection domains. +The mapping has a number of attributes, which include:

+ +
    +
  • the virtual address at which the region is mapped in the PD
    • +
  • caching attributes (mostly relevant for device memory)
    • +
  • permissions (read, write and execute)
    • +
+ +

Note: When a memory region is mapped into multiple protection +domains, the attributes used for different mappings may vary.

+ +

Channels

+ +

A channel enables two protection domains to interact using protected procedures or notifications. +Each connects exactly two PDs; there are no multi-party channels.

+ +

When a channel is created between two PDs, a channel identifier is configured for each PD. +The channel identifier is used by the PD to reference the channel. +Each PD can refer to the channel with a different identifier. +For example if PDs A and B are connected by a channel, A may refer to the channel using an identifier of 37 while B may use 42 to refer to the same channel.

+ +

Note: There is no way for a PD to directly refer to another PD in the system. +PDs can only refer to other PDs indirectly if there is a channel between them. +In this case, the channel identifier is effectively a proxy identifier for the other PD. +So, to extend the prior example, A can indirectly refer to B via the channel identifier 37. +Similarly, B can refer to A via the channel identifier 42.

+ +

The system supports a maximum of 63 channels and interrupts per protection domain.

+ +

Protected procedures

+ +

A protection domain may provide a protected procedure (PP) which can be invoked from another protection domain. +Up to 64 words of data may be passed as arguments when calling a protected procedure. +The protected procedure return value may also be up to 64 words.

+ +

When a protection domain calls a protected procedure, the procedure executes within the context of the providing protection domain.

+ +

A protected call is only possible if the callee has strictly higher priority than the caller. +Transitive calls are possible, and as such a PD may call a protected procedure in another PD from a protected entry point. +However the overall call graph between PDs must form a directed, acyclic graph. +It follows that a PD can not call itself, even indirectly. +For example, A calls B calls C is valid (subject to the priority constraint), while A calls B calls A is not valid.

+ +

When a protection domain is called, the protected entry point is invoked. +The control returns to the caller when the protected entry point returns.

+ +

The caller is blocked until the callee returns. +Protected procedures must execute in bounded time. +It is intended that a future version of Microkit will enforce this condition through static analysis. +In the present version the caller must trust the callee to conform.

+ +

In general, PPs are provided by services for use by clients that trust the protection domain to provide that service.

+ +

To call a PP, a PD calls microkit_ppcall passing the channel identifier and a message structure. +A message structure is returned from this function.

+ +

When a PD’s protected procedure is invoked, the protected entry point is invoked with the channel identifier and message structure passed as arguments. +The protected entry point must return a message structure.

+ +

Notifications

+ +

A notification is a (binary) semaphore-like synchronisation mechanism. +For example, a PD can notify another PD to indicate availability of data in a shared memory region if they share a channel.

+ +

To notify another PD, a PD calls microkit_notify, passing the channel identifier. +When a PD receives a notification, the notified entry point is invoked with the appropriate channel identifier passed as an argument.

+ +

Unlike protected procedures, notifications can be sent in either direction on a channel regardless of priority.

+ +

Note: Notifications provide a mechanism for synchronisation between PDs, however this is not a blocking operation. +If a PD notifies another PD, that PD will become scheduled to run (if it is not already), but the current PD does not block. +Of course, if the notified PD has a higher priority than the current PD, then the current PD will be preempted (but not blocked) by the other PD.

+ +

Depending on the scheduling, one PD could notify another multiple times without it being scheduled, resulting +in a single execution of the notified entry point. For example, if PD A notifies PD B three times on the +same channel without PD B ever executing, once PD B is scheduled it would only see one notification and hence +only enter notified once for that channel.

+ +

Interrupts

+ +

Hardware interrupts can be used to notify a protection domain. +The system description specifies if a protection domain receives notifications for any hardware interrupt sources. +Each hardware interrupt is assigned a channel identifier. +In this way the protection domain can distinguish the hardware interrupt from other notifications. +A specific hardware interrupt can only be associated with at most one protection domain. It should be noted that once a +hardware interrupt has been received, it will not be received again until microkit_irq_ack is called. The seL4 kernel +will mask the hardware interrupt until it has been acknowledged.

+ +

Microkit does not provides timers, nor any sleep API. +After initialisation, activity in the system is initiated by an interrupt causing a notified entry point to be invoked. +That notified function may in turn notify or call other protection domains that cause other system activity, but eventually all activity indirectly initiated from that interrupt will complete, at which point the system is inactive again until another interrupt occurs.

+ +

Faults

+ +

Faults such as an invalid memory access or illegal instruction are delivered to the seL4 kernel which then forwards them to +a designated ‘fault handler’. By default, all faults caused by protection domains go to the system fault handler which +simply prints out details about the fault in a debug configuration.

+ +

When a protection domain is a child of another protection domain, the designated fault handler for the child is the parent +protection domain. The same applies for a virtual machine.

+ +

This means that whenever a fault is caused by a child, it will be delivered to the parent PD instead of the system fault +handler via the fault entry point. It is then up to the parent to decide how the fault is handled.

+ +

The default system fault handler (aka the monitor) has the highest priority and so will +execute and handle faults immediately after they occur. For child PDs that have their faults +delivered to another PD, the fault being handled depends on when the parent PD is scheduled.

+ +

I/O Ports

+ +

I/O ports are x86 mechanisms to access certain physical devices (e.g. PC serial ports or PCI) using the in and out CPU instructions. The system description specifies if a protection domain have access to certain port address ranges. These accesses will be executed by seL4 and the result returned to protection domains.

+ +

SDK

+ +

Microkit is distributed as a software development kit (SDK).

+ +

The SDK includes support for one or more boards. +Three configurations are supported for each board: debug, release, and benchmark. +See the Configurations section for more details.

+ +

The SDK contains:

+ +
    +
  • Microkit user manual (this document)
    • +
  • Microkit tool
    • +
+ +

Additionally, for each supported board configuration the following are provided:

+ +
    +
  • libmicrokit.a
    • +
  • initialiser.elf
    • +
  • monitor.elf
    • +
  • seL4 kernel image +
      +
    • On ARM/RISC-V: sel4.elf
      • +
    • On x86-64: sel4_64.elf (64-bit) and sel4_32.elf (32-bit)
      • +
    +
    • +
+ +

On ARM and RISC-V, an additional loader.elf is provided, which acts as the system’s bootloader.

+ +

On x86-64, 32-bit/64-bit variants of the kernel are provided as even on 64-bit platforms (e.g QEMU), +a 32-bit kernel is required.

+ +

There are also examples provided in the example directory.

+ +

The Microkit SDK does not provide, nor require, any specific build system. +The user is free to build their system using whatever build system is deemed most appropriate for their specific use case.

+ +

The Microkit tool should be invoked by the system build process to transform a system description (and any referenced program images) into an image file which can be loaded by the target board’s bootloader.

+ +

The ELF files provided as program images should be standard ELF files and have been linked against the provided libmicrokit.a.

+ +

Configurations

+ +

Debug

+ +

The debug configuration includes a debug build of the seL4 kernel to allow console debug output using the kernel’s UART driver.

+ +

Release

+ +

The release configuration is a release build of the seL4 kernel and is intended for production builds. The loader, monitor, initialiser and +kernel do not perform any serial output.

+ +
Proofs
+ +

The formal verification of seL4 applies to a specific set of seL4 configuration only. This means that making a release build +of a Microkit system does not imply that the seL4 kernel being used is verified.

+ +

Currently Microkit always uses the MCS configuration of seL4 which is still undergoing verification, scheduled to complete +for RISC-V in 2026 and AArch64 in 2027. The design proofs for MCS are done but the work to show that the kernel code conforms +to the design is still undergoing.

+ +

You can find more information about what verified seL4 configurations do exist +here

+ +

A roadmap for upcoming verification is available here.

+ +

Benchmark

+ +

The benchmark configuration uses a build of the seL4 kernel that exports the hardware’s performance monitoring unit (PMU) to PDs. +The kernel also tracks information about CPU utilisation. This benchmark configuration exists due a limitation of the seL4 kernel +and is intended to be removed once RFC-16 is implemented.

+ +

Multi-core (SMP) configurations

+ +

The configurations listed above default to using the uni-core configuration of seL4/Microkit. +Currently we do not want to default to using the multi-core configuration of the kernel so +separate configurations exist for users wanting to use multi-core.

+ +

The multi-core configurations are the same as the configurations listed above, except with the +smp- prefix. For example, smp-debug for the multi-core variant of debug.

+ +

On ARM/RISC-V, the number of cores available defaults to the number of cores the target board has.

+ +

On x86-64, the number of cores available depends on how many are detected at run-time. Right now +there is a fixed upper limit, see the board-specific documentation for details.

+ +

System Requirements

+ +

The Microkit tool requires Linux (x86-64 or AArch64), macOS (x86-64 or AArch64).

+ +

On Linux, the Microkit tool is statically linked and should run on any distribution.

+ +

On macOS, the Microkit tool should run on macOS 10.12 (Sierra) or higher.

+ +

The Microkit tool does not depend on any additional system binaries.

+ +

Microkit Tool

+ +

The Microkit tool is available in bin/microkit.

+ +

The Microkit tool takes as input a system description. +The format of the system description is described in a subsequent chapter.

+ +

Usage:

+ +
microkit [-h] [-o OUTPUT] [-r REPORT] [--capdl-json CAPDL_SPEC] [--image-type {binary,elf,uimage}]
+          --board [BOARD] --config CONFIG [--search-path [SEARCH_PATH ...]] system
+
+ +

The path to the system description file, board to build the system for, and configuration to build for must be provided.

+ +

The search paths provided tell the tool where to find any program images specified in the system description file.

+ +

In the case of errors, a diagnostic message shall be output to stderr and a non-zero code returned.

+ +

In the case of success, a loadable image file and a report shall be produced. The +type of image is specified by the --image-type argument. +The output paths for these can be specified by -o and -r respectively. +The default output paths are loader.img and report.txt.

+ +

The report is a plain text file describing important information about the system. +The report can be useful when debugging potential system problems. +This report does not have a fixed format and may change between versions. +It is not intended to be machine readable.

+ +

Image format

+ +

ARM

+ +

On ARM, the Microkit tool will produce either a raw binary that is intended to be loaded and jumped or +an ELF. By default, the tool will produce a raw binary unless the format is specified using the --image-type argument.

+ +

For the raw binary format, there is a specified entry point of the image that is documented in the board-specific +instructions in this manual, under Board Support Packages. If the image is not loaded at this address +it should still work by relocating itself upon boot.

+ +

This image is expected to be loaded via a previous bootloader, typically U-Boot using the go command for +the binary image format and the bootelf command for ELFs. Note when using bootelf you may need to set +the autostart environment variable with setenv autostart yes to have the image executed after bootelf.

+ +

See the board-specific instructions for more details.

+ +

RISC-V

+ +

On RISC-V, the Microkit tool can produce either a raw binary that is intended to be loaded and jumped, +a uImage with the Linux header or an ELF. Typically the tool will produce a uImage by default, for +board-specific details see Board Support Packages.

+ +

For the raw binary format, there is a specified entry point of the image that is documented in the board-specific +instructions in this manual, under Board Support Packages. If the image is not loaded at this address +it should still work by relocating itself upon boot.

+ +

For the uImage format. You may load this image anywhere in memory along with your platform’s DTB, then use +the bootm command in U-Boot. It will copy the loader to the correct location in memory and jump to it.

+ +

x86-64

+ +

On x86-64, the image format is always ELF, it is expected to be loaded as a Multiboot boot module.

+ +

See x86-64 generic support for more details.

+ +

Language Support

+ +

There are native APIs for C/C++ and Rust.

+ +

libmicrokit exports a C API and so can be used in any language +that supports C FFI.

+ +

For Rust, native bindings exist but are not included in the SDK itself. They are +available at rust-sel4.

+ +

libmicrokit

+ +

All program images should link against libmicrokit.a.

+ +

The library provides the C runtime for the protection domain, along with interfaces for the Microkit APIs.

+ +

The component must provide the following functions:

+ +
void init(void);
+void notified(microkit_channel ch);
+
+ +

If the protection domain provides a protected procedure it must also implement:

+ +
microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo);
+
+ +

If the protection domain has children it must also implement:

+ +
seL4_Bool fault(microkit_child child, microkit_msginfo msginfo,
+                microkit_msginfo *reply_msginfo);
+
+ +

libmicrokit provides the following functions:

+ +
microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo);
+void microkit_notify(microkit_channel ch);
+microkit_msginfo microkit_msginfo_new(seL4_Word label, seL4_Uint16 count);
+seL4_Word microkit_msginfo_get_label(microkit_msginfo msginfo);
+seL4_Word microkit_msginfo_get_count(microkit_msginfo msginfo);
+void microkit_irq_ack(microkit_channel ch);
+void microkit_deferred_notify(microkit_channel ch);
+void microkit_deferred_irq_ack(microkit_channel ch);
+void microkit_pd_restart(microkit_child pd, seL4_Word entry_point);
+void microkit_pd_stop(microkit_child pd);
+void microkit_mr_set(seL4_Uint8 mr, seL4_Word value);
+seL4_Word microkit_mr_get(seL4_Uint8 mr);
+void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point);
+void microkit_vcpu_stop(microkit_child vcpu);
+void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq,
+                                  seL4_Uint8 priority, seL4_Uint8 group,
+                                  seL4_Uint8 index);
+void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq);
+seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg);
+void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value);
+void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response);
+void microkit_x86_ioport_write_8(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data);
+void microkit_x86_ioport_write_16(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data);
+void microkit_x86_ioport_write_32(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data);
+seL4_Uint8 microkit_x86_ioport_read_8(microkit_ioport ioport_id, seL4_Word port_addr);
+seL4_Uint16 microkit_x86_ioport_read_16(microkit_ioport ioport_id, seL4_Word port_addr);
+seL4_Uint32 microkit_x86_ioport_read_32(microkit_ioport ioport_id, seL4_Word port_addr);
+seL4_Word microkit_vcpu_x86_read_vmcs(microkit_child vcpu, seL4_Word field);
+void microkit_vcpu_x86_write_vmcs(microkit_child vcpu, seL4_Word field, seL4_Word value);
+seL4_Word microkit_vcpu_x86_read_msr(microkit_child vcpu, seL4_Word field);
+void microkit_vcpu_x86_write_msr(microkit_child vcpu, seL4_Word field, seL4_Word value);
+void microkit_vcpu_x86_enable_ioport(microkit_child vcpu, microkit_ioport ioport_id,
+                                     seL4_Word port_addr, seL4_Word length);
+void microkit_vcpu_x86_disable_ioport(microkit_child vcpu, seL4_Word port_addr, seL4_Word length);
+void microkit_vcpu_x86_write_regs(microkit_child vcpu, seL4_VCPUContext *regs);
+
+ +

void init(void)

+ +

Every PD must expose an init entry point. +This is called by the system at boot time.

+ +

void notified(microkit_channel ch)

+ +

The notified entry point is called by the system when a PD has received a notification on a channel.

+ +

ch identifies the channel which has been notified (and indirectly the PD that performed the notification).

+ +

Note: ch could identify an interrupt.

+ +

Channel identifiers are specified in the system configuration.

+ +

microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo)

+ +

The protected entry point is optional. +This is invoked when another PD calls microkit_ppcall on a channel shared with the PD.

+ +

The ch argument identifies the channel on which the PP was invoked. +Indirectly this identifies the PD performing the call. +Channel identifiers are specified in the system configuration. +Note: The channel argument is passed by the system and is unforgeable.

+ +

The msginfo argument is the argument passed to the PP and is provided by the calling PD. +The contents of the message is up to a pre-arranged protocol between the PDs. +The message contents are opaque to the system. +Note: The message is copied from the caller.

+ +

The returned microkit_msginfo is the return value of the protected procedure. +As with arguments, this is copied to the caller.

+ +

seL4_Bool fault(microkit_child child, microkit_msginfo msginfo, microkit_msginfo *reply_msginfo)

+ +

The fault entry point being invoked depends on whether the given PD has children. +It is invoked when a child PD or VM causes a fault.

+ +

The child argument identifies the child that caused the fault.

+ +

The msginfo argument is given by the seL4 kernel when a fault occurs and contains information +as to what fault occurred.

+ +

The reply_msginfo argument is given by libmicrokit and can be used to reply to the fault.

+ +

The returned seL4_Bool is whether or not to reply to the fault with the message reply_msginfo. +Returning seL4_True will reply to the fault. Returning seL4_False will not reply to the fault.

+ +

You can use microkit_msginfo_get_label on msginfo to deduce what kind of fault happened +(for example, whether it was a user exception or a virtual memory fault).

+ +

Whether or not you reply to the fault depends on the type of fault that has occurred and how you want +to handle it.

+ +

To find the full list of possible faults that could occur and details regarding to replying to a particular +kind of fault, please see the ‘Faults’ section of the +seL4 reference manual.

+ +

microkit_msginfo microkit_ppcall(microkit_channel ch, microkit_msginfo msginfo)

+ +

Performs a call to a protected procedure in a different PD. +The ch argument identifies the protected procedure to be called. +msginfo is passed as argument to the protected procedure. +Channel identifiers are specified in the system configuration.

+ +

The protected procedure’s return data is returned in the microkit_msginfo.

+ +

void microkit_notify(microkit_channel ch)

+ +

Notify the channel ch. +Channel identifiers are specified in the system configuration.

+ +

void microkit_irq_ack(microkit_channel ch)

+ +

Acknowledge the interrupt identified by the specified channel.

+ +

void microkit_deferred_notify(microkit_channel ch)

+ +

The same as microkit_notify but will instead not actually perform the notify until +the entry point where microkit_deferred_notify was called returns.

+ +

It is important to note that only a single ‘deferred’ API call can be made within the +same entry point.

+ +

The purpose of this API is for performance critical code as this API saves +a kernel system call.

+ +

void microkit_deferred_irq_ack(microkit_channel ch)

+ +

The same as microkit_irq_ack but will instead not actually perform the IRQ acknowledge +until the entry point where microkit_deferred_irq_ack was called returns.

+ +

It is important to note that only a single ‘deferred’ API call can be made within the +same entry point.

+ +

The purpose of this API is for performance critical code as this API saves +a kernel system call.

+ +

void microkit_pd_restart(microkit_child pd, uintptr_t entry_point)

+ +

Restart the execution of a child protection domain with ID pd at the given entry_point. +This will set the program counter of the child protection domain to entry_point.

+ +

void microkit_pd_stop(microkit_child pd)

+ +

Stop the execution of the child protection domain with ID pd.

+ +

microkit_msginfo microkit_msginfo_new(uint64_t label, uint16_t count)

+ +

Creates a new message structure.

+ +

The message can be passed to microkit_ppcall or returned from protected.

+ +

uint64_t microkit_msginfo_get_label(microkit_msginfo msginfo)

+ +

Returns the label from a message.

+ +

uint64_t microkit_msginfo_get_count(microkit_msginfo msginfo)

+ +

Returns the count of message registers in the message.

+ +

uint64_t microkit_mr_get(uint8_t mr)

+ +

Get a message register.

+ +

void microkit_mr_set(uint8_t mr, uint64_t value)

+ +

Set a message register.

+ +

void microkit_vcpu_restart(microkit_child vcpu, seL4_Word entry_point)

+ +

Restart the execution of a VM’s virtual CPU with ID vcpu at the given entry point. +This will set the program counter of the vCPU to entry_point.

+ +

void microkit_vcpu_stop(microkit_child vcpu)

+ +

Stop the execution of the VM’s virtual CPU with ID vcpu.

+ +

`void microkit_vcpu_arm_inject_irq(microkit_child vcpu, seL4_Uint16 irq,

+

seL4_Uint8 priority, seL4_Uint8 group, +seL4_Uint8 index)`

+ +

Inject a virtual ARM interrupt for a virtual CPU vcpu with IRQ number irq. +The priority (0-31) determines what ARM GIC (generic interrupt controller) +priority level the virtual IRQ will be injected as. The group determines whether +the virtual IRQ will be injected into secure world (1) or non-secure world (0). +The index is the index of the virtual GIC list register.

+ +

void microkit_vcpu_arm_ack_vppi(microkit_child vcpu, seL4_Word irq)

+ +

Acknowledge a ARM virtual Private Peripheral Interrupt (PPI) with IRQ number irq +for a VM’s vCPU with ID vcpu.

+ +

seL4_Word microkit_vcpu_arm_read_reg(microkit_child vcpu, seL4_Word reg)

+ +

Read a register for a given virtual CPU with ID vcpu. The reg argument is the index of the +register that is read. The list of registers is defined by the enum seL4_VCPUReg +in the seL4 source code.

+ +

void microkit_vcpu_arm_write_reg(microkit_child vcpu, seL4_Word reg, seL4_Word value)

+ +

Write to a register for a given virtual CPU with ID vcpu. The reg argument is the index of the +register that is written to. The value argument is what the register will be set to. +The list of registers is defined by the enum seL4_VCPUReg in the seL4 source code.

+ +

void microkit_arm_smc_call(seL4_ARM_SMCContext *args, seL4_ARM_SMCContext *response)

+ +

The API takes in arguments for a Secure Monitor Call which will be performed by seL4. Any +response values will be placed into the response structure.

+ +

The seL4_ARM_SMCContext structure contains fields for registers x0 to x7.

+ +

Note that this API is only available when the PD making the call has been configured to +have SMC enabled in the SDF. Note that when the kernel makes the actual SMC, it cannot +pre-empt the Secure Monitor and therefore any kernel WCET properties are no longer guaranteed.

+ +

void microkit_x86_ioport_write_(8|16|32)(microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word data)

+ +

Write an 8, 16, or 32 bits value at port address port_addr to I/O Port with ID ioport_id.

+ +

seL4_Uint(8|16|32) microkit_x86_ioport_read_(8|16|32)(microkit_ioport ioport_id, seL4_Word port_addr)

+ +

Read an 8, 16, or 32 bits value at port address port_addr from I/O Port with ID ioport_id.

+ +

seL4_Word microkit_vcpu_x86_read_vmcs(microkit_child vcpu, seL4_Word field)

+ +

Read a Virtual Machine Control Structure field specified by field for a given virtual CPU +with ID vcpu using the vmread instruction.

+ +

All the VMCS fields are listed in the seL4 source at include/arch/x86/arch/object/vcpu.h.

+ +

The following fields can be read from:

+ +
    +
  • VMX_GUEST_RIP
    • +
  • VMX_GUEST_RSP
    • +
  • VMX_GUEST_ES_SELECTOR
    • +
  • VMX_GUEST_CS_SELECTOR
    • +
  • VMX_GUEST_SS_SELECTOR
    • +
  • VMX_GUEST_DS_SELECTOR
    • +
  • VMX_GUEST_FS_SELECTOR
    • +
  • VMX_GUEST_GS_SELECTOR
    • +
  • VMX_GUEST_LDTR_SELECTOR
    • +
  • VMX_GUEST_TR_SELECTOR
    • +
  • VMX_GUEST_DEBUGCTRL
    • +
  • VMX_GUEST_PAT
    • +
  • VMX_GUEST_EFER
    • +
  • VMX_GUEST_PERF_GLOBAL_CTRL
    • +
  • VMX_GUEST_PDPTE0
    • +
  • VMX_GUEST_PDPTE1
    • +
  • VMX_GUEST_PDPTE2
    • +
  • VMX_GUEST_PDPTE3
    • +
  • VMX_GUEST_ES_LIMIT
    • +
  • VMX_GUEST_CS_LIMIT
    • +
  • VMX_GUEST_SS_LIMIT
    • +
  • VMX_GUEST_DS_LIMIT
    • +
  • VMX_GUEST_FS_LIMIT
    • +
  • VMX_GUEST_GS_LIMIT
    • +
  • VMX_GUEST_LDTR_LIMIT
    • +
  • VMX_GUEST_TR_LIMIT
    • +
  • VMX_GUEST_GDTR_LIMIT
    • +
  • VMX_GUEST_IDTR_LIMIT
    • +
  • VMX_GUEST_ES_ACCESS_RIGHTS
    • +
  • VMX_GUEST_CS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_SS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_DS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_FS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_GS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_LDTR_ACCESS_RIGHTS
    • +
  • VMX_GUEST_TR_ACCESS_RIGHTS
    • +
  • VMX_GUEST_INTERRUPTABILITY
    • +
  • VMX_GUEST_ACTIVITY
    • +
  • VMX_GUEST_SMBASE
    • +
  • VMX_GUEST_SYSENTER_CS
    • +
  • VMX_GUEST_PREEMPTION_TIMER_VALUE
    • +
  • VMX_GUEST_ES_BASE
    • +
  • VMX_GUEST_CS_BASE
    • +
  • VMX_GUEST_SS_BASE
    • +
  • VMX_GUEST_DS_BASE
    • +
  • VMX_GUEST_FS_BASE
    • +
  • VMX_GUEST_GS_BASE
    • +
  • VMX_GUEST_LDTR_BASE
    • +
  • VMX_GUEST_TR_BASE
    • +
  • VMX_GUEST_GDTR_BASE
    • +
  • VMX_GUEST_IDTR_BASE
    • +
  • VMX_GUEST_DR7
    • +
  • VMX_GUEST_RFLAGS
    • +
  • VMX_GUEST_PENDING_DEBUG_EXCEPTIONS
    • +
  • VMX_GUEST_SYSENTER_ESP
    • +
  • VMX_GUEST_SYSENTER_EIP
    • +
  • VMX_CONTROL_CR0_MASK
    • +
  • VMX_CONTROL_CR4_MASK
    • +
  • VMX_CONTROL_CR0_READ_SHADOW
    • +
  • VMX_CONTROL_CR4_READ_SHADOW
    • +
  • VMX_DATA_INSTRUCTION_ERROR
    • +
  • VMX_DATA_EXIT_INTERRUPT_INFO
    • +
  • VMX_DATA_EXIT_INTERRUPT_ERROR
    • +
  • VMX_DATA_IDT_VECTOR_INFO
    • +
  • VMX_DATA_IDT_VECTOR_ERROR
    • +
  • VMX_DATA_EXIT_INSTRUCTION_LENGTH
    • +
  • VMX_DATA_EXIT_INSTRUCTION_INFO
    • +
  • VMX_DATA_GUEST_PHYSICAL
    • +
  • VMX_DATA_IO_RCX
    • +
  • VMX_DATA_IO_RSI
    • +
  • VMX_DATA_IO_RDI
    • +
  • VMX_DATA_IO_RIP
    • +
  • VMX_DATA_GUEST_LINEAR_ADDRESS
    • +
  • VMX_CONTROL_ENTRY_INTERRUPTION_INFO
    • +
  • VMX_CONTROL_PIN_EXECUTION_CONTROLS
    • +
  • VMX_CONTROL_PRIMARY_PROCESSOR_CONTROLS
    • +
  • VMX_CONTROL_EXCEPTION_BITMAP
    • +
  • VMX_CONTROL_EXIT_CONTROLS
    • +
  • VMX_GUEST_CR0
    • +
  • VMX_GUEST_CR3
    • +
  • VMX_GUEST_CR4
    • +
+ +

void microkit_vcpu_x86_write_vmcs(microkit_child vcpu, seL4_Word field, seL4_Word value)

+ +

Write a Virtual Machine Control Structure field specified by field for a given virtual CPU +with ID vcpu using the vmwrite instruction. The value may be modified to ensure any bits +that are fixed in the hardware are correct, and that any features required for kernel correctness +are not disabled.

+ +

All the VMCS fields are listed in the seL4 source at include/arch/x86/arch/object/vcpu.h.

+ +

The following fields can be written to:

+ +
    +
  • VMX_GUEST_RIP
    • +
  • VMX_GUEST_RSP
    • +
  • VMX_GUEST_ES_SELECTOR
    • +
  • VMX_GUEST_CS_SELECTOR
    • +
  • VMX_GUEST_SS_SELECTOR
    • +
  • VMX_GUEST_DS_SELECTOR
    • +
  • VMX_GUEST_FS_SELECTOR
    • +
  • VMX_GUEST_GS_SELECTOR
    • +
  • VMX_GUEST_LDTR_SELECTOR
    • +
  • VMX_GUEST_TR_SELECTOR
    • +
  • VMX_GUEST_DEBUGCTRL
    • +
  • VMX_GUEST_PAT
    • +
  • VMX_GUEST_EFER
    • +
  • VMX_GUEST_PERF_GLOBAL_CTRL
    • +
  • VMX_GUEST_PDPTE0
    • +
  • VMX_GUEST_PDPTE1
    • +
  • VMX_GUEST_PDPTE2
    • +
  • VMX_GUEST_PDPTE3
    • +
  • VMX_GUEST_ES_LIMIT
    • +
  • VMX_GUEST_CS_LIMIT
    • +
  • VMX_GUEST_SS_LIMIT
    • +
  • VMX_GUEST_DS_LIMIT
    • +
  • VMX_GUEST_FS_LIMIT
    • +
  • VMX_GUEST_GS_LIMIT
    • +
  • VMX_GUEST_LDTR_LIMIT
    • +
  • VMX_GUEST_TR_LIMIT
    • +
  • VMX_GUEST_GDTR_LIMIT
    • +
  • VMX_GUEST_IDTR_LIMIT
    • +
  • VMX_GUEST_ES_ACCESS_RIGHTS
    • +
  • VMX_GUEST_CS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_SS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_DS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_FS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_GS_ACCESS_RIGHTS
    • +
  • VMX_GUEST_LDTR_ACCESS_RIGHTS
    • +
  • VMX_GUEST_TR_ACCESS_RIGHTS
    • +
  • VMX_GUEST_INTERRUPTABILITY
    • +
  • VMX_GUEST_ACTIVITY
    • +
  • VMX_GUEST_SMBASE
    • +
  • VMX_GUEST_SYSENTER_CS
    • +
  • VMX_GUEST_PREEMPTION_TIMER_VALUE
    • +
  • VMX_GUEST_ES_BASE
    • +
  • VMX_GUEST_CS_BASE
    • +
  • VMX_GUEST_SS_BASE
    • +
  • VMX_GUEST_DS_BASE
    • +
  • VMX_GUEST_FS_BASE
    • +
  • VMX_GUEST_GS_BASE
    • +
  • VMX_GUEST_LDTR_BASE
    • +
  • VMX_GUEST_TR_BASE
    • +
  • VMX_GUEST_GDTR_BASE
    • +
  • VMX_GUEST_IDTR_BASE
    • +
  • VMX_GUEST_DR7
    • +
  • VMX_GUEST_RFLAGS
    • +
  • VMX_GUEST_PENDING_DEBUG_EXCEPTIONS
    • +
  • VMX_GUEST_SYSENTER_ESP
    • +
  • VMX_GUEST_SYSENTER_EIP
    • +
  • VMX_CONTROL_CR0_MASK
    • +
  • VMX_CONTROL_CR4_MASK
    • +
  • VMX_CONTROL_CR0_READ_SHADOW
    • +
  • VMX_CONTROL_CR4_READ_SHADOW
    • +
  • VMX_CONTROL_EXCEPTION_BITMAP
    • +
  • VMX_CONTROL_ENTRY_INTERRUPTION_INFO
    • +
  • VMX_CONTROL_ENTRY_EXCEPTION_ERROR_CODE
    • +
  • VMX_CONTROL_PIN_EXECUTION_CONTROLS
    • +
  • VMX_CONTROL_PRIMARY_PROCESSOR_CONTROLS
    • +
  • VMX_CONTROL_SECONDARY_PROCESSOR_CONTROLS
    • +
  • VMX_CONTROL_EXIT_CONTROLS
    • +
  • VMX_GUEST_CR3
    • +
  • VMX_GUEST_CR0
    • +
  • VMX_GUEST_CR4
    • +
+ +

seL4_Word microkit_vcpu_x86_read_msr(microkit_child vcpu, seL4_Word field)

+ +

Read a 64-bit Model Specific Register of a given virtual CPU with ID vcpu specified by +field from hardware using the rdmsr instruction. The following registers can be written to:

+ +
    +
  • IA32_LSTAR_MSR
    • +
  • IA32_STAR_MSR
    • +
  • IA32_CSTAR_MSR
    • +
  • IA32_FMASK_MSR
    • +
+ +

void microkit_vcpu_x86_write_msr(microkit_child vcpu, seL4_Word field, seL4_Word value)

+ +

Write a 64-bit Model Specific Register of a given virtual CPU with ID vcpu specified by +field to hardware using the wrmsr instruction. The following registers can be read from:

+ +
    +
  • IA32_LSTAR_MSR
    • +
  • IA32_STAR_MSR
    • +
  • IA32_CSTAR_MSR
    • +
  • IA32_FMASK_MSR
    • +
+ +

void microkit_vcpu_x86_enable_ioport(microkit_child vcpu, microkit_ioport ioport_id, seL4_Word port_addr, seL4_Word length)

+ +

Enable I/O port range [port_addr..port_addr + length) of I/O Port with ID ioport_id +in the execution environment of a given virtual CPU with ID vcpu.

+ +

void microkit_vcpu_x86_disable_ioport(microkit_child vcpu, seL4_Word port_addr, seL4_Word length)

+ +

Disable I/O port range [port_addr..port_addr + length) in the execution environment of a given +virtual CPU with ID vcpu.

+ +

void microkit_vcpu_x86_write_regs(microkit_child vcpu, seL4_VCPUContext *regs)

+ +

Write the registers of a given virtual CPU with ID vcpu. The regs argument is the pointer to +the struct of registers seL4_VCPUContext that are written from.

+ +

System Description File

+ +

This section describes the format of the System Description File (SDF).

+ +

The system description file is an XML file that is provided as input to the +microkit tool.

+ +

The root element of the XML file is system.

+ +

Within the system root element the following child elements are supported:

+ +
    +
  • protection_domain
    • +
  • memory_region
    • +
  • channel
    • +
+ +

protection_domain

+ +

The protection_domain element describes a protection domain.

+ +

It supports the following attributes:

+ +
    +
  • name: A unique name for the protection domain
    • +
  • priority: The priority of the protection domain (integer 0 to 254).
    • +
  • budget: (optional) The PD’s budget in microseconds; defaults to 1,000.
    • +
  • period: (optional) The PD’s period in microseconds; must not be smaller than the budget; defaults to the budget.
    • +
  • passive: (optional) Indicates that the protection domain will be passive and thus have its scheduling context removed after initialisation; defaults to false.
    • +
  • stack_size: (optional) Number of bytes that will be used for the PD’s stack. +Must be be between 4KiB and 16MiB and be 4K page-aligned. Defaults to 8KiB.
    • +
  • cpu: (optional) set the physical CPU core this PD will run on. Defaults to zero.
    • +
  • smc: (optional, only on ARM) Allow the PD to give an SMC call for the kernel to perform.. Defaults to false.
    • +
+ +

Additionally, it supports the following child elements:

+ +
    +
  • program_image: (exactly one) Describes the program image for the protection domain.
    • +
  • map: (zero or more) Describes mapping of memory regions into the protection domain.
    • +
  • irq: (zero or more) Describes hardware interrupt associations.
    • +
  • setvar: (zero or more) Describes variable rewriting.
    • +
  • protection_domain: (zero or more) Describes a child protection domain.
    • +
  • virtual_machine: (zero or one) Describes a child virtual machine.
    • +
+ +

The program_image element has a single path attribute describing the path to an ELF file.

+ +

The map element has the following attributes:

+ +
    +
  • mr: Identifies the memory region to map.
    • +
  • vaddr: Identifies the virtual address at which to map the memory region.
    • +
  • perms: Identifies the permissions with which to map the memory region. Can be a combination of r (read), w (write), and x (eXecute), with the exception of a write-only mapping (just w).
    • +
  • cached: (optional) Determines if mapped with caching enabled or disabled. Defaults to true.
    • +
  • setvar_vaddr: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the virtual address of the memory region.
    • +
  • setvar_size: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the size of the memory region.
    • +
+ +

The irq element has the following attributes on ARM and RISC-V:

+ +
    +
  • irq: The hardware interrupt number.
    • +
  • id: The channel identifier. Must be at least 0 and less than 63.
    • +
  • trigger: (optional) Whether the IRQ is edge triggered (“edge”) or level triggered (“level”). Defaults to “level”.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ.
    • +
+ +

The irq element has the following attributes when registering X86_64 IOAPIC interrupts:

+ +
    +
  • id: The channel identifier. Must be at least 0 and less than 63.
    • +
  • pin: IOAPIC pin that generates the interrupt.
    • +
  • vector: CPU vector to deliver the interrupt to.
    • +
  • ioapic: (optional) Zero based index of the IOAPIC to get the interrupt from. Defaults to 0.
    • +
  • level: (optional) Whether the IRQ is level triggered (1) or edge triggered (0). Defaults to level (1).
    • +
  • polarity: (optional) Whether the line polarity is high (1) or low (0). Defaults to high (1).
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ.
    • +
+ +

The irq element has the following attributes when registering X86_64 MSI interrupts:

+ +
    +
  • id: The channel identifier. Must be at least 0 and less than 63.
    • +
  • pcidev: The PCI device address of the device that will generate the interrupt, in BUS:DEV:FUNC notation (e.g. 01:1f:2).
    • +
  • handle: Value of the handle programmed into the data portion of the MSI.
    • +
  • vector: CPU vector to deliver the interrupt to.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier of the IRQ.
    • +
+ +

The ioport element has the following attributes:

+ +
    +
  • id: The I/O port identifier. Must be at least 0 and less than 63.
    • +
  • addr: The base address of the I/O port.
    • +
  • size: The size in bytes of the I/O port region.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the I/O port identifier.
    • +
  • setvar_addr: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the base address of the I/O port.
    • +
+ +

The setvar element has the following attributes:

+ +
    +
  • symbol: Name of a symbol in the ELF file.
    • +
  • region_paddr: Name of an MR. The symbol’s value shall be updated to this MR’s physical address. + Note that on x86-64 platforms this MR must have a specified physical address. + This restriction is due to x86-64 physical memory layout not being known at build-time.
    • +
+ +

The protection_domain element has the same attributes as any other protection domain as well as:

+ +
    +
  • id: The ID of the child for the parent to refer to.
    • +
  • setvar_id: (optional) Specifies a symbol in the parent program image. This symbol will be rewritten with the ID of the child.
    • +
+ +

The virtual_machine element has the following attributes:

+ +
    +
  • name: A unique name for the virtual machine
    • +
  • priority: The priority of the virtual machine (integer 0 to 254).
    • +
  • budget: (optional) The VM’s budget in microseconds; defaults to 1,000.
    • +
  • period: (optional) The VM’s period in microseconds; must not be smaller than the budget; defaults to the budget.
    • +
+ +

Additionally, it supports the following child elements:

+ +
    +
  • vcpu: (one or more) Describes the virtual CPU that will be tied to the virtual machine.
    • +
  • map: (zero or more) Describes mapping of memory regions into the virtual machine.
    • +
+ +

The vcpu element has the following attributes:

+ +
    +
  • id: The vCPU identifier. Must be at least 0 and less than 62.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the vCPU identifier.
    • +
+ +

The map element has the same attributes as the protection domain with the exception of setvar_vaddr.

+ +

memory_region

+ +

The memory_region element describes a memory region.

+ +

It supports the following attributes:

+ +
    +
  • name: A unique name for the memory region
    • +
  • size: Size of the memory region in bytes (must be a multiple of the page size)
    • +
  • page_size: (optional) Size of the pages used in the memory region; must be a supported page size if provided. Defaults to the largest page size for the target architecture that the memory region is aligned to.
    • +
  • phys_addr: (optional) The physical address for the start of the memory region (must be a multiple of the page size).
    • +
+ +

The memory_region element does not support any child elements.

+ +

Page sizes by architecture

+ +

Below are the available page sizes for each architecture that Microkit supports.

+ +
AArch64
+ +
    +
  • 0x1000 (4KiB)
    • +
  • 0x200000 (2MiB)
    • +
+ +
RISC-V 64-bit
+ +
    +
  • 0x1000 (4KiB)
    • +
  • 0x200000 (2MiB)
    • +
+ +
x86-64
+ +
    +
  • 0x1000 (4KiB)
    • +
  • 0x200000 (2MiB)
    • +
+ +

channel

+ +

The channel element has exactly two end children elements for specifying the two PDs associated with the channel.

+ +

The end element has the following attributes:

+ +
    +
  • pd: Name of the protection domain for this end.
    • +
  • id: Channel identifier in the context of the named protection domain. Must be at least 0 and less than 63.
    • +
  • pp: (optional) Indicates that the protection domain for this end can perform a protected procedure call to the other end; defaults to false. + Protected procedure calls can only be to PDs of strictly higher priority.
    • +
  • notify: (optional) Indicates that the protection domain for this end can send a notification to the other end; defaults to true.
    • +
  • setvar_id: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the channel identifier.
    • +
+ +

The id is passed to the PD in the notified and protected entry points. +The id should be passed to the microkit_notify and microkit_ppcall functions.

+ +

Board Support Packages

+ +

This chapter describes the board support packages that are available in the SDK.

+ +

The currently supported platforms are:

+
    +
  • ariane
    • +
  • cheshire
    • +
  • hifive_p550
    • +
  • imx8mm_evk
    • +
  • imx8mp_evk
    • +
  • imx8mp_iotgate
    • +
  • imx8mq_evk
    • +
  • maaxboard
    • +
  • odroidc2
    • +
  • odroidc4
    • +
  • qemu_virt_aarch64
    • +
  • qemu_virt_riscv64
    • +
  • rockpro64
    • +
  • rpi4b_1gb
    • +
  • rpi4b_2gb
    • +
  • rpi4b_4gb
    • +
  • rpi4b_8gb
    • +
  • serengeti
    • +
  • star64
    • +
  • tqma8xqp1gb
    • +
  • ultra96v2
    • +
  • x86_64_generic
    • +
  • x86_64_generic_vtx
    • +
  • zcu102
    • +
+ +

Ariane (CVA6)

+ +

Initial support is available for the CVA6 (formerly Ariane) core design +on the Digilent Genesys2 board. CVA6 is an open-source RISC-V (rv64i) processor.

+ +

Microkit support expects that a compatible RISC-V SBI (e.g OpenSBI) has executed before +jumping to the beginning of the loader image.

+ +

Microkit outputs an ELF for this platform.

+ +

You may compile OpenSBI with the Microkit image as a payload, or alternately install +OpenSBI (with U-Boot optionally) to the SD card.

+ +

If you are booting from U-Boot, use the following command to start the system image:

+ +
=> bootelf ${image_addr}
+
+ +

Where image_addr is the load address of the ELF image.

+ +

Note that the OpenSBI version from the CVA6 SDK at the time of writing has issues when +booting. It is recommended to use the mainline OpenSBI.

+ +

Compulab IOT-GATE-IMX8MPLUS

+ +

The IOT-GATE-IMX8PLUS is based on the NXP i.MX8MP SoC.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x50000000
+
+ +

Cheshire

+ +

Support is available for Cheshire. +It is an SoC design based on the CVA6 core, implementing a 64-bit RISC-V CPU.

+ +

Microkit outputs an ELF for this platform. Several steps are required in order to boot.

+ +

A custom version of OpenSBI is required. It can be found +here. +Build the firmware payload using platform fpga/cheshire.

+ +

To boot a Microkit image, use a GDB prompt via openOCD per seL4 Docs:

+ +
    +
  1. +

    Reset board

    + + 
     (gdb) monitor reset halt
+
    +
    2. +
  2. +

    Set the a0 and a1 registers for OpenSBI

    + + 
     # tell OpenSBI where DTB is (there is none)
+ (gdb) set $a0=0
+ # tell OpenSBI that the default hart is #0
+ (gdb) set $a1=0
+
    +
    3. +
  3. +

    Load OpenSBI’s FW_JUMP payload targeted at 0x90000000, implicitly setting the program counter.

    + + 
     (gdb) load /path/to/opensbi/fw_jump.elf
+
    +
    4. +
  4. +

    Load the Microkit image:

    + + 
    (gdb) restore /path/to/loader.img
+
    +
    5. +
  5. +

    Allow OpenSBI and Microkit to boot:

    + + 
     (gdb) continue
+
    +
    6. +
+ +

i.MX8MM-EVK

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x41000000
+
+ +

i.MX8MP-EVK

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x41000000
+
+ +

i.MX8MQ-EVK

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x41000000
+
+ +

MaaXBoard

+ +

The MaaXBoard is a low-cost ARM SBC based on the NXP i.MX8MQ system-on-chip.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x50000000
+
+ +

Odroid-C2

+ +

The HardKernel Odroid-C2 is an ARM SBC based on the Amlogic Meson S905 system-on-chip. It +should be noted that the Odroid-C2 is no longer available for purchase but its successor, +the Odroid-C4, is readily available at the time of writing.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x20000000
+
+ +

Odroid-C4

+ +

The HardKernel Odroid-C4 is an ARM SBC based on the Amlogic Meson S905X3 system-on-chip.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x20000000
+
+ +

Serengeti

+ +

Serengeti is a fork of the Cheshire platform by Trustworthy Systems. More +information on the hardware platform can be found here.

+ +

Right now Serengeti is a superset of Cheshire by offering more peripherals than Cheshire +has.

+ +

For running on Serengeti, please see Cheshire for instructions.

+ +

SiFive Premier P550

+ +

The SiFive Premier P550 is a development board based on the ESWIN EIC7700X system-on-chip.

+ +

Microkit will produce a uImage. To load the image you will need to use +the bootm command. bootm expects an address of where +the Device Tree Blob (DTB) will be as well as the image.

+ +

If you do not have a DTB for this platform you can obtain it from the seL4 source code with:

+
dtc -I dts -O dtb seL4/tools/dts/hifive-p550.dts > hifive-p550.dtb
+
+ +

Now you can load the images into U-Boot at the appropriate addresses, for example via TFTP:

+ +
=> setenv imgaddr "0xB0000000"
+=> setenv dtbaddr "0xA0000000"
+=> tftpboot ${imgaddr} /path/to/loader.img
+=> tftpboot ${dtbaddr} /path/to/hifive-p550.dtb
+=> bootm ${imgaddr} - ${dtbaddr}
+
+ +

imgaddr and dtbaddr are arbitrarily chosen addresses in main memory for this platform, +you can load the image and DTB at another address.

+ +

QEMU virt (AArch64)

+ +

Support is available for the virtual AArch64 QEMU platform. This is a platform that is not based +on any specific SoC or hardware platform and is intended for simulating systems for +development or testing.

+ +

It should be noted that the platform support is configured with 2GB of main memory and the +Cortex-A53 CPU. seL4 needs to know the memory layout and CPU at build-time so if +you want to change these parameters (e.g to allow more memory), you will have to change the kernel +options for qemu_virt_aarch64 in build_sdk.py.

+ +

You can use the following command to simulate a Microkit system:

+ +
$ qemu-system-aarch64 \
+    -machine virt,virtualization=on \
+    -cpu cortex-a53 \
+    -nographic \
+    -serial mon:stdio \
+    -device loader,file=[SYSTEM IMAGE],addr=0x70000000,cpu-num=0 \
+    -m size=2G
+
+ +

When using the SMP configurations add the -smp 4 argument to the QEMU command.

+ +

You can find more about the QEMU virt platform in the +QEMU documentation.

+ +

QEMU virt (RISC-V 64-bit)

+ +

Support is available for the virtual RISC-V (64-bit) QEMU platform. +This is a platform that is not based on any specific SoC or hardware platform +and is intended for simulating systems for development or testing.

+ +

It should be noted that the platform support is configured with 2GB of main memory. +seL4 has a static amount of memory at build-time, if you want allow for more memory, +you will have to change the kernel options for qemu_virt_riscv64 in build_sdk.py.

+ +

You can use the following command to simulate a Microkit system:

+ +
$ qemu-system-riscv64 \
+    -machine virt \
+    -nographic \
+    -serial mon:stdio \
+    -kernel [SYSTEM IMAGE] \
+    -m size=2G
+
+ +

When using the SMP configurations add the -smp 4 argument to the QEMU command.

+ +

QEMU will start the system image using its packaged version of OpenSBI.

+ +

You can find more about the QEMU virt platform in the +QEMU documentation.

+ +

Raspberry Pi 4B

+ +

Support is available for the Raspberry Pi 4 Model B. There are multiple models of the +Raspberry Pi 4B that have different amounts of RAM, we have support for the 1GB, +2GB, 4GB and 8GB models. Because the amount of RAM must be known statically by +seL4, the Microkit board names differ for each model:

+ +
    +
  • rpi4b_1gb for 1GB of RAM.
    • +
  • rpi4b_2gb for 2GB of RAM.
    • +
  • rpi4b_4gb for 4GB of RAM.
    • +
  • rpi4b_8gb for 8GB of RAM.
    • +
+ +

For initial board setup, please see the instructions on the +seL4 website.

+ +

When getting into the U-Boot console you want to load the Microkit binary image to +address 0x10000000 and then run go 0x10000000.

+ +

For example, if you were to load the image via the MMC you would run the following +U-Boot commands:

+ +
 => fatload mmc 0 0x10000000 <SYSTEM IMAGE>
+ => go 0x10000000
+
+ +

Pine64 ROCKPro64

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x30000000
+
+ +

Pine64 Star64

+ +

Support is available for the Pine64 Star64 platform which is based on the +StarFive JH7110 SoC.

+ +

The platform has a 4GB and 8GB model, we assume the 4GB model.

+ +

The default boot flow of the Star64 is:

+
    +
  1. OpenSBI
    2. +
  2. U-Boot
    3. +
  3. Operating System
    4. +
+ +

This means that the system image that Microkit produces does not need to be explicitly +packaged with an SBI implementation such as OpenSBI.

+ +

Microkit will produce a uImage. To load the image you will need to use +the bootm command. bootm expects an address of where +the Device Tree Blob (DTB) will be as well as the image.

+ +

If you do not have a DTB for this platform you can obtain it from the seL4 source code with:

+
dtc -I dts -O dtb seL4/tools/dts/star64.dts > star64.dtb
+
+ +

Now you can load the images into U-Boot at the appropriate addresses, for example via TFTP:

+ +
=> setenv imgaddr "0xE0000000"
+=> setenv dtbaddr "0xD0000000"
+=> tftpboot ${imgaddr} /path/to/loader.img
+=> tftpboot ${dtbaddr} /path/to/star64.dtb
+=> bootm ${imgaddr} - ${dtbaddr}
+
+ +

imgaddr and dtbaddr are arbitrarily chosen addresses in main memory for this platform, +you can load the image and DTB at another address.

+ +

TQMa8XQP 1GB

+ +

The TQMa8XQP is a system-on-module designed by TQ-Systems GmbH. +The modules incorporates an NXP i.MX8X Quad Plus system-on-chip and 1GiB ECC memory.

+ +

TQ-Systems provide the MBa8Xx carrier board for development purposes. +The instructions provided assume the use of the MBa8Xx carrier board. +If you are using a different carrier board please refer to the appropriate documentation.

+ +

Note: There are different configured of the TQMa8Xx board which include different NXP SoCs +and different memory configurations. Such modules are not supported.

+ +

The MBa8Xx provides access to the TQMa8XQP UART via UART-USB bridge. +To access the UART connect a USB micro cable to port X13. +The UART-USB bridge supports 4 individual UARTs; the UART is connected to the 2nd port.

+ +

By default the SoM will autoboot using U-Boot. +Hit any key during the boot process to stop the autoboot.

+ +

A new board will autoboot to Linux. +You will likely want to disable autoboot:

+ +
=> env set bootdelay -1
+=> env save
+
+ +

The board can be reset by pressing switch S4 (located next to the Ethernet port). +Alternatively, you can use the reset command from the U-Boot prompt.

+ +

During development the most convenient way to boot a Microkit image is via network booting. +U-Boot support booting via the tftp protocol. +To support this you’ll want to configure the network. +U-Boot supports DHCP, however it is often more reliable to explicitly set an IP address. +For example:

+ +
=> env set ipaddr 10.1.1.2
+=> env set netmask 255.255.255.0
+=> env set serverip 10.1.1.1
+=> env save
+
+ +

To use tftp you also need to set the file to load and the memory address to load it to:

+ +
=> env set bootfile loader.img
+=> env set loadaddr 0x80280000
+=> env save
+
+ +

The system image generated by the Microkit tool by default is a raw binary file.

+ +

An example sequence of commands for booting is:

+ +
=> tftpboot
+=> dcache flush
+=> icache flush
+=> go ${loadaddr}
+
+ +

Rather than typing these each time you can create a U-Boot script:

+ +
=> env set microkit 'tftpboot; dcache flush; icache flush; go ${loadaddr}'
+=> env save
+=> run microkit
+
+ +

When debugging is enabled the kernel will use the same UART as U-Boot.

+ +

Ultra96V2

+ +

To run the built image on the board, you have to use properly patched U-Boot - please see the section for ZCU102, for the details.

+ +

You have to load the binary file into memory and run it:

+
ZynqMP> tftpboot 0x40000000 loader.img
+...
+ZynqMP> go 0x40000000
+
+ +

x86-64 generic

+ +

This board supports x86-64 platforms with generic microarchitecture and no virtualisation.

+ +

Up to 16 CPU cores are supported. If your platform’s CPU count exceeds the maximum, the excess CPUs +are ignored by seL4. This limitation is due to a build-time config option of seL4, to increase the +limit, see the board configuration in build_sdk.py.

+ +

On x86-64, Microkit produces 3 ELF images in the output directory:

+ +
    +
  • sel4.elf, seL4 kernel (64-bit ELF)
    • +
  • sel4_32.elf, seL4 kernel (32-bit ELF)
    • +
  • Initial Task image (Multiboot Boot Module ELF)
    • +
+ +

The filename of the initial task image is specified with the -o option, and defaults to loader.img. +Both kernel ELF files are written to the same directory as the initial task image.

+ +

Although this target is for x86-64, your bootloader may require a 32-bit kernel ELF.

+ +

When using QEMU, you must use the 32-bit kernel ELF, for example:

+ +
$ qemu-system-x86_64 \
+	-cpu qemu64,+fsgsbase,+pdpe1gb,+xsaveopt,+xsave \
+	-m "1G" \
+	-display none \
+	-serial mon:stdio \
+	-kernel sel4_32.elf \
+	-initrd loader.img
+
+ +

Unlike Microkit’s qemu_virt_aarch64 and qemu_virt_riscv64, the amount of memory provided to QEMU +is configurable at run time with the -m option, rather than at build time.

+ +

QEMU currently does not support 64-bit kernel ELFs and gives the following error:

+
qemu-system-x86_64: Cannot load x86-64 image, give a 32bit one.
+
+ +

To obtain a bootable ISO image, a Multiboot 2-compliant bootloader must be used. Please refer to your +bootloader’s documentations.

+ +

x86_64 generic

+ +

This board supports x86-64 platforms with generic microarchitecture and virtualisation.

+ +

This configuration assumes Intel VT-x support. Currently, only 1 vCPU is supported per virtual machine +on x86-64.

+ +

The boot process is identical to x86-64 generic.

+ +

This configuration exists because some x86 emulators (for example, QEMU on macOS on Apple Silicon) do +not emulate Intel VT-x.

+ +

If you see the following message at boot:

+
vt-x: not supported
+
+

Consider using the non VT-x configuration: x86-64 generic, or switch to a x86 emulator that +emulates Intel VT-x, such as Bochs.

+ +

ZCU102

+ +

The ZCU102 can run on a physical board or on an appropriate QEMU based emulator.

+ +

Microkit will produce a raw binary file by default, so when using U-Boot run the following command:

+ +
=> go 0x40000000
+
+ +

For simulating the ZCU102 using QEMU, use the following command:

+ +
$ qemu-system-aarch64 \
+   -m size=4G  \
+   -machine xlnx-zcu102,virtualization=on \
+   -nographic \
+   -device loader,file=[SYSTEM IMAGE],addr=0x40000000,cpu-num=0 \
+   -serial mon:stdio
+
+ +

When using the SMP configurations add the -smp 4 argument to the QEMU command.

+ +

It should be noted that when using U-Boot to load and run a Microkit system image, +that there may be additional setup needed.

+ +

For the ZynqMP class of platforms, which the ZCU102 is apart of, U-Boot does not start +the Microkit system Exception Level 2 (EL2) which is necessary for Microkit to start +(this is because seL4 is configured as a hypervisor).

+ +

You can see that when using the go command, U-Boot is +unconditionally always dropping down to EL1.

+ +

To avoid this behaviour, the call to armv8_switch_to_el1 should be replaced with +armv8_switch_to_el2 in this do_go_exec function.

+ +

Adding Platform Support

+ +

The following section is a guide for adding support for a new ARM or RISC-V platform to Microkit.

+ +

Prerequisites

+ +

Before you can start with adding platform support to Microkit, the platform must be supported by the seL4 kernel. +You can find information on how to do so here.

+ +

Getting Microkit Components Working

+ +
build_sdk.py
+ +

The first step to adding Microkit support is to modify the build_sdk.py script in order to build the required +artefacts for the new platform. This involves adding to the SUPPORTED_BOARDS list with the BoardInfo options +containing the platform specific attributes. This should be fairly self-explanatory by looking at the existing +entries with the exception of the loader_link_address.

+ +

The loader_link_address parameter specifies the physical address of where the bootloader for Microkit (which +is responsible for setting up the system before seL4 starts) is going to be loaded. This address needs to +match where in main memory the final system image is actually loaded (e.g where a previous bootloader such as U-Boot +loads the image to). This means that the address is restricted to the platform’s main memory region.

+ +
Loader
+ +
UART
+ +

The other component of Microkit that is platform dependent is the loader itself. The loader will attempt to access +the UART for debug output which requires a basic putc implementation. The UART device used in the loader should be +the same as what is used for the seL4 kernel debug output.

+ +

It should be noted that on RISC-V platforms, the SBI will be used for putc so no porting is necessary.

+ +
CPU configuration
+ +

For supporting multi-core systems on Microkit, the loader needs to know the platform-specific CPU identifiers +that we want to make use of.

+ +

For ARM platforms, a psci_target_cpus array needs to be defined which contains the PSCI target_cpu value for +each CPU. This value can be found by looking at the reg field for each CPU in the Device Tree.

+ +

For RISC-V platforms, a hart_ids array needs to be defined which contains the Hart ID for +each CPU. This value can be found by looking at the reg field for each CPU in the Device Tree. The first value +must be the same as FIRST_HART_ID defined in seL4.

+ +
Next steps
+ +

Once you have patched the loader and the SDK build script, there should be no other changes required to have a working +platform port. It is a good idea at this point to boot a hello world system to confirm the port is working.

+ +

If there are issues with porting the platform, please open an issue on GitHub.

+ +

Contributing Platform Support

+ +

Once you believe that the port works, you can open a pull request with required +changes as well as documentation in the manual about the platform and how to run Microkit images on it.

+ +

Please also update the platforms.yml file, you can find more information at the top of the file.

+ +

Rationale

+ +

This section describes the rationales driving the Microkit design choices.

+ +

Overview

+ +

The seL4 microkernel provides a set of powerful and flexible mechanisms that can be used for building almost arbitrary systems. +While minimising constraints on the nature of system designs and scope of deployments, this flexibility makes it challenging to design the best system for a particular use case, requiring extensive seL4 experience from developers.

+ +

The Microkit addresses this challenge by constraining the +system architecture to one that provides enough features and power for +its target usage class (IoT, cyberphysical and other embedded systems +with a static architecture), enabling a much simpler set of developer-visible abstractions.

+ +

Protection Domains

+ +

PDs are single-threaded to keep the programming model and implementations simple, and because this serves the needs of most present use cases in the target domains. +Extending the model to multithreaded applications (clients) is straightforward and can be done if needed. +Extending to multithreaded services is possible but requires additional infrastructure for which we see no need in the near future.

+ +

Protected Procedure Priorities

+ +

The restriction of only calling to higher priority prevents deadlocks and reflects the notion that the callee operates on behalf of the caller, and it should not be possible to preempt execution of the callee unless the caller could be preempted as well.

+ +

This greatly simplifies reasoning about real-time properties in the system; in particular, it means that PPs can be used to implement resource servers, where shared resources are encapsulated in a component that ensures mutual exclusion, while avoiding unbounded priority inversions through the immediate priority ceiling protocol.

+ +

While it would be possible to achieve the same by allowing PPs between PDs of the same priority, this would be much harder to statically analyse for loop-freedom (and thus deadlock-freedom). +The drawback is that we waste a part of the priority space where a logical entity is split into multiple PDs, eg to separate out a particularly critical component to formally verify it, when the complete entity would be too complex for formal verification. +For the kinds of systems targeted by the Microkit, this reduction of the usable priority space is unlikely to cause problems.

+ +

Protected Procedure Argument Size

+ +

The limitation on the size of by-value arguments is forced by the (architecture-dependent) limits on the payload size of the underlying seL4 operations, as well as by efficiency considerations. +The protected procedure payload should be considered as analogous to function arguments in the C language; similar limitations exist in the C ABIs (Application Binary Interfaces) of various platforms.

+ +

Limits

+ +

The limitation on the number of protection domains in the system is relatively arbitrary. +Based on experience with the system and the types of systems being built it is possible for this to be increased in the future.

+ +

The limitation on the number of channels for a protection domain is based on the size of the notification word in seL4. +Changing this to be larger than 64 would most likely require changes to seL4. The reason for why the limit is not a +power of two is due to part of the notification word being for internal libmicrokit use.

+ +

Internals

+ +

The following section describes internal details for how the Microkit works +and all the components of Microkit. As a user of Microkit, it is not necessary +know this information, however, there is no harm in having a greater +understanding of the tools that you are using.

+ +

Microkit flow

+ +

The diagram above aims to show the general flow of a Microkit system from +build-time to run-time.

+ +

The user provides the SDF (System Description File) and the ELFs that +correspond to PD program images to the Microkit tool which is responsible +for packaging everything together into a single image for the target +platform.

+ +

ARM and RISC-V

+ +

The final image is a bootable image which contains a couple different things:

+ +
    +
  • the Microkit loader
    • +
  • seL4
    • +
  • the capDL initialiser (and associated capDL specification)
    • +
+ +

When booting the image, the Microkit loader starts, jumps to the kernel, which +starts the capDL initialiser, which then sets up the entire system and starts +all the PDs, including the Monitor.

+ +

x86

+ +

The tool produces the kernel image and boot module image that contains the capDL initialiser. +You must bring your own Multiboot 2 compliant bootloader which then loads the kernel and boot module.

+ +

Now, we will go into a bit more detail about each of these stages of the +booting process as well as what exactly the Microkit tool is doing.

+ +

Loader (ARM and RISC-V)

+ +

The loader starts first, it has two main jobs:

+ +
    +
  1. Unpack all the parts of the system (kernel and initialiser) into +their expected locations within main memory.
    2. +
  2. Finish initialising the hardware such that the rest of the system can start.
    3. +
+ +

Before the Microkit loader starts, there would most likely have been some other +bootloader such as U-Boot or firmware on the target that did its own hardware +initialisation before starting Microkit.

+ +

However, there are certain things that seL4 expects to be initialised +that will not be done by a previous booting stage, such as:

+ +
    +
  • changing to the right exception level
    • +
  • enabling the MMU (seL4 expects the MMU to be on when it starts)
    • +
  • interrupt controller setup
    • +
+ +

Once this is all completed, the loader jumps to seL4 which starts executing. +The loader will never be executed again.

+ +

capDL Initialiser

+ +

Once the kernel has done its own initialisation, it will begin the +‘initial task’. On seL4, this is a thread that contains all the initial +capabilities to resources and free memory that are used to setup the rest of the system.

+ +

Within a Microkit environment, the ‘initial task’ is the capDL initialiser. Its main +job is to initialises and starts the system in conformance with the capDL specification.

+ +

At build-time, the Microkit tool embeds the capDL specification that describe +all kernel objects that needs to be created. Then for each kernel object, the spec +describe what state they need to be in and what capabilities exist to that object +(i.e. who has access to this kernel object). For example, the spec would specify the:

+
    +
  • starting Instruction Pointer (IP), Stack Pointer (SP) and IPC buffer pointer of a Thread Control Block (TCB),
    • +
  • page table structure and mapping attributes of an address space (VSpace),
    • +
  • interrupts (IRQ),
    • +
  • scheduling parameters (Scheduling Context),
    • +
  • and so on…
    • +
+ +

Monitor

+ +

The Monitor is a special PD that executes at the highest priority. It’s job +is to receive any faults caused by protection domains crashing or causing exceptions.

+ +

After the monitor initialises itself, goes to sleep and waits for any +faults from protection domains. On debug mode, this results in a message about +which PD caused an exception and details on the PD’s state at the time of the fault.

+ +

Other than printing fault details, the monitor does not do anything to handle +the fault, it will simply go back to sleep waiting for any other faults.

+ +

libmicrokit

+ +

Unlike the previous sections, libmicrokit is not its own program but it is worth +a mention since it makes up the core of each protection domain in a system.

+ +

When each PD starts, we enter libmicrokit’s starting point which does some initial +setup and calls the init entry point specified by the user. Once that completes, +the PD will enter libmicrokit’s event handler which sleeps until it receives events.

+ +

These events could be notifies (from other PDs or from an interrupt), PPCs, and faults. +For each event, the appropriate user-specified entry point is called and then when it +returns the PD goes back to sleep, waiting on any more events.

+ +

Microkit tool

+ +

The Microkit tool’s ultimate job is to take in the description of the user’s system, +the SDF, and convert into an seL4 system that boots and executes.

+ +

There are obvious steps such as parsing the SDF and PD ELFs. But the majority of +the work done by the tool is converting the system description into the capDL specification +then embedding it into the capDL initialiser image.

+ +

ARM & RISC-V specific

+

Since the physical memory layout of ARM and RISC-V platforms can be determined at boot +time by reading the device tree. The Microkit tool goes one step further and statically +check that the produced capDL specification is bootable on the target board. For example, +we check that there are no frames outside of device or normal memory, and that there are +enough memory to create all required kernel objects.

+ +

In order to do this however, the Microkit tool needs to emulate how the seL4 kernel boot +to obtain the list of free untyped objects that the kernel would give to the initial task.

+ +

While this is non-trivial to do, it comes with the useful property that if the tool +produces a valid image, there should be no errors upon initialising the system +If there are any errors with configuring the system (e.g running out of memory), +they will be caught at build-time. This can only reasonably be done due to the +static-architecture of Microkit systems.

+ +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/microkit/manual/latest/microkit_user_manual.pdf b/projects/microkit/manual/latest/microkit_user_manual.pdf new file mode 100644 index 00000000000..27c33193214 Binary files /dev/null and b/projects/microkit/manual/latest/microkit_user_manual.pdf differ diff --git a/projects/microkit/platforms.html b/projects/microkit/platforms.html new file mode 100644 index 00000000000..33e114a8e5e --- /dev/null +++ b/projects/microkit/platforms.html @@ -0,0 +1,750 @@ + + + + + + + Microkit Supported Platforms | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit Supported Platforms

+ +

The following platforms are supported by the seL4 Microkit. See also the section +on Board Support Packages in the Microkit manual.

+ +

Microkit currently supports Arm AArch64 and RISC-V boards. x64 +support is on the roadmap.

+ +

Arm

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlatformSystem-on-chipCoreMicrokit platform
i.MX8M PlusIMX8MP-EVKCortex-A53 Quad 1.8 GHzimx8mp_iotgate
Raspberry Pi 4BBCM2711Cortex-A72rpi4b_2gb
Raspberry Pi 4BBCM2711Cortex-A72rpi4b_4gb
Raspberry Pi 4BBCM2711Cortex-A72rpi4b_8gb
Ultra96v2 Evaluation KitZynq UltraScale+ MPSoCCortex-A53ultra96v2
ROCKPro64RK3399 hexa-coreCortex-A53 Quad 1.8 GHzrockpro64
Raspberry Pi 4BBCM2711Cortex-A72rpi4b_1gb
i.MX8M MiniIMX8MM-EVKCortex-A53 Quad 1.8 GHzimx8mm_evk
i.MX8M PlusIMX8MP-EVKCortex-A53 Quad 1.8 GHzimx8mp_evk
i.MX8M QuadMCIMX8M-EVKBCortex-A53 Quad 1.5 GHzimx8mq_evk
Avnet MaaXBoardi.MX8MQCortex-A53 Quad 1.5 GHzmaaxboard
Odroid-C2Amlogic S905Cortex-A53odroidc2
Odroid-C4Amlogic S905X3Cortex-A55odroidc4
QEMU Arm VirtvirtCortext-A53qemu_virt_aarch64
TQMa8XQP 1GBi.MX8X Quad PlusCortex-A35tqma8xqp1gb
Zynq ZCU102 Evaluation KitZynq UltraScale+ MPSoCCortex-A53zcu102
+ +

RISC-V

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlatformSystem-on-chipCoreMicrokit platform
Cheshire Cheshireserengeti
HiFive Premier P550ESWIN EIC7700XP550hifive_p550
Ariane Ariane (CVA6)ariane
Cheshire Cheshirecheshire
Pine64 Star64StarFive JH7110U74-MC, E24star64
QEMU RISC-Vvirtrv64qemu_virt_riscv64
+ +

Upcoming in the next release

+ + + + + + + + + + + + + + + + + + + + + + + + +
PlatformSystem-on-chipCoreMicrokit platform
Zynq ZCU102 Evaluation KitZynq UltraScale+ MPSoCCortex-A53kria_k26
Rock3bRK3568 quad-coreCortex-A55 Quad 2.0 GHzrock3b
+ +

Not in the list above?

+ +

See the section on adding platform +support for how to add a new platform to +Microkit. To add a platform to Microkit it must be supported by seL4 first. See +the seL4 page on supported platforms for options on that.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/microkit/platforms.md b/projects/microkit/platforms.md deleted file mode 100644 index a9e2e5dd299..00000000000 --- a/projects/microkit/platforms.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- - -# Microkit Supported Platforms - -The following platforms are supported by the seL4 Microkit. See also the section -on [Board Support Packages](manual/latest/#bsps) in the Microkit manual. - -Microkit currently supports [Arm](#arm) AArch64 and [RISC-V](#risc-v) boards. x64 -support is on the [roadmap](roadmap.html). - -{%- assign platforms = site.data.microkit_platforms.platforms %} - -## Arm - -| Platform | System-on-chip | Core | Microkit platform | -| - | - | - | - | - -{%- assign has_upcoming = false %} -{%- for p in platforms %} -{%- if p.since == 'dev' %} -{%- assign has_upcoming = true %} -{%- continue %} -{%- endif %} -{%- assign pages = site.pages | where: "cmake_plat", p.cmake_plat %} -{%- if pages.size == 1 %} -{%- assign pg = pages[0] %} -{%- if pg.arm_hardware != true %} -{%- continue %} -{%- endif %} -{%- assign display_name = pg.platform %} -{%- assign soc = pg.soc %} -{%- assign cpu = p.cpu | default: pg.cpu %} -{%- else %} -{%- assign display_name = p.name %} -{%- assign soc = "" %} -{%- assign cpu = p.cpu | default: "" %} -{%- endif %} -| [{{ display_name }}](manual/latest/#{{p.name}}) | {{ soc }} | {{ cpu }} | `{{ p.name }}` | -{%- endfor %} - -## RISC-V - -| Platform | System-on-chip | Core | Microkit platform | -| - | - | - | - | - -{%- for p in platforms %} -{%- if p.since == 'dev' %} -{%- assign has_upcoming = true %} -{%- continue %} -{%- endif %} -{%- assign pages = site.pages | where: "cmake_plat", p.cmake_plat %} -{%- if pages.size == 1 %} -{%- assign pg = pages[0] %} -{%- if pg.riscv_hardware != true %} -{%- continue %} -{%- endif %} -{%- assign display_name = pg.platform %} -{%- assign soc = pg.soc %} -{%- assign cpu = p.cpu | default: pg.cpu %} -{%- assign arch = pg.arch %} -{%- else %} -{%- assign display_name = p.name %} -{%- assign soc = "" %} -{%- assign cpu = p.cpu | default: "" %} -{%- endif %} -| [{{ display_name }}](manual/latest/#{{p.name}}) | {{ soc }} | {{ cpu }} | `{{ p.name }}` | -{%- endfor %} - -{%- if has_upcoming %} - -## Upcoming in the next release - -| Platform | System-on-chip | Core | Microkit platform | -| - | - | - | - | - -{%- for p in platforms %} -{%- if p.since != 'dev' %} -{%- continue %} -{%- endif %} -{%- assign pages = site.pages | where: "cmake_plat", p.cmake_plat %} -{%- if pages.size == 1 %} -{%- assign pg = pages[0] %} -{%- assign url = pg.url | relative_url %} -{%- assign display_name = '[' | append: pg.platform | append: '](' | append: url | append: ')' %} -{%- assign soc = pg.soc %} -{%- assign cpu = p.cpu | default: pg.cpu %} -{%- else %} -{%- assign display_name = p.name %} -{%- assign soc = "" %} -{%- assign cpu = p.cpu | default: "" %} -{%- endif %} -| {{ display_name }} | {{ soc }} | {{ cpu }} | `{{ p.name }}` | -{%- endfor %} - -{%- endif %} - -## Not in the list above? - -See the section on [adding platform -support](manual/latest/#adding-platform-support) for how to add a new platform to -Microkit. To add a platform to Microkit it must be supported by seL4 first. See -the seL4 page on [supported platforms](../../Hardware/#not-in-the-lists-above) for options on that. diff --git a/projects/microkit/releases.md b/projects/microkit/releases.md deleted file mode 100644 index e4c4cc6fcac..00000000000 --- a/projects/microkit/releases.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -permalink: /releases/microkit.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- - -# Microkit releases - -This page documents tagged releases of the seL4 [Microkit](../projects/microkit/) and their -corresponding SDK downloads and GPG signatures. - -The downloads are signed by Ivan Velickovic with the -key fingerprint `EFC6 142C FE61 C255 B4CD E959 6FBD 87E8 4FA8 89BB`. The key -is available from . - -{% assign coll = site['releases'] | where: "project", "microkit" %} -{% comment %} -Sort sorts by string sorting so a version of 2.3.0 is higher than 10.0.0. -Because of this we need to split the list into two before sorting. -{% endcomment %} -{% assign releases_1 = coll | where_exp:"item", "item.version_digits != 2" | sort: "version" %} -{% assign releases_2 = coll | where_exp:"item", "item.version_digits == 2" | sort: "version" %} -{% assign releases = releases_1 | concat: releases_2 %} - -{% assign sdk_downloads = site.data.projects.microkit.sdk_downloads %} - -{% for release in releases reversed -%} - -## {{ release.title }} {% if forloop.first %}(latest){% endif %} - -[Release notes]({{ release.url | relative_url }}) - - - - - - - - - - - -{%- assign sdks = sdk_downloads | where: "version", release.title %} -{%- assign sdks = sdks[0] %} -{%- for sdk in sdks.sdks %} - - - - - - -{%- endfor %} - -
OSArchDownloadSignature
{{ sdk.os }}{{ sdk.arch }}{{ sdk.label }}sig
- -{% endfor %} diff --git a/projects/microkit/roadmap.html b/projects/microkit/roadmap.html new file mode 100644 index 00000000000..478d2f0d401 --- /dev/null +++ b/projects/microkit/roadmap.html @@ -0,0 +1,624 @@ + + + + + + + Microkit roadmap | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit roadmap

+ +

Microkit is actively developed and so there are various features that +intend to be added to support the community’s needs.

+ +

This page talks about major features, for smaller improvements or +bugs see GitHub issues.

+ +

If you have a particular feature that is not listed here or need clarity +on its status, please open an issue on GitHub +or contact the developers.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureCurrent statusTimelineAvailability
Multi-core supportMerged, available in 2.1.0Q4’25PR #353
x86 supportMerged, available in 2.1.0Q4’25PR #337
Multi-kernel supportActively worked on.Q4’25Branch
PD templatesInitial work explored, requires more experimentation and development.Q1’26N/A
+ +

Feature details

+ +

x86 support

+ +

x86-64 support is available in the latest Microkit (since PR #337), +but not in an available release. The next release will contain x86-64 support.

+ +

Multi-kernel support

+ +

seL4 supports running on multiple cores, however there are no verified multi-core configurations. +As verified multi-core is a while away, one strategy to get a multi-core system working with +single-core seL4 is to run an instance of seL4 on each core. This feature requires a number of internal +changes but should be mostly transparent to the user.

+ +

This is being actively worked on, more details can be found here.

+ +

PD templates

+ +

Microkit systems have a ‘static architecture’, each PD declares what resources it needs at +build-time. This restriction provides useful properties but can be too limiting for certain +systems.

+ +

PD templates aim to allow PDs to be loaded at run-time and claim different resources. The +total potential resources any PD might have at a given time is still known at build-time, +but this allows some flexibilty particularly when doing something like live-upgrading a +system.

+ +

This feature is still in the somewhat early stages so is unlikely to be available soon.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/microkit/roadmap.md b/projects/microkit/roadmap.md deleted file mode 100644 index 57d19a43821..00000000000 --- a/projects/microkit/roadmap.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 UNSW ---- - -# Microkit roadmap - -Microkit is actively developed and so there are various features that -intend to be added to support the community's needs. - -This page talks about major features, for smaller improvements or -bugs see [GitHub issues](https://github.com/seL4/microkit/issues). - -If you have a particular feature that is not listed here or need clarity -on its status, please [open an issue on GitHub](https://github.com/seL4/microkit/issues) -or [contact the developers](https://sel4.systems/support.html). - -| Feature | Current status | Timeline | Availability | -|-----------------------------------------------------------| -| Multi-core support | Merged, available in 2.1.0 | Q4'25 | [PR #353](https://github.com/seL4/microkit/pull/353) | -| [x86 support](#x86) | Merged, available in 2.1.0 | Q4'25 | [PR #337](https://github.com/seL4/microkit/pull/337) | -| [Multi-kernel support](#multikernel) | Actively worked on. | Q4'25 | [Branch](https://github.com/au-ts/multikernel-manifest/) | -| [PD templates](#templates) | Initial work explored, requires more experimentation and development. | Q1'26 | N/A | - -## Feature details - -### x86 support {#x86} - -x86-64 support is available in the latest Microkit (since [PR #337](https://github.com/seL4/microkit/pull/337)), -but not in an available release. The next release will contain x86-64 support. - -### Multi-kernel support {#multikernel} - -seL4 supports running on multiple cores, however there are no verified multi-core configurations. -As verified multi-core is a while away, one strategy to get a multi-core system working with -single-core seL4 is to run an instance of seL4 on each core. This feature requires a number of internal -changes but should be mostly transparent to the user. - -This is being actively worked on, more details can be found [here](https://github.com/au-ts/multikernel-manifest/). - -### PD templates {#templates} - -Microkit systems have a 'static architecture', each PD declares what resources it needs at -build-time. This restriction provides useful properties but can be too limiting for certain -systems. - -PD templates aim to allow PDs to be loaded at run-time and claim different resources. The -total potential resources any PD might have at a given time is still known at build-time, -but this allows some flexibilty particularly when doing something like live-upgrading a -system. - -This feature is still in the somewhat early stages so is unlikely to be available soon. diff --git a/projects/microkit/setting-up.html b/projects/microkit/setting-up.html new file mode 100644 index 00000000000..6f9ae11502d --- /dev/null +++ b/projects/microkit/setting-up.html @@ -0,0 +1,568 @@ + + + + + + + Setting up your machine to use Microkit | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Setting up your machine to use Microkit

+ +

The seL4 Microkit is distributed as a software development kit (SDK) for Linux +and Mac on Intel and Arm architectures and needs no further setup.

+ +

You are free to choose your own development environment and build system. For an +example, see the Microkit tutorial, or the example +folder in the SDK together with the Microkit manual.

+ +

The SDK for the latest release can be downloaded below:

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/microkit/setting-up.md b/projects/microkit/setting-up.md deleted file mode 100644 index 42d2940fdad..00000000000 --- a/projects/microkit/setting-up.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- - -# Setting up your machine to use Microkit - -The seL4 Microkit is distributed as a software development kit (SDK) for Linux -and Mac on Intel and Arm architectures and needs no further setup. - -You are free to choose your own development environment and build system. For an -example, see the [Microkit tutorial](tutorial/welcome.html), or the `example` -folder in the SDK together with the [Microkit manual](manual/latest/). - -The SDK for the latest release can be downloaded below: - -{% assign coll = site['releases'] | where: "project", "microkit" %} -{% comment %} -Sort sorts by string sorting so a version of 2.3.0 is higher than 10.0.0. -Because of this we need to split the list into two before sorting. -{% endcomment %} -{% assign releases_1 = coll | where_exp:"item", "item.version_digits != 2" | sort: "version" %} -{% assign releases_2 = coll | where_exp:"item", "item.version_digits == 2" | sort: "version" %} -{% assign releases = releases_1 | concat: releases_2 | reverse %} -{% assign sdk_downloads = site.data.projects.microkit.sdk_downloads %} -{% assign release = releases[0] -%} - -- Release [{{ release.title }}]({{ release.url | relative_url }}) -{%- assign sdks = sdk_downloads | where: "version", release.title %} -{%- assign sdks = sdks[0] %} -{%- for sdk in sdks.sdks %} - - [{{ sdk.label }}]({{sdk.url}}) [[sig]({{sdk.url}}.asc)] -{%- endfor %} diff --git a/projects/microkit/tutorial/assets b/projects/microkit/tutorial/assets deleted file mode 120000 index de6efb55a38..00000000000 --- a/projects/microkit/tutorial/assets +++ /dev/null @@ -1 +0,0 @@ -../../../_repos/au-ts/microkit_tutorial/website/src/assets \ No newline at end of file diff --git a/projects/microkit/tutorial/assets/PD starting.svg b/projects/microkit/tutorial/assets/PD starting.svg new file mode 100644 index 00000000000..d4d38c8dcf1 --- /dev/null +++ b/projects/microkit/tutorial/assets/PD starting.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/projects/microkit/tutorial/assets/overview.svg b/projects/microkit/tutorial/assets/overview.svg new file mode 100644 index 00000000000..ba7f7bbc54e --- /dev/null +++ b/projects/microkit/tutorial/assets/overview.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/projects/microkit/tutorial/assets/part1/event_loop.svg b/projects/microkit/tutorial/assets/part1/event_loop.svg new file mode 100644 index 00000000000..39e1675a94c --- /dev/null +++ b/projects/microkit/tutorial/assets/part1/event_loop.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/projects/microkit/tutorial/assets/part1/overview.svg b/projects/microkit/tutorial/assets/part1/overview.svg new file mode 100644 index 00000000000..200e04d1a0f --- /dev/null +++ b/projects/microkit/tutorial/assets/part1/overview.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/projects/microkit/tutorial/assets/part2/overview.svg b/projects/microkit/tutorial/assets/part2/overview.svg new file mode 100644 index 00000000000..34ab1b5a95d --- /dev/null +++ b/projects/microkit/tutorial/assets/part2/overview.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/projects/microkit/tutorial/assets/part3/overview.svg b/projects/microkit/tutorial/assets/part3/overview.svg new file mode 100644 index 00000000000..e199286a159 --- /dev/null +++ b/projects/microkit/tutorial/assets/part3/overview.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/projects/microkit/tutorial/assets/part4/passthrough.svg b/projects/microkit/tutorial/assets/part4/passthrough.svg new file mode 100644 index 00000000000..946d7ec10a9 --- /dev/null +++ b/projects/microkit/tutorial/assets/part4/passthrough.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/projects/microkit/tutorial/assets/pd_starting.svg b/projects/microkit/tutorial/assets/pd_starting.svg new file mode 100644 index 00000000000..23f1e10180b --- /dev/null +++ b/projects/microkit/tutorial/assets/pd_starting.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/projects/microkit/tutorial/assets/rpi3_gpio.png b/projects/microkit/tutorial/assets/rpi3_gpio.png new file mode 100644 index 00000000000..24238cc23d8 Binary files /dev/null and b/projects/microkit/tutorial/assets/rpi3_gpio.png differ diff --git a/projects/microkit/tutorial/assets/serial_server.svg b/projects/microkit/tutorial/assets/serial_server.svg new file mode 100644 index 00000000000..54ff80211a6 --- /dev/null +++ b/projects/microkit/tutorial/assets/serial_server.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/projects/microkit/tutorial/end.html b/projects/microkit/tutorial/end.html new file mode 100644 index 00000000000..9d9858ffd58 --- /dev/null +++ b/projects/microkit/tutorial/end.html @@ -0,0 +1,600 @@ + + + + + + + Microkit Tutorial - End | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ +

End

+ +

This is the end of the tutorial. Thank you for taking to the time to complete it, I hope +you found it enjoyable and you learnt something!

+ +

If you have any questions or feedback, feel free to open an issue on the GitHub repository.

+ + + + + +

Solutions

+ +

The solutions are available for download from here.

+ +

Alternatively you can download them via:

+
# Make sure to run these commands in the microkit_tutorial directory created in part 0
+curl -L trustworthy.systems/Downloads/microkit_tutorial/solutions.tar.gz -o solutions.tar.gz
+tar xf solutions.tar.gz
+
+ +

To build the solutions do:

+
cd solutions
+make part4
+
+ +

To run the solutions do:

+
make run
+
+ + +
+ +
+
+ + + +
+ +
+
+ + diff --git a/projects/microkit/tutorial/end.md b/projects/microkit/tutorial/end.md deleted file mode 100644 index 5ecd0d323e7..00000000000 --- a/projects/microkit/tutorial/end.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Microkit Tutorial - End -nav_prev: part4.html -SPDX-License-Identifier: CC-BY-NC-SA-4.0 -SPDX-FileCopyrightText: 2025 Ivan Velickovic ---- - -{% include include_external_markdown.md - file="_processed/microkit-tutorial/end.md" %} diff --git a/projects/microkit/tutorial/part0.html b/projects/microkit/tutorial/part0.html new file mode 100644 index 00000000000..f8101d8dca8 --- /dev/null +++ b/projects/microkit/tutorial/part0.html @@ -0,0 +1,823 @@ + + + + + + + Microkit Tutorial - Setting Up | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ +

Part 0 - Setting up your environment

+ + + +

This page covers two things:

+
    +
  1. Acquiring the Microkit SDK and the other dependencies needed for the tutorial.
    2. +
  2. Acquiring the tutorial code, so you can complete the exercises.
    3. +
+ +

If you have any issues, feel free to open an issue on the GitHub repository.

+ +

Acquiring the dependencies

+

We have two options for working on the tutorial:

+ +
    +
  1. Install dependencies and do the tutorial natively, however this option is only available if you are doing the tutorial on Linux, macOS or Nix.
    2. +
  2. If you prefer to use Docker, you can follow the instructions for Docker.
    3. +
+ +

Option 1 - Linux, macOS, Nix

+ +

You’ll need the following dependencies:

+
    +
  • Make
    • +
  • AAarch64 cross compiler
    • +
  • QEMU simulator for running the tutorial
    • +
  • The Microkit SDK
    • +
+ +
+
+ + + + + + + + + + + +
+ +

Option 2 - Docker

+ +

seL4 provides an official Docker container which has the necessary dependencies for this tutorial. +You can find instructions for acquring it here.

+ +

After setting up the Docker container, run the following commands outside Docker:

+
# First make a directory for the tutorial
+mkdir microkit_tutorial
+cd microkit_tutorial
+# Then start the Docker container
+container
+# Then download and extract the SDK
+curl -L https://github.com/seL4/microkit/releases/download/2.0.1/microkit-sdk-2.0.1-linux-x86-64.tar.gz -o sdk.tar.gz
+tar xf sdk.tar.gz
+
+ +

This Docker image is mounted on your host file system. What that means is that the microkit_tutorial directory is +accessible from both Docker and from your normal environment.

+ +

Run all the commands for downloading the tutorial code and building/running the tutorial in the container. You can +then open the microkit_tutorial directory in your code editor for viewing/editing the tutorial code.

+ + + +

Getting the tutorial code

+ +
# Download and extract the tutorial code (in the microkit_tutorial directory)
+curl -L trustworthy.systems/Downloads/microkit_tutorial/tutorial.tar.gz -o tutorial.tar.gz
+tar xf tutorial.tar.gz
+
+ +

Now you can move on to part 1 of the tutorial.

+ + +
+ +
+
+ + + +
+ +
+
+ + diff --git a/projects/microkit/tutorial/part0.md b/projects/microkit/tutorial/part0.md deleted file mode 100644 index 8aca5aac3df..00000000000 --- a/projects/microkit/tutorial/part0.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Microkit Tutorial - Setting Up -nav_prev: welcome.html -nav_next: part1.html -SPDX-License-Identifier: CC-BY-NC-SA-4.0 -SPDX-FileCopyrightText: 2025 Ivan Velickovic ---- - -{% include include_external_markdown.md - file="_processed/microkit-tutorial/part0.md" %} diff --git a/projects/microkit/tutorial/part1.html b/projects/microkit/tutorial/part1.html new file mode 100644 index 00000000000..872e1115326 --- /dev/null +++ b/projects/microkit/tutorial/part1.html @@ -0,0 +1,939 @@ + + + + + + + Microkit Tutorial - Serial server | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ +

Part 1 - Serial server

+ +

Since seL4 is a micro-kernel, a lot of functionality you would typically expect +from a kernel is deliberately not implemented. One example of this is something as simple +as outputting and inputting characters via a terminal. There are no write or read system calls +like on Linux or macOS. While there is a way to output characters to the terminal via seL4, +it is strictly for when debugging/developing.

+ +

This means that if we want to build a system like Wordle, which takes user-input +and displays the game results via the serial connection, we first need a driver for the serial +connection.

+ +

In this first part, you will learn all the pieces that go to make a driver on top of +seL4. This driver will act as a “server” that clients (in this case the Wordle client) +will send data to. The serial server then is the one actually talking to the serial +device. The serial device that we will be using is called a Universal Asynchronous Receiver-Transmitter (UART).

+ +

Below is a diagram of what we will end up with by the end of this part1:

+ + + + + +

Serial server overview

+ +

Creating a serial server

+ +

System description example

+ +

In Microkit, you describe the architecture of the system you are building in a file we refer to as the “system description”. This file is written in the XML format. Below is an example of a very simple “hello world!” system you could create. It contains a single protection domain that will print out “hello, world!” when it executes. You can see here we define a <protection_domain>, with the program image being some code that we have compiled to hello_world.elf.

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<system>
+    <protection_domain name="hello_world">
+        <program_image path="hello_world.elf" />
+    </protection_domain>
+</system>
+
+ +

Before making our own system description, let’s first understand what a protection domain actually is.

+ +

Protection Domains (PDs)

+ +

A protection domain is similar to a “process” on typical UNIX systems. However, by default a protection domain +cannot do much except execute its code.

+ +

A protection domain is an abstraction created by Microkit and is made up of various seL4 primitives. The main ones are:

+
    +
  • A thread-control-block (TCB), because in order to actually have a thread of execution, seL4 needs to create a thread.
    • +
  • A virtual address-space, known as a VSpace. This is what memory the kernel allows the PD to access. By default all that +is in the VSpace is the ELF2 of the PD, so it can execute its own code, and nothing else.
    • +
  • A capability space, known as a CSpace. Each protection domain has its own CSpace which is a data structure that holds all the capabilities +that a PD has access to.
    • +
+ +

As you can see, there is not lot a PD can actually do by default. And this is intentional. We do not want PDs +to be able to access anything unless we explicitly allow it. This is allowed by the capability system, as all resources +in seL4 are modelled by capabilities. If a PD does not have the capability to some resource, seL4 does not allow it to use it!

+ +
+ What is a capability? (click to expand) +

Whenever you open a file on UNIX-like operating systems, the kernel gives you a file-descriptor. A unique token that + is used to refer to that file from now on. Say if you want to read or write or close the file, you have to use the + file-descriptor. You can think of capabilities as similar to file-descriptors except that it is for every kind of + object in seL4. For example if you wanted a thread to have access to a certain page of memory, it must have the + capability to that page. If you want multiple threads to communicate (as we’ll see later), each thread must + also have capabilities to the communication objects (such as Endpoints and Notifications in seL4).

+
+ +

Entry points

+ +

Although a protection domain is somewhat analogous to a process, it has a considerably different program structure and life-cycle. A process on a typical operating system will have a main function which is invoked by the system when the process is created. When the main function returns the process is destroyed. By comparison a protection domain has three entry points: init, notified and, optionally, protected.

+ +

When a Microkit system is booted, all PDs in the system execute the init entry point, and then the Microkit library (libmicrokit) that +each PD is linked with waits for events to come in. This diagram shows the control flow of a PD:

+ +

Serial server overview

+ +

Here is a description of the protection_domain element:

+
    +
  • name: a unique name for the protection domain.
    • +
  • priority: (optional) the priority of the protection domain (integer 0 to 254), defaults to 0 which is the lowest possible priority. The priority dictates which order PDs will run in. For example if there are two PDs that are both schedulable (i.e. are ready to run) then seL4 +will run the higher priority one first.
    • +
  • budget: (optional) the PD’s budget in microseconds; defaults to 1,000.
    • +
  • period: (optional) the PD’s period in microseconds; must not be smaller than the budget; defaults to the budget.
    • +
+ +
+ What are budgets and periods? +

While not the focus of this tutorial, budgets and periods allow those making systems on seL4 to specify how long a thread runs +for a given amount of time. For example, if there was a thread with 100ms of budget and 300ms of period, that means that the +thread is allowed to run for (at most) 100ms every 300ms of CPU time.

+ +

If you are interested, there is more information in the seL4 reference manual.

+
+ +

Serial server protection domain

+ +

Now that you have some understanding of how protection domains work and are specified, your task is to:

+
    +
  • Edit the system description (wordle.system) to specify a protection domain for the serial server. +
      +
    • The name of the program image produced by the Makefile is serial_server.elf.
      • +
    • All values in the XML description are surrounded by quotes, for example, <protection_domain name="pd" priority="254" />.
      • +
    +
    • +
  • Since this PD is a server rather than a client, it should have a higher priority than the client.
    • +
+ +

Building

+ +

If we build part 1 and then look inside the build directory:

+
# Run these commands inside the "microkit_tutorial" directory
+$ cd tutorial
+# If you are working on native macOS, `make` may be installed as `gmake` instead.
+$ make part1
+$ ls build
+serial_server.elf serial_server.o loader.img report.txt
+
+ +

We can see that when we run make part1, the file serial_server.c gets compiled into serial_server.elf. That is why the name of the program image in the system description file is serial_server.elf.

+ +

After compiling all the code, the microkit tool takes our ELFs and system description file +and produces loader.img, a binary containing everything that we then give to QEMU to load.

+ +

The report.txt file contains details about the system that can be useful when debugging, but +for this tutorial, you do not need to look at it.

+ + + + + + + + + + +

Running

+ +

In order to actually run the system, we will be using the QEMU emulator which allows us to essentially create +virtual hardware that we then run seL4 on.

+ +

You can emulate the system using the provided Makefile with:

+
make run
+
+ +

To exit QEMU, press CTRL + a then x.

+ +
+ Explanation of the QEMU command + +

The full command that is actually being run by make is:

+ + 
qemu-system-aarch64 -machine virt,virtualization=on \
+    -cpu cortex-a53 \
+    -serial mon:stdio \
+    -device loader,file=build/loader.img,addr=0x70000000,cpu-num=0 \
+    -m size=1G \
+    -nographic \
+    -netdev user,id=mynet0 \
+    -device virtio-net-device,netdev=mynet0,mac=52:55:00:d1:55:01
+
+ +

For those not overly familiar with QEMU, I will break down the arguments.

+
    +
  • -machine virt,virtualization=on -cpu cortex-a53: This just specifies the board we are emulating, in this case we are using QEMU’s AArch64 “virt” board which has no physical counterpart, and we’re specifying to use one ARM Cortex-A53 CPU. The virtualization=on is for part 4 of the tutorial, where we run virtual machines on top of seL4.
    • +
  • -serial mon:stdio: Send virtual serial output and QEMU’s monitor output onto stdio.
    • +
  • -device loader,file=build/loader.img,addr=0x70000000,cpu-num=0: QEMU won’t know how to automatically load this image. Typically with seL4 projects the image is passed via the -kernel flag, however, in this case we have to make the address that the Microkit bootloader is expecting to be loaded at explicit. This is because we are giving QEMU a “raw image”. More information is here.
    • +
  • -m size=1G: Have 1G of RAM. This is plenty for this tutorial, but depending on what you’re doing, might need to be increased.
    • +
  • -nographic: Disable all graphical output to use QEMU just on the command line.
    • +
  • -netdev user,id=mynet0 -device virtio-net-device,netdev=mynet0,mac=52:55:00:d1:55:01: Enables networking for part 4 of the tutorial.
    • +
+
+ +

If you’ve done everything correctly, you should see the following output:

+
MON|ERROR: received message 0x00000006  badge: 0x0000000000000001  tcb cap: 0x8000000000000006
+MON|ERROR: faulting PD: serial_server
+MON|ERROR: Registers:
+MON|ERROR: pc : 0x00000000002000e8
+MON|ERROR: spsr : 0x0000000000000040
+MON|ERROR: x0 : 0x0000000000000050
+MON|ERROR: x1 : 0x0000000000000038
+MON|ERROR: x2 : 0x0000000000000000
+MON|ERROR: x3 : 0x0000000000000000
+MON|ERROR: x4 : 0x0000000000000000
+MON|ERROR: x5 : 0x0000000000000000
+MON|ERROR: x6 : 0x0000000000000000
+MON|ERROR: x7 : 0x0000000000000000
+MON|ERROR: VMFault: ip=0x00000000002000e8  fault_addr=0x0000000000000038  fsr=0x0000000092000046  (data fault)
+MON|ERROR:    ec: 0x00000024  Data Abort from a lower Exception level   il: 1   iss: 0x00000046
+MON|ERROR:    dfsc = translation fault, level 2 (0x00000006) -- write not read
+
+ +

When we start the system we get a bunch of error printing, what has happened?

+ +

Remember that by default a protection domain does not have access to any memory other than its own code +(as well as any global data and the stack region).

+ +

If we look at serial_server.c:

+ +
void uart_handle_irq() {
+    *REG_PTR(uart_base_vaddr, UARTICR) = 0x7f0;
+}
+
+void uart_put_str(char *str) {
+    while (*str) {
+        uart_put_char(*str);
+        str++;
+    }
+
+ +

You will see that it tries to access the UART hardware when it calls uart_init(), which it doesn’t have access to! What happens +is that seL4 gets a “virtual memory fault” and delivers this to something called the monitor which +then prints out the errors you are seeing with MON|ERROR. The monitor acts as the initial task and default fault-handler for Microkit.

+ +

So how do we prevent the virtual memory fault from happening? We need to give the serial server access to the UART.

+ +

Accessing the UART

+ +

Our serial driver will be useless unless it can actually access the UART device registers. We +cannot just access the physical address of the UART device since the driver is a user-space +program (Protection Domain) and so has its own virtual address space. +This means we will need to map in the physical address into our PD’s virtual address space. +Microkit provides an abstraction for this, it is called “Memory Regions”.

+ +

Memory Regions (MRs)

+ +

We can create memory regions at a specific physical address, or somewhere in RAM, that we can then map into the address space of whichever PD we want to have access to it. Here is a full description of the memory_region element which you would use to create a memory region:

+
    +
  • name: A unique name for the memory region
    • +
  • size: Size of the memory region in bytes (must be a multiple of the page size)
    • +
  • page_size: (optional) Size of the pages used in the memory region; must be a supported page size if provided. Defaults to the largest page size for the target architecture that the memory region is aligned to.
    • +
  • phys_addr: (optional) The physical address for the start of the memory region (must be a multiple of the page size).
    • +
+ +

In order to access the memory region from a PD, it needs to be mapped using the map element:

+
    +
  • mr: Identifies the memory region to map.
    • +
  • vaddr: Identifies the virtual address at which to map the memory region.
    • +
  • perms: Identifies the permissions with which to map the memory region. Can be a combination of r (read), w (write), and x (eXecute), with the exception of a write-only mapping (just w).
    • +
  • cached: (optional) Determines if mapped with caching enabled or disabled. Defaults to true.
    • +
  • setvar_vaddr: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the virtual address of the memory region.
    • +
  • setvar_size: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the size of the memory region.
    • +
+ +

Example

+ +

Here is an example of how the system description would look for a driver for a real time clock (RTC) device.

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<system>
+    <!-- Define a page sized region for accessing the "real-time clock" -->
+    <memory_region name="rtc" size="0x1000" phys_addr="0x9010000" />
+
+    <protection_domain name="timer_driver">
+        <program_image path="timer_driver.elf" />
+        <!--
+            Map in the "rtc" region that corresponds to the physical address
+            of the real time clock. The Microkit tool will set the value of
+            the variable "rtc_base_vaddr" to the virtual address of the mapping
+            when compiling the final `loader.img` image
+         -->
+        <map mr="rtc" vaddr="0x2000000" perms="rw" cached="false"
+            setvar_vaddr="rtc_base_vaddr" />
+    </protection_domain>
+</system>
+
+ +

Mapping in the UART device

+ +

From reading the above example and referring to the description of the map and memory_region elements, you should be able to create the mapping to the UART for the serial server.

+ +

Note that:

+
    +
  • With QEMU, we’ll be using a PL011 UART which has a physical address of 0x9000000.
    • +
  • You only need to map in a single 4KiB page.
    • +
  • Microkit places the code of a PD starting at 0x200000 in it’s virtual address space. This means that the address to place the mapping for the UART should be below this, or significantly higher to avoid overlapping (e.g. 0x4000000) with the code of the PD.
    • +
  • You can use setvar_vaddr to initialise a symbol in the code to the specified virtual address. The UART driver provided expects a uintptr_t uart_base_vaddr variable to be set to the virtual address of the UART mapping.
    • +
  • Since we are doing memory mapped I/O, we do not want to enable caching on the mapping.
    • +
+ +

Your task now is to:

+
    +
  • Map in the UART to the serial server PD with both read and write permissions.
    • +
  • Run the system and check to see if the SERIAL SERVER: starting appears.
    • +
+ +

Interrupt handling

+ +

An interrupt request (IRQ) is a signal from a hardware device (e.g. the UART serial device) that tells software that some event +has happened. In the case of the UART device, every time we input a character, the device will deliver an interrupt to +seL4. In seL4, it decodes the signal and then sends the interrupt as a notification to user-space. In our system we want +this interrupt to go to the serial server so that it can handle the interrupt.

+ +

In the serial server code (serial_server.c) you will see the notified(microkit_channel ch) entry point. What we want to +happen is that whenever we get an interrupt form the UART the notified entry point is executed. Then we can handle the interrupt and once notified +finishes, the PD will go back to waiting to receive more events (such as more interrupts).

+ +

In the Microkit system description, we need to register these interrupts and associate them with a certain PD. This is because like with memory, IRQs are also modelled by capabilities meaning that we need to have the capability to a certain interrupt, before it can be delivered to a PD by seL4.

+ +

The irq element is a child element of protection_domain (just like program_image), and has the following attributes:

+
    +
  • irq: The interrupt number.
    • +
  • id: The channel identifier, an integer from 0 to 623.
    • +
+ +

The channel identifier is what’s used by a PD to distinguish a particular interrupt from other interrupts or other notification sources. +For example, if you had <irq id="0" irq="20" /> this would mean that whenever we get the interrupt number 20 from the hardware, the +notified(microkit_channel ch) function will be entered, where the value of the ch parameter is 0.

+ +

Your task now is to:

+
    +
  • Specify the interrupt for serial input in the system description. +
      +
    • For the QEMU platform, the IRQ number is 334. +
      • +
    +
    • +
  • Inspect the serial server code (serial_server.c) and complete the notified entry point. When receiving the UART interrupt, do the following: +
      +
    1. Get the character that has been inputted via the keyboard with the int uart_get_char() function.
      2. +
    2. Print out the character using the void uart_put_char(int ch) function.
      3. +
    3. Call the function void uart_handle_irq() for the driver to handle the IRQ.
      4. +
    4. Call the libmicrokit function void microkit_irq_ack(microkit_channel ch), in order to acknowledge the IRQ. +
        +
      • Why do we need to acknowledge the IRQ? What this does is tell seL4 that we have finished handling +the IRQ and are ready to receive another one. If we do not acknowledge it, we will never receive +another UART IRQ again!
        • +
      +
      5. +
    +
    • +
+ +

Now we can check to see that we are actually receiving interrupts. When you input a character, it should be printing as well. If that is working, you can move on to the next exercise.

+ +
+ +
+
    +
  1. +

    MMIO stands for “Memory Mapped Input/Output”. It is a way of interacting with certain hardware via memory, in this case the UART device. ↩

    +
    2. +
  2. +

    ELF stands for Executable and Linkable Format, it is just a standard format to compile programs into. ↩

    +
    3. +
  3. +

    You might find this number a bit unexpected, as it is not a power of two. You can + find more details in the Microkit manual here. ↩

    +
    4. +
  4. +

    You may be wondering how we know this number. On ARM and RISC-V platforms, there are two main ways to + find out the IRQ number for a specific hardware device. One is via official documentation like a + ‘Technical Reference Manual’, the other is by inspecting something called the Device Tree Source. This + is a file associated with a particular hardware platform, like the QEMU platform or a particular Raspberry Pi + model for example. These ‘Device Trees’ contain information such as what the physical address is of a device, + and what interrupt number(s) it uses. It should be noted that when registering an IRQ with Microkit/seL4, you + must have the CPU observable number, which may not be the same number as the one in the DTS. For example, on + ARM peripheral devices (such as UARTs) are offset by 32. In our case, the DTS says the UART devices has an IRQ + with number 1, which means that when we want to use it in Microkit/seL4, it becomes 33. ↩

    +
    5. +
+
+ +
+ +
+
+ + + +
+ +
+
+ + diff --git a/projects/microkit/tutorial/part1.md b/projects/microkit/tutorial/part1.md deleted file mode 100644 index 410bbbb2b6a..00000000000 --- a/projects/microkit/tutorial/part1.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Microkit Tutorial - Serial server -nav_prev: part0.html -nav_next: part2.html -SPDX-License-Identifier: CC-BY-NC-SA-4.0 -SPDX-FileCopyrightText: 2025 Ivan Velickovic ---- - -{% include include_external_markdown.md - file="_processed/microkit-tutorial/part1.md" %} diff --git a/projects/microkit/tutorial/part2.html b/projects/microkit/tutorial/part2.html new file mode 100644 index 00000000000..8aa00340680 --- /dev/null +++ b/projects/microkit/tutorial/part2.html @@ -0,0 +1,776 @@ + + + + + + + Microkit Tutorial - Client | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ +

Part 2 - Client

+ +

Now that we have a serial server working, our next goal will be to have a client PD that serves a command-line interface to play Wordle. For this we want to have a way for the client to retrieve characters from the serial server. A relatively simple way to do this is to share a buffer and have the serial server notify the client that there’s a new character to read. We also want the client to be able to send characters for the serial server +to output to the terminal. By the end of this part, we will have something like the following:

+ +

Serial server and client overview

+ + + +

Your first task is to:

+
    +
  • Add a PD for the client to the system description. The name of the client’s program image is client.elf. +
      +
    • Note that, as mentioned in part 1, the client should have a lower priority than the serial server.
      • +
    +
    • +
+ +

Building

+ +

For building part 2, run the command:

+ +
make part2
+
+ +

Running

+ +

The same command from part 1 works:

+
make run
+
+ +

You should get the following output, indicating that the client has been successfully started:

+
SERIAL SERVER: starting
+CLIENT: starting
+
+ +

The next step is to get the client and serial server communicating.

+ +

Channels

+ +

A channel allows two protection domains to interact with each other, either via notifications which are asynchronous and bidirectional, or, protected procedures which are synchronous and unidirectional. In this part of the tutorial, you’ll be using notifications (protected procedures will be covered later).

+ +

When a channel is created between two PDs, a channel identifier is configured for each PD. The channel identifier is used by the PD to reference the channel. Each PD can refer to the channel with a different identifier. For example if PDs A and B are connected by a channel, A may refer to the channel using an identifier of 37 while B may use 42 to refer to the same channel.

+ +

The channel element has exactly two end children elements for specifying the two PDs associated with the channel.

+ +

The end element has the following attributes:

+ +
    +
  • pd: Name of the protection domain for this end.
    • +
  • id: Channel identifier in the context of the named protection domain. Must be at least 0 and less than 63.
    • +
  • pp: (optional) Indicates that the protection domain for this end can perform a protected procedure call to the other end; defaults to false. + Protected procedure calls can only be to PDs of strictly higher priority.
    • +
  • notify: (optional) Indicates that the protection domain for this end can send a notification to the other end; defaults to true.
    • +
+ +

Example

+ +

Here is a basic example of two PDs using a channel to notify each other.

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<system>
+    <protection_domain name="sender">
+        <program_image path="sender.elf" />
+    </protection_domain>
+    <protection_domain name="receiver">
+        <program_image path="receiver.elf" />
+    </protection_domain>
+
+    <channel>
+        <end pd="sender" id="1" />
+        <end pd="receiver" id="2" />
+    </channel>
+</system>
+
+ +

The sender’s code might look something like this:

+
#include <microkit.h>
+
+#define RECEIVER_CHANNEL_ID 1
+
+void init() {
+    // Send a message to the receiver
+    microkit_notify(RECEIVER_CHANNEL_ID);
+}
+
+ +

The receiver’s code might look something like this:

+
#include <microkit.h>
+
+#define SENDER_CHANNEL_ID 2
+
+void notified(microkit_channel ch) {
+    // Receive a message from the sender
+    switch (ch) {
+        case SENDER_CHANNEL_ID:
+            microkit_dbg_puts("Received message from sender!\n");
+    }
+}
+
+void init() {}
+
+ +

Notice that the IDs of the channel are local to the PD. The sender refers to the channel with 2 but the receiver refers to the same channel with 1.

+ +

Your task now is to:

+
    +
  • Add the channel to the system description.
    • +
  • You can make sure you have added the channel correctly by printing a message when the client gets notified from the serial server. +
      +
    • You can use either microkit_dbg_puts to print out a string or use printf for formatted strings. printf is just using microkit_dbg_puts +behind the scenes anyways, but will be more convenient if you have to debug etc.
      • +
    +
    • +
+ +

Shared buffer

+ +

Now that we can communicate between the client and serial server, the serial server has the ability to let the client know that it has received input. Since we cannot pass data via notifications, we will use a shared buffer, placing each new character in the buffer and subsequently notifying the client.

+ +

Example

+ +

If we wanted to have two PDs that share a buffer to avoid costly IPC to send data between the PDs, my system description might look something like this:

+ +
<?xml version="1.0" encoding="UTF-8"?>
+<system>
+    <!--
+        Define a page sized buffer to share between the "sender" and "receiver"
+        protection domains.
+    -->
+    <memory_region name="shared_buffer" size="0x1000" />
+
+    <protection_domain name="sender">
+        <program_image path="sender.elf" />
+        <!--
+            Map the buffer into the address space of "sender", which only
+            writes to it. The Microkit tool will do ELF symbol patching to set
+            the virtual address of the mapping to a global variable called
+            "buffer". The region is mapped as read-write as write-only mappings
+            are not permitted by seL4 (at least on AArch64).
+        -->
+        <map mr="shared_buffer" vaddr="0x4000000" perms="rw" setvar_vaddr="buffer"/>
+    </protection_domain>
+    <protection_domain name="receiver">
+        <program_image path="receiver.elf" />
+        <!--
+            Map the buffer into the address space of "receiver", which only
+            reads from it. The Microkit tool will do ELF symbol patching to set
+            the virtual address of the mapping to a global variable called
+            "buffer".
+        -->
+        <map mr="shared_buffer" vaddr="0x4000000" perms="r" setvar_vaddr="buffer"/>
+    </protection_domain>
+</system>
+
+ +
+ Reference for memory region and map elements + +

memory_region:

+
    +
  • name: A unique name for the memory region
    • +
  • size: Size of the memory region in bytes (must be a multiple of the page size)
    • +
  • page_size: (optional) Size of the pages used in the memory region; must be a supported page size if provided. Defaults to the largest page size for the target architecture that the memory region is aligned to.
    • +
  • phys_addr: (optional) The physical address for the start of the memory region (must be a multiple of the page size).
    • +
+ +

map:

+
    +
  • mr: Identifies the memory region to map.
    • +
  • vaddr: Identifies the virtual address at which to map the memory region.
    • +
  • perms: Identifies the permissions with which to map the memory region. Can be a combination of r (read), w (write), and x (eXecute), with the exception of a write-only mapping (just w).
    • +
  • cached: (optional) Determines if mapped with caching enabled or disabled. Defaults to true.
    • +
  • setvar_vaddr: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the virtual address of the memory region.
    • +
  • setvar_size: (optional) Specifies a symbol in the program image. This symbol will be rewritten with the size of the memory region.
    • +
+
+ +

Your task now is to:

+
    +
  • Create two shared buffers between the client and server. One buffer should handle user input, the other should handle output in order to display the game state.
    • +
  • Be able to print out the characters received from the serial server in the client.
    • +
  • Implement the serial_send function in the client to print out the game’s interface.
    • +
+ +

Ultimately, you want to be able to get some output like this:

+
SERIAL SERVER: starting
+CLIENT: starting
+Welcome to the Wordle client!
+[h] [e] [l] [l] [o]
+[t] [h] [e] [r] [e]
+[ ] [ ] [ ] [ ] [ ]
+[ ] [ ] [ ] [ ] [ ]
+[ ] [ ] [ ] [ ] [ ]
+
+ +

Pressing ENTER (\r) should move to the next line if they’ve entered enough characters. Similarly, you should be able to delete a character by pressing BACKSPACE.

+ +

Once you have that working, we can implement the Wordle server to get it to check whether we have a correct guess.

+ + +
+ +
+
+ + + +
+ +
+
+ + diff --git a/projects/microkit/tutorial/part2.md b/projects/microkit/tutorial/part2.md deleted file mode 100644 index 1ec10a2b93b..00000000000 --- a/projects/microkit/tutorial/part2.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Microkit Tutorial - Client -nav_prev: part1.html -nav_next: part3.html -SPDX-License-Identifier: CC-BY-NC-SA-4.0 -SPDX-FileCopyrightText: 2025 Ivan Velickovic ---- - -{% include include_external_markdown.md - file="_processed/microkit-tutorial/part2.md" %} diff --git a/projects/microkit/tutorial/part3.html b/projects/microkit/tutorial/part3.html new file mode 100644 index 00000000000..67791441d35 --- /dev/null +++ b/projects/microkit/tutorial/part3.html @@ -0,0 +1,641 @@ + + + + + + + Microkit Tutorial - Wordle server | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ +

Part 3 - Wordle server

+ +

This part involves hooking up the client with a Wordle server PD. The Wordle server will accept attempted guesses of what the word is from the client, and will reply with what characters in the word were correct, incorrect, or correct but in the wrong position. At the end of this exercise, you should have a playable Wordle!

+ +

As mentioned in the previous part, there are two operations you can do using a channel, so far we have used notifications to asynchronously signal a PD that an event has occurred. With the Wordle server however, we want the semantics that the client requests the server to check the word that has been entered by the player, and returns a response with: what characters were correct, what characters were correct but in the wrong place, and what characters were incorrect.

+ +

To do this, we will use a synchronous method of communication, where the client will be blocked and waiting on the Wordle server for a response on each request.

+ +

Client and wordle server overview

+ +

Protected Procedure Calls (PPC)

+ +

A protection domain may provide a protected procedure (PP) which can be invoked from another protection domain. Up to 64 words of data may be passed as arguments when calling a protected procedure. The protected procedure return value may also be up to 64 words.

+ +

When a protection domain calls a protected procedure, the procedure executes within the context of the providing protection domain.

+ +

A protected procedure call is only possible if the callee has strictly higher priority than the caller. This means that if A has a priority of 1 and B has a priority of 254, A can invoke B’s protected procedure, but B cannot invoke A’s protected procedure. Transitive calls are possible, and as such a PD may call a protected procedure in another PD from a protected entry point. However the overall call graph between PDs forms a directed, acyclic graph. It follows that a PD can not call itself, even indirectly. For example, A calls B calls C is valid (subject to the priority constraint), while A calls B calls A is not valid.

+ +

When a protection domain is called, the protected entry point is invoked. The control returns to the caller when the protected entry point returns.

+ +

The caller is blocked until the callee returns. Protected procedures must execute in bounded time. Currently, the caller must trust the callee to conform.

+ +

To call a PP, a PD calls microkit_ppcall passing the channel identifier and a message structure, a message structure is returned from this function.

+
    +
  • To create a message structure, you can use microkit_msginfo microkit_msginfo_new(uint64_t label, uint16_t count). The label is typically used for distinguishing PPCs when a server has multiple services for a client to invoke. In this tutorial it will not be necessary to use the label and it can just be 0. The count will be used and it represents how many arguments (message-registers) are in the PPC.
    • +
  • To set the arguments of a message (message registers), you can use void microkit_mr_set(uint8_t mr, uint64_t value) where mr is the index.
    • +
  • To get arguments from the returned message, you can use uint64_t microkit_mr_get(uint8_t mr) where mr is the index.
    • +
  • To get the label of a message, you can use uint64_t microkit_msginfo_get_label(microkit_msginfo msginfo);.
    • +
+ +

When a PD’s protected procedure is invoked, the protected entry point is invoked with the channel identifier and message structure passed as arguments. The protected entry point must return a message structure.

+ +

Your task now is to:

+
    +
  • Add a Wordle server PD (using the program image wordle_server.elf).
    • +
  • Add the ability to invoke the Wordle server’s protected procedure from the client. This means creating a channel between the two PDs and setting pp="true" on the client end of the channel.
    • +
  • On the client side, implement wordle_server_send to send the user-inputted word from the client to the Wordle server. +
      +
    • Do this using message registers by setting each character of the word from the client to the Wordle server.
      • +
    +
    • +
  • On the Wordle server side, implement the protected entry point microkit_msginfo protected(microkit_channel ch, microkit_msginfo msginfo). +
      +
    • Use the helper functions in wordle_server.c to put the state of each character in the same message-register that the character +was delivered in.
      • +
    +
    • +
+ +

Building

+ +

For building part 3, run the command:

+ +
make part3
+
+ +

Running

+ +

The same command from the previous parts works:

+
make run
+
+ +

Hopefully now you have the table printing with colour output (orange for correct letter wrong position, white for incorrect letter) and are +able to guess the word! If all the letters are green, then you have won.

+ + +
+ +
+
+ + + +
+ +
+
+ + diff --git a/projects/microkit/tutorial/part3.md b/projects/microkit/tutorial/part3.md deleted file mode 100644 index 2d396a4188e..00000000000 --- a/projects/microkit/tutorial/part3.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Microkit Tutorial - Wordle server -nav_prev: part2.html -nav_next: part4.html -SPDX-License-Identifier: CC-BY-NC-SA-4.0 -SPDX-FileCopyrightText: 2025 Ivan Velickovic ---- - -{% include include_external_markdown.md - file="_processed/microkit-tutorial/part3.md" %} diff --git a/projects/microkit/tutorial/part4.html b/projects/microkit/tutorial/part4.html new file mode 100644 index 00000000000..cb0bf3ad562 --- /dev/null +++ b/projects/microkit/tutorial/part4.html @@ -0,0 +1,784 @@ + + + + + + + Microkit Tutorial - Virtual machines | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ +

Part 4 - Virtual machines

+ +

Now that you have a playable Wordle, you will notice that the word to guess +is always “hello” and does not change. That is a bit boring and not realistic.

+ +

The real Wordle game client works by having some server contain the word that +changes every day. What if we could do something similar so that every time we +start the game, we have to guess a new word? One way of doing this would be +talking to some external server that picks a random word which the Wordle server +receives.

+ +

This approach sounds complicated, and from part 1 you will know that in this tutorial we had to implement our own device driver just to be able to output characters to a screen. Talking +to the internet would require an ethernet device driver which is non-trivial to create.

+ +

What if we wanted to have other more complicated systems? We would have to implement a lot +of device drivers. For hardware like USB or Bluetooth, there would be +hundreds of thousands of lines of code we would have to port from Linux or something +else to get working on seL4.

+ +

However, there is a quicker and easier approach. We can run a virtual machine! 1

+ +

In this part, you will be shown how to run a virtual machine running Linux using +Microkit. We will make use of the ethernet driver that already exists in Linux to +talk to a server trustworthy.systems/projects/microkit/tutorial/word that responds with a new five-letter word +on every request.

+ +

If you do wget -qO- trustworthy.systems/projects/microkit/tutorial/word, you should see a new word each time +you run the command.

+ +

Virtual machines on seL4

+ +

Virtual machine with passthrough ethernet diagram

+ +

This diagram shows two main components involved when using virtual machines on top of seL4. Obviously there is a +virtual machine (VM), but there is also a virtual machine monitor (VMM). The VMM is responsible for starting and +managing the VM for its lifetime. As the VM doesn’t necessarily know it is being virtualised and thinks that it +is just running directly on hardware, it will try to perform operations such as memory read/write to regions of +memory we do not want it to. Making these kinds of restrictions is well-suited to a capability system, as we can easily control exactly +what resources the VM has power over.

+ +

In this case we want to give the VM access to the ethernet device, so we map the address of the device into +the VM’s virtual machine. This is typically called “pass-through” because, as you can see from the diagram, the +VM bypasses both the VMM and seL4 when it accesses the device. This is ideal for performance as it means that +the VMM nor seL4 consume any CPU when the VM is accessing the device.

+ +

However, interrupts are still managed through seL4 and the VMM. The reason for this is because we do not want +the virtual machine to be able to mess with any other interrupts in the system, and most hardware architectures +(such as ARM which we are using today) leave this problem up to software.

+ +

Integrating with the Wordle system

+ +

Our goal is to have a Linux virtual machine start that then gets the word from trustworthy.systems/projects/microkit/tutorial/word which +it sends to the VMM for it to give to the Wordle server.

+ +

In Microkit it is possible to describe a VM using the virtual_machine element. It is +very similar to a PD in that it has its own TCB, VSpace and CSpace.

+ +

There are a few pieces in order to create a VMM and VM in the system description, so I have given the description +for you to copy-and-paste into your wordle.system. There are comments to help you understand all the pieces.

+ +
<!--
+    This is what the virtual machine will use as its "RAM".
+    Remember it does not know it is a VM and so it will expect a
+    block of contigious memory as RAM.
+-->
+<memory_region name="guest_ram" size="0x10000000" page_size="0x200_000"
+    phys_addr="0x40000000" />
+<!-- Create a memory region for the ethernet device -->
+<memory_region name="ethernet" size="0x1000" phys_addr="0xa003000" />
+<!--
+    Create a memory region for the GIC CPU interface. This is a device
+    that is virtualised at the hardware-level, unlike other parts
+    of the GIC.
+-->
+<memory_region name="gic_vcpu" size="0x1000" phys_addr="0x8040000" />
+
+<!-- Create a VMM protection domain -->
+<protection_domain name="vmm" priority="101">
+    <program_image path="vmm.elf" />
+    <!--
+        Map in the virtual machine's RAM region as the VMM needs
+        access to it as well for starting and setting up the VM.
+    -->
+    <map mr="guest_ram" vaddr="0x40000000" perms="rw"
+        setvar_vaddr="guest_ram_vaddr" />
+    <!--
+        Create the virtual machine, the vCPU `id` is used for the
+        VMM to refer to the VM. Similar to channels and IRQs.
+    -->
+    <virtual_machine name="linux" priority="100">
+        <vcpu id="0" />
+        <map mr="guest_ram" vaddr="0x40000000" perms="rwx" />
+        <map mr="ethernet" vaddr="0xa003000" perms="rw" cached="false" />
+        <map mr="uart" vaddr="0x9000000" perms="rw" cached="false" />
+        <map mr="gic_vcpu" vaddr="0x8010000" perms="rw" cached="false" />
+    </virtual_machine>
+    <!--
+        We want the VMM to receive the ethernet interrupts, which it
+        will then deliver to the VM.
+     -->
+    <irq irq="79" id="2" trigger="edge" />
+</protection_domain>
+
+ +

Next, let’s try build and run the system to see Linux booting.

+ +

Building

+ +

For building part 4, run the command:

+ +
make part4
+
+ +

Running

+ +

The same command from the previous parts works:

+
make run
+
+ +

When you run the system, you will see a lot more output than the previous parts, most +of this is Linux’s boot logs. At the bottom you should see the following (note that it may take a couple of seconds):

+
Starting network: OK
+udhcpc: started, v1.35.0
+udhcpc: broadcasting discover
+udhcpc: broadcasting select for 10.0.2.15, server 10.0.2.2
+udhcpc: lease of 10.0.2.15 obtained from 10.0.2.2, lease time 86400
+deleting routers
+adding dns 10.0.2.3
+Linux user-space: Send request to trustworthy.systems/projects/microkit/tutorial/word
+Linux user-space: Received word
+Linux user-space: Transfer word to virtual-machine monitor
+vmm microkit_ppcall: invalid channel given '1'
+
+ +

What is happening here? Well after Linux boots it starts the initial task I have added a script that will +automatically run and get the current Wordle word and copy it to the VMM. Surprisingly, it is a very simple +script:

+
#!/bin/sh
+
+# Establish internet connection
+ifconfig eth0 up
+udhcpc eth0
+
+# Request the word
+echo "Linux user-space: Send request to trustworthy.systems/projects/microkit/tutorial/word"
+WORD=$(wget -qO- --no-check-certificate trustworthy.systems/projects/microkit/tutorial/word)
+echo "Linux user-space: Received word"
+
+# Need to go through each letter of the word
+# and then write it to a location that the
+# virtual machine monitor is expecting
+echo "Linux user-space: Transfer word to virtual-machine monitor"
+busybox devmem 0x50000000 b $(printf "%d" "'${WORD:0:1}")
+busybox devmem 0x50000001 b $(printf "%d" "'${WORD:1:2}")
+busybox devmem 0x50000002 b $(printf "%d" "'${WORD:2:3}")
+busybox devmem 0x50000003 b $(printf "%d" "'${WORD:3:4}")
+busybox devmem 0x50000004 b $(printf "%d" "'${WORD:4:5}")
+echo "Linux user-space: Finished"
+
+ +

Once we have the word, we simply transfer it character-by-character to the VMM using a tool that lets us write +to a physical address (physical address from the virtual machine’s point of view). Since the characters are being written to +memory that the VM does not have access to, this will cause a virtual memory fault which seL4 gives to the VMM to handle. +You will notice that this is not particularly efficient, especially if we were doing this process with large amounts of data. +Fortunately, other methods such as the virtIO standard exist. But for this tutorial, that is out of scope.

+ +

If we look at the last line of the output:

+
vmm microkit_ppcall: invalid channel given '1'
+
+ +

What is happening is that the VMM is trying to perform a PPC to send the word to the Wordle server. However, as we do not have a +channel, we are trying to invoke a channel that does not exist!

+ +

We can easily fix this by creating a channel between the VMM and the Wordle server:

+
<channel>
+    <!-- The VMM code expects the channel ID to be 1. -->
+    <end pd="vmm" id="1" pp="true" />
+    <end pd="wordle_server" id="2" />
+</channel>
+
+ +

Finally, we need to add code in wordle_server.c in order to handle the PPC from the VMM. We can look at how the +VMM is transferring the word here:

+
microkit_msginfo msg = microkit_msginfo_new(0, WORDLE_WORD_SIZE);
+for (int i = 0; i < WORDLE_WORD_SIZE; i++) {
+    microkit_mr_set(i, word[i]);
+}
+microkit_ppcall(WORDLE_SERVER_CHANNEL, msg);
+
+ +

It is simply setting each character in one of the message-registers. So in the Wordle server you can read each +message-register using uint64_t microkit_mr_get(uint8_t mr) to update the word array from being equal to “hello” +to our new word.

+ +

After doing that and re-running the system, you should see the message Linux user-space: Transfer word to virtual-machine monitor. +Hit the RETURN key then you should see the client interface printing again. You can now guess the +secret word! If you do not want to guess, you can instead print out the word in the Wordle server :).

+ +
+ +
+
    +
  1. +

    It is not always ideal to use virtual machines. Especially when you care about + performance and reliability, having a native seL4 driver is typically better. ↩

    +
    2. +
+
+ +
+ +
+
+ + + +
+ +
+
+ + diff --git a/projects/microkit/tutorial/part4.md b/projects/microkit/tutorial/part4.md deleted file mode 100644 index 57b842c33c6..00000000000 --- a/projects/microkit/tutorial/part4.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Microkit Tutorial - Virtual machines -nav_prev: part3.html -nav_next: end.html -SPDX-License-Identifier: CC-BY-NC-SA-4.0 -SPDX-FileCopyrightText: 2025 Ivan Velickovic ---- - -{% include include_external_markdown.md - file="_processed/microkit-tutorial/part4.md" %} diff --git a/projects/microkit/tutorial/welcome.html b/projects/microkit/tutorial/welcome.html new file mode 100644 index 00000000000..6ed94c6576a --- /dev/null +++ b/projects/microkit/tutorial/welcome.html @@ -0,0 +1,595 @@ + + + + + + + Microkit Tutorial Welcome | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+ +
+
+
+ +
+ +

Welcome

+ +

Welcome to the tutorial for the seL4 Microkit.

+ +

To complete this tutorial, you will need:

+
    +
  • A laptop or computer with access to the internet.
    • +
  • Some familiarity with operating systems concepts and the C programming language.
    • +
+ +

Getting started

+ +

In this tutorial, you will be completing multiple exercises to end up with a system that +implements the Wordle game. If you are +not familiar with Wordle, it is a simple word guessing game. Through implementing the game, +you will see how systems are constructed on seL4 using Microkit. This Wordle system, while +largely a toy, does represent a realistic architecture as there is:

+
    +
  • a device driver (to allow the user to input a word)
    • +
  • a trusted server (which has the secret word)
    • +
  • an untrusted client (which guesses what the word is based on user input)
    • +
+ +

All of these are isolated components that then communicate via seL4 and Microkit.

+ +

But, before we can start the actual tutorial, you will have to go to part 0 to set up your machine.

+ +

License

+ +

Creative Commons License
This work is created by Ivan Velickovic and licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

+ + +
+ +
+
+ + + +
+ +
+
+ + diff --git a/projects/microkit/tutorial/welcome.md b/projects/microkit/tutorial/welcome.md deleted file mode 100644 index 66361302136..00000000000 --- a/projects/microkit/tutorial/welcome.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Microkit Tutorial Welcome -nav_next: part0.html -SPDX-License-Identifier: CC-BY-NC-SA-4.0 -SPDX-FileCopyrightText: 2025 Ivan Velickovic ---- - -{% include include_external_markdown.md - file="_processed/microkit-tutorial/welcome.md" %} diff --git a/projects/roadmap.html b/projects/roadmap.html new file mode 100644 index 00000000000..6ac01856fa8 --- /dev/null +++ b/projects/roadmap.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/roadmap.md b/projects/roadmap.md deleted file mode 100644 index 0a5ec2b4de0..00000000000 --- a/projects/roadmap.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/roadmap.html ---- diff --git a/projects/rust/.gitignore b/projects/rust/.gitignore deleted file mode 100644 index 0c8db9fc863..00000000000 --- a/projects/rust/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -# Copyright 2025 seL4 Project a Series of LF Projects, LLC. -# SPDX-License-Identifier: BSD-2-Clause - -/tutorial/ diff --git a/projects/rust/how-to-use.html b/projects/rust/how-to-use.html new file mode 100644 index 00000000000..7a8f86019dc --- /dev/null +++ b/projects/rust/how-to-use.html @@ -0,0 +1,600 @@ + + + + + + + Rust: How to Use | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Rust: How to Use

+ +

Using these crates requires a compatible Rust toolchain. See the project’s rust-toolchain.toml for the particular toolchain version that is used for testing. Note that these crates use nightly-only features, so, if you are using a stable toolchain, you must set the environment variable RUSTC_BOOTSTRAP=1.

+ +

These crates are not yet hosted on crates.io. Use them either as Git or path +Cargo dependencies.

+ +

Environment Variables

+ +

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).
    • +
+ +

Language Runtime Crates

+ +

Two language runtime crates, one for root tasks and another for Microkit protection domains, provide runtime elements such as an entry point, thread-local storage, panic handling, a stack, and a heap. See their API docs (linked below) for information on how to use them.

+ +
    +
  • sel4-root-task: A runtime for root tasks that supports thread-local +storage and unwinding, and provides a global allocator. +rustdoc
    • +
  • sel4-microkit: A runtime for seL4 +Microkit protection domains, including an implementation of +libmicrokit and abstractions for IPC. +rustdoc
    • +
+ +

Choosing a --target argument for rustc

+ +

rustc’s baremetal builtin target triples (e.g. aarch64-unknown-none) will suffice, but we provide a collection of custom target specifications that are tuned specifically for use in seL4 userspace, and that cover a range of language runtime configurations. See the source directory that contains them for more information.

+ +

Demos

+ +

These demos provide concrete examples of how to integrate these crates into a seL4-based project:

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/rust/how-to-use.md b/projects/rust/how-to-use.md deleted file mode 100644 index aab2e95ad53..00000000000 --- a/projects/rust/how-to-use.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -repo_link: https://github.com/seL4/rust-sel4/blob/main/ -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Rust: How to Use - -Using these crates requires a compatible Rust toolchain. See the project's [rust-toolchain.toml]({{page.repo_link}}/rust-toolchain.toml) for the particular toolchain version that is used for testing. Note that these crates use nightly-only features, so, if you are using a stable toolchain, you must set the environment variable `RUSTC_BOOTSTRAP=1`. - -These crates are not yet hosted on [crates.io](https://crates.io). Use them either as Git or path -Cargo dependencies. - -## Environment Variables - -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). - -## Language Runtime Crates - -Two language runtime crates, one for root tasks and another for Microkit protection domains, provide runtime elements such as an entry point, thread-local storage, panic handling, a stack, and a heap. See their API docs (linked below) for information on how to use them. - -- [`sel4-root-task`]({{page.repo_link}}/crates/sel4-root-task): A runtime for root tasks that supports thread-local -storage and unwinding, and provides a global allocator. -[rustdoc](https://sel4.github.io/rust-sel4/views/aarch64-root-task/aarch64-sel4/doc/sel4_root_task/index.html) -- [`sel4-microkit`]({{page.repo_link}}/crates/sel4-microkit): A runtime for [seL4 -Microkit](../microkit/) protection domains, including an implementation of -libmicrokit and abstractions for IPC. -[rustdoc](https://sel4.github.io/rust-sel4/views/aarch64-microkit/aarch64-sel4-microkit/doc/sel4_microkit/index.html) - -## Choosing a `--target` argument for `rustc` {#target-spec} - -`rustc`'s baremetal builtin target triples (e.g. `aarch64-unknown-none`) will suffice, but we provide a collection of [custom target specifications](https://doc.rust-lang.org/beta/rustc/targets/custom.html) that are tuned specifically for use in seL4 userspace, and that cover a range of language runtime configurations. See [the source directory that contains them]({{page.repo_link}}/support/targets#readme) for more information. - -## Demos - -These demos provide concrete examples of how to integrate these crates into a seL4-based project: - -- [Simple root task](https://github.com/seL4/rust-root-task-demo) -- [Simple system using the seL4 Microkit](https://github.com/seL4/rust-microkit-demo) -- [HTTP server using the seL4 Microkit](https://github.com/seL4/rust-microkit-http-server-demo) diff --git a/projects/rust/index.html b/projects/rust/index.html new file mode 100644 index 00000000000..36cdd2c8c12 --- /dev/null +++ b/projects/rust/index.html @@ -0,0 +1,699 @@ + + + + + + + Rust | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Rust

+ +

seL4 officially supports the use of Rust in userspace. This support entails:

+ +
    +
  • Rust bindings for the seL4 API (source)
    • +
  • A runtime for root tasks (source)
    • +
  • A runtime for seL4 Microkit protection domains +(source)
    • +
  • Custom rustc target specifications for seL4 userspace (JSON and docs)
    • +
  • Many more crates for use in seL4 userspace (Sources)
    • +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+

+ Tutorial +

+
+ Learn how to use Rust in seL4 userspace. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ API +

+
+ Rustdoc for the crates mantained by the seL4 Foundation. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ How to use +

+
+ How to use the seL4 rust crates. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ Sources +

+
+ Repository for development and collaboration on Rust support in seL4 userspace. +
+
+ Learn more + + +
+
+
+ + +
+ +

The development and maintenance of Rust support for seL4 userspace is funded and +managed by the seL4 Foundation. All of this work happens in one GitHub +repository: seL4/rust-sel4.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/rust/index.md b/projects/rust/index.md deleted file mode 100644 index 7ed2084a774..00000000000 --- a/projects/rust/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -project: rust - -redirect_from: - - /Rust - -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Rust - -seL4 officially supports the use of Rust in userspace. This support entails: - -- Rust bindings for the seL4 API ([source](https://github.com/seL4/rust-sel4/tree/main/crates/sel4)) -- A runtime for root tasks ([source](https://github.com/seL4/rust-sel4/tree/main/crates/sel4-root-task)) -- A runtime for [seL4 Microkit](../microkit) protection domains - ([source](https://github.com/seL4/rust-sel4/tree/main/crates/sel4-microkit)) -- Custom `rustc` target specifications for seL4 userspace ([JSON and docs](https://github.com/seL4/rust-sel4/tree/main/support/targets#readme)) -- Many more crates for use in seL4 userspace ([Sources](https://github.com/seL4/rust-sel4/tree/main/crates/)) - -
- - {% include card.html - icon="arrow-right-end-on-rectangle" - title="Tutorial" - body="Learn how to use Rust in seL4 userspace." - link="/projects/rust/tutorial/introduction.html" - %} - - {% include card.html - icon="document-magnifying-glass" - title="API" - body="Rustdoc for the crates mantained by the seL4 Foundation." - link="https://sel4.github.io/rust-sel4/" - %} - - {% include card.html - icon="document-magnifying-glass" - title="How to use" - body="How to use the seL4 rust crates." - link="/projects/rust/how-to-use.html" - %} - - {% include card.html - icon="other/github" - title="Sources" - body="Repository for development and collaboration on Rust support in seL4 userspace." - link="https://github.com/sel4/rust-sel4" - %} - -
- -The development and maintenance of Rust support for seL4 userspace is funded and -managed by the seL4 Foundation. All of this work happens in one GitHub -repository: [seL4/rust-sel4](https://github.com/sel4/rust-sel4). diff --git a/projects/rust/releases.html b/projects/rust/releases.html new file mode 100644 index 00000000000..d7630c86bb3 --- /dev/null +++ b/projects/rust/releases.html @@ -0,0 +1,567 @@ + + + + + + + Rust: Releases | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Rust: Releases

+ +

For the latest features, along with compatibility with the latest versions of the Rust toolchain, consider using the main branch of the seL4/rust-sel4 repository.

+ +

Releases serve as snapshots of that branch:

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/rust/releases.md b/projects/rust/releases.md deleted file mode 100644 index c5a4d59fb42..00000000000 --- a/projects/rust/releases.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Rust: Releases - -For the latest features, along with compatibility with the latest versions of the Rust toolchain, consider using the `main` branch of the [seL4/rust-sel4](https://github.com/seL4/rust-sel4) repository. - -Releases serve as snapshots of that branch: - -{%- assign releases = site.data.projects.rust.releases %} - -{%- for release in releases reversed -%} -{%- assign kernel_url = '/releases/sel4/' | append: release.kernel_version | - append: '.html' | relative_url %} -{%- assign microkit_url = '/releases/microkit/' | append: release.microkit_version | - append: '.html' | relative_url %} -- Release [rust-sel4 {{ release.version }}]({{ release.url }}) - (compatible with seL4 version [{{ release.kernel_version }}]({{kernel_url}}) - and Microkit version [{{ release.microkit_version }})]({{microkit_url}}) - {% if forloop.first %}**(latest)**{% endif %} - -{%- endfor %} diff --git a/projects/rust/supported-configurations.html b/projects/rust/supported-configurations.html new file mode 100644 index 00000000000..c069e5d0686 --- /dev/null +++ b/projects/rust/supported-configurations.html @@ -0,0 +1,552 @@ + + + + + + + Rust: Supported Configurations | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Rust: Supported Configurations

+ +

The Rust crates maintained by the seL4 Foundation support all configurations (that is, all platforms and combinations of CMake options) that are supported by the kernel itself, except those based on 32-bit x86. The Microkit-related crates support all Microkit configurations.

+ +

See the Choosing a --target argument for rustc section for information about how to target a particular configuration using rustc.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/rust/supported-configurations.md b/projects/rust/supported-configurations.md deleted file mode 100644 index 7e668ce5e4d..00000000000 --- a/projects/rust/supported-configurations.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Rust: Supported Configurations - -The Rust crates maintained by the seL4 Foundation support all configurations (that is, all platforms and combinations of CMake options) that are supported by the kernel itself, except those based on 32-bit x86. The Microkit-related crates support all Microkit configurations. - -See the [Choosing a `--target` argument for `rustc`](./how-to-use.md#target-spec) section for information about how to target a particular configuration using `rustc`. diff --git a/projects/rust/tutorial/.nojekyll b/projects/rust/tutorial/.nojekyll new file mode 100644 index 00000000000..f17311098f5 --- /dev/null +++ b/projects/rust/tutorial/.nojekyll @@ -0,0 +1 @@ +This file makes sure that Github Pages doesn't process mdBook's output. diff --git a/projects/rust/tutorial/404.html b/projects/rust/tutorial/404.html new file mode 100644 index 00000000000..27ed2d9187e --- /dev/null +++ b/projects/rust/tutorial/404.html @@ -0,0 +1,216 @@ + + + + + + Page not found - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

Document not found (404)

+

This URL is invalid, sorry. Please use the navigation bar or search to continue.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/FontAwesome/css/font-awesome.css b/projects/rust/tutorial/FontAwesome/css/font-awesome.css new file mode 100644 index 00000000000..540440ce89f --- /dev/null +++ b/projects/rust/tutorial/FontAwesome/css/font-awesome.css @@ -0,0 +1,4 @@ +/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:'FontAwesome';src:url('../fonts/fontawesome-webfont.eot?v=4.7.0');src:url('../fonts/fontawesome-webfont.eot?#iefix&v=4.7.0') format('embedded-opentype'),url('../fonts/fontawesome-webfont.woff2?v=4.7.0') format('woff2'),url('../fonts/fontawesome-webfont.woff?v=4.7.0') format('woff'),url('../fonts/fontawesome-webfont.ttf?v=4.7.0') format('truetype'),url('../fonts/fontawesome-webfont.svg?v=4.7.0#fontawesomeregular') format('svg');font-weight:normal;font-style:normal}.fa{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571429em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14285714em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14285714em;width:2.14285714em;top:.14285714em;text-align:center}.fa-li.fa-lg{left:-1.85714286em}.fa-border{padding:.2em .25em .15em;border:solid .08em #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa.fa-pull-left{margin-right:.3em}.fa.fa-pull-right{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left{margin-right:.3em}.fa.pull-right{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s infinite linear;animation:fa-spin 2s infinite linear}.fa-pulse{-webkit-animation:fa-spin 1s infinite steps(8);animation:fa-spin 1s infinite steps(8)}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scale(-1, 1);-ms-transform:scale(-1, 1);transform:scale(-1, 1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scale(1, -1);-ms-transform:scale(1, -1);transform:scale(1, -1)}:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270,:root .fa-flip-horizontal,:root .fa-flip-vertical{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:"\f000"}.fa-music:before{content:"\f001"}.fa-search:before{content:"\f002"}.fa-envelope-o:before{content:"\f003"}.fa-heart:before{content:"\f004"}.fa-star:before{content:"\f005"}.fa-star-o:before{content:"\f006"}.fa-user:before{content:"\f007"}.fa-film:before{content:"\f008"}.fa-th-large:before{content:"\f009"}.fa-th:before{content:"\f00a"}.fa-th-list:before{content:"\f00b"}.fa-check:before{content:"\f00c"}.fa-remove:before,.fa-close:before,.fa-times:before{content:"\f00d"}.fa-search-plus:before{content:"\f00e"}.fa-search-minus:before{content:"\f010"}.fa-power-off:before{content:"\f011"}.fa-signal:before{content:"\f012"}.fa-gear:before,.fa-cog:before{content:"\f013"}.fa-trash-o:before{content:"\f014"}.fa-home:before{content:"\f015"}.fa-file-o:before{content:"\f016"}.fa-clock-o:before{content:"\f017"}.fa-road:before{content:"\f018"}.fa-download:before{content:"\f019"}.fa-arrow-circle-o-down:before{content:"\f01a"}.fa-arrow-circle-o-up:before{content:"\f01b"}.fa-inbox:before{content:"\f01c"}.fa-play-circle-o:before{content:"\f01d"}.fa-rotate-right:before,.fa-repeat:before{content:"\f01e"}.fa-refresh:before{content:"\f021"}.fa-list-alt:before{content:"\f022"}.fa-lock:before{content:"\f023"}.fa-flag:before{content:"\f024"}.fa-headphones:before{content:"\f025"}.fa-volume-off:before{content:"\f026"}.fa-volume-down:before{content:"\f027"}.fa-volume-up:before{content:"\f028"}.fa-qrcode:before{content:"\f029"}.fa-barcode:before{content:"\f02a"}.fa-tag:before{content:"\f02b"}.fa-tags:before{content:"\f02c"}.fa-book:before{content:"\f02d"}.fa-bookmark:before{content:"\f02e"}.fa-print:before{content:"\f02f"}.fa-camera:before{content:"\f030"}.fa-font:before{content:"\f031"}.fa-bold:before{content:"\f032"}.fa-italic:before{content:"\f033"}.fa-text-height:before{content:"\f034"}.fa-text-width:before{content:"\f035"}.fa-align-left:before{content:"\f036"}.fa-align-center:before{content:"\f037"}.fa-align-right:before{content:"\f038"}.fa-align-justify:before{content:"\f039"}.fa-list:before{content:"\f03a"}.fa-dedent:before,.fa-outdent:before{content:"\f03b"}.fa-indent:before{content:"\f03c"}.fa-video-camera:before{content:"\f03d"}.fa-photo:before,.fa-image:before,.fa-picture-o:before{content:"\f03e"}.fa-pencil:before{content:"\f040"}.fa-map-marker:before{content:"\f041"}.fa-adjust:before{content:"\f042"}.fa-tint:before{content:"\f043"}.fa-edit:before,.fa-pencil-square-o:before{content:"\f044"}.fa-share-square-o:before{content:"\f045"}.fa-check-square-o:before{content:"\f046"}.fa-arrows:before{content:"\f047"}.fa-step-backward:before{content:"\f048"}.fa-fast-backward:before{content:"\f049"}.fa-backward:before{content:"\f04a"}.fa-play:before{content:"\f04b"}.fa-pause:before{content:"\f04c"}.fa-stop:before{content:"\f04d"}.fa-forward:before{content:"\f04e"}.fa-fast-forward:before{content:"\f050"}.fa-step-forward:before{content:"\f051"}.fa-eject:before{content:"\f052"}.fa-chevron-left:before{content:"\f053"}.fa-chevron-right:before{content:"\f054"}.fa-plus-circle:before{content:"\f055"}.fa-minus-circle:before{content:"\f056"}.fa-times-circle:before{content:"\f057"}.fa-check-circle:before{content:"\f058"}.fa-question-circle:before{content:"\f059"}.fa-info-circle:before{content:"\f05a"}.fa-crosshairs:before{content:"\f05b"}.fa-times-circle-o:before{content:"\f05c"}.fa-check-circle-o:before{content:"\f05d"}.fa-ban:before{content:"\f05e"}.fa-arrow-left:before{content:"\f060"}.fa-arrow-right:before{content:"\f061"}.fa-arrow-up:before{content:"\f062"}.fa-arrow-down:before{content:"\f063"}.fa-mail-forward:before,.fa-share:before{content:"\f064"}.fa-expand:before{content:"\f065"}.fa-compress:before{content:"\f066"}.fa-plus:before{content:"\f067"}.fa-minus:before{content:"\f068"}.fa-asterisk:before{content:"\f069"}.fa-exclamation-circle:before{content:"\f06a"}.fa-gift:before{content:"\f06b"}.fa-leaf:before{content:"\f06c"}.fa-fire:before{content:"\f06d"}.fa-eye:before{content:"\f06e"}.fa-eye-slash:before{content:"\f070"}.fa-warning:before,.fa-exclamation-triangle:before{content:"\f071"}.fa-plane:before{content:"\f072"}.fa-calendar:before{content:"\f073"}.fa-random:before{content:"\f074"}.fa-comment:before{content:"\f075"}.fa-magnet:before{content:"\f076"}.fa-chevron-up:before{content:"\f077"}.fa-chevron-down:before{content:"\f078"}.fa-retweet:before{content:"\f079"}.fa-shopping-cart:before{content:"\f07a"}.fa-folder:before{content:"\f07b"}.fa-folder-open:before{content:"\f07c"}.fa-arrows-v:before{content:"\f07d"}.fa-arrows-h:before{content:"\f07e"}.fa-bar-chart-o:before,.fa-bar-chart:before{content:"\f080"}.fa-twitter-square:before{content:"\f081"}.fa-facebook-square:before{content:"\f082"}.fa-camera-retro:before{content:"\f083"}.fa-key:before{content:"\f084"}.fa-gears:before,.fa-cogs:before{content:"\f085"}.fa-comments:before{content:"\f086"}.fa-thumbs-o-up:before{content:"\f087"}.fa-thumbs-o-down:before{content:"\f088"}.fa-star-half:before{content:"\f089"}.fa-heart-o:before{content:"\f08a"}.fa-sign-out:before{content:"\f08b"}.fa-linkedin-square:before{content:"\f08c"}.fa-thumb-tack:before{content:"\f08d"}.fa-external-link:before{content:"\f08e"}.fa-sign-in:before{content:"\f090"}.fa-trophy:before{content:"\f091"}.fa-github-square:before{content:"\f092"}.fa-upload:before{content:"\f093"}.fa-lemon-o:before{content:"\f094"}.fa-phone:before{content:"\f095"}.fa-square-o:before{content:"\f096"}.fa-bookmark-o:before{content:"\f097"}.fa-phone-square:before{content:"\f098"}.fa-twitter:before{content:"\f099"}.fa-facebook-f:before,.fa-facebook:before{content:"\f09a"}.fa-github:before{content:"\f09b"}.fa-unlock:before{content:"\f09c"}.fa-credit-card:before{content:"\f09d"}.fa-feed:before,.fa-rss:before{content:"\f09e"}.fa-hdd-o:before{content:"\f0a0"}.fa-bullhorn:before{content:"\f0a1"}.fa-bell:before{content:"\f0f3"}.fa-certificate:before{content:"\f0a3"}.fa-hand-o-right:before{content:"\f0a4"}.fa-hand-o-left:before{content:"\f0a5"}.fa-hand-o-up:before{content:"\f0a6"}.fa-hand-o-down:before{content:"\f0a7"}.fa-arrow-circle-left:before{content:"\f0a8"}.fa-arrow-circle-right:before{content:"\f0a9"}.fa-arrow-circle-up:before{content:"\f0aa"}.fa-arrow-circle-down:before{content:"\f0ab"}.fa-globe:before{content:"\f0ac"}.fa-wrench:before{content:"\f0ad"}.fa-tasks:before{content:"\f0ae"}.fa-filter:before{content:"\f0b0"}.fa-briefcase:before{content:"\f0b1"}.fa-arrows-alt:before{content:"\f0b2"}.fa-group:before,.fa-users:before{content:"\f0c0"}.fa-chain:before,.fa-link:before{content:"\f0c1"}.fa-cloud:before{content:"\f0c2"}.fa-flask:before{content:"\f0c3"}.fa-cut:before,.fa-scissors:before{content:"\f0c4"}.fa-copy:before,.fa-files-o:before{content:"\f0c5"}.fa-paperclip:before{content:"\f0c6"}.fa-save:before,.fa-floppy-o:before{content:"\f0c7"}.fa-square:before{content:"\f0c8"}.fa-navicon:before,.fa-reorder:before,.fa-bars:before{content:"\f0c9"}.fa-list-ul:before{content:"\f0ca"}.fa-list-ol:before{content:"\f0cb"}.fa-strikethrough:before{content:"\f0cc"}.fa-underline:before{content:"\f0cd"}.fa-table:before{content:"\f0ce"}.fa-magic:before{content:"\f0d0"}.fa-truck:before{content:"\f0d1"}.fa-pinterest:before{content:"\f0d2"}.fa-pinterest-square:before{content:"\f0d3"}.fa-google-plus-square:before{content:"\f0d4"}.fa-google-plus:before{content:"\f0d5"}.fa-money:before{content:"\f0d6"}.fa-caret-down:before{content:"\f0d7"}.fa-caret-up:before{content:"\f0d8"}.fa-caret-left:before{content:"\f0d9"}.fa-caret-right:before{content:"\f0da"}.fa-columns:before{content:"\f0db"}.fa-unsorted:before,.fa-sort:before{content:"\f0dc"}.fa-sort-down:before,.fa-sort-desc:before{content:"\f0dd"}.fa-sort-up:before,.fa-sort-asc:before{content:"\f0de"}.fa-envelope:before{content:"\f0e0"}.fa-linkedin:before{content:"\f0e1"}.fa-rotate-left:before,.fa-undo:before{content:"\f0e2"}.fa-legal:before,.fa-gavel:before{content:"\f0e3"}.fa-dashboard:before,.fa-tachometer:before{content:"\f0e4"}.fa-comment-o:before{content:"\f0e5"}.fa-comments-o:before{content:"\f0e6"}.fa-flash:before,.fa-bolt:before{content:"\f0e7"}.fa-sitemap:before{content:"\f0e8"}.fa-umbrella:before{content:"\f0e9"}.fa-paste:before,.fa-clipboard:before{content:"\f0ea"}.fa-lightbulb-o:before{content:"\f0eb"}.fa-exchange:before{content:"\f0ec"}.fa-cloud-download:before{content:"\f0ed"}.fa-cloud-upload:before{content:"\f0ee"}.fa-user-md:before{content:"\f0f0"}.fa-stethoscope:before{content:"\f0f1"}.fa-suitcase:before{content:"\f0f2"}.fa-bell-o:before{content:"\f0a2"}.fa-coffee:before{content:"\f0f4"}.fa-cutlery:before{content:"\f0f5"}.fa-file-text-o:before{content:"\f0f6"}.fa-building-o:before{content:"\f0f7"}.fa-hospital-o:before{content:"\f0f8"}.fa-ambulance:before{content:"\f0f9"}.fa-medkit:before{content:"\f0fa"}.fa-fighter-jet:before{content:"\f0fb"}.fa-beer:before{content:"\f0fc"}.fa-h-square:before{content:"\f0fd"}.fa-plus-square:before{content:"\f0fe"}.fa-angle-double-left:before{content:"\f100"}.fa-angle-double-right:before{content:"\f101"}.fa-angle-double-up:before{content:"\f102"}.fa-angle-double-down:before{content:"\f103"}.fa-angle-left:before{content:"\f104"}.fa-angle-right:before{content:"\f105"}.fa-angle-up:before{content:"\f106"}.fa-angle-down:before{content:"\f107"}.fa-desktop:before{content:"\f108"}.fa-laptop:before{content:"\f109"}.fa-tablet:before{content:"\f10a"}.fa-mobile-phone:before,.fa-mobile:before{content:"\f10b"}.fa-circle-o:before{content:"\f10c"}.fa-quote-left:before{content:"\f10d"}.fa-quote-right:before{content:"\f10e"}.fa-spinner:before{content:"\f110"}.fa-circle:before{content:"\f111"}.fa-mail-reply:before,.fa-reply:before{content:"\f112"}.fa-github-alt:before{content:"\f113"}.fa-folder-o:before{content:"\f114"}.fa-folder-open-o:before{content:"\f115"}.fa-smile-o:before{content:"\f118"}.fa-frown-o:before{content:"\f119"}.fa-meh-o:before{content:"\f11a"}.fa-gamepad:before{content:"\f11b"}.fa-keyboard-o:before{content:"\f11c"}.fa-flag-o:before{content:"\f11d"}.fa-flag-checkered:before{content:"\f11e"}.fa-terminal:before{content:"\f120"}.fa-code:before{content:"\f121"}.fa-mail-reply-all:before,.fa-reply-all:before{content:"\f122"}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:"\f123"}.fa-location-arrow:before{content:"\f124"}.fa-crop:before{content:"\f125"}.fa-code-fork:before{content:"\f126"}.fa-unlink:before,.fa-chain-broken:before{content:"\f127"}.fa-question:before{content:"\f128"}.fa-info:before{content:"\f129"}.fa-exclamation:before{content:"\f12a"}.fa-superscript:before{content:"\f12b"}.fa-subscript:before{content:"\f12c"}.fa-eraser:before{content:"\f12d"}.fa-puzzle-piece:before{content:"\f12e"}.fa-microphone:before{content:"\f130"}.fa-microphone-slash:before{content:"\f131"}.fa-shield:before{content:"\f132"}.fa-calendar-o:before{content:"\f133"}.fa-fire-extinguisher:before{content:"\f134"}.fa-rocket:before{content:"\f135"}.fa-maxcdn:before{content:"\f136"}.fa-chevron-circle-left:before{content:"\f137"}.fa-chevron-circle-right:before{content:"\f138"}.fa-chevron-circle-up:before{content:"\f139"}.fa-chevron-circle-down:before{content:"\f13a"}.fa-html5:before{content:"\f13b"}.fa-css3:before{content:"\f13c"}.fa-anchor:before{content:"\f13d"}.fa-unlock-alt:before{content:"\f13e"}.fa-bullseye:before{content:"\f140"}.fa-ellipsis-h:before{content:"\f141"}.fa-ellipsis-v:before{content:"\f142"}.fa-rss-square:before{content:"\f143"}.fa-play-circle:before{content:"\f144"}.fa-ticket:before{content:"\f145"}.fa-minus-square:before{content:"\f146"}.fa-minus-square-o:before{content:"\f147"}.fa-level-up:before{content:"\f148"}.fa-level-down:before{content:"\f149"}.fa-check-square:before{content:"\f14a"}.fa-pencil-square:before{content:"\f14b"}.fa-external-link-square:before{content:"\f14c"}.fa-share-square:before{content:"\f14d"}.fa-compass:before{content:"\f14e"}.fa-toggle-down:before,.fa-caret-square-o-down:before{content:"\f150"}.fa-toggle-up:before,.fa-caret-square-o-up:before{content:"\f151"}.fa-toggle-right:before,.fa-caret-square-o-right:before{content:"\f152"}.fa-euro:before,.fa-eur:before{content:"\f153"}.fa-gbp:before{content:"\f154"}.fa-dollar:before,.fa-usd:before{content:"\f155"}.fa-rupee:before,.fa-inr:before{content:"\f156"}.fa-cny:before,.fa-rmb:before,.fa-yen:before,.fa-jpy:before{content:"\f157"}.fa-ruble:before,.fa-rouble:before,.fa-rub:before{content:"\f158"}.fa-won:before,.fa-krw:before{content:"\f159"}.fa-bitcoin:before,.fa-btc:before{content:"\f15a"}.fa-file:before{content:"\f15b"}.fa-file-text:before{content:"\f15c"}.fa-sort-alpha-asc:before{content:"\f15d"}.fa-sort-alpha-desc:before{content:"\f15e"}.fa-sort-amount-asc:before{content:"\f160"}.fa-sort-amount-desc:before{content:"\f161"}.fa-sort-numeric-asc:before{content:"\f162"}.fa-sort-numeric-desc:before{content:"\f163"}.fa-thumbs-up:before{content:"\f164"}.fa-thumbs-down:before{content:"\f165"}.fa-youtube-square:before{content:"\f166"}.fa-youtube:before{content:"\f167"}.fa-xing:before{content:"\f168"}.fa-xing-square:before{content:"\f169"}.fa-youtube-play:before{content:"\f16a"}.fa-dropbox:before{content:"\f16b"}.fa-stack-overflow:before{content:"\f16c"}.fa-instagram:before{content:"\f16d"}.fa-flickr:before{content:"\f16e"}.fa-adn:before{content:"\f170"}.fa-bitbucket:before{content:"\f171"}.fa-bitbucket-square:before{content:"\f172"}.fa-tumblr:before{content:"\f173"}.fa-tumblr-square:before{content:"\f174"}.fa-long-arrow-down:before{content:"\f175"}.fa-long-arrow-up:before{content:"\f176"}.fa-long-arrow-left:before{content:"\f177"}.fa-long-arrow-right:before{content:"\f178"}.fa-apple:before{content:"\f179"}.fa-windows:before{content:"\f17a"}.fa-android:before{content:"\f17b"}.fa-linux:before{content:"\f17c"}.fa-dribbble:before{content:"\f17d"}.fa-skype:before{content:"\f17e"}.fa-foursquare:before{content:"\f180"}.fa-trello:before{content:"\f181"}.fa-female:before{content:"\f182"}.fa-male:before{content:"\f183"}.fa-gittip:before,.fa-gratipay:before{content:"\f184"}.fa-sun-o:before{content:"\f185"}.fa-moon-o:before{content:"\f186"}.fa-archive:before{content:"\f187"}.fa-bug:before{content:"\f188"}.fa-vk:before{content:"\f189"}.fa-weibo:before{content:"\f18a"}.fa-renren:before{content:"\f18b"}.fa-pagelines:before{content:"\f18c"}.fa-stack-exchange:before{content:"\f18d"}.fa-arrow-circle-o-right:before{content:"\f18e"}.fa-arrow-circle-o-left:before{content:"\f190"}.fa-toggle-left:before,.fa-caret-square-o-left:before{content:"\f191"}.fa-dot-circle-o:before{content:"\f192"}.fa-wheelchair:before{content:"\f193"}.fa-vimeo-square:before{content:"\f194"}.fa-turkish-lira:before,.fa-try:before{content:"\f195"}.fa-plus-square-o:before{content:"\f196"}.fa-space-shuttle:before{content:"\f197"}.fa-slack:before{content:"\f198"}.fa-envelope-square:before{content:"\f199"}.fa-wordpress:before{content:"\f19a"}.fa-openid:before{content:"\f19b"}.fa-institution:before,.fa-bank:before,.fa-university:before{content:"\f19c"}.fa-mortar-board:before,.fa-graduation-cap:before{content:"\f19d"}.fa-yahoo:before{content:"\f19e"}.fa-google:before{content:"\f1a0"}.fa-reddit:before{content:"\f1a1"}.fa-reddit-square:before{content:"\f1a2"}.fa-stumbleupon-circle:before{content:"\f1a3"}.fa-stumbleupon:before{content:"\f1a4"}.fa-delicious:before{content:"\f1a5"}.fa-digg:before{content:"\f1a6"}.fa-pied-piper-pp:before{content:"\f1a7"}.fa-pied-piper-alt:before{content:"\f1a8"}.fa-drupal:before{content:"\f1a9"}.fa-joomla:before{content:"\f1aa"}.fa-language:before{content:"\f1ab"}.fa-fax:before{content:"\f1ac"}.fa-building:before{content:"\f1ad"}.fa-child:before{content:"\f1ae"}.fa-paw:before{content:"\f1b0"}.fa-spoon:before{content:"\f1b1"}.fa-cube:before{content:"\f1b2"}.fa-cubes:before{content:"\f1b3"}.fa-behance:before{content:"\f1b4"}.fa-behance-square:before{content:"\f1b5"}.fa-steam:before{content:"\f1b6"}.fa-steam-square:before{content:"\f1b7"}.fa-recycle:before{content:"\f1b8"}.fa-automobile:before,.fa-car:before{content:"\f1b9"}.fa-cab:before,.fa-taxi:before{content:"\f1ba"}.fa-tree:before{content:"\f1bb"}.fa-spotify:before{content:"\f1bc"}.fa-deviantart:before{content:"\f1bd"}.fa-soundcloud:before{content:"\f1be"}.fa-database:before{content:"\f1c0"}.fa-file-pdf-o:before{content:"\f1c1"}.fa-file-word-o:before{content:"\f1c2"}.fa-file-excel-o:before{content:"\f1c3"}.fa-file-powerpoint-o:before{content:"\f1c4"}.fa-file-photo-o:before,.fa-file-picture-o:before,.fa-file-image-o:before{content:"\f1c5"}.fa-file-zip-o:before,.fa-file-archive-o:before{content:"\f1c6"}.fa-file-sound-o:before,.fa-file-audio-o:before{content:"\f1c7"}.fa-file-movie-o:before,.fa-file-video-o:before{content:"\f1c8"}.fa-file-code-o:before{content:"\f1c9"}.fa-vine:before{content:"\f1ca"}.fa-codepen:before{content:"\f1cb"}.fa-jsfiddle:before{content:"\f1cc"}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-saver:before,.fa-support:before,.fa-life-ring:before{content:"\f1cd"}.fa-circle-o-notch:before{content:"\f1ce"}.fa-ra:before,.fa-resistance:before,.fa-rebel:before{content:"\f1d0"}.fa-ge:before,.fa-empire:before{content:"\f1d1"}.fa-git-square:before{content:"\f1d2"}.fa-git:before{content:"\f1d3"}.fa-y-combinator-square:before,.fa-yc-square:before,.fa-hacker-news:before{content:"\f1d4"}.fa-tencent-weibo:before{content:"\f1d5"}.fa-qq:before{content:"\f1d6"}.fa-wechat:before,.fa-weixin:before{content:"\f1d7"}.fa-send:before,.fa-paper-plane:before{content:"\f1d8"}.fa-send-o:before,.fa-paper-plane-o:before{content:"\f1d9"}.fa-history:before{content:"\f1da"}.fa-circle-thin:before{content:"\f1db"}.fa-header:before{content:"\f1dc"}.fa-paragraph:before{content:"\f1dd"}.fa-sliders:before{content:"\f1de"}.fa-share-alt:before{content:"\f1e0"}.fa-share-alt-square:before{content:"\f1e1"}.fa-bomb:before{content:"\f1e2"}.fa-soccer-ball-o:before,.fa-futbol-o:before{content:"\f1e3"}.fa-tty:before{content:"\f1e4"}.fa-binoculars:before{content:"\f1e5"}.fa-plug:before{content:"\f1e6"}.fa-slideshare:before{content:"\f1e7"}.fa-twitch:before{content:"\f1e8"}.fa-yelp:before{content:"\f1e9"}.fa-newspaper-o:before{content:"\f1ea"}.fa-wifi:before{content:"\f1eb"}.fa-calculator:before{content:"\f1ec"}.fa-paypal:before{content:"\f1ed"}.fa-google-wallet:before{content:"\f1ee"}.fa-cc-visa:before{content:"\f1f0"}.fa-cc-mastercard:before{content:"\f1f1"}.fa-cc-discover:before{content:"\f1f2"}.fa-cc-amex:before{content:"\f1f3"}.fa-cc-paypal:before{content:"\f1f4"}.fa-cc-stripe:before{content:"\f1f5"}.fa-bell-slash:before{content:"\f1f6"}.fa-bell-slash-o:before{content:"\f1f7"}.fa-trash:before{content:"\f1f8"}.fa-copyright:before{content:"\f1f9"}.fa-at:before{content:"\f1fa"}.fa-eyedropper:before{content:"\f1fb"}.fa-paint-brush:before{content:"\f1fc"}.fa-birthday-cake:before{content:"\f1fd"}.fa-area-chart:before{content:"\f1fe"}.fa-pie-chart:before{content:"\f200"}.fa-line-chart:before{content:"\f201"}.fa-lastfm:before{content:"\f202"}.fa-lastfm-square:before{content:"\f203"}.fa-toggle-off:before{content:"\f204"}.fa-toggle-on:before{content:"\f205"}.fa-bicycle:before{content:"\f206"}.fa-bus:before{content:"\f207"}.fa-ioxhost:before{content:"\f208"}.fa-angellist:before{content:"\f209"}.fa-cc:before{content:"\f20a"}.fa-shekel:before,.fa-sheqel:before,.fa-ils:before{content:"\f20b"}.fa-meanpath:before{content:"\f20c"}.fa-buysellads:before{content:"\f20d"}.fa-connectdevelop:before{content:"\f20e"}.fa-dashcube:before{content:"\f210"}.fa-forumbee:before{content:"\f211"}.fa-leanpub:before{content:"\f212"}.fa-sellsy:before{content:"\f213"}.fa-shirtsinbulk:before{content:"\f214"}.fa-simplybuilt:before{content:"\f215"}.fa-skyatlas:before{content:"\f216"}.fa-cart-plus:before{content:"\f217"}.fa-cart-arrow-down:before{content:"\f218"}.fa-diamond:before{content:"\f219"}.fa-ship:before{content:"\f21a"}.fa-user-secret:before{content:"\f21b"}.fa-motorcycle:before{content:"\f21c"}.fa-street-view:before{content:"\f21d"}.fa-heartbeat:before{content:"\f21e"}.fa-venus:before{content:"\f221"}.fa-mars:before{content:"\f222"}.fa-mercury:before{content:"\f223"}.fa-intersex:before,.fa-transgender:before{content:"\f224"}.fa-transgender-alt:before{content:"\f225"}.fa-venus-double:before{content:"\f226"}.fa-mars-double:before{content:"\f227"}.fa-venus-mars:before{content:"\f228"}.fa-mars-stroke:before{content:"\f229"}.fa-mars-stroke-v:before{content:"\f22a"}.fa-mars-stroke-h:before{content:"\f22b"}.fa-neuter:before{content:"\f22c"}.fa-genderless:before{content:"\f22d"}.fa-facebook-official:before{content:"\f230"}.fa-pinterest-p:before{content:"\f231"}.fa-whatsapp:before{content:"\f232"}.fa-server:before{content:"\f233"}.fa-user-plus:before{content:"\f234"}.fa-user-times:before{content:"\f235"}.fa-hotel:before,.fa-bed:before{content:"\f236"}.fa-viacoin:before{content:"\f237"}.fa-train:before{content:"\f238"}.fa-subway:before{content:"\f239"}.fa-medium:before{content:"\f23a"}.fa-yc:before,.fa-y-combinator:before{content:"\f23b"}.fa-optin-monster:before{content:"\f23c"}.fa-opencart:before{content:"\f23d"}.fa-expeditedssl:before{content:"\f23e"}.fa-battery-4:before,.fa-battery:before,.fa-battery-full:before{content:"\f240"}.fa-battery-3:before,.fa-battery-three-quarters:before{content:"\f241"}.fa-battery-2:before,.fa-battery-half:before{content:"\f242"}.fa-battery-1:before,.fa-battery-quarter:before{content:"\f243"}.fa-battery-0:before,.fa-battery-empty:before{content:"\f244"}.fa-mouse-pointer:before{content:"\f245"}.fa-i-cursor:before{content:"\f246"}.fa-object-group:before{content:"\f247"}.fa-object-ungroup:before{content:"\f248"}.fa-sticky-note:before{content:"\f249"}.fa-sticky-note-o:before{content:"\f24a"}.fa-cc-jcb:before{content:"\f24b"}.fa-cc-diners-club:before{content:"\f24c"}.fa-clone:before{content:"\f24d"}.fa-balance-scale:before{content:"\f24e"}.fa-hourglass-o:before{content:"\f250"}.fa-hourglass-1:before,.fa-hourglass-start:before{content:"\f251"}.fa-hourglass-2:before,.fa-hourglass-half:before{content:"\f252"}.fa-hourglass-3:before,.fa-hourglass-end:before{content:"\f253"}.fa-hourglass:before{content:"\f254"}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:"\f255"}.fa-hand-stop-o:before,.fa-hand-paper-o:before{content:"\f256"}.fa-hand-scissors-o:before{content:"\f257"}.fa-hand-lizard-o:before{content:"\f258"}.fa-hand-spock-o:before{content:"\f259"}.fa-hand-pointer-o:before{content:"\f25a"}.fa-hand-peace-o:before{content:"\f25b"}.fa-trademark:before{content:"\f25c"}.fa-registered:before{content:"\f25d"}.fa-creative-commons:before{content:"\f25e"}.fa-gg:before{content:"\f260"}.fa-gg-circle:before{content:"\f261"}.fa-tripadvisor:before{content:"\f262"}.fa-odnoklassniki:before{content:"\f263"}.fa-odnoklassniki-square:before{content:"\f264"}.fa-get-pocket:before{content:"\f265"}.fa-wikipedia-w:before{content:"\f266"}.fa-safari:before{content:"\f267"}.fa-chrome:before{content:"\f268"}.fa-firefox:before{content:"\f269"}.fa-opera:before{content:"\f26a"}.fa-internet-explorer:before{content:"\f26b"}.fa-tv:before,.fa-television:before{content:"\f26c"}.fa-contao:before{content:"\f26d"}.fa-500px:before{content:"\f26e"}.fa-amazon:before{content:"\f270"}.fa-calendar-plus-o:before{content:"\f271"}.fa-calendar-minus-o:before{content:"\f272"}.fa-calendar-times-o:before{content:"\f273"}.fa-calendar-check-o:before{content:"\f274"}.fa-industry:before{content:"\f275"}.fa-map-pin:before{content:"\f276"}.fa-map-signs:before{content:"\f277"}.fa-map-o:before{content:"\f278"}.fa-map:before{content:"\f279"}.fa-commenting:before{content:"\f27a"}.fa-commenting-o:before{content:"\f27b"}.fa-houzz:before{content:"\f27c"}.fa-vimeo:before{content:"\f27d"}.fa-black-tie:before{content:"\f27e"}.fa-fonticons:before{content:"\f280"}.fa-reddit-alien:before{content:"\f281"}.fa-edge:before{content:"\f282"}.fa-credit-card-alt:before{content:"\f283"}.fa-codiepie:before{content:"\f284"}.fa-modx:before{content:"\f285"}.fa-fort-awesome:before{content:"\f286"}.fa-usb:before{content:"\f287"}.fa-product-hunt:before{content:"\f288"}.fa-mixcloud:before{content:"\f289"}.fa-scribd:before{content:"\f28a"}.fa-pause-circle:before{content:"\f28b"}.fa-pause-circle-o:before{content:"\f28c"}.fa-stop-circle:before{content:"\f28d"}.fa-stop-circle-o:before{content:"\f28e"}.fa-shopping-bag:before{content:"\f290"}.fa-shopping-basket:before{content:"\f291"}.fa-hashtag:before{content:"\f292"}.fa-bluetooth:before{content:"\f293"}.fa-bluetooth-b:before{content:"\f294"}.fa-percent:before{content:"\f295"}.fa-gitlab:before{content:"\f296"}.fa-wpbeginner:before{content:"\f297"}.fa-wpforms:before{content:"\f298"}.fa-envira:before{content:"\f299"}.fa-universal-access:before{content:"\f29a"}.fa-wheelchair-alt:before{content:"\f29b"}.fa-question-circle-o:before{content:"\f29c"}.fa-blind:before{content:"\f29d"}.fa-audio-description:before{content:"\f29e"}.fa-volume-control-phone:before{content:"\f2a0"}.fa-braille:before{content:"\f2a1"}.fa-assistive-listening-systems:before{content:"\f2a2"}.fa-asl-interpreting:before,.fa-american-sign-language-interpreting:before{content:"\f2a3"}.fa-deafness:before,.fa-hard-of-hearing:before,.fa-deaf:before{content:"\f2a4"}.fa-glide:before{content:"\f2a5"}.fa-glide-g:before{content:"\f2a6"}.fa-signing:before,.fa-sign-language:before{content:"\f2a7"}.fa-low-vision:before{content:"\f2a8"}.fa-viadeo:before{content:"\f2a9"}.fa-viadeo-square:before{content:"\f2aa"}.fa-snapchat:before{content:"\f2ab"}.fa-snapchat-ghost:before{content:"\f2ac"}.fa-snapchat-square:before{content:"\f2ad"}.fa-pied-piper:before{content:"\f2ae"}.fa-first-order:before{content:"\f2b0"}.fa-yoast:before{content:"\f2b1"}.fa-themeisle:before{content:"\f2b2"}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:"\f2b3"}.fa-fa:before,.fa-font-awesome:before{content:"\f2b4"}.fa-handshake-o:before{content:"\f2b5"}.fa-envelope-open:before{content:"\f2b6"}.fa-envelope-open-o:before{content:"\f2b7"}.fa-linode:before{content:"\f2b8"}.fa-address-book:before{content:"\f2b9"}.fa-address-book-o:before{content:"\f2ba"}.fa-vcard:before,.fa-address-card:before{content:"\f2bb"}.fa-vcard-o:before,.fa-address-card-o:before{content:"\f2bc"}.fa-user-circle:before{content:"\f2bd"}.fa-user-circle-o:before{content:"\f2be"}.fa-user-o:before{content:"\f2c0"}.fa-id-badge:before{content:"\f2c1"}.fa-drivers-license:before,.fa-id-card:before{content:"\f2c2"}.fa-drivers-license-o:before,.fa-id-card-o:before{content:"\f2c3"}.fa-quora:before{content:"\f2c4"}.fa-free-code-camp:before{content:"\f2c5"}.fa-telegram:before{content:"\f2c6"}.fa-thermometer-4:before,.fa-thermometer:before,.fa-thermometer-full:before{content:"\f2c7"}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:"\f2c8"}.fa-thermometer-2:before,.fa-thermometer-half:before{content:"\f2c9"}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:"\f2ca"}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:"\f2cb"}.fa-shower:before{content:"\f2cc"}.fa-bathtub:before,.fa-s15:before,.fa-bath:before{content:"\f2cd"}.fa-podcast:before{content:"\f2ce"}.fa-window-maximize:before{content:"\f2d0"}.fa-window-minimize:before{content:"\f2d1"}.fa-window-restore:before{content:"\f2d2"}.fa-times-rectangle:before,.fa-window-close:before{content:"\f2d3"}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:"\f2d4"}.fa-bandcamp:before{content:"\f2d5"}.fa-grav:before{content:"\f2d6"}.fa-etsy:before{content:"\f2d7"}.fa-imdb:before{content:"\f2d8"}.fa-ravelry:before{content:"\f2d9"}.fa-eercast:before{content:"\f2da"}.fa-microchip:before{content:"\f2db"}.fa-snowflake-o:before{content:"\f2dc"}.fa-superpowers:before{content:"\f2dd"}.fa-wpexplorer:before{content:"\f2de"}.fa-meetup:before{content:"\f2e0"}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto} diff --git a/projects/rust/tutorial/FontAwesome/fonts/FontAwesome.ttf b/projects/rust/tutorial/FontAwesome/fonts/FontAwesome.ttf new file mode 100644 index 00000000000..35acda2fa11 Binary files /dev/null and b/projects/rust/tutorial/FontAwesome/fonts/FontAwesome.ttf differ diff --git a/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.eot b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000000..e9f60ca953f Binary files /dev/null and b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.eot differ diff --git a/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.svg b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000000..855c845e538 --- /dev/null +++ b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.ttf b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000000..35acda2fa11 Binary files /dev/null and b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.ttf differ diff --git a/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.woff b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000000..400014a4b06 Binary files /dev/null and b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.woff differ diff --git a/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.woff2 b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000000..4d13fc60404 Binary files /dev/null and b/projects/rust/tutorial/FontAwesome/fonts/fontawesome-webfont.woff2 differ diff --git a/projects/rust/tutorial/assets/sel4-rust-tutorial.css b/projects/rust/tutorial/assets/sel4-rust-tutorial.css new file mode 100644 index 00000000000..bcbbbbc97b5 --- /dev/null +++ b/projects/rust/tutorial/assets/sel4-rust-tutorial.css @@ -0,0 +1,47 @@ +/* + * Copyright 2024, Colias Group, LLC + * + * SPDX-License-Identifier: BSD-2-Clause + * + */ + +.fragment-with-gh-link > .fragment-with-gh-link-link > pre > code { + background-color: color-mix(in srgb, var(--bg), #777 20%); + padding-top: .5rem; + padding-bottom: .5rem; + /* text-align: right; */ +} + +.fragment-with-gh-link > .fragment-with-gh-link-link > pre { + margin-bottom: 0; + /* margin-top: 0; */ +} + +.fragment-with-gh-link > .fragment-with-gh-link-fragment > pre { + margin-top: 0; + /* margin-bottom: 0; */ +} + +div.step-hint { + padding: 8px; + border-width: 1px; + border-color: var(--icons); + border-style: solid; + /* border-color: rgba(0, 0, 0, 0.5);; */ + /* background-color: rgba(0, 0, 0, 0.025); */ + /* background-color: rgba(0, 0, 0, 0.08); */ + /* background-color: var(--sidebar-bg); */ +} + +div.step-hint p:last-child { + margin-bottom: 0; +} + +a.step-heading-clickable, a.step-heading-clickable:link { + text-decoration: none !important;; + color: inherit; +} + +.step-heading-clickable:hover { + background-color: var(--theme-hover); +} diff --git a/projects/rust/tutorial/assets/sel4-rust-tutorial.js b/projects/rust/tutorial/assets/sel4-rust-tutorial.js new file mode 100644 index 00000000000..0effaed55c9 --- /dev/null +++ b/projects/rust/tutorial/assets/sel4-rust-tutorial.js @@ -0,0 +1,6 @@ +/* + * Copyright 2024, Colias Group, LLC + * + * SPDX-License-Identifier: BSD-2-Clause + * + */ diff --git a/projects/rust/tutorial/ayu-highlight.css b/projects/rust/tutorial/ayu-highlight.css new file mode 100644 index 00000000000..32c9432224b --- /dev/null +++ b/projects/rust/tutorial/ayu-highlight.css @@ -0,0 +1,78 @@ +/* +Based off of the Ayu theme +Original by Dempfi (https://github.com/dempfi/ayu) +*/ + +.hljs { + display: block; + overflow-x: auto; + background: #191f26; + color: #e6e1cf; +} + +.hljs-comment, +.hljs-quote { + color: #5c6773; + font-style: italic; +} + +.hljs-variable, +.hljs-template-variable, +.hljs-attribute, +.hljs-attr, +.hljs-regexp, +.hljs-link, +.hljs-selector-id, +.hljs-selector-class { + color: #ff7733; +} + +.hljs-number, +.hljs-meta, +.hljs-builtin-name, +.hljs-literal, +.hljs-type, +.hljs-params { + color: #ffee99; +} + +.hljs-string, +.hljs-bullet { + color: #b8cc52; +} + +.hljs-title, +.hljs-built_in, +.hljs-section { + color: #ffb454; +} + +.hljs-keyword, +.hljs-selector-tag, +.hljs-symbol { + color: #ff7733; +} + +.hljs-name { + color: #36a3d9; +} + +.hljs-tag { + color: #00568d; +} + +.hljs-emphasis { + font-style: italic; +} + +.hljs-strong { + font-weight: bold; +} + +.hljs-addition { + color: #91b362; +} + +.hljs-deletion { + color: #d96c75; +} diff --git a/projects/rust/tutorial/book.js b/projects/rust/tutorial/book.js new file mode 100644 index 00000000000..5df2096f7ce --- /dev/null +++ b/projects/rust/tutorial/book.js @@ -0,0 +1,818 @@ +'use strict'; + +/* global default_theme, default_dark_theme, default_light_theme, hljs, ClipboardJS */ + +// Fix back button cache problem +window.onunload = function() { }; + +// Global variable, shared between modules +function playground_text(playground, hidden = true) { + const code_block = playground.querySelector('code'); + + if (window.ace && code_block.classList.contains('editable')) { + const editor = window.ace.edit(code_block); + return editor.getValue(); + } else if (hidden) { + return code_block.textContent; + } else { + return code_block.innerText; + } +} + +(function codeSnippets() { + function fetch_with_timeout(url, options, timeout = 6000) { + return Promise.race([ + fetch(url, options), + new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout)), + ]); + } + + const playgrounds = Array.from(document.querySelectorAll('.playground')); + if (playgrounds.length > 0) { + fetch_with_timeout('https://play.rust-lang.org/meta/crates', { + headers: { + 'Content-Type': 'application/json', + }, + method: 'POST', + mode: 'cors', + }) + .then(response => response.json()) + .then(response => { + // get list of crates available in the rust playground + const playground_crates = response.crates.map(item => item['id']); + playgrounds.forEach(block => handle_crate_list_update(block, playground_crates)); + }); + } + + function handle_crate_list_update(playground_block, playground_crates) { + // update the play buttons after receiving the response + update_play_button(playground_block, playground_crates); + + // and install on change listener to dynamically update ACE editors + if (window.ace) { + const code_block = playground_block.querySelector('code'); + if (code_block.classList.contains('editable')) { + const editor = window.ace.edit(code_block); + editor.addEventListener('change', () => { + update_play_button(playground_block, playground_crates); + }); + // add Ctrl-Enter command to execute rust code + editor.commands.addCommand({ + name: 'run', + bindKey: { + win: 'Ctrl-Enter', + mac: 'Ctrl-Enter', + }, + exec: _editor => run_rust_code(playground_block), + }); + } + } + } + + // updates the visibility of play button based on `no_run` class and + // used crates vs ones available on https://play.rust-lang.org + function update_play_button(pre_block, playground_crates) { + const play_button = pre_block.querySelector('.play-button'); + + // skip if code is `no_run` + if (pre_block.querySelector('code').classList.contains('no_run')) { + play_button.classList.add('hidden'); + return; + } + + // get list of `extern crate`'s from snippet + const txt = playground_text(pre_block); + const re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g; + const snippet_crates = []; + let item; + // eslint-disable-next-line no-cond-assign + while (item = re.exec(txt)) { + snippet_crates.push(item[1]); + } + + // check if all used crates are available on play.rust-lang.org + const all_available = snippet_crates.every(function(elem) { + return playground_crates.indexOf(elem) > -1; + }); + + if (all_available) { + play_button.classList.remove('hidden'); + } else { + play_button.classList.add('hidden'); + } + } + + function run_rust_code(code_block) { + let result_block = code_block.querySelector('.result'); + if (!result_block) { + result_block = document.createElement('code'); + result_block.className = 'result hljs language-bash'; + + code_block.append(result_block); + } + + const text = playground_text(code_block); + const classes = code_block.querySelector('code').classList; + let edition = '2015'; + classes.forEach(className => { + if (className.startsWith('edition')) { + edition = className.slice(7); + } + }); + const params = { + version: 'stable', + optimize: '0', + code: text, + edition: edition, + }; + + if (text.indexOf('#![feature') !== -1) { + params.version = 'nightly'; + } + + result_block.innerText = 'Running...'; + + fetch_with_timeout('https://play.rust-lang.org/evaluate.json', { + headers: { + 'Content-Type': 'application/json', + }, + method: 'POST', + mode: 'cors', + body: JSON.stringify(params), + }) + .then(response => response.json()) + .then(response => { + if (response.result.trim() === '') { + result_block.innerText = 'No output'; + result_block.classList.add('result-no-output'); + } else { + result_block.innerText = response.result; + result_block.classList.remove('result-no-output'); + } + }) + .catch(error => result_block.innerText = 'Playground Communication: ' + error.message); + } + + // Syntax highlighting Configuration + hljs.configure({ + tabReplace: ' ', // 4 spaces + languages: [], // Languages used for auto-detection + }); + + const code_nodes = Array + .from(document.querySelectorAll('code')) + // Don't highlight `inline code` blocks in headers. + .filter(function(node) { + return !node.parentElement.classList.contains('header'); + }); + + if (window.ace) { + // language-rust class needs to be removed for editable + // blocks or highlightjs will capture events + code_nodes + .filter(function(node) { + return node.classList.contains('editable'); + }) + .forEach(function(block) { + block.classList.remove('language-rust'); + }); + + code_nodes + .filter(function(node) { + return !node.classList.contains('editable'); + }) + .forEach(function(block) { + hljs.highlightBlock(block); + }); + } else { + code_nodes.forEach(function(block) { + hljs.highlightBlock(block); + }); + } + + // Adding the hljs class gives code blocks the color css + // even if highlighting doesn't apply + code_nodes.forEach(function(block) { + block.classList.add('hljs'); + }); + + Array.from(document.querySelectorAll('code.hljs')).forEach(function(block) { + + const lines = Array.from(block.querySelectorAll('.boring')); + // If no lines were hidden, return + if (!lines.length) { + return; + } + block.classList.add('hide-boring'); + + const buttons = document.createElement('div'); + buttons.className = 'buttons'; + buttons.innerHTML = ''; + + // add expand button + const pre_block = block.parentNode; + pre_block.insertBefore(buttons, pre_block.firstChild); + + pre_block.querySelector('.buttons').addEventListener('click', function(e) { + if (e.target.classList.contains('fa-eye')) { + e.target.classList.remove('fa-eye'); + e.target.classList.add('fa-eye-slash'); + e.target.title = 'Hide lines'; + e.target.setAttribute('aria-label', e.target.title); + + block.classList.remove('hide-boring'); + } else if (e.target.classList.contains('fa-eye-slash')) { + e.target.classList.remove('fa-eye-slash'); + e.target.classList.add('fa-eye'); + e.target.title = 'Show hidden lines'; + e.target.setAttribute('aria-label', e.target.title); + + block.classList.add('hide-boring'); + } + }); + }); + + if (window.playground_copyable) { + Array.from(document.querySelectorAll('pre code')).forEach(function(block) { + const pre_block = block.parentNode; + if (!pre_block.classList.contains('playground')) { + let buttons = pre_block.querySelector('.buttons'); + if (!buttons) { + buttons = document.createElement('div'); + buttons.className = 'buttons'; + pre_block.insertBefore(buttons, pre_block.firstChild); + } + + const clipButton = document.createElement('button'); + clipButton.className = 'clip-button'; + clipButton.title = 'Copy to clipboard'; + clipButton.setAttribute('aria-label', clipButton.title); + clipButton.innerHTML = ''; + + buttons.insertBefore(clipButton, buttons.firstChild); + } + }); + } + + // Process playground code blocks + Array.from(document.querySelectorAll('.playground')).forEach(function(pre_block) { + // Add play button + let buttons = pre_block.querySelector('.buttons'); + if (!buttons) { + buttons = document.createElement('div'); + buttons.className = 'buttons'; + pre_block.insertBefore(buttons, pre_block.firstChild); + } + + const runCodeButton = document.createElement('button'); + runCodeButton.className = 'fa fa-play play-button'; + runCodeButton.hidden = true; + runCodeButton.title = 'Run this code'; + runCodeButton.setAttribute('aria-label', runCodeButton.title); + + buttons.insertBefore(runCodeButton, buttons.firstChild); + runCodeButton.addEventListener('click', () => { + run_rust_code(pre_block); + }); + + if (window.playground_copyable) { + const copyCodeClipboardButton = document.createElement('button'); + copyCodeClipboardButton.className = 'clip-button'; + copyCodeClipboardButton.innerHTML = ''; + copyCodeClipboardButton.title = 'Copy to clipboard'; + copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title); + + buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild); + } + + const code_block = pre_block.querySelector('code'); + if (window.ace && code_block.classList.contains('editable')) { + const undoChangesButton = document.createElement('button'); + undoChangesButton.className = 'fa fa-history reset-button'; + undoChangesButton.title = 'Undo changes'; + undoChangesButton.setAttribute('aria-label', undoChangesButton.title); + + buttons.insertBefore(undoChangesButton, buttons.firstChild); + + undoChangesButton.addEventListener('click', function() { + const editor = window.ace.edit(code_block); + editor.setValue(editor.originalCode); + editor.clearSelection(); + }); + } + }); +})(); + +(function themes() { + const html = document.querySelector('html'); + const themeToggleButton = document.getElementById('theme-toggle'); + const themePopup = document.getElementById('theme-list'); + const themeColorMetaTag = document.querySelector('meta[name="theme-color"]'); + const themeIds = []; + themePopup.querySelectorAll('button.theme').forEach(function(el) { + themeIds.push(el.id); + }); + const stylesheets = { + ayuHighlight: document.querySelector('#ayu-highlight-css'), + tomorrowNight: document.querySelector('#tomorrow-night-css'), + highlight: document.querySelector('#highlight-css'), + }; + + function showThemes() { + themePopup.style.display = 'block'; + themeToggleButton.setAttribute('aria-expanded', true); + themePopup.querySelector('button#' + get_theme()).focus(); + } + + function updateThemeSelected() { + themePopup.querySelectorAll('.theme-selected').forEach(function(el) { + el.classList.remove('theme-selected'); + }); + const selected = get_saved_theme() ?? 'default_theme'; + let element = themePopup.querySelector('button#' + selected); + if (element === null) { + // Fall back in case there is no "Default" item. + element = themePopup.querySelector('button#' + get_theme()); + } + element.classList.add('theme-selected'); + } + + function hideThemes() { + themePopup.style.display = 'none'; + themeToggleButton.setAttribute('aria-expanded', false); + themeToggleButton.focus(); + } + + function get_saved_theme() { + let theme = null; + try { + theme = localStorage.getItem('mdbook-theme'); + } catch (e) { + // ignore error. + } + return theme; + } + + function delete_saved_theme() { + localStorage.removeItem('mdbook-theme'); + } + + function get_theme() { + const theme = get_saved_theme(); + if (theme === null || theme === undefined || !themeIds.includes(theme)) { + if (typeof default_dark_theme === 'undefined') { + // A customized index.hbs might not define this, so fall back to + // old behavior of determining the default on page load. + return default_theme; + } + return window.matchMedia('(prefers-color-scheme: dark)').matches + ? default_dark_theme + : default_light_theme; + } else { + return theme; + } + } + + let previousTheme = default_theme; + function set_theme(theme, store = true) { + let ace_theme; + + if (theme === 'coal' || theme === 'navy') { + stylesheets.ayuHighlight.disabled = true; + stylesheets.tomorrowNight.disabled = false; + stylesheets.highlight.disabled = true; + + ace_theme = 'ace/theme/tomorrow_night'; + } else if (theme === 'ayu') { + stylesheets.ayuHighlight.disabled = false; + stylesheets.tomorrowNight.disabled = true; + stylesheets.highlight.disabled = true; + ace_theme = 'ace/theme/tomorrow_night'; + } else { + stylesheets.ayuHighlight.disabled = true; + stylesheets.tomorrowNight.disabled = true; + stylesheets.highlight.disabled = false; + ace_theme = 'ace/theme/dawn'; + } + + setTimeout(function() { + themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor; + }, 1); + + if (window.ace && window.editors) { + window.editors.forEach(function(editor) { + editor.setTheme(ace_theme); + }); + } + + if (store) { + try { + localStorage.setItem('mdbook-theme', theme); + } catch (e) { + // ignore error. + } + } + + html.classList.remove(previousTheme); + html.classList.add(theme); + previousTheme = theme; + updateThemeSelected(); + } + + const query = window.matchMedia('(prefers-color-scheme: dark)'); + query.onchange = function() { + set_theme(get_theme(), false); + }; + + // Set theme. + set_theme(get_theme(), false); + + themeToggleButton.addEventListener('click', function() { + if (themePopup.style.display === 'block') { + hideThemes(); + } else { + showThemes(); + } + }); + + themePopup.addEventListener('click', function(e) { + let theme; + if (e.target.className === 'theme') { + theme = e.target.id; + } else if (e.target.parentElement.className === 'theme') { + theme = e.target.parentElement.id; + } else { + return; + } + if (theme === 'default_theme' || theme === null) { + delete_saved_theme(); + set_theme(get_theme(), false); + } else { + set_theme(theme); + } + }); + + themePopup.addEventListener('focusout', function(e) { + // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below) + if (!!e.relatedTarget && + !themeToggleButton.contains(e.relatedTarget) && + !themePopup.contains(e.relatedTarget) + ) { + hideThemes(); + } + }); + + // Should not be needed, but it works around an issue on macOS & iOS: + // https://github.com/rust-lang/mdBook/issues/628 + document.addEventListener('click', function(e) { + if (themePopup.style.display === 'block' && + !themeToggleButton.contains(e.target) && + !themePopup.contains(e.target) + ) { + hideThemes(); + } + }); + + document.addEventListener('keydown', function(e) { + if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { + return; + } + if (!themePopup.contains(e.target)) { + return; + } + + let li; + switch (e.key) { + case 'Escape': + e.preventDefault(); + hideThemes(); + break; + case 'ArrowUp': + e.preventDefault(); + li = document.activeElement.parentElement; + if (li && li.previousElementSibling) { + li.previousElementSibling.querySelector('button').focus(); + } + break; + case 'ArrowDown': + e.preventDefault(); + li = document.activeElement.parentElement; + if (li && li.nextElementSibling) { + li.nextElementSibling.querySelector('button').focus(); + } + break; + case 'Home': + e.preventDefault(); + themePopup.querySelector('li:first-child button').focus(); + break; + case 'End': + e.preventDefault(); + themePopup.querySelector('li:last-child button').focus(); + break; + } + }); +})(); + +(function sidebar() { + const body = document.querySelector('body'); + const sidebar = document.getElementById('sidebar'); + const sidebarLinks = document.querySelectorAll('#sidebar a'); + const sidebarToggleButton = document.getElementById('sidebar-toggle'); + const sidebarToggleAnchor = document.getElementById('sidebar-toggle-anchor'); + const sidebarResizeHandle = document.getElementById('sidebar-resize-handle'); + let firstContact = null; + + function showSidebar() { + body.classList.remove('sidebar-hidden'); + body.classList.add('sidebar-visible'); + Array.from(sidebarLinks).forEach(function(link) { + link.setAttribute('tabIndex', 0); + }); + sidebarToggleButton.setAttribute('aria-expanded', true); + sidebar.setAttribute('aria-hidden', false); + try { + localStorage.setItem('mdbook-sidebar', 'visible'); + } catch (e) { + // Ignore error. + } + } + + function hideSidebar() { + body.classList.remove('sidebar-visible'); + body.classList.add('sidebar-hidden'); + Array.from(sidebarLinks).forEach(function(link) { + link.setAttribute('tabIndex', -1); + }); + sidebarToggleButton.setAttribute('aria-expanded', false); + sidebar.setAttribute('aria-hidden', true); + try { + localStorage.setItem('mdbook-sidebar', 'hidden'); + } catch (e) { + // Ignore error. + } + } + + // Toggle sidebar + sidebarToggleAnchor.addEventListener('change', function sidebarToggle() { + if (sidebarToggleAnchor.checked) { + const current_width = parseInt( + document.documentElement.style.getPropertyValue('--sidebar-target-width'), 10); + if (current_width < 150) { + document.documentElement.style.setProperty('--sidebar-target-width', '150px'); + } + showSidebar(); + } else { + hideSidebar(); + } + }); + + sidebarResizeHandle.addEventListener('mousedown', initResize, false); + + function initResize() { + window.addEventListener('mousemove', resize, false); + window.addEventListener('mouseup', stopResize, false); + body.classList.add('sidebar-resizing'); + } + function resize(e) { + let pos = e.clientX - sidebar.offsetLeft; + if (pos < 20) { + hideSidebar(); + } else { + if (body.classList.contains('sidebar-hidden')) { + showSidebar(); + } + pos = Math.min(pos, window.innerWidth - 100); + document.documentElement.style.setProperty('--sidebar-target-width', pos + 'px'); + } + } + //on mouseup remove windows functions mousemove & mouseup + function stopResize() { + body.classList.remove('sidebar-resizing'); + window.removeEventListener('mousemove', resize, false); + window.removeEventListener('mouseup', stopResize, false); + } + + document.addEventListener('touchstart', function(e) { + firstContact = { + x: e.touches[0].clientX, + time: Date.now(), + }; + }, { passive: true }); + + document.addEventListener('touchmove', function(e) { + if (!firstContact) { + return; + } + + const curX = e.touches[0].clientX; + const xDiff = curX - firstContact.x, + tDiff = Date.now() - firstContact.time; + + if (tDiff < 250 && Math.abs(xDiff) >= 150) { + if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300)) { + showSidebar(); + } else if (xDiff < 0 && curX < 300) { + hideSidebar(); + } + + firstContact = null; + } + }, { passive: true }); +})(); + +(function chapterNavigation() { + document.addEventListener('keydown', function(e) { + if (e.altKey || e.ctrlKey || e.metaKey) { + return; + } + if (window.search && window.search.hasFocus()) { + return; + } + const html = document.querySelector('html'); + + function next() { + const nextButton = document.querySelector('.nav-chapters.next'); + if (nextButton) { + window.location.href = nextButton.href; + } + } + function prev() { + const previousButton = document.querySelector('.nav-chapters.previous'); + if (previousButton) { + window.location.href = previousButton.href; + } + } + function showHelp() { + const container = document.getElementById('mdbook-help-container'); + const overlay = document.getElementById('mdbook-help-popup'); + container.style.display = 'flex'; + + // Clicking outside the popup will dismiss it. + const mouseHandler = event => { + if (overlay.contains(event.target)) { + return; + } + if (event.button !== 0) { + return; + } + event.preventDefault(); + event.stopPropagation(); + document.removeEventListener('mousedown', mouseHandler); + hideHelp(); + }; + + // Pressing esc will dismiss the popup. + const escapeKeyHandler = event => { + if (event.key === 'Escape') { + event.preventDefault(); + event.stopPropagation(); + document.removeEventListener('keydown', escapeKeyHandler, true); + hideHelp(); + } + }; + document.addEventListener('keydown', escapeKeyHandler, true); + document.getElementById('mdbook-help-container') + .addEventListener('mousedown', mouseHandler); + } + function hideHelp() { + document.getElementById('mdbook-help-container').style.display = 'none'; + } + + // Usually needs the Shift key to be pressed + switch (e.key) { + case '?': + e.preventDefault(); + showHelp(); + break; + } + + // Rest of the keys are only active when the Shift key is not pressed + if (e.shiftKey) { + return; + } + + switch (e.key) { + case 'ArrowRight': + e.preventDefault(); + if (html.dir === 'rtl') { + prev(); + } else { + next(); + } + break; + case 'ArrowLeft': + e.preventDefault(); + if (html.dir === 'rtl') { + next(); + } else { + prev(); + } + break; + } + }); +})(); + +(function clipboard() { + const clipButtons = document.querySelectorAll('.clip-button'); + + function hideTooltip(elem) { + elem.firstChild.innerText = ''; + elem.className = 'clip-button'; + } + + function showTooltip(elem, msg) { + elem.firstChild.innerText = msg; + elem.className = 'clip-button tooltipped'; + } + + const clipboardSnippets = new ClipboardJS('.clip-button', { + text: function(trigger) { + hideTooltip(trigger); + const playground = trigger.closest('pre'); + return playground_text(playground, false); + }, + }); + + Array.from(clipButtons).forEach(function(clipButton) { + clipButton.addEventListener('mouseout', function(e) { + hideTooltip(e.currentTarget); + }); + }); + + clipboardSnippets.on('success', function(e) { + e.clearSelection(); + showTooltip(e.trigger, 'Copied!'); + }); + + clipboardSnippets.on('error', function(e) { + showTooltip(e.trigger, 'Clipboard error!'); + }); +})(); + +(function scrollToTop() { + const menuTitle = document.querySelector('.menu-title'); + + menuTitle.addEventListener('click', function() { + document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' }); + }); +})(); + +(function controllMenu() { + const menu = document.getElementById('menu-bar'); + + (function controllPosition() { + let scrollTop = document.scrollingElement.scrollTop; + let prevScrollTop = scrollTop; + const minMenuY = -menu.clientHeight - 50; + // When the script loads, the page can be at any scroll (e.g. if you reforesh it). + menu.style.top = scrollTop + 'px'; + // Same as parseInt(menu.style.top.slice(0, -2), but faster + let topCache = menu.style.top.slice(0, -2); + menu.classList.remove('sticky'); + let stickyCache = false; // Same as menu.classList.contains('sticky'), but faster + document.addEventListener('scroll', function() { + scrollTop = Math.max(document.scrollingElement.scrollTop, 0); + // `null` means that it doesn't need to be updated + let nextSticky = null; + let nextTop = null; + const scrollDown = scrollTop > prevScrollTop; + const menuPosAbsoluteY = topCache - scrollTop; + if (scrollDown) { + nextSticky = false; + if (menuPosAbsoluteY > 0) { + nextTop = prevScrollTop; + } + } else { + if (menuPosAbsoluteY > 0) { + nextSticky = true; + } else if (menuPosAbsoluteY < minMenuY) { + nextTop = prevScrollTop + minMenuY; + } + } + if (nextSticky === true && stickyCache === false) { + menu.classList.add('sticky'); + stickyCache = true; + } else if (nextSticky === false && stickyCache === true) { + menu.classList.remove('sticky'); + stickyCache = false; + } + if (nextTop !== null) { + menu.style.top = nextTop + 'px'; + topCache = nextTop; + } + prevScrollTop = scrollTop; + }, { passive: true }); + })(); + (function controllBorder() { + function updateBorder() { + if (menu.offsetTop === 0) { + menu.classList.remove('bordered'); + } else { + menu.classList.add('bordered'); + } + } + updateBorder(); + document.addEventListener('scroll', updateBorder, { passive: true }); + })(); +})(); diff --git a/projects/rust/tutorial/clipboard.min.js b/projects/rust/tutorial/clipboard.min.js new file mode 100644 index 00000000000..02c549e35c8 --- /dev/null +++ b/projects/rust/tutorial/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.4 + * https://zenorocha.github.io/clipboard.js + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return function(n){var o={};function r(t){if(o[t])return o[t].exports;var e=o[t]={i:t,l:!1,exports:{}};return n[t].call(e.exports,e,e.exports,r),e.l=!0,e.exports}return r.m=n,r.c=o,r.d=function(t,e,n){r.o(t,e)||Object.defineProperty(t,e,{enumerable:!0,get:n})},r.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(t){var e=t&&t.__esModule?function(){return t.default}:function(){return t};return r.d(e,"a",e),e},r.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},r.p="",r(r.s=0)}([function(t,e,n){"use strict";var r="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},i=function(){function o(t,e){for(var n=0;n .hljs { + color: var(--links); +} + +/* + body-container is necessary because mobile browsers don't seem to like + overflow-x on the body tag when there is a tag. +*/ +#body-container { + /* + This is used when the sidebar pushes the body content off the side of + the screen on small screens. Without it, dragging on mobile Safari + will want to reposition the viewport in a weird way. + */ + overflow-x: clip; +} + +/* Menu Bar */ + +#menu-bar, +#menu-bar-hover-placeholder { + z-index: 101; + margin: auto calc(0px - var(--page-padding)); +} +#menu-bar { + position: relative; + display: flex; + flex-wrap: wrap; + background-color: var(--bg); + border-block-end-color: var(--bg); + border-block-end-width: 1px; + border-block-end-style: solid; +} +#menu-bar.sticky, +#menu-bar-hover-placeholder:hover + #menu-bar, +#menu-bar:hover, +html.sidebar-visible #menu-bar { + position: -webkit-sticky; + position: sticky; + top: 0 !important; +} +#menu-bar-hover-placeholder { + position: sticky; + position: -webkit-sticky; + top: 0; + height: var(--menu-bar-height); +} +#menu-bar.bordered { + border-block-end-color: var(--table-border-color); +} +#menu-bar i, #menu-bar .icon-button { + position: relative; + padding: 0 8px; + z-index: 10; + line-height: var(--menu-bar-height); + cursor: pointer; + transition: color 0.5s; +} +@media only screen and (max-width: 420px) { + #menu-bar i, #menu-bar .icon-button { + padding: 0 5px; + } +} + +.icon-button { + border: none; + background: none; + padding: 0; + color: inherit; +} +.icon-button i { + margin: 0; +} + +.right-buttons { + margin: 0 15px; +} +.right-buttons a { + text-decoration: none; +} + +.left-buttons { + display: flex; + margin: 0 5px; +} +html:not(.js) .left-buttons button { + display: none; +} + +.menu-title { + display: inline-block; + font-weight: 200; + font-size: 2.4rem; + line-height: var(--menu-bar-height); + text-align: center; + margin: 0; + flex: 1; + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} +.menu-title { + cursor: pointer; +} + +.menu-bar, +.menu-bar:visited, +.nav-chapters, +.nav-chapters:visited, +.mobile-nav-chapters, +.mobile-nav-chapters:visited, +.menu-bar .icon-button, +.menu-bar a i { + color: var(--icons); +} + +.menu-bar i:hover, +.menu-bar .icon-button:hover, +.nav-chapters:hover, +.mobile-nav-chapters i:hover { + color: var(--icons-hover); +} + +/* Nav Icons */ + +.nav-chapters { + font-size: 2.5em; + text-align: center; + text-decoration: none; + + position: fixed; + top: 0; + bottom: 0; + margin: 0; + max-width: 150px; + min-width: 90px; + + display: flex; + justify-content: center; + align-content: center; + flex-direction: column; + + transition: color 0.5s, background-color 0.5s; +} + +.nav-chapters:hover { + text-decoration: none; + background-color: var(--theme-hover); + transition: background-color 0.15s, color 0.15s; +} + +.nav-wrapper { + margin-block-start: 50px; + display: none; +} + +.mobile-nav-chapters { + font-size: 2.5em; + text-align: center; + text-decoration: none; + width: 90px; + border-radius: 5px; + background-color: var(--sidebar-bg); +} + +/* Only Firefox supports flow-relative values */ +.previous { float: left; } +[dir=rtl] .previous { float: right; } + +/* Only Firefox supports flow-relative values */ +.next { + float: right; + right: var(--page-padding); +} +[dir=rtl] .next { + float: left; + right: unset; + left: var(--page-padding); +} + +/* Use the correct buttons for RTL layouts*/ +[dir=rtl] .previous i.fa-angle-left:before {content:"\f105";} +[dir=rtl] .next i.fa-angle-right:before { content:"\f104"; } + +@media only screen and (max-width: 1080px) { + .nav-wide-wrapper { display: none; } + .nav-wrapper { display: block; } +} + +/* sidebar-visible */ +@media only screen and (max-width: 1380px) { + #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper { display: none; } + #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper { display: block; } +} + +/* Inline code */ + +:not(pre) > .hljs { + display: inline; + padding: 0.1em 0.3em; + border-radius: 3px; +} + +:not(pre):not(a) > .hljs { + color: var(--inline-code-color); + overflow-x: initial; +} + +a:hover > .hljs { + text-decoration: underline; +} + +pre { + position: relative; +} +pre > .buttons { + position: absolute; + z-index: 100; + right: 0px; + top: 2px; + margin: 0px; + padding: 2px 0px; + + color: var(--sidebar-fg); + cursor: pointer; + visibility: hidden; + opacity: 0; + transition: visibility 0.1s linear, opacity 0.1s linear; +} +pre:hover > .buttons { + visibility: visible; + opacity: 1 +} +pre > .buttons :hover { + color: var(--sidebar-active); + border-color: var(--icons-hover); + background-color: var(--theme-hover); +} +pre > .buttons i { + margin-inline-start: 8px; +} +pre > .buttons button { + cursor: inherit; + margin: 0px 5px; + padding: 4px 4px 3px 5px; + font-size: 23px; + + border-style: solid; + border-width: 1px; + border-radius: 4px; + border-color: var(--icons); + background-color: var(--theme-popup-bg); + transition: 100ms; + transition-property: color,border-color,background-color; + color: var(--icons); +} + +pre > .buttons button.clip-button { + padding: 2px 4px 0px 6px; +} +pre > .buttons button.clip-button::before { + /* clipboard image from octicons (https://github.com/primer/octicons/tree/v2.0.0) MIT license + */ + content: url('data:image/svg+xml,\ +\ +\ +'); + filter: var(--copy-button-filter); +} +pre > .buttons button.clip-button:hover::before { + filter: var(--copy-button-filter-hover); +} + +@media (pointer: coarse) { + pre > .buttons button { + /* On mobile, make it easier to tap buttons. */ + padding: 0.3rem 1rem; + } + + .sidebar-resize-indicator { + /* Hide resize indicator on devices with limited accuracy */ + display: none; + } +} +pre > code { + display: block; + padding: 1rem; +} + +/* FIXME: ACE editors overlap their buttons because ACE does absolute + positioning within the code block which breaks padding. The only solution I + can think of is to move the padding to the outer pre tag (or insert a div + wrapper), but that would require fixing a whole bunch of CSS rules. +*/ +.hljs.ace_editor { + padding: 0rem 0rem; +} + +pre > .result { + margin-block-start: 10px; +} + +/* Search */ + +#searchresults a { + text-decoration: none; +} + +mark { + border-radius: 2px; + padding-block-start: 0; + padding-block-end: 1px; + padding-inline-start: 3px; + padding-inline-end: 3px; + margin-block-start: 0; + margin-block-end: -1px; + margin-inline-start: -3px; + margin-inline-end: -3px; + background-color: var(--search-mark-bg); + transition: background-color 300ms linear; + cursor: pointer; +} + +mark.fade-out { + background-color: rgba(0,0,0,0) !important; + cursor: auto; +} + +.searchbar-outer { + margin-inline-start: auto; + margin-inline-end: auto; + max-width: var(--content-max-width); +} + +#searchbar { + width: 100%; + margin-block-start: 5px; + margin-block-end: 0; + margin-inline-start: auto; + margin-inline-end: auto; + padding: 10px 16px; + transition: box-shadow 300ms ease-in-out; + border: 1px solid var(--searchbar-border-color); + border-radius: 3px; + background-color: var(--searchbar-bg); + color: var(--searchbar-fg); +} +#searchbar:focus, +#searchbar.active { + box-shadow: 0 0 3px var(--searchbar-shadow-color); +} + +.searchresults-header { + font-weight: bold; + font-size: 1em; + padding-block-start: 18px; + padding-block-end: 0; + padding-inline-start: 5px; + padding-inline-end: 0; + color: var(--searchresults-header-fg); +} + +.searchresults-outer { + margin-inline-start: auto; + margin-inline-end: auto; + max-width: var(--content-max-width); + border-block-end: 1px dashed var(--searchresults-border-color); +} + +ul#searchresults { + list-style: none; + padding-inline-start: 20px; +} +ul#searchresults li { + margin: 10px 0px; + padding: 2px; + border-radius: 2px; +} +ul#searchresults li.focus { + background-color: var(--searchresults-li-bg); +} +ul#searchresults span.teaser { + display: block; + clear: both; + margin-block-start: 5px; + margin-block-end: 0; + margin-inline-start: 20px; + margin-inline-end: 0; + font-size: 0.8em; +} +ul#searchresults span.teaser em { + font-weight: bold; + font-style: normal; +} + +/* Sidebar */ + +.sidebar { + position: fixed; + left: 0; + top: 0; + bottom: 0; + width: var(--sidebar-width); + font-size: 0.875em; + box-sizing: border-box; + -webkit-overflow-scrolling: touch; + overscroll-behavior-y: contain; + background-color: var(--sidebar-bg); + color: var(--sidebar-fg); +} +.sidebar-iframe-inner { + --padding: 10px; + + background-color: var(--sidebar-bg); + padding: var(--padding); + margin: 0; + font-size: 1.4rem; + color: var(--sidebar-fg); + min-height: calc(100vh - var(--padding) * 2); +} +.sidebar-iframe-outer { + border: none; + height: 100%; + position: absolute; + top: 0; + bottom: 0; + left: 0; + right: 0; +} +[dir=rtl] .sidebar { left: unset; right: 0; } +.sidebar-resizing { + -moz-user-select: none; + -webkit-user-select: none; + -ms-user-select: none; + user-select: none; +} +html:not(.sidebar-resizing) .sidebar { + transition: transform 0.3s; /* Animation: slide away */ +} +.sidebar code { + line-height: 2em; +} +.sidebar .sidebar-scrollbox { + overflow-y: auto; + position: absolute; + top: 0; + bottom: 0; + left: 0; + right: 0; + padding: 10px 10px; +} +.sidebar .sidebar-resize-handle { + position: absolute; + cursor: col-resize; + width: 0; + right: calc(var(--sidebar-resize-indicator-width) * -1); + top: 0; + bottom: 0; + display: flex; + align-items: center; +} + +.sidebar-resize-handle .sidebar-resize-indicator { + width: 100%; + height: 16px; + color: var(--icons); + margin-inline-start: var(--sidebar-resize-indicator-space); + display: flex; + align-items: center; + justify-content: flex-start; +} +.sidebar-resize-handle .sidebar-resize-indicator::before { + content: ""; + width: 2px; + height: 12px; + border-left: dotted 2px currentColor; +} +.sidebar-resize-handle .sidebar-resize-indicator::after { + content: ""; + width: 2px; + height: 16px; + border-left: dotted 2px currentColor; +} + +[dir=rtl] .sidebar .sidebar-resize-handle { + left: calc(var(--sidebar-resize-indicator-width) * -1); + right: unset; +} +.js .sidebar .sidebar-resize-handle { + cursor: col-resize; + width: calc(var(--sidebar-resize-indicator-width) - var(--sidebar-resize-indicator-space)); +} +/* sidebar-hidden */ +#sidebar-toggle-anchor:not(:checked) ~ .sidebar { + transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width))); + z-index: -1; +} +[dir=rtl] #sidebar-toggle-anchor:not(:checked) ~ .sidebar { + transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width))); +} +.sidebar::-webkit-scrollbar { + background: var(--sidebar-bg); +} +.sidebar::-webkit-scrollbar-thumb { + background: var(--scrollbar); +} + +/* sidebar-visible */ +#sidebar-toggle-anchor:checked ~ .page-wrapper { + transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width))); +} +[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper { + transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width))); +} +@media only screen and (min-width: 620px) { + #sidebar-toggle-anchor:checked ~ .page-wrapper { + transform: none; + margin-inline-start: calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)); + } + [dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper { + transform: none; + } +} + +.chapter { + list-style: none outside none; + padding-inline-start: 0; + line-height: 2.2em; +} + +.chapter ol { + width: 100%; +} + +.chapter li { + display: flex; + color: var(--sidebar-non-existant); +} +.chapter li a { + display: block; + padding: 0; + text-decoration: none; + color: var(--sidebar-fg); +} + +.chapter li a:hover { + color: var(--sidebar-active); +} + +.chapter li a.active { + color: var(--sidebar-active); +} + +.chapter li > a.toggle { + cursor: pointer; + display: block; + margin-inline-start: auto; + padding: 0 10px; + user-select: none; + opacity: 0.68; +} + +.chapter li > a.toggle div { + transition: transform 0.5s; +} + +/* collapse the section */ +.chapter li:not(.expanded) + li > ol { + display: none; +} + +.chapter li.chapter-item { + line-height: 1.5em; + margin-block-start: 0.6em; +} + +.chapter li.expanded > a.toggle div { + transform: rotate(90deg); +} + +.spacer { + width: 100%; + height: 3px; + margin: 5px 0px; +} +.chapter .spacer { + background-color: var(--sidebar-spacer); +} + +@media (-moz-touch-enabled: 1), (pointer: coarse) { + .chapter li a { padding: 5px 0; } + .spacer { margin: 10px 0; } +} + +.section { + list-style: none outside none; + padding-inline-start: 20px; + line-height: 1.9em; +} + +/* Theme Menu Popup */ + +.theme-popup { + position: absolute; + left: 10px; + top: var(--menu-bar-height); + z-index: 1000; + border-radius: 4px; + font-size: 0.7em; + color: var(--fg); + background: var(--theme-popup-bg); + border: 1px solid var(--theme-popup-border); + margin: 0; + padding: 0; + list-style: none; + display: none; + /* Don't let the children's background extend past the rounded corners. */ + overflow: hidden; +} +[dir=rtl] .theme-popup { left: unset; right: 10px; } +.theme-popup .default { + color: var(--icons); +} +.theme-popup .theme { + width: 100%; + border: 0; + margin: 0; + padding: 2px 20px; + line-height: 25px; + white-space: nowrap; + text-align: start; + cursor: pointer; + color: inherit; + background: inherit; + font-size: inherit; +} +.theme-popup .theme:hover { + background-color: var(--theme-hover); +} + +.theme-selected::before { + display: inline-block; + content: "✓"; + margin-inline-start: -14px; + width: 14px; +} + +/* The container for the help popup that covers the whole window. */ +#mdbook-help-container { + /* Position and size for the whole window. */ + position: fixed; + top: 0; + left: 0; + right: 0; + bottom: 0; + /* This uses flex layout (which is set in book.js), and centers the popup + in the window.*/ + display: none; + align-items: center; + justify-content: center; + z-index: 1000; + /* Dim out the book while the popup is visible. */ + background: var(--overlay-bg); +} + +/* The popup help box. */ +#mdbook-help-popup { + box-shadow: 0 4px 24px rgba(0,0,0,0.15); + min-width: 300px; + max-width: 500px; + width: 100%; + box-sizing: border-box; + display: flex; + flex-direction: column; + align-items: center; + background-color: var(--bg); + color: var(--fg); + border-width: 1px; + border-color: var(--theme-popup-border); + border-style: solid; + border-radius: 8px; + padding: 10px; +} + +.mdbook-help-title { + text-align: center; + /* mdbook's margin for h2 is way too large. */ + margin: 10px; +} diff --git a/projects/rust/tutorial/css/general.css b/projects/rust/tutorial/css/general.css new file mode 100644 index 00000000000..9946cfc01a9 --- /dev/null +++ b/projects/rust/tutorial/css/general.css @@ -0,0 +1,279 @@ +/* Base styles and content styles */ + +:root { + /* Browser default font-size is 16px, this way 1 rem = 10px */ + font-size: 62.5%; + color-scheme: var(--color-scheme); +} + +html { + font-family: "Open Sans", sans-serif; + color: var(--fg); + background-color: var(--bg); + text-size-adjust: none; + -webkit-text-size-adjust: none; +} + +body { + margin: 0; + font-size: 1.6rem; + overflow-x: hidden; +} + +code { + font-family: var(--mono-font) !important; + font-size: var(--code-font-size); + direction: ltr !important; +} + +/* make long words/inline code not x overflow */ +main { + overflow-wrap: break-word; +} + +/* make wide tables scroll if they overflow */ +.table-wrapper { + overflow-x: auto; +} + +/* Don't change font size in headers. */ +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + font-size: unset; +} + +.left { float: left; } +.right { float: right; } +.boring { opacity: 0.6; } +.hide-boring .boring { display: none; } +.hidden { display: none !important; } + +h2, h3 { margin-block-start: 2.5em; } +h4, h5 { margin-block-start: 2em; } + +.header + .header h3, +.header + .header h4, +.header + .header h5 { + margin-block-start: 1em; +} + +h1:target::before, +h2:target::before, +h3:target::before, +h4:target::before, +h5:target::before, +h6:target::before { + display: inline-block; + content: "»"; + margin-inline-start: -30px; + width: 30px; +} + +/* This is broken on Safari as of version 14, but is fixed + in Safari Technology Preview 117 which I think will be Safari 14.2. + https://bugs.webkit.org/show_bug.cgi?id=218076 +*/ +:target { + /* Safari does not support logical properties */ + scroll-margin-top: calc(var(--menu-bar-height) + 0.5em); +} + +.page { + outline: 0; + padding: 0 var(--page-padding); + margin-block-start: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */ +} +.page-wrapper { + box-sizing: border-box; + background-color: var(--bg); +} +.no-js .page-wrapper, +.js:not(.sidebar-resizing) .page-wrapper { + transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */ +} +[dir=rtl] .js:not(.sidebar-resizing) .page-wrapper { + transition: margin-right 0.3s ease, transform 0.3s ease; /* Animation: slide away */ +} + +.content { + overflow-y: auto; + padding: 0 5px 50px 5px; +} +.content main { + margin-inline-start: auto; + margin-inline-end: auto; + max-width: var(--content-max-width); +} +.content p { line-height: 1.45em; } +.content ol { line-height: 1.45em; } +.content ul { line-height: 1.45em; } +.content a { text-decoration: none; } +.content a:hover { text-decoration: underline; } +.content img, .content video { max-width: 100%; } +.content .header:link, +.content .header:visited { + color: var(--fg); +} +.content .header:link, +.content .header:visited:hover { + text-decoration: none; +} + +table { + margin: 0 auto; + border-collapse: collapse; +} +table td { + padding: 3px 20px; + border: 1px var(--table-border-color) solid; +} +table thead { + background: var(--table-header-bg); +} +table thead td { + font-weight: 700; + border: none; +} +table thead th { + padding: 3px 20px; +} +table thead tr { + border: 1px var(--table-header-bg) solid; +} +/* Alternate background colors for rows */ +table tbody tr:nth-child(2n) { + background: var(--table-alternate-bg); +} + + +blockquote { + margin: 20px 0; + padding: 0 20px; + color: var(--fg); + background-color: var(--quote-bg); + border-block-start: .1em solid var(--quote-border); + border-block-end: .1em solid var(--quote-border); +} + +.warning { + margin: 20px; + padding: 0 20px; + border-inline-start: 2px solid var(--warning-border); +} + +.warning:before { + position: absolute; + width: 3rem; + height: 3rem; + margin-inline-start: calc(-1.5rem - 21px); + content: "ⓘ"; + text-align: center; + background-color: var(--bg); + color: var(--warning-border); + font-weight: bold; + font-size: 2rem; +} + +blockquote .warning:before { + background-color: var(--quote-bg); +} + +kbd { + background-color: var(--table-border-color); + border-radius: 4px; + border: solid 1px var(--theme-popup-border); + box-shadow: inset 0 -1px 0 var(--theme-hover); + display: inline-block; + font-size: var(--code-font-size); + font-family: var(--mono-font); + line-height: 10px; + padding: 4px 5px; + vertical-align: middle; +} + +sup { + /* Set the line-height for superscript and footnote references so that there + isn't an awkward space appearing above lines that contain the footnote. + + See https://github.com/rust-lang/mdBook/pull/2443#discussion_r1813773583 + for an explanation. + */ + line-height: 0; +} + +.footnote-definition { + font-size: 0.9em; +} +/* The default spacing for a list is a little too large. */ +.footnote-definition ul, +.footnote-definition ol { + padding-left: 20px; +} +.footnote-definition > li { + /* Required to position the ::before target */ + position: relative; +} +.footnote-definition > li:target { + scroll-margin-top: 50vh; +} +.footnote-reference:target { + scroll-margin-top: 50vh; +} +/* Draws a border around the footnote (including the marker) when it is selected. + TODO: If there are multiple linkbacks, highlight which one you just came + from so you know which one to click. +*/ +.footnote-definition > li:target::before { + border: 2px solid var(--footnote-highlight); + border-radius: 6px; + position: absolute; + top: -8px; + right: -8px; + bottom: -8px; + left: -32px; + pointer-events: none; + content: ""; +} +/* Pulses the footnote reference so you can quickly see where you left off reading. + This could use some improvement. +*/ +@media not (prefers-reduced-motion) { + .footnote-reference:target { + animation: fn-highlight 0.8s; + border-radius: 2px; + } + + @keyframes fn-highlight { + from { + background-color: var(--footnote-highlight); + } + } +} + +.tooltiptext { + position: absolute; + visibility: hidden; + color: #fff; + background-color: #333; + transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */ + left: -8px; /* Half of the width of the icon */ + top: -35px; + font-size: 0.8em; + text-align: center; + border-radius: 6px; + padding: 5px 8px; + margin: 5px; + z-index: 1000; +} +.tooltipped .tooltiptext { + visibility: visible; +} + +.chapter li.part-title { + color: var(--sidebar-fg); + margin: 5px 0px; + font-weight: bold; +} + +.result-no-output { + font-style: italic; +} diff --git a/projects/rust/tutorial/css/print.css b/projects/rust/tutorial/css/print.css new file mode 100644 index 00000000000..80ec3a54419 --- /dev/null +++ b/projects/rust/tutorial/css/print.css @@ -0,0 +1,50 @@ + +#sidebar, +#menu-bar, +.nav-chapters, +.mobile-nav-chapters { + display: none; +} + +#page-wrapper.page-wrapper { + transform: none !important; + margin-inline-start: 0px; + overflow-y: initial; +} + +#content { + max-width: none; + margin: 0; + padding: 0; +} + +.page { + overflow-y: initial; +} + +code { + direction: ltr !important; +} + +pre > .buttons { + z-index: 2; +} + +a, a:visited, a:active, a:hover { + color: #4183c4; + text-decoration: none; +} + +h1, h2, h3, h4, h5, h6 { + page-break-inside: avoid; + page-break-after: avoid; +} + +pre, code { + page-break-inside: avoid; + white-space: pre-wrap; +} + +.fa { + display: none !important; +} diff --git a/projects/rust/tutorial/css/variables.css b/projects/rust/tutorial/css/variables.css new file mode 100644 index 00000000000..5742d24142b --- /dev/null +++ b/projects/rust/tutorial/css/variables.css @@ -0,0 +1,330 @@ + +/* Globals */ + +:root { + --sidebar-target-width: 300px; + --sidebar-width: min(var(--sidebar-target-width), 80vw); + --sidebar-resize-indicator-width: 8px; + --sidebar-resize-indicator-space: 2px; + --page-padding: 15px; + --content-max-width: 750px; + --menu-bar-height: 50px; + --mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; + --code-font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */ +} + +/* Themes */ + +.ayu { + --bg: hsl(210, 25%, 8%); + --fg: #c5c5c5; + + --sidebar-bg: #14191f; + --sidebar-fg: #c8c9db; + --sidebar-non-existant: #5c6773; + --sidebar-active: #ffb454; + --sidebar-spacer: #2d334f; + + --scrollbar: var(--sidebar-fg); + + --icons: #737480; + --icons-hover: #b7b9cc; + + --links: #0096cf; + + --inline-code-color: #ffb454; + + --theme-popup-bg: #14191f; + --theme-popup-border: #5c6773; + --theme-hover: #191f26; + + --quote-bg: hsl(226, 15%, 17%); + --quote-border: hsl(226, 15%, 22%); + + --warning-border: #ff8e00; + + --table-border-color: hsl(210, 25%, 13%); + --table-header-bg: hsl(210, 25%, 28%); + --table-alternate-bg: hsl(210, 25%, 11%); + + --searchbar-border-color: #848484; + --searchbar-bg: #424242; + --searchbar-fg: #fff; + --searchbar-shadow-color: #d4c89f; + --searchresults-header-fg: #666; + --searchresults-border-color: #888; + --searchresults-li-bg: #252932; + --search-mark-bg: #e3b171; + + --color-scheme: dark; + + /* Same as `--icons` */ + --copy-button-filter: invert(45%) sepia(6%) saturate(621%) hue-rotate(198deg) brightness(99%) contrast(85%); + /* Same as `--sidebar-active` */ + --copy-button-filter-hover: invert(68%) sepia(55%) saturate(531%) hue-rotate(341deg) brightness(104%) contrast(101%); + + --footnote-highlight: #2668a6; + + --overlay-bg: rgba(33, 40, 48, 0.4); +} + +.coal { + --bg: hsl(200, 7%, 8%); + --fg: #98a3ad; + + --sidebar-bg: #292c2f; + --sidebar-fg: #a1adb8; + --sidebar-non-existant: #505254; + --sidebar-active: #3473ad; + --sidebar-spacer: #393939; + + --scrollbar: var(--sidebar-fg); + + --icons: #43484d; + --icons-hover: #b3c0cc; + + --links: #2b79a2; + + --inline-code-color: #c5c8c6; + + --theme-popup-bg: #141617; + --theme-popup-border: #43484d; + --theme-hover: #1f2124; + + --quote-bg: hsl(234, 21%, 18%); + --quote-border: hsl(234, 21%, 23%); + + --warning-border: #ff8e00; + + --table-border-color: hsl(200, 7%, 13%); + --table-header-bg: hsl(200, 7%, 28%); + --table-alternate-bg: hsl(200, 7%, 11%); + + --searchbar-border-color: #aaa; + --searchbar-bg: #b7b7b7; + --searchbar-fg: #000; + --searchbar-shadow-color: #aaa; + --searchresults-header-fg: #666; + --searchresults-border-color: #98a3ad; + --searchresults-li-bg: #2b2b2f; + --search-mark-bg: #355c7d; + + --color-scheme: dark; + + /* Same as `--icons` */ + --copy-button-filter: invert(26%) sepia(8%) saturate(575%) hue-rotate(169deg) brightness(87%) contrast(82%); + /* Same as `--sidebar-active` */ + --copy-button-filter-hover: invert(36%) sepia(70%) saturate(503%) hue-rotate(167deg) brightness(98%) contrast(89%); + + --footnote-highlight: #4079ae; + + --overlay-bg: rgba(33, 40, 48, 0.4); +} + +.light, html:not(.js) { + --bg: hsl(0, 0%, 100%); + --fg: hsl(0, 0%, 0%); + + --sidebar-bg: #fafafa; + --sidebar-fg: hsl(0, 0%, 0%); + --sidebar-non-existant: #aaaaaa; + --sidebar-active: #1f1fff; + --sidebar-spacer: #f4f4f4; + + --scrollbar: #8F8F8F; + + --icons: #747474; + --icons-hover: #000000; + + --links: #20609f; + + --inline-code-color: #301900; + + --theme-popup-bg: #fafafa; + --theme-popup-border: #cccccc; + --theme-hover: #e6e6e6; + + --quote-bg: hsl(197, 37%, 96%); + --quote-border: hsl(197, 37%, 91%); + + --warning-border: #ff8e00; + + --table-border-color: hsl(0, 0%, 95%); + --table-header-bg: hsl(0, 0%, 80%); + --table-alternate-bg: hsl(0, 0%, 97%); + + --searchbar-border-color: #aaa; + --searchbar-bg: #fafafa; + --searchbar-fg: #000; + --searchbar-shadow-color: #aaa; + --searchresults-header-fg: #666; + --searchresults-border-color: #888; + --searchresults-li-bg: #e4f2fe; + --search-mark-bg: #a2cff5; + + --color-scheme: light; + + /* Same as `--icons` */ + --copy-button-filter: invert(45.49%); + /* Same as `--sidebar-active` */ + --copy-button-filter-hover: invert(14%) sepia(93%) saturate(4250%) hue-rotate(243deg) brightness(99%) contrast(130%); + + --footnote-highlight: #7e7eff; + + --overlay-bg: rgba(200, 200, 205, 0.4); +} + +.navy { + --bg: hsl(226, 23%, 11%); + --fg: #bcbdd0; + + --sidebar-bg: #282d3f; + --sidebar-fg: #c8c9db; + --sidebar-non-existant: #505274; + --sidebar-active: #2b79a2; + --sidebar-spacer: #2d334f; + + --scrollbar: var(--sidebar-fg); + + --icons: #737480; + --icons-hover: #b7b9cc; + + --links: #2b79a2; + + --inline-code-color: #c5c8c6; + + --theme-popup-bg: #161923; + --theme-popup-border: #737480; + --theme-hover: #282e40; + + --quote-bg: hsl(226, 15%, 17%); + --quote-border: hsl(226, 15%, 22%); + + --warning-border: #ff8e00; + + --table-border-color: hsl(226, 23%, 16%); + --table-header-bg: hsl(226, 23%, 31%); + --table-alternate-bg: hsl(226, 23%, 14%); + + --searchbar-border-color: #aaa; + --searchbar-bg: #aeaec6; + --searchbar-fg: #000; + --searchbar-shadow-color: #aaa; + --searchresults-header-fg: #5f5f71; + --searchresults-border-color: #5c5c68; + --searchresults-li-bg: #242430; + --search-mark-bg: #a2cff5; + + --color-scheme: dark; + + /* Same as `--icons` */ + --copy-button-filter: invert(51%) sepia(10%) saturate(393%) hue-rotate(198deg) brightness(86%) contrast(87%); + /* Same as `--sidebar-active` */ + --copy-button-filter-hover: invert(46%) sepia(20%) saturate(1537%) hue-rotate(156deg) brightness(85%) contrast(90%); + + --footnote-highlight: #4079ae; + + --overlay-bg: rgba(33, 40, 48, 0.4); +} + +.rust { + --bg: hsl(60, 9%, 87%); + --fg: #262625; + + --sidebar-bg: #3b2e2a; + --sidebar-fg: #c8c9db; + --sidebar-non-existant: #505254; + --sidebar-active: #e69f67; + --sidebar-spacer: #45373a; + + --scrollbar: var(--sidebar-fg); + + --icons: #737480; + --icons-hover: #262625; + + --links: #2b79a2; + + --inline-code-color: #6e6b5e; + + --theme-popup-bg: #e1e1db; + --theme-popup-border: #b38f6b; + --theme-hover: #99908a; + + --quote-bg: hsl(60, 5%, 75%); + --quote-border: hsl(60, 5%, 70%); + + --warning-border: #ff8e00; + + --table-border-color: hsl(60, 9%, 82%); + --table-header-bg: #b3a497; + --table-alternate-bg: hsl(60, 9%, 84%); + + --searchbar-border-color: #aaa; + --searchbar-bg: #fafafa; + --searchbar-fg: #000; + --searchbar-shadow-color: #aaa; + --searchresults-header-fg: #666; + --searchresults-border-color: #888; + --searchresults-li-bg: #dec2a2; + --search-mark-bg: #e69f67; + + /* Same as `--icons` */ + --copy-button-filter: invert(51%) sepia(10%) saturate(393%) hue-rotate(198deg) brightness(86%) contrast(87%); + /* Same as `--sidebar-active` */ + --copy-button-filter-hover: invert(77%) sepia(16%) saturate(1798%) hue-rotate(328deg) brightness(98%) contrast(83%); + + --footnote-highlight: #d3a17a; + + --overlay-bg: rgba(150, 150, 150, 0.25); +} + +@media (prefers-color-scheme: dark) { + html:not(.js) { + --bg: hsl(200, 7%, 8%); + --fg: #98a3ad; + + --sidebar-bg: #292c2f; + --sidebar-fg: #a1adb8; + --sidebar-non-existant: #505254; + --sidebar-active: #3473ad; + --sidebar-spacer: #393939; + + --scrollbar: var(--sidebar-fg); + + --icons: #43484d; + --icons-hover: #b3c0cc; + + --links: #2b79a2; + + --inline-code-color: #c5c8c6; + + --theme-popup-bg: #141617; + --theme-popup-border: #43484d; + --theme-hover: #1f2124; + + --quote-bg: hsl(234, 21%, 18%); + --quote-border: hsl(234, 21%, 23%); + + --warning-border: #ff8e00; + + --table-border-color: hsl(200, 7%, 13%); + --table-header-bg: hsl(200, 7%, 28%); + --table-alternate-bg: hsl(200, 7%, 11%); + + --searchbar-border-color: #aaa; + --searchbar-bg: #b7b7b7; + --searchbar-fg: #000; + --searchbar-shadow-color: #aaa; + --searchresults-header-fg: #666; + --searchresults-border-color: #98a3ad; + --searchresults-li-bg: #2b2b2f; + --search-mark-bg: #355c7d; + + --color-scheme: dark; + + /* Same as `--icons` */ + --copy-button-filter: invert(26%) sepia(8%) saturate(575%) hue-rotate(169deg) brightness(87%) contrast(82%); + /* Same as `--sidebar-active` */ + --copy-button-filter-hover: invert(36%) sepia(70%) saturate(503%) hue-rotate(167deg) brightness(98%) contrast(89%); + } +} diff --git a/projects/rust/tutorial/elasticlunr.min.js b/projects/rust/tutorial/elasticlunr.min.js new file mode 100644 index 00000000000..94b20dd2ef4 --- /dev/null +++ b/projects/rust/tutorial/elasticlunr.min.js @@ -0,0 +1,10 @@ +/** + * elasticlunr - http://weixsong.github.io + * Lightweight full-text search engine in Javascript for browser search and offline search. - 0.9.5 + * + * Copyright (C) 2017 Oliver Nightingale + * Copyright (C) 2017 Wei Song + * MIT Licensed + * @license + */ +!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u0&&t.push(e);for(var i in n)"docs"!==i&&"df"!==i&&this.expandToken(e+i,t,n[i]);return t},t.InvertedIndex.prototype.toJSON=function(){return{root:this.root}},t.Configuration=function(e,n){var e=e||"";if(void 0==n||null==n)throw new Error("fields should not be null");this.config={};var i;try{i=JSON.parse(e),this.buildUserConfig(i,n)}catch(o){t.utils.warn("user configuration parse failed, will use default configuration"),this.buildDefaultConfig(n)}},t.Configuration.prototype.buildDefaultConfig=function(e){this.reset(),e.forEach(function(e){this.config[e]={boost:1,bool:"OR",expand:!1}},this)},t.Configuration.prototype.buildUserConfig=function(e,n){var i="OR",o=!1;if(this.reset(),"bool"in e&&(i=e.bool||i),"expand"in e&&(o=e.expand||o),"fields"in e)for(var r in e.fields)if(n.indexOf(r)>-1){var s=e.fields[r],u=o;void 0!=s.expand&&(u=s.expand),this.config[r]={boost:s.boost||0===s.boost?s.boost:1,bool:s.bool||i,expand:u}}else t.utils.warn("field name in user configuration not found in index instance fields");else this.addAllFields2UserConfig(i,o,n)},t.Configuration.prototype.addAllFields2UserConfig=function(e,t,n){n.forEach(function(n){this.config[n]={boost:1,bool:e,expand:t}},this)},t.Configuration.prototype.get=function(){return this.config},t.Configuration.prototype.reset=function(){this.config={}},lunr.SortedSet=function(){this.length=0,this.elements=[]},lunr.SortedSet.load=function(e){var t=new this;return t.elements=e,t.length=e.length,t},lunr.SortedSet.prototype.add=function(){var e,t;for(e=0;e1;){if(r===e)return o;e>r&&(t=o),r>e&&(n=o),i=n-t,o=t+Math.floor(i/2),r=this.elements[o]}return r===e?o:-1},lunr.SortedSet.prototype.locationFor=function(e){for(var t=0,n=this.elements.length,i=n-t,o=t+Math.floor(i/2),r=this.elements[o];i>1;)e>r&&(t=o),r>e&&(n=o),i=n-t,o=t+Math.floor(i/2),r=this.elements[o];return r>e?o:e>r?o+1:void 0},lunr.SortedSet.prototype.intersect=function(e){for(var t=new lunr.SortedSet,n=0,i=0,o=this.length,r=e.length,s=this.elements,u=e.elements;;){if(n>o-1||i>r-1)break;s[n]!==u[i]?s[n]u[i]&&i++:(t.add(s[n]),n++,i++)}return t},lunr.SortedSet.prototype.clone=function(){var e=new lunr.SortedSet;return e.elements=this.toArray(),e.length=e.elements.length,e},lunr.SortedSet.prototype.union=function(e){var t,n,i;this.length>=e.length?(t=this,n=e):(t=e,n=this),i=t.clone();for(var o=0,r=n.toArray();o + + + + diff --git a/projects/rust/tutorial/fonts/OPEN-SANS-LICENSE.txt b/projects/rust/tutorial/fonts/OPEN-SANS-LICENSE.txt new file mode 100644 index 00000000000..d6456956733 --- /dev/null +++ b/projects/rust/tutorial/fonts/OPEN-SANS-LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/projects/rust/tutorial/fonts/SOURCE-CODE-PRO-LICENSE.txt b/projects/rust/tutorial/fonts/SOURCE-CODE-PRO-LICENSE.txt new file mode 100644 index 00000000000..366206f5495 --- /dev/null +++ b/projects/rust/tutorial/fonts/SOURCE-CODE-PRO-LICENSE.txt @@ -0,0 +1,93 @@ +Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries. + +This Font Software is licensed under the SIL Open Font License, Version 1.1. +This license is copied below, and is also available with a FAQ at: +http://scripts.sil.org/OFL + + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, +in Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the corresponding +Copyright Holder. This restriction only applies to the primary font name as +presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created +using the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/projects/rust/tutorial/fonts/fonts.css b/projects/rust/tutorial/fonts/fonts.css new file mode 100644 index 00000000000..698e1e19e65 --- /dev/null +++ b/projects/rust/tutorial/fonts/fonts.css @@ -0,0 +1,100 @@ +/* Open Sans is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 */ +/* Source Code Pro is under the Open Font License. See https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL */ + +/* open-sans-300 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: normal; + font-weight: 300; + src: local('Open Sans Light'), local('OpenSans-Light'), + url('../fonts/open-sans-v17-all-charsets-300.woff2') format('woff2'); +} + +/* open-sans-300italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: italic; + font-weight: 300; + src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'), + url('../fonts/open-sans-v17-all-charsets-300italic.woff2') format('woff2'); +} + +/* open-sans-regular - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: normal; + font-weight: 400; + src: local('Open Sans Regular'), local('OpenSans-Regular'), + url('../fonts/open-sans-v17-all-charsets-regular.woff2') format('woff2'); +} + +/* open-sans-italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: italic; + font-weight: 400; + src: local('Open Sans Italic'), local('OpenSans-Italic'), + url('../fonts/open-sans-v17-all-charsets-italic.woff2') format('woff2'); +} + +/* open-sans-600 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: normal; + font-weight: 600; + src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'), + url('../fonts/open-sans-v17-all-charsets-600.woff2') format('woff2'); +} + +/* open-sans-600italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: italic; + font-weight: 600; + src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'), + url('../fonts/open-sans-v17-all-charsets-600italic.woff2') format('woff2'); +} + +/* open-sans-700 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: normal; + font-weight: 700; + src: local('Open Sans Bold'), local('OpenSans-Bold'), + url('../fonts/open-sans-v17-all-charsets-700.woff2') format('woff2'); +} + +/* open-sans-700italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: italic; + font-weight: 700; + src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'), + url('../fonts/open-sans-v17-all-charsets-700italic.woff2') format('woff2'); +} + +/* open-sans-800 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: normal; + font-weight: 800; + src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'), + url('../fonts/open-sans-v17-all-charsets-800.woff2') format('woff2'); +} + +/* open-sans-800italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Open Sans'; + font-style: italic; + font-weight: 800; + src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'), + url('../fonts/open-sans-v17-all-charsets-800italic.woff2') format('woff2'); +} + +/* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */ +@font-face { + font-family: 'Source Code Pro'; + font-style: normal; + font-weight: 500; + src: url('../fonts/source-code-pro-v11-all-charsets-500.woff2') format('woff2'); +} diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-300.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-300.woff2 new file mode 100644 index 00000000000..9f51be370fa Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-300.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-300italic.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-300italic.woff2 new file mode 100644 index 00000000000..2f545448418 Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-300italic.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-600.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-600.woff2 new file mode 100644 index 00000000000..f503d558d58 Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-600.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-600italic.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-600italic.woff2 new file mode 100644 index 00000000000..c99aabe8034 Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-600italic.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-700.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-700.woff2 new file mode 100644 index 00000000000..421a1ab25fa Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-700.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-700italic.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-700italic.woff2 new file mode 100644 index 00000000000..12ce3d20d1c Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-700italic.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-800.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-800.woff2 new file mode 100644 index 00000000000..c94a223b033 Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-800.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-800italic.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-800italic.woff2 new file mode 100644 index 00000000000..eed7d3c63d1 Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-800italic.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-italic.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-italic.woff2 new file mode 100644 index 00000000000..398b68a0853 Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-italic.woff2 differ diff --git a/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-regular.woff2 b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-regular.woff2 new file mode 100644 index 00000000000..8383e94c654 Binary files /dev/null and b/projects/rust/tutorial/fonts/open-sans-v17-all-charsets-regular.woff2 differ diff --git a/projects/rust/tutorial/fonts/source-code-pro-v11-all-charsets-500.woff2 b/projects/rust/tutorial/fonts/source-code-pro-v11-all-charsets-500.woff2 new file mode 100644 index 00000000000..722245682f5 Binary files /dev/null and b/projects/rust/tutorial/fonts/source-code-pro-v11-all-charsets-500.woff2 differ diff --git a/projects/rust/tutorial/highlight.css b/projects/rust/tutorial/highlight.css new file mode 100644 index 00000000000..352c79b9617 --- /dev/null +++ b/projects/rust/tutorial/highlight.css @@ -0,0 +1,83 @@ +/* + * An increased contrast highlighting scheme loosely based on the + * "Base16 Atelier Dune Light" theme by Bram de Haan + * (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune) + * Original Base16 color scheme by Chris Kempson + * (https://github.com/chriskempson/base16) + */ + +/* Comment */ +.hljs-comment, +.hljs-quote { + color: #575757; +} + +/* Red */ +.hljs-variable, +.hljs-template-variable, +.hljs-attribute, +.hljs-attr, +.hljs-tag, +.hljs-name, +.hljs-regexp, +.hljs-link, +.hljs-name, +.hljs-selector-id, +.hljs-selector-class { + color: #d70025; +} + +/* Orange */ +.hljs-number, +.hljs-meta, +.hljs-built_in, +.hljs-builtin-name, +.hljs-literal, +.hljs-type, +.hljs-params { + color: #b21e00; +} + +/* Green */ +.hljs-string, +.hljs-symbol, +.hljs-bullet { + color: #008200; +} + +/* Blue */ +.hljs-title, +.hljs-section { + color: #0030f2; +} + +/* Purple */ +.hljs-keyword, +.hljs-selector-tag { + color: #9d00ec; +} + +.hljs { + display: block; + overflow-x: auto; + background: #f6f7f6; + color: #000; +} + +.hljs-emphasis { + font-style: italic; +} + +.hljs-strong { + font-weight: bold; +} + +.hljs-addition { + color: #22863a; + background-color: #f0fff4; +} + +.hljs-deletion { + color: #b31d28; + background-color: #ffeef0; +} diff --git a/projects/rust/tutorial/highlight.js b/projects/rust/tutorial/highlight.js new file mode 100644 index 00000000000..18d24345bdd --- /dev/null +++ b/projects/rust/tutorial/highlight.js @@ -0,0 +1,54 @@ +/* + Highlight.js 10.1.1 (93fd0d73) + License: BSD-3-Clause + Copyright (c) 2006-2020, Ivan Sagalaev +*/ +var hljs=function(){"use strict";function e(n){Object.freeze(n);var t="function"==typeof n;return Object.getOwnPropertyNames(n).forEach((function(r){!Object.hasOwnProperty.call(n,r)||null===n[r]||"object"!=typeof n[r]&&"function"!=typeof n[r]||t&&("caller"===r||"callee"===r||"arguments"===r)||Object.isFrozen(n[r])||e(n[r])})),n}class n{constructor(e){void 0===e.data&&(e.data={}),this.data=e.data}ignoreMatch(){this.ignore=!0}}function t(e){return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'")}function r(e,...n){var t={};for(const n in e)t[n]=e[n];return n.forEach((function(e){for(const n in e)t[n]=e[n]})),t}function a(e){return e.nodeName.toLowerCase()}var i=Object.freeze({__proto__:null,escapeHTML:t,inherit:r,nodeStream:function(e){var n=[];return function e(t,r){for(var i=t.firstChild;i;i=i.nextSibling)3===i.nodeType?r+=i.nodeValue.length:1===i.nodeType&&(n.push({event:"start",offset:r,node:i}),r=e(i,r),a(i).match(/br|hr|img|input/)||n.push({event:"stop",offset:r,node:i}));return r}(e,0),n},mergeStreams:function(e,n,r){var i=0,s="",o=[];function l(){return e.length&&n.length?e[0].offset!==n[0].offset?e[0].offset"}function u(e){s+=""}function d(e){("start"===e.event?c:u)(e.node)}for(;e.length||n.length;){var g=l();if(s+=t(r.substring(i,g[0].offset)),i=g[0].offset,g===e){o.reverse().forEach(u);do{d(g.splice(0,1)[0]),g=l()}while(g===e&&g.length&&g[0].offset===i);o.reverse().forEach(c)}else"start"===g[0].event?o.push(g[0].node):o.pop(),d(g.splice(0,1)[0])}return s+t(r.substr(i))}});const s="",o=e=>!!e.kind;class l{constructor(e,n){this.buffer="",this.classPrefix=n.classPrefix,e.walk(this)}addText(e){this.buffer+=t(e)}openNode(e){if(!o(e))return;let n=e.kind;e.sublanguage||(n=`${this.classPrefix}${n}`),this.span(n)}closeNode(e){o(e)&&(this.buffer+=s)}value(){return this.buffer}span(e){this.buffer+=``}}class c{constructor(){this.rootNode={children:[]},this.stack=[this.rootNode]}get top(){return this.stack[this.stack.length-1]}get root(){return this.rootNode}add(e){this.top.children.push(e)}openNode(e){const n={kind:e,children:[]};this.add(n),this.stack.push(n)}closeNode(){if(this.stack.length>1)return this.stack.pop()}closeAllNodes(){for(;this.closeNode(););}toJSON(){return JSON.stringify(this.rootNode,null,4)}walk(e){return this.constructor._walk(e,this.rootNode)}static _walk(e,n){return"string"==typeof n?e.addText(n):n.children&&(e.openNode(n),n.children.forEach(n=>this._walk(e,n)),e.closeNode(n)),e}static _collapse(e){"string"!=typeof e&&e.children&&(e.children.every(e=>"string"==typeof e)?e.children=[e.children.join("")]:e.children.forEach(e=>{c._collapse(e)}))}}class u extends c{constructor(e){super(),this.options=e}addKeyword(e,n){""!==e&&(this.openNode(n),this.addText(e),this.closeNode())}addText(e){""!==e&&this.add(e)}addSublanguage(e,n){const t=e.root;t.kind=n,t.sublanguage=!0,this.add(t)}toHTML(){return new l(this,this.options).value()}finalize(){return!0}}function d(e){return e?"string"==typeof e?e:e.source:null}const g="(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)",h={begin:"\\\\[\\s\\S]",relevance:0},f={className:"string",begin:"'",end:"'",illegal:"\\n",contains:[h]},p={className:"string",begin:'"',end:'"',illegal:"\\n",contains:[h]},b={begin:/\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/},m=function(e,n,t={}){var a=r({className:"comment",begin:e,end:n,contains:[]},t);return a.contains.push(b),a.contains.push({className:"doctag",begin:"(?:TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):",relevance:0}),a},v=m("//","$"),x=m("/\\*","\\*/"),E=m("#","$");var _=Object.freeze({__proto__:null,IDENT_RE:"[a-zA-Z]\\w*",UNDERSCORE_IDENT_RE:"[a-zA-Z_]\\w*",NUMBER_RE:"\\b\\d+(\\.\\d+)?",C_NUMBER_RE:g,BINARY_NUMBER_RE:"\\b(0b[01]+)",RE_STARTERS_RE:"!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~",SHEBANG:(e={})=>{const n=/^#![ ]*\//;return e.binary&&(e.begin=function(...e){return e.map(e=>d(e)).join("")}(n,/.*\b/,e.binary,/\b.*/)),r({className:"meta",begin:n,end:/$/,relevance:0,"on:begin":(e,n)=>{0!==e.index&&n.ignoreMatch()}},e)},BACKSLASH_ESCAPE:h,APOS_STRING_MODE:f,QUOTE_STRING_MODE:p,PHRASAL_WORDS_MODE:b,COMMENT:m,C_LINE_COMMENT_MODE:v,C_BLOCK_COMMENT_MODE:x,HASH_COMMENT_MODE:E,NUMBER_MODE:{className:"number",begin:"\\b\\d+(\\.\\d+)?",relevance:0},C_NUMBER_MODE:{className:"number",begin:g,relevance:0},BINARY_NUMBER_MODE:{className:"number",begin:"\\b(0b[01]+)",relevance:0},CSS_NUMBER_MODE:{className:"number",begin:"\\b\\d+(\\.\\d+)?(%|em|ex|ch|rem|vw|vh|vmin|vmax|cm|mm|in|pt|pc|px|deg|grad|rad|turn|s|ms|Hz|kHz|dpi|dpcm|dppx)?",relevance:0},REGEXP_MODE:{begin:/(?=\/[^/\n]*\/)/,contains:[{className:"regexp",begin:/\//,end:/\/[gimuy]*/,illegal:/\n/,contains:[h,{begin:/\[/,end:/\]/,relevance:0,contains:[h]}]}]},TITLE_MODE:{className:"title",begin:"[a-zA-Z]\\w*",relevance:0},UNDERSCORE_TITLE_MODE:{className:"title",begin:"[a-zA-Z_]\\w*",relevance:0},METHOD_GUARD:{begin:"\\.\\s*[a-zA-Z_]\\w*",relevance:0},END_SAME_AS_BEGIN:function(e){return Object.assign(e,{"on:begin":(e,n)=>{n.data._beginMatch=e[1]},"on:end":(e,n)=>{n.data._beginMatch!==e[1]&&n.ignoreMatch()}})}}),N="of and for in not or if then".split(" ");function w(e,n){return n?+n:function(e){return N.includes(e.toLowerCase())}(e)?0:1}const R=t,y=r,{nodeStream:k,mergeStreams:O}=i,M=Symbol("nomatch");return function(t){var a=[],i={},s={},o=[],l=!0,c=/(^(<[^>]+>|\t|)+|\n)/gm,g="Could not find the language '{}', did you forget to load/include a language module?";const h={disableAutodetect:!0,name:"Plain text",contains:[]};var f={noHighlightRe:/^(no-?highlight)$/i,languageDetectRe:/\blang(?:uage)?-([\w-]+)\b/i,classPrefix:"hljs-",tabReplace:null,useBR:!1,languages:null,__emitter:u};function p(e){return f.noHighlightRe.test(e)}function b(e,n,t,r){var a={code:n,language:e};S("before:highlight",a);var i=a.result?a.result:m(a.language,a.code,t,r);return i.code=a.code,S("after:highlight",i),i}function m(e,t,a,s){var o=t;function c(e,n){var t=E.case_insensitive?n[0].toLowerCase():n[0];return Object.prototype.hasOwnProperty.call(e.keywords,t)&&e.keywords[t]}function u(){null!=y.subLanguage?function(){if(""!==A){var e=null;if("string"==typeof y.subLanguage){if(!i[y.subLanguage])return void O.addText(A);e=m(y.subLanguage,A,!0,k[y.subLanguage]),k[y.subLanguage]=e.top}else e=v(A,y.subLanguage.length?y.subLanguage:null);y.relevance>0&&(I+=e.relevance),O.addSublanguage(e.emitter,e.language)}}():function(){if(!y.keywords)return void O.addText(A);let e=0;y.keywordPatternRe.lastIndex=0;let n=y.keywordPatternRe.exec(A),t="";for(;n;){t+=A.substring(e,n.index);const r=c(y,n);if(r){const[e,a]=r;O.addText(t),t="",I+=a,O.addKeyword(n[0],e)}else t+=n[0];e=y.keywordPatternRe.lastIndex,n=y.keywordPatternRe.exec(A)}t+=A.substr(e),O.addText(t)}(),A=""}function h(e){return e.className&&O.openNode(e.className),y=Object.create(e,{parent:{value:y}})}function p(e){return 0===y.matcher.regexIndex?(A+=e[0],1):(L=!0,0)}var b={};function x(t,r){var i=r&&r[0];if(A+=t,null==i)return u(),0;if("begin"===b.type&&"end"===r.type&&b.index===r.index&&""===i){if(A+=o.slice(r.index,r.index+1),!l){const n=Error("0 width match regex");throw n.languageName=e,n.badRule=b.rule,n}return 1}if(b=r,"begin"===r.type)return function(e){var t=e[0],r=e.rule;const a=new n(r),i=[r.__beforeBegin,r["on:begin"]];for(const n of i)if(n&&(n(e,a),a.ignore))return p(t);return r&&r.endSameAsBegin&&(r.endRe=RegExp(t.replace(/[-/\\^$*+?.()|[\]{}]/g,"\\$&"),"m")),r.skip?A+=t:(r.excludeBegin&&(A+=t),u(),r.returnBegin||r.excludeBegin||(A=t)),h(r),r.returnBegin?0:t.length}(r);if("illegal"===r.type&&!a){const e=Error('Illegal lexeme "'+i+'" for mode "'+(y.className||"")+'"');throw e.mode=y,e}if("end"===r.type){var s=function(e){var t=e[0],r=o.substr(e.index),a=function e(t,r,a){let i=function(e,n){var t=e&&e.exec(n);return t&&0===t.index}(t.endRe,a);if(i){if(t["on:end"]){const e=new n(t);t["on:end"](r,e),e.ignore&&(i=!1)}if(i){for(;t.endsParent&&t.parent;)t=t.parent;return t}}if(t.endsWithParent)return e(t.parent,r,a)}(y,e,r);if(!a)return M;var i=y;i.skip?A+=t:(i.returnEnd||i.excludeEnd||(A+=t),u(),i.excludeEnd&&(A=t));do{y.className&&O.closeNode(),y.skip||y.subLanguage||(I+=y.relevance),y=y.parent}while(y!==a.parent);return a.starts&&(a.endSameAsBegin&&(a.starts.endRe=a.endRe),h(a.starts)),i.returnEnd?0:t.length}(r);if(s!==M)return s}if("illegal"===r.type&&""===i)return 1;if(B>1e5&&B>3*r.index)throw Error("potential infinite loop, way more iterations than matches");return A+=i,i.length}var E=T(e);if(!E)throw console.error(g.replace("{}",e)),Error('Unknown language: "'+e+'"');var _=function(e){function n(n,t){return RegExp(d(n),"m"+(e.case_insensitive?"i":"")+(t?"g":""))}class t{constructor(){this.matchIndexes={},this.regexes=[],this.matchAt=1,this.position=0}addRule(e,n){n.position=this.position++,this.matchIndexes[this.matchAt]=n,this.regexes.push([n,e]),this.matchAt+=function(e){return RegExp(e.toString()+"|").exec("").length-1}(e)+1}compile(){0===this.regexes.length&&(this.exec=()=>null);const e=this.regexes.map(e=>e[1]);this.matcherRe=n(function(e,n="|"){for(var t=/\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./,r=0,a="",i=0;i0&&(a+=n),a+="(";o.length>0;){var l=t.exec(o);if(null==l){a+=o;break}a+=o.substring(0,l.index),o=o.substring(l.index+l[0].length),"\\"===l[0][0]&&l[1]?a+="\\"+(+l[1]+s):(a+=l[0],"("===l[0]&&r++)}a+=")"}return a}(e),!0),this.lastIndex=0}exec(e){this.matcherRe.lastIndex=this.lastIndex;const n=this.matcherRe.exec(e);if(!n)return null;const t=n.findIndex((e,n)=>n>0&&void 0!==e),r=this.matchIndexes[t];return n.splice(0,t),Object.assign(n,r)}}class a{constructor(){this.rules=[],this.multiRegexes=[],this.count=0,this.lastIndex=0,this.regexIndex=0}getMatcher(e){if(this.multiRegexes[e])return this.multiRegexes[e];const n=new t;return this.rules.slice(e).forEach(([e,t])=>n.addRule(e,t)),n.compile(),this.multiRegexes[e]=n,n}considerAll(){this.regexIndex=0}addRule(e,n){this.rules.push([e,n]),"begin"===n.type&&this.count++}exec(e){const n=this.getMatcher(this.regexIndex);n.lastIndex=this.lastIndex;const t=n.exec(e);return t&&(this.regexIndex+=t.position+1,this.regexIndex===this.count&&(this.regexIndex=0)),t}}function i(e,n){const t=e.input[e.index-1],r=e.input[e.index+e[0].length];"."!==t&&"."!==r||n.ignoreMatch()}if(e.contains&&e.contains.includes("self"))throw Error("ERR: contains `self` is not supported at the top-level of a language. See documentation.");return function t(s,o){const l=s;if(s.compiled)return l;s.compiled=!0,s.__beforeBegin=null,s.keywords=s.keywords||s.beginKeywords;let c=null;if("object"==typeof s.keywords&&(c=s.keywords.$pattern,delete s.keywords.$pattern),s.keywords&&(s.keywords=function(e,n){var t={};return"string"==typeof e?r("keyword",e):Object.keys(e).forEach((function(n){r(n,e[n])})),t;function r(e,r){n&&(r=r.toLowerCase()),r.split(" ").forEach((function(n){var r=n.split("|");t[r[0]]=[e,w(r[0],r[1])]}))}}(s.keywords,e.case_insensitive)),s.lexemes&&c)throw Error("ERR: Prefer `keywords.$pattern` to `mode.lexemes`, BOTH are not allowed. (see mode reference) ");return l.keywordPatternRe=n(s.lexemes||c||/\w+/,!0),o&&(s.beginKeywords&&(s.begin="\\b("+s.beginKeywords.split(" ").join("|")+")(?=\\b|\\s)",s.__beforeBegin=i),s.begin||(s.begin=/\B|\b/),l.beginRe=n(s.begin),s.endSameAsBegin&&(s.end=s.begin),s.end||s.endsWithParent||(s.end=/\B|\b/),s.end&&(l.endRe=n(s.end)),l.terminator_end=d(s.end)||"",s.endsWithParent&&o.terminator_end&&(l.terminator_end+=(s.end?"|":"")+o.terminator_end)),s.illegal&&(l.illegalRe=n(s.illegal)),void 0===s.relevance&&(s.relevance=1),s.contains||(s.contains=[]),s.contains=[].concat(...s.contains.map((function(e){return function(e){return e.variants&&!e.cached_variants&&(e.cached_variants=e.variants.map((function(n){return r(e,{variants:null},n)}))),e.cached_variants?e.cached_variants:function e(n){return!!n&&(n.endsWithParent||e(n.starts))}(e)?r(e,{starts:e.starts?r(e.starts):null}):Object.isFrozen(e)?r(e):e}("self"===e?s:e)}))),s.contains.forEach((function(e){t(e,l)})),s.starts&&t(s.starts,o),l.matcher=function(e){const n=new a;return e.contains.forEach(e=>n.addRule(e.begin,{rule:e,type:"begin"})),e.terminator_end&&n.addRule(e.terminator_end,{type:"end"}),e.illegal&&n.addRule(e.illegal,{type:"illegal"}),n}(l),l}(e)}(E),N="",y=s||_,k={},O=new f.__emitter(f);!function(){for(var e=[],n=y;n!==E;n=n.parent)n.className&&e.unshift(n.className);e.forEach(e=>O.openNode(e))}();var A="",I=0,S=0,B=0,L=!1;try{for(y.matcher.considerAll();;){B++,L?L=!1:(y.matcher.lastIndex=S,y.matcher.considerAll());const e=y.matcher.exec(o);if(!e)break;const n=x(o.substring(S,e.index),e);S=e.index+n}return x(o.substr(S)),O.closeAllNodes(),O.finalize(),N=O.toHTML(),{relevance:I,value:N,language:e,illegal:!1,emitter:O,top:y}}catch(n){if(n.message&&n.message.includes("Illegal"))return{illegal:!0,illegalBy:{msg:n.message,context:o.slice(S-100,S+100),mode:n.mode},sofar:N,relevance:0,value:R(o),emitter:O};if(l)return{illegal:!1,relevance:0,value:R(o),emitter:O,language:e,top:y,errorRaised:n};throw n}}function v(e,n){n=n||f.languages||Object.keys(i);var t=function(e){const n={relevance:0,emitter:new f.__emitter(f),value:R(e),illegal:!1,top:h};return n.emitter.addText(e),n}(e),r=t;return n.filter(T).filter(I).forEach((function(n){var a=m(n,e,!1);a.language=n,a.relevance>r.relevance&&(r=a),a.relevance>t.relevance&&(r=t,t=a)})),r.language&&(t.second_best=r),t}function x(e){return f.tabReplace||f.useBR?e.replace(c,e=>"\n"===e?f.useBR?"
":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(//g,"\n"):n=e;const r=n.textContent,a=t?b(t,r,!0):v(r),i=k(n);if(i.length){const e=document.createElement("div");e.innerHTML=a.value,a.value=O(i,k(e),r)}a.value=x(a.value),S("after:highlightBlock",{block:e,result:a}),e.innerHTML=a.value,e.className=function(e,n,t){var r=n?s[n]:t,a=[e.trim()];return e.match(/\bhljs\b/)||a.push("hljs"),e.includes(r)||a.push(r),a.join(" ").trim()}(e.className,t,a.language),e.result={language:a.language,re:a.relevance,relavance:a.relevance},a.second_best&&(e.second_best={language:a.second_best.language,re:a.second_best.relevance,relavance:a.second_best.relevance})}const N=()=>{if(!N.called){N.called=!0;var e=document.querySelectorAll("pre code");a.forEach.call(e,E)}};function T(e){return e=(e||"").toLowerCase(),i[e]||i[s[e]]}function A(e,{languageName:n}){"string"==typeof e&&(e=[e]),e.forEach(e=>{s[e]=n})}function I(e){var n=T(e);return n&&!n.disableAutodetect}function S(e,n){var t=e;o.forEach((function(e){e[t]&&e[t](n)}))}Object.assign(t,{highlight:b,highlightAuto:v,fixMarkup:x,highlightBlock:E,configure:function(e){f=y(f,e)},initHighlighting:N,initHighlightingOnLoad:function(){window.addEventListener("DOMContentLoaded",N,!1)},registerLanguage:function(e,n){var r=null;try{r=n(t)}catch(n){if(console.error("Language definition for '{}' could not be registered.".replace("{}",e)),!l)throw n;console.error(n),r=h}r.name||(r.name=e),i[e]=r,r.rawDefinition=n.bind(null,t),r.aliases&&A(r.aliases,{languageName:e})},listLanguages:function(){return Object.keys(i)},getLanguage:T,registerAliases:A,requireLanguage:function(e){var n=T(e);if(n)return n;throw Error("The '{}' language is required, but not loaded.".replace("{}",e))},autoDetection:I,inherit:y,addPlugin:function(e){o.push(e)}}),t.debugMode=function(){l=!1},t.safeMode=function(){l=!0},t.versionString="10.1.1";for(const n in _)"object"==typeof _[n]&&e(_[n]);return Object.assign(t,_),t}({})}();"object"==typeof exports&&"undefined"!=typeof module&&(module.exports=hljs); +hljs.registerLanguage("apache",function(){"use strict";return function(e){var n={className:"number",begin:"\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}(:\\d{1,5})?"};return{name:"Apache config",aliases:["apacheconf"],case_insensitive:!0,contains:[e.HASH_COMMENT_MODE,{className:"section",begin:"",contains:[n,{className:"number",begin:":\\d{1,5}"},e.inherit(e.QUOTE_STRING_MODE,{relevance:0})]},{className:"attribute",begin:/\w+/,relevance:0,keywords:{nomarkup:"order deny allow setenv rewriterule rewriteengine rewritecond documentroot sethandler errordocument loadmodule options header listen serverroot servername"},starts:{end:/$/,relevance:0,keywords:{literal:"on off all deny allow"},contains:[{className:"meta",begin:"\\s\\[",end:"\\]$"},{className:"variable",begin:"[\\$%]\\{",end:"\\}",contains:["self",{className:"number",begin:"[\\$%]\\d+"}]},n,{className:"number",begin:"\\d+"},e.QUOTE_STRING_MODE]}}],illegal:/\S/}}}()); +hljs.registerLanguage("bash",function(){"use strict";return function(e){const s={};Object.assign(s,{className:"variable",variants:[{begin:/\$[\w\d#@][\w\d_]*/},{begin:/\$\{/,end:/\}/,contains:[{begin:/:-/,contains:[s]}]}]});const t={className:"subst",begin:/\$\(/,end:/\)/,contains:[e.BACKSLASH_ESCAPE]},n={className:"string",begin:/"/,end:/"/,contains:[e.BACKSLASH_ESCAPE,s,t]};t.contains.push(n);const a={begin:/\$\(\(/,end:/\)\)/,contains:[{begin:/\d+#[0-9a-f]+/,className:"number"},e.NUMBER_MODE,s]},i=e.SHEBANG({binary:"(fish|bash|zsh|sh|csh|ksh|tcsh|dash|scsh)",relevance:10}),c={className:"function",begin:/\w[\w\d_]*\s*\(\s*\)\s*\{/,returnBegin:!0,contains:[e.inherit(e.TITLE_MODE,{begin:/\w[\w\d_]*/})],relevance:0};return{name:"Bash",aliases:["sh","zsh"],keywords:{$pattern:/\b-?[a-z\._]+\b/,keyword:"if then else elif fi for while in do done case esac function",literal:"true false",built_in:"break cd continue eval exec exit export getopts hash pwd readonly return shift test times trap umask unset alias bind builtin caller command declare echo enable help let local logout mapfile printf read readarray source type typeset ulimit unalias set shopt autoload bg bindkey bye cap chdir clone comparguments compcall compctl compdescribe compfiles compgroups compquote comptags comptry compvalues dirs disable disown echotc echoti emulate fc fg float functions getcap getln history integer jobs kill limit log noglob popd print pushd pushln rehash sched setcap setopt stat suspend ttyctl unfunction unhash unlimit unsetopt vared wait whence where which zcompile zformat zftp zle zmodload zparseopts zprof zpty zregexparse zsocket zstyle ztcp",_:"-ne -eq -lt -gt -f -d -e -s -l -a"},contains:[i,e.SHEBANG(),c,a,e.HASH_COMMENT_MODE,n,{className:"",begin:/\\"/},{className:"string",begin:/'/,end:/'/},s]}}}()); +hljs.registerLanguage("c-like",function(){"use strict";return function(e){function t(e){return"(?:"+e+")?"}var n="(decltype\\(auto\\)|"+t("[a-zA-Z_]\\w*::")+"[a-zA-Z_]\\w*"+t("<.*?>")+")",r={className:"keyword",begin:"\\b[a-z\\d_]*_t\\b"},a={className:"string",variants:[{begin:'(u8?|U|L)?"',end:'"',illegal:"\\n",contains:[e.BACKSLASH_ESCAPE]},{begin:"(u8?|U|L)?'(\\\\(x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4,8}|[0-7]{3}|\\S)|.)",end:"'",illegal:"."},e.END_SAME_AS_BEGIN({begin:/(?:u8?|U|L)?R"([^()\\ ]{0,16})\(/,end:/\)([^()\\ ]{0,16})"/})]},i={className:"number",variants:[{begin:"\\b(0b[01']+)"},{begin:"(-?)\\b([\\d']+(\\.[\\d']*)?|\\.[\\d']+)(u|U|l|L|ul|UL|f|F|b|B)"},{begin:"(-?)(\\b0[xX][a-fA-F0-9']+|(\\b[\\d']+(\\.[\\d']*)?|\\.[\\d']+)([eE][-+]?[\\d']+)?)"}],relevance:0},s={className:"meta",begin:/#\s*[a-z]+\b/,end:/$/,keywords:{"meta-keyword":"if else elif endif define undef warning error line pragma _Pragma ifdef ifndef include"},contains:[{begin:/\\\n/,relevance:0},e.inherit(a,{className:"meta-string"}),{className:"meta-string",begin:/<.*?>/,end:/$/,illegal:"\\n"},e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},o={className:"title",begin:t("[a-zA-Z_]\\w*::")+e.IDENT_RE,relevance:0},c=t("[a-zA-Z_]\\w*::")+e.IDENT_RE+"\\s*\\(",l={keyword:"int float while private char char8_t char16_t char32_t catch import module export virtual operator sizeof dynamic_cast|10 typedef const_cast|10 const for static_cast|10 union namespace unsigned long volatile static protected bool template mutable if public friend do goto auto void enum else break extern using asm case typeid wchar_t short reinterpret_cast|10 default double register explicit signed typename try this switch continue inline delete alignas alignof constexpr consteval constinit decltype concept co_await co_return co_yield requires noexcept static_assert thread_local restrict final override atomic_bool atomic_char atomic_schar atomic_uchar atomic_short atomic_ushort atomic_int atomic_uint atomic_long atomic_ulong atomic_llong atomic_ullong new throw return and and_eq bitand bitor compl not not_eq or or_eq xor xor_eq",built_in:"std string wstring cin cout cerr clog stdin stdout stderr stringstream istringstream ostringstream auto_ptr deque list queue stack vector map set pair bitset multiset multimap unordered_set unordered_map unordered_multiset unordered_multimap priority_queue make_pair array shared_ptr abort terminate abs acos asin atan2 atan calloc ceil cosh cos exit exp fabs floor fmod fprintf fputs free frexp fscanf future isalnum isalpha iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit tolower toupper labs ldexp log10 log malloc realloc memchr memcmp memcpy memset modf pow printf putchar puts scanf sinh sin snprintf sprintf sqrt sscanf strcat strchr strcmp strcpy strcspn strlen strncat strncmp strncpy strpbrk strrchr strspn strstr tanh tan vfprintf vprintf vsprintf endl initializer_list unique_ptr _Bool complex _Complex imaginary _Imaginary",literal:"true false nullptr NULL"},d=[r,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,i,a],_={variants:[{begin:/=/,end:/;/},{begin:/\(/,end:/\)/},{beginKeywords:"new throw return else",end:/;/}],keywords:l,contains:d.concat([{begin:/\(/,end:/\)/,keywords:l,contains:d.concat(["self"]),relevance:0}]),relevance:0},u={className:"function",begin:"("+n+"[\\*&\\s]+)+"+c,returnBegin:!0,end:/[{;=]/,excludeEnd:!0,keywords:l,illegal:/[^\w\s\*&:<>]/,contains:[{begin:"decltype\\(auto\\)",keywords:l,relevance:0},{begin:c,returnBegin:!0,contains:[o],relevance:0},{className:"params",begin:/\(/,end:/\)/,keywords:l,relevance:0,contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,i,r,{begin:/\(/,end:/\)/,keywords:l,relevance:0,contains:["self",e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,i,r]}]},r,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,s]};return{aliases:["c","cc","h","c++","h++","hpp","hh","hxx","cxx"],keywords:l,disableAutodetect:!0,illegal:"",keywords:l,contains:["self",r]},{begin:e.IDENT_RE+"::",keywords:l},{className:"class",beginKeywords:"class struct",end:/[{;:]/,contains:[{begin://,contains:["self"]},e.TITLE_MODE]}]),exports:{preprocessor:s,strings:a,keywords:l}}}}()); +hljs.registerLanguage("c",function(){"use strict";return function(e){var n=e.getLanguage("c-like").rawDefinition();return n.name="C",n.aliases=["c","h"],n}}()); +hljs.registerLanguage("coffeescript",function(){"use strict";const e=["as","in","of","if","for","while","finally","var","new","function","do","return","void","else","break","catch","instanceof","with","throw","case","default","try","switch","continue","typeof","delete","let","yield","const","class","debugger","async","await","static","import","from","export","extends"],n=["true","false","null","undefined","NaN","Infinity"],a=[].concat(["setInterval","setTimeout","clearInterval","clearTimeout","require","exports","eval","isFinite","isNaN","parseFloat","parseInt","decodeURI","decodeURIComponent","encodeURI","encodeURIComponent","escape","unescape"],["arguments","this","super","console","window","document","localStorage","module","global"],["Intl","DataView","Number","Math","Date","String","RegExp","Object","Function","Boolean","Error","Symbol","Set","Map","WeakSet","WeakMap","Proxy","Reflect","JSON","Promise","Float64Array","Int16Array","Int32Array","Int8Array","Uint16Array","Uint32Array","Float32Array","Array","Uint8Array","Uint8ClampedArray","ArrayBuffer"],["EvalError","InternalError","RangeError","ReferenceError","SyntaxError","TypeError","URIError"]);return function(r){var t={keyword:e.concat(["then","unless","until","loop","by","when","and","or","is","isnt","not"]).filter((e=>n=>!e.includes(n))(["var","const","let","function","static"])).join(" "),literal:n.concat(["yes","no","on","off"]).join(" "),built_in:a.concat(["npm","print"]).join(" ")},i="[A-Za-z$_][0-9A-Za-z$_]*",s={className:"subst",begin:/#\{/,end:/}/,keywords:t},o=[r.BINARY_NUMBER_MODE,r.inherit(r.C_NUMBER_MODE,{starts:{end:"(\\s*/)?",relevance:0}}),{className:"string",variants:[{begin:/'''/,end:/'''/,contains:[r.BACKSLASH_ESCAPE]},{begin:/'/,end:/'/,contains:[r.BACKSLASH_ESCAPE]},{begin:/"""/,end:/"""/,contains:[r.BACKSLASH_ESCAPE,s]},{begin:/"/,end:/"/,contains:[r.BACKSLASH_ESCAPE,s]}]},{className:"regexp",variants:[{begin:"///",end:"///",contains:[s,r.HASH_COMMENT_MODE]},{begin:"//[gim]{0,3}(?=\\W)",relevance:0},{begin:/\/(?![ *]).*?(?![\\]).\/[gim]{0,3}(?=\W)/}]},{begin:"@"+i},{subLanguage:"javascript",excludeBegin:!0,excludeEnd:!0,variants:[{begin:"```",end:"```"},{begin:"`",end:"`"}]}];s.contains=o;var c=r.inherit(r.TITLE_MODE,{begin:i}),l={className:"params",begin:"\\([^\\(]",returnBegin:!0,contains:[{begin:/\(/,end:/\)/,keywords:t,contains:["self"].concat(o)}]};return{name:"CoffeeScript",aliases:["coffee","cson","iced"],keywords:t,illegal:/\/\*/,contains:o.concat([r.COMMENT("###","###"),r.HASH_COMMENT_MODE,{className:"function",begin:"^\\s*"+i+"\\s*=\\s*(\\(.*\\))?\\s*\\B[-=]>",end:"[-=]>",returnBegin:!0,contains:[c,l]},{begin:/[:\(,=]\s*/,relevance:0,contains:[{className:"function",begin:"(\\(.*\\))?\\s*\\B[-=]>",end:"[-=]>",returnBegin:!0,contains:[l]}]},{className:"class",beginKeywords:"class",end:"$",illegal:/[:="\[\]]/,contains:[{beginKeywords:"extends",endsWithParent:!0,illegal:/[:="\[\]]/,contains:[c]},c]},{begin:i+":",end:":",returnBegin:!0,returnEnd:!0,relevance:0}])}}}()); +hljs.registerLanguage("cpp",function(){"use strict";return function(e){var t=e.getLanguage("c-like").rawDefinition();return t.disableAutodetect=!1,t.name="C++",t.aliases=["cc","c++","h++","hpp","hh","hxx","cxx"],t}}()); +hljs.registerLanguage("csharp",function(){"use strict";return function(e){var n={keyword:"abstract as base bool break byte case catch char checked const continue decimal default delegate do double enum event explicit extern finally fixed float for foreach goto if implicit in int interface internal is lock long object operator out override params private protected public readonly ref sbyte sealed short sizeof stackalloc static string struct switch this try typeof uint ulong unchecked unsafe ushort using virtual void volatile while add alias ascending async await by descending dynamic equals from get global group into join let nameof on orderby partial remove select set value var when where yield",literal:"null false true"},i=e.inherit(e.TITLE_MODE,{begin:"[a-zA-Z](\\.?\\w)*"}),a={className:"number",variants:[{begin:"\\b(0b[01']+)"},{begin:"(-?)\\b([\\d']+(\\.[\\d']*)?|\\.[\\d']+)(u|U|l|L|ul|UL|f|F|b|B)"},{begin:"(-?)(\\b0[xX][a-fA-F0-9']+|(\\b[\\d']+(\\.[\\d']*)?|\\.[\\d']+)([eE][-+]?[\\d']+)?)"}],relevance:0},s={className:"string",begin:'@"',end:'"',contains:[{begin:'""'}]},t=e.inherit(s,{illegal:/\n/}),l={className:"subst",begin:"{",end:"}",keywords:n},r=e.inherit(l,{illegal:/\n/}),c={className:"string",begin:/\$"/,end:'"',illegal:/\n/,contains:[{begin:"{{"},{begin:"}}"},e.BACKSLASH_ESCAPE,r]},o={className:"string",begin:/\$@"/,end:'"',contains:[{begin:"{{"},{begin:"}}"},{begin:'""'},l]},g=e.inherit(o,{illegal:/\n/,contains:[{begin:"{{"},{begin:"}}"},{begin:'""'},r]});l.contains=[o,c,s,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,a,e.C_BLOCK_COMMENT_MODE],r.contains=[g,c,t,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,a,e.inherit(e.C_BLOCK_COMMENT_MODE,{illegal:/\n/})];var d={variants:[o,c,s,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE]},E={begin:"<",end:">",contains:[{beginKeywords:"in out"},i]},_=e.IDENT_RE+"(<"+e.IDENT_RE+"(\\s*,\\s*"+e.IDENT_RE+")*>)?(\\[\\])?",b={begin:"@"+e.IDENT_RE,relevance:0};return{name:"C#",aliases:["cs","c#"],keywords:n,illegal:/::/,contains:[e.COMMENT("///","$",{returnBegin:!0,contains:[{className:"doctag",variants:[{begin:"///",relevance:0},{begin:"\x3c!--|--\x3e"},{begin:""}]}]}),e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,{className:"meta",begin:"#",end:"$",keywords:{"meta-keyword":"if else elif endif define undef warning error line region endregion pragma checksum"}},d,a,{beginKeywords:"class interface",end:/[{;=]/,illegal:/[^\s:,]/,contains:[{beginKeywords:"where class"},i,E,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{beginKeywords:"namespace",end:/[{;=]/,illegal:/[^\s:]/,contains:[i,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{className:"meta",begin:"^\\s*\\[",excludeBegin:!0,end:"\\]",excludeEnd:!0,contains:[{className:"meta-string",begin:/"/,end:/"/}]},{beginKeywords:"new return throw await else",relevance:0},{className:"function",begin:"("+_+"\\s+)+"+e.IDENT_RE+"\\s*(\\<.+\\>)?\\s*\\(",returnBegin:!0,end:/\s*[{;=]/,excludeEnd:!0,keywords:n,contains:[{begin:e.IDENT_RE+"\\s*(\\<.+\\>)?\\s*\\(",returnBegin:!0,contains:[e.TITLE_MODE,E],relevance:0},{className:"params",begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,keywords:n,relevance:0,contains:[d,a,e.C_BLOCK_COMMENT_MODE]},e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},b]}}}()); +hljs.registerLanguage("css",function(){"use strict";return function(e){var n={begin:/(?:[A-Z\_\.\-]+|--[a-zA-Z0-9_-]+)\s*:/,returnBegin:!0,end:";",endsWithParent:!0,contains:[{className:"attribute",begin:/\S/,end:":",excludeEnd:!0,starts:{endsWithParent:!0,excludeEnd:!0,contains:[{begin:/[\w-]+\(/,returnBegin:!0,contains:[{className:"built_in",begin:/[\w-]+/},{begin:/\(/,end:/\)/,contains:[e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,e.CSS_NUMBER_MODE]}]},e.CSS_NUMBER_MODE,e.QUOTE_STRING_MODE,e.APOS_STRING_MODE,e.C_BLOCK_COMMENT_MODE,{className:"number",begin:"#[0-9A-Fa-f]+"},{className:"meta",begin:"!important"}]}}]};return{name:"CSS",case_insensitive:!0,illegal:/[=\/|'\$]/,contains:[e.C_BLOCK_COMMENT_MODE,{className:"selector-id",begin:/#[A-Za-z0-9_-]+/},{className:"selector-class",begin:/\.[A-Za-z0-9_-]+/},{className:"selector-attr",begin:/\[/,end:/\]/,illegal:"$",contains:[e.APOS_STRING_MODE,e.QUOTE_STRING_MODE]},{className:"selector-pseudo",begin:/:(:)?[a-zA-Z0-9\_\-\+\(\)"'.]+/},{begin:"@(page|font-face)",lexemes:"@[a-z-]+",keywords:"@page @font-face"},{begin:"@",end:"[{;]",illegal:/:/,returnBegin:!0,contains:[{className:"keyword",begin:/@\-?\w[\w]*(\-\w+)*/},{begin:/\s/,endsWithParent:!0,excludeEnd:!0,relevance:0,keywords:"and or not only",contains:[{begin:/[a-z-]+:/,className:"attribute"},e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,e.CSS_NUMBER_MODE]}]},{className:"selector-tag",begin:"[a-zA-Z-][a-zA-Z0-9_-]*",relevance:0},{begin:"{",end:"}",illegal:/\S/,contains:[e.C_BLOCK_COMMENT_MODE,n]}]}}}()); +hljs.registerLanguage("diff",function(){"use strict";return function(e){return{name:"Diff",aliases:["patch"],contains:[{className:"meta",relevance:10,variants:[{begin:/^@@ +\-\d+,\d+ +\+\d+,\d+ +@@$/},{begin:/^\*\*\* +\d+,\d+ +\*\*\*\*$/},{begin:/^\-\-\- +\d+,\d+ +\-\-\-\-$/}]},{className:"comment",variants:[{begin:/Index: /,end:/$/},{begin:/={3,}/,end:/$/},{begin:/^\-{3}/,end:/$/},{begin:/^\*{3} /,end:/$/},{begin:/^\+{3}/,end:/$/},{begin:/^\*{15}$/}]},{className:"addition",begin:"^\\+",end:"$"},{className:"deletion",begin:"^\\-",end:"$"},{className:"addition",begin:"^\\!",end:"$"}]}}}()); +hljs.registerLanguage("go",function(){"use strict";return function(e){var n={keyword:"break default func interface select case map struct chan else goto package switch const fallthrough if range type continue for import return var go defer bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 uint16 uint32 uint64 int uint uintptr rune",literal:"true false iota nil",built_in:"append cap close complex copy imag len make new panic print println real recover delete"};return{name:"Go",aliases:["golang"],keywords:n,illegal:"e(n)).join("")}return function(a){var s={className:"number",relevance:0,variants:[{begin:/([\+\-]+)?[\d]+_[\d_]+/},{begin:a.NUMBER_RE}]},i=a.COMMENT();i.variants=[{begin:/;/,end:/$/},{begin:/#/,end:/$/}];var t={className:"variable",variants:[{begin:/\$[\w\d"][\w\d_]*/},{begin:/\$\{(.*?)}/}]},r={className:"literal",begin:/\bon|off|true|false|yes|no\b/},l={className:"string",contains:[a.BACKSLASH_ESCAPE],variants:[{begin:"'''",end:"'''",relevance:10},{begin:'"""',end:'"""',relevance:10},{begin:'"',end:'"'},{begin:"'",end:"'"}]},c={begin:/\[/,end:/\]/,contains:[i,r,t,l,s,"self"],relevance:0},g="("+[/[A-Za-z0-9_-]+/,/"(\\"|[^"])*"/,/'[^']*'/].map(n=>e(n)).join("|")+")";return{name:"TOML, also INI",aliases:["toml"],case_insensitive:!0,illegal:/\S/,contains:[i,{className:"section",begin:/\[+/,end:/\]+/},{begin:n(g,"(\\s*\\.\\s*",g,")*",n("(?=",/\s*=\s*[^#\s]/,")")),className:"attr",starts:{end:/$/,contains:[i,c,r,t,l,s]}}]}}}()); +hljs.registerLanguage("java",function(){"use strict";function e(e){return e?"string"==typeof e?e:e.source:null}function n(e){return a("(",e,")?")}function a(...n){return n.map(n=>e(n)).join("")}function s(...n){return"("+n.map(n=>e(n)).join("|")+")"}return function(e){var t="false synchronized int abstract float private char boolean var static null if const for true while long strictfp finally protected import native final void enum else break transient catch instanceof byte super volatile case assert short package default double public try this switch continue throws protected public private module requires exports do",i={className:"meta",begin:"@[À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*",contains:[{begin:/\(/,end:/\)/,contains:["self"]}]},r=e=>a("[",e,"]+([",e,"_]*[",e,"]+)?"),c={className:"number",variants:[{begin:`\\b(0[bB]${r("01")})[lL]?`},{begin:`\\b(0${r("0-7")})[dDfFlL]?`},{begin:a(/\b0[xX]/,s(a(r("a-fA-F0-9"),/\./,r("a-fA-F0-9")),a(r("a-fA-F0-9"),/\.?/),a(/\./,r("a-fA-F0-9"))),/([pP][+-]?(\d+))?/,/[fFdDlL]?/)},{begin:a(/\b/,s(a(/\d*\./,r("\\d")),r("\\d")),/[eE][+-]?[\d]+[dDfF]?/)},{begin:a(/\b/,r(/\d/),n(/\.?/),n(r(/\d/)),/[dDfFlL]?/)}],relevance:0};return{name:"Java",aliases:["jsp"],keywords:t,illegal:/<\/|#/,contains:[e.COMMENT("/\\*\\*","\\*/",{relevance:0,contains:[{begin:/\w+@/,relevance:0},{className:"doctag",begin:"@[A-Za-z]+"}]}),e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,{className:"class",beginKeywords:"class interface",end:/[{;=]/,excludeEnd:!0,keywords:"class interface",illegal:/[:"\[\]]/,contains:[{beginKeywords:"extends implements"},e.UNDERSCORE_TITLE_MODE]},{beginKeywords:"new throw return else",relevance:0},{className:"function",begin:"([À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*(<[À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*(\\s*,\\s*[À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*)*>)?\\s+)+"+e.UNDERSCORE_IDENT_RE+"\\s*\\(",returnBegin:!0,end:/[{;=]/,excludeEnd:!0,keywords:t,contains:[{begin:e.UNDERSCORE_IDENT_RE+"\\s*\\(",returnBegin:!0,relevance:0,contains:[e.UNDERSCORE_TITLE_MODE]},{className:"params",begin:/\(/,end:/\)/,keywords:t,relevance:0,contains:[i,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,e.C_NUMBER_MODE,e.C_BLOCK_COMMENT_MODE]},e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},c,i]}}}()); +hljs.registerLanguage("javascript",function(){"use strict";const e=["as","in","of","if","for","while","finally","var","new","function","do","return","void","else","break","catch","instanceof","with","throw","case","default","try","switch","continue","typeof","delete","let","yield","const","class","debugger","async","await","static","import","from","export","extends"],n=["true","false","null","undefined","NaN","Infinity"],a=[].concat(["setInterval","setTimeout","clearInterval","clearTimeout","require","exports","eval","isFinite","isNaN","parseFloat","parseInt","decodeURI","decodeURIComponent","encodeURI","encodeURIComponent","escape","unescape"],["arguments","this","super","console","window","document","localStorage","module","global"],["Intl","DataView","Number","Math","Date","String","RegExp","Object","Function","Boolean","Error","Symbol","Set","Map","WeakSet","WeakMap","Proxy","Reflect","JSON","Promise","Float64Array","Int16Array","Int32Array","Int8Array","Uint16Array","Uint32Array","Float32Array","Array","Uint8Array","Uint8ClampedArray","ArrayBuffer"],["EvalError","InternalError","RangeError","ReferenceError","SyntaxError","TypeError","URIError"]);function s(e){return r("(?=",e,")")}function r(...e){return e.map(e=>(function(e){return e?"string"==typeof e?e:e.source:null})(e)).join("")}return function(t){var i="[A-Za-z$_][0-9A-Za-z$_]*",c={begin:/<[A-Za-z0-9\\._:-]+/,end:/\/[A-Za-z0-9\\._:-]+>|\/>/},o={$pattern:"[A-Za-z$_][0-9A-Za-z$_]*",keyword:e.join(" "),literal:n.join(" "),built_in:a.join(" ")},l={className:"number",variants:[{begin:"\\b(0[bB][01]+)n?"},{begin:"\\b(0[oO][0-7]+)n?"},{begin:t.C_NUMBER_RE+"n?"}],relevance:0},E={className:"subst",begin:"\\$\\{",end:"\\}",keywords:o,contains:[]},d={begin:"html`",end:"",starts:{end:"`",returnEnd:!1,contains:[t.BACKSLASH_ESCAPE,E],subLanguage:"xml"}},g={begin:"css`",end:"",starts:{end:"`",returnEnd:!1,contains:[t.BACKSLASH_ESCAPE,E],subLanguage:"css"}},u={className:"string",begin:"`",end:"`",contains:[t.BACKSLASH_ESCAPE,E]};E.contains=[t.APOS_STRING_MODE,t.QUOTE_STRING_MODE,d,g,u,l,t.REGEXP_MODE];var b=E.contains.concat([{begin:/\(/,end:/\)/,contains:["self"].concat(E.contains,[t.C_BLOCK_COMMENT_MODE,t.C_LINE_COMMENT_MODE])},t.C_BLOCK_COMMENT_MODE,t.C_LINE_COMMENT_MODE]),_={className:"params",begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,contains:b};return{name:"JavaScript",aliases:["js","jsx","mjs","cjs"],keywords:o,contains:[t.SHEBANG({binary:"node",relevance:5}),{className:"meta",relevance:10,begin:/^\s*['"]use (strict|asm)['"]/},t.APOS_STRING_MODE,t.QUOTE_STRING_MODE,d,g,u,t.C_LINE_COMMENT_MODE,t.COMMENT("/\\*\\*","\\*/",{relevance:0,contains:[{className:"doctag",begin:"@[A-Za-z]+",contains:[{className:"type",begin:"\\{",end:"\\}",relevance:0},{className:"variable",begin:i+"(?=\\s*(-)|$)",endsParent:!0,relevance:0},{begin:/(?=[^\n])\s/,relevance:0}]}]}),t.C_BLOCK_COMMENT_MODE,l,{begin:r(/[{,\n]\s*/,s(r(/(((\/\/.*)|(\/\*(.|\n)*\*\/))\s*)*/,i+"\\s*:"))),relevance:0,contains:[{className:"attr",begin:i+s("\\s*:"),relevance:0}]},{begin:"("+t.RE_STARTERS_RE+"|\\b(case|return|throw)\\b)\\s*",keywords:"return throw case",contains:[t.C_LINE_COMMENT_MODE,t.C_BLOCK_COMMENT_MODE,t.REGEXP_MODE,{className:"function",begin:"(\\([^(]*(\\([^(]*(\\([^(]*\\))?\\))?\\)|"+t.UNDERSCORE_IDENT_RE+")\\s*=>",returnBegin:!0,end:"\\s*=>",contains:[{className:"params",variants:[{begin:t.UNDERSCORE_IDENT_RE},{className:null,begin:/\(\s*\)/,skip:!0},{begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,keywords:o,contains:b}]}]},{begin:/,/,relevance:0},{className:"",begin:/\s/,end:/\s*/,skip:!0},{variants:[{begin:"<>",end:""},{begin:c.begin,end:c.end}],subLanguage:"xml",contains:[{begin:c.begin,end:c.end,skip:!0,contains:["self"]}]}],relevance:0},{className:"function",beginKeywords:"function",end:/\{/,excludeEnd:!0,contains:[t.inherit(t.TITLE_MODE,{begin:i}),_],illegal:/\[|%/},{begin:/\$[(.]/},t.METHOD_GUARD,{className:"class",beginKeywords:"class",end:/[{;=]/,excludeEnd:!0,illegal:/[:"\[\]]/,contains:[{beginKeywords:"extends"},t.UNDERSCORE_TITLE_MODE]},{beginKeywords:"constructor",end:/\{/,excludeEnd:!0},{begin:"(get|set)\\s+(?="+i+"\\()",end:/{/,keywords:"get set",contains:[t.inherit(t.TITLE_MODE,{begin:i}),{begin:/\(\)/},_]}],illegal:/#(?!!)/}}}()); +hljs.registerLanguage("json",function(){"use strict";return function(n){var e={literal:"true false null"},i=[n.C_LINE_COMMENT_MODE,n.C_BLOCK_COMMENT_MODE],t=[n.QUOTE_STRING_MODE,n.C_NUMBER_MODE],a={end:",",endsWithParent:!0,excludeEnd:!0,contains:t,keywords:e},l={begin:"{",end:"}",contains:[{className:"attr",begin:/"/,end:/"/,contains:[n.BACKSLASH_ESCAPE],illegal:"\\n"},n.inherit(a,{begin:/:/})].concat(i),illegal:"\\S"},s={begin:"\\[",end:"\\]",contains:[n.inherit(a)],illegal:"\\S"};return t.push(l,s),i.forEach((function(n){t.push(n)})),{name:"JSON",contains:t,keywords:e,illegal:"\\S"}}}()); +hljs.registerLanguage("kotlin",function(){"use strict";return function(e){var n={keyword:"abstract as val var vararg get set class object open private protected public noinline crossinline dynamic final enum if else do while for when throw try catch finally import package is in fun override companion reified inline lateinit init interface annotation data sealed internal infix operator out by constructor super tailrec where const inner suspend typealias external expect actual trait volatile transient native default",built_in:"Byte Short Char Int Long Boolean Float Double Void Unit Nothing",literal:"true false null"},a={className:"symbol",begin:e.UNDERSCORE_IDENT_RE+"@"},i={className:"subst",begin:"\\${",end:"}",contains:[e.C_NUMBER_MODE]},s={className:"variable",begin:"\\$"+e.UNDERSCORE_IDENT_RE},t={className:"string",variants:[{begin:'"""',end:'"""(?=[^"])',contains:[s,i]},{begin:"'",end:"'",illegal:/\n/,contains:[e.BACKSLASH_ESCAPE]},{begin:'"',end:'"',illegal:/\n/,contains:[e.BACKSLASH_ESCAPE,s,i]}]};i.contains.push(t);var r={className:"meta",begin:"@(?:file|property|field|get|set|receiver|param|setparam|delegate)\\s*:(?:\\s*"+e.UNDERSCORE_IDENT_RE+")?"},l={className:"meta",begin:"@"+e.UNDERSCORE_IDENT_RE,contains:[{begin:/\(/,end:/\)/,contains:[e.inherit(t,{className:"meta-string"})]}]},c=e.COMMENT("/\\*","\\*/",{contains:[e.C_BLOCK_COMMENT_MODE]}),o={variants:[{className:"type",begin:e.UNDERSCORE_IDENT_RE},{begin:/\(/,end:/\)/,contains:[]}]},d=o;return d.variants[1].contains=[o],o.variants[1].contains=[d],{name:"Kotlin",aliases:["kt"],keywords:n,contains:[e.COMMENT("/\\*\\*","\\*/",{relevance:0,contains:[{className:"doctag",begin:"@[A-Za-z]+"}]}),e.C_LINE_COMMENT_MODE,c,{className:"keyword",begin:/\b(break|continue|return|this)\b/,starts:{contains:[{className:"symbol",begin:/@\w+/}]}},a,r,l,{className:"function",beginKeywords:"fun",end:"[(]|$",returnBegin:!0,excludeEnd:!0,keywords:n,illegal:/fun\s+(<.*>)?[^\s\(]+(\s+[^\s\(]+)\s*=/,relevance:5,contains:[{begin:e.UNDERSCORE_IDENT_RE+"\\s*\\(",returnBegin:!0,relevance:0,contains:[e.UNDERSCORE_TITLE_MODE]},{className:"type",begin://,keywords:"reified",relevance:0},{className:"params",begin:/\(/,end:/\)/,endsParent:!0,keywords:n,relevance:0,contains:[{begin:/:/,end:/[=,\/]/,endsWithParent:!0,contains:[o,e.C_LINE_COMMENT_MODE,c],relevance:0},e.C_LINE_COMMENT_MODE,c,r,l,t,e.C_NUMBER_MODE]},c]},{className:"class",beginKeywords:"class interface trait",end:/[:\{(]|$/,excludeEnd:!0,illegal:"extends implements",contains:[{beginKeywords:"public protected internal private constructor"},e.UNDERSCORE_TITLE_MODE,{className:"type",begin://,excludeBegin:!0,excludeEnd:!0,relevance:0},{className:"type",begin:/[,:]\s*/,end:/[<\(,]|$/,excludeBegin:!0,returnEnd:!0},r,l]},t,{className:"meta",begin:"^#!/usr/bin/env",end:"$",illegal:"\n"},{className:"number",begin:"\\b(0[bB]([01]+[01_]+[01]+|[01]+)|0[xX]([a-fA-F0-9]+[a-fA-F0-9_]+[a-fA-F0-9]+|[a-fA-F0-9]+)|(([\\d]+[\\d_]+[\\d]+|[\\d]+)(\\.([\\d]+[\\d_]+[\\d]+|[\\d]+))?|\\.([\\d]+[\\d_]+[\\d]+|[\\d]+))([eE][-+]?\\d+)?)[lLfF]?",relevance:0}]}}}()); +hljs.registerLanguage("less",function(){"use strict";return function(e){var n="([\\w-]+|@{[\\w-]+})",a=[],s=[],t=function(e){return{className:"string",begin:"~?"+e+".*?"+e}},r=function(e,n,a){return{className:e,begin:n,relevance:a}},i={begin:"\\(",end:"\\)",contains:s,relevance:0};s.push(e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,t("'"),t('"'),e.CSS_NUMBER_MODE,{begin:"(url|data-uri)\\(",starts:{className:"string",end:"[\\)\\n]",excludeEnd:!0}},r("number","#[0-9A-Fa-f]+\\b"),i,r("variable","@@?[\\w-]+",10),r("variable","@{[\\w-]+}"),r("built_in","~?`[^`]*?`"),{className:"attribute",begin:"[\\w-]+\\s*:",end:":",returnBegin:!0,excludeEnd:!0},{className:"meta",begin:"!important"});var c=s.concat({begin:"{",end:"}",contains:a}),l={beginKeywords:"when",endsWithParent:!0,contains:[{beginKeywords:"and not"}].concat(s)},o={begin:n+"\\s*:",returnBegin:!0,end:"[;}]",relevance:0,contains:[{className:"attribute",begin:n,end:":",excludeEnd:!0,starts:{endsWithParent:!0,illegal:"[<=$]",relevance:0,contains:s}}]},g={className:"keyword",begin:"@(import|media|charset|font-face|(-[a-z]+-)?keyframes|supports|document|namespace|page|viewport|host)\\b",starts:{end:"[;{}]",returnEnd:!0,contains:s,relevance:0}},d={className:"variable",variants:[{begin:"@[\\w-]+\\s*:",relevance:15},{begin:"@[\\w-]+"}],starts:{end:"[;}]",returnEnd:!0,contains:c}},b={variants:[{begin:"[\\.#:&\\[>]",end:"[;{}]"},{begin:n,end:"{"}],returnBegin:!0,returnEnd:!0,illegal:"[<='$\"]",relevance:0,contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,l,r("keyword","all\\b"),r("variable","@{[\\w-]+}"),r("selector-tag",n+"%?",0),r("selector-id","#"+n),r("selector-class","\\."+n,0),r("selector-tag","&",0),{className:"selector-attr",begin:"\\[",end:"\\]"},{className:"selector-pseudo",begin:/:(:)?[a-zA-Z0-9\_\-\+\(\)"'.]+/},{begin:"\\(",end:"\\)",contains:c},{begin:"!important"}]};return a.push(e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,g,d,o,b),{name:"Less",case_insensitive:!0,illegal:"[=>'/<($\"]",contains:a}}}()); +hljs.registerLanguage("lua",function(){"use strict";return function(e){var t={begin:"\\[=*\\[",end:"\\]=*\\]",contains:["self"]},a=[e.COMMENT("--(?!\\[=*\\[)","$"),e.COMMENT("--\\[=*\\[","\\]=*\\]",{contains:[t],relevance:10})];return{name:"Lua",keywords:{$pattern:e.UNDERSCORE_IDENT_RE,literal:"true false nil",keyword:"and break do else elseif end for goto if in local not or repeat return then until while",built_in:"_G _ENV _VERSION __index __newindex __mode __call __metatable __tostring __len __gc __add __sub __mul __div __mod __pow __concat __unm __eq __lt __le assert collectgarbage dofile error getfenv getmetatable ipairs load loadfile loadstring module next pairs pcall print rawequal rawget rawset require select setfenv setmetatable tonumber tostring type unpack xpcall arg self coroutine resume yield status wrap create running debug getupvalue debug sethook getmetatable gethook setmetatable setlocal traceback setfenv getinfo setupvalue getlocal getregistry getfenv io lines write close flush open output type read stderr stdin input stdout popen tmpfile math log max acos huge ldexp pi cos tanh pow deg tan cosh sinh random randomseed frexp ceil floor rad abs sqrt modf asin min mod fmod log10 atan2 exp sin atan os exit setlocale date getenv difftime remove time clock tmpname rename execute package preload loadlib loaded loaders cpath config path seeall string sub upper len gfind rep find match char dump gmatch reverse byte format gsub lower table setn insert getn foreachi maxn foreach concat sort remove"},contains:a.concat([{className:"function",beginKeywords:"function",end:"\\)",contains:[e.inherit(e.TITLE_MODE,{begin:"([_a-zA-Z]\\w*\\.)*([_a-zA-Z]\\w*:)?[_a-zA-Z]\\w*"}),{className:"params",begin:"\\(",endsWithParent:!0,contains:a}].concat(a)},e.C_NUMBER_MODE,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,{className:"string",begin:"\\[=*\\[",end:"\\]=*\\]",contains:[t],relevance:5}])}}}()); +hljs.registerLanguage("makefile",function(){"use strict";return function(e){var i={className:"variable",variants:[{begin:"\\$\\("+e.UNDERSCORE_IDENT_RE+"\\)",contains:[e.BACKSLASH_ESCAPE]},{begin:/\$[@%`]+/}]}]}]};return{name:"HTML, XML",aliases:["html","xhtml","rss","atom","xjb","xsd","xsl","plist","wsf","svg"],case_insensitive:!0,contains:[{className:"meta",begin:"",relevance:10,contains:[a,i,t,s,{begin:"\\[",end:"\\]",contains:[{className:"meta",begin:"",contains:[a,s,i,t]}]}]},e.COMMENT("\x3c!--","--\x3e",{relevance:10}),{begin:"<\\!\\[CDATA\\[",end:"\\]\\]>",relevance:10},n,{className:"meta",begin:/<\?xml/,end:/\?>/,relevance:10},{className:"tag",begin:")",end:">",keywords:{name:"style"},contains:[c],starts:{end:"",returnEnd:!0,subLanguage:["css","xml"]}},{className:"tag",begin:")",end:">",keywords:{name:"script"},contains:[c],starts:{end:"<\/script>",returnEnd:!0,subLanguage:["javascript","handlebars","xml"]}},{className:"tag",begin:"",contains:[{className:"name",begin:/[^\/><\s]+/,relevance:0},c]}]}}}()); +hljs.registerLanguage("markdown",function(){"use strict";return function(n){const e={begin:"<",end:">",subLanguage:"xml",relevance:0},a={begin:"\\[.+?\\][\\(\\[].*?[\\)\\]]",returnBegin:!0,contains:[{className:"string",begin:"\\[",end:"\\]",excludeBegin:!0,returnEnd:!0,relevance:0},{className:"link",begin:"\\]\\(",end:"\\)",excludeBegin:!0,excludeEnd:!0},{className:"symbol",begin:"\\]\\[",end:"\\]",excludeBegin:!0,excludeEnd:!0}],relevance:10},i={className:"strong",contains:[],variants:[{begin:/_{2}/,end:/_{2}/},{begin:/\*{2}/,end:/\*{2}/}]},s={className:"emphasis",contains:[],variants:[{begin:/\*(?!\*)/,end:/\*/},{begin:/_(?!_)/,end:/_/,relevance:0}]};i.contains.push(s),s.contains.push(i);var c=[e,a];return i.contains=i.contains.concat(c),s.contains=s.contains.concat(c),{name:"Markdown",aliases:["md","mkdown","mkd"],contains:[{className:"section",variants:[{begin:"^#{1,6}",end:"$",contains:c=c.concat(i,s)},{begin:"(?=^.+?\\n[=-]{2,}$)",contains:[{begin:"^[=-]*$"},{begin:"^",end:"\\n",contains:c}]}]},e,{className:"bullet",begin:"^[ \t]*([*+-]|(\\d+\\.))(?=\\s+)",end:"\\s+",excludeEnd:!0},i,s,{className:"quote",begin:"^>\\s+",contains:c,end:"$"},{className:"code",variants:[{begin:"(`{3,})(.|\\n)*?\\1`*[ ]*"},{begin:"(~{3,})(.|\\n)*?\\1~*[ ]*"},{begin:"```",end:"```+[ ]*$"},{begin:"~~~",end:"~~~+[ ]*$"},{begin:"`.+?`"},{begin:"(?=^( {4}|\\t))",contains:[{begin:"^( {4}|\\t)",end:"(\\n)$"}],relevance:0}]},{begin:"^[-\\*]{3,}",end:"$"},a,{begin:/^\[[^\n]+\]:/,returnBegin:!0,contains:[{className:"symbol",begin:/\[/,end:/\]/,excludeBegin:!0,excludeEnd:!0},{className:"link",begin:/:\s*/,end:/$/,excludeBegin:!0}]}]}}}()); +hljs.registerLanguage("nginx",function(){"use strict";return function(e){var n={className:"variable",variants:[{begin:/\$\d+/},{begin:/\$\{/,end:/}/},{begin:"[\\$\\@]"+e.UNDERSCORE_IDENT_RE}]},a={endsWithParent:!0,keywords:{$pattern:"[a-z/_]+",literal:"on off yes no true false none blocked debug info notice warn error crit select break last permanent redirect kqueue rtsig epoll poll /dev/poll"},relevance:0,illegal:"=>",contains:[e.HASH_COMMENT_MODE,{className:"string",contains:[e.BACKSLASH_ESCAPE,n],variants:[{begin:/"/,end:/"/},{begin:/'/,end:/'/}]},{begin:"([a-z]+):/",end:"\\s",endsWithParent:!0,excludeEnd:!0,contains:[n]},{className:"regexp",contains:[e.BACKSLASH_ESCAPE,n],variants:[{begin:"\\s\\^",end:"\\s|{|;",returnEnd:!0},{begin:"~\\*?\\s+",end:"\\s|{|;",returnEnd:!0},{begin:"\\*(\\.[a-z\\-]+)+"},{begin:"([a-z\\-]+\\.)+\\*"}]},{className:"number",begin:"\\b\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}(:\\d{1,5})?\\b"},{className:"number",begin:"\\b\\d+[kKmMgGdshdwy]*\\b",relevance:0},n]};return{name:"Nginx config",aliases:["nginxconf"],contains:[e.HASH_COMMENT_MODE,{begin:e.UNDERSCORE_IDENT_RE+"\\s+{",returnBegin:!0,end:"{",contains:[{className:"section",begin:e.UNDERSCORE_IDENT_RE}],relevance:0},{begin:e.UNDERSCORE_IDENT_RE+"\\s",end:";|{",returnBegin:!0,contains:[{className:"attribute",begin:e.UNDERSCORE_IDENT_RE,starts:a}],relevance:0}],illegal:"[^\\s\\}]"}}}()); +hljs.registerLanguage("objectivec",function(){"use strict";return function(e){var n=/[a-zA-Z@][a-zA-Z0-9_]*/,_={$pattern:n,keyword:"@interface @class @protocol @implementation"};return{name:"Objective-C",aliases:["mm","objc","obj-c"],keywords:{$pattern:n,keyword:"int float while char export sizeof typedef const struct for union unsigned long volatile static bool mutable if do return goto void enum else break extern asm case short default double register explicit signed typename this switch continue wchar_t inline readonly assign readwrite self @synchronized id typeof nonatomic super unichar IBOutlet IBAction strong weak copy in out inout bycopy byref oneway __strong __weak __block __autoreleasing @private @protected @public @try @property @end @throw @catch @finally @autoreleasepool @synthesize @dynamic @selector @optional @required @encode @package @import @defs @compatibility_alias __bridge __bridge_transfer __bridge_retained __bridge_retain __covariant __contravariant __kindof _Nonnull _Nullable _Null_unspecified __FUNCTION__ __PRETTY_FUNCTION__ __attribute__ getter setter retain unsafe_unretained nonnull nullable null_unspecified null_resettable class instancetype NS_DESIGNATED_INITIALIZER NS_UNAVAILABLE NS_REQUIRES_SUPER NS_RETURNS_INNER_POINTER NS_INLINE NS_AVAILABLE NS_DEPRECATED NS_ENUM NS_OPTIONS NS_SWIFT_UNAVAILABLE NS_ASSUME_NONNULL_BEGIN NS_ASSUME_NONNULL_END NS_REFINED_FOR_SWIFT NS_SWIFT_NAME NS_SWIFT_NOTHROW NS_DURING NS_HANDLER NS_ENDHANDLER NS_VALUERETURN NS_VOIDRETURN",literal:"false true FALSE TRUE nil YES NO NULL",built_in:"BOOL dispatch_once_t dispatch_queue_t dispatch_sync dispatch_async dispatch_once"},illegal:"/,end:/$/,illegal:"\\n"},e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{className:"class",begin:"("+_.keyword.split(" ").join("|")+")\\b",end:"({|$)",excludeEnd:!0,keywords:_,contains:[e.UNDERSCORE_TITLE_MODE]},{begin:"\\."+e.UNDERSCORE_IDENT_RE,relevance:0}]}}}()); +hljs.registerLanguage("perl",function(){"use strict";return function(e){var n={$pattern:/[\w.]+/,keyword:"getpwent getservent quotemeta msgrcv scalar kill dbmclose undef lc ma syswrite tr send umask sysopen shmwrite vec qx utime local oct semctl localtime readpipe do return format read sprintf dbmopen pop getpgrp not getpwnam rewinddir qq fileno qw endprotoent wait sethostent bless s|0 opendir continue each sleep endgrent shutdown dump chomp connect getsockname die socketpair close flock exists index shmget sub for endpwent redo lstat msgctl setpgrp abs exit select print ref gethostbyaddr unshift fcntl syscall goto getnetbyaddr join gmtime symlink semget splice x|0 getpeername recv log setsockopt cos last reverse gethostbyname getgrnam study formline endhostent times chop length gethostent getnetent pack getprotoent getservbyname rand mkdir pos chmod y|0 substr endnetent printf next open msgsnd readdir use unlink getsockopt getpriority rindex wantarray hex system getservbyport endservent int chr untie rmdir prototype tell listen fork shmread ucfirst setprotoent else sysseek link getgrgid shmctl waitpid unpack getnetbyname reset chdir grep split require caller lcfirst until warn while values shift telldir getpwuid my getprotobynumber delete and sort uc defined srand accept package seekdir getprotobyname semop our rename seek if q|0 chroot sysread setpwent no crypt getc chown sqrt write setnetent setpriority foreach tie sin msgget map stat getlogin unless elsif truncate exec keys glob tied closedir ioctl socket readlink eval xor readline binmode setservent eof ord bind alarm pipe atan2 getgrent exp time push setgrent gt lt or ne m|0 break given say state when"},t={className:"subst",begin:"[$@]\\{",end:"\\}",keywords:n},s={begin:"->{",end:"}"},r={variants:[{begin:/\$\d/},{begin:/[\$%@](\^\w\b|#\w+(::\w+)*|{\w+}|\w+(::\w*)*)/},{begin:/[\$%@][^\s\w{]/,relevance:0}]},i=[e.BACKSLASH_ESCAPE,t,r],a=[r,e.HASH_COMMENT_MODE,e.COMMENT("^\\=\\w","\\=cut",{endsWithParent:!0}),s,{className:"string",contains:i,variants:[{begin:"q[qwxr]?\\s*\\(",end:"\\)",relevance:5},{begin:"q[qwxr]?\\s*\\[",end:"\\]",relevance:5},{begin:"q[qwxr]?\\s*\\{",end:"\\}",relevance:5},{begin:"q[qwxr]?\\s*\\|",end:"\\|",relevance:5},{begin:"q[qwxr]?\\s*\\<",end:"\\>",relevance:5},{begin:"qw\\s+q",end:"q",relevance:5},{begin:"'",end:"'",contains:[e.BACKSLASH_ESCAPE]},{begin:'"',end:'"'},{begin:"`",end:"`",contains:[e.BACKSLASH_ESCAPE]},{begin:"{\\w+}",contains:[],relevance:0},{begin:"-?\\w+\\s*\\=\\>",contains:[],relevance:0}]},{className:"number",begin:"(\\b0[0-7_]+)|(\\b0x[0-9a-fA-F_]+)|(\\b[1-9][0-9_]*(\\.[0-9_]+)?)|[0_]\\b",relevance:0},{begin:"(\\/\\/|"+e.RE_STARTERS_RE+"|\\b(split|return|print|reverse|grep)\\b)\\s*",keywords:"split return print reverse grep",relevance:0,contains:[e.HASH_COMMENT_MODE,{className:"regexp",begin:"(s|tr|y)/(\\\\.|[^/])*/(\\\\.|[^/])*/[a-z]*",relevance:10},{className:"regexp",begin:"(m|qr)?/",end:"/[a-z]*",contains:[e.BACKSLASH_ESCAPE],relevance:0}]},{className:"function",beginKeywords:"sub",end:"(\\s*\\(.*?\\))?[;{]",excludeEnd:!0,relevance:5,contains:[e.TITLE_MODE]},{begin:"-\\w\\b",relevance:0},{begin:"^__DATA__$",end:"^__END__$",subLanguage:"mojolicious",contains:[{begin:"^@@.*",end:"$",className:"comment"}]}];return t.contains=a,s.contains=a,{name:"Perl",aliases:["pl","pm"],keywords:n,contains:a}}}()); +hljs.registerLanguage("php",function(){"use strict";return function(e){var r={begin:"\\$+[a-zA-Z_-ÿ][a-zA-Z0-9_-ÿ]*"},t={className:"meta",variants:[{begin:/<\?php/,relevance:10},{begin:/<\?[=]?/},{begin:/\?>/}]},a={className:"string",contains:[e.BACKSLASH_ESCAPE,t],variants:[{begin:'b"',end:'"'},{begin:"b'",end:"'"},e.inherit(e.APOS_STRING_MODE,{illegal:null}),e.inherit(e.QUOTE_STRING_MODE,{illegal:null})]},n={variants:[e.BINARY_NUMBER_MODE,e.C_NUMBER_MODE]},i={keyword:"__CLASS__ __DIR__ __FILE__ __FUNCTION__ __LINE__ __METHOD__ __NAMESPACE__ __TRAIT__ die echo exit include include_once print require require_once array abstract and as binary bool boolean break callable case catch class clone const continue declare default do double else elseif empty enddeclare endfor endforeach endif endswitch endwhile eval extends final finally float for foreach from global goto if implements instanceof insteadof int integer interface isset iterable list new object or private protected public real return string switch throw trait try unset use var void while xor yield",literal:"false null true",built_in:"Error|0 AppendIterator ArgumentCountError ArithmeticError ArrayIterator ArrayObject AssertionError BadFunctionCallException BadMethodCallException CachingIterator CallbackFilterIterator CompileError Countable DirectoryIterator DivisionByZeroError DomainException EmptyIterator ErrorException Exception FilesystemIterator FilterIterator GlobIterator InfiniteIterator InvalidArgumentException IteratorIterator LengthException LimitIterator LogicException MultipleIterator NoRewindIterator OutOfBoundsException OutOfRangeException OuterIterator OverflowException ParentIterator ParseError RangeException RecursiveArrayIterator RecursiveCachingIterator RecursiveCallbackFilterIterator RecursiveDirectoryIterator RecursiveFilterIterator RecursiveIterator RecursiveIteratorIterator RecursiveRegexIterator RecursiveTreeIterator RegexIterator RuntimeException SeekableIterator SplDoublyLinkedList SplFileInfo SplFileObject SplFixedArray SplHeap SplMaxHeap SplMinHeap SplObjectStorage SplObserver SplObserver SplPriorityQueue SplQueue SplStack SplSubject SplSubject SplTempFileObject TypeError UnderflowException UnexpectedValueException ArrayAccess Closure Generator Iterator IteratorAggregate Serializable Throwable Traversable WeakReference Directory __PHP_Incomplete_Class parent php_user_filter self static stdClass"};return{aliases:["php","php3","php4","php5","php6","php7"],case_insensitive:!0,keywords:i,contains:[e.HASH_COMMENT_MODE,e.COMMENT("//","$",{contains:[t]}),e.COMMENT("/\\*","\\*/",{contains:[{className:"doctag",begin:"@[A-Za-z]+"}]}),e.COMMENT("__halt_compiler.+?;",!1,{endsWithParent:!0,keywords:"__halt_compiler"}),{className:"string",begin:/<<<['"]?\w+['"]?$/,end:/^\w+;?$/,contains:[e.BACKSLASH_ESCAPE,{className:"subst",variants:[{begin:/\$\w+/},{begin:/\{\$/,end:/\}/}]}]},t,{className:"keyword",begin:/\$this\b/},r,{begin:/(::|->)+[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*/},{className:"function",beginKeywords:"fn function",end:/[;{]/,excludeEnd:!0,illegal:"[$%\\[]",contains:[e.UNDERSCORE_TITLE_MODE,{className:"params",begin:"\\(",end:"\\)",excludeBegin:!0,excludeEnd:!0,keywords:i,contains:["self",r,e.C_BLOCK_COMMENT_MODE,a,n]}]},{className:"class",beginKeywords:"class interface",end:"{",excludeEnd:!0,illegal:/[:\(\$"]/,contains:[{beginKeywords:"extends implements"},e.UNDERSCORE_TITLE_MODE]},{beginKeywords:"namespace",end:";",illegal:/[\.']/,contains:[e.UNDERSCORE_TITLE_MODE]},{beginKeywords:"use",end:";",contains:[e.UNDERSCORE_TITLE_MODE]},{begin:"=>"},a,n]}}}()); +hljs.registerLanguage("php-template",function(){"use strict";return function(n){return{name:"PHP template",subLanguage:"xml",contains:[{begin:/<\?(php|=)?/,end:/\?>/,subLanguage:"php",contains:[{begin:"/\\*",end:"\\*/",skip:!0},{begin:'b"',end:'"',skip:!0},{begin:"b'",end:"'",skip:!0},n.inherit(n.APOS_STRING_MODE,{illegal:null,className:null,contains:null,skip:!0}),n.inherit(n.QUOTE_STRING_MODE,{illegal:null,className:null,contains:null,skip:!0})]}]}}}()); +hljs.registerLanguage("plaintext",function(){"use strict";return function(t){return{name:"Plain text",aliases:["text","txt"],disableAutodetect:!0}}}()); +hljs.registerLanguage("properties",function(){"use strict";return function(e){var n="[ \\t\\f]*",t="("+n+"[:=]"+n+"|[ \\t\\f]+)",a="([^\\\\:= \\t\\f\\n]|\\\\.)+",s={end:t,relevance:0,starts:{className:"string",end:/$/,relevance:0,contains:[{begin:"\\\\\\n"}]}};return{name:".properties",case_insensitive:!0,illegal:/\S/,contains:[e.COMMENT("^\\s*[!#]","$"),{begin:"([^\\\\\\W:= \\t\\f\\n]|\\\\.)+"+t,returnBegin:!0,contains:[{className:"attr",begin:"([^\\\\\\W:= \\t\\f\\n]|\\\\.)+",endsParent:!0,relevance:0}],starts:s},{begin:a+t,returnBegin:!0,relevance:0,contains:[{className:"meta",begin:a,endsParent:!0,relevance:0}],starts:s},{className:"attr",relevance:0,begin:a+n+"$"}]}}}()); +hljs.registerLanguage("python",function(){"use strict";return function(e){var n={keyword:"and elif is global as in if from raise for except finally print import pass return exec else break not with class assert yield try while continue del or def lambda async await nonlocal|10",built_in:"Ellipsis NotImplemented",literal:"False None True"},a={className:"meta",begin:/^(>>>|\.\.\.) /},i={className:"subst",begin:/\{/,end:/\}/,keywords:n,illegal:/#/},s={begin:/\{\{/,relevance:0},r={className:"string",contains:[e.BACKSLASH_ESCAPE],variants:[{begin:/(u|b)?r?'''/,end:/'''/,contains:[e.BACKSLASH_ESCAPE,a],relevance:10},{begin:/(u|b)?r?"""/,end:/"""/,contains:[e.BACKSLASH_ESCAPE,a],relevance:10},{begin:/(fr|rf|f)'''/,end:/'''/,contains:[e.BACKSLASH_ESCAPE,a,s,i]},{begin:/(fr|rf|f)"""/,end:/"""/,contains:[e.BACKSLASH_ESCAPE,a,s,i]},{begin:/(u|r|ur)'/,end:/'/,relevance:10},{begin:/(u|r|ur)"/,end:/"/,relevance:10},{begin:/(b|br)'/,end:/'/},{begin:/(b|br)"/,end:/"/},{begin:/(fr|rf|f)'/,end:/'/,contains:[e.BACKSLASH_ESCAPE,s,i]},{begin:/(fr|rf|f)"/,end:/"/,contains:[e.BACKSLASH_ESCAPE,s,i]},e.APOS_STRING_MODE,e.QUOTE_STRING_MODE]},l={className:"number",relevance:0,variants:[{begin:e.BINARY_NUMBER_RE+"[lLjJ]?"},{begin:"\\b(0o[0-7]+)[lLjJ]?"},{begin:e.C_NUMBER_RE+"[lLjJ]?"}]},t={className:"params",variants:[{begin:/\(\s*\)/,skip:!0,className:null},{begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,contains:["self",a,l,r,e.HASH_COMMENT_MODE]}]};return i.contains=[r,l,a],{name:"Python",aliases:["py","gyp","ipython"],keywords:n,illegal:/(<\/|->|\?)|=>/,contains:[a,l,{beginKeywords:"if",relevance:0},r,e.HASH_COMMENT_MODE,{variants:[{className:"function",beginKeywords:"def"},{className:"class",beginKeywords:"class"}],end:/:/,illegal:/[${=;\n,]/,contains:[e.UNDERSCORE_TITLE_MODE,t,{begin:/->/,endsWithParent:!0,keywords:"None"}]},{className:"meta",begin:/^[\t ]*@/,end:/$/},{begin:/\b(print|exec)\(/}]}}}()); +hljs.registerLanguage("python-repl",function(){"use strict";return function(n){return{aliases:["pycon"],contains:[{className:"meta",starts:{end:/ |$/,starts:{end:"$",subLanguage:"python"}},variants:[{begin:/^>>>(?=[ ]|$)/},{begin:/^\.\.\.(?=[ ]|$)/}]}]}}}()); +hljs.registerLanguage("ruby",function(){"use strict";return function(e){var n="[a-zA-Z_]\\w*[!?=]?|[-+~]\\@|<<|>>|=~|===?|<=>|[<>]=?|\\*\\*|[-/+%^&*~`|]|\\[\\]=?",a={keyword:"and then defined module in return redo if BEGIN retry end for self when next until do begin unless END rescue else break undef not super class case require yield alias while ensure elsif or include attr_reader attr_writer attr_accessor",literal:"true false nil"},s={className:"doctag",begin:"@[A-Za-z]+"},i={begin:"#<",end:">"},r=[e.COMMENT("#","$",{contains:[s]}),e.COMMENT("^\\=begin","^\\=end",{contains:[s],relevance:10}),e.COMMENT("^__END__","\\n$")],c={className:"subst",begin:"#\\{",end:"}",keywords:a},t={className:"string",contains:[e.BACKSLASH_ESCAPE,c],variants:[{begin:/'/,end:/'/},{begin:/"/,end:/"/},{begin:/`/,end:/`/},{begin:"%[qQwWx]?\\(",end:"\\)"},{begin:"%[qQwWx]?\\[",end:"\\]"},{begin:"%[qQwWx]?{",end:"}"},{begin:"%[qQwWx]?<",end:">"},{begin:"%[qQwWx]?/",end:"/"},{begin:"%[qQwWx]?%",end:"%"},{begin:"%[qQwWx]?-",end:"-"},{begin:"%[qQwWx]?\\|",end:"\\|"},{begin:/\B\?(\\\d{1,3}|\\x[A-Fa-f0-9]{1,2}|\\u[A-Fa-f0-9]{4}|\\?\S)\b/},{begin:/<<[-~]?'?(\w+)(?:.|\n)*?\n\s*\1\b/,returnBegin:!0,contains:[{begin:/<<[-~]?'?/},e.END_SAME_AS_BEGIN({begin:/(\w+)/,end:/(\w+)/,contains:[e.BACKSLASH_ESCAPE,c]})]}]},b={className:"params",begin:"\\(",end:"\\)",endsParent:!0,keywords:a},d=[t,i,{className:"class",beginKeywords:"class module",end:"$|;",illegal:/=/,contains:[e.inherit(e.TITLE_MODE,{begin:"[A-Za-z_]\\w*(::\\w+)*(\\?|\\!)?"}),{begin:"<\\s*",contains:[{begin:"("+e.IDENT_RE+"::)?"+e.IDENT_RE}]}].concat(r)},{className:"function",beginKeywords:"def",end:"$|;",contains:[e.inherit(e.TITLE_MODE,{begin:n}),b].concat(r)},{begin:e.IDENT_RE+"::"},{className:"symbol",begin:e.UNDERSCORE_IDENT_RE+"(\\!|\\?)?:",relevance:0},{className:"symbol",begin:":(?!\\s)",contains:[t,{begin:n}],relevance:0},{className:"number",begin:"(\\b0[0-7_]+)|(\\b0x[0-9a-fA-F_]+)|(\\b[1-9][0-9_]*(\\.[0-9_]+)?)|[0_]\\b",relevance:0},{begin:"(\\$\\W)|((\\$|\\@\\@?)(\\w+))"},{className:"params",begin:/\|/,end:/\|/,keywords:a},{begin:"("+e.RE_STARTERS_RE+"|unless)\\s*",keywords:"unless",contains:[i,{className:"regexp",contains:[e.BACKSLASH_ESCAPE,c],illegal:/\n/,variants:[{begin:"/",end:"/[a-z]*"},{begin:"%r{",end:"}[a-z]*"},{begin:"%r\\(",end:"\\)[a-z]*"},{begin:"%r!",end:"![a-z]*"},{begin:"%r\\[",end:"\\][a-z]*"}]}].concat(r),relevance:0}].concat(r);c.contains=d,b.contains=d;var g=[{begin:/^\s*=>/,starts:{end:"$",contains:d}},{className:"meta",begin:"^([>?]>|[\\w#]+\\(\\w+\\):\\d+:\\d+>|(\\w+-)?\\d+\\.\\d+\\.\\d(p\\d+)?[^>]+>)",starts:{end:"$",contains:d}}];return{name:"Ruby",aliases:["rb","gemspec","podspec","thor","irb"],keywords:a,illegal:/\/\*/,contains:r.concat(g).concat(d)}}}()); +hljs.registerLanguage("rust",function(){"use strict";return function(e){var n="([ui](8|16|32|64|128|size)|f(32|64))?",t="drop i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize f32 f64 str char bool Box Option Result String Vec Copy Send Sized Sync Drop Fn FnMut FnOnce ToOwned Clone Debug PartialEq PartialOrd Eq Ord AsRef AsMut Into From Default Iterator Extend IntoIterator DoubleEndedIterator ExactSizeIterator SliceConcatExt ToString assert! assert_eq! bitflags! bytes! cfg! col! concat! concat_idents! debug_assert! debug_assert_eq! env! panic! file! format! format_args! include_bin! include_str! line! local_data_key! module_path! option_env! print! println! select! stringify! try! unimplemented! unreachable! vec! write! writeln! macro_rules! assert_ne! debug_assert_ne!";return{name:"Rust",aliases:["rs"],keywords:{$pattern:e.IDENT_RE+"!?",keyword:"abstract as async await become box break const continue crate do dyn else enum extern false final fn for if impl in let loop macro match mod move mut override priv pub ref return self Self static struct super trait true try type typeof unsafe unsized use virtual where while yield",literal:"true false Some None Ok Err",built_in:t},illegal:""}]}}}()); +hljs.registerLanguage("scss",function(){"use strict";return function(e){var t={className:"variable",begin:"(\\$[a-zA-Z-][a-zA-Z0-9_-]*)\\b"},i={className:"number",begin:"#[0-9A-Fa-f]+"};return e.CSS_NUMBER_MODE,e.QUOTE_STRING_MODE,e.APOS_STRING_MODE,e.C_BLOCK_COMMENT_MODE,{name:"SCSS",case_insensitive:!0,illegal:"[=/|']",contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,{className:"selector-id",begin:"\\#[A-Za-z0-9_-]+",relevance:0},{className:"selector-class",begin:"\\.[A-Za-z0-9_-]+",relevance:0},{className:"selector-attr",begin:"\\[",end:"\\]",illegal:"$"},{className:"selector-tag",begin:"\\b(a|abbr|acronym|address|area|article|aside|audio|b|base|big|blockquote|body|br|button|canvas|caption|cite|code|col|colgroup|command|datalist|dd|del|details|dfn|div|dl|dt|em|embed|fieldset|figcaption|figure|footer|form|frame|frameset|(h[1-6])|head|header|hgroup|hr|html|i|iframe|img|input|ins|kbd|keygen|label|legend|li|link|map|mark|meta|meter|nav|noframes|noscript|object|ol|optgroup|option|output|p|param|pre|progress|q|rp|rt|ruby|samp|script|section|select|small|span|strike|strong|style|sub|sup|table|tbody|td|textarea|tfoot|th|thead|time|title|tr|tt|ul|var|video)\\b",relevance:0},{className:"selector-pseudo",begin:":(visited|valid|root|right|required|read-write|read-only|out-range|optional|only-of-type|only-child|nth-of-type|nth-last-of-type|nth-last-child|nth-child|not|link|left|last-of-type|last-child|lang|invalid|indeterminate|in-range|hover|focus|first-of-type|first-line|first-letter|first-child|first|enabled|empty|disabled|default|checked|before|after|active)"},{className:"selector-pseudo",begin:"::(after|before|choices|first-letter|first-line|repeat-index|repeat-item|selection|value)"},t,{className:"attribute",begin:"\\b(src|z-index|word-wrap|word-spacing|word-break|width|widows|white-space|visibility|vertical-align|unicode-bidi|transition-timing-function|transition-property|transition-duration|transition-delay|transition|transform-style|transform-origin|transform|top|text-underline-position|text-transform|text-shadow|text-rendering|text-overflow|text-indent|text-decoration-style|text-decoration-line|text-decoration-color|text-decoration|text-align-last|text-align|tab-size|table-layout|right|resize|quotes|position|pointer-events|perspective-origin|perspective|page-break-inside|page-break-before|page-break-after|padding-top|padding-right|padding-left|padding-bottom|padding|overflow-y|overflow-x|overflow-wrap|overflow|outline-width|outline-style|outline-offset|outline-color|outline|orphans|order|opacity|object-position|object-fit|normal|none|nav-up|nav-right|nav-left|nav-index|nav-down|min-width|min-height|max-width|max-height|mask|marks|margin-top|margin-right|margin-left|margin-bottom|margin|list-style-type|list-style-position|list-style-image|list-style|line-height|letter-spacing|left|justify-content|initial|inherit|ime-mode|image-orientation|image-resolution|image-rendering|icon|hyphens|height|font-weight|font-variant-ligatures|font-variant|font-style|font-stretch|font-size-adjust|font-size|font-language-override|font-kerning|font-feature-settings|font-family|font|float|flex-wrap|flex-shrink|flex-grow|flex-flow|flex-direction|flex-basis|flex|filter|empty-cells|display|direction|cursor|counter-reset|counter-increment|content|column-width|column-span|column-rule-width|column-rule-style|column-rule-color|column-rule|column-gap|column-fill|column-count|columns|color|clip-path|clip|clear|caption-side|break-inside|break-before|break-after|box-sizing|box-shadow|box-decoration-break|bottom|border-width|border-top-width|border-top-style|border-top-right-radius|border-top-left-radius|border-top-color|border-top|border-style|border-spacing|border-right-width|border-right-style|border-right-color|border-right|border-radius|border-left-width|border-left-style|border-left-color|border-left|border-image-width|border-image-source|border-image-slice|border-image-repeat|border-image-outset|border-image|border-color|border-collapse|border-bottom-width|border-bottom-style|border-bottom-right-radius|border-bottom-left-radius|border-bottom-color|border-bottom|border|background-size|background-repeat|background-position|background-origin|background-image|background-color|background-clip|background-attachment|background-blend-mode|background|backface-visibility|auto|animation-timing-function|animation-play-state|animation-name|animation-iteration-count|animation-fill-mode|animation-duration|animation-direction|animation-delay|animation|align-self|align-items|align-content)\\b",illegal:"[^\\s]"},{begin:"\\b(whitespace|wait|w-resize|visible|vertical-text|vertical-ideographic|uppercase|upper-roman|upper-alpha|underline|transparent|top|thin|thick|text|text-top|text-bottom|tb-rl|table-header-group|table-footer-group|sw-resize|super|strict|static|square|solid|small-caps|separate|se-resize|scroll|s-resize|rtl|row-resize|ridge|right|repeat|repeat-y|repeat-x|relative|progress|pointer|overline|outside|outset|oblique|nowrap|not-allowed|normal|none|nw-resize|no-repeat|no-drop|newspaper|ne-resize|n-resize|move|middle|medium|ltr|lr-tb|lowercase|lower-roman|lower-alpha|loose|list-item|line|line-through|line-edge|lighter|left|keep-all|justify|italic|inter-word|inter-ideograph|inside|inset|inline|inline-block|inherit|inactive|ideograph-space|ideograph-parenthesis|ideograph-numeric|ideograph-alpha|horizontal|hidden|help|hand|groove|fixed|ellipsis|e-resize|double|dotted|distribute|distribute-space|distribute-letter|distribute-all-lines|disc|disabled|default|decimal|dashed|crosshair|collapse|col-resize|circle|char|center|capitalize|break-word|break-all|bottom|both|bolder|bold|block|bidi-override|below|baseline|auto|always|all-scroll|absolute|table|table-cell)\\b"},{begin:":",end:";",contains:[t,i,e.CSS_NUMBER_MODE,e.QUOTE_STRING_MODE,e.APOS_STRING_MODE,{className:"meta",begin:"!important"}]},{begin:"@(page|font-face)",lexemes:"@[a-z-]+",keywords:"@page @font-face"},{begin:"@",end:"[{;]",returnBegin:!0,keywords:"and or not only",contains:[{begin:"@[a-z-]+",className:"keyword"},t,e.QUOTE_STRING_MODE,e.APOS_STRING_MODE,i,e.CSS_NUMBER_MODE]}]}}}()); +hljs.registerLanguage("shell",function(){"use strict";return function(s){return{name:"Shell Session",aliases:["console"],contains:[{className:"meta",begin:"^\\s{0,3}[/\\w\\d\\[\\]()@-]*[>%$#]",starts:{end:"$",subLanguage:"bash"}}]}}}()); +hljs.registerLanguage("sql",function(){"use strict";return function(e){var t=e.COMMENT("--","$");return{name:"SQL",case_insensitive:!0,illegal:/[<>{}*]/,contains:[{beginKeywords:"begin end start commit rollback savepoint lock alter create drop rename call delete do handler insert load replace select truncate update set show pragma grant merge describe use explain help declare prepare execute deallocate release unlock purge reset change stop analyze cache flush optimize repair kill install uninstall checksum restore check backup revoke comment values with",end:/;/,endsWithParent:!0,keywords:{$pattern:/[\w\.]+/,keyword:"as abort abs absolute acc acce accep accept access accessed accessible account acos action activate add addtime admin administer advanced advise aes_decrypt aes_encrypt after agent aggregate ali alia alias all allocate allow alter always analyze ancillary and anti any anydata anydataset anyschema anytype apply archive archived archivelog are as asc ascii asin assembly assertion associate asynchronous at atan atn2 attr attri attrib attribu attribut attribute attributes audit authenticated authentication authid authors auto autoallocate autodblink autoextend automatic availability avg backup badfile basicfile before begin beginning benchmark between bfile bfile_base big bigfile bin binary_double binary_float binlog bit_and bit_count bit_length bit_or bit_xor bitmap blob_base block blocksize body both bound bucket buffer_cache buffer_pool build bulk by byte byteordermark bytes cache caching call calling cancel capacity cascade cascaded case cast catalog category ceil ceiling chain change changed char_base char_length character_length characters characterset charindex charset charsetform charsetid check checksum checksum_agg child choose chr chunk class cleanup clear client clob clob_base clone close cluster_id cluster_probability cluster_set clustering coalesce coercibility col collate collation collect colu colum column column_value columns columns_updated comment commit compact compatibility compiled complete composite_limit compound compress compute concat concat_ws concurrent confirm conn connec connect connect_by_iscycle connect_by_isleaf connect_by_root connect_time connection consider consistent constant constraint constraints constructor container content contents context contributors controlfile conv convert convert_tz corr corr_k corr_s corresponding corruption cos cost count count_big counted covar_pop covar_samp cpu_per_call cpu_per_session crc32 create creation critical cross cube cume_dist curdate current current_date current_time current_timestamp current_user cursor curtime customdatum cycle data database databases datafile datafiles datalength date_add date_cache date_format date_sub dateadd datediff datefromparts datename datepart datetime2fromparts day day_to_second dayname dayofmonth dayofweek dayofyear days db_role_change dbtimezone ddl deallocate declare decode decompose decrement decrypt deduplicate def defa defau defaul default defaults deferred defi defin define degrees delayed delegate delete delete_all delimited demand dense_rank depth dequeue des_decrypt des_encrypt des_key_file desc descr descri describ describe descriptor deterministic diagnostics difference dimension direct_load directory disable disable_all disallow disassociate discardfile disconnect diskgroup distinct distinctrow distribute distributed div do document domain dotnet double downgrade drop dumpfile duplicate duration each edition editionable editions element ellipsis else elsif elt empty enable enable_all enclosed encode encoding encrypt end end-exec endian enforced engine engines enqueue enterprise entityescaping eomonth error errors escaped evalname evaluate event eventdata events except exception exceptions exchange exclude excluding execu execut execute exempt exists exit exp expire explain explode export export_set extended extent external external_1 external_2 externally extract failed failed_login_attempts failover failure far fast feature_set feature_value fetch field fields file file_name_convert filesystem_like_logging final finish first first_value fixed flash_cache flashback floor flush following follows for forall force foreign form forma format found found_rows freelist freelists freepools fresh from from_base64 from_days ftp full function general generated get get_format get_lock getdate getutcdate global global_name globally go goto grant grants greatest group group_concat group_id grouping grouping_id groups gtid_subtract guarantee guard handler hash hashkeys having hea head headi headin heading heap help hex hierarchy high high_priority hosts hour hours http id ident_current ident_incr ident_seed identified identity idle_time if ifnull ignore iif ilike ilm immediate import in include including increment index indexes indexing indextype indicator indices inet6_aton inet6_ntoa inet_aton inet_ntoa infile initial initialized initially initrans inmemory inner innodb input insert install instance instantiable instr interface interleaved intersect into invalidate invisible is is_free_lock is_ipv4 is_ipv4_compat is_not is_not_null is_used_lock isdate isnull isolation iterate java join json json_exists keep keep_duplicates key keys kill language large last last_day last_insert_id last_value lateral lax lcase lead leading least leaves left len lenght length less level levels library like like2 like4 likec limit lines link list listagg little ln load load_file lob lobs local localtime localtimestamp locate locator lock locked log log10 log2 logfile logfiles logging logical logical_reads_per_call logoff logon logs long loop low low_priority lower lpad lrtrim ltrim main make_set makedate maketime managed management manual map mapping mask master master_pos_wait match matched materialized max maxextents maximize maxinstances maxlen maxlogfiles maxloghistory maxlogmembers maxsize maxtrans md5 measures median medium member memcompress memory merge microsecond mid migration min minextents minimum mining minus minute minutes minvalue missing mod mode model modification modify module monitoring month months mount move movement multiset mutex name name_const names nan national native natural nav nchar nclob nested never new newline next nextval no no_write_to_binlog noarchivelog noaudit nobadfile nocheck nocompress nocopy nocycle nodelay nodiscardfile noentityescaping noguarantee nokeep nologfile nomapping nomaxvalue nominimize nominvalue nomonitoring none noneditionable nonschema noorder nopr nopro noprom nopromp noprompt norely noresetlogs noreverse normal norowdependencies noschemacheck noswitch not nothing notice notnull notrim novalidate now nowait nth_value nullif nulls num numb numbe nvarchar nvarchar2 object ocicoll ocidate ocidatetime ociduration ociinterval ociloblocator ocinumber ociref ocirefcursor ocirowid ocistring ocitype oct octet_length of off offline offset oid oidindex old on online only opaque open operations operator optimal optimize option optionally or oracle oracle_date oradata ord ordaudio orddicom orddoc order ordimage ordinality ordvideo organization orlany orlvary out outer outfile outline output over overflow overriding package pad parallel parallel_enable parameters parent parse partial partition partitions pascal passing password password_grace_time password_lock_time password_reuse_max password_reuse_time password_verify_function patch path patindex pctincrease pctthreshold pctused pctversion percent percent_rank percentile_cont percentile_disc performance period period_add period_diff permanent physical pi pipe pipelined pivot pluggable plugin policy position post_transaction pow power pragma prebuilt precedes preceding precision prediction prediction_cost prediction_details prediction_probability prediction_set prepare present preserve prior priority private private_sga privileges procedural procedure procedure_analyze processlist profiles project prompt protection public publishingservername purge quarter query quick quiesce quota quotename radians raise rand range rank raw read reads readsize rebuild record records recover recovery recursive recycle redo reduced ref reference referenced references referencing refresh regexp_like register regr_avgx regr_avgy regr_count regr_intercept regr_r2 regr_slope regr_sxx regr_sxy reject rekey relational relative relaylog release release_lock relies_on relocate rely rem remainder rename repair repeat replace replicate replication required reset resetlogs resize resource respect restore restricted result result_cache resumable resume retention return returning returns reuse reverse revoke right rlike role roles rollback rolling rollup round row row_count rowdependencies rowid rownum rows rtrim rules safe salt sample save savepoint sb1 sb2 sb4 scan schema schemacheck scn scope scroll sdo_georaster sdo_topo_geometry search sec_to_time second seconds section securefile security seed segment select self semi sequence sequential serializable server servererror session session_user sessions_per_user set sets settings sha sha1 sha2 share shared shared_pool short show shrink shutdown si_averagecolor si_colorhistogram si_featurelist si_positionalcolor si_stillimage si_texture siblings sid sign sin size size_t sizes skip slave sleep smalldatetimefromparts smallfile snapshot some soname sort soundex source space sparse spfile split sql sql_big_result sql_buffer_result sql_cache sql_calc_found_rows sql_small_result sql_variant_property sqlcode sqldata sqlerror sqlname sqlstate sqrt square standalone standby start starting startup statement static statistics stats_binomial_test stats_crosstab stats_ks_test stats_mode stats_mw_test stats_one_way_anova stats_t_test_ stats_t_test_indep stats_t_test_one stats_t_test_paired stats_wsr_test status std stddev stddev_pop stddev_samp stdev stop storage store stored str str_to_date straight_join strcmp strict string struct stuff style subdate subpartition subpartitions substitutable substr substring subtime subtring_index subtype success sum suspend switch switchoffset switchover sync synchronous synonym sys sys_xmlagg sysasm sysaux sysdate sysdatetimeoffset sysdba sysoper system system_user sysutcdatetime table tables tablespace tablesample tan tdo template temporary terminated tertiary_weights test than then thread through tier ties time time_format time_zone timediff timefromparts timeout timestamp timestampadd timestampdiff timezone_abbr timezone_minute timezone_region to to_base64 to_date to_days to_seconds todatetimeoffset trace tracking transaction transactional translate translation treat trigger trigger_nestlevel triggers trim truncate try_cast try_convert try_parse type ub1 ub2 ub4 ucase unarchived unbounded uncompress under undo unhex unicode uniform uninstall union unique unix_timestamp unknown unlimited unlock unnest unpivot unrecoverable unsafe unsigned until untrusted unusable unused update updated upgrade upped upper upsert url urowid usable usage use use_stored_outlines user user_data user_resources users using utc_date utc_timestamp uuid uuid_short validate validate_password_strength validation valist value values var var_samp varcharc vari varia variab variabl variable variables variance varp varraw varrawc varray verify version versions view virtual visible void wait wallet warning warnings week weekday weekofyear wellformed when whene whenev wheneve whenever where while whitespace window with within without work wrapped xdb xml xmlagg xmlattributes xmlcast xmlcolattval xmlelement xmlexists xmlforest xmlindex xmlnamespaces xmlpi xmlquery xmlroot xmlschema xmlserialize xmltable xmltype xor year year_to_month years yearweek",literal:"true false null unknown",built_in:"array bigint binary bit blob bool boolean char character date dec decimal float int int8 integer interval number numeric real record serial serial8 smallint text time timestamp tinyint varchar varchar2 varying void"},contains:[{className:"string",begin:"'",end:"'",contains:[{begin:"''"}]},{className:"string",begin:'"',end:'"',contains:[{begin:'""'}]},{className:"string",begin:"`",end:"`"},e.C_NUMBER_MODE,e.C_BLOCK_COMMENT_MODE,t,e.HASH_COMMENT_MODE]},e.C_BLOCK_COMMENT_MODE,t,e.HASH_COMMENT_MODE]}}}()); +hljs.registerLanguage("swift",function(){"use strict";return function(e){var i={keyword:"#available #colorLiteral #column #else #elseif #endif #file #fileLiteral #function #if #imageLiteral #line #selector #sourceLocation _ __COLUMN__ __FILE__ __FUNCTION__ __LINE__ Any as as! as? associatedtype associativity break case catch class continue convenience default defer deinit didSet do dynamic dynamicType else enum extension fallthrough false fileprivate final for func get guard if import in indirect infix init inout internal is lazy left let mutating nil none nonmutating open operator optional override postfix precedence prefix private protocol Protocol public repeat required rethrows return right self Self set static struct subscript super switch throw throws true try try! try? Type typealias unowned var weak where while willSet",literal:"true false nil",built_in:"abs advance alignof alignofValue anyGenerator assert assertionFailure bridgeFromObjectiveC bridgeFromObjectiveCUnconditional bridgeToObjectiveC bridgeToObjectiveCUnconditional c compactMap contains count countElements countLeadingZeros debugPrint debugPrintln distance dropFirst dropLast dump encodeBitsAsWords enumerate equal fatalError filter find getBridgedObjectiveCType getVaList indices insertionSort isBridgedToObjectiveC isBridgedVerbatimToObjectiveC isUniquelyReferenced isUniquelyReferencedNonObjC join lazy lexicographicalCompare map max maxElement min minElement numericCast overlaps partition posix precondition preconditionFailure print println quickSort readLine reduce reflect reinterpretCast reverse roundUpToAlignment sizeof sizeofValue sort split startsWith stride strideof strideofValue swap toString transcode underestimateCount unsafeAddressOf unsafeBitCast unsafeDowncast unsafeUnwrap unsafeReflect withExtendedLifetime withObjectAtPlusZero withUnsafePointer withUnsafePointerToObject withUnsafeMutablePointer withUnsafeMutablePointers withUnsafePointer withUnsafePointers withVaList zip"},n=e.COMMENT("/\\*","\\*/",{contains:["self"]}),t={className:"subst",begin:/\\\(/,end:"\\)",keywords:i,contains:[]},a={className:"string",contains:[e.BACKSLASH_ESCAPE,t],variants:[{begin:/"""/,end:/"""/},{begin:/"/,end:/"/}]},r={className:"number",begin:"\\b([\\d_]+(\\.[\\deE_]+)?|0x[a-fA-F0-9_]+(\\.[a-fA-F0-9p_]+)?|0b[01_]+|0o[0-7_]+)\\b",relevance:0};return t.contains=[r],{name:"Swift",keywords:i,contains:[a,e.C_LINE_COMMENT_MODE,n,{className:"type",begin:"\\b[A-Z][\\wÀ-ʸ']*[!?]"},{className:"type",begin:"\\b[A-Z][\\wÀ-ʸ']*",relevance:0},r,{className:"function",beginKeywords:"func",end:"{",excludeEnd:!0,contains:[e.inherit(e.TITLE_MODE,{begin:/[A-Za-z$_][0-9A-Za-z$_]*/}),{begin://},{className:"params",begin:/\(/,end:/\)/,endsParent:!0,keywords:i,contains:["self",r,a,e.C_BLOCK_COMMENT_MODE,{begin:":"}],illegal:/["']/}],illegal:/\[|%/},{className:"class",beginKeywords:"struct protocol class extension enum",keywords:i,end:"\\{",excludeEnd:!0,contains:[e.inherit(e.TITLE_MODE,{begin:/[A-Za-z$_][\u00C0-\u02B80-9A-Za-z$_]*/})]},{className:"meta",begin:"(@discardableResult|@warn_unused_result|@exported|@lazy|@noescape|@NSCopying|@NSManaged|@objc|@objcMembers|@convention|@required|@noreturn|@IBAction|@IBDesignable|@IBInspectable|@IBOutlet|@infix|@prefix|@postfix|@autoclosure|@testable|@available|@nonobjc|@NSApplicationMain|@UIApplicationMain|@dynamicMemberLookup|@propertyWrapper)\\b"},{beginKeywords:"import",end:/$/,contains:[e.C_LINE_COMMENT_MODE,n]}]}}}()); +hljs.registerLanguage("typescript",function(){"use strict";const e=["as","in","of","if","for","while","finally","var","new","function","do","return","void","else","break","catch","instanceof","with","throw","case","default","try","switch","continue","typeof","delete","let","yield","const","class","debugger","async","await","static","import","from","export","extends"],n=["true","false","null","undefined","NaN","Infinity"],a=[].concat(["setInterval","setTimeout","clearInterval","clearTimeout","require","exports","eval","isFinite","isNaN","parseFloat","parseInt","decodeURI","decodeURIComponent","encodeURI","encodeURIComponent","escape","unescape"],["arguments","this","super","console","window","document","localStorage","module","global"],["Intl","DataView","Number","Math","Date","String","RegExp","Object","Function","Boolean","Error","Symbol","Set","Map","WeakSet","WeakMap","Proxy","Reflect","JSON","Promise","Float64Array","Int16Array","Int32Array","Int8Array","Uint16Array","Uint32Array","Float32Array","Array","Uint8Array","Uint8ClampedArray","ArrayBuffer"],["EvalError","InternalError","RangeError","ReferenceError","SyntaxError","TypeError","URIError"]);return function(r){var t={$pattern:"[A-Za-z$_][0-9A-Za-z$_]*",keyword:e.concat(["type","namespace","typedef","interface","public","private","protected","implements","declare","abstract","readonly"]).join(" "),literal:n.join(" "),built_in:a.concat(["any","void","number","boolean","string","object","never","enum"]).join(" ")},s={className:"meta",begin:"@[A-Za-z$_][0-9A-Za-z$_]*"},i={className:"number",variants:[{begin:"\\b(0[bB][01]+)n?"},{begin:"\\b(0[oO][0-7]+)n?"},{begin:r.C_NUMBER_RE+"n?"}],relevance:0},o={className:"subst",begin:"\\$\\{",end:"\\}",keywords:t,contains:[]},c={begin:"html`",end:"",starts:{end:"`",returnEnd:!1,contains:[r.BACKSLASH_ESCAPE,o],subLanguage:"xml"}},l={begin:"css`",end:"",starts:{end:"`",returnEnd:!1,contains:[r.BACKSLASH_ESCAPE,o],subLanguage:"css"}},E={className:"string",begin:"`",end:"`",contains:[r.BACKSLASH_ESCAPE,o]};o.contains=[r.APOS_STRING_MODE,r.QUOTE_STRING_MODE,c,l,E,i,r.REGEXP_MODE];var d={begin:"\\(",end:/\)/,keywords:t,contains:["self",r.QUOTE_STRING_MODE,r.APOS_STRING_MODE,r.NUMBER_MODE]},u={className:"params",begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,keywords:t,contains:[r.C_LINE_COMMENT_MODE,r.C_BLOCK_COMMENT_MODE,s,d]};return{name:"TypeScript",aliases:["ts"],keywords:t,contains:[r.SHEBANG(),{className:"meta",begin:/^\s*['"]use strict['"]/},r.APOS_STRING_MODE,r.QUOTE_STRING_MODE,c,l,E,r.C_LINE_COMMENT_MODE,r.C_BLOCK_COMMENT_MODE,i,{begin:"("+r.RE_STARTERS_RE+"|\\b(case|return|throw)\\b)\\s*",keywords:"return throw case",contains:[r.C_LINE_COMMENT_MODE,r.C_BLOCK_COMMENT_MODE,r.REGEXP_MODE,{className:"function",begin:"(\\([^(]*(\\([^(]*(\\([^(]*\\))?\\))?\\)|"+r.UNDERSCORE_IDENT_RE+")\\s*=>",returnBegin:!0,end:"\\s*=>",contains:[{className:"params",variants:[{begin:r.UNDERSCORE_IDENT_RE},{className:null,begin:/\(\s*\)/,skip:!0},{begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,keywords:t,contains:d.contains}]}]}],relevance:0},{className:"function",beginKeywords:"function",end:/[\{;]/,excludeEnd:!0,keywords:t,contains:["self",r.inherit(r.TITLE_MODE,{begin:"[A-Za-z$_][0-9A-Za-z$_]*"}),u],illegal:/%/,relevance:0},{beginKeywords:"constructor",end:/[\{;]/,excludeEnd:!0,contains:["self",u]},{begin:/module\./,keywords:{built_in:"module"},relevance:0},{beginKeywords:"module",end:/\{/,excludeEnd:!0},{beginKeywords:"interface",end:/\{/,excludeEnd:!0,keywords:"interface extends"},{begin:/\$[(.]/},{begin:"\\."+r.IDENT_RE,relevance:0},s,d]}}}()); +hljs.registerLanguage("yaml",function(){"use strict";return function(e){var n="true false yes no null",a="[\\w#;/?:@&=+$,.~*\\'()[\\]]+",s={className:"string",relevance:0,variants:[{begin:/'/,end:/'/},{begin:/"/,end:/"/},{begin:/\S+/}],contains:[e.BACKSLASH_ESCAPE,{className:"template-variable",variants:[{begin:"{{",end:"}}"},{begin:"%{",end:"}"}]}]},i=e.inherit(s,{variants:[{begin:/'/,end:/'/},{begin:/"/,end:/"/},{begin:/[^\s,{}[\]]+/}]}),l={end:",",endsWithParent:!0,excludeEnd:!0,contains:[],keywords:n,relevance:0},t={begin:"{",end:"}",contains:[l],illegal:"\\n",relevance:0},g={begin:"\\[",end:"\\]",contains:[l],illegal:"\\n",relevance:0},b=[{className:"attr",variants:[{begin:"\\w[\\w :\\/.-]*:(?=[ \t]|$)"},{begin:'"\\w[\\w :\\/.-]*":(?=[ \t]|$)'},{begin:"'\\w[\\w :\\/.-]*':(?=[ \t]|$)"}]},{className:"meta",begin:"^---s*$",relevance:10},{className:"string",begin:"[\\|>]([0-9]?[+-])?[ ]*\\n( *)[\\S ]+\\n(\\2[\\S ]+\\n?)*"},{begin:"<%[%=-]?",end:"[%-]?%>",subLanguage:"ruby",excludeBegin:!0,excludeEnd:!0,relevance:0},{className:"type",begin:"!\\w+!"+a},{className:"type",begin:"!<"+a+">"},{className:"type",begin:"!"+a},{className:"type",begin:"!!"+a},{className:"meta",begin:"&"+e.UNDERSCORE_IDENT_RE+"$"},{className:"meta",begin:"\\*"+e.UNDERSCORE_IDENT_RE+"$"},{className:"bullet",begin:"\\-(?=[ ]|$)",relevance:0},e.HASH_COMMENT_MODE,{beginKeywords:n,keywords:{literal:n}},{className:"number",begin:"\\b[0-9]{4}(-[0-9][0-9]){0,2}([Tt \\t][0-9][0-9]?(:[0-9][0-9]){2})?(\\.[0-9]*)?([ \\t])*(Z|[-+][0-9][0-9]?(:[0-9][0-9])?)?\\b"},{className:"number",begin:e.C_NUMBER_RE+"\\b"},t,g,s],c=[...b];return c.pop(),c.push(i),l.contains=c,{name:"YAML",case_insensitive:!0,aliases:["yml","YAML"],contains:b}}}()); +hljs.registerLanguage("armasm",function(){"use strict";return function(s){const e={variants:[s.COMMENT("^[ \\t]*(?=#)","$",{relevance:0,excludeBegin:!0}),s.COMMENT("[;@]","$",{relevance:0}),s.C_LINE_COMMENT_MODE,s.C_BLOCK_COMMENT_MODE]};return{name:"ARM Assembly",case_insensitive:!0,aliases:["arm"],keywords:{$pattern:"\\.?"+s.IDENT_RE,meta:".2byte .4byte .align .ascii .asciz .balign .byte .code .data .else .end .endif .endm .endr .equ .err .exitm .extern .global .hword .if .ifdef .ifndef .include .irp .long .macro .rept .req .section .set .skip .space .text .word .arm .thumb .code16 .code32 .force_thumb .thumb_func .ltorg ALIAS ALIGN ARM AREA ASSERT ATTR CN CODE CODE16 CODE32 COMMON CP DATA DCB DCD DCDU DCDO DCFD DCFDU DCI DCQ DCQU DCW DCWU DN ELIF ELSE END ENDFUNC ENDIF ENDP ENTRY EQU EXPORT EXPORTAS EXTERN FIELD FILL FUNCTION GBLA GBLL GBLS GET GLOBAL IF IMPORT INCBIN INCLUDE INFO KEEP LCLA LCLL LCLS LTORG MACRO MAP MEND MEXIT NOFP OPT PRESERVE8 PROC QN READONLY RELOC REQUIRE REQUIRE8 RLIST FN ROUT SETA SETL SETS SN SPACE SUBT THUMB THUMBX TTL WHILE WEND ",built_in:"r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15 pc lr sp ip sl sb fp a1 a2 a3 a4 v1 v2 v3 v4 v5 v6 v7 v8 f0 f1 f2 f3 f4 f5 f6 f7 p0 p1 p2 p3 p4 p5 p6 p7 p8 p9 p10 p11 p12 p13 p14 p15 c0 c1 c2 c3 c4 c5 c6 c7 c8 c9 c10 c11 c12 c13 c14 c15 q0 q1 q2 q3 q4 q5 q6 q7 q8 q9 q10 q11 q12 q13 q14 q15 cpsr_c cpsr_x cpsr_s cpsr_f cpsr_cx cpsr_cxs cpsr_xs cpsr_xsf cpsr_sf cpsr_cxsf spsr_c spsr_x spsr_s spsr_f spsr_cx spsr_cxs spsr_xs spsr_xsf spsr_sf spsr_cxsf s0 s1 s2 s3 s4 s5 s6 s7 s8 s9 s10 s11 s12 s13 s14 s15 s16 s17 s18 s19 s20 s21 s22 s23 s24 s25 s26 s27 s28 s29 s30 s31 d0 d1 d2 d3 d4 d5 d6 d7 d8 d9 d10 d11 d12 d13 d14 d15 d16 d17 d18 d19 d20 d21 d22 d23 d24 d25 d26 d27 d28 d29 d30 d31 {PC} {VAR} {TRUE} {FALSE} {OPT} {CONFIG} {ENDIAN} {CODESIZE} {CPU} {FPU} {ARCHITECTURE} {PCSTOREOFFSET} {ARMASM_VERSION} {INTER} {ROPI} {RWPI} {SWST} {NOSWST} . @"},contains:[{className:"keyword",begin:"\\b(adc|(qd?|sh?|u[qh]?)?add(8|16)?|usada?8|(q|sh?|u[qh]?)?(as|sa)x|and|adrl?|sbc|rs[bc]|asr|b[lx]?|blx|bxj|cbn?z|tb[bh]|bic|bfc|bfi|[su]bfx|bkpt|cdp2?|clz|clrex|cmp|cmn|cpsi[ed]|cps|setend|dbg|dmb|dsb|eor|isb|it[te]{0,3}|lsl|lsr|ror|rrx|ldm(([id][ab])|f[ds])?|ldr((s|ex)?[bhd])?|movt?|mvn|mra|mar|mul|[us]mull|smul[bwt][bt]|smu[as]d|smmul|smmla|mla|umlaal|smlal?([wbt][bt]|d)|mls|smlsl?[ds]|smc|svc|sev|mia([bt]{2}|ph)?|mrr?c2?|mcrr2?|mrs|msr|orr|orn|pkh(tb|bt)|rbit|rev(16|sh)?|sel|[su]sat(16)?|nop|pop|push|rfe([id][ab])?|stm([id][ab])?|str(ex)?[bhd]?|(qd?)?sub|(sh?|q|u[qh]?)?sub(8|16)|[su]xt(a?h|a?b(16)?)|srs([id][ab])?|swpb?|swi|smi|tst|teq|wfe|wfi|yield)(eq|ne|cs|cc|mi|pl|vs|vc|hi|ls|ge|lt|gt|le|al|hs|lo)?[sptrx]?(?=\\s)"},e,s.QUOTE_STRING_MODE,{className:"string",begin:"'",end:"[^\\\\]'",relevance:0},{className:"title",begin:"\\|",end:"\\|",illegal:"\\n",relevance:0},{className:"number",variants:[{begin:"[#$=]?0x[0-9a-f]+"},{begin:"[#$=]?0b[01]+"},{begin:"[#$=]\\d+"},{begin:"\\b\\d+"}],relevance:0},{className:"symbol",variants:[{begin:"^[ \\t]*[a-z_\\.\\$][a-z0-9_\\.\\$]+:"},{begin:"^[a-z_\\.\\$][a-z0-9_\\.\\$]+"},{begin:"[=#]\\w+"}],relevance:0}]}}}()); +hljs.registerLanguage("d",function(){"use strict";return function(e){var a={$pattern:e.UNDERSCORE_IDENT_RE,keyword:"abstract alias align asm assert auto body break byte case cast catch class const continue debug default delete deprecated do else enum export extern final finally for foreach foreach_reverse|10 goto if immutable import in inout int interface invariant is lazy macro mixin module new nothrow out override package pragma private protected public pure ref return scope shared static struct super switch synchronized template this throw try typedef typeid typeof union unittest version void volatile while with __FILE__ __LINE__ __gshared|10 __thread __traits __DATE__ __EOF__ __TIME__ __TIMESTAMP__ __VENDOR__ __VERSION__",built_in:"bool cdouble cent cfloat char creal dchar delegate double dstring float function idouble ifloat ireal long real short string ubyte ucent uint ulong ushort wchar wstring",literal:"false null true"},d="((0|[1-9][\\d_]*)|0[bB][01_]+|0[xX]([\\da-fA-F][\\da-fA-F_]*|_[\\da-fA-F][\\da-fA-F_]*))",n="\\\\(['\"\\?\\\\abfnrtv]|u[\\dA-Fa-f]{4}|[0-7]{1,3}|x[\\dA-Fa-f]{2}|U[\\dA-Fa-f]{8})|&[a-zA-Z\\d]{2,};",t={className:"number",begin:"\\b"+d+"(L|u|U|Lu|LU|uL|UL)?",relevance:0},_={className:"number",begin:"\\b(((0[xX](([\\da-fA-F][\\da-fA-F_]*|_[\\da-fA-F][\\da-fA-F_]*)\\.([\\da-fA-F][\\da-fA-F_]*|_[\\da-fA-F][\\da-fA-F_]*)|\\.?([\\da-fA-F][\\da-fA-F_]*|_[\\da-fA-F][\\da-fA-F_]*))[pP][+-]?(0|[1-9][\\d_]*|\\d[\\d_]*|[\\d_]+?\\d))|((0|[1-9][\\d_]*|\\d[\\d_]*|[\\d_]+?\\d)(\\.\\d*|([eE][+-]?(0|[1-9][\\d_]*|\\d[\\d_]*|[\\d_]+?\\d)))|\\d+\\.(0|[1-9][\\d_]*|\\d[\\d_]*|[\\d_]+?\\d)(0|[1-9][\\d_]*|\\d[\\d_]*|[\\d_]+?\\d)|\\.(0|[1-9][\\d_]*)([eE][+-]?(0|[1-9][\\d_]*|\\d[\\d_]*|[\\d_]+?\\d))?))([fF]|L|i|[fF]i|Li)?|"+d+"(i|[fF]i|Li))",relevance:0},r={className:"string",begin:"'("+n+"|.)",end:"'",illegal:"."},i={className:"string",begin:'"',contains:[{begin:n,relevance:0}],end:'"[cwd]?'},s=e.COMMENT("\\/\\+","\\+\\/",{contains:["self"],relevance:10});return{name:"D",keywords:a,contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,s,{className:"string",begin:'x"[\\da-fA-F\\s\\n\\r]*"[cwd]?',relevance:10},i,{className:"string",begin:'[rq]"',end:'"[cwd]?',relevance:5},{className:"string",begin:"`",end:"`[cwd]?"},{className:"string",begin:'q"\\{',end:'\\}"'},_,t,r,{className:"meta",begin:"^#!",end:"$",relevance:5},{className:"meta",begin:"#(line)",end:"$",relevance:5},{className:"keyword",begin:"@[a-zA-Z_][a-zA-Z_\\d]*"}]}}}()); +hljs.registerLanguage("handlebars",function(){"use strict";function e(...e){return e.map(e=>(function(e){return e?"string"==typeof e?e:e.source:null})(e)).join("")}return function(n){const a={"builtin-name":"action bindattr collection component concat debugger each each-in get hash if in input link-to loc log lookup mut outlet partial query-params render template textarea unbound unless view with yield"},t=/\[.*?\]/,s=/[^\s!"#%&'()*+,.\/;<=>@\[\\\]^`{|}~]+/,i=e("(",/'.*?'/,"|",/".*?"/,"|",t,"|",s,"|",/\.|\//,")+"),r=e("(",t,"|",s,")(?==)"),l={begin:i,lexemes:/[\w.\/]+/},c=n.inherit(l,{keywords:{literal:"true false undefined null"}}),o={begin:/\(/,end:/\)/},m={className:"attr",begin:r,relevance:0,starts:{begin:/=/,end:/=/,starts:{contains:[n.NUMBER_MODE,n.QUOTE_STRING_MODE,n.APOS_STRING_MODE,c,o]}}},d={contains:[n.NUMBER_MODE,n.QUOTE_STRING_MODE,n.APOS_STRING_MODE,{begin:/as\s+\|/,keywords:{keyword:"as"},end:/\|/,contains:[{begin:/\w+/}]},m,c,o],returnEnd:!0},g=n.inherit(l,{className:"name",keywords:a,starts:n.inherit(d,{end:/\)/})});o.contains=[g];const u=n.inherit(l,{keywords:a,className:"name",starts:n.inherit(d,{end:/}}/})}),b=n.inherit(l,{keywords:a,className:"name"}),h=n.inherit(l,{className:"name",keywords:a,starts:n.inherit(d,{end:/}}/})});return{name:"Handlebars",aliases:["hbs","html.hbs","html.handlebars","htmlbars"],case_insensitive:!0,subLanguage:"xml",contains:[{begin:/\\\{\{/,skip:!0},{begin:/\\\\(?=\{\{)/,skip:!0},n.COMMENT(/\{\{!--/,/--\}\}/),n.COMMENT(/\{\{!/,/\}\}/),{className:"template-tag",begin:/\{\{\{\{(?!\/)/,end:/\}\}\}\}/,contains:[u],starts:{end:/\{\{\{\{\//,returnEnd:!0,subLanguage:"xml"}},{className:"template-tag",begin:/\{\{\{\{\//,end:/\}\}\}\}/,contains:[b]},{className:"template-tag",begin:/\{\{#/,end:/\}\}/,contains:[u]},{className:"template-tag",begin:/\{\{(?=else\}\})/,end:/\}\}/,keywords:"else"},{className:"template-tag",begin:/\{\{\//,end:/\}\}/,contains:[b]},{className:"template-variable",begin:/\{\{\{/,end:/\}\}\}/,contains:[h]},{className:"template-variable",begin:/\{\{/,end:/\}\}/,contains:[h]}]}}}()); +hljs.registerLanguage("haskell",function(){"use strict";return function(e){var n={variants:[e.COMMENT("--","$"),e.COMMENT("{-","-}",{contains:["self"]})]},i={className:"meta",begin:"{-#",end:"#-}"},a={className:"meta",begin:"^#",end:"$"},s={className:"type",begin:"\\b[A-Z][\\w']*",relevance:0},l={begin:"\\(",end:"\\)",illegal:'"',contains:[i,a,{className:"type",begin:"\\b[A-Z][\\w]*(\\((\\.\\.|,|\\w+)\\))?"},e.inherit(e.TITLE_MODE,{begin:"[_a-z][\\w']*"}),n]};return{name:"Haskell",aliases:["hs"],keywords:"let in if then else case of where do module import hiding qualified type data newtype deriving class instance as default infix infixl infixr foreign export ccall stdcall cplusplus jvm dotnet safe unsafe family forall mdo proc rec",contains:[{beginKeywords:"module",end:"where",keywords:"module where",contains:[l,n],illegal:"\\W\\.|;"},{begin:"\\bimport\\b",end:"$",keywords:"import qualified as hiding",contains:[l,n],illegal:"\\W\\.|;"},{className:"class",begin:"^(\\s*)?(class|instance)\\b",end:"where",keywords:"class family instance where",contains:[s,l,n]},{className:"class",begin:"\\b(data|(new)?type)\\b",end:"$",keywords:"data family type newtype deriving",contains:[i,s,l,{begin:"{",end:"}",contains:l.contains},n]},{beginKeywords:"default",end:"$",contains:[s,l,n]},{beginKeywords:"infix infixl infixr",end:"$",contains:[e.C_NUMBER_MODE,n]},{begin:"\\bforeign\\b",end:"$",keywords:"foreign import export ccall stdcall cplusplus jvm dotnet safe unsafe",contains:[s,e.QUOTE_STRING_MODE,n]},{className:"meta",begin:"#!\\/usr\\/bin\\/env runhaskell",end:"$"},i,a,e.QUOTE_STRING_MODE,e.C_NUMBER_MODE,s,e.inherit(e.TITLE_MODE,{begin:"^[_a-z][\\w']*"}),n,{begin:"->|<-"}]}}}()); +hljs.registerLanguage("julia",function(){"use strict";return function(e){var r="[A-Za-z_\\u00A1-\\uFFFF][A-Za-z_0-9\\u00A1-\\uFFFF]*",t={$pattern:r,keyword:"in isa where baremodule begin break catch ccall const continue do else elseif end export false finally for function global if import importall let local macro module quote return true try using while type immutable abstract bitstype typealias ",literal:"true false ARGS C_NULL DevNull ENDIAN_BOM ENV I Inf Inf16 Inf32 Inf64 InsertionSort JULIA_HOME LOAD_PATH MergeSort NaN NaN16 NaN32 NaN64 PROGRAM_FILE QuickSort RoundDown RoundFromZero RoundNearest RoundNearestTiesAway RoundNearestTiesUp RoundToZero RoundUp STDERR STDIN STDOUT VERSION catalan e|0 eu|0 eulergamma golden im nothing pi γ π φ ",built_in:"ANY AbstractArray AbstractChannel AbstractFloat AbstractMatrix AbstractRNG AbstractSerializer AbstractSet AbstractSparseArray AbstractSparseMatrix AbstractSparseVector AbstractString AbstractUnitRange AbstractVecOrMat AbstractVector Any ArgumentError Array AssertionError Associative Base64DecodePipe Base64EncodePipe Bidiagonal BigFloat BigInt BitArray BitMatrix BitVector Bool BoundsError BufferStream CachingPool CapturedException CartesianIndex CartesianRange Cchar Cdouble Cfloat Channel Char Cint Cintmax_t Clong Clonglong ClusterManager Cmd CodeInfo Colon Complex Complex128 Complex32 Complex64 CompositeException Condition ConjArray ConjMatrix ConjVector Cptrdiff_t Cshort Csize_t Cssize_t Cstring Cuchar Cuint Cuintmax_t Culong Culonglong Cushort Cwchar_t Cwstring DataType Date DateFormat DateTime DenseArray DenseMatrix DenseVecOrMat DenseVector Diagonal Dict DimensionMismatch Dims DirectIndexString Display DivideError DomainError EOFError EachLine Enum Enumerate ErrorException Exception ExponentialBackOff Expr Factorization FileMonitor Float16 Float32 Float64 Function Future GlobalRef GotoNode HTML Hermitian IO IOBuffer IOContext IOStream IPAddr IPv4 IPv6 IndexCartesian IndexLinear IndexStyle InexactError InitError Int Int128 Int16 Int32 Int64 Int8 IntSet Integer InterruptException InvalidStateException Irrational KeyError LabelNode LinSpace LineNumberNode LoadError LowerTriangular MIME Matrix MersenneTwister Method MethodError MethodTable Module NTuple NewvarNode NullException Nullable Number ObjectIdDict OrdinalRange OutOfMemoryError OverflowError Pair ParseError PartialQuickSort PermutedDimsArray Pipe PollingFileWatcher ProcessExitedException Ptr QuoteNode RandomDevice Range RangeIndex Rational RawFD ReadOnlyMemoryError Real ReentrantLock Ref Regex RegexMatch RemoteChannel RemoteException RevString RoundingMode RowVector SSAValue SegmentationFault SerializationState Set SharedArray SharedMatrix SharedVector Signed SimpleVector Slot SlotNumber SparseMatrixCSC SparseVector StackFrame StackOverflowError StackTrace StepRange StepRangeLen StridedArray StridedMatrix StridedVecOrMat StridedVector String SubArray SubString SymTridiagonal Symbol Symmetric SystemError TCPSocket Task Text TextDisplay Timer Tridiagonal Tuple Type TypeError TypeMapEntry TypeMapLevel TypeName TypeVar TypedSlot UDPSocket UInt UInt128 UInt16 UInt32 UInt64 UInt8 UndefRefError UndefVarError UnicodeError UniformScaling Union UnionAll UnitRange Unsigned UpperTriangular Val Vararg VecElement VecOrMat Vector VersionNumber Void WeakKeyDict WeakRef WorkerConfig WorkerPool "},a={keywords:t,illegal:/<\//},n={className:"subst",begin:/\$\(/,end:/\)/,keywords:t},o={className:"variable",begin:"\\$"+r},i={className:"string",contains:[e.BACKSLASH_ESCAPE,n,o],variants:[{begin:/\w*"""/,end:/"""\w*/,relevance:10},{begin:/\w*"/,end:/"\w*/}]},l={className:"string",contains:[e.BACKSLASH_ESCAPE,n,o],begin:"`",end:"`"},s={className:"meta",begin:"@"+r};return a.name="Julia",a.contains=[{className:"number",begin:/(\b0x[\d_]*(\.[\d_]*)?|0x\.\d[\d_]*)p[-+]?\d+|\b0[box][a-fA-F0-9][a-fA-F0-9_]*|(\b\d[\d_]*(\.[\d_]*)?|\.\d[\d_]*)([eEfF][-+]?\d+)?/,relevance:0},{className:"string",begin:/'(.|\\[xXuU][a-zA-Z0-9]+)'/},i,l,s,{className:"comment",variants:[{begin:"#=",end:"=#",relevance:10},{begin:"#",end:"$"}]},e.HASH_COMMENT_MODE,{className:"keyword",begin:"\\b(((abstract|primitive)\\s+)type|(mutable\\s+)?struct)\\b"},{begin:/<:/}],n.contains=a.contains,a}}()); +hljs.registerLanguage("nim",function(){"use strict";return function(e){return{name:"Nim",aliases:["nim"],keywords:{keyword:"addr and as asm bind block break case cast const continue converter discard distinct div do elif else end enum except export finally for from func generic if import in include interface is isnot iterator let macro method mixin mod nil not notin object of or out proc ptr raise ref return shl shr static template try tuple type using var when while with without xor yield",literal:"shared guarded stdin stdout stderr result true false",built_in:"int int8 int16 int32 int64 uint uint8 uint16 uint32 uint64 float float32 float64 bool char string cstring pointer expr stmt void auto any range array openarray varargs seq set clong culong cchar cschar cshort cint csize clonglong cfloat cdouble clongdouble cuchar cushort cuint culonglong cstringarray semistatic"},contains:[{className:"meta",begin:/{\./,end:/\.}/,relevance:10},{className:"string",begin:/[a-zA-Z]\w*"/,end:/"/,contains:[{begin:/""/}]},{className:"string",begin:/([a-zA-Z]\w*)?"""/,end:/"""/},e.QUOTE_STRING_MODE,{className:"type",begin:/\b[A-Z]\w+\b/,relevance:0},{className:"number",relevance:0,variants:[{begin:/\b(0[xX][0-9a-fA-F][_0-9a-fA-F]*)('?[iIuU](8|16|32|64))?/},{begin:/\b(0o[0-7][_0-7]*)('?[iIuUfF](8|16|32|64))?/},{begin:/\b(0(b|B)[01][_01]*)('?[iIuUfF](8|16|32|64))?/},{begin:/\b(\d[_\d]*)('?[iIuUfF](8|16|32|64))?/}]},e.HASH_COMMENT_MODE]}}}()); +hljs.registerLanguage("nix",function(){"use strict";return function(e){var n={keyword:"rec with let in inherit assert if else then",literal:"true false or and null",built_in:"import abort baseNameOf dirOf isNull builtins map removeAttrs throw toString derivation"},i={className:"subst",begin:/\$\{/,end:/}/,keywords:n},t={className:"string",contains:[i],variants:[{begin:"''",end:"''"},{begin:'"',end:'"'}]},s=[e.NUMBER_MODE,e.HASH_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,t,{begin:/[a-zA-Z0-9-_]+(\s*=)/,returnBegin:!0,relevance:0,contains:[{className:"attr",begin:/\S+/}]}];return i.contains=s,{name:"Nix",aliases:["nixos"],keywords:n,contains:s}}}()); +hljs.registerLanguage("r",function(){"use strict";return function(e){var n="([a-zA-Z]|\\.[a-zA-Z.])[a-zA-Z0-9._]*";return{name:"R",contains:[e.HASH_COMMENT_MODE,{begin:n,keywords:{$pattern:n,keyword:"function if in break next repeat else for return switch while try tryCatch stop warning require library attach detach source setMethod setGeneric setGroupGeneric setClass ...",literal:"NULL NA TRUE FALSE T F Inf NaN NA_integer_|10 NA_real_|10 NA_character_|10 NA_complex_|10"},relevance:0},{className:"number",begin:"0[xX][0-9a-fA-F]+[Li]?\\b",relevance:0},{className:"number",begin:"\\d+(?:[eE][+\\-]?\\d*)?L\\b",relevance:0},{className:"number",begin:"\\d+\\.(?!\\d)(?:i\\b)?",relevance:0},{className:"number",begin:"\\d+(?:\\.\\d*)?(?:[eE][+\\-]?\\d*)?i?\\b",relevance:0},{className:"number",begin:"\\.\\d+(?:[eE][+\\-]?\\d*)?i?\\b",relevance:0},{begin:"`",end:"`",relevance:0},{className:"string",contains:[e.BACKSLASH_ESCAPE],variants:[{begin:'"',end:'"'},{begin:"'",end:"'"}]}]}}}()); +hljs.registerLanguage("scala",function(){"use strict";return function(e){var n={className:"subst",variants:[{begin:"\\$[A-Za-z0-9_]+"},{begin:"\\${",end:"}"}]},a={className:"string",variants:[{begin:'"',end:'"',illegal:"\\n",contains:[e.BACKSLASH_ESCAPE]},{begin:'"""',end:'"""',relevance:10},{begin:'[a-z]+"',end:'"',illegal:"\\n",contains:[e.BACKSLASH_ESCAPE,n]},{className:"string",begin:'[a-z]+"""',end:'"""',contains:[n],relevance:10}]},s={className:"type",begin:"\\b[A-Z][A-Za-z0-9_]*",relevance:0},t={className:"title",begin:/[^0-9\n\t "'(),.`{}\[\]:;][^\n\t "'(),.`{}\[\]:;]+|[^0-9\n\t "'(),.`{}\[\]:;=]/,relevance:0},i={className:"class",beginKeywords:"class object trait type",end:/[:={\[\n;]/,excludeEnd:!0,contains:[{beginKeywords:"extends with",relevance:10},{begin:/\[/,end:/\]/,excludeBegin:!0,excludeEnd:!0,relevance:0,contains:[s]},{className:"params",begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,relevance:0,contains:[s]},t]},l={className:"function",beginKeywords:"def",end:/[:={\[(\n;]/,excludeEnd:!0,contains:[t]};return{name:"Scala",keywords:{literal:"true false null",keyword:"type yield lazy override def with val var sealed abstract private trait object if forSome for while throw finally protected extends import final return else break new catch super class case package default try this match continue throws implicit"},contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,{className:"symbol",begin:"'\\w[\\w\\d_]*(?!')"},s,l,i,e.C_NUMBER_MODE,{className:"meta",begin:"@[A-Za-z]+"}]}}}()); +hljs.registerLanguage("x86asm",function(){"use strict";return function(s){return{name:"Intel x86 Assembly",case_insensitive:!0,keywords:{$pattern:"[.%]?"+s.IDENT_RE,keyword:"lock rep repe repz repne repnz xaquire xrelease bnd nobnd aaa aad aam aas adc add and arpl bb0_reset bb1_reset bound bsf bsr bswap bt btc btr bts call cbw cdq cdqe clc cld cli clts cmc cmp cmpsb cmpsd cmpsq cmpsw cmpxchg cmpxchg486 cmpxchg8b cmpxchg16b cpuid cpu_read cpu_write cqo cwd cwde daa das dec div dmint emms enter equ f2xm1 fabs fadd faddp fbld fbstp fchs fclex fcmovb fcmovbe fcmove fcmovnb fcmovnbe fcmovne fcmovnu fcmovu fcom fcomi fcomip fcomp fcompp fcos fdecstp fdisi fdiv fdivp fdivr fdivrp femms feni ffree ffreep fiadd ficom ficomp fidiv fidivr fild fimul fincstp finit fist fistp fisttp fisub fisubr fld fld1 fldcw fldenv fldl2e fldl2t fldlg2 fldln2 fldpi fldz fmul fmulp fnclex fndisi fneni fninit fnop fnsave fnstcw fnstenv fnstsw fpatan fprem fprem1 fptan frndint frstor fsave fscale fsetpm fsin fsincos fsqrt fst fstcw fstenv fstp fstsw fsub fsubp fsubr fsubrp ftst fucom fucomi fucomip fucomp fucompp fxam fxch fxtract fyl2x fyl2xp1 hlt ibts icebp idiv imul in inc incbin insb insd insw int int01 int1 int03 int3 into invd invpcid invlpg invlpga iret iretd iretq iretw jcxz jecxz jrcxz jmp jmpe lahf lar lds lea leave les lfence lfs lgdt lgs lidt lldt lmsw loadall loadall286 lodsb lodsd lodsq lodsw loop loope loopne loopnz loopz lsl lss ltr mfence monitor mov movd movq movsb movsd movsq movsw movsx movsxd movzx mul mwait neg nop not or out outsb outsd outsw packssdw packsswb packuswb paddb paddd paddsb paddsiw paddsw paddusb paddusw paddw pand pandn pause paveb pavgusb pcmpeqb pcmpeqd pcmpeqw pcmpgtb pcmpgtd pcmpgtw pdistib pf2id pfacc pfadd pfcmpeq pfcmpge pfcmpgt pfmax pfmin pfmul pfrcp pfrcpit1 pfrcpit2 pfrsqit1 pfrsqrt pfsub pfsubr pi2fd pmachriw pmaddwd pmagw pmulhriw pmulhrwa pmulhrwc pmulhw pmullw pmvgezb pmvlzb pmvnzb pmvzb pop popa popad popaw popf popfd popfq popfw por prefetch prefetchw pslld psllq psllw psrad psraw psrld psrlq psrlw psubb psubd psubsb psubsiw psubsw psubusb psubusw psubw punpckhbw punpckhdq punpckhwd punpcklbw punpckldq punpcklwd push pusha pushad pushaw pushf pushfd pushfq pushfw pxor rcl rcr rdshr rdmsr rdpmc rdtsc rdtscp ret retf retn rol ror rdm rsdc rsldt rsm rsts sahf sal salc sar sbb scasb scasd scasq scasw sfence sgdt shl shld shr shrd sidt sldt skinit smi smint smintold smsw stc std sti stosb stosd stosq stosw str sub svdc svldt svts swapgs syscall sysenter sysexit sysret test ud0 ud1 ud2b ud2 ud2a umov verr verw fwait wbinvd wrshr wrmsr xadd xbts xchg xlatb xlat xor cmove cmovz cmovne cmovnz cmova cmovnbe cmovae cmovnb cmovb cmovnae cmovbe cmovna cmovg cmovnle cmovge cmovnl cmovl cmovnge cmovle cmovng cmovc cmovnc cmovo cmovno cmovs cmovns cmovp cmovpe cmovnp cmovpo je jz jne jnz ja jnbe jae jnb jb jnae jbe jna jg jnle jge jnl jl jnge jle jng jc jnc jo jno js jns jpo jnp jpe jp sete setz setne setnz seta setnbe setae setnb setnc setb setnae setcset setbe setna setg setnle setge setnl setl setnge setle setng sets setns seto setno setpe setp setpo setnp addps addss andnps andps cmpeqps cmpeqss cmpleps cmpless cmpltps cmpltss cmpneqps cmpneqss cmpnleps cmpnless cmpnltps cmpnltss cmpordps cmpordss cmpunordps cmpunordss cmpps cmpss comiss cvtpi2ps cvtps2pi cvtsi2ss cvtss2si cvttps2pi cvttss2si divps divss ldmxcsr maxps maxss minps minss movaps movhps movlhps movlps movhlps movmskps movntps movss movups mulps mulss orps rcpps rcpss rsqrtps rsqrtss shufps sqrtps sqrtss stmxcsr subps subss ucomiss unpckhps unpcklps xorps fxrstor fxrstor64 fxsave fxsave64 xgetbv xsetbv xsave xsave64 xsaveopt xsaveopt64 xrstor xrstor64 prefetchnta prefetcht0 prefetcht1 prefetcht2 maskmovq movntq pavgb pavgw pextrw pinsrw pmaxsw pmaxub pminsw pminub pmovmskb pmulhuw psadbw pshufw pf2iw pfnacc pfpnacc pi2fw pswapd maskmovdqu clflush movntdq movnti movntpd movdqa movdqu movdq2q movq2dq paddq pmuludq pshufd pshufhw pshuflw pslldq psrldq psubq punpckhqdq punpcklqdq addpd addsd andnpd andpd cmpeqpd cmpeqsd cmplepd cmplesd cmpltpd cmpltsd cmpneqpd cmpneqsd cmpnlepd cmpnlesd cmpnltpd cmpnltsd cmpordpd cmpordsd cmpunordpd cmpunordsd cmppd comisd cvtdq2pd cvtdq2ps cvtpd2dq cvtpd2pi cvtpd2ps cvtpi2pd cvtps2dq cvtps2pd cvtsd2si cvtsd2ss cvtsi2sd cvtss2sd cvttpd2pi cvttpd2dq cvttps2dq cvttsd2si divpd divsd maxpd maxsd minpd minsd movapd movhpd movlpd movmskpd movupd mulpd mulsd orpd shufpd sqrtpd sqrtsd subpd subsd ucomisd unpckhpd unpcklpd xorpd addsubpd addsubps haddpd haddps hsubpd hsubps lddqu movddup movshdup movsldup clgi stgi vmcall vmclear vmfunc vmlaunch vmload vmmcall vmptrld vmptrst vmread vmresume vmrun vmsave vmwrite vmxoff vmxon invept invvpid pabsb pabsw pabsd palignr phaddw phaddd phaddsw phsubw phsubd phsubsw pmaddubsw pmulhrsw pshufb psignb psignw psignd extrq insertq movntsd movntss lzcnt blendpd blendps blendvpd blendvps dppd dpps extractps insertps movntdqa mpsadbw packusdw pblendvb pblendw pcmpeqq pextrb pextrd pextrq phminposuw pinsrb pinsrd pinsrq pmaxsb pmaxsd pmaxud pmaxuw pminsb pminsd pminud pminuw pmovsxbw pmovsxbd pmovsxbq pmovsxwd pmovsxwq pmovsxdq pmovzxbw pmovzxbd pmovzxbq pmovzxwd pmovzxwq pmovzxdq pmuldq pmulld ptest roundpd roundps roundsd roundss crc32 pcmpestri pcmpestrm pcmpistri pcmpistrm pcmpgtq popcnt getsec pfrcpv pfrsqrtv movbe aesenc aesenclast aesdec aesdeclast aesimc aeskeygenassist vaesenc vaesenclast vaesdec vaesdeclast vaesimc vaeskeygenassist vaddpd vaddps vaddsd vaddss vaddsubpd vaddsubps vandpd vandps vandnpd vandnps vblendpd vblendps vblendvpd vblendvps vbroadcastss vbroadcastsd vbroadcastf128 vcmpeq_ospd vcmpeqpd vcmplt_ospd vcmpltpd vcmple_ospd vcmplepd vcmpunord_qpd vcmpunordpd vcmpneq_uqpd vcmpneqpd vcmpnlt_uspd vcmpnltpd vcmpnle_uspd vcmpnlepd vcmpord_qpd vcmpordpd vcmpeq_uqpd vcmpnge_uspd vcmpngepd vcmpngt_uspd vcmpngtpd vcmpfalse_oqpd vcmpfalsepd vcmpneq_oqpd vcmpge_ospd vcmpgepd vcmpgt_ospd vcmpgtpd vcmptrue_uqpd vcmptruepd vcmplt_oqpd vcmple_oqpd vcmpunord_spd vcmpneq_uspd vcmpnlt_uqpd vcmpnle_uqpd vcmpord_spd vcmpeq_uspd vcmpnge_uqpd vcmpngt_uqpd vcmpfalse_ospd vcmpneq_ospd vcmpge_oqpd vcmpgt_oqpd vcmptrue_uspd vcmppd vcmpeq_osps vcmpeqps vcmplt_osps vcmpltps vcmple_osps vcmpleps vcmpunord_qps vcmpunordps vcmpneq_uqps vcmpneqps vcmpnlt_usps vcmpnltps vcmpnle_usps vcmpnleps vcmpord_qps vcmpordps vcmpeq_uqps vcmpnge_usps vcmpngeps vcmpngt_usps vcmpngtps vcmpfalse_oqps vcmpfalseps vcmpneq_oqps vcmpge_osps vcmpgeps vcmpgt_osps vcmpgtps vcmptrue_uqps vcmptrueps vcmplt_oqps vcmple_oqps vcmpunord_sps vcmpneq_usps vcmpnlt_uqps vcmpnle_uqps vcmpord_sps vcmpeq_usps vcmpnge_uqps vcmpngt_uqps vcmpfalse_osps vcmpneq_osps vcmpge_oqps vcmpgt_oqps vcmptrue_usps vcmpps vcmpeq_ossd vcmpeqsd vcmplt_ossd vcmpltsd vcmple_ossd vcmplesd vcmpunord_qsd vcmpunordsd vcmpneq_uqsd vcmpneqsd vcmpnlt_ussd vcmpnltsd vcmpnle_ussd vcmpnlesd vcmpord_qsd vcmpordsd vcmpeq_uqsd vcmpnge_ussd vcmpngesd vcmpngt_ussd vcmpngtsd vcmpfalse_oqsd vcmpfalsesd vcmpneq_oqsd vcmpge_ossd vcmpgesd vcmpgt_ossd vcmpgtsd vcmptrue_uqsd vcmptruesd vcmplt_oqsd vcmple_oqsd vcmpunord_ssd vcmpneq_ussd vcmpnlt_uqsd vcmpnle_uqsd vcmpord_ssd vcmpeq_ussd vcmpnge_uqsd vcmpngt_uqsd vcmpfalse_ossd vcmpneq_ossd vcmpge_oqsd vcmpgt_oqsd vcmptrue_ussd vcmpsd vcmpeq_osss vcmpeqss vcmplt_osss vcmpltss vcmple_osss vcmpless vcmpunord_qss vcmpunordss vcmpneq_uqss vcmpneqss vcmpnlt_usss vcmpnltss vcmpnle_usss vcmpnless vcmpord_qss vcmpordss vcmpeq_uqss vcmpnge_usss vcmpngess vcmpngt_usss vcmpngtss vcmpfalse_oqss vcmpfalsess vcmpneq_oqss vcmpge_osss vcmpgess vcmpgt_osss vcmpgtss vcmptrue_uqss vcmptruess vcmplt_oqss vcmple_oqss vcmpunord_sss vcmpneq_usss vcmpnlt_uqss vcmpnle_uqss vcmpord_sss vcmpeq_usss vcmpnge_uqss vcmpngt_uqss vcmpfalse_osss vcmpneq_osss vcmpge_oqss vcmpgt_oqss vcmptrue_usss vcmpss vcomisd vcomiss vcvtdq2pd vcvtdq2ps vcvtpd2dq vcvtpd2ps vcvtps2dq vcvtps2pd vcvtsd2si vcvtsd2ss vcvtsi2sd vcvtsi2ss vcvtss2sd vcvtss2si vcvttpd2dq vcvttps2dq vcvttsd2si vcvttss2si vdivpd vdivps vdivsd vdivss vdppd vdpps vextractf128 vextractps vhaddpd vhaddps vhsubpd vhsubps vinsertf128 vinsertps vlddqu vldqqu vldmxcsr vmaskmovdqu vmaskmovps vmaskmovpd vmaxpd vmaxps vmaxsd vmaxss vminpd vminps vminsd vminss vmovapd vmovaps vmovd vmovq vmovddup vmovdqa vmovqqa vmovdqu vmovqqu vmovhlps vmovhpd vmovhps vmovlhps vmovlpd vmovlps vmovmskpd vmovmskps vmovntdq vmovntqq vmovntdqa vmovntpd vmovntps vmovsd vmovshdup vmovsldup vmovss vmovupd vmovups vmpsadbw vmulpd vmulps vmulsd vmulss vorpd vorps vpabsb vpabsw vpabsd vpacksswb vpackssdw vpackuswb vpackusdw vpaddb vpaddw vpaddd vpaddq vpaddsb vpaddsw vpaddusb vpaddusw vpalignr vpand vpandn vpavgb vpavgw vpblendvb vpblendw vpcmpestri vpcmpestrm vpcmpistri vpcmpistrm vpcmpeqb vpcmpeqw vpcmpeqd vpcmpeqq vpcmpgtb vpcmpgtw vpcmpgtd vpcmpgtq vpermilpd vpermilps vperm2f128 vpextrb vpextrw vpextrd vpextrq vphaddw vphaddd vphaddsw vphminposuw vphsubw vphsubd vphsubsw vpinsrb vpinsrw vpinsrd vpinsrq vpmaddwd vpmaddubsw vpmaxsb vpmaxsw vpmaxsd vpmaxub vpmaxuw vpmaxud vpminsb vpminsw vpminsd vpminub vpminuw vpminud vpmovmskb vpmovsxbw vpmovsxbd vpmovsxbq vpmovsxwd vpmovsxwq vpmovsxdq vpmovzxbw vpmovzxbd vpmovzxbq vpmovzxwd vpmovzxwq vpmovzxdq vpmulhuw vpmulhrsw vpmulhw vpmullw vpmulld vpmuludq vpmuldq vpor vpsadbw vpshufb vpshufd vpshufhw vpshuflw vpsignb vpsignw vpsignd vpslldq vpsrldq vpsllw vpslld vpsllq vpsraw vpsrad vpsrlw vpsrld vpsrlq vptest vpsubb vpsubw vpsubd vpsubq vpsubsb vpsubsw vpsubusb vpsubusw vpunpckhbw vpunpckhwd vpunpckhdq vpunpckhqdq vpunpcklbw vpunpcklwd vpunpckldq vpunpcklqdq vpxor vrcpps vrcpss vrsqrtps vrsqrtss vroundpd vroundps vroundsd vroundss vshufpd vshufps vsqrtpd vsqrtps vsqrtsd vsqrtss vstmxcsr vsubpd vsubps vsubsd vsubss vtestps vtestpd vucomisd vucomiss vunpckhpd vunpckhps vunpcklpd vunpcklps vxorpd vxorps vzeroall vzeroupper pclmullqlqdq pclmulhqlqdq pclmullqhqdq pclmulhqhqdq pclmulqdq vpclmullqlqdq vpclmulhqlqdq vpclmullqhqdq vpclmulhqhqdq vpclmulqdq vfmadd132ps vfmadd132pd vfmadd312ps vfmadd312pd vfmadd213ps vfmadd213pd vfmadd123ps vfmadd123pd vfmadd231ps vfmadd231pd vfmadd321ps vfmadd321pd vfmaddsub132ps vfmaddsub132pd vfmaddsub312ps vfmaddsub312pd vfmaddsub213ps vfmaddsub213pd vfmaddsub123ps vfmaddsub123pd vfmaddsub231ps vfmaddsub231pd vfmaddsub321ps vfmaddsub321pd vfmsub132ps vfmsub132pd vfmsub312ps vfmsub312pd vfmsub213ps vfmsub213pd vfmsub123ps vfmsub123pd vfmsub231ps vfmsub231pd vfmsub321ps vfmsub321pd vfmsubadd132ps vfmsubadd132pd vfmsubadd312ps vfmsubadd312pd vfmsubadd213ps vfmsubadd213pd vfmsubadd123ps vfmsubadd123pd vfmsubadd231ps vfmsubadd231pd vfmsubadd321ps vfmsubadd321pd vfnmadd132ps vfnmadd132pd vfnmadd312ps vfnmadd312pd vfnmadd213ps vfnmadd213pd vfnmadd123ps vfnmadd123pd vfnmadd231ps vfnmadd231pd vfnmadd321ps vfnmadd321pd vfnmsub132ps vfnmsub132pd vfnmsub312ps vfnmsub312pd vfnmsub213ps vfnmsub213pd vfnmsub123ps vfnmsub123pd vfnmsub231ps vfnmsub231pd vfnmsub321ps vfnmsub321pd vfmadd132ss vfmadd132sd vfmadd312ss vfmadd312sd vfmadd213ss vfmadd213sd vfmadd123ss vfmadd123sd vfmadd231ss vfmadd231sd vfmadd321ss vfmadd321sd vfmsub132ss vfmsub132sd vfmsub312ss vfmsub312sd vfmsub213ss vfmsub213sd vfmsub123ss vfmsub123sd vfmsub231ss vfmsub231sd vfmsub321ss vfmsub321sd vfnmadd132ss vfnmadd132sd vfnmadd312ss vfnmadd312sd vfnmadd213ss vfnmadd213sd vfnmadd123ss vfnmadd123sd vfnmadd231ss vfnmadd231sd vfnmadd321ss vfnmadd321sd vfnmsub132ss vfnmsub132sd vfnmsub312ss vfnmsub312sd vfnmsub213ss vfnmsub213sd vfnmsub123ss vfnmsub123sd vfnmsub231ss vfnmsub231sd vfnmsub321ss vfnmsub321sd rdfsbase rdgsbase rdrand wrfsbase wrgsbase vcvtph2ps vcvtps2ph adcx adox rdseed clac stac xstore xcryptecb xcryptcbc xcryptctr xcryptcfb xcryptofb montmul xsha1 xsha256 llwpcb slwpcb lwpval lwpins vfmaddpd vfmaddps vfmaddsd vfmaddss vfmaddsubpd vfmaddsubps vfmsubaddpd vfmsubaddps vfmsubpd vfmsubps vfmsubsd vfmsubss vfnmaddpd vfnmaddps vfnmaddsd vfnmaddss vfnmsubpd vfnmsubps vfnmsubsd vfnmsubss vfrczpd vfrczps vfrczsd vfrczss vpcmov vpcomb vpcomd vpcomq vpcomub vpcomud vpcomuq vpcomuw vpcomw vphaddbd vphaddbq vphaddbw vphadddq vphaddubd vphaddubq vphaddubw vphaddudq vphadduwd vphadduwq vphaddwd vphaddwq vphsubbw vphsubdq vphsubwd vpmacsdd vpmacsdqh vpmacsdql vpmacssdd vpmacssdqh vpmacssdql vpmacsswd vpmacssww vpmacswd vpmacsww vpmadcsswd vpmadcswd vpperm vprotb vprotd vprotq vprotw vpshab vpshad vpshaq vpshaw vpshlb vpshld vpshlq vpshlw vbroadcasti128 vpblendd vpbroadcastb vpbroadcastw vpbroadcastd vpbroadcastq vpermd vpermpd vpermps vpermq vperm2i128 vextracti128 vinserti128 vpmaskmovd vpmaskmovq vpsllvd vpsllvq vpsravd vpsrlvd vpsrlvq vgatherdpd vgatherqpd vgatherdps vgatherqps vpgatherdd vpgatherqd vpgatherdq vpgatherqq xabort xbegin xend xtest andn bextr blci blcic blsi blsic blcfill blsfill blcmsk blsmsk blsr blcs bzhi mulx pdep pext rorx sarx shlx shrx tzcnt tzmsk t1mskc valignd valignq vblendmpd vblendmps vbroadcastf32x4 vbroadcastf64x4 vbroadcasti32x4 vbroadcasti64x4 vcompresspd vcompressps vcvtpd2udq vcvtps2udq vcvtsd2usi vcvtss2usi vcvttpd2udq vcvttps2udq vcvttsd2usi vcvttss2usi vcvtudq2pd vcvtudq2ps vcvtusi2sd vcvtusi2ss vexpandpd vexpandps vextractf32x4 vextractf64x4 vextracti32x4 vextracti64x4 vfixupimmpd vfixupimmps vfixupimmsd vfixupimmss vgetexppd vgetexpps vgetexpsd vgetexpss vgetmantpd vgetmantps vgetmantsd vgetmantss vinsertf32x4 vinsertf64x4 vinserti32x4 vinserti64x4 vmovdqa32 vmovdqa64 vmovdqu32 vmovdqu64 vpabsq vpandd vpandnd vpandnq vpandq vpblendmd vpblendmq vpcmpltd vpcmpled vpcmpneqd vpcmpnltd vpcmpnled vpcmpd vpcmpltq vpcmpleq vpcmpneqq vpcmpnltq vpcmpnleq vpcmpq vpcmpequd vpcmpltud vpcmpleud vpcmpnequd vpcmpnltud vpcmpnleud vpcmpud vpcmpequq vpcmpltuq vpcmpleuq vpcmpnequq vpcmpnltuq vpcmpnleuq vpcmpuq vpcompressd vpcompressq vpermi2d vpermi2pd vpermi2ps vpermi2q vpermt2d vpermt2pd vpermt2ps vpermt2q vpexpandd vpexpandq vpmaxsq vpmaxuq vpminsq vpminuq vpmovdb vpmovdw vpmovqb vpmovqd vpmovqw vpmovsdb vpmovsdw vpmovsqb vpmovsqd vpmovsqw vpmovusdb vpmovusdw vpmovusqb vpmovusqd vpmovusqw vpord vporq vprold vprolq vprolvd vprolvq vprord vprorq vprorvd vprorvq vpscatterdd vpscatterdq vpscatterqd vpscatterqq vpsraq vpsravq vpternlogd vpternlogq vptestmd vptestmq vptestnmd vptestnmq vpxord vpxorq vrcp14pd vrcp14ps vrcp14sd vrcp14ss vrndscalepd vrndscaleps vrndscalesd vrndscaless vrsqrt14pd vrsqrt14ps vrsqrt14sd vrsqrt14ss vscalefpd vscalefps vscalefsd vscalefss vscatterdpd vscatterdps vscatterqpd vscatterqps vshuff32x4 vshuff64x2 vshufi32x4 vshufi64x2 kandnw kandw kmovw knotw kortestw korw kshiftlw kshiftrw kunpckbw kxnorw kxorw vpbroadcastmb2q vpbroadcastmw2d vpconflictd vpconflictq vplzcntd vplzcntq vexp2pd vexp2ps vrcp28pd vrcp28ps vrcp28sd vrcp28ss vrsqrt28pd vrsqrt28ps vrsqrt28sd vrsqrt28ss vgatherpf0dpd vgatherpf0dps vgatherpf0qpd vgatherpf0qps vgatherpf1dpd vgatherpf1dps vgatherpf1qpd vgatherpf1qps vscatterpf0dpd vscatterpf0dps vscatterpf0qpd vscatterpf0qps vscatterpf1dpd vscatterpf1dps vscatterpf1qpd vscatterpf1qps prefetchwt1 bndmk bndcl bndcu bndcn bndmov bndldx bndstx sha1rnds4 sha1nexte sha1msg1 sha1msg2 sha256rnds2 sha256msg1 sha256msg2 hint_nop0 hint_nop1 hint_nop2 hint_nop3 hint_nop4 hint_nop5 hint_nop6 hint_nop7 hint_nop8 hint_nop9 hint_nop10 hint_nop11 hint_nop12 hint_nop13 hint_nop14 hint_nop15 hint_nop16 hint_nop17 hint_nop18 hint_nop19 hint_nop20 hint_nop21 hint_nop22 hint_nop23 hint_nop24 hint_nop25 hint_nop26 hint_nop27 hint_nop28 hint_nop29 hint_nop30 hint_nop31 hint_nop32 hint_nop33 hint_nop34 hint_nop35 hint_nop36 hint_nop37 hint_nop38 hint_nop39 hint_nop40 hint_nop41 hint_nop42 hint_nop43 hint_nop44 hint_nop45 hint_nop46 hint_nop47 hint_nop48 hint_nop49 hint_nop50 hint_nop51 hint_nop52 hint_nop53 hint_nop54 hint_nop55 hint_nop56 hint_nop57 hint_nop58 hint_nop59 hint_nop60 hint_nop61 hint_nop62 hint_nop63",built_in:"ip eip rip al ah bl bh cl ch dl dh sil dil bpl spl r8b r9b r10b r11b r12b r13b r14b r15b ax bx cx dx si di bp sp r8w r9w r10w r11w r12w r13w r14w r15w eax ebx ecx edx esi edi ebp esp eip r8d r9d r10d r11d r12d r13d r14d r15d rax rbx rcx rdx rsi rdi rbp rsp r8 r9 r10 r11 r12 r13 r14 r15 cs ds es fs gs ss st st0 st1 st2 st3 st4 st5 st6 st7 mm0 mm1 mm2 mm3 mm4 mm5 mm6 mm7 xmm0 xmm1 xmm2 xmm3 xmm4 xmm5 xmm6 xmm7 xmm8 xmm9 xmm10 xmm11 xmm12 xmm13 xmm14 xmm15 xmm16 xmm17 xmm18 xmm19 xmm20 xmm21 xmm22 xmm23 xmm24 xmm25 xmm26 xmm27 xmm28 xmm29 xmm30 xmm31 ymm0 ymm1 ymm2 ymm3 ymm4 ymm5 ymm6 ymm7 ymm8 ymm9 ymm10 ymm11 ymm12 ymm13 ymm14 ymm15 ymm16 ymm17 ymm18 ymm19 ymm20 ymm21 ymm22 ymm23 ymm24 ymm25 ymm26 ymm27 ymm28 ymm29 ymm30 ymm31 zmm0 zmm1 zmm2 zmm3 zmm4 zmm5 zmm6 zmm7 zmm8 zmm9 zmm10 zmm11 zmm12 zmm13 zmm14 zmm15 zmm16 zmm17 zmm18 zmm19 zmm20 zmm21 zmm22 zmm23 zmm24 zmm25 zmm26 zmm27 zmm28 zmm29 zmm30 zmm31 k0 k1 k2 k3 k4 k5 k6 k7 bnd0 bnd1 bnd2 bnd3 cr0 cr1 cr2 cr3 cr4 cr8 dr0 dr1 dr2 dr3 dr8 tr3 tr4 tr5 tr6 tr7 r0 r1 r2 r3 r4 r5 r6 r7 r0b r1b r2b r3b r4b r5b r6b r7b r0w r1w r2w r3w r4w r5w r6w r7w r0d r1d r2d r3d r4d r5d r6d r7d r0h r1h r2h r3h r0l r1l r2l r3l r4l r5l r6l r7l r8l r9l r10l r11l r12l r13l r14l r15l db dw dd dq dt ddq do dy dz resb resw resd resq rest resdq reso resy resz incbin equ times byte word dword qword nosplit rel abs seg wrt strict near far a32 ptr",meta:"%define %xdefine %+ %undef %defstr %deftok %assign %strcat %strlen %substr %rotate %elif %else %endif %if %ifmacro %ifctx %ifidn %ifidni %ifid %ifnum %ifstr %iftoken %ifempty %ifenv %error %warning %fatal %rep %endrep %include %push %pop %repl %pathsearch %depend %use %arg %stacksize %local %line %comment %endcomment .nolist __FILE__ __LINE__ __SECT__ __BITS__ __OUTPUT_FORMAT__ __DATE__ __TIME__ __DATE_NUM__ __TIME_NUM__ __UTC_DATE__ __UTC_TIME__ __UTC_DATE_NUM__ __UTC_TIME_NUM__ __PASS__ struc endstruc istruc at iend align alignb sectalign daz nodaz up down zero default option assume public bits use16 use32 use64 default section segment absolute extern global common cpu float __utf16__ __utf16le__ __utf16be__ __utf32__ __utf32le__ __utf32be__ __float8__ __float16__ __float32__ __float64__ __float80m__ __float80e__ __float128l__ __float128h__ __Infinity__ __QNaN__ __SNaN__ Inf NaN QNaN SNaN float8 float16 float32 float64 float80m float80e float128l float128h __FLOAT_DAZ__ __FLOAT_ROUND__ __FLOAT__"},contains:[s.COMMENT(";","$",{relevance:0}),{className:"number",variants:[{begin:"\\b(?:([0-9][0-9_]*)?\\.[0-9_]*(?:[eE][+-]?[0-9_]+)?|(0[Xx])?[0-9][0-9_]*\\.?[0-9_]*(?:[pP](?:[+-]?[0-9_]+)?)?)\\b",relevance:0},{begin:"\\$[0-9][0-9A-Fa-f]*",relevance:0},{begin:"\\b(?:[0-9A-Fa-f][0-9A-Fa-f_]*[Hh]|[0-9][0-9_]*[DdTt]?|[0-7][0-7_]*[QqOo]|[0-1][0-1_]*[BbYy])\\b"},{begin:"\\b(?:0[Xx][0-9A-Fa-f_]+|0[DdTt][0-9_]+|0[QqOo][0-7_]+|0[BbYy][0-1_]+)\\b"}]},s.QUOTE_STRING_MODE,{className:"string",variants:[{begin:"'",end:"[^\\\\]'"},{begin:"`",end:"[^\\\\]`"}],relevance:0},{className:"symbol",variants:[{begin:"^\\s*[A-Za-z._?][A-Za-z0-9_$#@~.?]*(:|\\s+label)"},{begin:"^\\s*%%[A-Za-z0-9_$#@~.?]*:"}],relevance:0},{className:"subst",begin:"%[0-9]+",relevance:0},{className:"subst",begin:"%!S+",relevance:0},{className:"meta",begin:/^\s*\.[\w_-]+/}]}}}()); \ No newline at end of file diff --git a/projects/rust/tutorial/index.html b/projects/rust/tutorial/index.html new file mode 100644 index 00000000000..8fb0a290fc0 --- /dev/null +++ b/projects/rust/tutorial/index.html @@ -0,0 +1,239 @@ + + + + + + Introduction - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Tutorial: Using Rust in seL4 Userspace

+

seL4 has official support for Rust in userspace, funded by the seL4 Foundation:

+

https://github.com/seL4/rust-sel4

+

The exports of this project covered in this tutorial are:

+
    +
  • Rust bindings for the seL4 API
    • +
  • A runtime for root tasks
    • +
  • Rust bindings for the seL4 Microkit API
    • +
  • A runtime for seL4 Microkit protection domains
    • +
  • Custom rustc target specifications for seL4 userspace
    • +
+

Part I covers the Rust bindings for the seL4 API and the runtime for root tasks. +Familiarity with the seL4 API isn't necessarily assumed or required, but this text doesn't introduce its elements in as much detail as the seL4 Manual.

+

Part II is much shorter, and covers the Rust language runtime for seL4 Microkit protection domains and implementation of the Microkit API. +This part does assume that the reader is familiar with the basics of the Microkit framework and API, or is using a companion resource to learn about the Microkit in parallel.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/introduction.html b/projects/rust/tutorial/introduction.html new file mode 100644 index 00000000000..8fb0a290fc0 --- /dev/null +++ b/projects/rust/tutorial/introduction.html @@ -0,0 +1,239 @@ + + + + + + Introduction - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Tutorial: Using Rust in seL4 Userspace

+

seL4 has official support for Rust in userspace, funded by the seL4 Foundation:

+

https://github.com/seL4/rust-sel4

+

The exports of this project covered in this tutorial are:

+
    +
  • Rust bindings for the seL4 API
    • +
  • A runtime for root tasks
    • +
  • Rust bindings for the seL4 Microkit API
    • +
  • A runtime for seL4 Microkit protection domains
    • +
  • Custom rustc target specifications for seL4 userspace
    • +
+

Part I covers the Rust bindings for the seL4 API and the runtime for root tasks. +Familiarity with the seL4 API isn't necessarily assumed or required, but this text doesn't introduce its elements in as much detail as the seL4 Manual.

+

Part II is much shorter, and covers the Rust language runtime for seL4 Microkit protection domains and implementation of the Microkit API. +This part does assume that the reader is familiar with the basics of the Microkit framework and API, or is using a companion resource to learn about the Microkit in parallel.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/mark.min.js b/projects/rust/tutorial/mark.min.js new file mode 100644 index 00000000000..16362318834 --- /dev/null +++ b/projects/rust/tutorial/mark.min.js @@ -0,0 +1,7 @@ +/*!*************************************************** +* mark.js v8.11.1 +* https://markjs.io/ +* Copyright (c) 2014–2018, Julian Kühnel +* Released under the MIT license https://git.io/vwTVl +*****************************************************/ +!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n1&&void 0!==arguments[1])||arguments[1],i=arguments.length>2&&void 0!==arguments[2]?arguments[2]:[],o=arguments.length>3&&void 0!==arguments[3]?arguments[3]:5e3;t(this,e),this.ctx=n,this.iframes=r,this.exclude=i,this.iframesTimeout=o}return n(e,[{key:"getContexts",value:function(){var e=[];return(void 0!==this.ctx&&this.ctx?NodeList.prototype.isPrototypeOf(this.ctx)?Array.prototype.slice.call(this.ctx):Array.isArray(this.ctx)?this.ctx:"string"==typeof this.ctx?Array.prototype.slice.call(document.querySelectorAll(this.ctx)):[this.ctx]:[]).forEach(function(t){var n=e.filter(function(e){return e.contains(t)}).length>0;-1!==e.indexOf(t)||n||e.push(t)}),e}},{key:"getIframeContents",value:function(e,t){var n=arguments.length>2&&void 0!==arguments[2]?arguments[2]:function(){},r=void 0;try{var i=e.contentWindow;if(r=i.document,!i||!r)throw new Error("iframe inaccessible")}catch(e){n()}r&&t(r)}},{key:"isIframeBlank",value:function(e){var t="about:blank",n=e.getAttribute("src").trim();return e.contentWindow.location.href===t&&n!==t&&n}},{key:"observeIframeLoad",value:function(e,t,n){var r=this,i=!1,o=null,a=function a(){if(!i){i=!0,clearTimeout(o);try{r.isIframeBlank(e)||(e.removeEventListener("load",a),r.getIframeContents(e,t,n))}catch(e){n()}}};e.addEventListener("load",a),o=setTimeout(a,this.iframesTimeout)}},{key:"onIframeReady",value:function(e,t,n){try{"complete"===e.contentWindow.document.readyState?this.isIframeBlank(e)?this.observeIframeLoad(e,t,n):this.getIframeContents(e,t,n):this.observeIframeLoad(e,t,n)}catch(e){n()}}},{key:"waitForIframes",value:function(e,t){var n=this,r=0;this.forEachIframe(e,function(){return!0},function(e){r++,n.waitForIframes(e.querySelector("html"),function(){--r||t()})},function(e){e||t()})}},{key:"forEachIframe",value:function(t,n,r){var i=this,o=arguments.length>3&&void 0!==arguments[3]?arguments[3]:function(){},a=t.querySelectorAll("iframe"),s=a.length,c=0;a=Array.prototype.slice.call(a);var u=function(){--s<=0&&o(c)};s||u(),a.forEach(function(t){e.matches(t,i.exclude)?u():i.onIframeReady(t,function(e){n(t)&&(c++,r(e)),u()},u)})}},{key:"createIterator",value:function(e,t,n){return document.createNodeIterator(e,t,n,!1)}},{key:"createInstanceOnIframe",value:function(t){return new e(t.querySelector("html"),this.iframes)}},{key:"compareNodeIframe",value:function(e,t,n){if(e.compareDocumentPosition(n)&Node.DOCUMENT_POSITION_PRECEDING){if(null===t)return!0;if(t.compareDocumentPosition(n)&Node.DOCUMENT_POSITION_FOLLOWING)return!0}return!1}},{key:"getIteratorNode",value:function(e){var t=e.previousNode();return{prevNode:t,node:null===t?e.nextNode():e.nextNode()&&e.nextNode()}}},{key:"checkIframeFilter",value:function(e,t,n,r){var i=!1,o=!1;return r.forEach(function(e,t){e.val===n&&(i=t,o=e.handled)}),this.compareNodeIframe(e,t,n)?(!1!==i||o?!1===i||o||(r[i].handled=!0):r.push({val:n,handled:!0}),!0):(!1===i&&r.push({val:n,handled:!1}),!1)}},{key:"handleOpenIframes",value:function(e,t,n,r){var i=this;e.forEach(function(e){e.handled||i.getIframeContents(e.val,function(e){i.createInstanceOnIframe(e).forEachNode(t,n,r)})})}},{key:"iterateThroughNodes",value:function(e,t,n,r,i){for(var o,a=this,s=this.createIterator(t,e,r),c=[],u=[],l=void 0,h=void 0;void 0,o=a.getIteratorNode(s),h=o.prevNode,l=o.node;)this.iframes&&this.forEachIframe(t,function(e){return a.checkIframeFilter(l,h,e,c)},function(t){a.createInstanceOnIframe(t).forEachNode(e,function(e){return u.push(e)},r)}),u.push(l);u.forEach(function(e){n(e)}),this.iframes&&this.handleOpenIframes(c,e,n,r),i()}},{key:"forEachNode",value:function(e,t,n){var r=this,i=arguments.length>3&&void 0!==arguments[3]?arguments[3]:function(){},o=this.getContexts(),a=o.length;a||i(),o.forEach(function(o){var s=function(){r.iterateThroughNodes(e,o,t,n,function(){--a<=0&&i()})};r.iframes?r.waitForIframes(o,s):s()})}}],[{key:"matches",value:function(e,t){var n="string"==typeof t?[t]:t,r=e.matches||e.matchesSelector||e.msMatchesSelector||e.mozMatchesSelector||e.oMatchesSelector||e.webkitMatchesSelector;if(r){var i=!1;return n.every(function(t){return!r.call(e,t)||(i=!0,!1)}),i}return!1}}]),e}(),o=function(){function e(n){t(this,e),this.opt=r({},{diacritics:!0,synonyms:{},accuracy:"partially",caseSensitive:!1,ignoreJoiners:!1,ignorePunctuation:[],wildcards:"disabled"},n)}return n(e,[{key:"create",value:function(e){return"disabled"!==this.opt.wildcards&&(e=this.setupWildcardsRegExp(e)),e=this.escapeStr(e),Object.keys(this.opt.synonyms).length&&(e=this.createSynonymsRegExp(e)),(this.opt.ignoreJoiners||this.opt.ignorePunctuation.length)&&(e=this.setupIgnoreJoinersRegExp(e)),this.opt.diacritics&&(e=this.createDiacriticsRegExp(e)),e=this.createMergedBlanksRegExp(e),(this.opt.ignoreJoiners||this.opt.ignorePunctuation.length)&&(e=this.createJoinersRegExp(e)),"disabled"!==this.opt.wildcards&&(e=this.createWildcardsRegExp(e)),e=this.createAccuracyRegExp(e),new RegExp(e,"gm"+(this.opt.caseSensitive?"":"i"))}},{key:"escapeStr",value:function(e){return e.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g,"\\$&")}},{key:"createSynonymsRegExp",value:function(e){var t=this.opt.synonyms,n=this.opt.caseSensitive?"":"i",r=this.opt.ignoreJoiners||this.opt.ignorePunctuation.length?"\0":"";for(var i in t)if(t.hasOwnProperty(i)){var o=t[i],a="disabled"!==this.opt.wildcards?this.setupWildcardsRegExp(i):this.escapeStr(i),s="disabled"!==this.opt.wildcards?this.setupWildcardsRegExp(o):this.escapeStr(o);""!==a&&""!==s&&(e=e.replace(new RegExp("("+this.escapeStr(a)+"|"+this.escapeStr(s)+")","gm"+n),r+"("+this.processSynonyms(a)+"|"+this.processSynonyms(s)+")"+r))}return e}},{key:"processSynonyms",value:function(e){return(this.opt.ignoreJoiners||this.opt.ignorePunctuation.length)&&(e=this.setupIgnoreJoinersRegExp(e)),e}},{key:"setupWildcardsRegExp",value:function(e){return(e=e.replace(/(?:\\)*\?/g,function(e){return"\\"===e.charAt(0)?"?":""})).replace(/(?:\\)*\*/g,function(e){return"\\"===e.charAt(0)?"*":""})}},{key:"createWildcardsRegExp",value:function(e){var t="withSpaces"===this.opt.wildcards;return e.replace(/\u0001/g,t?"[\\S\\s]?":"\\S?").replace(/\u0002/g,t?"[\\S\\s]*?":"\\S*")}},{key:"setupIgnoreJoinersRegExp",value:function(e){return e.replace(/[^(|)\\]/g,function(e,t,n){var r=n.charAt(t+1);return/[(|)\\]/.test(r)||""===r?e:e+"\0"})}},{key:"createJoinersRegExp",value:function(e){var t=[],n=this.opt.ignorePunctuation;return Array.isArray(n)&&n.length&&t.push(this.escapeStr(n.join(""))),this.opt.ignoreJoiners&&t.push("\\u00ad\\u200b\\u200c\\u200d"),t.length?e.split(/\u0000+/).join("["+t.join("")+"]*"):e}},{key:"createDiacriticsRegExp",value:function(e){var t=this.opt.caseSensitive?"":"i",n=this.opt.caseSensitive?["aàáảãạăằắẳẵặâầấẩẫậäåāą","AÀÁẢÃẠĂẰẮẲẴẶÂẦẤẨẪẬÄÅĀĄ","cçćč","CÇĆČ","dđď","DĐĎ","eèéẻẽẹêềếểễệëěēę","EÈÉẺẼẸÊỀẾỂỄỆËĚĒĘ","iìíỉĩịîïī","IÌÍỈĨỊÎÏĪ","lł","LŁ","nñňń","NÑŇŃ","oòóỏõọôồốổỗộơởỡớờợöøō","OÒÓỎÕỌÔỒỐỔỖỘƠỞỠỚỜỢÖØŌ","rř","RŘ","sšśșş","SŠŚȘŞ","tťțţ","TŤȚŢ","uùúủũụưừứửữựûüůū","UÙÚỦŨỤƯỪỨỬỮỰÛÜŮŪ","yýỳỷỹỵÿ","YÝỲỶỸỴŸ","zžżź","ZŽŻŹ"]:["aàáảãạăằắẳẵặâầấẩẫậäåāąAÀÁẢÃẠĂẰẮẲẴẶÂẦẤẨẪẬÄÅĀĄ","cçćčCÇĆČ","dđďDĐĎ","eèéẻẽẹêềếểễệëěēęEÈÉẺẼẸÊỀẾỂỄỆËĚĒĘ","iìíỉĩịîïīIÌÍỈĨỊÎÏĪ","lłLŁ","nñňńNÑŇŃ","oòóỏõọôồốổỗộơởỡớờợöøōOÒÓỎÕỌÔỒỐỔỖỘƠỞỠỚỜỢÖØŌ","rřRŘ","sšśșşSŠŚȘŞ","tťțţTŤȚŢ","uùúủũụưừứửữựûüůūUÙÚỦŨỤƯỪỨỬỮỰÛÜŮŪ","yýỳỷỹỵÿYÝỲỶỸỴŸ","zžżźZŽŻŹ"],r=[];return e.split("").forEach(function(i){n.every(function(n){if(-1!==n.indexOf(i)){if(r.indexOf(n)>-1)return!1;e=e.replace(new RegExp("["+n+"]","gm"+t),"["+n+"]"),r.push(n)}return!0})}),e}},{key:"createMergedBlanksRegExp",value:function(e){return e.replace(/[\s]+/gim,"[\\s]+")}},{key:"createAccuracyRegExp",value:function(e){var t=this,n=this.opt.accuracy,r="string"==typeof n?n:n.value,i="";switch(("string"==typeof n?[]:n.limiters).forEach(function(e){i+="|"+t.escapeStr(e)}),r){case"partially":default:return"()("+e+")";case"complementary":return"()([^"+(i="\\s"+(i||this.escapeStr("!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~¡¿")))+"]*"+e+"[^"+i+"]*)";case"exactly":return"(^|\\s"+i+")("+e+")(?=$|\\s"+i+")"}}}]),e}(),a=function(){function a(e){t(this,a),this.ctx=e,this.ie=!1;var n=window.navigator.userAgent;(n.indexOf("MSIE")>-1||n.indexOf("Trident")>-1)&&(this.ie=!0)}return n(a,[{key:"log",value:function(t){var n=arguments.length>1&&void 0!==arguments[1]?arguments[1]:"debug",r=this.opt.log;this.opt.debug&&"object"===(void 0===r?"undefined":e(r))&&"function"==typeof r[n]&&r[n]("mark.js: "+t)}},{key:"getSeparatedKeywords",value:function(e){var t=this,n=[];return e.forEach(function(e){t.opt.separateWordSearch?e.split(" ").forEach(function(e){e.trim()&&-1===n.indexOf(e)&&n.push(e)}):e.trim()&&-1===n.indexOf(e)&&n.push(e)}),{keywords:n.sort(function(e,t){return t.length-e.length}),length:n.length}}},{key:"isNumeric",value:function(e){return Number(parseFloat(e))==e}},{key:"checkRanges",value:function(e){var t=this;if(!Array.isArray(e)||"[object Object]"!==Object.prototype.toString.call(e[0]))return this.log("markRanges() will only accept an array of objects"),this.opt.noMatch(e),[];var n=[],r=0;return e.sort(function(e,t){return e.start-t.start}).forEach(function(e){var i=t.callNoMatchOnInvalidRanges(e,r),o=i.start,a=i.end;i.valid&&(e.start=o,e.length=a-o,n.push(e),r=a)}),n}},{key:"callNoMatchOnInvalidRanges",value:function(e,t){var n=void 0,r=void 0,i=!1;return e&&void 0!==e.start?(r=(n=parseInt(e.start,10))+parseInt(e.length,10),this.isNumeric(e.start)&&this.isNumeric(e.length)&&r-t>0&&r-n>0?i=!0:(this.log("Ignoring invalid or overlapping range: "+JSON.stringify(e)),this.opt.noMatch(e))):(this.log("Ignoring invalid range: "+JSON.stringify(e)),this.opt.noMatch(e)),{start:n,end:r,valid:i}}},{key:"checkWhitespaceRanges",value:function(e,t,n){var r=void 0,i=!0,o=n.length,a=t-o,s=parseInt(e.start,10)-a;return(r=(s=s>o?o:s)+parseInt(e.length,10))>o&&(r=o,this.log("End range automatically set to the max value of "+o)),s<0||r-s<0||s>o||r>o?(i=!1,this.log("Invalid range: "+JSON.stringify(e)),this.opt.noMatch(e)):""===n.substring(s,r).replace(/\s+/g,"")&&(i=!1,this.log("Skipping whitespace only range: "+JSON.stringify(e)),this.opt.noMatch(e)),{start:s,end:r,valid:i}}},{key:"getTextNodes",value:function(e){var t=this,n="",r=[];this.iterator.forEachNode(NodeFilter.SHOW_TEXT,function(e){r.push({start:n.length,end:(n+=e.textContent).length,node:e})},function(e){return t.matchesExclude(e.parentNode)?NodeFilter.FILTER_REJECT:NodeFilter.FILTER_ACCEPT},function(){e({value:n,nodes:r})})}},{key:"matchesExclude",value:function(e){return i.matches(e,this.opt.exclude.concat(["script","style","title","head","html"]))}},{key:"wrapRangeInTextNode",value:function(e,t,n){var r=this.opt.element?this.opt.element:"mark",i=e.splitText(t),o=i.splitText(n-t),a=document.createElement(r);return a.setAttribute("data-markjs","true"),this.opt.className&&a.setAttribute("class",this.opt.className),a.textContent=i.textContent,i.parentNode.replaceChild(a,i),o}},{key:"wrapRangeInMappedTextNode",value:function(e,t,n,r,i){var o=this;e.nodes.every(function(a,s){var c=e.nodes[s+1];if(void 0===c||c.start>t){if(!r(a.node))return!1;var u=t-a.start,l=(n>a.end?a.end:n)-a.start,h=e.value.substr(0,a.start),f=e.value.substr(l+a.start);if(a.node=o.wrapRangeInTextNode(a.node,u,l),e.value=h+f,e.nodes.forEach(function(t,n){n>=s&&(e.nodes[n].start>0&&n!==s&&(e.nodes[n].start-=l),e.nodes[n].end-=l)}),n-=l,i(a.node.previousSibling,a.start),!(n>a.end))return!1;t=a.end}return!0})}},{key:"wrapGroups",value:function(e,t,n,r){return r((e=this.wrapRangeInTextNode(e,t,t+n)).previousSibling),e}},{key:"separateGroups",value:function(e,t,n,r,i){for(var o=t.length,a=1;a-1&&r(t[a],e)&&(e=this.wrapGroups(e,s,t[a].length,i))}return e}},{key:"wrapMatches",value:function(e,t,n,r,i){var o=this,a=0===t?0:t+1;this.getTextNodes(function(t){t.nodes.forEach(function(t){t=t.node;for(var i=void 0;null!==(i=e.exec(t.textContent))&&""!==i[a];){if(o.opt.separateGroups)t=o.separateGroups(t,i,a,n,r);else{if(!n(i[a],t))continue;var s=i.index;if(0!==a)for(var c=1;c + + + + + Hello, World! - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Hello, World!

+

Navigate to and run the hello world Microkit example:

+
cd workspaces/microkit/hello-world
+make simulate
+
+

Here is its source:

+
+
+
hello-world/pds/hello/src/main.rs:7:22
+
+
+
#![no_std]
+#![no_main]
+
+use sel4_microkit::{debug_println, protection_domain, Handler, Infallible};
+
+#[protection_domain]
+fn init() -> impl Handler {
+    debug_println!("Hello, World!");
+    HandlerImpl
+}
+
+struct HandlerImpl;
+
+impl Handler for HandlerImpl {
+    type Error = Infallible;
+}
+
+
+
+

The sel4_microkit crate implements a Rust language runtime for Microkit protection domains, and implements the Microkit API. +It is written in pure Rust, and does not link against libmicrokit.

+

The Event Handler

+

The #[protection_domain] attribute macro declares a function to be the protection domain's initialization function. +The entrypoint function must have a signature of the form:

+
fn() -> T
+where
+    T: sel4_microkit::Handler
+

An implementation of the Handler trait is used by the runtime as the event handler for the protection domain's main loop. +The +notified, +protected, +and +fault +methods correspond to their equivalents in <microkit.h>.

+

The default implementations of these methods just panic. +Our event handler, which we've called HandlerImpl, is the simplest possible Handler implementation.

+

Language Runtime

+

As detailed in its rustdoc, the #[protection_domain] attribute macro takes the same parameters as #[root_task]. +Furthermore, the sel4_microkit crate supports all of the same Rust language runtime elements that we explored in Chapter 2, including +sel4_microkit::panicking::catch_unwind() +and +sel4_microkit::panicking::set_hook() +.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/microkit/index.html b/projects/rust/tutorial/microkit/index.html new file mode 100644 index 00000000000..0126c476232 --- /dev/null +++ b/projects/rust/tutorial/microkit/index.html @@ -0,0 +1,239 @@ + + + + + + Overview - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

seL4 Microkit

+

The seL4 Microkit is a framework for creating static systems based on seL4. +This part of the text assumes that the reader is familiar with the basics of the Microkit framework and API, or is using a companion resource to learn about the Microkit in parallel. +Here are three such resources:

+ +

This part also assumes that the reader has worked through chapters 2 and 6 of Part I.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/microkit/ipc.html b/projects/rust/tutorial/microkit/ipc.html new file mode 100644 index 00000000000..7980a9d7f77 --- /dev/null +++ b/projects/rust/tutorial/microkit/ipc.html @@ -0,0 +1,363 @@ + + + + + + IPC - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

IPC

+

This chapter covers making and handling protected procedure calls in protection domains written in Rust. +Navigate to and run the example:

+
cd workspaces/microkit/ipc
+make simulate
+
+

The example system description specifies two protection domains, with a channel between them:

+
+
+
ipc.system:7:20
+
+
+
<system>
+    <protection_domain name="client" priority="100">
+        <program_image path="microkit-ipc-client.elf" />
+    </protection_domain>
+
+    <protection_domain name="server" priority="200">
+        <program_image path="microkit-ipc-server.elf" />
+    </protection_domain>
+
+    <channel>
+        <end pd="client" id="13" pp="true" />
+        <end pd="server" id="37" />
+    </channel>
+</system>
+
+
+
+
+
+
+
pds/client/src/main.rs:14:36
+
+
+
const SERVER: Channel = Channel::new(13);
+
+#[protection_domain]
+fn init() -> impl Handler {
+    debug_println!("client: initializing");
+    HandlerImpl
+}
+
+struct HandlerImpl;
+
+impl Handler for HandlerImpl {
+    type Error = Infallible;
+
+    fn notified(&mut self, channels: ChannelSet) -> Result<(), Self::Error> {
+        debug_println!("client: notified by {}", channels.display());
+
+        if channels.contains(SERVER) {
+            debug_println!("client: TEST_PASS");
+        }
+
+        Ok(())
+    }
+}
+
+
+
+
+
+
pds/server/src/main.rs:12:39
+
+
+
const CLIENT: Channel = Channel::new(37);
+
+#[protection_domain]
+fn init() -> impl Handler {
+    debug_println!("server: initializing");
+
+    debug_println!("server: notifying client");
+
+    CLIENT.notify();
+
+    HandlerImpl
+}
+
+struct HandlerImpl;
+
+impl Handler for HandlerImpl {
+    type Error = Infallible;
+
+    fn protected(
+        &mut self,
+        channel: Channel,
+        msg_info: MessageInfo,
+    ) -> Result<MessageInfo, Self::Error> {
+        debug_println!("server: called by {:?}", channel);
+
+        todo!()
+    }
+}
+
+
+
+

The +Channel type is the Rust equivalent of the +microkit_channel +type alias in libmicrokit. +Note how the functionality corresponding to libmicrokit's microkit_notify, microkit_irq_ack, and microkit_ppcall is implemented in methods for Channel.

+

The +MessageInfo type is the Rust equivalent of the +microkit_msginfo +type alias in libmicrokit. +Just as microkit_msginfo is an alias for seL4_MessageInfo_t, sel4_microkit::MessageInfo is just a thin wrapper around MessageInfo.

+

libmicrokit has microkit_mr_set() and microkit_mr_get() for interacting with the IPC buffer. +In the sel4_microkit crate, we have +get_mr() +and +set_mr() +, +but we also have +with_msg_regs(), +with_msg_regs_mut(), +with_msg_bytes(), and +with_msg_bytes_mut(), +which use +sel4::with_ipc_buffer() and +sel4::with_ipc_buffer_mut() under the hood.

+

Step 10.A (exercise)       

+

Exercise: +In the client's notified() handler, make a protected procedure call to the server using SERVER.pp_call(). +Handle the call in the server's protected() handler. +Include data in the message using sel4_microkit::with_msg_regs{,_mut}.

+

Exercise (optional): +Send something more interesting over IPC using +msg_bytes +and +msg_bytes_mut +. +For example, the zerocopy crate can be used to view certain types as bytes and vice versa, and the lightweight postcard crate can be used to serialize and deserialize a wider range of types using serde.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/microkit/shared-memory.html b/projects/rust/tutorial/microkit/shared-memory.html new file mode 100644 index 00000000000..7977e0aa0c9 --- /dev/null +++ b/projects/rust/tutorial/microkit/shared-memory.html @@ -0,0 +1,375 @@ + + + + + + Shared Memory - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Shared Memory

+

This chapter covers interacting with shared memory from protection domains written in Rust. +Navigate to and run the example:

+
cd workspaces/microkit/shared-memory
+make simulate
+
+

The example system description specifies two protection domains which share two memory regions:

+
+
+
shared-memory.system:7:28
+
+
+
<system>
+    <memory_region name="region_a" size="0x1_000" />
+
+    <memory_region name="region_b" size="0x1_000" />
+
+    <protection_domain name="client" priority="100">
+        <program_image path="microkit-shared-memory-client.elf" />
+        <map mr="region_a" vaddr="0x2_000_000" perms="rw" cached="true" setvar_vaddr="region_a_vaddr" />
+        <map mr="region_b" vaddr="0x2_400_000" perms="rw" cached="true" setvar_vaddr="region_b_vaddr" />
+    </protection_domain>
+
+    <protection_domain name="server" priority="200">
+        <program_image path="microkit-shared-memory-server.elf" />
+        <map mr="region_a" vaddr="0x2_000_000" perms="r" cached="true" setvar_vaddr="region_a_vaddr" />
+        <map mr="region_b" vaddr="0x2_400_000" perms="r" cached="true" setvar_vaddr="region_b_vaddr" />
+    </protection_domain>
+
+    <channel>
+        <end pd="client" id="13" pp="true" />
+        <end pd="server" id="37" />
+    </channel>
+</system>
+
+
+
+
+

The Microkit tool will inject memory region virtual addresses into protection domain images according to the setvar_vaddr attribute values. +For example, the virtual address of the mapping of region_a into the client protection domain will be injected into the microkit-shared-memory-client.elf image at the location specified by then region_a_vaddr symbol.

+

In the case of Rust, declaring a symbol that the Microkit tool can patch requires a bit more intentionality than in the C case. +The sel4_microkit::var! macro is provided to declare such symbols.

+

The var! macro's implementation is just a few lines of code. +We want to express this symbol as a global variable that does not change at runtime, but which cannot be assumed to have the value we assign it at compile time, and which must not be optimized away. +The near-trivial +sel4_immutable_cell::ImmutableCell type encapsulates this pattern. +The #[no_mangle] attribute instructs the compiler to use the name of the variable as the name of the symbol. +This is the default in C, but not Rust. +We direct the compiler to put this symbol in the .data section with #[link_section = ".data"] to ensure that space is allocated for it in the ELF file itself, not just the program image it describes.

+

So far, the example protection domains just store pointers to the shared memory regions in their handler state:

+
+
+
pds/client/src/main.rs:17:31
+
+
+
fn init() -> impl Handler {
+    debug_println!("client: initializing");
+
+    let region_a = *var!(region_a_vaddr: usize = 0);
+    let region_b = *var!(region_b_vaddr: usize = 0);
+
+    debug_println!("client: region_a = {region_a:#x?}");
+    debug_println!("client: region_b = {region_b:#x?}");
+
+    let _ = SERVER.pp_call(MessageInfo::default());
+
+    debug_println!("TEST_PASS");
+
+    NullHandler::new()
+}
+
+
+
+
+
+
pds/server/src/main.rs:17:46
+
+
+
fn init() -> impl Handler {
+    debug_println!("server: initializing");
+
+    let region_a = *var!(region_a_vaddr: usize = 0);
+    let region_b = *var!(region_b_vaddr: usize = 0);
+
+    debug_println!("server: region_a = {region_a:#x?}");
+    debug_println!("server: region_b = {region_b:#x?}");
+
+    HandlerImpl { region_a, region_b }
+}
+
+struct HandlerImpl {
+    region_a: usize,
+    region_b: usize,
+}
+
+impl Handler for HandlerImpl {
+    type Error = Infallible;
+
+    fn protected(
+        &mut self,
+        channel: Channel,
+        _msg_info: MessageInfo,
+    ) -> Result<MessageInfo, Self::Error> {
+        assert_eq!(channel, CLIENT);
+
+        Ok(MessageInfo::default())
+    }
+}
+
+
+
+

Step 11.A       

+

Let's assign types to these shared memory regions. +We can define our types in a crate that both the client and server can use:

+
+
+
pds/common/src/lib.rs:9:18
+
+
+
use zerocopy::{FromBytes, IntoBytes};
+
+pub const REGION_A_SIZE: usize = 1337;
+
+#[repr(C)]
+#[derive(IntoBytes, FromBytes)]
+pub struct RegionB {
+    pub field_1: u64,
+    pub foo: [u16; 16],
+}
+
+
+
+

Suppose region_a: [u8; REGION_A_SIZE] and region_b: RegionB. +You could just turn the virtual addresses we get in our var! symbols into pointers and start interacting with the shared memory regions with unsafe ptr::* operations, but we can leverage the Rust type system to come up with a solution that only requires unsafe at initialization time.

+

Step 11.B       

+

The +sel4-shared-memory +crate provides a way for you to declare a memory region's type and bounds, along with the memory access operations that can safely be used on it, so that you can access it without unsafe code. +That initial declaration is, however, unsafe.

+

The +sel4-shared-memory +is a thin wrapper around the +sel4_abstract_ptr +crate, instantiating its abstract pointer types with memory access operations suitable for memory that is shared with another protection domain.

+

The +sel4_microkit::memory_region_symbol! +macro is like the sel4_microkit::var! macro, except specialized for shared memory region virtual address symbols. +For one, the underlying symbol is always of type usize and the macro returns a value of type NonNull<_>. +memory_region_symbol! has a few additional features. +For example, memory_region_symbol!(foo: *mut [u8] n = BAR) returns a NonNull<[u8]> with a runtime slice length of BAR.

+

See this step's diff for how to put this all together.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/print.html b/projects/rust/tutorial/print.html new file mode 100644 index 00000000000..6bd031d4499 --- /dev/null +++ b/projects/rust/tutorial/print.html @@ -0,0 +1,1514 @@ + + + + + + Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Tutorial: Using Rust in seL4 Userspace

+

seL4 has official support for Rust in userspace, funded by the seL4 Foundation:

+

https://github.com/seL4/rust-sel4

+

The exports of this project covered in this tutorial are:

+
    +
  • Rust bindings for the seL4 API
    • +
  • A runtime for root tasks
    • +
  • Rust bindings for the seL4 Microkit API
    • +
  • A runtime for seL4 Microkit protection domains
    • +
  • Custom rustc target specifications for seL4 userspace
    • +
+

Part I covers the Rust bindings for the seL4 API and the runtime for root tasks. +Familiarity with the seL4 API isn't necessarily assumed or required, but this text doesn't introduce its elements in as much detail as the seL4 Manual.

+

Part II is much shorter, and covers the Rust language runtime for seL4 Microkit protection domains and implementation of the Microkit API. +This part does assume that the reader is familiar with the basics of the Microkit framework and API, or is using a companion resource to learn about the Microkit in parallel.

+
+

Setup

+

This tutorial is presented as a linear series of patches to https://github.com/seL4/seL4-rust-tutorial-code, starting at commit 8ca0e1939dc1, and ending with commit 5253edc1ed12. +Each patch, or step, as we shall call them, is an instructive modification to a code example. +You are encouraged (but by no means required) to attempt those marked as exercises in this text on your own. +Note that while most step patches include tests, the reader is not expected to write tests for exercises themselves.

+

Clone the repository and checkout the starting commit:

+
git clone https://github.com/seL4/seL4-rust-tutorial-code
+cd seL4-rust-tutorial-code
+git checkout 8ca0e1939dc1
+
+

Observe the steps ahead:

+
git log 8ca0e1939dc1..5253edc1ed12
+
+

Each step header contains two icons. +Clicking the clipboard copies the commit hash corresponding to the step to the clipboard. +The GitHub icon is a link to the commit on GitHub.

+

Use any Git workflow that works for you. +For example, you could cherry-pick the steps that are not marked as exercises after examining and understanding them, and then attempt the exercises on your own, using those step commits as hints when necessary.

+

Docker

+

We will work inside of a Docker container built with docker/Dockerfile. +This Dockerfile installs some build-time dependencies, and then builds seL4, seL4 Microkit, and some additional programs and tools.

+

Build the image:

+
make -C docker build
+
+

Run a container in the background:

+
make -C docker run
+
+

Start a shell inside the container:

+
make -C docker exec
+
+

The rest of this text assumes that you are in a shell inside the container.

+

Two Workspaces

+

To simplify our Cargo invocations, this repository's Rust code has been divided between two distinct workspaces: workspaces/root-task and workspaces/microkit. +Both are subject to the top-level .cargo/config.toml, whereas workspaces/root-task/.cargo/config.toml and workspaces/microkit/.cargo/config.toml each apply to only one. +These workspace-specific config.toml files demonstrate all that is required to configure the crates in the rust-sel4 project:

+ +

VSCode + Dev Containers

+

If you want help from rust-analyzer, the Rust Language Server, you can use VSCode with the Dev Containers extension. +This will enable you to run VSCode inside of the container you just built, which contains the seL4 build artifacts that rust-analyzer will require to analyzer your code.

+

This repository provides a separate Dev Container configuration for each workspace:

+ +

To work in a particular workspace, open this repository in VSCode, run > Dev Containers: Reopen in Container, and select the corresponding configuration. +You should now be able to use the rust-analyzer VSCode extension normally for the code in the selected workspace.

+

Rustdoc

+

Rustdoc for the rust-sel4 project is hosted here:

+

https://sel4.github.io/rust-sel4/

+

However, for the sake of consistency, rustdoc for the particular configurations studied in this text are hosted here too. +There is one set of rustdoc for each of the two workspace configurations mentioned in Two Workspaces. +Rustdoc does not generate an index page, but you can navigate across crates within a workspace configuration using the sidebar present on top-level rustdoc page for any module.

+ +
+

The Root Task

+

After initializing itself, the seL4 kernel passes control to a userspace program called the root task, whose image is provided to the kernel at boot-time. +The root task's capability space contains capabilities for all memory and boot-time objects. +That is to say, the root task spawns with the maximum privilege that a userspace program can have. +The kernel provides the root task with a map of its initial capability space in the form of the BootInfo frame. +You can read more about the root task's environment in seL4 Reference Manual § 9.1.

+

Part I of this tutorial will focus on writing from-scratch root tasks in Rust. +Some of the code in Part I will be quite low-level, interacting with the language runtime, the linker, and some of the finer details related to bootstrapping an seL4-based system. +The only seL4-related crates we will be using are the language runtime and bindings for the seL4 API. +Unlike situations where higher-level seL4-related libraries (such as seL4_libs) are used, we will be allocating objects and manage virtual address spaces from scratch.

+

At boot time, the seL4 kernel and root task are loaded into memory by a kind of bootloader stub referred to as a seL4 kernel loader. +For Part I, we will use the kernel loader from the rust-sel4 project. +We won't cover how it works or how to use it explicitly in this text. +It is built at docker/Dockerfile:94:108, and used at mk/root-task.mk:31:36.

+
+

Hello, World!

+

Run the hello world example:

+
cd workspaces/root-task/hello-world
+make simulate
+
+

Press ctrl-a x to exit QEMU.

+

Here is its source:

+
+
+
hello-world/src/main.rs:7:17
+
+
+
#![no_std]
+#![no_main]
+
+use sel4_root_task::root_task;
+
+#[root_task]
+fn main(_bootinfo: &sel4::BootInfoPtr) -> ! {
+    sel4::debug_println!("Hello, World!");
+
+    sel4::init_thread::suspend_self()
+}
+
+
+
+

The Rust standard library is divided into three layers:

+
    +
  • core: dependency-free foundation
    • +
  • alloc: implements heap-backed data structures, but requires a runtime that provides a heap allocator
    • +
  • std includes core and alloc, and adds APIs that depend on OS services such as networking and filesystems
    • +
+

The high-level std doesn't support the low-level seL4 root task target. +#![no_std] declares that this crate does not depend on std, and prevents rustc from automatically importing it.

+

Our language runtime will handle the program's entrypoint differently than a typical Rust program. +#![no_main] informs rustc of this fact.

+

The sel4 crate binds the seL4 API. +It is generated from source (.xml, .bf, and .h) in libsel4. +We will cover the contents of this crate in future chapters.

+

The sel4_root_task crate implements a Rust language runtime for the root task environment.

+

The #[root_task] attribute macro declares a function to be the root task's entrypoint. +The entrypoint function must have a signature of the form:

+
fn(&sel4::BootInfoPtr) -> T
+where
+    T: sel4_root_task::Termination
+

(Rustdoc for BootInfoPtr and Termination)

+

The root task has no way to exit, so, to terminate cleanly, it must suspend its own thread. +sel4::init_thread::suspend_self() does exactly this.

+

Step 2.A (exercise)       

+

Exercise: Cause a panic.

+

Step 2.B (exercise)       

+

Exercise: Catch the panic using sel4_root_task::panicking::catch_unwind().

+

Step 2.C (exercise)       

+

You can set a custom panic hook with sel4_root_task::panicking::PanicHook. +The default hook just prints the panic's ExternalPanicInfo.

+

Exercise: Set a custom panic hook.

+

Step 2.D (exercise)       

+

Exercise: Cause a stack overflow.

+

Step 2.E (exercise)       

+

The #[root_task] attribute macro accepts a named stack_size parameter, which can be any expression of type usize and whose value is interpreted as the root task's initial thread's stack size, in bytes. +For example:

+
#[root_task(stack_size = 13 * 37)]
+

The default stack size is sel4_root_task::DEFAULT_STACK_SIZE.

+

Exercise: Adjust the root task's initial thread's stack size to prevent the stack overflow you just caused.

+

Step 2.F (exercise)       

+

By default, the sel4_root_task runtime does not include a heap. +Any attempt to use the alloc crate will result in a link-time failure.

+

The #[root_task] attribute macro accepts a heap_size parameter, which can be any expression of type usize and whose value is interpreted as the root task's heap size, in bytes. +Note that heap_size must come after stack_size in the case where both are present. +For example:

+
#[root_task(heap_size = 0xf00d)]
+

or

+
#[root_task(stack_size = 13 * 37, heap_size = 0xf00d)]
+

Exercise: Add a heap and use it.

+

Step 2.G       

+

The sel4_logging crate builds on top of the log crate to add utilities for initializing simple loggers in minimal environments, such as a seL4 root task. +This step demonstrates one way to initialize a logger using this crate:

+
+
+
hello-world/src/main.rs:17:20 after 2.G
+
+
+
static LOGGER: Logger = LoggerBuilder::const_default()
+    .level_filter(LevelFilter::Info)
+    .write(|s| sel4::debug_print!("{}", s))
+    .build();
+
+
+
+
+
+
hello-world/src/main.rs:41 after 2.G
+
+
+
    LOGGER.set().unwrap();
+
+
+
+
+

Allocating Kernel Objects

+

Start by navigating to and running this chapter's example, which, so far, is empty.

+
cd workspaces/root-task/kernel-objects
+make simulate
+
+

Userspace operates the seL4 kernel by creating, managing, and accessing kernel objects via references called capabilites. +See seL4 Reference Manual § 2.3 (Kernel Objects) for an outline of the core types of kernel objects.

+

In the context of seL4, a capability is a granular, unforgeable token of authority that references a kernel object and carries access rights that limit what the user of a cabability can do with the referenced kernel object. +In general, a system call in seL4 amounts to refering to a cabability and an action on the kernel object the cabability points to. +This is called invoking a capability.

+ +

Just as each thread is associated with a virtual address space which the hardware uses to translate virtual memory addresses into locations in physical memory, each seL4 thread is also assocated with a capability space (CSpace) which the kernel uses to translate so-called capability pointers (CPointers or CPtrs) into locations (slots) in the kernel's capability tables called CNodes.

+

The sel4::CPtr type is a wrapper around a machine word. +The sel4::Cap<T> type wraps a CPtr associated with the current thread's CSpace, and thus points to a particular capability slot within the kernel. +It is paramterized by a capability type T: sel4::CapType, representing the type of capability in that slot. +It is up to the crate user to ensure that Cap's are valid and well-typed in the current thread.

+

The sel4::cap module contains aliases of the form sel4::Cap<sel4::cap_type::*>.

+

Depending on the Cap's type T, a Cap has a number of methods available, which correspond to invocations for that capability type. +For example, sel4::Cap::tcb_resume() is available when T is sel4::cap_type::Tcb.

+

Step 3.A       

+

As elaborated in seL4 Reference Manual § 2.4 (Kernel Memory Allocation), userspace is responsible for managing the memory associated with kernel objects. +Untyped memory is the name of the object type for free memory. +At boot time, the root task is granted untyped memory capabilities for all of the system's memory, except for the memory used for the kernel and the root task's own resources.

+

Print the untyped memory described by the BootInfo frame:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:14:22 after 3.A
+
+
+
    sel4::debug_println!("untyped:");
+    for ut_desc in bootinfo.untyped_list() {
+        sel4::debug_println!(
+            "    paddr: {:#016x?}, size bits: {:02?}, is device: {:?}",
+            ut_desc.paddr(),
+            ut_desc.size_bits(),
+            ut_desc.is_device()
+        );
+    }
+
+
+
+

Sample output:

+
untyped:
+    paddr: 0x00000000000000, size bits: 27, is device: true
+    paddr: 0x00000008001000, size bits: 12, is device: true
+    paddr: 0x00000008002000, size bits: 13, is device: true
+    paddr: 0x00000008004000, size bits: 14, is device: true
+    paddr: 0x00000008008000, size bits: 15, is device: true
+    paddr: 0x00000008011000, size bits: 12, is device: true
+    paddr: 0x00000008012000, size bits: 13, is device: true
+    ...
+
+

sel4::UntypedDesc::size_bits() returns the log base 2 of the size of the region of memory described by the descriptor.

+

sel4::UntypedDesc::is_device() returns whether the region is device memory or kernel memory. +Device memory can only be used for creating frames, whereas kernel memory has no such restrictions.

+

Step 3.B       

+

Add a function that finds the largest untyped region passed to the root task:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:32:42 after 3.B
+
+
+
fn find_largest_kernel_untyped(bootinfo: &sel4::BootInfo) -> sel4::cap::Untyped {
+    let (ut_ix, _desc) = bootinfo
+        .untyped_list()
+        .iter()
+        .enumerate()
+        .filter(|(_i, desc)| !desc.is_device())
+        .max_by_key(|(_i, desc)| desc.size_bits())
+        .unwrap();
+
+    bootinfo.untyped().index(ut_ix).cap()
+}
+
+
+
+

The expression bootinfo.untyped().index(ut_ix).cap() indexes into bootinfo.untyped(): SlotRegion<Untyped> to retrieve a Slot<Untyped>, which can be turned into a Cap<Untyped> (= cap::Untyped).

+

Step 3.C       

+

In this step, we will allocate a Notification object.

+

We already know how to refer to a capability in the current thread's CSpace: a CPtr. +However, some capability invocations allow us to refer to a capability slot in any CSpace whose root CNode is present in the current thread's CSpace. +In these cases, we must provide:

+
    +
  • A CPtr, interpreted in the context of the current thread's CSpace, which points to the target CSpace's root CNode
    • +
  • A CPtr, interpreted in the context of the target CSpace, which points to the target capability slot
    • +
  • A depth, which is the number of bits of the second CPtr to interpret. This allows for the second CPtr to point to a CNode. Why this is necessary is outside the scope of this tutorial, but you can read about it in seL4 Reference Manual § 2.4 (CSpace Addressing).
    • +
+

Consider, for example, the seL4_CNode_Mint capability invocation. +dest_* and src_* are both capability slots addressed in this way.

+

This more flexible method of capability slot addressing is encapsulated in the sel4::AbsoluteCPtr type.

+

The seL4_Untyped_Retype method is used for allocating new objects from an untyped object. +The _service parameter is the address of the untyped object as a normal CPtr. +root, node_index, and node_depth address, in the more flexible way outlined above, the destination CNode into which capabilities for the new objects will be inserted. +node_offset and num_objects specify a range of slots within the selected CNode for the new capabilites (and, simultaneously, the number of new objects that will be created).

+

type and size_bits specify the shape of the new object(s) +Note that size_bits is relevant for only certain object types (see seL4 Reference Manual § 2.4.2 (Summary of Object Sizes) for more information). +This shape information is encapsulated in the sel4::ObjectBlueprint type.

+

Multiple kernel objects can be allocated from a single unytped object. +For each untyped object, the kernel maintains a watermark which tracks how much of the untyped object has been used up for object allocation. +seL4_Untyped_Retype aligns the watermark to the desired object type's size, and then advances it according to the object type size and number of objects. +This process is detailed in the fourth paragraph of seL4 Reference Manual § 2.4.1 (Reusing Memory).

+

Let us now work towards calling sel4::cap::Untyped::untyped_retype() on our previously acquired largest_kernel_ut. +We wish to allocate one notification object and insert a capability for it into a free slot in the current thread's own CSpace. +More precisely, we need a sel4::AbsoluteCPtr for the current thread's own CSpace's root CNode, and an index into that CNode for a free slot.

+

The CPtr for the initial thread's own CSpace root is a constant:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:27:27 after 3.C
+
+
+
    let cnode = sel4::init_thread::slot::CNODE.cap();
+
+
+
+

bootinfo can tell us about a range of empty slots in this CSpace. +We can leverage the fact that Rust's Range<T> type is an iterator for certain T to allocate slots in an ergonomic way:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:29:33 after 3.C
+
+
+
    let mut empty_slots = bootinfo
+        .empty()
+        .range()
+        .map(sel4::init_thread::Slot::from_index);
+    let notification_slot = empty_slots.next().unwrap();
+
+
+
+

The {{#rustdoc_link root-task sel4/cap/type.CNode.html#method.absolute_cptr_for_selfsel4::cap::CNode::absolute_cptr_for_self()}} method elaborates a sel4::cap::Cnode into a sel4::AbsoluteCPtr. +Interestingly, there are two ways to do this, but the current implementation is just to use a depth of zero.

+

Now we can invoke our untyped capability to allocate a notification object:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:36:43 after 3.C
+
+
+
    largest_kernel_ut
+        .untyped_retype(
+            &sel4::ObjectBlueprint::Notification,
+            &cnode.absolute_cptr_for_self(),
+            notification_slot.index(),
+            1,
+        )
+        .unwrap();
+
+
+
+

Now that we know that notification_slot contains a notification capability, we can cast it and get a sel4::cap::Notification:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:45:47 after 3.C
+
+
+
    let notification = notification_slot
+        .downcast::<sel4::cap_type::Notification>()
+        .cap();
+
+
+
+

Step 3.D (exercise)       

+

Exercise:: Use sel4::cap::Notification::signal() and sel4::cap::Notification::wait() to signal and then wait on the notification.

+

Step 3.E (exercise)       

+

As described in seL4 Reference Manual § 5 (Notifications), a notification capability can contain a word-sized mask called a badge. +When that capability is used to signal the notification, the notification's word-sized state is bit-wise ored with the capability's badge. +A wait call on the notification returns and clears the notification's state, provided that a signal call has occurred since the last wait call.

+

sel4::AbsoluteCPtr::mint() mints a new capability from an existing capability, updatings its access rights and badge.

+

Exercise:: Allocate a new empty slot in the current CNode.

+

A slot in the root task's CSpace (i.e. a value of type sel4::init_thread::Slot) can be turned into an sel4::AbsoluteCPtr using {{#rustdoc_link root-task sel4/cap/type.CNode.html#method.absolute_cptrsel4::CNode::absolute_cptr()}}:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:63:63 after 3.E
+
+
+
            &cnode.absolute_cptr(notification_slot.cptr()),
+
+
+
+

Exercise:: Mint a capability based on the capability in notification_slot into your newly allocated slot. Use sel4::CapRights::all() for the rights parameter, and specify a non-zero badge value.

+

Exercise:: Signal the notification using your newly minted badged capability. Using the return value of sel4::Notification::wait(), compare the badge value it returns with the badge you used to mint the capability.

+

Step 3.F (exercise)       

+

Exercise:: sel4::CapRights::all() is overly-permissive. Use the overly-restrictive sel4::CapRights::none() instead and watch the program fail.

+

Step 3.G (exercise)       

+

Exercise:: Now use the minimum rights necessary for the program to run.

+
+

Modifying the Address Space

+

This chapter will focus on using the seL4 virtual address space (VSpace) APIs to manipulate the root task's own address space. +Start by navigating to and running this chapter's example, which, so far, is empty.

+
cd workspaces/root-task/address-space
+make simulate
+
+

In seL4, each thread is associated with a virtual address space (VSpace). +A VSpace is comprised of a tree of translation tables mapping virtual addresses into physical frames of memory. +VSpaces are represented by their root translation structures. +While the high-level virtual address space API concepts are architecture-independent, the specific kernel object types for a given architecture mirror that architecture's paging structures. +That said, all architectures share two object types:

+ +

The root task is provided with capabilites for the objects comprising its own virtual address space. +The locations of these capabilities in the root task's CSpace is provided in the BootInfo struct. +Our goal for this chapter will be to create a frame object and experiment with mapping it into the root task's own address space.

+

Step 4.A (exercise)       

+

Exercise: Using code snippets from Chapter 3 (Allocating Kernel Objects), create a frame object. We seek a value frame: sel4::cap::Granule (which can also be written as frame: sel4::Cap<sel4::cap_type::Granule>).

+

Note that, after importing the sel4::CapTypeForObjectOfFixedSize trait, you can express the appropriate sel4::ObjectBlueprint as sel4::cap_type::Granule::object_blueprint().

+

Step 4.B       

+

In order to avoid interacting with intermediate translation structures, let's reserve an aligned granule-sized region in the root task's program image that we can use for our experiment:

+
+
+
workspaces/root-task/address-space/src/main.rs:15:20 after 4.B
+
+
+
const GRANULE_SIZE: usize = sel4::FrameObjectType::GRANULE.bytes(); // 4096
+
+#[repr(C, align(4096))]
+struct PagePlaceholder(#[allow(dead_code)] [u8; GRANULE_SIZE]);
+
+static mut PAGE_A: PagePlaceholder = PagePlaceholder([0xee; GRANULE_SIZE]);
+
+
+
+
+
+
workspaces/root-task/address-space/src/main.rs:46:49 after 4.B
+
+
+
    let page_a_addr = ptr::addr_of!(PAGE_A).cast::<u8>();
+    sel4::debug_println!("PAGE_A: {page_a_addr:#x?}");
+    assert_eq!(page_a_addr as usize % GRANULE_SIZE, 0);
+    assert_eq!(unsafe { page_a_addr.read() }, 0xee);
+
+
+
+

This reservation covers exactly one page in the root task's virtual address space.

+

Step 4.C       

+

Let's unmap the page in the root task image that initially backs our reserved region. This will give us a hole in the root task VSpace, which we can use for our experiment.

+

This function determines the slot in the root task's CSpace of the page capability corresponding to the page in the root task's VSpace which contains the given address:

+
+
+
workspaces/root-task/address-space/src/main.rs:73:84 after 4.C
+
+
+
fn get_user_image_frame_slot(
+    bootinfo: &sel4::BootInfo,
+    addr: usize,
+) -> sel4::init_thread::Slot<sel4::cap_type::Granule> {
+    extern "C" {
+        static __executable_start: usize;
+    }
+    let user_image_addr = ptr::addr_of!(__executable_start) as usize;
+    bootinfo
+        .user_image_frames()
+        .index(addr / GRANULE_SIZE - user_image_addr / GRANULE_SIZE)
+}
+
+
+
+

__executable_start is defined by the linker. +We can use it, along with addr, to identify the offset into bootinfo.user_image_frames() of the capability we are after.

+

Use the get_user_image_frame_slot() function to find the capability corresponding to the frame backing our reserved region, and unmap that frame, leaving a hole in the root task's virtual address space. +Try to access that region, and observe a page fault:

+
+
+
workspaces/root-task/address-space/src/main.rs:51:54 after 4.C
+
+
+
    let page_a_slot = get_user_image_frame_slot(bootinfo, page_a_addr as usize);
+    page_a_slot.cap().frame_unmap().unwrap();
+
+    unsafe { page_a_addr.read() };
+
+
+
+

Step 4.D (exercise)       

+

Exercise: Map new_frame at page_a_addr using new_frame.frame_map(), which corresponds to seL4_ARM_Page_Map.

+

Here are some hints for the parameters of .frame_map():

+
    +
  • vspace: A capability for the root task's VSpace can be expressed using sel4::init_thread::slot::VSPACE.cap().
    • +
  • rights: sel4::CapRights::read_write() are the most permissive rights, and will work for our purposes.
    • +
  • attrs: sel4::VmAttributes::default() will work here.
    • +
+
+

Using a Serial Device

+

In this chapter, we will build a root task that interacts with a serial device. +Start by navigating to and running this chapter's example, which, so far, doesn't do anything interesting.

+
cd workspaces/root-task/serial-device
+make simulate
+
+

The module at device.rs implements a higher-level interface over the serial device's MMIO registers, whose physical base address is:

+
+
+
workspaces/root-task/serial-device/src/main.rs:16:16
+
+
+
const SERIAL_DEVICE_MMIO_PADDR: usize = 0x0900_0000;
+
+
+
+

Our first goal will be to map the serial device's MMIO registers into the root task's address space.

+

After that, we will set up the root task's access to the serial device's interrupt, whose value is:

+
+
+
workspaces/root-task/serial-device/src/main.rs:18:18
+
+
+
const SERIAL_DEVICE_IRQ: usize = 33;
+
+
+
+

Finally, we will implement a simple loop that echoes serial input to serial output.

+

Step 5.A       

+

First, add some familiar snippets that we will use for allocating CSlots and kernel objects:

+
+
+
workspaces/root-task/serial-device/src/main.rs:34:44 after 5.A
+
+
+
fn find_largest_kernel_untyped(bootinfo: &sel4::BootInfo) -> sel4::cap::Untyped {
+    let (ut_ix, _desc) = bootinfo
+        .untyped_list()
+        .iter()
+        .enumerate()
+        .filter(|(_i, desc)| !desc.is_device())
+        .max_by_key(|(_i, desc)| desc.size_bits())
+        .unwrap();
+
+    bootinfo.untyped().index(ut_ix).cap()
+}
+
+
+
+
+
+
workspaces/root-task/serial-device/src/main.rs:22:27 after 5.A
+
+
+
    let mut empty_slots = bootinfo
+        .empty()
+        .range()
+        .map(sel4::init_thread::Slot::<sel4::cap_type::Unspecified>::from_index);
+
+    let largest_kernel_ut = find_largest_kernel_untyped(bootinfo);
+
+
+
+

Step 5.B (exercise)       

+

largest_kernel_ut will be useful for allocating kernel objects whose backing physical addresses don't matter to us, but we must allocate the frame which contains the serial device's MMIO registers at a particular physicall address (SERIAL_DEVICE_MMIO_PADDR). +Furthermore, the seL4 API distinguishes between general purpose untyped and device untyped. General purpose untyped is backed by normal memory, and can be used to create any type of object. Device untyped is not backed by normal memory, and can only be used to create frames. +See the last two paragraphs of seL4 Reference Manual § 2.4 (Kernel Memory Allocation) for more information. +So, we must allocate the serial device MMIO frame from the particular initial device untyped that contains SERIAL_DEVICE_MMIO_PADDR.

+

Exercice: Identify this initial untyped in the bootinfo. We will need a corresponding sel4::cap::Untyped along with the untyped's physical address (or sel4::UntypedDesc, which contains the physical address) for the next step.

+

Step 5.C       

+

The untyped we've identified contains the frame we are targeting, but that frame may be somewhere in the middle of the region of device memory the untyped covers. +To allocate the frame at SERIAL_DEVICE_MMIO_PADDR, we must allocate dummy objects from this untyped until its watermark is at SERIAL_DEVICE_MMIO_PADDR.

+

This trim_untyped function takes the untyped capability, its physical address, the desired physical address, and two empty slots for temporarily holding dummy objects. +We need two slots because the kernel resets an untyped's watermark if it has no live children. +So, we must always keep one child around so that our progress on advancing the watermark is never lost.

+
+
+
workspaces/root-task/serial-device/src/main.rs:43:49 after 5.C
+
+
+
    trim_untyped(
+        device_ut_cap,
+        device_ut_desc.paddr(),
+        SERIAL_DEVICE_MMIO_PADDR,
+        empty_slots.next().unwrap(),
+        empty_slots.next().unwrap(),
+    );
+
+
+
+
+
+
workspaces/root-task/serial-device/src/main.rs:68:97 after 5.C
+
+
+
fn trim_untyped(
+    ut: sel4::cap::Untyped,
+    ut_paddr: usize,
+    target_paddr: usize,
+    free_slot_a: sel4::init_thread::Slot,
+    free_slot_b: sel4::init_thread::Slot,
+) {
+    let rel_a = sel4::init_thread::slot::CNODE
+        .cap()
+        .absolute_cptr(free_slot_a.cptr());
+    let rel_b = sel4::init_thread::slot::CNODE
+        .cap()
+        .absolute_cptr(free_slot_b.cptr());
+    let mut cur_paddr = ut_paddr;
+    while cur_paddr != target_paddr {
+        let size_bits = (target_paddr - cur_paddr).ilog2().try_into().unwrap();
+        ut.untyped_retype(
+            &sel4::ObjectBlueprint::Untyped { size_bits },
+            &sel4::init_thread::slot::CNODE
+                .cap()
+                .absolute_cptr_for_self(),
+            free_slot_b.index(),
+            1,
+        )
+        .unwrap();
+        rel_a.delete().unwrap();
+        rel_a.move_(&rel_b).unwrap();
+        cur_paddr += 1 << size_bits;
+    }
+}
+
+
+
+

Step 5.D       

+

device_ut_cap is now primed; the physical address of the next allocation will be SERIAL_DEVICE_MMIO_PADDR.

+

Exercise: Allocate a small frame object (sel4::cap_type::Granule) from device_ut_cap.

+

If your sel4::cap::Granule is called serial_device_frame_cap, then the following assertion should succeed:

+
+
+
workspaces/root-task/serial-device/src/main.rs:70:73 after 5.D
+
+
+
    assert_eq!(
+        serial_device_frame_cap.frame_get_address().unwrap(),
+        SERIAL_DEVICE_MMIO_PADDR
+    );
+
+
+
+

Step 5.E (exercise)       

+

Exercise: Using code from Step 4.B, Step 4.C, and Step 4.D, map serial_device_frame_cap into the root task's virtual address space.

+

You should now be able interact with the serial device's MMIO registers. +Try printing "Hello, World!" to the serial console with something like:

+
+
+
workspaces/root-task/serial-device/src/main.rs:102:108 after 5.E
+
+
+
    let serial_device = unsafe { Device::new(serial_device_mmio_page_addr.cast()) };
+
+    serial_device.init();
+
+    for c in b"Hello, World!\n" {
+        serial_device.put_char(*c);
+    }
+
+
+
+

where serial_device_mmio_page_addr: *mut _ is a pointer to where the MMIO registers are mapped in the root task's virtual address space.

+

Step 5.F (exercise)       

+

Interrupts are delivered to userspace via notifications. +A IRQHandler capability represents the authority to manage a particular interrupt. +Specifically, an IRQHandler capability (sel4::cap::IrqHandler) has the following methods:

+
    +
  • seL4_IRQHandler_SetNotification(): +Associate the interrupt with the given notification. Userspace can call seL4_Wait() or seL4_Poll() on this notification to receive the interrupt.
    • +
  • seL4_IRQHandler_Clear(): +Disassociate the notification associated with this interrupts.
    • +
  • seL4_IRQHandler_Ack(): +Tell the kernel to pass on acknowledgement of this interrupt to the interrupt controller.
    • +
+

The Rust bindings for these methods are:

+ +

The root task spawns with a special IRQControl capability (sel4::cap::IrqControl) which can be used to create IRQHandler capabilities with seL4_IRQControl_Get() (sel4::cap::IrqControl::irq_control_get()).

+

The intent behind this API is that a highly-privileged component will hold an IRQControl capability, which it will use to distribute more finely-grained IRQHandler capabilities to less privileged components for the interrupts they will manage.

+

The root task can access its IRQControl capability with sel4::init_thread::slot::IRQ_CONTROL.cap()

+

Exercise: Use sel4::init_thread::slot::IRQ_CONTROL.cap() to create a sel4::cap::IrqHandler for SERIAL_DEVICE_IRQ.

+

Step 5.G (exercise)       

+

Exercise: Create a notification object from largest_kernel_ut and associate it with the IRQHandler you just created using sel4::cap::IrqHandler::irq_handler_set_notification().

+

Step 5.H (exercise)       

+

Exercise: Use serial_device: Device, your IRQHandler, and the notification you associated with the interrupt to write a loop that echoes serial input to serial output.

+

Use serial_device.clear_all_interrupts() and irq_handler_cap.irq_handler_ack() in sequence to clear the interrupt at the device and interrupt controller levels respectively. +Note that you should do this at the beginning of the loop in case your loop enters with an interrupt already pending.

+

Use irq_notification_cap.wait() to wait for hte interrupt.

+

Use serial_device.get_char() and serial_device.put_char() to read and write data.

+
+

Spawning a Thread

+

In this chapter, we will explore IPC through an example that spawns a secondary thread. +This example starts with a more interesting program than the other examples we've worked with so far. +It spawns a secondary thread, and then interacts with it using a notification.

+

Navigate to and run the example:

+
cd workspaces/root-task/spawn-thread
+make simulate
+
+

Explore main.rs at will. +If you're used to using seL4_libs, you may notice that our Rust code here is much more low-level and verbose. +That is because we aren't using any higher-level seL4-related libraries such as +<sel4utils/thread.h>. +Our code is more like spawning a thread using <sel4/sel4.h> alone. +Note, though, that our code does depend on a few Rust language runtime building block crates such as +sel4-initialize-tls +and +sel4-stack +.

+

The exercises in this chapter are only concerned with the following two functions, which run concurrently:

+
+
+
workspaces/root-task/spawn-thread/src/main.rs:75:79
+
+
+
fn secondary_thread_main(inter_thread_nfn: sel4::cap::Notification) {
+    sel4::debug_println!("In secondary thread");
+
+    inter_thread_nfn.signal();
+}
+
+
+
+
+
+
workspaces/root-task/spawn-thread/src/main.rs:81:85
+
+
+
fn interact_with_secondary_thread(inter_thread_nfn: sel4::cap::Notification) {
+    sel4::debug_println!("In primary thread");
+
+    inter_thread_nfn.wait();
+}
+
+
+
+

secondary_thread_main() runs in the secondary thread, and interact_with_secondary_thread() runs in the secondary thread.

+

Step 6.A       

+

In this step, we introduce IPC between secondary_thread_main() and interact_with_secondary_thread by changing

+
inter_thread_nfn: sel4::cap::Notification
+
+

to

+
inter_thread_ep: sel4::cap::Endpoint
+
+

Before, the two sides of the notification communicated via +inter_thread_nfn.signal() +and +inter_thread_nfn.wait().

+

Now, communication over this IPC endpoint will happen by +inter_thread_ep.send() and +inter_thread_ep.recv() +.

+ +

As described in seL4 Reference Manual § 4 (Message Passing (IPC)) and seL4 Reference Manual § 4.2 (Endpoints), a capability for an Endpoint object can be invoked with send() and recv(). +send() and recv() block until the two sides of the object rendezvous, at which point a message is passed from the sender to the receiver. +This message may contain data and capabilities.

+

Each thread is associated with a special page of memory called an IPC buffer. +The sender populates its own IPC buffer with data and/or CPtrs, and then calls send() with a metadata value called the MessageInfo. +The kernel copies data from the sender's IPC buffer into that of the receiver, and/or capabilities from the sender's CSpace into that of the receiver. +The kernel uses the MessageInfo to determine how much data to copy between the two IPC buffers +(the length field) +and how many CPtrs to read from the IPC buffers for copying betwen CSpaces +(the +caps_unwrapped +and +extra_caps +fields). +Finally, the kernel passes the MessageInfo, and control, to the receiver.

+

In Rust, the sender and receiver can interact with their own IPC buffer using +sel4::with_ipc_buffer +and +sel4::with_ipc_buffer_mut. +Message data is held in the message registers (an array of machine words), which is a field of the IPC buffer ( +msg_regs +and +msg_regs_mut +). +The length field of the MessageInfo specifies how many message registers will be copied into the receiver's IPC buffer.

+

One can also view the message registers as an array of bytes using +msg_bytes +and +msg_bytes_mut. +In this case, one rounds the length of their message up to the nearest multiple of the machine word size when computing the message length for the MessageInfo.

+

The MessageInfo also includes a few bits of data called a label (label_width bits wide) that is not interpreted by the kernel.

+

In Rust, the MessageInfoBuilder type is a clear and concise way to construct a MessageInfo.

+

In Rust, to smooth out differences between the mixed-criticality and legacy kernel schedulers, recv() always takes a reply_authority argument. +Under legacy scheduler configurations, which is what this text uses, this argument can be of type ().

+

Taking all of this together, let's use our IPC endpoint to send an empty message:

+
+
+
workspaces/root-task/spawn-thread/src/main.rs:75:79 after 6.A
+
+
+
fn secondary_thread_main(inter_thread_ep: sel4::cap::Endpoint) {
+    sel4::debug_println!("In secondary thread");
+
+    inter_thread_ep.send(sel4::MessageInfoBuilder::default().label(123).build());
+}
+
+
+
+
+
+
workspaces/root-task/spawn-thread/src/main.rs:81:87 after 6.A
+
+
+
fn interact_with_secondary_thread(inter_thread_ep: sel4::cap::Endpoint) {
+    sel4::debug_println!("In primary thread");
+
+    let (msg_info, _badge) = inter_thread_ep.recv(());
+
+    assert_eq!(msg_info.label(), 123);
+}
+
+
+
+

Step 6.B (exercise)       

+

Exercise: use +sel4::with_ipc_buffer +and +sel4::with_ipc_buffer_mut +to send a message with some data.

+

Step 6.C (exercise)       

+

See seL4 Reference Manual § 4.2.4 (Calling and Replying) for a description of the seL4_Call syscall (Endpoint::call() in Rust).

+

Exercise: Change the

+
inter_thread_ep.send()
+
+

in secondary_thread_main() to

+
inter_thread_ep.call()
+
+

and modify interact_with_secondary_thread() to sel4::reply with a message.

+
+

Spawning a Task (Challenge)

+

This final chapter of Part I contains a more open-ended and challenging exercise. +We start with an example that spawns an entire new process, which, in the context of low-level seL4 userspace, is often called a task:

+
cd workspaces/root-task/spawn-task
+make simulate
+
+

Similarly to what we saw in Chapter 6 (Spawning a Thread), the code in this example is more low-level and complex compared to what you have seen in code that leverages <sel4utils/process.h>. +Again, our code here is more like spawning a task using <sel4/sel4.h> alone.

+

This example consists of two programs. +The spawn-task crate is the root task, and the spawn-task-child crate is the child task.

+

The child task does not spawn in any standard sort of environment, so is includes its own ad-hoc Rust language runtime in child/src/runtime.rs, complete with thread-local storage, a global heap allocator, and exception handling. +This runtime is built using a few Rust langauge runtime building block crates:

+ +

This minimal, ad-hoc language runtime is a neat, instructive piece of code. +It shows how one can build a new Rust language runtime out of the building blocks provided by the rust-sel4 project.

+

Explore the root task and child task.

+

Right now, all the child task does is send a test message over an endpoint back to the root task. +The challenge in this chapter, step 7.E, is to extend the root task so that it sets up the child task to be able to interact with the serial device, and to extend the child task to implement the same echo loop as in [./serial-device.html#step-5h]. +Steps 7.A, 7.B, 7.C, and 7.D, which are not exercises, make some incremental extensions towards those goals to help you get started.

+

Step 7.A       

+

This step extends the ObjectAllocator type in workspaces/root-task/spawn-task/src/object_allocator.rs after 7.B with the recklessly_allocate_at() method. +This method allocates an object according to the blueprint parameter at the given physical address paddr. +Instead of just allocating the object from the largest kernel untyped like the allocate() method does, this method searches through the bootinfo to find the initial untyped capability whose corresponding untyped object contains paddr, allocates dummy objects from this untyped object until its watermark reaches paddr, and then allocates the desired object. +recklessly_allocate_at()'s procedure is similar to that which we followed in step 5.C.

+

This implementation is "reckless" because it modifies the state of the untyped capability it allocates from (allocating from it and changing its watermark) without keeping track of having done so. +So, subsequent calls for paddrs contained in the same initial untyped would fail or, worse, misbehave. +However, we expect to only need to call it once, so we are okay with this caveat.

+

In step 7.E, you be able to use this method to allocate the serial device MMIO register frame.

+

Step 7.B       

+

This step extends the create_child_vspace() function in workspaces/root-task/spawn-task/src/child_vspace.rs after 7.A to take an extra_frames parameter. +create_child_vspace() now maps these extra frames into the child task's address space, after the end of the program image, and after the IPC buffer frame.

+

In step 7.E, you be able to use this parameter to pass in the serial device MMIO register frame to mapped into the child task's address space.

+

Step 7.C       

+

This step simply copies the Device type from chapter 5 into the child task.

+

In step 7.E, you be able to use this type to interact with the serial device's MMIO registers, just like we as part of step 5.E.

+

Step 7.D       

+

This step just adds the SERIAL_DEVICE_MMIO_PADDR and SERIAL_DEVICE_IRQ constants from chapter 5 to the root task.

+

Step 7.E (challenge)       

+

Exercise: +Extend the root task so that it sets up the child task to be able to interact with the serial device, and extend the child task to implement the same echo loop as in [./serial-device.html#step-5h-exercise].

+
+
+ + Hint for the root task (click to expand) + +

Try following this sequence of sub-steps: +- Allocate serial_device_frame_cap: sel4::cap::Granule using object_allocator.recklessly_allocate_at(). +- Map serial_device_frame_cap into the child task's address space using create_child_vspace()'s extra_frames parameter. +- Similarly to how we did so in steps 5.F and 5.G, obtain irq_handler_cap: sel4::cap::IrqHandler for SERIAL_DEVICE_IRQ (object_allocator.allocate_slot() might come in handy), allocate irq_nfn_cap: sel4::cap::Notification, and associate irq_nfn_cap with SERIAL_DEVICE_IRQ using irq_handler_cap. +- Copy irq_handler_cap and irq_nfn_cap into the child task's CSpace in a similar way to how child_tcb and inter_task_ep are copied.

+
+
+

+
+
+ + Hint for the child task (click to expand) + +

Try following this sequence of sub-steps: +- Declare constants IRQ_HANDLER: sel4::cap::IrqHandler and IRQ_NFN: sel4::cap::Notification after OWN_TCB and INTRA_TASK_EP. +- Obtain the virtual address of the serial device MMIO frame with addr_of_page_beyond_image(1) (recall how create_child_vspace()'s extra_frames parameter works). +- Initialize the serial device with Device::new() and Device::init() (as we did for part of step 5.E), and use the serial device just like we did in step 5.H.

+
+
+
+

seL4 Microkit

+

The seL4 Microkit is a framework for creating static systems based on seL4. +This part of the text assumes that the reader is familiar with the basics of the Microkit framework and API, or is using a companion resource to learn about the Microkit in parallel. +Here are three such resources:

+ +

This part also assumes that the reader has worked through chapters 2 and 6 of Part I.

+
+

Hello, World!

+

Navigate to and run the hello world Microkit example:

+
cd workspaces/microkit/hello-world
+make simulate
+
+

Here is its source:

+
+
+
hello-world/pds/hello/src/main.rs:7:22
+
+
+
#![no_std]
+#![no_main]
+
+use sel4_microkit::{debug_println, protection_domain, Handler, Infallible};
+
+#[protection_domain]
+fn init() -> impl Handler {
+    debug_println!("Hello, World!");
+    HandlerImpl
+}
+
+struct HandlerImpl;
+
+impl Handler for HandlerImpl {
+    type Error = Infallible;
+}
+
+
+
+

The sel4_microkit crate implements a Rust language runtime for Microkit protection domains, and implements the Microkit API. +It is written in pure Rust, and does not link against libmicrokit.

+

The Event Handler

+

The #[protection_domain] attribute macro declares a function to be the protection domain's initialization function. +The entrypoint function must have a signature of the form:

+
fn() -> T
+where
+    T: sel4_microkit::Handler
+

An implementation of the Handler trait is used by the runtime as the event handler for the protection domain's main loop. +The +notified, +protected, +and +fault +methods correspond to their equivalents in <microkit.h>.

+

The default implementations of these methods just panic. +Our event handler, which we've called HandlerImpl, is the simplest possible Handler implementation.

+

Language Runtime

+

As detailed in its rustdoc, the #[protection_domain] attribute macro takes the same parameters as #[root_task]. +Furthermore, the sel4_microkit crate supports all of the same Rust language runtime elements that we explored in Chapter 2, including +sel4_microkit::panicking::catch_unwind() +and +sel4_microkit::panicking::set_hook() +.

+
+

IPC

+

This chapter covers making and handling protected procedure calls in protection domains written in Rust. +Navigate to and run the example:

+
cd workspaces/microkit/ipc
+make simulate
+
+

The example system description specifies two protection domains, with a channel between them:

+
+
+
ipc.system:7:20
+
+
+
<system>
+    <protection_domain name="client" priority="100">
+        <program_image path="microkit-ipc-client.elf" />
+    </protection_domain>
+
+    <protection_domain name="server" priority="200">
+        <program_image path="microkit-ipc-server.elf" />
+    </protection_domain>
+
+    <channel>
+        <end pd="client" id="13" pp="true" />
+        <end pd="server" id="37" />
+    </channel>
+</system>
+
+
+
+
+
+
+
pds/client/src/main.rs:14:36
+
+
+
const SERVER: Channel = Channel::new(13);
+
+#[protection_domain]
+fn init() -> impl Handler {
+    debug_println!("client: initializing");
+    HandlerImpl
+}
+
+struct HandlerImpl;
+
+impl Handler for HandlerImpl {
+    type Error = Infallible;
+
+    fn notified(&mut self, channels: ChannelSet) -> Result<(), Self::Error> {
+        debug_println!("client: notified by {}", channels.display());
+
+        if channels.contains(SERVER) {
+            debug_println!("client: TEST_PASS");
+        }
+
+        Ok(())
+    }
+}
+
+
+
+
+
+
pds/server/src/main.rs:12:39
+
+
+
const CLIENT: Channel = Channel::new(37);
+
+#[protection_domain]
+fn init() -> impl Handler {
+    debug_println!("server: initializing");
+
+    debug_println!("server: notifying client");
+
+    CLIENT.notify();
+
+    HandlerImpl
+}
+
+struct HandlerImpl;
+
+impl Handler for HandlerImpl {
+    type Error = Infallible;
+
+    fn protected(
+        &mut self,
+        channel: Channel,
+        msg_info: MessageInfo,
+    ) -> Result<MessageInfo, Self::Error> {
+        debug_println!("server: called by {:?}", channel);
+
+        todo!()
+    }
+}
+
+
+
+

The +Channel type is the Rust equivalent of the +microkit_channel +type alias in libmicrokit. +Note how the functionality corresponding to libmicrokit's microkit_notify, microkit_irq_ack, and microkit_ppcall is implemented in methods for Channel.

+

The +MessageInfo type is the Rust equivalent of the +microkit_msginfo +type alias in libmicrokit. +Just as microkit_msginfo is an alias for seL4_MessageInfo_t, sel4_microkit::MessageInfo is just a thin wrapper around MessageInfo.

+

libmicrokit has microkit_mr_set() and microkit_mr_get() for interacting with the IPC buffer. +In the sel4_microkit crate, we have +get_mr() +and +set_mr() +, +but we also have +with_msg_regs(), +with_msg_regs_mut(), +with_msg_bytes(), and +with_msg_bytes_mut(), +which use +sel4::with_ipc_buffer() and +sel4::with_ipc_buffer_mut() under the hood.

+

Step 10.A (exercise)       

+

Exercise: +In the client's notified() handler, make a protected procedure call to the server using SERVER.pp_call(). +Handle the call in the server's protected() handler. +Include data in the message using sel4_microkit::with_msg_regs{,_mut}.

+

Exercise (optional): +Send something more interesting over IPC using +msg_bytes +and +msg_bytes_mut +. +For example, the zerocopy crate can be used to view certain types as bytes and vice versa, and the lightweight postcard crate can be used to serialize and deserialize a wider range of types using serde.

+
+

Shared Memory

+

This chapter covers interacting with shared memory from protection domains written in Rust. +Navigate to and run the example:

+
cd workspaces/microkit/shared-memory
+make simulate
+
+

The example system description specifies two protection domains which share two memory regions:

+
+
+
shared-memory.system:7:28
+
+
+
<system>
+    <memory_region name="region_a" size="0x1_000" />
+
+    <memory_region name="region_b" size="0x1_000" />
+
+    <protection_domain name="client" priority="100">
+        <program_image path="microkit-shared-memory-client.elf" />
+        <map mr="region_a" vaddr="0x2_000_000" perms="rw" cached="true" setvar_vaddr="region_a_vaddr" />
+        <map mr="region_b" vaddr="0x2_400_000" perms="rw" cached="true" setvar_vaddr="region_b_vaddr" />
+    </protection_domain>
+
+    <protection_domain name="server" priority="200">
+        <program_image path="microkit-shared-memory-server.elf" />
+        <map mr="region_a" vaddr="0x2_000_000" perms="r" cached="true" setvar_vaddr="region_a_vaddr" />
+        <map mr="region_b" vaddr="0x2_400_000" perms="r" cached="true" setvar_vaddr="region_b_vaddr" />
+    </protection_domain>
+
+    <channel>
+        <end pd="client" id="13" pp="true" />
+        <end pd="server" id="37" />
+    </channel>
+</system>
+
+
+
+
+

The Microkit tool will inject memory region virtual addresses into protection domain images according to the setvar_vaddr attribute values. +For example, the virtual address of the mapping of region_a into the client protection domain will be injected into the microkit-shared-memory-client.elf image at the location specified by then region_a_vaddr symbol.

+

In the case of Rust, declaring a symbol that the Microkit tool can patch requires a bit more intentionality than in the C case. +The sel4_microkit::var! macro is provided to declare such symbols.

+

The var! macro's implementation is just a few lines of code. +We want to express this symbol as a global variable that does not change at runtime, but which cannot be assumed to have the value we assign it at compile time, and which must not be optimized away. +The near-trivial +sel4_immutable_cell::ImmutableCell type encapsulates this pattern. +The #[no_mangle] attribute instructs the compiler to use the name of the variable as the name of the symbol. +This is the default in C, but not Rust. +We direct the compiler to put this symbol in the .data section with #[link_section = ".data"] to ensure that space is allocated for it in the ELF file itself, not just the program image it describes.

+

So far, the example protection domains just store pointers to the shared memory regions in their handler state:

+
+
+
pds/client/src/main.rs:17:31
+
+
+
fn init() -> impl Handler {
+    debug_println!("client: initializing");
+
+    let region_a = *var!(region_a_vaddr: usize = 0);
+    let region_b = *var!(region_b_vaddr: usize = 0);
+
+    debug_println!("client: region_a = {region_a:#x?}");
+    debug_println!("client: region_b = {region_b:#x?}");
+
+    let _ = SERVER.pp_call(MessageInfo::default());
+
+    debug_println!("TEST_PASS");
+
+    NullHandler::new()
+}
+
+
+
+
+
+
pds/server/src/main.rs:17:46
+
+
+
fn init() -> impl Handler {
+    debug_println!("server: initializing");
+
+    let region_a = *var!(region_a_vaddr: usize = 0);
+    let region_b = *var!(region_b_vaddr: usize = 0);
+
+    debug_println!("server: region_a = {region_a:#x?}");
+    debug_println!("server: region_b = {region_b:#x?}");
+
+    HandlerImpl { region_a, region_b }
+}
+
+struct HandlerImpl {
+    region_a: usize,
+    region_b: usize,
+}
+
+impl Handler for HandlerImpl {
+    type Error = Infallible;
+
+    fn protected(
+        &mut self,
+        channel: Channel,
+        _msg_info: MessageInfo,
+    ) -> Result<MessageInfo, Self::Error> {
+        assert_eq!(channel, CLIENT);
+
+        Ok(MessageInfo::default())
+    }
+}
+
+
+
+

Step 11.A       

+

Let's assign types to these shared memory regions. +We can define our types in a crate that both the client and server can use:

+
+
+
pds/common/src/lib.rs:9:18
+
+
+
use zerocopy::{FromBytes, IntoBytes};
+
+pub const REGION_A_SIZE: usize = 1337;
+
+#[repr(C)]
+#[derive(IntoBytes, FromBytes)]
+pub struct RegionB {
+    pub field_1: u64,
+    pub foo: [u16; 16],
+}
+
+
+
+

Suppose region_a: [u8; REGION_A_SIZE] and region_b: RegionB. +You could just turn the virtual addresses we get in our var! symbols into pointers and start interacting with the shared memory regions with unsafe ptr::* operations, but we can leverage the Rust type system to come up with a solution that only requires unsafe at initialization time.

+

Step 11.B       

+

The +sel4-shared-memory +crate provides a way for you to declare a memory region's type and bounds, along with the memory access operations that can safely be used on it, so that you can access it without unsafe code. +That initial declaration is, however, unsafe.

+

The +sel4-shared-memory +is a thin wrapper around the +sel4_abstract_ptr +crate, instantiating its abstract pointer types with memory access operations suitable for memory that is shared with another protection domain.

+

The +sel4_microkit::memory_region_symbol! +macro is like the sel4_microkit::var! macro, except specialized for shared memory region virtual address symbols. +For one, the underlying symbol is always of type usize and the macro returns a value of type NonNull<_>. +memory_region_symbol! has a few additional features. +For example, memory_region_symbol!(foo: *mut [u8] n = BAR) returns a NonNull<[u8]> with a runtime slice length of BAR.

+

See this step's diff for how to put this all together.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/root-task/address-space.html b/projects/rust/tutorial/root-task/address-space.html new file mode 100644 index 00000000000..fd1a761f527 --- /dev/null +++ b/projects/rust/tutorial/root-task/address-space.html @@ -0,0 +1,330 @@ + + + + + + Modifying the Address Space - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Modifying the Address Space

+

This chapter will focus on using the seL4 virtual address space (VSpace) APIs to manipulate the root task's own address space. +Start by navigating to and running this chapter's example, which, so far, is empty.

+
cd workspaces/root-task/address-space
+make simulate
+
+

In seL4, each thread is associated with a virtual address space (VSpace). +A VSpace is comprised of a tree of translation tables mapping virtual addresses into physical frames of memory. +VSpaces are represented by their root translation structures. +While the high-level virtual address space API concepts are architecture-independent, the specific kernel object types for a given architecture mirror that architecture's paging structures. +That said, all architectures share two object types:

+ +

The root task is provided with capabilites for the objects comprising its own virtual address space. +The locations of these capabilities in the root task's CSpace is provided in the BootInfo struct. +Our goal for this chapter will be to create a frame object and experiment with mapping it into the root task's own address space.

+

Step 4.A (exercise)       

+

Exercise: Using code snippets from Chapter 3 (Allocating Kernel Objects), create a frame object. We seek a value frame: sel4::cap::Granule (which can also be written as frame: sel4::Cap<sel4::cap_type::Granule>).

+

Note that, after importing the sel4::CapTypeForObjectOfFixedSize trait, you can express the appropriate sel4::ObjectBlueprint as sel4::cap_type::Granule::object_blueprint().

+

Step 4.B       

+

In order to avoid interacting with intermediate translation structures, let's reserve an aligned granule-sized region in the root task's program image that we can use for our experiment:

+
+
+
workspaces/root-task/address-space/src/main.rs:15:20 after 4.B
+
+
+
const GRANULE_SIZE: usize = sel4::FrameObjectType::GRANULE.bytes(); // 4096
+
+#[repr(C, align(4096))]
+struct PagePlaceholder(#[allow(dead_code)] [u8; GRANULE_SIZE]);
+
+static mut PAGE_A: PagePlaceholder = PagePlaceholder([0xee; GRANULE_SIZE]);
+
+
+
+
+
+
workspaces/root-task/address-space/src/main.rs:46:49 after 4.B
+
+
+
    let page_a_addr = ptr::addr_of!(PAGE_A).cast::<u8>();
+    sel4::debug_println!("PAGE_A: {page_a_addr:#x?}");
+    assert_eq!(page_a_addr as usize % GRANULE_SIZE, 0);
+    assert_eq!(unsafe { page_a_addr.read() }, 0xee);
+
+
+
+

This reservation covers exactly one page in the root task's virtual address space.

+

Step 4.C       

+

Let's unmap the page in the root task image that initially backs our reserved region. This will give us a hole in the root task VSpace, which we can use for our experiment.

+

This function determines the slot in the root task's CSpace of the page capability corresponding to the page in the root task's VSpace which contains the given address:

+
+
+
workspaces/root-task/address-space/src/main.rs:73:84 after 4.C
+
+
+
fn get_user_image_frame_slot(
+    bootinfo: &sel4::BootInfo,
+    addr: usize,
+) -> sel4::init_thread::Slot<sel4::cap_type::Granule> {
+    extern "C" {
+        static __executable_start: usize;
+    }
+    let user_image_addr = ptr::addr_of!(__executable_start) as usize;
+    bootinfo
+        .user_image_frames()
+        .index(addr / GRANULE_SIZE - user_image_addr / GRANULE_SIZE)
+}
+
+
+
+

__executable_start is defined by the linker. +We can use it, along with addr, to identify the offset into bootinfo.user_image_frames() of the capability we are after.

+

Use the get_user_image_frame_slot() function to find the capability corresponding to the frame backing our reserved region, and unmap that frame, leaving a hole in the root task's virtual address space. +Try to access that region, and observe a page fault:

+
+
+
workspaces/root-task/address-space/src/main.rs:51:54 after 4.C
+
+
+
    let page_a_slot = get_user_image_frame_slot(bootinfo, page_a_addr as usize);
+    page_a_slot.cap().frame_unmap().unwrap();
+
+    unsafe { page_a_addr.read() };
+
+
+
+

Step 4.D (exercise)       

+

Exercise: Map new_frame at page_a_addr using new_frame.frame_map(), which corresponds to seL4_ARM_Page_Map.

+

Here are some hints for the parameters of .frame_map():

+
    +
  • vspace: A capability for the root task's VSpace can be expressed using sel4::init_thread::slot::VSPACE.cap().
    • +
  • rights: sel4::CapRights::read_write() are the most permissive rights, and will work for our purposes.
    • +
  • attrs: sel4::VmAttributes::default() will work here.
    • +
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/root-task/hello-world.html b/projects/rust/tutorial/root-task/hello-world.html new file mode 100644 index 00000000000..1b5d6cff6b6 --- /dev/null +++ b/projects/rust/tutorial/root-task/hello-world.html @@ -0,0 +1,328 @@ + + + + + + Hello, World! - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Hello, World!

+

Run the hello world example:

+
cd workspaces/root-task/hello-world
+make simulate
+
+

Press ctrl-a x to exit QEMU.

+

Here is its source:

+
+
+
hello-world/src/main.rs:7:17
+
+
+
#![no_std]
+#![no_main]
+
+use sel4_root_task::root_task;
+
+#[root_task]
+fn main(_bootinfo: &sel4::BootInfoPtr) -> ! {
+    sel4::debug_println!("Hello, World!");
+
+    sel4::init_thread::suspend_self()
+}
+
+
+
+

The Rust standard library is divided into three layers:

+
    +
  • core: dependency-free foundation
    • +
  • alloc: implements heap-backed data structures, but requires a runtime that provides a heap allocator
    • +
  • std includes core and alloc, and adds APIs that depend on OS services such as networking and filesystems
    • +
+

The high-level std doesn't support the low-level seL4 root task target. +#![no_std] declares that this crate does not depend on std, and prevents rustc from automatically importing it.

+

Our language runtime will handle the program's entrypoint differently than a typical Rust program. +#![no_main] informs rustc of this fact.

+

The sel4 crate binds the seL4 API. +It is generated from source (.xml, .bf, and .h) in libsel4. +We will cover the contents of this crate in future chapters.

+

The sel4_root_task crate implements a Rust language runtime for the root task environment.

+

The #[root_task] attribute macro declares a function to be the root task's entrypoint. +The entrypoint function must have a signature of the form:

+
fn(&sel4::BootInfoPtr) -> T
+where
+    T: sel4_root_task::Termination
+

(Rustdoc for BootInfoPtr and Termination)

+

The root task has no way to exit, so, to terminate cleanly, it must suspend its own thread. +sel4::init_thread::suspend_self() does exactly this.

+

Step 2.A (exercise)       

+

Exercise: Cause a panic.

+

Step 2.B (exercise)       

+

Exercise: Catch the panic using sel4_root_task::panicking::catch_unwind().

+

Step 2.C (exercise)       

+

You can set a custom panic hook with sel4_root_task::panicking::PanicHook. +The default hook just prints the panic's ExternalPanicInfo.

+

Exercise: Set a custom panic hook.

+

Step 2.D (exercise)       

+

Exercise: Cause a stack overflow.

+

Step 2.E (exercise)       

+

The #[root_task] attribute macro accepts a named stack_size parameter, which can be any expression of type usize and whose value is interpreted as the root task's initial thread's stack size, in bytes. +For example:

+
#[root_task(stack_size = 13 * 37)]
+

The default stack size is sel4_root_task::DEFAULT_STACK_SIZE.

+

Exercise: Adjust the root task's initial thread's stack size to prevent the stack overflow you just caused.

+

Step 2.F (exercise)       

+

By default, the sel4_root_task runtime does not include a heap. +Any attempt to use the alloc crate will result in a link-time failure.

+

The #[root_task] attribute macro accepts a heap_size parameter, which can be any expression of type usize and whose value is interpreted as the root task's heap size, in bytes. +Note that heap_size must come after stack_size in the case where both are present. +For example:

+
#[root_task(heap_size = 0xf00d)]
+

or

+
#[root_task(stack_size = 13 * 37, heap_size = 0xf00d)]
+

Exercise: Add a heap and use it.

+

Step 2.G       

+

The sel4_logging crate builds on top of the log crate to add utilities for initializing simple loggers in minimal environments, such as a seL4 root task. +This step demonstrates one way to initialize a logger using this crate:

+
+
+
hello-world/src/main.rs:17:20 after 2.G
+
+
+
static LOGGER: Logger = LoggerBuilder::const_default()
+    .level_filter(LevelFilter::Info)
+    .write(|s| sel4::debug_print!("{}", s))
+    .build();
+
+
+
+
+
+
hello-world/src/main.rs:41 after 2.G
+
+
+
    LOGGER.set().unwrap();
+
+
+
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/root-task/index.html b/projects/rust/tutorial/root-task/index.html new file mode 100644 index 00000000000..fdb85f665f9 --- /dev/null +++ b/projects/rust/tutorial/root-task/index.html @@ -0,0 +1,244 @@ + + + + + + Overview - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

The Root Task

+

After initializing itself, the seL4 kernel passes control to a userspace program called the root task, whose image is provided to the kernel at boot-time. +The root task's capability space contains capabilities for all memory and boot-time objects. +That is to say, the root task spawns with the maximum privilege that a userspace program can have. +The kernel provides the root task with a map of its initial capability space in the form of the BootInfo frame. +You can read more about the root task's environment in seL4 Reference Manual § 9.1.

+

Part I of this tutorial will focus on writing from-scratch root tasks in Rust. +Some of the code in Part I will be quite low-level, interacting with the language runtime, the linker, and some of the finer details related to bootstrapping an seL4-based system. +The only seL4-related crates we will be using are the language runtime and bindings for the seL4 API. +Unlike situations where higher-level seL4-related libraries (such as seL4_libs) are used, we will be allocating objects and manage virtual address spaces from scratch.

+

At boot time, the seL4 kernel and root task are loaded into memory by a kind of bootloader stub referred to as a seL4 kernel loader. +For Part I, we will use the kernel loader from the rust-sel4 project. +We won't cover how it works or how to use it explicitly in this text. +It is built at docker/Dockerfile:94:108, and used at mk/root-task.mk:31:36.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/root-task/kernel-objects.html b/projects/rust/tutorial/root-task/kernel-objects.html new file mode 100644 index 00000000000..bc41eeeb4e0 --- /dev/null +++ b/projects/rust/tutorial/root-task/kernel-objects.html @@ -0,0 +1,420 @@ + + + + + + Allocating Kernel Objects - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Allocating Kernel Objects

+

Start by navigating to and running this chapter's example, which, so far, is empty.

+
cd workspaces/root-task/kernel-objects
+make simulate
+
+

Userspace operates the seL4 kernel by creating, managing, and accessing kernel objects via references called capabilites. +See seL4 Reference Manual § 2.3 (Kernel Objects) for an outline of the core types of kernel objects.

+

In the context of seL4, a capability is a granular, unforgeable token of authority that references a kernel object and carries access rights that limit what the user of a cabability can do with the referenced kernel object. +In general, a system call in seL4 amounts to refering to a cabability and an action on the kernel object the cabability points to. +This is called invoking a capability.

+ +

Just as each thread is associated with a virtual address space which the hardware uses to translate virtual memory addresses into locations in physical memory, each seL4 thread is also assocated with a capability space (CSpace) which the kernel uses to translate so-called capability pointers (CPointers or CPtrs) into locations (slots) in the kernel's capability tables called CNodes.

+

The sel4::CPtr type is a wrapper around a machine word. +The sel4::Cap<T> type wraps a CPtr associated with the current thread's CSpace, and thus points to a particular capability slot within the kernel. +It is paramterized by a capability type T: sel4::CapType, representing the type of capability in that slot. +It is up to the crate user to ensure that Cap's are valid and well-typed in the current thread.

+

The sel4::cap module contains aliases of the form sel4::Cap<sel4::cap_type::*>.

+

Depending on the Cap's type T, a Cap has a number of methods available, which correspond to invocations for that capability type. +For example, sel4::Cap::tcb_resume() is available when T is sel4::cap_type::Tcb.

+

Step 3.A       

+

As elaborated in seL4 Reference Manual § 2.4 (Kernel Memory Allocation), userspace is responsible for managing the memory associated with kernel objects. +Untyped memory is the name of the object type for free memory. +At boot time, the root task is granted untyped memory capabilities for all of the system's memory, except for the memory used for the kernel and the root task's own resources.

+

Print the untyped memory described by the BootInfo frame:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:14:22 after 3.A
+
+
+
    sel4::debug_println!("untyped:");
+    for ut_desc in bootinfo.untyped_list() {
+        sel4::debug_println!(
+            "    paddr: {:#016x?}, size bits: {:02?}, is device: {:?}",
+            ut_desc.paddr(),
+            ut_desc.size_bits(),
+            ut_desc.is_device()
+        );
+    }
+
+
+
+

Sample output:

+
untyped:
+    paddr: 0x00000000000000, size bits: 27, is device: true
+    paddr: 0x00000008001000, size bits: 12, is device: true
+    paddr: 0x00000008002000, size bits: 13, is device: true
+    paddr: 0x00000008004000, size bits: 14, is device: true
+    paddr: 0x00000008008000, size bits: 15, is device: true
+    paddr: 0x00000008011000, size bits: 12, is device: true
+    paddr: 0x00000008012000, size bits: 13, is device: true
+    ...
+
+

sel4::UntypedDesc::size_bits() returns the log base 2 of the size of the region of memory described by the descriptor.

+

sel4::UntypedDesc::is_device() returns whether the region is device memory or kernel memory. +Device memory can only be used for creating frames, whereas kernel memory has no such restrictions.

+

Step 3.B       

+

Add a function that finds the largest untyped region passed to the root task:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:32:42 after 3.B
+
+
+
fn find_largest_kernel_untyped(bootinfo: &sel4::BootInfo) -> sel4::cap::Untyped {
+    let (ut_ix, _desc) = bootinfo
+        .untyped_list()
+        .iter()
+        .enumerate()
+        .filter(|(_i, desc)| !desc.is_device())
+        .max_by_key(|(_i, desc)| desc.size_bits())
+        .unwrap();
+
+    bootinfo.untyped().index(ut_ix).cap()
+}
+
+
+
+

The expression bootinfo.untyped().index(ut_ix).cap() indexes into bootinfo.untyped(): SlotRegion<Untyped> to retrieve a Slot<Untyped>, which can be turned into a Cap<Untyped> (= cap::Untyped).

+

Step 3.C       

+

In this step, we will allocate a Notification object.

+

We already know how to refer to a capability in the current thread's CSpace: a CPtr. +However, some capability invocations allow us to refer to a capability slot in any CSpace whose root CNode is present in the current thread's CSpace. +In these cases, we must provide:

+
    +
  • A CPtr, interpreted in the context of the current thread's CSpace, which points to the target CSpace's root CNode
    • +
  • A CPtr, interpreted in the context of the target CSpace, which points to the target capability slot
    • +
  • A depth, which is the number of bits of the second CPtr to interpret. This allows for the second CPtr to point to a CNode. Why this is necessary is outside the scope of this tutorial, but you can read about it in seL4 Reference Manual § 2.4 (CSpace Addressing).
    • +
+

Consider, for example, the seL4_CNode_Mint capability invocation. +dest_* and src_* are both capability slots addressed in this way.

+

This more flexible method of capability slot addressing is encapsulated in the sel4::AbsoluteCPtr type.

+

The seL4_Untyped_Retype method is used for allocating new objects from an untyped object. +The _service parameter is the address of the untyped object as a normal CPtr. +root, node_index, and node_depth address, in the more flexible way outlined above, the destination CNode into which capabilities for the new objects will be inserted. +node_offset and num_objects specify a range of slots within the selected CNode for the new capabilites (and, simultaneously, the number of new objects that will be created).

+

type and size_bits specify the shape of the new object(s) +Note that size_bits is relevant for only certain object types (see seL4 Reference Manual § 2.4.2 (Summary of Object Sizes) for more information). +This shape information is encapsulated in the sel4::ObjectBlueprint type.

+

Multiple kernel objects can be allocated from a single unytped object. +For each untyped object, the kernel maintains a watermark which tracks how much of the untyped object has been used up for object allocation. +seL4_Untyped_Retype aligns the watermark to the desired object type's size, and then advances it according to the object type size and number of objects. +This process is detailed in the fourth paragraph of seL4 Reference Manual § 2.4.1 (Reusing Memory).

+

Let us now work towards calling sel4::cap::Untyped::untyped_retype() on our previously acquired largest_kernel_ut. +We wish to allocate one notification object and insert a capability for it into a free slot in the current thread's own CSpace. +More precisely, we need a sel4::AbsoluteCPtr for the current thread's own CSpace's root CNode, and an index into that CNode for a free slot.

+

The CPtr for the initial thread's own CSpace root is a constant:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:27:27 after 3.C
+
+
+
    let cnode = sel4::init_thread::slot::CNODE.cap();
+
+
+
+

bootinfo can tell us about a range of empty slots in this CSpace. +We can leverage the fact that Rust's Range<T> type is an iterator for certain T to allocate slots in an ergonomic way:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:29:33 after 3.C
+
+
+
    let mut empty_slots = bootinfo
+        .empty()
+        .range()
+        .map(sel4::init_thread::Slot::from_index);
+    let notification_slot = empty_slots.next().unwrap();
+
+
+
+

The {{#rustdoc_link root-task sel4/cap/type.CNode.html#method.absolute_cptr_for_selfsel4::cap::CNode::absolute_cptr_for_self()}} method elaborates a sel4::cap::Cnode into a sel4::AbsoluteCPtr. +Interestingly, there are two ways to do this, but the current implementation is just to use a depth of zero.

+

Now we can invoke our untyped capability to allocate a notification object:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:36:43 after 3.C
+
+
+
    largest_kernel_ut
+        .untyped_retype(
+            &sel4::ObjectBlueprint::Notification,
+            &cnode.absolute_cptr_for_self(),
+            notification_slot.index(),
+            1,
+        )
+        .unwrap();
+
+
+
+

Now that we know that notification_slot contains a notification capability, we can cast it and get a sel4::cap::Notification:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:45:47 after 3.C
+
+
+
    let notification = notification_slot
+        .downcast::<sel4::cap_type::Notification>()
+        .cap();
+
+
+
+

Step 3.D (exercise)       

+

Exercise:: Use sel4::cap::Notification::signal() and sel4::cap::Notification::wait() to signal and then wait on the notification.

+

Step 3.E (exercise)       

+

As described in seL4 Reference Manual § 5 (Notifications), a notification capability can contain a word-sized mask called a badge. +When that capability is used to signal the notification, the notification's word-sized state is bit-wise ored with the capability's badge. +A wait call on the notification returns and clears the notification's state, provided that a signal call has occurred since the last wait call.

+

sel4::AbsoluteCPtr::mint() mints a new capability from an existing capability, updatings its access rights and badge.

+

Exercise:: Allocate a new empty slot in the current CNode.

+

A slot in the root task's CSpace (i.e. a value of type sel4::init_thread::Slot) can be turned into an sel4::AbsoluteCPtr using {{#rustdoc_link root-task sel4/cap/type.CNode.html#method.absolute_cptrsel4::CNode::absolute_cptr()}}:

+
+
+
workspaces/root-task/kernel-objects/src/main.rs:63:63 after 3.E
+
+
+
            &cnode.absolute_cptr(notification_slot.cptr()),
+
+
+
+

Exercise:: Mint a capability based on the capability in notification_slot into your newly allocated slot. Use sel4::CapRights::all() for the rights parameter, and specify a non-zero badge value.

+

Exercise:: Signal the notification using your newly minted badged capability. Using the return value of sel4::Notification::wait(), compare the badge value it returns with the badge you used to mint the capability.

+

Step 3.F (exercise)       

+

Exercise:: sel4::CapRights::all() is overly-permissive. Use the overly-restrictive sel4::CapRights::none() instead and watch the program fail.

+

Step 3.G (exercise)       

+

Exercise:: Now use the minimum rights necessary for the program to run.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/root-task/serial-device.html b/projects/rust/tutorial/root-task/serial-device.html new file mode 100644 index 00000000000..7a188bf9504 --- /dev/null +++ b/projects/rust/tutorial/root-task/serial-device.html @@ -0,0 +1,424 @@ + + + + + + Using a Serial Device - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Using a Serial Device

+

In this chapter, we will build a root task that interacts with a serial device. +Start by navigating to and running this chapter's example, which, so far, doesn't do anything interesting.

+
cd workspaces/root-task/serial-device
+make simulate
+
+

The module at device.rs implements a higher-level interface over the serial device's MMIO registers, whose physical base address is:

+
+
+
workspaces/root-task/serial-device/src/main.rs:16:16
+
+
+
const SERIAL_DEVICE_MMIO_PADDR: usize = 0x0900_0000;
+
+
+
+

Our first goal will be to map the serial device's MMIO registers into the root task's address space.

+

After that, we will set up the root task's access to the serial device's interrupt, whose value is:

+
+
+
workspaces/root-task/serial-device/src/main.rs:18:18
+
+
+
const SERIAL_DEVICE_IRQ: usize = 33;
+
+
+
+

Finally, we will implement a simple loop that echoes serial input to serial output.

+

Step 5.A       

+

First, add some familiar snippets that we will use for allocating CSlots and kernel objects:

+
+
+
workspaces/root-task/serial-device/src/main.rs:34:44 after 5.A
+
+
+
fn find_largest_kernel_untyped(bootinfo: &sel4::BootInfo) -> sel4::cap::Untyped {
+    let (ut_ix, _desc) = bootinfo
+        .untyped_list()
+        .iter()
+        .enumerate()
+        .filter(|(_i, desc)| !desc.is_device())
+        .max_by_key(|(_i, desc)| desc.size_bits())
+        .unwrap();
+
+    bootinfo.untyped().index(ut_ix).cap()
+}
+
+
+
+
+
+
workspaces/root-task/serial-device/src/main.rs:22:27 after 5.A
+
+
+
    let mut empty_slots = bootinfo
+        .empty()
+        .range()
+        .map(sel4::init_thread::Slot::<sel4::cap_type::Unspecified>::from_index);
+
+    let largest_kernel_ut = find_largest_kernel_untyped(bootinfo);
+
+
+
+

Step 5.B (exercise)       

+

largest_kernel_ut will be useful for allocating kernel objects whose backing physical addresses don't matter to us, but we must allocate the frame which contains the serial device's MMIO registers at a particular physicall address (SERIAL_DEVICE_MMIO_PADDR). +Furthermore, the seL4 API distinguishes between general purpose untyped and device untyped. General purpose untyped is backed by normal memory, and can be used to create any type of object. Device untyped is not backed by normal memory, and can only be used to create frames. +See the last two paragraphs of seL4 Reference Manual § 2.4 (Kernel Memory Allocation) for more information. +So, we must allocate the serial device MMIO frame from the particular initial device untyped that contains SERIAL_DEVICE_MMIO_PADDR.

+

Exercice: Identify this initial untyped in the bootinfo. We will need a corresponding sel4::cap::Untyped along with the untyped's physical address (or sel4::UntypedDesc, which contains the physical address) for the next step.

+

Step 5.C       

+

The untyped we've identified contains the frame we are targeting, but that frame may be somewhere in the middle of the region of device memory the untyped covers. +To allocate the frame at SERIAL_DEVICE_MMIO_PADDR, we must allocate dummy objects from this untyped until its watermark is at SERIAL_DEVICE_MMIO_PADDR.

+

This trim_untyped function takes the untyped capability, its physical address, the desired physical address, and two empty slots for temporarily holding dummy objects. +We need two slots because the kernel resets an untyped's watermark if it has no live children. +So, we must always keep one child around so that our progress on advancing the watermark is never lost.

+
+
+
workspaces/root-task/serial-device/src/main.rs:43:49 after 5.C
+
+
+
    trim_untyped(
+        device_ut_cap,
+        device_ut_desc.paddr(),
+        SERIAL_DEVICE_MMIO_PADDR,
+        empty_slots.next().unwrap(),
+        empty_slots.next().unwrap(),
+    );
+
+
+
+
+
+
workspaces/root-task/serial-device/src/main.rs:68:97 after 5.C
+
+
+
fn trim_untyped(
+    ut: sel4::cap::Untyped,
+    ut_paddr: usize,
+    target_paddr: usize,
+    free_slot_a: sel4::init_thread::Slot,
+    free_slot_b: sel4::init_thread::Slot,
+) {
+    let rel_a = sel4::init_thread::slot::CNODE
+        .cap()
+        .absolute_cptr(free_slot_a.cptr());
+    let rel_b = sel4::init_thread::slot::CNODE
+        .cap()
+        .absolute_cptr(free_slot_b.cptr());
+    let mut cur_paddr = ut_paddr;
+    while cur_paddr != target_paddr {
+        let size_bits = (target_paddr - cur_paddr).ilog2().try_into().unwrap();
+        ut.untyped_retype(
+            &sel4::ObjectBlueprint::Untyped { size_bits },
+            &sel4::init_thread::slot::CNODE
+                .cap()
+                .absolute_cptr_for_self(),
+            free_slot_b.index(),
+            1,
+        )
+        .unwrap();
+        rel_a.delete().unwrap();
+        rel_a.move_(&rel_b).unwrap();
+        cur_paddr += 1 << size_bits;
+    }
+}
+
+
+
+

Step 5.D       

+

device_ut_cap is now primed; the physical address of the next allocation will be SERIAL_DEVICE_MMIO_PADDR.

+

Exercise: Allocate a small frame object (sel4::cap_type::Granule) from device_ut_cap.

+

If your sel4::cap::Granule is called serial_device_frame_cap, then the following assertion should succeed:

+
+
+
workspaces/root-task/serial-device/src/main.rs:70:73 after 5.D
+
+
+
    assert_eq!(
+        serial_device_frame_cap.frame_get_address().unwrap(),
+        SERIAL_DEVICE_MMIO_PADDR
+    );
+
+
+
+

Step 5.E (exercise)       

+

Exercise: Using code from Step 4.B, Step 4.C, and Step 4.D, map serial_device_frame_cap into the root task's virtual address space.

+

You should now be able interact with the serial device's MMIO registers. +Try printing "Hello, World!" to the serial console with something like:

+
+
+
workspaces/root-task/serial-device/src/main.rs:102:108 after 5.E
+
+
+
    let serial_device = unsafe { Device::new(serial_device_mmio_page_addr.cast()) };
+
+    serial_device.init();
+
+    for c in b"Hello, World!\n" {
+        serial_device.put_char(*c);
+    }
+
+
+
+

where serial_device_mmio_page_addr: *mut _ is a pointer to where the MMIO registers are mapped in the root task's virtual address space.

+

Step 5.F (exercise)       

+

Interrupts are delivered to userspace via notifications. +A IRQHandler capability represents the authority to manage a particular interrupt. +Specifically, an IRQHandler capability (sel4::cap::IrqHandler) has the following methods:

+
    +
  • seL4_IRQHandler_SetNotification(): +Associate the interrupt with the given notification. Userspace can call seL4_Wait() or seL4_Poll() on this notification to receive the interrupt.
    • +
  • seL4_IRQHandler_Clear(): +Disassociate the notification associated with this interrupts.
    • +
  • seL4_IRQHandler_Ack(): +Tell the kernel to pass on acknowledgement of this interrupt to the interrupt controller.
    • +
+

The Rust bindings for these methods are:

+ +

The root task spawns with a special IRQControl capability (sel4::cap::IrqControl) which can be used to create IRQHandler capabilities with seL4_IRQControl_Get() (sel4::cap::IrqControl::irq_control_get()).

+

The intent behind this API is that a highly-privileged component will hold an IRQControl capability, which it will use to distribute more finely-grained IRQHandler capabilities to less privileged components for the interrupts they will manage.

+

The root task can access its IRQControl capability with sel4::init_thread::slot::IRQ_CONTROL.cap()

+

Exercise: Use sel4::init_thread::slot::IRQ_CONTROL.cap() to create a sel4::cap::IrqHandler for SERIAL_DEVICE_IRQ.

+

Step 5.G (exercise)       

+

Exercise: Create a notification object from largest_kernel_ut and associate it with the IRQHandler you just created using sel4::cap::IrqHandler::irq_handler_set_notification().

+

Step 5.H (exercise)       

+

Exercise: Use serial_device: Device, your IRQHandler, and the notification you associated with the interrupt to write a loop that echoes serial input to serial output.

+

Use serial_device.clear_all_interrupts() and irq_handler_cap.irq_handler_ack() in sequence to clear the interrupt at the device and interrupt controller levels respectively. +Note that you should do this at the beginning of the loop in case your loop enters with an interrupt already pending.

+

Use irq_notification_cap.wait() to wait for hte interrupt.

+

Use serial_device.get_char() and serial_device.put_char() to read and write data.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/root-task/spawn-task.html b/projects/rust/tutorial/root-task/spawn-task.html new file mode 100644 index 00000000000..e7690797325 --- /dev/null +++ b/projects/rust/tutorial/root-task/spawn-task.html @@ -0,0 +1,301 @@ + + + + + + Spawning a Task (Challenge) - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Spawning a Task (Challenge)

+

This final chapter of Part I contains a more open-ended and challenging exercise. +We start with an example that spawns an entire new process, which, in the context of low-level seL4 userspace, is often called a task:

+
cd workspaces/root-task/spawn-task
+make simulate
+
+

Similarly to what we saw in Chapter 6 (Spawning a Thread), the code in this example is more low-level and complex compared to what you have seen in code that leverages <sel4utils/process.h>. +Again, our code here is more like spawning a task using <sel4/sel4.h> alone.

+

This example consists of two programs. +The spawn-task crate is the root task, and the spawn-task-child crate is the child task.

+

The child task does not spawn in any standard sort of environment, so is includes its own ad-hoc Rust language runtime in child/src/runtime.rs, complete with thread-local storage, a global heap allocator, and exception handling. +This runtime is built using a few Rust langauge runtime building block crates:

+ +

This minimal, ad-hoc language runtime is a neat, instructive piece of code. +It shows how one can build a new Rust language runtime out of the building blocks provided by the rust-sel4 project.

+

Explore the root task and child task.

+

Right now, all the child task does is send a test message over an endpoint back to the root task. +The challenge in this chapter, step 7.E, is to extend the root task so that it sets up the child task to be able to interact with the serial device, and to extend the child task to implement the same echo loop as in [./serial-device.html#step-5h]. +Steps 7.A, 7.B, 7.C, and 7.D, which are not exercises, make some incremental extensions towards those goals to help you get started.

+

Step 7.A       

+

This step extends the ObjectAllocator type in workspaces/root-task/spawn-task/src/object_allocator.rs after 7.B with the recklessly_allocate_at() method. +This method allocates an object according to the blueprint parameter at the given physical address paddr. +Instead of just allocating the object from the largest kernel untyped like the allocate() method does, this method searches through the bootinfo to find the initial untyped capability whose corresponding untyped object contains paddr, allocates dummy objects from this untyped object until its watermark reaches paddr, and then allocates the desired object. +recklessly_allocate_at()'s procedure is similar to that which we followed in step 5.C.

+

This implementation is "reckless" because it modifies the state of the untyped capability it allocates from (allocating from it and changing its watermark) without keeping track of having done so. +So, subsequent calls for paddrs contained in the same initial untyped would fail or, worse, misbehave. +However, we expect to only need to call it once, so we are okay with this caveat.

+

In step 7.E, you be able to use this method to allocate the serial device MMIO register frame.

+

Step 7.B       

+

This step extends the create_child_vspace() function in workspaces/root-task/spawn-task/src/child_vspace.rs after 7.A to take an extra_frames parameter. +create_child_vspace() now maps these extra frames into the child task's address space, after the end of the program image, and after the IPC buffer frame.

+

In step 7.E, you be able to use this parameter to pass in the serial device MMIO register frame to mapped into the child task's address space.

+

Step 7.C       

+

This step simply copies the Device type from chapter 5 into the child task.

+

In step 7.E, you be able to use this type to interact with the serial device's MMIO registers, just like we as part of step 5.E.

+

Step 7.D       

+

This step just adds the SERIAL_DEVICE_MMIO_PADDR and SERIAL_DEVICE_IRQ constants from chapter 5 to the root task.

+

Step 7.E (challenge)       

+

Exercise: +Extend the root task so that it sets up the child task to be able to interact with the serial device, and extend the child task to implement the same echo loop as in [./serial-device.html#step-5h-exercise].

+
+
+ + Hint for the root task (click to expand) + +

Try following this sequence of sub-steps: +- Allocate serial_device_frame_cap: sel4::cap::Granule using object_allocator.recklessly_allocate_at(). +- Map serial_device_frame_cap into the child task's address space using create_child_vspace()'s extra_frames parameter. +- Similarly to how we did so in steps 5.F and 5.G, obtain irq_handler_cap: sel4::cap::IrqHandler for SERIAL_DEVICE_IRQ (object_allocator.allocate_slot() might come in handy), allocate irq_nfn_cap: sel4::cap::Notification, and associate irq_nfn_cap with SERIAL_DEVICE_IRQ using irq_handler_cap. +- Copy irq_handler_cap and irq_nfn_cap into the child task's CSpace in a similar way to how child_tcb and inter_task_ep are copied.

+
+
+

+
+
+ + Hint for the child task (click to expand) + +

Try following this sequence of sub-steps: +- Declare constants IRQ_HANDLER: sel4::cap::IrqHandler and IRQ_NFN: sel4::cap::Notification after OWN_TCB and INTRA_TASK_EP. +- Obtain the virtual address of the serial device MMIO frame with addr_of_page_beyond_image(1) (recall how create_child_vspace()'s extra_frames parameter works). +- Initialize the serial device with Device::new() and Device::init() (as we did for part of step 5.E), and use the serial device just like we did in step 5.H.

+
+
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/root-task/spawn-thread.html b/projects/rust/tutorial/root-task/spawn-thread.html new file mode 100644 index 00000000000..cecf75dc348 --- /dev/null +++ b/projects/rust/tutorial/root-task/spawn-thread.html @@ -0,0 +1,371 @@ + + + + + + Spawning a Thread - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Spawning a Thread

+

In this chapter, we will explore IPC through an example that spawns a secondary thread. +This example starts with a more interesting program than the other examples we've worked with so far. +It spawns a secondary thread, and then interacts with it using a notification.

+

Navigate to and run the example:

+
cd workspaces/root-task/spawn-thread
+make simulate
+
+

Explore main.rs at will. +If you're used to using seL4_libs, you may notice that our Rust code here is much more low-level and verbose. +That is because we aren't using any higher-level seL4-related libraries such as +<sel4utils/thread.h>. +Our code is more like spawning a thread using <sel4/sel4.h> alone. +Note, though, that our code does depend on a few Rust language runtime building block crates such as +sel4-initialize-tls +and +sel4-stack +.

+

The exercises in this chapter are only concerned with the following two functions, which run concurrently:

+
+
+
workspaces/root-task/spawn-thread/src/main.rs:75:79
+
+
+
fn secondary_thread_main(inter_thread_nfn: sel4::cap::Notification) {
+    sel4::debug_println!("In secondary thread");
+
+    inter_thread_nfn.signal();
+}
+
+
+
+
+
+
workspaces/root-task/spawn-thread/src/main.rs:81:85
+
+
+
fn interact_with_secondary_thread(inter_thread_nfn: sel4::cap::Notification) {
+    sel4::debug_println!("In primary thread");
+
+    inter_thread_nfn.wait();
+}
+
+
+
+

secondary_thread_main() runs in the secondary thread, and interact_with_secondary_thread() runs in the secondary thread.

+

Step 6.A       

+

In this step, we introduce IPC between secondary_thread_main() and interact_with_secondary_thread by changing

+
inter_thread_nfn: sel4::cap::Notification
+
+

to

+
inter_thread_ep: sel4::cap::Endpoint
+
+

Before, the two sides of the notification communicated via +inter_thread_nfn.signal() +and +inter_thread_nfn.wait().

+

Now, communication over this IPC endpoint will happen by +inter_thread_ep.send() and +inter_thread_ep.recv() +.

+ +

As described in seL4 Reference Manual § 4 (Message Passing (IPC)) and seL4 Reference Manual § 4.2 (Endpoints), a capability for an Endpoint object can be invoked with send() and recv(). +send() and recv() block until the two sides of the object rendezvous, at which point a message is passed from the sender to the receiver. +This message may contain data and capabilities.

+

Each thread is associated with a special page of memory called an IPC buffer. +The sender populates its own IPC buffer with data and/or CPtrs, and then calls send() with a metadata value called the MessageInfo. +The kernel copies data from the sender's IPC buffer into that of the receiver, and/or capabilities from the sender's CSpace into that of the receiver. +The kernel uses the MessageInfo to determine how much data to copy between the two IPC buffers +(the length field) +and how many CPtrs to read from the IPC buffers for copying betwen CSpaces +(the +caps_unwrapped +and +extra_caps +fields). +Finally, the kernel passes the MessageInfo, and control, to the receiver.

+

In Rust, the sender and receiver can interact with their own IPC buffer using +sel4::with_ipc_buffer +and +sel4::with_ipc_buffer_mut. +Message data is held in the message registers (an array of machine words), which is a field of the IPC buffer ( +msg_regs +and +msg_regs_mut +). +The length field of the MessageInfo specifies how many message registers will be copied into the receiver's IPC buffer.

+

One can also view the message registers as an array of bytes using +msg_bytes +and +msg_bytes_mut. +In this case, one rounds the length of their message up to the nearest multiple of the machine word size when computing the message length for the MessageInfo.

+

The MessageInfo also includes a few bits of data called a label (label_width bits wide) that is not interpreted by the kernel.

+

In Rust, the MessageInfoBuilder type is a clear and concise way to construct a MessageInfo.

+

In Rust, to smooth out differences between the mixed-criticality and legacy kernel schedulers, recv() always takes a reply_authority argument. +Under legacy scheduler configurations, which is what this text uses, this argument can be of type ().

+

Taking all of this together, let's use our IPC endpoint to send an empty message:

+
+
+
workspaces/root-task/spawn-thread/src/main.rs:75:79 after 6.A
+
+
+
fn secondary_thread_main(inter_thread_ep: sel4::cap::Endpoint) {
+    sel4::debug_println!("In secondary thread");
+
+    inter_thread_ep.send(sel4::MessageInfoBuilder::default().label(123).build());
+}
+
+
+
+
+
+
workspaces/root-task/spawn-thread/src/main.rs:81:87 after 6.A
+
+
+
fn interact_with_secondary_thread(inter_thread_ep: sel4::cap::Endpoint) {
+    sel4::debug_println!("In primary thread");
+
+    let (msg_info, _badge) = inter_thread_ep.recv(());
+
+    assert_eq!(msg_info.label(), 123);
+}
+
+
+
+

Step 6.B (exercise)       

+

Exercise: use +sel4::with_ipc_buffer +and +sel4::with_ipc_buffer_mut +to send a message with some data.

+

Step 6.C (exercise)       

+

See seL4 Reference Manual § 4.2.4 (Calling and Replying) for a description of the seL4_Call syscall (Endpoint::call() in Rust).

+

Exercise: Change the

+
inter_thread_ep.send()
+
+

in secondary_thread_main() to

+
inter_thread_ep.call()
+
+

and modify interact_with_secondary_thread() to sel4::reply with a message.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/searcher.js b/projects/rust/tutorial/searcher.js new file mode 100644 index 00000000000..fc65604eb38 --- /dev/null +++ b/projects/rust/tutorial/searcher.js @@ -0,0 +1,529 @@ +'use strict'; + +/* global Mark, elasticlunr, path_to_root */ + +window.search = window.search || {}; +(function search() { + // Search functionality + // + // You can use !hasFocus() to prevent keyhandling in your key + // event handlers while the user is typing their search. + + if (!Mark || !elasticlunr) { + return; + } + + // eslint-disable-next-line max-len + // IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith + if (!String.prototype.startsWith) { + String.prototype.startsWith = function(search, pos) { + return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search; + }; + } + + const search_wrap = document.getElementById('search-wrapper'), + searchbar = document.getElementById('searchbar'), + searchresults = document.getElementById('searchresults'), + searchresults_outer = document.getElementById('searchresults-outer'), + searchresults_header = document.getElementById('searchresults-header'), + searchicon = document.getElementById('search-toggle'), + content = document.getElementById('content'), + + // SVG text elements don't render if inside a tag. + mark_exclude = ['text'], + marker = new Mark(content), + URL_SEARCH_PARAM = 'search', + URL_MARK_PARAM = 'highlight'; + + let current_searchterm = '', + doc_urls = [], + search_options = { + bool: 'AND', + expand: true, + fields: { + title: {boost: 1}, + body: {boost: 1}, + breadcrumbs: {boost: 0}, + }, + }, + searchindex = null, + results_options = { + teaser_word_count: 30, + limit_results: 30, + }, + teaser_count = 0; + + function hasFocus() { + return searchbar === document.activeElement; + } + + function removeChildren(elem) { + while (elem.firstChild) { + elem.removeChild(elem.firstChild); + } + } + + // Helper to parse a url into its building blocks. + function parseURL(url) { + const a = document.createElement('a'); + a.href = url; + return { + source: url, + protocol: a.protocol.replace(':', ''), + host: a.hostname, + port: a.port, + params: (function() { + const ret = {}; + const seg = a.search.replace(/^\?/, '').split('&'); + for (const part of seg) { + if (!part) { + continue; + } + const s = part.split('='); + ret[s[0]] = s[1]; + } + return ret; + })(), + file: (a.pathname.match(/\/([^/?#]+)$/i) || ['', ''])[1], + hash: a.hash.replace('#', ''), + path: a.pathname.replace(/^([^/])/, '/$1'), + }; + } + + // Helper to recreate a url string from its building blocks. + function renderURL(urlobject) { + let url = urlobject.protocol + '://' + urlobject.host; + if (urlobject.port !== '') { + url += ':' + urlobject.port; + } + url += urlobject.path; + let joiner = '?'; + for (const prop in urlobject.params) { + if (Object.prototype.hasOwnProperty.call(urlobject.params, prop)) { + url += joiner + prop + '=' + urlobject.params[prop]; + joiner = '&'; + } + } + if (urlobject.hash !== '') { + url += '#' + urlobject.hash; + } + return url; + } + + // Helper to escape html special chars for displaying the teasers + const escapeHTML = (function() { + const MAP = { + '&': '&', + '<': '<', + '>': '>', + '"': '"', + '\'': ''', + }; + const repl = function(c) { + return MAP[c]; + }; + return function(s) { + return s.replace(/[&<>'"]/g, repl); + }; + })(); + + function formatSearchMetric(count, searchterm) { + if (count === 1) { + return count + ' search result for \'' + searchterm + '\':'; + } else if (count === 0) { + return 'No search results for \'' + searchterm + '\'.'; + } else { + return count + ' search results for \'' + searchterm + '\':'; + } + } + + function formatSearchResult(result, searchterms) { + const teaser = makeTeaser(escapeHTML(result.doc.body), searchterms); + teaser_count++; + + // The ?URL_MARK_PARAM= parameter belongs inbetween the page and the #heading-anchor + const url = doc_urls[result.ref].split('#'); + if (url.length === 1) { // no anchor found + url.push(''); + } + + // encodeURIComponent escapes all chars that could allow an XSS except + // for '. Due to that we also manually replace ' with its url-encoded + // representation (%27). + const encoded_search = encodeURIComponent(searchterms.join(' ')).replace(/'/g, '%27'); + + return '' + + result.doc.breadcrumbs + '' + '' + teaser + ''; + } + + function makeTeaser(body, searchterms) { + // The strategy is as follows: + // First, assign a value to each word in the document: + // Words that correspond to search terms (stemmer aware): 40 + // Normal words: 2 + // First word in a sentence: 8 + // Then use a sliding window with a constant number of words and count the + // sum of the values of the words within the window. Then use the window that got the + // maximum sum. If there are multiple maximas, then get the last one. + // Enclose the terms in . + const stemmed_searchterms = searchterms.map(function(w) { + return elasticlunr.stemmer(w.toLowerCase()); + }); + const searchterm_weight = 40; + const weighted = []; // contains elements of ["word", weight, index_in_document] + // split in sentences, then words + const sentences = body.toLowerCase().split('. '); + let index = 0; + let value = 0; + let searchterm_found = false; + for (const sentenceindex in sentences) { + const words = sentences[sentenceindex].split(' '); + value = 8; + for (const wordindex in words) { + const word = words[wordindex]; + if (word.length > 0) { + for (const searchtermindex in stemmed_searchterms) { + if (elasticlunr.stemmer(word).startsWith( + stemmed_searchterms[searchtermindex]) + ) { + value = searchterm_weight; + searchterm_found = true; + } + } + weighted.push([word, value, index]); + value = 2; + } + index += word.length; + index += 1; // ' ' or '.' if last word in sentence + } + index += 1; // because we split at a two-char boundary '. ' + } + + if (weighted.length === 0) { + return body; + } + + const window_weight = []; + const window_size = Math.min(weighted.length, results_options.teaser_word_count); + + let cur_sum = 0; + for (let wordindex = 0; wordindex < window_size; wordindex++) { + cur_sum += weighted[wordindex][1]; + } + window_weight.push(cur_sum); + for (let wordindex = 0; wordindex < weighted.length - window_size; wordindex++) { + cur_sum -= weighted[wordindex][1]; + cur_sum += weighted[wordindex + window_size][1]; + window_weight.push(cur_sum); + } + + let max_sum_window_index = 0; + if (searchterm_found) { + let max_sum = 0; + // backwards + for (let i = window_weight.length - 1; i >= 0; i--) { + if (window_weight[i] > max_sum) { + max_sum = window_weight[i]; + max_sum_window_index = i; + } + } + } else { + max_sum_window_index = 0; + } + + // add around searchterms + const teaser_split = []; + index = weighted[max_sum_window_index][2]; + for (let i = max_sum_window_index; i < max_sum_window_index + window_size; i++) { + const word = weighted[i]; + if (index < word[2]) { + // missing text from index to start of `word` + teaser_split.push(body.substring(index, word[2])); + index = word[2]; + } + if (word[1] === searchterm_weight) { + teaser_split.push(''); + } + index = word[2] + word[0].length; + teaser_split.push(body.substring(word[2], index)); + if (word[1] === searchterm_weight) { + teaser_split.push(''); + } + } + + return teaser_split.join(''); + } + + function init(config) { + results_options = config.results_options; + search_options = config.search_options; + doc_urls = config.doc_urls; + searchindex = elasticlunr.Index.load(config.index); + + // Set up events + searchicon.addEventListener('click', () => { + searchIconClickHandler(); + }, false); + searchbar.addEventListener('keyup', () => { + searchbarKeyUpHandler(); + }, false); + document.addEventListener('keydown', e => { + globalKeyHandler(e); + }, false); + // If the user uses the browser buttons, do the same as if a reload happened + window.onpopstate = () => { + doSearchOrMarkFromUrl(); + }; + // Suppress "submit" events so the page doesn't reload when the user presses Enter + document.addEventListener('submit', e => { + e.preventDefault(); + }, false); + + // If reloaded, do the search or mark again, depending on the current url parameters + doSearchOrMarkFromUrl(); + + // Exported functions + config.hasFocus = hasFocus; + } + + function unfocusSearchbar() { + // hacky, but just focusing a div only works once + const tmp = document.createElement('input'); + tmp.setAttribute('style', 'position: absolute; opacity: 0;'); + searchicon.appendChild(tmp); + tmp.focus(); + tmp.remove(); + } + + // On reload or browser history backwards/forwards events, parse the url and do search or mark + function doSearchOrMarkFromUrl() { + // Check current URL for search request + const url = parseURL(window.location.href); + if (Object.prototype.hasOwnProperty.call(url.params, URL_SEARCH_PARAM) + && url.params[URL_SEARCH_PARAM] !== '') { + showSearch(true); + searchbar.value = decodeURIComponent( + (url.params[URL_SEARCH_PARAM] + '').replace(/\+/g, '%20')); + searchbarKeyUpHandler(); // -> doSearch() + } else { + showSearch(false); + } + + if (Object.prototype.hasOwnProperty.call(url.params, URL_MARK_PARAM)) { + const words = decodeURIComponent(url.params[URL_MARK_PARAM]).split(' '); + marker.mark(words, { + exclude: mark_exclude, + }); + + const markers = document.querySelectorAll('mark'); + const hide = () => { + for (let i = 0; i < markers.length; i++) { + markers[i].classList.add('fade-out'); + window.setTimeout(() => { + marker.unmark(); + }, 300); + } + }; + + for (let i = 0; i < markers.length; i++) { + markers[i].addEventListener('click', hide); + } + } + } + + // Eventhandler for keyevents on `document` + function globalKeyHandler(e) { + if (e.altKey || + e.ctrlKey || + e.metaKey || + e.shiftKey || + e.target.type === 'textarea' || + e.target.type === 'text' || + !hasFocus() && /^(?:input|select|textarea)$/i.test(e.target.nodeName) + ) { + return; + } + + if (e.key === 'Escape') { + e.preventDefault(); + searchbar.classList.remove('active'); + setSearchUrlParameters('', + searchbar.value.trim() !== '' ? 'push' : 'replace'); + if (hasFocus()) { + unfocusSearchbar(); + } + showSearch(false); + marker.unmark(); + } else if (!hasFocus() && (e.key === 's' || e.key === '/')) { + e.preventDefault(); + showSearch(true); + window.scrollTo(0, 0); + searchbar.select(); + } else if (hasFocus() && (e.key === 'ArrowDown' + || e.key === 'Enter')) { + e.preventDefault(); + const first = searchresults.firstElementChild; + if (first !== null) { + unfocusSearchbar(); + first.classList.add('focus'); + if (e.key === 'Enter') { + window.location.assign(first.querySelector('a')); + } + } + } else if (!hasFocus() && (e.key === 'ArrowDown' + || e.key === 'ArrowUp' + || e.key === 'Enter')) { + // not `:focus` because browser does annoying scrolling + const focused = searchresults.querySelector('li.focus'); + if (!focused) { + return; + } + e.preventDefault(); + if (e.key === 'ArrowDown') { + const next = focused.nextElementSibling; + if (next) { + focused.classList.remove('focus'); + next.classList.add('focus'); + } + } else if (e.key === 'ArrowUp') { + focused.classList.remove('focus'); + const prev = focused.previousElementSibling; + if (prev) { + prev.classList.add('focus'); + } else { + searchbar.select(); + } + } else { // Enter + window.location.assign(focused.querySelector('a')); + } + } + } + + function showSearch(yes) { + if (yes) { + search_wrap.classList.remove('hidden'); + searchicon.setAttribute('aria-expanded', 'true'); + } else { + search_wrap.classList.add('hidden'); + searchicon.setAttribute('aria-expanded', 'false'); + const results = searchresults.children; + for (let i = 0; i < results.length; i++) { + results[i].classList.remove('focus'); + } + } + } + + function showResults(yes) { + if (yes) { + searchresults_outer.classList.remove('hidden'); + } else { + searchresults_outer.classList.add('hidden'); + } + } + + // Eventhandler for search icon + function searchIconClickHandler() { + if (search_wrap.classList.contains('hidden')) { + showSearch(true); + window.scrollTo(0, 0); + searchbar.select(); + } else { + showSearch(false); + } + } + + // Eventhandler for keyevents while the searchbar is focused + function searchbarKeyUpHandler() { + const searchterm = searchbar.value.trim(); + if (searchterm !== '') { + searchbar.classList.add('active'); + doSearch(searchterm); + } else { + searchbar.classList.remove('active'); + showResults(false); + removeChildren(searchresults); + } + + setSearchUrlParameters(searchterm, 'push_if_new_search_else_replace'); + + // Remove marks + marker.unmark(); + } + + // Update current url with ?URL_SEARCH_PARAM= parameter, remove ?URL_MARK_PARAM and + // `#heading-anchor`. `action` can be one of "push", "replace", + // "push_if_new_search_else_replace" and replaces or pushes a new browser history item. + // "push_if_new_search_else_replace" pushes if there is no `?URL_SEARCH_PARAM=abc` yet. + function setSearchUrlParameters(searchterm, action) { + const url = parseURL(window.location.href); + const first_search = !Object.prototype.hasOwnProperty.call(url.params, URL_SEARCH_PARAM); + + if (searchterm !== '' || action === 'push_if_new_search_else_replace') { + url.params[URL_SEARCH_PARAM] = searchterm; + delete url.params[URL_MARK_PARAM]; + url.hash = ''; + } else { + delete url.params[URL_MARK_PARAM]; + delete url.params[URL_SEARCH_PARAM]; + } + // A new search will also add a new history item, so the user can go back + // to the page prior to searching. A updated search term will only replace + // the url. + if (action === 'push' || action === 'push_if_new_search_else_replace' && first_search ) { + history.pushState({}, document.title, renderURL(url)); + } else if (action === 'replace' || + action === 'push_if_new_search_else_replace' && + !first_search + ) { + history.replaceState({}, document.title, renderURL(url)); + } + } + + function doSearch(searchterm) { + // Don't search the same twice + if (current_searchterm === searchterm) { + return; + } else { + current_searchterm = searchterm; + } + + if (searchindex === null) { + return; + } + + // Do the actual search + const results = searchindex.search(searchterm, search_options); + const resultcount = Math.min(results.length, results_options.limit_results); + + // Display search metrics + searchresults_header.innerText = formatSearchMetric(resultcount, searchterm); + + // Clear and insert results + const searchterms = searchterm.split(' '); + removeChildren(searchresults); + for (let i = 0; i < resultcount ; i++) { + const resultElem = document.createElement('li'); + resultElem.innerHTML = formatSearchResult(results[i], searchterms); + searchresults.appendChild(resultElem); + } + + // Display results + showResults(true); + } + + function loadScript(url, id) { + const script = document.createElement('script'); + script.src = url; + script.id = id; + script.onload = () => init(window.search); + script.onerror = error => { + console.error(`Failed to load \`${url}\`: ${error}`); + }; + document.head.append(script); + } + + loadScript(path_to_root + 'searchindex.js', 'search-index'); + +})(window.search); diff --git a/projects/rust/tutorial/searchindex.js b/projects/rust/tutorial/searchindex.js new file mode 100644 index 00000000000..a93f33bddf1 --- /dev/null +++ b/projects/rust/tutorial/searchindex.js @@ -0,0 +1 @@ +window.search = JSON.parse('{"doc_urls":["introduction.html#tutorial-using-rust-in-sel4-userspace","setup.html#setup","setup.html#docker","setup.html#two-workspaces","setup.html#vscode--dev-containers","setup.html#rustdoc","root-task/index.html#the-root-task","root-task/hello-world.html#hello-world","root-task/hello-world.html#step-2a-exercise","root-task/hello-world.html#step-2b-exercise","root-task/hello-world.html#step-2c-exercise","root-task/hello-world.html#step-2d-exercise","root-task/hello-world.html#step-2e-exercise","root-task/hello-world.html#step-2f-exercise","root-task/hello-world.html#step-2g","root-task/kernel-objects.html#allocating-kernel-objects","root-task/kernel-objects.html#step-3a","root-task/kernel-objects.html#step-3b","root-task/kernel-objects.html#step-3c","root-task/kernel-objects.html#step-3d-exercise","root-task/kernel-objects.html#step-3e-exercise","root-task/kernel-objects.html#step-3f-exercise","root-task/kernel-objects.html#step-3g-exercise","root-task/address-space.html#modifying-the-address-space","root-task/address-space.html#step-4a-exercise","root-task/address-space.html#step-4b","root-task/address-space.html#step-4c","root-task/address-space.html#step-4d-exercise","root-task/serial-device.html#using-a-serial-device","root-task/serial-device.html#step-5a","root-task/serial-device.html#step-5b-exercise","root-task/serial-device.html#step-5c","root-task/serial-device.html#step-5d","root-task/serial-device.html#step-5e-exercise","root-task/serial-device.html#step-5f-exercise","root-task/serial-device.html#step-5g-exercise","root-task/serial-device.html#step-5h-exercise","root-task/spawn-thread.html#spawning-a-thread","root-task/spawn-thread.html#step-6a","root-task/spawn-thread.html#step-6b-exercise","root-task/spawn-thread.html#step-6c-exercise","root-task/spawn-task.html#spawning-a-task-challenge","root-task/spawn-task.html#step-7a","root-task/spawn-task.html#step-7b","root-task/spawn-task.html#step-7c","root-task/spawn-task.html#step-7d","root-task/spawn-task.html#step-7e-challenge","microkit/index.html#sel4-microkit","microkit/hello-world.html#hello-world","microkit/hello-world.html#the-event-handler","microkit/hello-world.html#language-runtime","microkit/ipc.html#ipc","microkit/ipc.html#step-10a-exercise","microkit/shared-memory.html#shared-memory","microkit/shared-memory.html#step-11a","microkit/shared-memory.html#step-11b"],"index":{"documentStore":{"docInfo":{"0":{"body":90,"breadcrumbs":6,"title":5},"1":{"body":107,"breadcrumbs":2,"title":1},"10":{"body":15,"breadcrumbs":5,"title":3},"11":{"body":4,"breadcrumbs":5,"title":3},"12":{"body":40,"breadcrumbs":5,"title":3},"13":{"body":49,"breadcrumbs":5,"title":3},"14":{"body":41,"breadcrumbs":4,"title":2},"15":{"body":172,"breadcrumbs":6,"title":3},"16":{"body":142,"breadcrumbs":5,"title":2},"17":{"body":41,"breadcrumbs":5,"title":2},"18":{"body":332,"breadcrumbs":5,"title":2},"19":{"body":7,"breadcrumbs":6,"title":3},"2":{"body":45,"breadcrumbs":2,"title":1},"20":{"body":116,"breadcrumbs":6,"title":3},"21":{"body":12,"breadcrumbs":6,"title":3},"22":{"body":8,"breadcrumbs":6,"title":3},"23":{"body":148,"breadcrumbs":6,"title":3},"24":{"body":27,"breadcrumbs":6,"title":3},"25":{"body":64,"breadcrumbs":5,"title":2},"26":{"body":104,"breadcrumbs":5,"title":2},"27":{"body":30,"breadcrumbs":6,"title":3},"28":{"body":81,"breadcrumbs":6,"title":3},"29":{"body":43,"breadcrumbs":5,"title":2},"3":{"body":64,"breadcrumbs":3,"title":2},"30":{"body":92,"breadcrumbs":6,"title":3},"31":{"body":116,"breadcrumbs":5,"title":2},"32":{"body":28,"breadcrumbs":5,"title":2},"33":{"body":53,"breadcrumbs":6,"title":3},"34":{"body":95,"breadcrumbs":6,"title":3},"35":{"body":10,"breadcrumbs":6,"title":3},"36":{"body":46,"breadcrumbs":6,"title":3},"37":{"body":116,"breadcrumbs":4,"title":2},"38":{"body":262,"breadcrumbs":4,"title":2},"39":{"body":7,"breadcrumbs":5,"title":3},"4":{"body":62,"breadcrumbs":4,"title":3},"40":{"body":21,"breadcrumbs":5,"title":3},"41":{"body":194,"breadcrumbs":6,"title":3},"42":{"body":101,"breadcrumbs":5,"title":2},"43":{"body":41,"breadcrumbs":5,"title":2},"44":{"body":21,"breadcrumbs":5,"title":2},"45":{"body":9,"breadcrumbs":5,"title":2},"46":{"body":121,"breadcrumbs":6,"title":3},"47":{"body":40,"breadcrumbs":3,"title":2},"48":{"body":56,"breadcrumbs":4,"title":2},"49":{"body":48,"breadcrumbs":4,"title":2},"5":{"body":49,"breadcrumbs":2,"title":1},"50":{"body":24,"breadcrumbs":4,"title":2},"51":{"body":182,"breadcrumbs":2,"title":1},"52":{"body":53,"breadcrumbs":4,"title":3},"53":{"body":280,"breadcrumbs":4,"title":2},"54":{"body":66,"breadcrumbs":4,"title":2},"55":{"body":89,"breadcrumbs":4,"title":2},"6":{"body":137,"breadcrumbs":3,"title":2},"7":{"body":150,"breadcrumbs":4,"title":2},"8":{"body":3,"breadcrumbs":5,"title":3},"9":{"body":5,"breadcrumbs":5,"title":3}},"docs":{"0":{"body":"seL4 has official support for Rust in userspace, funded by the seL4 Foundation: https://github.com/seL4/rust-sel4 The exports of this project covered in this tutorial are: Rust bindings for the seL4 API A runtime for root tasks Rust bindings for the seL4 Microkit API A runtime for seL4 Microkit protection domains Custom rustc target specifications for seL4 userspace Part I covers the Rust bindings for the seL4 API and the runtime for root tasks. Familiarity with the seL4 API isn\'t necessarily assumed or required, but this text doesn\'t introduce its elements in as much detail as the seL4 Manual . Part II is much shorter, and covers the Rust language runtime for seL4 Microkit protection domains and implementation of the Microkit API. This part does assume that the reader is familiar with the basics of the Microkit framework and API, or is using a companion resource to learn about the Microkit in parallel.","breadcrumbs":"Introduction » Tutorial: Using Rust in seL4 Userspace","id":"0","title":"Tutorial: Using Rust in seL4 Userspace"},"1":{"body":"This tutorial is presented as a linear series of patches to https://github.com/seL4/seL4-rust-tutorial-code , starting at commit 8ca0e1939dc1, and ending with commit 5253edc1ed12. Each patch, or step, as we shall call them, is an instructive modification to a code example. You are encouraged (but by no means required) to attempt those marked as exercises in this text on your own. Note that while most step patches include tests, the reader is not expected to write tests for exercises themselves. Clone the repository and checkout the starting commit: git clone https://github.com/seL4/seL4-rust-tutorial-code\\ncd seL4-rust-tutorial-code\\ngit checkout 8ca0e1939dc1 Observe the steps ahead: git log 8ca0e1939dc1..5253edc1ed12 Each step header contains two icons. Clicking the clipboard copies the commit hash corresponding to the step to the clipboard. The GitHub icon is a link to the commit on GitHub. Use any Git workflow that works for you. For example, you could cherry-pick the steps that are not marked as exercises after examining and understanding them, and then attempt the exercises on your own, using those step commits as hints when necessary.","breadcrumbs":"Setup » Setup","id":"1","title":"Setup"},"10":{"body":"You can set a custom panic hook with sel4_root_task::panicking::PanicHook . The default hook just prints the panic\'s ExternalPanicInfo. Exercise: Set a custom panic hook.","breadcrumbs":"Hello, World! » Step 2.C (exercise)","id":"10","title":"Step 2.C (exercise)"},"11":{"body":"Exercise: Cause a stack overflow.","breadcrumbs":"Hello, World! » Step 2.D (exercise)","id":"11","title":"Step 2.D (exercise)"},"12":{"body":"The #[root_task] attribute macro accepts a named stack_size parameter, which can be any expression of type usize and whose value is interpreted as the root task\'s initial thread\'s stack size, in bytes. For example: #[root_task(stack_size = 13 * 37)] The default stack size is sel4_root_task::DEFAULT_STACK_SIZE . Exercise: Adjust the root task\'s initial thread\'s stack size to prevent the stack overflow you just caused.","breadcrumbs":"Hello, World! » Step 2.E (exercise)","id":"12","title":"Step 2.E (exercise)"},"13":{"body":"By default, the sel4_root_task runtime does not include a heap. Any attempt to use the alloc crate will result in a link-time failure. The #[root_task] attribute macro accepts a heap_size parameter, which can be any expression of type usize and whose value is interpreted as the root task\'s heap size, in bytes. Note that heap_size must come after stack_size in the case where both are present. For example: #[root_task(heap_size = 0xf00d)] or #[root_task(stack_size = 13 * 37, heap_size = 0xf00d)] Exercise: Add a heap and use it.","breadcrumbs":"Hello, World! » Step 2.F (exercise)","id":"13","title":"Step 2.F (exercise)"},"14":{"body":"The sel4_logging crate builds on top of the log crate to add utilities for initializing simple loggers in minimal environments, such as a seL4 root task. This step demonstrates one way to initialize a logger using this crate: hello-world/src/main.rs:17:20 after 2.G static LOGGER: Logger = LoggerBuilder::const_default() .level_filter(LevelFilter::Info) .write(|s| sel4::debug_print!(\\"{}\\", s)) .build(); hello-world/src/main.rs:41 after 2.G LOGGER.set().unwrap();","breadcrumbs":"Hello, World! » Step 2.G","id":"14","title":"Step 2.G"},"15":{"body":"Start by navigating to and running this chapter\'s example, which, so far, is empty. cd workspaces/root-task/kernel-objects\\nmake simulate Userspace operates the seL4 kernel by creating, managing, and accessing kernel objects via references called capabilites . See seL4 Reference Manual § 2.3 (Kernel Objects) for an outline of the core types of kernel objects. In the context of seL4, a capability is a granular, unforgeable token of authority that references a kernel object and carries access rights that limit what the user of a cabability can do with the referenced kernel object. In general, a system call in seL4 amounts to refering to a cabability and an action on the kernel object the cabability points to. This is called invoking a capability . Just as each thread is associated with a virtual address space which the hardware uses to translate virtual memory addresses into locations in physical memory, each seL4 thread is also assocated with a capability space ( CSpace ) which the kernel uses to translate so-called capability pointers ( CPointers or CPtrs ) into locations (slots) in the kernel\'s capability tables called CNodes . The sel4::CPtr type is a wrapper around a machine word. The sel4::Cap type wraps a CPtr associated with the current thread\'s CSpace, and thus points to a particular capability slot within the kernel. It is paramterized by a capability type T: sel4::CapType , representing the type of capability in that slot. It is up to the crate user to ensure that Cap\'s are valid and well-typed in the current thread. The sel4::cap module contains aliases of the form sel4::Cap. Depending on the Cap\'s type T, a Cap has a number of methods available, which correspond to invocations for that capability type. For example, sel4::Cap::tcb_resume() is available when T is sel4::cap_type::Tcb .","breadcrumbs":"Allocating Kernel Objects » Allocating Kernel Objects","id":"15","title":"Allocating Kernel Objects"},"16":{"body":"As elaborated in seL4 Reference Manual § 2.4 (Kernel Memory Allocation) , userspace is responsible for managing the memory associated with kernel objects. Untyped memory is the name of the object type for free memory. At boot time, the root task is granted untyped memory capabilities for all of the system\'s memory, except for the memory used for the kernel and the root task\'s own resources. Print the untyped memory described by the BootInfo frame : workspaces/root-task/kernel-objects/src/main.rs:14:22 after 3.A sel4::debug_println!(\\"untyped:\\"); for ut_desc in bootinfo.untyped_list() { sel4::debug_println!( \\" paddr: {:#016x?}, size bits: {:02?}, is device: {:?}\\", ut_desc.paddr(), ut_desc.size_bits(), ut_desc.is_device() ); } Sample output: untyped: paddr: 0x00000000000000, size bits: 27, is device: true paddr: 0x00000008001000, size bits: 12, is device: true paddr: 0x00000008002000, size bits: 13, is device: true paddr: 0x00000008004000, size bits: 14, is device: true paddr: 0x00000008008000, size bits: 15, is device: true paddr: 0x00000008011000, size bits: 12, is device: true paddr: 0x00000008012000, size bits: 13, is device: true ... sel4::UntypedDesc::size_bits() returns the log base 2 of the size of the region of memory described by the descriptor. sel4::UntypedDesc::is_device() returns whether the region is device memory or kernel memory. Device memory can only be used for creating frames, whereas kernel memory has no such restrictions.","breadcrumbs":"Allocating Kernel Objects » Step 3.A","id":"16","title":"Step 3.A"},"17":{"body":"Add a function that finds the largest untyped region passed to the root task: workspaces/root-task/kernel-objects/src/main.rs:32:42 after 3.B fn find_largest_kernel_untyped(bootinfo: &sel4::BootInfo) -> sel4::cap::Untyped { let (ut_ix, _desc) = bootinfo .untyped_list() .iter() .enumerate() .filter(|(_i, desc)| !desc.is_device()) .max_by_key(|(_i, desc)| desc.size_bits()) .unwrap(); bootinfo.untyped().index(ut_ix).cap()\\n} The expression bootinfo.untyped().index(ut_ix).cap() indexes into bootinfo.untyped(): SlotRegion to retrieve a Slot, which can be turned into a Cap (= cap::Untyped).","breadcrumbs":"Allocating Kernel Objects » Step 3.B","id":"17","title":"Step 3.B"},"18":{"body":"In this step, we will allocate a Notification object. We already know how to refer to a capability in the current thread\'s CSpace: a CPtr. However, some capability invocations allow us to refer to a capability slot in any CSpace whose root CNode is present in the current thread\'s CSpace. In these cases, we must provide: A CPtr, interpreted in the context of the current thread\'s CSpace, which points to the target CSpace\'s root CNode A CPtr, interpreted in the context of the target CSpace, which points to the target capability slot A depth, which is the number of bits of the second CPtr to interpret. This allows for the second CPtr to point to a CNode. Why this is necessary is outside the scope of this tutorial, but you can read about it in seL4 Reference Manual § 2.4 (CSpace Addressing) . Consider, for example, the seL4_CNode_Mint capability invocation. dest_* and src_* are both capability slots addressed in this way. This more flexible method of capability slot addressing is encapsulated in the sel4::AbsoluteCPtr type. The seL4_Untyped_Retype method is used for allocating new objects from an untyped object. The _service parameter is the address of the untyped object as a normal CPtr. root, node_index, and node_depth address, in the more flexible way outlined above, the destination CNode into which capabilities for the new objects will be inserted. node_offset and num_objects specify a range of slots within the selected CNode for the new capabilites (and, simultaneously, the number of new objects that will be created). type and size_bits specify the shape of the new object(s) Note that size_bits is relevant for only certain object types (see seL4 Reference Manual § 2.4.2 (Summary of Object Sizes) for more information). This shape information is encapsulated in the sel4::ObjectBlueprint type. Multiple kernel objects can be allocated from a single unytped object. For each untyped object, the kernel maintains a watermark which tracks how much of the untyped object has been used up for object allocation. seL4_Untyped_Retype aligns the watermark to the desired object type\'s size, and then advances it according to the object type size and number of objects. This process is detailed in the fourth paragraph of seL4 Reference Manual § 2.4.1 (Reusing Memory) . Let us now work towards calling sel4::cap::Untyped::untyped_retype() on our previously acquired largest_kernel_ut. We wish to allocate one notification object and insert a capability for it into a free slot in the current thread\'s own CSpace. More precisely, we need a sel4::AbsoluteCPtr for the current thread\'s own CSpace\'s root CNode, and an index into that CNode for a free slot. The CPtr for the initial thread\'s own CSpace root is a constant: workspaces/root-task/kernel-objects/src/main.rs:27:27 after 3.C let cnode = sel4::init_thread::slot::CNODE.cap(); bootinfo can tell us about a range of empty slots in this CSpace. We can leverage the fact that Rust\'s Range type is an iterator for certain T to allocate slots in an ergonomic way: workspaces/root-task/kernel-objects/src/main.rs:29:33 after 3.C let mut empty_slots = bootinfo .empty() .range() .map(sel4::init_thread::Slot::from_index); let notification_slot = empty_slots.next().unwrap(); The {{#rustdoc_link root-task sel4/cap/type.CNode.html#method.absolute_cptr_for_selfsel4::cap::CNode::absolute_cptr_for_self()}} method elaborates a sel4::cap::Cnode into a sel4::AbsoluteCPtr. Interestingly, there are two ways to do this, but the current implementation is just to use a depth of zero. Now we can invoke our untyped capability to allocate a notification object: workspaces/root-task/kernel-objects/src/main.rs:36:43 after 3.C largest_kernel_ut .untyped_retype( &sel4::ObjectBlueprint::Notification, &cnode.absolute_cptr_for_self(), notification_slot.index(), 1, ) .unwrap(); Now that we know that notification_slot contains a notification capability, we can cast it and get a sel4::cap::Notification : workspaces/root-task/kernel-objects/src/main.rs:45:47 after 3.C let notification = notification_slot .downcast::() .cap();","breadcrumbs":"Allocating Kernel Objects » Step 3.C","id":"18","title":"Step 3.C"},"19":{"body":"Exercise: : Use sel4::cap::Notification::signal() and sel4::cap::Notification::wait() to signal and then wait on the notification.","breadcrumbs":"Allocating Kernel Objects » Step 3.D (exercise)","id":"19","title":"Step 3.D (exercise)"},"2":{"body":"We will work inside of a Docker container built with docker/Dockerfile . This Dockerfile installs some build-time dependencies, and then builds seL4, seL4 Microkit , and some additional programs and tools. Build the image: make -C docker build Run a container in the background: make -C docker run Start a shell inside the container: make -C docker exec The rest of this text assumes that you are in a shell inside the container.","breadcrumbs":"Setup » Docker","id":"2","title":"Docker"},"20":{"body":"As described in seL4 Reference Manual § 5 (Notifications) , a notification capability can contain a word-sized mask called a badge. When that capability is used to signal the notification, the notification\'s word-sized state is bit-wise ored with the capability\'s badge. A wait call on the notification returns and clears the notification\'s state, provided that a signal call has occurred since the last wait call. sel4::AbsoluteCPtr::mint() mints a new capability from an existing capability, updatings its access rights and badge. Exercise: : Allocate a new empty slot in the current CNode. A slot in the root task\'s CSpace (i.e. a value of type sel4::init_thread::Slot ) can be turned into an sel4::AbsoluteCPtr using {{#rustdoc_link root-task sel4/cap/type.CNode.html#method.absolute_cptrsel4::CNode::absolute_cptr()}}: workspaces/root-task/kernel-objects/src/main.rs:63:63 after 3.E &cnode.absolute_cptr(notification_slot.cptr()), Exercise: : Mint a capability based on the capability in notification_slot into your newly allocated slot. Use sel4::CapRights::all() for the rights parameter, and specify a non-zero badge value. Exercise: : Signal the notification using your newly minted badged capability. Using the return value of sel4::Notification::wait(), compare the badge value it returns with the badge you used to mint the capability.","breadcrumbs":"Allocating Kernel Objects » Step 3.E (exercise)","id":"20","title":"Step 3.E (exercise)"},"21":{"body":"Exercise: : sel4::CapRights::all() is overly-permissive. Use the overly-restrictive sel4::CapRights::none() instead and watch the program fail.","breadcrumbs":"Allocating Kernel Objects » Step 3.F (exercise)","id":"21","title":"Step 3.F (exercise)"},"22":{"body":"Exercise: : Now use the minimum rights necessary for the program to run.","breadcrumbs":"Allocating Kernel Objects » Step 3.G (exercise)","id":"22","title":"Step 3.G (exercise)"},"23":{"body":"This chapter will focus on using the seL4 virtual address space (VSpace) APIs to manipulate the root task\'s own address space. Start by navigating to and running this chapter\'s example, which, so far, is empty. cd workspaces/root-task/address-space\\nmake simulate In seL4, each thread is associated with a virtual address space (VSpace). A VSpace is comprised of a tree of translation tables mapping virtual addresses into physical frames of memory. VSpaces are represented by their root translation structures. While the high-level virtual address space API concepts are architecture-independent, the specific kernel object types for a given architecture mirror that architecture\'s paging structures. That said, all architectures share two object types: The top-level paging structure, called a VSpace, which is used to represent a virtual address space. In the sel4 crate , the corresponding sel4::CapType is sel4::cap_type::VSpace (note that, for some architectures, this is a type alias). Frames of physical memory. The set of possible frames sizes is architecture-dependant. See seL4 Reference Manual § 7.1.3 (Page) . In the sel4 crate , sel4::cap_type::Granule is an alias for the sel4::CapType corresponding to the smallest frame object type. The root task is provided with capabilites for the objects comprising its own virtual address space. The locations of these capabilities in the root task\'s CSpace is provided in the BootInfo struct. Our goal for this chapter will be to create a frame object and experiment with mapping it into the root task\'s own address space.","breadcrumbs":"Modifying the Address Space » Modifying the Address Space","id":"23","title":"Modifying the Address Space"},"24":{"body":"Exercise: Using code snippets from Chapter 3 (Allocating Kernel Objects) , create a frame object. We seek a value frame: sel4::cap::Granule (which can also be written as frame: sel4::Cap). Note that, after importing the sel4::CapTypeForObjectOfFixedSize trait, you can express the appropriate sel4::ObjectBlueprint as sel4::cap_type::Granule::object_blueprint().","breadcrumbs":"Modifying the Address Space » Step 4.A (exercise)","id":"24","title":"Step 4.A (exercise)"},"25":{"body":"In order to avoid interacting with intermediate translation structures, let\'s reserve an aligned granule-sized region in the root task\'s program image that we can use for our experiment: workspaces/root-task/address-space/src/main.rs:15:20 after 4.B const GRANULE_SIZE: usize = sel4::FrameObjectType::GRANULE.bytes(); // 4096 #[repr(C, align(4096))]\\nstruct PagePlaceholder(#[allow(dead_code)] [u8; GRANULE_SIZE]); static mut PAGE_A: PagePlaceholder = PagePlaceholder([0xee; GRANULE_SIZE]); workspaces/root-task/address-space/src/main.rs:46:49 after 4.B let page_a_addr = ptr::addr_of!(PAGE_A).cast::(); sel4::debug_println!(\\"PAGE_A: {page_a_addr:#x?}\\"); assert_eq!(page_a_addr as usize % GRANULE_SIZE, 0); assert_eq!(unsafe { page_a_addr.read() }, 0xee); This reservation covers exactly one page in the root task\'s virtual address space.","breadcrumbs":"Modifying the Address Space » Step 4.B","id":"25","title":"Step 4.B"},"26":{"body":"Let\'s unmap the page in the root task image that initially backs our reserved region. This will give us a hole in the root task VSpace, which we can use for our experiment. This function determines the slot in the root task\'s CSpace of the page capability corresponding to the page in the root task\'s VSpace which contains the given address: workspaces/root-task/address-space/src/main.rs:73:84 after 4.C fn get_user_image_frame_slot( bootinfo: &sel4::BootInfo, addr: usize,\\n) -> sel4::init_thread::Slot { extern \\"C\\" { static __executable_start: usize; } let user_image_addr = ptr::addr_of!(__executable_start) as usize; bootinfo .user_image_frames() .index(addr / GRANULE_SIZE - user_image_addr / GRANULE_SIZE)\\n} __executable_start is defined by the linker. We can use it, along with addr, to identify the offset into bootinfo.user_image_frames() of the capability we are after. Use the get_user_image_frame_slot() function to find the capability corresponding to the frame backing our reserved region, and unmap that frame, leaving a hole in the root task\'s virtual address space. Try to access that region, and observe a page fault: workspaces/root-task/address-space/src/main.rs:51:54 after 4.C let page_a_slot = get_user_image_frame_slot(bootinfo, page_a_addr as usize); page_a_slot.cap().frame_unmap().unwrap(); unsafe { page_a_addr.read() };","breadcrumbs":"Modifying the Address Space » Step 4.C","id":"26","title":"Step 4.C"},"27":{"body":"Exercise: Map new_frame at page_a_addr using new_frame.frame_map() , which corresponds to seL4_ARM_Page_Map . Here are some hints for the parameters of .frame_map(): vspace: A capability for the root task\'s VSpace can be expressed using sel4::init_thread::slot::VSPACE.cap(). rights: sel4::CapRights::read_write() are the most permissive rights, and will work for our purposes. attrs: sel4::VmAttributes::default() will work here.","breadcrumbs":"Modifying the Address Space » Step 4.D (exercise)","id":"27","title":"Step 4.D (exercise)"},"28":{"body":"In this chapter, we will build a root task that interacts with a serial device. Start by navigating to and running this chapter\'s example, which, so far, doesn\'t do anything interesting. cd workspaces/root-task/serial-device\\nmake simulate The module at device.rs implements a higher-level interface over the serial device\'s MMIO registers, whose physical base address is: workspaces/root-task/serial-device/src/main.rs:16:16 const SERIAL_DEVICE_MMIO_PADDR: usize = 0x0900_0000; Our first goal will be to map the serial device\'s MMIO registers into the root task\'s address space. After that, we will set up the root task\'s access to the serial device\'s interrupt, whose value is: workspaces/root-task/serial-device/src/main.rs:18:18 const SERIAL_DEVICE_IRQ: usize = 33; Finally, we will implement a simple loop that echoes serial input to serial output.","breadcrumbs":"Using a Serial Device » Using a Serial Device","id":"28","title":"Using a Serial Device"},"29":{"body":"First, add some familiar snippets that we will use for allocating CSlots and kernel objects: workspaces/root-task/serial-device/src/main.rs:34:44 after 5.A fn find_largest_kernel_untyped(bootinfo: &sel4::BootInfo) -> sel4::cap::Untyped { let (ut_ix, _desc) = bootinfo .untyped_list() .iter() .enumerate() .filter(|(_i, desc)| !desc.is_device()) .max_by_key(|(_i, desc)| desc.size_bits()) .unwrap(); bootinfo.untyped().index(ut_ix).cap()\\n} workspaces/root-task/serial-device/src/main.rs:22:27 after 5.A let mut empty_slots = bootinfo .empty() .range() .map(sel4::init_thread::Slot::::from_index); let largest_kernel_ut = find_largest_kernel_untyped(bootinfo);","breadcrumbs":"Using a Serial Device » Step 5.A","id":"29","title":"Step 5.A"},"3":{"body":"To simplify our Cargo invocations, this repository\'s Rust code has been divided between two distinct workspaces: workspaces/root-task and workspaces/microkit . Both are subject to the top-level .cargo/config.toml , whereas workspaces/root-task/.cargo/config.toml and workspaces/microkit/.cargo/config.toml each apply to only one. These workspace-specific config.toml files demonstrate all that is required to configure the crates in the rust-sel4 project: An environment variable pointing at libsel4 (which includes the kernel configuration). See the relevant crate docs for information on this environment variable. A reference to a custom rustc target specification (the location of the target specification is given at .cargo/config.toml:8 , which refers to target-specs ).","breadcrumbs":"Setup » Two Workspaces","id":"3","title":"Two Workspaces"},"30":{"body":"largest_kernel_ut will be useful for allocating kernel objects whose backing physical addresses don\'t matter to us, but we must allocate the frame which contains the serial device\'s MMIO registers at a particular physicall address (SERIAL_DEVICE_MMIO_PADDR). Furthermore, the seL4 API distinguishes between general purpose untyped and device untyped . General purpose untyped is backed by normal memory, and can be used to create any type of object. Device untyped is not backed by normal memory, and can only be used to create frames. See the last two paragraphs of seL4 Reference Manual § 2.4 (Kernel Memory Allocation) for more information. So, we must allocate the serial device MMIO frame from the particular initial device untyped that contains SERIAL_DEVICE_MMIO_PADDR. Exercice: Identify this initial untyped in the bootinfo. We will need a corresponding sel4::cap::Untyped along with the untyped\'s physical address (or sel4::UntypedDesc, which contains the physical address) for the next step.","breadcrumbs":"Using a Serial Device » Step 5.B (exercise)","id":"30","title":"Step 5.B (exercise)"},"31":{"body":"The untyped we\'ve identified contains the frame we are targeting, but that frame may be somewhere in the middle of the region of device memory the untyped covers. To allocate the frame at SERIAL_DEVICE_MMIO_PADDR, we must allocate dummy objects from this untyped until its watermark is at SERIAL_DEVICE_MMIO_PADDR. This trim_untyped function takes the untyped capability, its physical address, the desired physical address, and two empty slots for temporarily holding dummy objects. We need two slots because the kernel resets an untyped\'s watermark if it has no live children. So, we must always keep one child around so that our progress on advancing the watermark is never lost. workspaces/root-task/serial-device/src/main.rs:43:49 after 5.C trim_untyped( device_ut_cap, device_ut_desc.paddr(), SERIAL_DEVICE_MMIO_PADDR, empty_slots.next().unwrap(), empty_slots.next().unwrap(), ); workspaces/root-task/serial-device/src/main.rs:68:97 after 5.C fn trim_untyped( ut: sel4::cap::Untyped, ut_paddr: usize, target_paddr: usize, free_slot_a: sel4::init_thread::Slot, free_slot_b: sel4::init_thread::Slot,\\n) { let rel_a = sel4::init_thread::slot::CNODE .cap() .absolute_cptr(free_slot_a.cptr()); let rel_b = sel4::init_thread::slot::CNODE .cap() .absolute_cptr(free_slot_b.cptr()); let mut cur_paddr = ut_paddr; while cur_paddr != target_paddr { let size_bits = (target_paddr - cur_paddr).ilog2().try_into().unwrap(); ut.untyped_retype( &sel4::ObjectBlueprint::Untyped { size_bits }, &sel4::init_thread::slot::CNODE .cap() .absolute_cptr_for_self(), free_slot_b.index(), 1, ) .unwrap(); rel_a.delete().unwrap(); rel_a.move_(&rel_b).unwrap(); cur_paddr += 1 << size_bits; }\\n}","breadcrumbs":"Using a Serial Device » Step 5.C","id":"31","title":"Step 5.C"},"32":{"body":"device_ut_cap is now primed; the physical address of the next allocation will be SERIAL_DEVICE_MMIO_PADDR. Exercise: Allocate a small frame object (sel4::cap_type::Granule) from device_ut_cap. If your sel4::cap::Granule is called serial_device_frame_cap, then the following assertion should succeed: workspaces/root-task/serial-device/src/main.rs:70:73 after 5.D assert_eq!( serial_device_frame_cap.frame_get_address().unwrap(), SERIAL_DEVICE_MMIO_PADDR );","breadcrumbs":"Using a Serial Device » Step 5.D","id":"32","title":"Step 5.D"},"33":{"body":"Exercise: Using code from Step 4.B , Step 4.C , and Step 4.D , map serial_device_frame_cap into the root task\'s virtual address space. You should now be able interact with the serial device\'s MMIO registers. Try printing \\"Hello, World!\\" to the serial console with something like: workspaces/root-task/serial-device/src/main.rs:102:108 after 5.E let serial_device = unsafe { Device::new(serial_device_mmio_page_addr.cast()) }; serial_device.init(); for c in b\\"Hello, World!\\\\n\\" { serial_device.put_char(*c); } where serial_device_mmio_page_addr: *mut _ is a pointer to where the MMIO registers are mapped in the root task\'s virtual address space.","breadcrumbs":"Using a Serial Device » Step 5.E (exercise)","id":"33","title":"Step 5.E (exercise)"},"34":{"body":"Interrupts are delivered to userspace via notifications. A IRQHandler capability represents the authority to manage a particular interrupt. Specifically, an IRQHandler capability ( sel4::cap::IrqHandler ) has the following methods: seL4_IRQHandler_SetNotification() : Associate the interrupt with the given notification. Userspace can call seL4_Wait() or seL4_Poll() on this notification to receive the interrupt. seL4_IRQHandler_Clear() : Disassociate the notification associated with this interrupts. seL4_IRQHandler_Ack() : Tell the kernel to pass on acknowledgement of this interrupt to the interrupt controller. The Rust bindings for these methods are: sel4::cap::IrqHandler::irq_handler_set_notification() sel4::cap::IrqHandler::irq_handler_clear() sel4::cap::IrqHandler::irq_handler_ack() The root task spawns with a special IRQControl capability ( sel4::cap::IrqControl ) which can be used to create IRQHandler capabilities with seL4_IRQControl_Get() ( sel4::cap::IrqControl::irq_control_get() ). The intent behind this API is that a highly-privileged component will hold an IRQControl capability, which it will use to distribute more finely-grained IRQHandler capabilities to less privileged components for the interrupts they will manage. The root task can access its IRQControl capability with sel4::init_thread::slot::IRQ_CONTROL.cap() Exercise: Use sel4::init_thread::slot::IRQ_CONTROL.cap() to create a sel4::cap::IrqHandler for SERIAL_DEVICE_IRQ.","breadcrumbs":"Using a Serial Device » Step 5.F (exercise)","id":"34","title":"Step 5.F (exercise)"},"35":{"body":"Exercise: Create a notification object from largest_kernel_ut and associate it with the IRQHandler you just created using sel4::cap::IrqHandler::irq_handler_set_notification() .","breadcrumbs":"Using a Serial Device » Step 5.G (exercise)","id":"35","title":"Step 5.G (exercise)"},"36":{"body":"Exercise: Use serial_device: Device, your IRQHandler, and the notification you associated with the interrupt to write a loop that echoes serial input to serial output. Use serial_device.clear_all_interrupts() and irq_handler_cap.irq_handler_ack() in sequence to clear the interrupt at the device and interrupt controller levels respectively. Note that you should do this at the beginning of the loop in case your loop enters with an interrupt already pending. Use irq_notification_cap.wait() to wait for hte interrupt. Use serial_device.get_char() and serial_device.put_char() to read and write data.","breadcrumbs":"Using a Serial Device » Step 5.H (exercise)","id":"36","title":"Step 5.H (exercise)"},"37":{"body":"In this chapter, we will explore IPC through an example that spawns a secondary thread. This example starts with a more interesting program than the other examples we\'ve worked with so far. It spawns a secondary thread, and then interacts with it using a notification. Navigate to and run the example: cd workspaces/root-task/spawn-thread\\nmake simulate Explore main.rs at will. If you\'re used to using seL4_libs , you may notice that our Rust code here is much more low-level and verbose. That is because we aren\'t using any higher-level seL4-related libraries such as . Our code is more like spawning a thread using alone. Note, though, that our code does depend on a few Rust language runtime building block crates such as sel4-initialize-tls and sel4-stack . The exercises in this chapter are only concerned with the following two functions, which run concurrently: workspaces/root-task/spawn-thread/src/main.rs:75:79 fn secondary_thread_main(inter_thread_nfn: sel4::cap::Notification) { sel4::debug_println!(\\"In secondary thread\\"); inter_thread_nfn.signal();\\n} workspaces/root-task/spawn-thread/src/main.rs:81:85 fn interact_with_secondary_thread(inter_thread_nfn: sel4::cap::Notification) { sel4::debug_println!(\\"In primary thread\\"); inter_thread_nfn.wait();\\n} secondary_thread_main() runs in the secondary thread, and interact_with_secondary_thread() runs in the secondary thread.","breadcrumbs":"Spawning a Thread » Spawning a Thread","id":"37","title":"Spawning a Thread"},"38":{"body":"In this step, we introduce IPC between secondary_thread_main() and interact_with_secondary_thread by changing inter_thread_nfn: sel4::cap::Notification to inter_thread_ep: sel4::cap::Endpoint Before, the two sides of the notification communicated via inter_thread_nfn.signal() and inter_thread_nfn.wait() . Now, communication over this IPC endpoint will happen by inter_thread_ep.send() and inter_thread_ep.recv() . As described in seL4 Reference Manual § 4 (Message Passing (IPC)) and seL4 Reference Manual § 4.2 (Endpoints) , a capability for an Endpoint object can be invoked with send() and recv() . send() and recv() block until the two sides of the object rendezvous, at which point a message is passed from the sender to the receiver. This message may contain data and capabilities. Each thread is associated with a special page of memory called an IPC buffer. The sender populates its own IPC buffer with data and/or CPtrs, and then calls send() with a metadata value called the MessageInfo . The kernel copies data from the sender\'s IPC buffer into that of the receiver, and/or capabilities from the sender\'s CSpace into that of the receiver. The kernel uses the MessageInfo to determine how much data to copy between the two IPC buffers (the length field) and how many CPtrs to read from the IPC buffers for copying betwen CSpaces (the caps_unwrapped and extra_caps fields). Finally, the kernel passes the MessageInfo, and control, to the receiver. In Rust, the sender and receiver can interact with their own IPC buffer using sel4::with_ipc_buffer and sel4::with_ipc_buffer_mut . Message data is held in the message registers (an array of machine words), which is a field of the IPC buffer ( msg_regs and msg_regs_mut ). The length field of the MessageInfo specifies how many message registers will be copied into the receiver\'s IPC buffer. One can also view the message registers as an array of bytes using msg_bytes and msg_bytes_mut . In this case, one rounds the length of their message up to the nearest multiple of the machine word size when computing the message length for the MessageInfo. The MessageInfo also includes a few bits of data called a label ( label_width bits wide) that is not interpreted by the kernel. In Rust, the MessageInfoBuilder type is a clear and concise way to construct a MessageInfo . In Rust, to smooth out differences between the mixed-criticality and legacy kernel schedulers, recv() always takes a reply_authority argument. Under legacy scheduler configurations, which is what this text uses, this argument can be of type (). Taking all of this together, let\'s use our IPC endpoint to send an empty message: workspaces/root-task/spawn-thread/src/main.rs:75:79 after 6.A fn secondary_thread_main(inter_thread_ep: sel4::cap::Endpoint) { sel4::debug_println!(\\"In secondary thread\\"); inter_thread_ep.send(sel4::MessageInfoBuilder::default().label(123).build());\\n} workspaces/root-task/spawn-thread/src/main.rs:81:87 after 6.A fn interact_with_secondary_thread(inter_thread_ep: sel4::cap::Endpoint) { sel4::debug_println!(\\"In primary thread\\"); let (msg_info, _badge) = inter_thread_ep.recv(()); assert_eq!(msg_info.label(), 123);\\n}","breadcrumbs":"Spawning a Thread » Step 6.A","id":"38","title":"Step 6.A"},"39":{"body":"Exercise: use sel4::with_ipc_buffer and sel4::with_ipc_buffer_mut to send a message with some data.","breadcrumbs":"Spawning a Thread » Step 6.B (exercise)","id":"39","title":"Step 6.B (exercise)"},"4":{"body":"If you want help from rust-analyzer , the Rust Language Server, you can use VSCode with the Dev Containers extension . This will enable you to run VSCode inside of the container you just built, which contains the seL4 build artifacts that rust-analyzer will require to analyzer your code. This repository provides a separate Dev Container configuration for each workspace: .devcontainer/root-task/devcontainer.json .devcontainer/microkit/devcontainer.json To work in a particular workspace, open this repository in VSCode, run > Dev Containers: Reopen in Container, and select the corresponding configuration. You should now be able to use the rust-analyzer VSCode extension normally for the code in the selected workspace.","breadcrumbs":"Setup » VSCode + Dev Containers","id":"4","title":"VSCode + Dev Containers"},"40":{"body":"See seL4 Reference Manual § 4.2.4 (Calling and Replying) for a description of the seL4_Call syscall ( Endpoint::call() in Rust). Exercise: Change the inter_thread_ep.send() in secondary_thread_main() to inter_thread_ep.call() and modify interact_with_secondary_thread() to sel4::reply with a message.","breadcrumbs":"Spawning a Thread » Step 6.C (exercise)","id":"40","title":"Step 6.C (exercise)"},"41":{"body":"This final chapter of Part I contains a more open-ended and challenging exercise. We start with an example that spawns an entire new process, which, in the context of low-level seL4 userspace, is often called a task : cd workspaces/root-task/spawn-task\\nmake simulate Similarly to what we saw in Chapter 6 (Spawning a Thread) , the code in this example is more low-level and complex compared to what you have seen in code that leverages . Again, our code here is more like spawning a task using alone. This example consists of two programs. The spawn-task crate is the root task, and the spawn-task-child crate is the child task. The child task does not spawn in any standard sort of environment, so is includes its own ad-hoc Rust language runtime in child/src/runtime.rs , complete with thread-local storage, a global heap allocator, and exception handling. This runtime is built using a few Rust langauge runtime building block crates: sel4-runtime-common sel4-initialize-tls sel4-dlmalloc sel4-stack sel4-panicking sel4-panicking-env This minimal, ad-hoc language runtime is a neat, instructive piece of code. It shows how one can build a new Rust language runtime out of the building blocks provided by the rust-sel4 project. Explore the root task and child task . Right now, all the child task does is send a test message over an endpoint back to the root task. The challenge in this chapter, step 7.E , is to extend the root task so that it sets up the child task to be able to interact with the serial device, and to extend the child task to implement the same echo loop as in [./serial-device.html#step-5h]. Steps 7.A , 7.B , 7.C , and 7.D , which are not exercises, make some incremental extensions towards those goals to help you get started.","breadcrumbs":"Spawning a Task (Challenge) » Spawning a Task (Challenge)","id":"41","title":"Spawning a Task (Challenge)"},"42":{"body":"This step extends the ObjectAllocator type in workspaces/root-task/spawn-task/src/object_allocator.rs after 7.B with the recklessly_allocate_at() method. This method allocates an object according to the blueprint parameter at the given physical address paddr. Instead of just allocating the object from the largest kernel untyped like the allocate() method does, this method searches through the bootinfo to find the initial untyped capability whose corresponding untyped object contains paddr, allocates dummy objects from this untyped object until its watermark reaches paddr, and then allocates the desired object. recklessly_allocate_at()\'s procedure is similar to that which we followed in step 5.C . This implementation is \\"reckless\\" because it modifies the state of the untyped capability it allocates from (allocating from it and changing its watermark) without keeping track of having done so. So, subsequent calls for paddrs contained in the same initial untyped would fail or, worse, misbehave. However, we expect to only need to call it once, so we are okay with this caveat. In step 7.E , you be able to use this method to allocate the serial device MMIO register frame.","breadcrumbs":"Spawning a Task (Challenge) » Step 7.A","id":"42","title":"Step 7.A"},"43":{"body":"This step extends the create_child_vspace() function in workspaces/root-task/spawn-task/src/child_vspace.rs after 7.A to take an extra_frames parameter. create_child_vspace() now maps these extra frames into the child task\'s address space, after the end of the program image, and after the IPC buffer frame. In step 7.E , you be able to use this parameter to pass in the serial device MMIO register frame to mapped into the child task\'s address space.","breadcrumbs":"Spawning a Task (Challenge) » Step 7.B","id":"43","title":"Step 7.B"},"44":{"body":"This step simply copies the Device type from chapter 5 into the child task. In step 7.E , you be able to use this type to interact with the serial device\'s MMIO registers, just like we as part of step 5.E .","breadcrumbs":"Spawning a Task (Challenge) » Step 7.C","id":"44","title":"Step 7.C"},"45":{"body":"This step just adds the SERIAL_DEVICE_MMIO_PADDR and SERIAL_DEVICE_IRQ constants from chapter 5 to the root task.","breadcrumbs":"Spawning a Task (Challenge) » Step 7.D","id":"45","title":"Step 7.D"},"46":{"body":"Exercise: Extend the root task so that it sets up the child task to be able to interact with the serial device, and extend the child task to implement the same echo loop as in [./serial-device.html#step-5h-exercise]. Hint for the root task (click to expand) Try following this sequence of sub-steps: - Allocate serial_device_frame_cap: sel4::cap::Granule using object_allocator.recklessly_allocate_at(). - Map serial_device_frame_cap into the child task\'s address space using create_child_vspace()\'s extra_frames parameter. - Similarly to how we did so in steps 5.F and 5.G , obtain irq_handler_cap: sel4::cap::IrqHandler for SERIAL_DEVICE_IRQ (object_allocator.allocate_slot() might come in handy), allocate irq_nfn_cap: sel4::cap::Notification, and associate irq_nfn_cap with SERIAL_DEVICE_IRQ using irq_handler_cap. - Copy irq_handler_cap and irq_nfn_cap into the child task\'s CSpace in a similar way to how child_tcb and inter_task_ep are copied. Hint for the child task (click to expand) Try following this sequence of sub-steps: - Declare constants IRQ_HANDLER: sel4::cap::IrqHandler and IRQ_NFN: sel4::cap::Notification after OWN_TCB and INTRA_TASK_EP. - Obtain the virtual address of the serial device MMIO frame with addr_of_page_beyond_image(1) (recall how create_child_vspace()\'s extra_frames parameter works). - Initialize the serial device with Device::new() and Device::init() (as we did for part of step 5.E ), and use the serial device just like we did in step 5.H .","breadcrumbs":"Spawning a Task (Challenge) » Step 7.E (challenge)","id":"46","title":"Step 7.E (challenge)"},"47":{"body":"The seL4 Microkit is a framework for creating static systems based on seL4. This part of the text assumes that the reader is familiar with the basics of the Microkit framework and API, or is using a companion resource to learn about the Microkit in parallel. Here are three such resources: The Mirokit manual The Mirokit tutorial This part also assumes that the reader has worked through chapters 2 and 6 of Part I .","breadcrumbs":"Overview » seL4 Microkit","id":"47","title":"seL4 Microkit"},"48":{"body":"Navigate to and run the hello world Microkit example: cd workspaces/microkit/hello-world\\nmake simulate Here is its source: hello-world/pds/hello/src/main.rs:7:22 #![no_std]\\n#![no_main] use sel4_microkit::{debug_println, protection_domain, Handler, Infallible}; #[protection_domain]\\nfn init() -> impl Handler { debug_println!(\\"Hello, World!\\"); HandlerImpl\\n} struct HandlerImpl; impl Handler for HandlerImpl { type Error = Infallible;\\n} The sel4_microkit crate implements a Rust language runtime for Microkit protection domains, and implements the Microkit API. It is written in pure Rust, and does not link against libmicrokit .","breadcrumbs":"Hello, World! » Hello, World!","id":"48","title":"Hello, World!"},"49":{"body":"The #[protection_domain] attribute macro declares a function to be the protection domain\'s initialization function. The entrypoint function must have a signature of the form: fn() -> T\\nwhere T: sel4_microkit::Handler An implementation of the Handler trait is used by the runtime as the event handler for the protection domain\'s main loop. The notified , protected , and fault methods correspond to their equivalents in . The default implementations of these methods just panic. Our event handler, which we\'ve called HandlerImpl, is the simplest possible Handler implementation.","breadcrumbs":"Hello, World! » The Event Handler","id":"49","title":"The Event Handler"},"5":{"body":"Rustdoc for the rust-sel4 project is hosted here: https://sel4.github.io/rust-sel4/ However, for the sake of consistency, rustdoc for the particular configurations studied in this text are hosted here too. There is one set of rustdoc for each of the two workspace configurations mentioned in Two Workspaces . Rustdoc does not generate an index page, but you can navigate across crates within a workspace configuration using the sidebar present on top-level rustdoc page for any module. Rustdoc for Part I Rustdoc for Part II","breadcrumbs":"Setup » Rustdoc","id":"5","title":"Rustdoc"},"50":{"body":"As detailed in its rustdoc, the #[protection_domain] attribute macro takes the same parameters as #[root_task] . Furthermore, the sel4_microkit crate supports all of the same Rust language runtime elements that we explored in Chapter 2 , including sel4_microkit::panicking::catch_unwind() and sel4_microkit::panicking::set_hook() .","breadcrumbs":"Hello, World! » Language Runtime","id":"50","title":"Language Runtime"},"51":{"body":"This chapter covers making and handling protected procedure calls in protection domains written in Rust. Navigate to and run the example: cd workspaces/microkit/ipc\\nmake simulate The example system description specifies two protection domains, with a channel between them: ipc.system:7:20 \\n pds/client/src/main.rs:14:36 const SERVER: Channel = Channel::new(13); #[protection_domain]\\nfn init() -> impl Handler { debug_println!(\\"client: initializing\\"); HandlerImpl\\n} struct HandlerImpl; impl Handler for HandlerImpl { type Error = Infallible; fn notified(&mut self, channels: ChannelSet) -> Result<(), Self::Error> { debug_println!(\\"client: notified by {}\\", channels.display()); if channels.contains(SERVER) { debug_println!(\\"client: TEST_PASS\\"); } Ok(()) }\\n} pds/server/src/main.rs:12:39 const CLIENT: Channel = Channel::new(37); #[protection_domain]\\nfn init() -> impl Handler { debug_println!(\\"server: initializing\\"); debug_println!(\\"server: notifying client\\"); CLIENT.notify(); HandlerImpl\\n} struct HandlerImpl; impl Handler for HandlerImpl { type Error = Infallible; fn protected( &mut self, channel: Channel, msg_info: MessageInfo, ) -> Result { debug_println!(\\"server: called by {:?}\\", channel); todo!() }\\n} The Channel type is the Rust equivalent of the microkit_channel type alias in libmicrokit. Note how the functionality corresponding to libmicrokit\'s microkit_notify, microkit_irq_ack, and microkit_ppcall is implemented in methods for Channel. The MessageInfo type is the Rust equivalent of the microkit_msginfo type alias in libmicrokit. Just as microkit_msginfo is an alias for seL4_MessageInfo_t, sel4_microkit::MessageInfo is just a thin wrapper around MessageInfo . libmicrokit has microkit_mr_set() and microkit_mr_get() for interacting with the IPC buffer. In the sel4_microkit crate, we have get_mr() and set_mr() , but we also have with_msg_regs() , with_msg_regs_mut() , with_msg_bytes() , and with_msg_bytes_mut() , which use sel4::with_ipc_buffer() and sel4::with_ipc_buffer_mut() under the hood.","breadcrumbs":"IPC » IPC","id":"51","title":"IPC"},"52":{"body":"Exercise: In the client\'s notified() handler, make a protected procedure call to the server using SERVER.pp_call(). Handle the call in the server\'s protected() handler. Include data in the message using sel4_microkit::with_msg_regs{,_mut}. Exercise (optional): Send something more interesting over IPC using msg_bytes and msg_bytes_mut . For example, the zerocopy crate can be used to view certain types as bytes and vice versa, and the lightweight postcard crate can be used to serialize and deserialize a wider range of types using serde .","breadcrumbs":"IPC » Step 10.A (exercise)","id":"52","title":"Step 10.A (exercise)"},"53":{"body":"This chapter covers interacting with shared memory from protection domains written in Rust. Navigate to and run the example: cd workspaces/microkit/shared-memory\\nmake simulate The example system description specifies two protection domains which share two memory regions: shared-memory.system:7:28 \\n The Microkit tool will inject memory region virtual addresses into protection domain images according to the setvar_vaddr attribute values. For example, the virtual address of the mapping of region_a into the client protection domain will be injected into the microkit-shared-memory-client.elf image at the location specified by then region_a_vaddr symbol. In the case of Rust, declaring a symbol that the Microkit tool can patch requires a bit more intentionality than in the C case. The sel4_microkit::var! macro is provided to declare such symbols. The var! macro\'s implementation is just a few lines of code. We want to express this symbol as a global variable that does not change at runtime, but which cannot be assumed to have the value we assign it at compile time, and which must not be optimized away. The near-trivial sel4_immutable_cell::ImmutableCell type encapsulates this pattern. The #[no_mangle] attribute instructs the compiler to use the name of the variable as the name of the symbol. This is the default in C, but not Rust. We direct the compiler to put this symbol in the .data section with #[link_section = \\".data\\"] to ensure that space is allocated for it in the ELF file itself, not just the program image it describes. So far, the example protection domains just store pointers to the shared memory regions in their handler state: pds/client/src/main.rs:17:31 fn init() -> impl Handler { debug_println!(\\"client: initializing\\"); let region_a = *var!(region_a_vaddr: usize = 0); let region_b = *var!(region_b_vaddr: usize = 0); debug_println!(\\"client: region_a = {region_a:#x?}\\"); debug_println!(\\"client: region_b = {region_b:#x?}\\"); let _ = SERVER.pp_call(MessageInfo::default()); debug_println!(\\"TEST_PASS\\"); NullHandler::new()\\n} pds/server/src/main.rs:17:46 fn init() -> impl Handler { debug_println!(\\"server: initializing\\"); let region_a = *var!(region_a_vaddr: usize = 0); let region_b = *var!(region_b_vaddr: usize = 0); debug_println!(\\"server: region_a = {region_a:#x?}\\"); debug_println!(\\"server: region_b = {region_b:#x?}\\"); HandlerImpl { region_a, region_b }\\n} struct HandlerImpl { region_a: usize, region_b: usize,\\n} impl Handler for HandlerImpl { type Error = Infallible; fn protected( &mut self, channel: Channel, _msg_info: MessageInfo, ) -> Result { assert_eq!(channel, CLIENT); Ok(MessageInfo::default()) }\\n}","breadcrumbs":"Shared Memory » Shared Memory","id":"53","title":"Shared Memory"},"54":{"body":"Let\'s assign types to these shared memory regions. We can define our types in a crate that both the client and server can use: pds/common/src/lib.rs:9:18 use zerocopy::{FromBytes, IntoBytes}; pub const REGION_A_SIZE: usize = 1337; #[repr(C)]\\n#[derive(IntoBytes, FromBytes)]\\npub struct RegionB { pub field_1: u64, pub foo: [u16; 16],\\n} Suppose region_a: [u8; REGION_A_SIZE] and region_b: RegionB. You could just turn the virtual addresses we get in our var! symbols into pointers and start interacting with the shared memory regions with unsafe ptr::* operations, but we can leverage the Rust type system to come up with a solution that only requires unsafe at initialization time.","breadcrumbs":"Shared Memory » Step 11.A","id":"54","title":"Step 11.A"},"55":{"body":"The sel4-shared-memory crate provides a way for you to declare a memory region\'s type and bounds, along with the memory access operations that can safely be used on it, so that you can access it without unsafe code. That initial declaration is, however, unsafe. The sel4-shared-memory is a thin wrapper around the sel4_abstract_ptr crate, instantiating its abstract pointer types with memory access operations suitable for memory that is shared with another protection domain. The sel4_microkit::memory_region_symbol! macro is like the sel4_microkit::var! macro, except specialized for shared memory region virtual address symbols. For one, the underlying symbol is always of type usize and the macro returns a value of type NonNull<_>. memory_region_symbol! has a few additional features. For example, memory_region_symbol!(foo: *mut [u8] n = BAR) returns a NonNull<[u8]> with a runtime slice length of BAR. See this step\'s diff for how to put this all together.","breadcrumbs":"Shared Memory » Step 11.B","id":"55","title":"Step 11.B"},"6":{"body":"After initializing itself, the seL4 kernel passes control to a userspace program called the root task, whose image is provided to the kernel at boot-time. The root task\'s capability space contains capabilities for all memory and boot-time objects. That is to say, the root task spawns with the maximum privilege that a userspace program can have. The kernel provides the root task with a map of its initial capability space in the form of the BootInfo frame . You can read more about the root task\'s environment in seL4 Reference Manual § 9.1 . Part I of this tutorial will focus on writing from-scratch root tasks in Rust. Some of the code in Part I will be quite low-level, interacting with the language runtime, the linker, and some of the finer details related to bootstrapping an seL4-based system. The only seL4-related crates we will be using are the language runtime and bindings for the seL4 API. Unlike situations where higher-level seL4-related libraries (such as seL4_libs ) are used, we will be allocating objects and manage virtual address spaces from scratch. At boot time, the seL4 kernel and root task are loaded into memory by a kind of bootloader stub referred to as a seL4 kernel loader. For Part I, we will use the kernel loader from the rust-sel4 project . We won\'t cover how it works or how to use it explicitly in this text. It is built at docker/Dockerfile:94:108 , and used at mk/root-task.mk:31:36 .","breadcrumbs":"Overview » The Root Task","id":"6","title":"The Root Task"},"7":{"body":"Run the hello world example: cd workspaces/root-task/hello-world\\nmake simulate Press ctrl-a x to exit QEMU. Here is its source: hello-world/src/main.rs:7:17 #![no_std]\\n#![no_main] use sel4_root_task::root_task; #[root_task]\\nfn main(_bootinfo: &sel4::BootInfoPtr) -> ! { sel4::debug_println!(\\"Hello, World!\\"); sel4::init_thread::suspend_self()\\n} The Rust standard library is divided into three layers: core : dependency-free foundation alloc : implements heap-backed data structures, but requires a runtime that provides a heap allocator std includes core and alloc, and adds APIs that depend on OS services such as networking and filesystems The high-level std doesn\'t support the low-level seL4 root task target. #![no_std] declares that this crate does not depend on std, and prevents rustc from automatically importing it. Our language runtime will handle the program\'s entrypoint differently than a typical Rust program. #![no_main] informs rustc of this fact. The sel4 crate binds the seL4 API. It is generated from source (.xml, .bf, and .h) in libsel4. We will cover the contents of this crate in future chapters. The sel4_root_task crate implements a Rust language runtime for the root task environment. The #[root_task] attribute macro declares a function to be the root task\'s entrypoint. The entrypoint function must have a signature of the form: fn(&sel4::BootInfoPtr) -> T\\nwhere T: sel4_root_task::Termination (Rustdoc for BootInfoPtr and Termination ) The root task has no way to exit, so, to terminate cleanly, it must suspend its own thread. sel4::init_thread::suspend_self() does exactly this.","breadcrumbs":"Hello, World! » Hello, World!","id":"7","title":"Hello, World!"},"8":{"body":"Exercise: Cause a panic.","breadcrumbs":"Hello, World! » Step 2.A (exercise)","id":"8","title":"Step 2.A (exercise)"},"9":{"body":"Exercise: Catch the panic using sel4_root_task::panicking::catch_unwind() .","breadcrumbs":"Hello, World! » Step 2.B (exercise)","id":"9","title":"Step 2.B (exercise)"}},"length":56,"save":true},"fields":["title","body","breadcrumbs"],"index":{"body":{"root":{"0":{"1":{"6":{"df":0,"docs":{},"x":{"df":1,"docs":{"16":{"tf":1.0}}}},"df":0,"docs":{}},"2":{"df":1,"docs":{"16":{"tf":1.0}}},"df":2,"docs":{"25":{"tf":1.0},"53":{"tf":2.0}},"x":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"8":{"0":{"0":{"1":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"8":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"1":{"1":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"9":{"0":{"0":{"_":{"0":{"0":{"0":{"0":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"df":1,"docs":{"25":{"tf":1.0}}}},"f":{"0":{"0":{"d":{"df":1,"docs":{"13":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"1":{"0":{".":{"a":{"df":1,"docs":{"52":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"1":{".":{"a":{"df":1,"docs":{"54":{"tf":1.0}}},"b":{"df":1,"docs":{"55":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"3":{"df":1,"docs":{"38":{"tf":1.0}}},"df":1,"docs":{"16":{"tf":1.4142135623730951}}},"3":{"3":{"7":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"df":3,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"16":{"tf":1.4142135623730951}}},"4":{"df":1,"docs":{"16":{"tf":1.0}}},"5":{"df":1,"docs":{"16":{"tf":1.0}}},"6":{"df":1,"docs":{"54":{"tf":1.0}}},"df":2,"docs":{"18":{"tf":1.0},"31":{"tf":1.4142135623730951}}},"2":{".":{"3":{"df":1,"docs":{"15":{"tf":1.0}}},"4":{".":{"1":{"df":1,"docs":{"18":{"tf":1.0}}},"2":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":3,"docs":{"16":{"tf":1.0},"18":{"tf":1.0},"30":{"tf":1.0}}},"a":{"df":1,"docs":{"8":{"tf":1.0}}},"b":{"df":1,"docs":{"9":{"tf":1.0}}},"c":{"df":1,"docs":{"10":{"tf":1.0}}},"d":{"df":1,"docs":{"11":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"12":{"tf":1.0}}},"f":{"df":1,"docs":{"13":{"tf":1.0}}},"g":{"df":1,"docs":{"14":{"tf":1.7320508075688772}}}},"7":{"df":1,"docs":{"16":{"tf":1.0}}},"df":3,"docs":{"16":{"tf":1.0},"47":{"tf":1.0},"50":{"tf":1.0}}},"3":{".":{"a":{"df":1,"docs":{"16":{"tf":1.4142135623730951}}},"b":{"df":1,"docs":{"17":{"tf":1.4142135623730951}}},"c":{"df":1,"docs":{"18":{"tf":2.23606797749979}}},"d":{"df":1,"docs":{"19":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"20":{"tf":1.4142135623730951}}},"f":{"df":1,"docs":{"21":{"tf":1.0}}},"g":{"df":1,"docs":{"22":{"tf":1.0}}}},"3":{"df":1,"docs":{"28":{"tf":1.0}}},"7":{"df":2,"docs":{"12":{"tf":1.0},"13":{"tf":1.0}}},"df":1,"docs":{"24":{"tf":1.0}}},"4":{".":{"2":{".":{"4":{"df":1,"docs":{"40":{"tf":1.0}}},"df":0,"docs":{}},"df":1,"docs":{"38":{"tf":1.0}}},"a":{"df":1,"docs":{"24":{"tf":1.0}}},"b":{"df":2,"docs":{"25":{"tf":1.7320508075688772},"33":{"tf":1.0}}},"c":{"df":2,"docs":{"26":{"tf":1.7320508075688772},"33":{"tf":1.0}}},"d":{"df":2,"docs":{"27":{"tf":1.0},"33":{"tf":1.0}}},"df":0,"docs":{}},"0":{"9":{"6":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"38":{"tf":1.0}}},"5":{".":{"a":{"df":1,"docs":{"29":{"tf":1.7320508075688772}}},"b":{"df":1,"docs":{"30":{"tf":1.0}}},"c":{"df":2,"docs":{"31":{"tf":1.7320508075688772},"42":{"tf":1.0}}},"d":{"df":1,"docs":{"32":{"tf":1.4142135623730951}}},"df":0,"docs":{},"e":{"df":3,"docs":{"33":{"tf":1.4142135623730951},"44":{"tf":1.0},"46":{"tf":1.0}}},"f":{"df":2,"docs":{"34":{"tf":1.0},"46":{"tf":1.0}}},"g":{"df":2,"docs":{"35":{"tf":1.0},"46":{"tf":1.0}}},"h":{"df":2,"docs":{"36":{"tf":1.0},"46":{"tf":1.0}}}},"2":{"5":{"3":{"df":0,"docs":{},"e":{"d":{"c":{"1":{"df":0,"docs":{},"e":{"d":{"1":{"2":{"df":1,"docs":{"1":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":3,"docs":{"20":{"tf":1.0},"44":{"tf":1.0},"45":{"tf":1.0}},"h":{"df":2,"docs":{"41":{"tf":1.0},"46":{"tf":1.0}}}},"6":{".":{"a":{"df":1,"docs":{"38":{"tf":1.7320508075688772}}},"b":{"df":1,"docs":{"39":{"tf":1.0}}},"c":{"df":1,"docs":{"40":{"tf":1.0}}},"df":0,"docs":{}},"df":2,"docs":{"41":{"tf":1.0},"47":{"tf":1.0}}},"7":{".":{"1":{".":{"3":{"df":1,"docs":{"23":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"a":{"df":3,"docs":{"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0}}},"b":{"df":3,"docs":{"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0}}},"c":{"df":2,"docs":{"41":{"tf":1.0},"44":{"tf":1.0}}},"d":{"df":2,"docs":{"41":{"tf":1.0},"45":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":5,"docs":{"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":1.0}}}},"df":0,"docs":{}},"8":{"c":{"a":{"0":{"df":0,"docs":{},"e":{"1":{"9":{"3":{"9":{"d":{"c":{"1":{".":{".":{"5":{"2":{"5":{"3":{"df":0,"docs":{},"e":{"d":{"c":{"1":{"df":0,"docs":{},"e":{"d":{"1":{"2":{"df":1,"docs":{"1":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"1":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"9":{".":{"1":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"_":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"26":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"b":{"a":{"d":{"df":0,"docs":{},"g":{"df":1,"docs":{"38":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"c":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}},"df":0,"docs":{}}}},"df":2,"docs":{"33":{"tf":1.0},"53":{"tf":1.0}},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}}}}}}},"a":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"v":{"df":1,"docs":{"18":{"tf":1.0}}}},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"(":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"a":{".":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"b":{".":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":1,"docs":{"31":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"t":{"df":0,"docs":{},"r":{"a":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"55":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"c":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":2,"docs":{"12":{"tf":1.0},"13":{"tf":1.0}}}},"s":{"df":0,"docs":{},"s":{"df":6,"docs":{"15":{"tf":1.4142135623730951},"20":{"tf":1.0},"26":{"tf":1.0},"28":{"tf":1.0},"34":{"tf":1.0},"55":{"tf":1.7320508075688772}}}}},"o":{"df":0,"docs":{},"r":{"d":{"df":3,"docs":{"18":{"tf":1.0},"42":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{},"k":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"g":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}}}}}}},"q":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":1,"docs":{"18":{"tf":1.0}}}}}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"15":{"tf":1.0}}}}}}},"d":{"d":{"df":6,"docs":{"13":{"tf":1.0},"14":{"tf":1.0},"17":{"tf":1.0},"29":{"tf":1.0},"45":{"tf":1.0},"7":{"tf":1.0}},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"2":{"tf":1.0},"55":{"tf":1.0}}}},"r":{"_":{"df":0,"docs":{},"o":{"df":0,"docs":{},"f":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"y":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"d":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"(":{"1":{"df":1,"docs":{"46":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":1,"docs":{"26":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":17,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":2.23606797749979},"23":{"tf":3.0},"25":{"tf":1.0},"26":{"tf":1.4142135623730951},"28":{"tf":1.4142135623730951},"30":{"tf":2.0},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"33":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951},"54":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.0}}}}}}},"df":1,"docs":{"41":{"tf":1.4142135623730951}},"j":{"df":0,"docs":{},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"12":{"tf":1.0}}}}}},"v":{"a":{"df":0,"docs":{},"n":{"c":{"df":2,"docs":{"18":{"tf":1.0},"31":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{},"g":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"41":{"tf":1.0}},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"48":{"tf":1.0}}}}}}},"df":0,"docs":{}},"h":{"df":0,"docs":{},"e":{"a":{"d":{"df":1,"docs":{"1":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}},"l":{"df":0,"docs":{},"i":{"a":{"df":2,"docs":{"23":{"tf":1.4142135623730951},"51":{"tf":1.7320508075688772}},"s":{"df":1,"docs":{"15":{"tf":1.0}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"(":{"4":{"0":{"9":{"6":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":2,"docs":{"18":{"tf":1.0},"25":{"tf":1.0}}}}},"l":{"df":0,"docs":{},"o":{"c":{"df":16,"docs":{"13":{"tf":1.0},"15":{"tf":1.0},"16":{"tf":1.0},"18":{"tf":2.6457513110645907},"20":{"tf":1.4142135623730951},"24":{"tf":1.0},"29":{"tf":1.0},"30":{"tf":2.0},"31":{"tf":1.4142135623730951},"32":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":2.8284271247461903},"46":{"tf":1.4142135623730951},"53":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.7320508075688772}}},"df":0,"docs":{},"w":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}},"o":{"df":0,"docs":{},"n":{"df":2,"docs":{"37":{"tf":1.0},"41":{"tf":1.0}},"g":{"df":3,"docs":{"26":{"tf":1.0},"30":{"tf":1.0},"55":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"e":{"a":{"d":{"df":0,"docs":{},"i":{"df":2,"docs":{"18":{"tf":1.0},"36":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"w":{"a":{"df":0,"docs":{},"y":{"df":3,"docs":{"31":{"tf":1.0},"38":{"tf":1.0},"55":{"tf":1.0}}}},"df":0,"docs":{}}},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"15":{"tf":1.0}}}}}}},"n":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"y":{"df":0,"docs":{},"z":{"df":1,"docs":{"4":{"tf":2.0}}}}}},"d":{"/":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"55":{"tf":1.0}}}}},"y":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"28":{"tf":1.0}}}}}},"p":{"df":0,"docs":{},"i":{"df":8,"docs":{"0":{"tf":2.449489742783178},"23":{"tf":1.4142135623730951},"30":{"tf":1.0},"34":{"tf":1.0},"47":{"tf":1.0},"48":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"p":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"3":{"tf":1.0}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"24":{"tf":1.0}}}}}}}}},"r":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"23":{"tf":2.23606797749979}},"e":{"\'":{"df":1,"docs":{"23":{"tf":1.0}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"\'":{"df":0,"docs":{},"t":{"df":1,"docs":{"37":{"tf":1.0}}}},"df":0,"docs":{}}},"g":{"df":0,"docs":{},"u":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}}}}}},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"d":{"df":4,"docs":{"15":{"tf":1.0},"31":{"tf":1.0},"51":{"tf":1.0},"55":{"tf":1.0}}},"df":0,"docs":{}}}},"r":{"a":{"df":0,"docs":{},"y":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"a":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"4":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"s":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"q":{"!":{"(":{"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{".":{"df":0,"docs":{},"l":{"a":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"38":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"25":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"f":{"df":1,"docs":{"25":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":1,"docs":{"32":{"tf":1.0}}}}},"df":1,"docs":{"32":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"df":2,"docs":{"53":{"tf":1.0},"54":{"tf":1.0}}}}},"o":{"c":{"df":1,"docs":{"15":{"tf":1.0}},"i":{"df":8,"docs":{"15":{"tf":1.4142135623730951},"16":{"tf":1.0},"23":{"tf":1.0},"34":{"tf":1.4142135623730951},"35":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"46":{"tf":1.0}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"m":{"df":4,"docs":{"0":{"tf":1.4142135623730951},"2":{"tf":1.0},"47":{"tf":1.4142135623730951},"53":{"tf":1.0}}}}}},"t":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":2,"docs":{"1":{"tf":1.4142135623730951},"13":{"tf":1.0}}}}}},"r":{"df":1,"docs":{"27":{"tf":1.0}},"i":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":6,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"49":{"tf":1.0},"50":{"tf":1.0},"53":{"tf":1.4142135623730951},"7":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":2,"docs":{"15":{"tf":1.0},"34":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"7":{"tf":1.0}}}},"df":0,"docs":{}}}}},"v":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"15":{"tf":1.4142135623730951}}}}},"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"d":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}}}},"w":{"a":{"df":0,"docs":{},"y":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}},"b":{"\\"":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"33":{"tf":1.0}}}}}}}},"a":{"c":{"df":0,"docs":{},"k":{"df":4,"docs":{"26":{"tf":1.4142135623730951},"30":{"tf":1.7320508075688772},"41":{"tf":1.0},"7":{"tf":1.0}},"g":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"2":{"tf":1.0}}},"df":0,"docs":{}}}}}}}},"d":{"df":0,"docs":{},"g":{"df":1,"docs":{"20":{"tf":2.6457513110645907}}}},"df":0,"docs":{},"r":{"df":1,"docs":{"55":{"tf":1.4142135623730951}}},"s":{"df":0,"docs":{},"e":{"df":5,"docs":{"16":{"tf":1.0},"20":{"tf":1.0},"28":{"tf":1.0},"47":{"tf":1.0},"6":{"tf":1.0}}},"i":{"c":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"38":{"tf":1.0}}}}},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"36":{"tf":1.0}}}}},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"34":{"tf":1.0}}},"df":0,"docs":{}}}},"t":{"df":0,"docs":{},"w":{"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":4,"docs":{"3":{"tf":1.0},"30":{"tf":1.0},"38":{"tf":1.7320508075688772},"51":{"tf":1.0}}}},"n":{"df":1,"docs":{"38":{"tf":1.0}}}}}}},"f":{"df":1,"docs":{"7":{"tf":1.0}}},"i":{"df":0,"docs":{},"n":{"d":{"df":4,"docs":{"0":{"tf":1.7320508075688772},"34":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}},"t":{"df":5,"docs":{"16":{"tf":2.8284271247461903},"18":{"tf":1.0},"20":{"tf":1.0},"38":{"tf":1.4142135623730951},"53":{"tf":1.0}}}},"l":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"k":{"df":3,"docs":{"37":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"42":{"tf":1.0}}}}}}}}}},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":2,"docs":{"16":{"tf":1.0},"6":{"tf":1.7320508075688772}},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}},"e":{"d":{"(":{")":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"(":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"x":{")":{".":{"c":{"a":{"df":0,"docs":{},"p":{"df":2,"docs":{"17":{"tf":1.4142135623730951},"29":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"_":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"16":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":9,"docs":{"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":1.4142135623730951},"23":{"tf":1.0},"26":{"tf":1.4142135623730951},"29":{"tf":1.4142135623730951},"30":{"tf":1.0},"42":{"tf":1.0},"6":{"tf":1.0}},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}},"l":{"df":0,"docs":{},"o":{"a":{"d":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"6":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"t":{"df":0,"docs":{},"h":{"df":4,"docs":{"13":{"tf":1.0},"18":{"tf":1.0},"3":{"tf":1.0},"54":{"tf":1.0}}}},"u":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"55":{"tf":1.0}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"38":{"tf":2.8284271247461903},"43":{"tf":1.0},"51":{"tf":1.0}}}}}},"i":{"df":0,"docs":{},"l":{"d":{"df":6,"docs":{"14":{"tf":1.4142135623730951},"2":{"tf":2.0},"28":{"tf":1.0},"37":{"tf":1.0},"4":{"tf":1.0},"41":{"tf":1.7320508075688772}}},"df":0,"docs":{},"t":{"df":4,"docs":{"2":{"tf":1.0},"4":{"tf":1.0},"41":{"tf":1.0},"6":{"tf":1.0}}}}}},"y":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":4,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"38":{"tf":1.0},"52":{"tf":1.0}}}}}},"c":{"a":{"b":{"a":{"b":{"df":0,"docs":{},"l":{"df":1,"docs":{"15":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"d":{"=":{"\\"":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":1,"docs":{"53":{"tf":2.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":15,"docs":{"1":{"tf":1.0},"15":{"tf":2.23606797749979},"18":{"tf":1.0},"20":{"tf":2.0},"23":{"tf":1.0},"32":{"tf":1.0},"34":{"tf":1.0},"38":{"tf":2.0},"40":{"tf":1.0},"41":{"tf":1.0},"42":{"tf":1.4142135623730951},"49":{"tf":1.0},"51":{"tf":1.4142135623730951},"52":{"tf":1.4142135623730951},"6":{"tf":1.0}}}},"p":{"\'":{"df":1,"docs":{"15":{"tf":1.4142135623730951}}},":":{":":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"<":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}}}}}}}},"a":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0}},"y":{"\'":{"df":1,"docs":{"20":{"tf":1.0}}},"df":0,"docs":{}}}}}},"l":{"df":12,"docs":{"15":{"tf":3.0},"16":{"tf":1.0},"18":{"tf":3.3166247903554},"20":{"tf":2.8284271247461903},"23":{"tf":1.0},"26":{"tf":1.7320508075688772},"27":{"tf":1.0},"31":{"tf":1.0},"34":{"tf":2.6457513110645907},"38":{"tf":1.7320508075688772},"42":{"tf":1.4142135623730951},"6":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"31":{"tf":1.7320508075688772}},"s":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"38":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"o":{"/":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{":":{"8":{"df":1,"docs":{"3":{"tf":1.0}}},"df":0,"docs":{}},"df":1,"docs":{"3":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":1,"docs":{"3":{"tf":1.0}}}},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"15":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"e":{"df":5,"docs":{"13":{"tf":1.0},"18":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"53":{"tf":1.4142135623730951}}},"t":{"df":1,"docs":{"18":{"tf":1.0}}}},"t":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"9":{"tf":1.0}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"s":{"df":3,"docs":{"11":{"tf":1.0},"12":{"tf":1.0},"8":{"tf":1.0}}}},"v":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}}}},"d":{"df":10,"docs":{"1":{"tf":1.0},"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.0},"48":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}}},"df":4,"docs":{"2":{"tf":1.7320508075688772},"26":{"tf":1.0},"33":{"tf":1.0},"53":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"18":{"tf":1.4142135623730951},"52":{"tf":1.0}}}}},"df":0,"docs":{}}}},"h":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"df":2,"docs":{"41":{"tf":1.7320508075688772},"46":{"tf":1.0}}}}}}},"n":{"df":0,"docs":{},"g":{"df":4,"docs":{"38":{"tf":1.0},"40":{"tf":1.0},"42":{"tf":1.0},"53":{"tf":1.0}}},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{":":{":":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"(":{"1":{"3":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"3":{"7":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":2,"docs":{"51":{"tf":3.3166247903554},"53":{"tf":2.0}},"s":{".":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"(":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":1,"docs":{"51":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"d":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"y":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}}}}},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"\'":{"df":3,"docs":{"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0}}},"df":12,"docs":{"23":{"tf":1.4142135623730951},"24":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.4142135623730951},"41":{"tf":1.7320508075688772},"44":{"tf":1.0},"45":{"tf":1.0},"47":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}}}}}}},"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"1":{"tf":1.0}}}}}},"i":{"df":0,"docs":{},"l":{"d":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{".":{"df":0,"docs":{},"r":{"df":1,"docs":{"41":{"tf":1.0}}}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"_":{"df":0,"docs":{},"t":{"c":{"b":{"df":1,"docs":{"46":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":5,"docs":{"31":{"tf":1.0},"41":{"tf":2.6457513110645907},"43":{"tf":1.4142135623730951},"44":{"tf":1.0},"46":{"tf":2.23606797749979}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":1,"docs":{"31":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"l":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"7":{"tf":1.0}}}}},"r":{"df":3,"docs":{"20":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0}}}},"df":0,"docs":{}},"i":{"c":{"df":0,"docs":{},"k":{"df":2,"docs":{"1":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"\'":{"df":1,"docs":{"52":{"tf":1.0}}},".":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.4142135623730951}}}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":1,"docs":{"51":{"tf":1.0}}}}}}}}},"df":3,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951},"54":{"tf":1.0}}}}},"p":{"b":{"df":0,"docs":{},"o":{"a":{"df":0,"docs":{},"r":{"d":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}}}}},"n":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{".":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"(":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{".":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"20":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":2.8284271247461903},"20":{"tf":1.0}}}},"df":0,"docs":{}}},"o":{"d":{"df":0,"docs":{},"e":{"df":10,"docs":{"1":{"tf":2.0},"24":{"tf":1.0},"3":{"tf":1.0},"33":{"tf":1.0},"37":{"tf":1.7320508075688772},"4":{"tf":1.4142135623730951},"41":{"tf":2.0},"53":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":3,"docs":{"13":{"tf":1.0},"46":{"tf":1.0},"54":{"tf":1.0}}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"1":{"tf":2.449489742783178}}}},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"41":{"tf":1.0}}}},"u":{"df":0,"docs":{},"n":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}}},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}}}}},"r":{"df":2,"docs":{"20":{"tf":1.0},"41":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.7320508075688772}}}},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"41":{"tf":1.0}}},"x":{"df":1,"docs":{"41":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"34":{"tf":1.4142135623730951}}}},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":1,"docs":{"23":{"tf":1.4142135623730951}}}}},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"n":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":1,"docs":{"23":{"tf":1.0}}}},"r":{"df":0,"docs":{},"n":{"df":1,"docs":{"37":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"s":{"df":1,"docs":{"38":{"tf":1.0}}}},"u":{"df":0,"docs":{},"r":{"df":0,"docs":{},"r":{"df":1,"docs":{"37":{"tf":1.0}}}}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"df":1,"docs":{"3":{"tf":1.0}}}}}}},"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":4,"docs":{"3":{"tf":1.4142135623730951},"38":{"tf":1.0},"4":{"tf":1.4142135623730951},"5":{"tf":1.7320508075688772}}}}}}},"s":{"df":0,"docs":{},"i":{"d":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":2,"docs":{"41":{"tf":1.0},"5":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"l":{"df":1,"docs":{"33":{"tf":1.0}}}},"t":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":3,"docs":{"18":{"tf":1.0},"45":{"tf":1.0},"46":{"tf":1.0}}}}},"df":4,"docs":{"25":{"tf":1.0},"28":{"tf":1.4142135623730951},"51":{"tf":1.4142135623730951},"54":{"tf":1.0}},"r":{"df":0,"docs":{},"u":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.0}}}},"df":0,"docs":{}}}}},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":13,"docs":{"1":{"tf":1.0},"15":{"tf":1.0},"18":{"tf":1.0},"2":{"tf":2.0},"20":{"tf":1.0},"26":{"tf":1.0},"30":{"tf":1.7320508075688772},"31":{"tf":1.0},"38":{"tf":1.0},"4":{"tf":2.6457513110645907},"41":{"tf":1.0},"42":{"tf":1.4142135623730951},"6":{"tf":1.0}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"7":{"tf":1.0}}}},"x":{"df":0,"docs":{},"t":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.4142135623730951},"41":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":4,"docs":{"34":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"6":{"tf":1.0}}}}}}},"p":{"df":0,"docs":{},"i":{"df":4,"docs":{"1":{"tf":1.0},"38":{"tf":2.0},"44":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"r":{"df":0,"docs":{},"e":{"df":2,"docs":{"15":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"d":{"df":10,"docs":{"1":{"tf":1.0},"15":{"tf":1.0},"23":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951},"27":{"tf":1.0},"30":{"tf":1.0},"4":{"tf":1.0},"42":{"tf":1.0},"49":{"tf":1.0},"51":{"tf":1.0}}},"df":0,"docs":{}}}}}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":7,"docs":{"0":{"tf":1.7320508075688772},"25":{"tf":1.0},"31":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}}}},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}}}}}},"t":{"df":0,"docs":{},"r":{"df":3,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":2.6457513110645907},"38":{"tf":1.4142135623730951}}}}},"r":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":16,"docs":{"13":{"tf":1.0},"14":{"tf":1.7320508075688772},"15":{"tf":1.0},"23":{"tf":1.4142135623730951},"3":{"tf":1.4142135623730951},"37":{"tf":1.0},"41":{"tf":1.7320508075688772},"48":{"tf":1.0},"5":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":1.4142135623730951},"54":{"tf":1.0},"55":{"tf":1.4142135623730951},"6":{"tf":1.0},"7":{"tf":2.0}}}}},"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"t":{"df":9,"docs":{"15":{"tf":1.0},"16":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0},"24":{"tf":1.0},"30":{"tf":1.4142135623730951},"34":{"tf":1.4142135623730951},"35":{"tf":1.4142135623730951},"47":{"tf":1.0}},"e":{"_":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"_":{"df":0,"docs":{},"v":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":1,"docs":{"43":{"tf":1.4142135623730951}},"e":{"(":{")":{"\'":{"df":1,"docs":{"46":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}}},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"29":{"tf":1.0}}}}},"p":{"a":{"c":{"df":0,"docs":{},"e":{"\'":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}},"df":7,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":3.0},"20":{"tf":1.0},"23":{"tf":1.0},"26":{"tf":1.0},"38":{"tf":1.4142135623730951},"46":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"l":{"df":1,"docs":{"7":{"tf":1.0}}}}},"u":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{")":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"g":{"2":{"(":{")":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"y":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":1,"docs":{"31":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":3,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":2.449489742783178},"20":{"tf":1.0}}}}}}},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":3,"docs":{"0":{"tf":1.0},"10":{"tf":1.4142135623730951},"3":{"tf":1.0}}}}}}}},"d":{"a":{"df":0,"docs":{},"t":{"a":{"df":6,"docs":{"36":{"tf":1.0},"38":{"tf":2.449489742783178},"39":{"tf":1.0},"52":{"tf":1.0},"53":{"tf":1.4142135623730951},"7":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{},"e":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"l":{"df":0,"docs":{},"n":{"!":{"(":{"\\"":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":2,"docs":{"51":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772}}}}},"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"48":{"tf":1.0}}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":2,"docs":{"51":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772}}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"53":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}}}},"c":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":5,"docs":{"46":{"tf":1.0},"49":{"tf":1.0},"53":{"tf":1.4142135623730951},"55":{"tf":1.4142135623730951},"7":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":5,"docs":{"10":{"tf":1.0},"12":{"tf":1.0},"13":{"tf":1.0},"49":{"tf":1.0},"53":{"tf":1.0}}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"26":{"tf":1.0},"54":{"tf":1.0}}}}},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"v":{"df":1,"docs":{"34":{"tf":1.0}}}}},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":2,"docs":{"14":{"tf":1.0},"3":{"tf":1.0}}}}}}}},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":5,"docs":{"15":{"tf":1.0},"2":{"tf":1.0},"23":{"tf":1.0},"37":{"tf":1.0},"7":{"tf":1.7320508075688772}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"(":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"s":{"c":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":0,"docs":{},"e":{"_":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":2,"docs":{"17":{"tf":1.4142135623730951},"29":{"tf":1.4142135623730951}},"r":{"df":0,"docs":{},"i":{"b":{"df":4,"docs":{"16":{"tf":1.4142135623730951},"20":{"tf":1.0},"38":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":3,"docs":{"40":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0}},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"16":{"tf":1.0}}}}}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"52":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"r":{"df":3,"docs":{"18":{"tf":1.0},"31":{"tf":1.0},"42":{"tf":1.0}}}},"t":{"_":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"18":{"tf":1.0}}}}}},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":4,"docs":{"0":{"tf":1.0},"18":{"tf":1.0},"50":{"tf":1.0},"6":{"tf":1.0}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"26":{"tf":1.0},"38":{"tf":1.0}}}}}}}},"v":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"/":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"/":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"j":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"4":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"4":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":1,"docs":{"4":{"tf":2.0}},"i":{"c":{"df":10,"docs":{"16":{"tf":3.1622776601683795},"28":{"tf":1.7320508075688772},"30":{"tf":2.0},"31":{"tf":1.0},"36":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":2.0}},"e":{"\'":{"df":4,"docs":{"28":{"tf":1.7320508075688772},"30":{"tf":1.0},"33":{"tf":1.0},"44":{"tf":1.0}}},".":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"#":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":2,"docs":{"41":{"tf":1.0},"46":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"r":{"df":1,"docs":{"28":{"tf":1.0}}}},"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"0":{"2":{":":{"1":{"0":{"8":{"df":1,"docs":{"33":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"6":{":":{"1":{"6":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"8":{":":{"1":{"8":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"2":{":":{"2":{"7":{"df":1,"docs":{"29":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"3":{"4":{":":{"4":{"4":{"df":1,"docs":{"29":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"3":{":":{"4":{"9":{"df":1,"docs":{"31":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"6":{"8":{":":{"9":{"7":{"df":1,"docs":{"31":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{"0":{":":{"7":{"3":{"df":1,"docs":{"32":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"46":{"tf":1.0}}}}}},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"(":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"l":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{".":{"c":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"33":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":1,"docs":{"46":{"tf":1.0}}}}}},"df":0,"docs":{}},"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"_":{"c":{"a":{"df":0,"docs":{},"p":{"df":2,"docs":{"31":{"tf":1.0},"32":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"c":{".":{"df":0,"docs":{},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":1,"docs":{"55":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"38":{"tf":1.0},"7":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}},"s":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"i":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"3":{"tf":1.0}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"h":{"df":1,"docs":{"30":{"tf":1.0}}}}}}}}},"r":{"df":0,"docs":{},"i":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"v":{"df":0,"docs":{},"i":{"d":{"df":2,"docs":{"3":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}}},"l":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"df":1,"docs":{"41":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"o":{"c":{"df":1,"docs":{"3":{"tf":1.0}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"/":{"d":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"2":{"tf":1.0}},"e":{":":{"9":{"4":{":":{"1":{"0":{"8":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":1,"docs":{"2":{"tf":2.23606797749979}},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"2":{"tf":1.0}}}}}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"n":{"\'":{"df":0,"docs":{},"t":{"df":3,"docs":{"0":{"tf":1.0},"28":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{}}}},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"\'":{"df":1,"docs":{"49":{"tf":1.4142135623730951}}},"df":5,"docs":{"0":{"tf":1.4142135623730951},"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":2.23606797749979},"55":{"tf":1.0}}}}},"df":0,"docs":{}},"n":{"\'":{"df":0,"docs":{},"t":{"df":1,"docs":{"30":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":1,"docs":{"42":{"tf":1.0}}}},"w":{"df":0,"docs":{},"n":{"c":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{":":{":":{"<":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":2,"docs":{"31":{"tf":1.4142135623730951},"42":{"tf":1.0}}}}}}},"df":0,"docs":{},"e":{"a":{"c":{"df":0,"docs":{},"h":{"df":8,"docs":{"1":{"tf":1.4142135623730951},"15":{"tf":1.4142135623730951},"18":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.0},"38":{"tf":1.0},"4":{"tf":1.0},"5":{"tf":1.0}}}},"df":0,"docs":{}},"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":4,"docs":{"28":{"tf":1.0},"36":{"tf":1.0},"41":{"tf":1.0},"46":{"tf":1.0}}}}},"df":0,"docs":{},"l":{"a":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":2,"docs":{"16":{"tf":1.0},"18":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"0":{"tf":1.0},"50":{"tf":1.0}}}}}}},"f":{"df":1,"docs":{"53":{"tf":1.0}}}},"m":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":7,"docs":{"15":{"tf":1.0},"18":{"tf":1.4142135623730951},"20":{"tf":1.0},"23":{"tf":1.0},"29":{"tf":1.0},"31":{"tf":1.0},"38":{"tf":1.0}}},"y":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":2,"docs":{"18":{"tf":1.0},"29":{"tf":1.0}},"s":{".":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":0,"docs":{},"t":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":2,"docs":{"18":{"tf":1.0},"31":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}}}},"n":{"a":{"b":{"df":0,"docs":{},"l":{"df":1,"docs":{"4":{"tf":1.0}}}},"df":0,"docs":{}},"c":{"a":{"df":0,"docs":{},"p":{"df":0,"docs":{},"s":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":2,"docs":{"18":{"tf":1.4142135623730951},"53":{"tf":1.0}}}}}}},"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"g":{"df":1,"docs":{"1":{"tf":1.0}}}},"df":0,"docs":{}}}}},"d":{"df":5,"docs":{"1":{"tf":1.0},"41":{"tf":1.0},"43":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{":":{":":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"40":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":2,"docs":{"38":{"tf":2.0},"41":{"tf":1.0}}}}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":2,"docs":{"15":{"tf":1.0},"53":{"tf":1.0}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"36":{"tf":1.0}}}},"i":{"df":0,"docs":{},"r":{"df":1,"docs":{"41":{"tf":1.0}}}},"r":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"49":{"tf":1.0},"7":{"tf":1.7320508075688772}}}}}}}}}},"u":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}}}},"v":{"df":1,"docs":{"41":{"tf":1.0}},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":5,"docs":{"14":{"tf":1.0},"3":{"tf":1.4142135623730951},"41":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}}}}}},"q":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"v":{"a":{"df":0,"docs":{},"l":{"df":2,"docs":{"49":{"tf":1.0},"51":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}}},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":3,"docs":{"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.0}}}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"49":{"tf":1.7320508075688772}}}}}},"x":{"a":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":2,"docs":{"25":{"tf":1.0},"7":{"tf":1.0}}}}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"1":{"tf":1.0}}}},"p":{"df":0,"docs":{},"l":{"df":15,"docs":{"1":{"tf":1.4142135623730951},"12":{"tf":1.0},"13":{"tf":1.0},"15":{"tf":1.4142135623730951},"18":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":2.0},"41":{"tf":1.7320508075688772},"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"52":{"tf":1.0},"53":{"tf":2.0},"55":{"tf":1.0},"7":{"tf":1.0}}}}}},"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":3,"docs":{"16":{"tf":1.0},"41":{"tf":1.0},"55":{"tf":1.0}}}}}},"df":0,"docs":{},"e":{"c":{"df":1,"docs":{"2":{"tf":1.0}}},"df":0,"docs":{},"r":{"c":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"30":{"tf":1.0}}},"df":0,"docs":{},"s":{"df":25,"docs":{"1":{"tf":2.0},"10":{"tf":1.4142135623730951},"11":{"tf":1.4142135623730951},"12":{"tf":1.4142135623730951},"13":{"tf":1.4142135623730951},"19":{"tf":1.4142135623730951},"20":{"tf":2.0},"21":{"tf":1.4142135623730951},"22":{"tf":1.4142135623730951},"24":{"tf":1.4142135623730951},"27":{"tf":1.4142135623730951},"30":{"tf":1.0},"32":{"tf":1.0},"33":{"tf":1.4142135623730951},"34":{"tf":1.4142135623730951},"35":{"tf":1.4142135623730951},"36":{"tf":1.4142135623730951},"37":{"tf":1.0},"39":{"tf":1.4142135623730951},"40":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951},"52":{"tf":1.7320508075688772},"8":{"tf":1.4142135623730951},"9":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"20":{"tf":1.0}}}},"t":{"df":1,"docs":{"7":{"tf":1.4142135623730951}}}},"p":{"a":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"46":{"tf":1.4142135623730951}}},"df":0,"docs":{}}},"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":2,"docs":{"1":{"tf":1.0},"42":{"tf":1.0}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":3,"docs":{"23":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0}}}}},"l":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"6":{"tf":1.0}}}}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"r":{"df":3,"docs":{"37":{"tf":1.4142135623730951},"41":{"tf":1.0},"50":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"0":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":6,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"17":{"tf":1.0},"24":{"tf":1.0},"27":{"tf":1.0},"53":{"tf":1.0}}}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":4,"docs":{"41":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.0},"46":{"tf":1.4142135623730951}}},"df":0,"docs":{},"s":{"df":2,"docs":{"4":{"tf":1.4142135623730951},"41":{"tf":1.0}}}},"r":{"df":0,"docs":{},"n":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"10":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":1,"docs":{"26":{"tf":1.0}}}}},"r":{"a":{"_":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"38":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":2,"docs":{"43":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}},"df":1,"docs":{"43":{"tf":1.0}}},"df":0,"docs":{}}}}},"f":{"a":{"c":{"df":0,"docs":{},"t":{"df":2,"docs":{"18":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":2,"docs":{"21":{"tf":1.0},"42":{"tf":1.0}},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"13":{"tf":1.0}}}}}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"r":{"df":3,"docs":{"0":{"tf":1.4142135623730951},"29":{"tf":1.0},"47":{"tf":1.0}}}},"df":0,"docs":{}}}}},"r":{"df":5,"docs":{"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"53":{"tf":1.0}}},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":2,"docs":{"26":{"tf":1.0},"49":{"tf":1.0}}}}}},"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"55":{"tf":1.0}}}}}},"df":0,"docs":{},"w":{"df":5,"docs":{"37":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"53":{"tf":1.0},"55":{"tf":1.0}}}},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"d":{"_":{"1":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"df":1,"docs":{"38":{"tf":2.0}}},"df":0,"docs":{}}},"l":{"df":0,"docs":{},"e":{"df":2,"docs":{"3":{"tf":1.0},"53":{"tf":1.0}},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"(":{"df":0,"docs":{},"|":{"(":{"_":{"df":0,"docs":{},"i":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"n":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"28":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0}}}},"d":{"_":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"(":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.4142135623730951}}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"df":3,"docs":{"17":{"tf":1.0},"26":{"tf":1.0},"42":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"34":{"tf":1.0}},"r":{"df":1,"docs":{"6":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":2,"docs":{"28":{"tf":1.0},"29":{"tf":1.0}}}}}},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":0,"docs":{},"i":{"b":{"df":0,"docs":{},"l":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}}},"n":{"(":{"&":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":11,"docs":{"17":{"tf":1.0},"26":{"tf":1.0},"29":{"tf":1.0},"31":{"tf":1.0},"37":{"tf":1.4142135623730951},"38":{"tf":1.4142135623730951},"48":{"tf":1.0},"49":{"tf":1.0},"51":{"tf":2.0},"53":{"tf":1.7320508075688772},"7":{"tf":1.0}}},"o":{"c":{"df":0,"docs":{},"u":{"df":2,"docs":{"23":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":5,"docs":{"32":{"tf":1.0},"34":{"tf":1.0},"37":{"tf":1.0},"42":{"tf":1.0},"46":{"tf":1.4142135623730951}}}}}},"o":{"df":1,"docs":{"54":{"tf":1.0}}},"r":{"df":0,"docs":{},"m":{"df":4,"docs":{"15":{"tf":1.0},"49":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}},"u":{"df":0,"docs":{},"n":{"d":{"a":{"df":0,"docs":{},"t":{"df":2,"docs":{"0":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"27":{"tf":1.0}}}},"df":0,"docs":{}}},"df":11,"docs":{"16":{"tf":1.4142135623730951},"23":{"tf":2.23606797749979},"24":{"tf":1.7320508075688772},"26":{"tf":1.4142135623730951},"30":{"tf":1.7320508075688772},"31":{"tf":1.7320508075688772},"32":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.7320508075688772},"46":{"tf":1.0},"6":{"tf":1.0}},"w":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"k":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.4142135623730951}}}}}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"a":{"df":1,"docs":{"31":{"tf":1.0}}},"b":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"31":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":1,"docs":{"31":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":3,"docs":{"16":{"tf":1.0},"18":{"tf":1.4142135623730951},"7":{"tf":1.0}}}},"o":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"n":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":8,"docs":{"17":{"tf":1.0},"26":{"tf":1.4142135623730951},"31":{"tf":1.0},"37":{"tf":1.0},"43":{"tf":1.0},"49":{"tf":1.7320508075688772},"51":{"tf":1.0},"7":{"tf":1.4142135623730951}}}}}}},"d":{"df":1,"docs":{"0":{"tf":1.0}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":2,"docs":{"30":{"tf":1.0},"50":{"tf":1.0}}}}}}}}}},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}}},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":4,"docs":{"15":{"tf":1.0},"30":{"tf":1.4142135623730951},"5":{"tf":1.0},"7":{"tf":1.0}}}}},"t":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"r":{"df":1,"docs":{"51":{"tf":1.0}}}},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"(":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"26":{"tf":1.0}}}}}}}}}},"df":0,"docs":{}},"df":1,"docs":{"26":{"tf":1.4142135623730951}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"1":{"tf":2.0}},"h":{"df":0,"docs":{},"u":{"b":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}},"v":{"df":0,"docs":{},"e":{"df":1,"docs":{"26":{"tf":1.0}},"n":{"df":5,"docs":{"23":{"tf":1.0},"26":{"tf":1.0},"3":{"tf":1.0},"34":{"tf":1.0},"42":{"tf":1.0}}}}}},"l":{"df":0,"docs":{},"o":{"b":{"a":{"df":0,"docs":{},"l":{"df":2,"docs":{"41":{"tf":1.0},"53":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"o":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"23":{"tf":1.0},"28":{"tf":1.0},"41":{"tf":1.0}}}},"df":0,"docs":{}},"r":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"34":{"tf":1.0}}}},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"16":{"tf":1.0}}},"u":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}},"df":1,"docs":{"25":{"tf":1.0}},"e":{"_":{"df":0,"docs":{},"s":{"df":2,"docs":{"25":{"tf":2.0},"26":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"i":{"df":1,"docs":{"46":{"tf":1.0}}},"l":{"df":4,"docs":{"41":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":1.0},"7":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":5,"docs":{"48":{"tf":1.7320508075688772},"49":{"tf":2.23606797749979},"51":{"tf":2.0},"52":{"tf":1.4142135623730951},"53":{"tf":2.0}},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"df":4,"docs":{"48":{"tf":1.7320508075688772},"49":{"tf":1.0},"51":{"tf":2.449489742783178},"53":{"tf":1.7320508075688772}}}}}}}}}},"df":0,"docs":{}},"p":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"r":{"d":{"df":0,"docs":{},"w":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"h":{"df":1,"docs":{"1":{"tf":1.0}}}},"v":{"df":0,"docs":{},"e":{"df":1,"docs":{"42":{"tf":1.0}}}}},"df":1,"docs":{"7":{"tf":1.0}},"e":{"a":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"1":{"tf":1.0}}}}},"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":1,"docs":{"13":{"tf":1.7320508075688772}}}}}},"df":3,"docs":{"13":{"tf":1.7320508075688772},"41":{"tf":1.0},"7":{"tf":1.4142135623730951}}}},"df":0,"docs":{},"l":{"d":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":4,"docs":{"14":{"tf":1.4142135623730951},"33":{"tf":1.0},"48":{"tf":1.7320508075688772},"7":{"tf":1.7320508075688772}}}},"p":{"df":2,"docs":{"4":{"tf":1.0},"41":{"tf":1.0}}}},"r":{"df":0,"docs":{},"e":{"df":7,"docs":{"27":{"tf":1.4142135623730951},"37":{"tf":1.0},"41":{"tf":1.0},"47":{"tf":1.0},"48":{"tf":1.0},"5":{"tf":1.4142135623730951},"7":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":2,"docs":{"23":{"tf":1.0},"7":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"28":{"tf":1.0},"37":{"tf":1.0},"6":{"tf":1.0}}}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"34":{"tf":1.0}}}}}},"n":{"df":0,"docs":{},"t":{"df":3,"docs":{"1":{"tf":1.0},"27":{"tf":1.0},"46":{"tf":1.4142135623730951}}}}},"o":{"c":{"df":1,"docs":{"41":{"tf":1.4142135623730951}}},"df":0,"docs":{},"l":{"d":{"df":2,"docs":{"31":{"tf":1.0},"34":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"26":{"tf":1.4142135623730951}}}},"o":{"d":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{},"k":{"df":1,"docs":{"10":{"tf":1.7320508075688772}}}},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"5":{"tf":1.4142135623730951}}}}},"t":{"df":0,"docs":{},"e":{"df":1,"docs":{"36":{"tf":1.0}}},"t":{"df":0,"docs":{},"p":{"df":0,"docs":{},"s":{":":{"/":{"/":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"u":{"b":{".":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{"/":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"0":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{".":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"u":{"b":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"/":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"5":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"i":{".":{"df":1,"docs":{"20":{"tf":1.0}}},"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}}}},"d":{"=":{"\\"":{"1":{"3":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}},"3":{"7":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":3,"docs":{"26":{"tf":1.0},"30":{"tf":1.0},"31":{"tf":1.0}}}}}}}}},"df":0,"docs":{},"i":{"df":2,"docs":{"0":{"tf":1.0},"5":{"tf":1.0}}},"m":{"a":{"df":0,"docs":{},"g":{"df":6,"docs":{"2":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0},"43":{"tf":1.0},"53":{"tf":1.7320508075688772},"6":{"tf":1.0}}}},"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"df":3,"docs":{"48":{"tf":1.4142135623730951},"51":{"tf":2.0},"53":{"tf":1.7320508075688772}},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":11,"docs":{"0":{"tf":1.0},"18":{"tf":1.0},"28":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":1.0},"46":{"tf":1.0},"48":{"tf":1.4142135623730951},"49":{"tf":1.7320508075688772},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.4142135623730951}}}}}}}},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":2,"docs":{"24":{"tf":1.0},"7":{"tf":1.0}}}}}}},"n":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"d":{"df":8,"docs":{"1":{"tf":1.0},"13":{"tf":1.0},"3":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"50":{"tf":1.0},"52":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"41":{"tf":1.0}}}}}}}}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"23":{"tf":1.0}}},"df":0,"docs":{}}}},"x":{"(":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":3,"docs":{"17":{"tf":1.0},"18":{"tf":1.0},"5":{"tf":1.0}}}}},"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"48":{"tf":1.4142135623730951},"51":{"tf":1.4142135623730951},"53":{"tf":1.0}}}},"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"df":4,"docs":{"18":{"tf":1.4142135623730951},"3":{"tf":1.0},"30":{"tf":1.0},"7":{"tf":1.0}}}}}},"i":{"df":0,"docs":{},"t":{"df":3,"docs":{"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}},"i":{"df":15,"docs":{"12":{"tf":1.4142135623730951},"14":{"tf":1.4142135623730951},"18":{"tf":1.0},"26":{"tf":1.0},"30":{"tf":1.4142135623730951},"37":{"tf":1.0},"41":{"tf":1.0},"42":{"tf":1.4142135623730951},"46":{"tf":1.0},"49":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951},"54":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.4142135623730951}}}}},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":2,"docs":{"28":{"tf":1.0},"36":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}},"i":{"d":{"df":2,"docs":{"2":{"tf":1.7320508075688772},"4":{"tf":1.0}}},"df":0,"docs":{}},"t":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"2":{"tf":1.0}}},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":1,"docs":{"55":{"tf":1.0}}}}}},"df":0,"docs":{},"e":{"a":{"d":{"df":2,"docs":{"21":{"tf":1.0},"42":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"u":{"c":{"df":0,"docs":{},"t":{"df":3,"docs":{"1":{"tf":1.0},"41":{"tf":1.0},"53":{"tf":1.0}}}},"df":0,"docs":{}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"r":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":1,"docs":{"46":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{".":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"40":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"v":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"(":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"(":{")":{".":{"df":0,"docs":{},"l":{"a":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"(":{"1":{"2":{"3":{")":{".":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":2,"docs":{"38":{"tf":1.0},"40":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":1,"docs":{"38":{"tf":1.0}}}},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"df":2,"docs":{"37":{"tf":1.0},"38":{"tf":1.0}}}}}},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"37":{"tf":1.0},"38":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":1,"docs":{"38":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"a":{"c":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"d":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"y":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"(":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":1,"docs":{"38":{"tf":1.0}}}},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"n":{"df":1,"docs":{"37":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":3,"docs":{"37":{"tf":1.0},"38":{"tf":1.0},"40":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":12,"docs":{"25":{"tf":1.0},"28":{"tf":1.0},"33":{"tf":1.0},"37":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"54":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":3,"docs":{"28":{"tf":1.0},"37":{"tf":1.0},"52":{"tf":1.0}},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}}}},"f":{"a":{"c":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"m":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"i":{"df":1,"docs":{"25":{"tf":1.0}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":4,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.7320508075688772},"38":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":3,"docs":{"28":{"tf":1.0},"34":{"tf":2.8284271247461903},"36":{"tf":2.23606797749979}}}}}}}},"o":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"df":0,"docs":{}},"r":{"a":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":1,"docs":{"46":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"u":{"c":{"df":2,"docs":{"0":{"tf":1.0},"38":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"v":{"df":0,"docs":{},"o":{"c":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.4142135623730951},"3":{"tf":1.0}}},"df":0,"docs":{},"k":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"38":{"tf":1.0}}}}}},"p":{"c":{".":{"df":0,"docs":{},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{":":{"7":{":":{"2":{"0":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":5,"docs":{"37":{"tf":1.0},"38":{"tf":3.4641016151377544},"43":{"tf":1.0},"51":{"tf":2.0},"52":{"tf":1.0}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"q":{"_":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":1,"docs":{"46":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"_":{"c":{"a":{"df":0,"docs":{},"p":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"a":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":1,"docs":{"46":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"n":{"_":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"46":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"46":{"tf":1.0}}}},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"c":{"a":{"df":0,"docs":{},"p":{".":{"df":0,"docs":{},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"36":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":1,"docs":{"34":{"tf":1.7320508075688772}}}}}}}}},"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":3,"docs":{"34":{"tf":2.0},"35":{"tf":1.0},"36":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"s":{"df":0,"docs":{},"n":{"\'":{"df":0,"docs":{},"t":{"df":1,"docs":{"0":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"17":{"tf":1.0},"18":{"tf":1.0},"29":{"tf":1.0}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":2,"docs":{"53":{"tf":1.0},"6":{"tf":1.0}}}}}}}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":2,"docs":{"31":{"tf":1.0},"42":{"tf":1.0}}}},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"\'":{"df":1,"docs":{"15":{"tf":1.0}}},"df":13,"docs":{"15":{"tf":3.1622776601683795},"16":{"tf":2.23606797749979},"18":{"tf":1.4142135623730951},"23":{"tf":1.0},"24":{"tf":1.0},"29":{"tf":1.0},"3":{"tf":1.0},"30":{"tf":1.4142135623730951},"31":{"tf":1.0},"34":{"tf":1.0},"38":{"tf":2.23606797749979},"42":{"tf":1.0},"6":{"tf":2.449489742783178}}}}}}},"i":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}}},"l":{"a":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"w":{"df":0,"docs":{},"i":{"d":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"38":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":1,"docs":{"38":{"tf":1.0}}}}},"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"df":1,"docs":{"41":{"tf":1.0}}}}},"df":0,"docs":{},"u":{"a":{"df":0,"docs":{},"g":{"df":8,"docs":{"0":{"tf":1.0},"37":{"tf":1.0},"4":{"tf":1.0},"41":{"tf":1.7320508075688772},"48":{"tf":1.0},"50":{"tf":1.4142135623730951},"6":{"tf":1.4142135623730951},"7":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":4,"docs":{"18":{"tf":1.4142135623730951},"29":{"tf":1.0},"30":{"tf":1.0},"35":{"tf":1.0}}}}},"df":0,"docs":{}}}}}}}},"df":2,"docs":{"17":{"tf":1.0},"42":{"tf":1.0}}}}}}},"s":{"df":0,"docs":{},"t":{"df":2,"docs":{"20":{"tf":1.0},"30":{"tf":1.0}}}},"y":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}},"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}}},"v":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{},"g":{"a":{"c":{"df":0,"docs":{},"i":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":2,"docs":{"38":{"tf":2.0},"55":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"34":{"tf":1.0}}}},"t":{"\'":{"df":4,"docs":{"25":{"tf":1.0},"26":{"tf":1.0},"38":{"tf":1.0},"54":{"tf":1.0}}},"df":0,"docs":{}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"(":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"14":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}}}}}}},"df":0,"docs":{}}}}}}}},"df":9,"docs":{"23":{"tf":1.4142135623730951},"28":{"tf":1.0},"3":{"tf":1.0},"36":{"tf":1.0},"37":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951},"5":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.4142135623730951}}},"r":{"a":{"df":0,"docs":{},"g":{"df":3,"docs":{"18":{"tf":1.0},"41":{"tf":1.0},"54":{"tf":1.0}}}},"df":0,"docs":{}}}}},"i":{"b":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"\'":{"df":1,"docs":{"51":{"tf":1.0}}},"df":2,"docs":{"48":{"tf":1.0},"51":{"tf":1.7320508075688772}}}}}}}},"df":0,"docs":{}}},"r":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":3,"docs":{"37":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{"df":2,"docs":{"3":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":0,"docs":{},"w":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":1,"docs":{"52":{"tf":1.0}}}}}}}}}}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"15":{"tf":1.0}}}}},"n":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"1":{"tf":1.0}}}},"df":1,"docs":{"53":{"tf":1.0}}},"k":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":3,"docs":{"1":{"tf":1.0},"13":{"tf":1.0},"48":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"26":{"tf":1.0},"6":{"tf":1.0}}}}}},"v":{"df":0,"docs":{},"e":{"df":1,"docs":{"31":{"tf":1.0}}}}},"o":{"a":{"d":{"df":1,"docs":{"6":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"6":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"41":{"tf":1.0}}},"t":{"df":4,"docs":{"15":{"tf":1.4142135623730951},"23":{"tf":1.0},"3":{"tf":1.0},"53":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"g":{"df":3,"docs":{"1":{"tf":1.0},"14":{"tf":1.0},"16":{"tf":1.0}},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"14":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{":":{":":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":1,"docs":{"14":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":1,"docs":{"14":{"tf":2.0}}}}}},"o":{"df":0,"docs":{},"p":{"df":5,"docs":{"28":{"tf":1.0},"36":{"tf":1.7320508075688772},"41":{"tf":1.0},"46":{"tf":1.0},"49":{"tf":1.0}}}},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"31":{"tf":1.0}}}},"w":{"df":4,"docs":{"37":{"tf":1.0},"41":{"tf":1.4142135623730951},"6":{"tf":1.0},"7":{"tf":1.0}}}}},"m":{"a":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"15":{"tf":1.0},"38":{"tf":1.4142135623730951}}}}},"r":{"df":0,"docs":{},"o":{"\'":{"df":1,"docs":{"53":{"tf":1.0}}},"df":7,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"49":{"tf":1.0},"50":{"tf":1.0},"53":{"tf":1.0},"55":{"tf":1.7320508075688772},"7":{"tf":1.0}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"(":{"_":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},".":{"df":0,"docs":{},"r":{"df":1,"docs":{"37":{"tf":1.0}}}},"df":1,"docs":{"49":{"tf":1.0}},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}}},"k":{"df":0,"docs":{},"e":{"df":11,"docs":{"15":{"tf":1.0},"2":{"tf":1.7320508075688772},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.4142135623730951},"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"52":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}}}},"n":{"a":{"df":0,"docs":{},"g":{"df":4,"docs":{"15":{"tf":1.0},"16":{"tf":1.0},"34":{"tf":1.4142135623730951},"6":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":1,"docs":{"38":{"tf":1.4142135623730951}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"23":{"tf":1.0}}}}}},"u":{"a":{"df":0,"docs":{},"l":{"df":11,"docs":{"0":{"tf":1.0},"15":{"tf":1.0},"16":{"tf":1.0},"18":{"tf":1.7320508075688772},"20":{"tf":1.0},"23":{"tf":1.0},"30":{"tf":1.0},"38":{"tf":1.4142135623730951},"40":{"tf":1.0},"47":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{}}},"p":{"(":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{":":{":":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{":":{":":{"<":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"d":{">":{":":{":":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"29":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":8,"docs":{"23":{"tf":1.4142135623730951},"27":{"tf":1.0},"28":{"tf":1.0},"33":{"tf":1.4142135623730951},"43":{"tf":1.4142135623730951},"46":{"tf":1.0},"53":{"tf":2.23606797749979},"6":{"tf":1.0}}},"r":{"df":0,"docs":{},"k":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}}},"s":{"df":0,"docs":{},"k":{"df":1,"docs":{"20":{"tf":1.0}}}},"t":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"30":{"tf":1.0}}}}}},"x":{"_":{"b":{"df":0,"docs":{},"y":{"_":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"y":{"(":{"df":0,"docs":{},"|":{"(":{"_":{"df":0,"docs":{},"i":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"m":{"df":1,"docs":{"6":{"tf":1.0}}}}}}}},"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"n":{"df":1,"docs":{"1":{"tf":1.0}}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":11,"docs":{"15":{"tf":1.4142135623730951},"16":{"tf":3.605551275463989},"18":{"tf":1.0},"23":{"tf":1.4142135623730951},"30":{"tf":1.7320508075688772},"31":{"tf":1.0},"38":{"tf":1.0},"53":{"tf":3.0},"54":{"tf":1.4142135623730951},"55":{"tf":2.6457513110645907},"6":{"tf":1.4142135623730951}}},"y":{".":{"df":0,"docs":{},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{":":{"7":{":":{"2":{"8":{"df":1,"docs":{"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"!":{"(":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":1,"docs":{"55":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":1,"docs":{"55":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"df":1,"docs":{"53":{"tf":1.4142135623730951}}}}}}}}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"5":{"tf":1.0}}}}}}},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":5,"docs":{"38":{"tf":3.1622776601683795},"39":{"tf":1.0},"40":{"tf":1.0},"41":{"tf":1.0},"52":{"tf":1.0}},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":3,"docs":{"38":{"tf":2.6457513110645907},"51":{"tf":1.7320508075688772},"53":{"tf":1.0}}}}}}}}},"df":0,"docs":{}}},"t":{"a":{"d":{"a":{"df":0,"docs":{},"t":{"a":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"d":{"df":6,"docs":{"15":{"tf":1.0},"18":{"tf":1.7320508075688772},"34":{"tf":1.4142135623730951},"42":{"tf":2.23606797749979},"49":{"tf":1.4142135623730951},"51":{"tf":1.0}}},"df":0,"docs":{}}}}},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{".":{"df":0,"docs":{},"h":{"df":1,"docs":{"49":{"tf":1.0}}}},"_":{"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"51":{"tf":1.0}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"a":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"m":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"51":{"tf":1.4142135623730951}}}}}}}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":1,"docs":{"51":{"tf":1.0}}}}}}}},"p":{"df":0,"docs":{},"p":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":5,"docs":{"0":{"tf":2.449489742783178},"2":{"tf":1.0},"47":{"tf":2.0},"48":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772}}}}}}}},"d":{"d":{"df":0,"docs":{},"l":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":2,"docs":{"14":{"tf":1.0},"41":{"tf":1.0}},"u":{"df":0,"docs":{},"m":{"df":1,"docs":{"22":{"tf":1.0}}}}}},"t":{"df":1,"docs":{"20":{"tf":2.0}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"47":{"tf":1.4142135623730951}}}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"23":{"tf":1.0}}}}}},"s":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"v":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"x":{"df":1,"docs":{"38":{"tf":1.0}}}},"k":{"/":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}}}}},"df":0,"docs":{}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":7,"docs":{"28":{"tf":1.4142135623730951},"30":{"tf":1.4142135623730951},"33":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":1.0}}}}},"o":{"d":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":1,"docs":{"1":{"tf":1.0}},"i":{"df":3,"docs":{"23":{"tf":1.0},"40":{"tf":1.0},"42":{"tf":1.0}}}}},"u":{"df":0,"docs":{},"l":{"df":3,"docs":{"15":{"tf":1.0},"28":{"tf":1.0},"5":{"tf":1.0}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":8,"docs":{"18":{"tf":2.0},"30":{"tf":1.0},"34":{"tf":1.0},"37":{"tf":1.7320508075688772},"41":{"tf":1.7320508075688772},"52":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.0}}}}},"r":{"=":{"\\"":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"a":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"b":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"g":{"_":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":2,"docs":{"38":{"tf":1.0},"52":{"tf":1.0}},"s":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":2,"docs":{"38":{"tf":1.0},"52":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":2,"docs":{"38":{"tf":1.0},"51":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":1,"docs":{"38":{"tf":1.0}},"s":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"u":{"c":{"df":0,"docs":{},"h":{"df":4,"docs":{"0":{"tf":1.4142135623730951},"18":{"tf":1.0},"37":{"tf":1.0},"38":{"tf":1.0}}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"df":2,"docs":{"18":{"tf":1.0},"38":{"tf":1.0}}}}}}},"t":{"df":8,"docs":{"18":{"tf":1.0},"25":{"tf":1.0},"29":{"tf":1.0},"31":{"tf":1.0},"33":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"55":{"tf":1.0}}}}},"n":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"=":{"\\"":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"a":{"df":1,"docs":{"53":{"tf":1.0}}},"b":{"df":1,"docs":{"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":3,"docs":{"12":{"tf":1.0},"16":{"tf":1.0},"53":{"tf":1.4142135623730951}}}},"v":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":8,"docs":{"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"48":{"tf":1.0},"5":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0}}}}}},"df":1,"docs":{"55":{"tf":1.0}},"e":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.0}},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"t":{"df":1,"docs":{"41":{"tf":1.0}}}},"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":3,"docs":{"1":{"tf":1.0},"18":{"tf":1.0},"22":{"tf":1.0}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"0":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"e":{"d":{"df":4,"docs":{"18":{"tf":1.0},"30":{"tf":1.0},"31":{"tf":1.0},"42":{"tf":1.0}}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"w":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"k":{"df":1,"docs":{"7":{"tf":1.0}}}}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}}},"w":{"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":1,"docs":{"27":{"tf":1.0}},"e":{".":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"27":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":3,"docs":{"18":{"tf":2.23606797749979},"20":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"20":{"tf":1.4142135623730951}}}}},"x":{"df":0,"docs":{},"t":{"df":2,"docs":{"30":{"tf":1.0},"32":{"tf":1.0}}}}},"o":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"48":{"tf":1.0},"7":{"tf":1.4142135623730951}}}},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.0}}}}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"t":{"d":{"df":2,"docs":{"48":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}},"d":{"df":0,"docs":{},"e":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"n":{"df":1,"docs":{"20":{"tf":1.0}},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"<":{"[":{"df":0,"docs":{},"u":{"8":{"df":1,"docs":{"55":{"tf":1.0}}},"df":0,"docs":{}}},"_":{"df":1,"docs":{"55":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"r":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"18":{"tf":1.0},"30":{"tf":1.4142135623730951},"4":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"e":{"df":8,"docs":{"1":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0},"24":{"tf":1.0},"36":{"tf":1.0},"37":{"tf":1.0},"51":{"tf":1.0}}},"i":{"c":{"df":1,"docs":{"37":{"tf":1.0}}},"df":0,"docs":{},"f":{"df":8,"docs":{"18":{"tf":2.23606797749979},"19":{"tf":1.0},"20":{"tf":2.23606797749979},"34":{"tf":2.0},"35":{"tf":1.0},"36":{"tf":1.0},"37":{"tf":1.0},"38":{"tf":1.0}},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"\'":{"df":1,"docs":{"20":{"tf":1.4142135623730951}}},"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":2,"docs":{"18":{"tf":1.7320508075688772},"20":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":3,"docs":{"49":{"tf":1.0},"51":{"tf":1.4142135623730951},"52":{"tf":1.0}},"e":{"d":{"(":{"&":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"w":{"df":8,"docs":{"18":{"tf":1.7320508075688772},"22":{"tf":1.0},"32":{"tf":1.0},"33":{"tf":1.0},"38":{"tf":1.0},"4":{"tf":1.0},"41":{"tf":1.0},"43":{"tf":1.0}}}},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{":":{":":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"df":1,"docs":{"53":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"m":{"_":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"15":{"tf":1.0},"18":{"tf":1.7320508075688772}}}}},"df":0,"docs":{}}}},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"(":{"df":1,"docs":{"18":{"tf":1.0}}},"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{".":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"46":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"y":{"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"46":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"df":1,"docs":{"42":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":13,"docs":{"15":{"tf":2.8284271247461903},"16":{"tf":1.4142135623730951},"18":{"tf":4.242640687119285},"23":{"tf":2.23606797749979},"24":{"tf":1.4142135623730951},"29":{"tf":1.0},"30":{"tf":1.4142135623730951},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"35":{"tf":1.0},"38":{"tf":1.4142135623730951},"42":{"tf":2.449489742783178},"6":{"tf":1.4142135623730951}},"s":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"4":{":":{"2":{"2":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"7":{":":{"2":{"7":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"9":{":":{"3":{"3":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"3":{"2":{":":{"4":{"2":{"df":1,"docs":{"17":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"6":{":":{"4":{"3":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"5":{":":{"4":{"7":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"6":{"3":{":":{"6":{"3":{"df":1,"docs":{"20":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":2,"docs":{"1":{"tf":1.0},"26":{"tf":1.0}}}}}},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"46":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}},"c":{"c":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"20":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"i":{"df":1,"docs":{"0":{"tf":1.0}}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"26":{"tf":1.0}}}}}}},"k":{"(":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}},"a":{"df":0,"docs":{},"y":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":1,"docs":{"51":{"tf":1.0}}},"n":{"c":{"df":1,"docs":{"42":{"tf":1.0}}},"df":9,"docs":{"14":{"tf":1.0},"18":{"tf":1.0},"25":{"tf":1.0},"3":{"tf":1.0},"31":{"tf":1.0},"38":{"tf":1.4142135623730951},"41":{"tf":1.0},"5":{"tf":1.0},"55":{"tf":1.0}}},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":2,"docs":{"4":{"tf":1.0},"41":{"tf":1.0}}},"r":{"df":3,"docs":{"15":{"tf":1.0},"54":{"tf":1.0},"55":{"tf":1.4142135623730951}}}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":1,"docs":{"53":{"tf":1.0}}},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"52":{"tf":1.0}}}}}}},"r":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"25":{"tf":1.0}}}}},"df":1,"docs":{"20":{"tf":1.0}}},"s":{"df":1,"docs":{"7":{"tf":1.0}}},"u":{"df":0,"docs":{},"t":{"df":2,"docs":{"38":{"tf":1.0},"41":{"tf":1.0}},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"15":{"tf":1.0},"18":{"tf":1.0}}}}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":3,"docs":{"16":{"tf":1.0},"28":{"tf":1.0},"36":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"i":{"d":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":4,"docs":{"28":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"52":{"tf":1.0}},"f":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":2,"docs":{"11":{"tf":1.0},"12":{"tf":1.0}}}}}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"21":{"tf":1.4142135623730951}}}}}}},"w":{"df":0,"docs":{},"n":{"_":{"df":0,"docs":{},"t":{"c":{"b":{"df":1,"docs":{"46":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":2,"docs":{"16":{"tf":2.8284271247461903},"42":{"tf":2.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"df":2,"docs":{"25":{"tf":1.0},"26":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}},":":{"#":{"df":0,"docs":{},"x":{"df":1,"docs":{"25":{"tf":1.0}}}},"df":0,"docs":{}},"df":3,"docs":{"25":{"tf":1.0},"26":{"tf":1.0},"27":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{".":{"c":{"a":{"df":0,"docs":{},"p":{"(":{")":{".":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"p":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"26":{"tf":1.0}}}}}}},"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":5,"docs":{"23":{"tf":1.7320508075688772},"25":{"tf":1.0},"26":{"tf":2.0},"38":{"tf":1.0},"5":{"tf":1.4142135623730951}},"p":{"df":0,"docs":{},"l":{"a":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"d":{"df":1,"docs":{"25":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"(":{"#":{"[":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"(":{"d":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"c":{"df":0,"docs":{},"o":{"d":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"[":{"0":{"df":0,"docs":{},"x":{"df":0,"docs":{},"e":{"df":1,"docs":{"25":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"i":{"c":{"\'":{"df":1,"docs":{"10":{"tf":1.0}}},"df":4,"docs":{"10":{"tf":1.4142135623730951},"49":{"tf":1.0},"8":{"tf":1.0},"9":{"tf":1.0}},"k":{"df":1,"docs":{"41":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"r":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":0,"docs":{},"h":{"df":2,"docs":{"18":{"tf":1.0},"30":{"tf":1.0}}}}},"df":0,"docs":{}}},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}}}}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":9,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.0},"20":{"tf":1.0},"27":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951},"50":{"tf":1.0}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}}}}},"df":0,"docs":{},"t":{"df":7,"docs":{"0":{"tf":1.7320508075688772},"41":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":1.0},"47":{"tf":1.7320508075688772},"5":{"tf":1.4142135623730951},"6":{"tf":1.7320508075688772}},"i":{"c":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":5,"docs":{"15":{"tf":1.0},"30":{"tf":1.4142135623730951},"34":{"tf":1.0},"4":{"tf":1.0},"5":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"s":{"df":0,"docs":{},"s":{"df":5,"docs":{"17":{"tf":1.0},"34":{"tf":1.0},"38":{"tf":1.7320508075688772},"43":{"tf":1.0},"6":{"tf":1.0}}}},"t":{"c":{"df":0,"docs":{},"h":{"df":2,"docs":{"1":{"tf":1.7320508075688772},"53":{"tf":1.0}}}},"df":0,"docs":{},"h":{"=":{"\\"":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":1,"docs":{"53":{"tf":1.0}}}}}}}},"d":{"=":{"\\"":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{},"s":{"/":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"4":{":":{"3":{"6":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{":":{"3":{"1":{"df":1,"docs":{"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"b":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"9":{":":{"1":{"8":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"2":{":":{"3":{"9":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{":":{"4":{"6":{"df":1,"docs":{"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"36":{"tf":1.0}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":2,"docs":{"21":{"tf":1.0},"27":{"tf":1.0}}}}},"s":{"=":{"\\"":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}},"w":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"h":{"df":0,"docs":{},"y":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"30":{"tf":1.0}}}},"df":7,"docs":{"15":{"tf":1.0},"23":{"tf":1.4142135623730951},"28":{"tf":1.0},"30":{"tf":1.7320508075688772},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"42":{"tf":1.0}}},"df":0,"docs":{}}}}},"i":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"1":{"tf":1.0}}}},"df":0,"docs":{},"e":{"c":{"df":1,"docs":{"41":{"tf":1.0}}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":4,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":1.7320508075688772},"3":{"tf":1.0},"38":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":5,"docs":{"15":{"tf":1.0},"33":{"tf":1.0},"53":{"tf":1.0},"54":{"tf":1.0},"55":{"tf":1.0}}}}}}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"38":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"b":{"df":0,"docs":{},"l":{"df":2,"docs":{"23":{"tf":1.0},"49":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"c":{"a":{"df":0,"docs":{},"r":{"d":{"df":1,"docs":{"52":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"p":{"=":{"\\"":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"e":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":4,"docs":{"1":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.0},"5":{"tf":1.0}}}}},"s":{"df":1,"docs":{"7":{"tf":1.0}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"12":{"tf":1.0},"7":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"s":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":2,"docs":{"37":{"tf":1.0},"38":{"tf":1.0}}}}},"df":0,"docs":{},"e":{"df":1,"docs":{"32":{"tf":1.0}}}},"n":{"df":0,"docs":{},"t":{"df":3,"docs":{"10":{"tf":1.0},"16":{"tf":1.0},"33":{"tf":1.0}}}},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"=":{"\\"":{"1":{"0":{"0":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"0":{"0":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"v":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":2,"docs":{"34":{"tf":1.4142135623730951},"6":{"tf":1.0}}}}}}}},"o":{"c":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":3,"docs":{"42":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":1.0}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":2,"docs":{"18":{"tf":1.0},"41":{"tf":1.0}}}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"\'":{"df":1,"docs":{"7":{"tf":1.0}}},"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":2,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}},"df":10,"docs":{"2":{"tf":1.0},"21":{"tf":1.0},"22":{"tf":1.0},"25":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.0},"43":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"31":{"tf":1.0}}}}}}},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":5,"docs":{"0":{"tf":1.0},"3":{"tf":1.0},"41":{"tf":1.0},"5":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":7,"docs":{"0":{"tf":1.4142135623730951},"48":{"tf":1.0},"49":{"tf":1.7320508075688772},"51":{"tf":2.0},"52":{"tf":1.4142135623730951},"53":{"tf":2.449489742783178},"55":{"tf":1.0}},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"d":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":5,"docs":{"48":{"tf":1.4142135623730951},"49":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":2.449489742783178},"53":{"tf":2.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"v":{"df":0,"docs":{},"i":{"d":{"df":9,"docs":{"18":{"tf":1.0},"20":{"tf":1.0},"23":{"tf":1.4142135623730951},"4":{"tf":1.0},"41":{"tf":1.0},"53":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.0}}},"df":0,"docs":{}}}}},"t":{"df":0,"docs":{},"r":{":":{":":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"o":{"df":0,"docs":{},"f":{"!":{"(":{"_":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"26":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{")":{".":{"c":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{":":{":":{"<":{"df":0,"docs":{},"u":{"8":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"54":{"tf":1.0}}}},"u":{"b":{"df":1,"docs":{"54":{"tf":2.0}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":1,"docs":{"48":{"tf":1.0}}},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"s":{"df":2,"docs":{"27":{"tf":1.0},"30":{"tf":1.4142135623730951}}}}}},"t":{"df":2,"docs":{"53":{"tf":1.0},"55":{"tf":1.0}}}}},"q":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":1,"docs":{"7":{"tf":1.0}}}}},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}}}},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"df":3,"docs":{"18":{"tf":1.7320508075688772},"29":{"tf":1.0},"52":{"tf":1.0}},"e":{"<":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"e":{"a":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"42":{"tf":1.0}}}},"d":{"df":4,"docs":{"18":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"6":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"0":{"tf":1.0},"1":{"tf":1.0},"47":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"46":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"v":{"df":2,"docs":{"34":{"tf":1.0},"38":{"tf":2.23606797749979}},"e":{"df":0,"docs":{},"r":{"\'":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}}}},"k":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"42":{"tf":1.0}},"l":{"df":0,"docs":{},"y":{"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"a":{"df":0,"docs":{},"t":{"(":{")":{"\'":{"df":1,"docs":{"42":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"v":{"df":1,"docs":{"38":{"tf":1.7320508075688772}}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":10,"docs":{"15":{"tf":2.0},"16":{"tf":1.0},"18":{"tf":2.23606797749979},"20":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.4142135623730951},"30":{"tf":1.0},"38":{"tf":1.4142135623730951},"40":{"tf":1.0},"6":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"n":{"c":{"df":1,"docs":{"15":{"tf":1.0}}},"df":0,"docs":{}}}}}},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"\'":{"df":1,"docs":{"55":{"tf":1.0}}},"_":{"a":{":":{"#":{"df":0,"docs":{},"x":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"_":{"df":0,"docs":{},"s":{"df":1,"docs":{"54":{"tf":1.4142135623730951}}},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":2,"docs":{"53":{"tf":2.6457513110645907},"54":{"tf":1.0}}},"b":{":":{"#":{"df":0,"docs":{},"x":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":2,"docs":{"53":{"tf":2.449489742783178},"54":{"tf":1.0}}},"df":0,"docs":{}},"b":{"df":1,"docs":{"54":{"tf":1.4142135623730951}}},"df":8,"docs":{"16":{"tf":1.4142135623730951},"17":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.7320508075688772},"31":{"tf":1.0},"53":{"tf":1.7320508075688772},"54":{"tf":1.4142135623730951},"55":{"tf":1.0}}}},"s":{"df":0,"docs":{},"t":{"df":7,"docs":{"28":{"tf":1.4142135623730951},"30":{"tf":1.0},"33":{"tf":1.4142135623730951},"38":{"tf":1.7320508075688772},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0}}}}}},"l":{"_":{"a":{".":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"_":{"(":{"&":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"b":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":1,"docs":{"31":{"tf":1.0}}},"b":{"df":1,"docs":{"31":{"tf":1.0}}},"df":0,"docs":{}},"a":{"df":0,"docs":{},"t":{"df":2,"docs":{"37":{"tf":1.0},"6":{"tf":1.7320508075688772}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":2,"docs":{"18":{"tf":1.0},"3":{"tf":1.0}}}}},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"z":{"df":0,"docs":{},"v":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":1,"docs":{"4":{"tf":1.0}}}}}},"p":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"40":{"tf":1.0}}},"y":{"_":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"38":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":2,"docs":{"1":{"tf":1.0},"4":{"tf":1.4142135623730951}}},"y":{"\'":{"df":1,"docs":{"3":{"tf":1.0}}},"df":0,"docs":{}}}}}}}},"r":{"(":{"c":{"df":2,"docs":{"25":{"tf":1.0},"54":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":3,"docs":{"15":{"tf":1.0},"23":{"tf":1.4142135623730951},"34":{"tf":1.0}}}}}},"q":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":7,"docs":{"0":{"tf":1.0},"1":{"tf":1.0},"3":{"tf":1.0},"4":{"tf":1.0},"53":{"tf":1.0},"54":{"tf":1.0},"7":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":2,"docs":{"25":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951}}}},"t":{"df":1,"docs":{"31":{"tf":1.0}}}},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"c":{"df":3,"docs":{"0":{"tf":1.0},"16":{"tf":1.0},"47":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}},"p":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"df":1,"docs":{"16":{"tf":1.0}}}}}},"t":{"df":1,"docs":{"2":{"tf":1.0}},"r":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"t":{"df":2,"docs":{"16":{"tf":1.0},"21":{"tf":1.0}}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"<":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}}}},"df":0,"docs":{}}}}}},"df":2,"docs":{"13":{"tf":1.0},"51":{"tf":1.0}}}}}},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":1,"docs":{"17":{"tf":1.0}}}}}},"u":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":3,"docs":{"16":{"tf":1.4142135623730951},"20":{"tf":1.7320508075688772},"55":{"tf":1.4142135623730951}}}}}},"u":{"df":0,"docs":{},"s":{"df":1,"docs":{"18":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":5,"docs":{"15":{"tf":1.0},"20":{"tf":1.4142135623730951},"22":{"tf":1.0},"27":{"tf":1.4142135623730951},"41":{"tf":1.0}}}}}},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"(":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"s":{"df":1,"docs":{"13":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"t":{"a":{"c":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"s":{"df":2,"docs":{"12":{"tf":1.0},"13":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":4,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"50":{"tf":1.0},"7":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}},"df":20,"docs":{"0":{"tf":1.4142135623730951},"12":{"tf":1.4142135623730951},"13":{"tf":1.0},"14":{"tf":1.0},"16":{"tf":1.4142135623730951},"17":{"tf":1.0},"18":{"tf":2.449489742783178},"20":{"tf":1.4142135623730951},"23":{"tf":2.23606797749979},"25":{"tf":1.4142135623730951},"26":{"tf":2.23606797749979},"27":{"tf":1.0},"28":{"tf":1.7320508075688772},"33":{"tf":1.4142135623730951},"34":{"tf":1.4142135623730951},"41":{"tf":2.0},"45":{"tf":1.0},"46":{"tf":1.4142135623730951},"6":{"tf":2.8284271247461903},"7":{"tf":2.0}}}},"u":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"n":{"df":11,"docs":{"15":{"tf":1.0},"2":{"tf":1.4142135623730951},"22":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":2.0},"4":{"tf":1.4142135623730951},"48":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":11,"docs":{"0":{"tf":2.0},"13":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":2.449489742783178},"48":{"tf":1.0},"49":{"tf":1.0},"50":{"tf":1.4142135623730951},"53":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.7320508075688772}}}}}},"s":{"df":0,"docs":{},"t":{"\'":{"df":1,"docs":{"18":{"tf":1.0}}},"c":{"df":3,"docs":{"0":{"tf":1.0},"3":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"d":{"df":0,"docs":{},"o":{"c":{"_":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"k":{"df":2,"docs":{"18":{"tf":1.0},"20":{"tf":1.0}}}}}}},"df":3,"docs":{"5":{"tf":2.8284271247461903},"50":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}},"df":17,"docs":{"0":{"tf":2.449489742783178},"1":{"tf":1.7320508075688772},"3":{"tf":1.4142135623730951},"34":{"tf":1.0},"37":{"tf":1.4142135623730951},"38":{"tf":1.7320508075688772},"4":{"tf":2.0},"40":{"tf":1.0},"41":{"tf":2.0},"48":{"tf":1.4142135623730951},"5":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772},"54":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.7320508075688772}}}}}},"s":{"a":{"df":0,"docs":{},"f":{"df":0,"docs":{},"e":{"df":1,"docs":{"55":{"tf":1.0}}}},"k":{"df":0,"docs":{},"e":{"df":1,"docs":{"5":{"tf":1.0}}}},"m":{"df":0,"docs":{},"e":{"df":4,"docs":{"41":{"tf":1.0},"42":{"tf":1.0},"46":{"tf":1.0},"50":{"tf":1.4142135623730951}}},"p":{"df":0,"docs":{},"l":{"df":1,"docs":{"16":{"tf":1.0}}}}},"w":{"df":1,"docs":{"41":{"tf":1.0}}}},"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":1,"docs":{"18":{"tf":1.0}}}}},"r":{"a":{"df":0,"docs":{},"t":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"6":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":1,"docs":{"14":{"tf":1.0}},"e":{"a":{"df":0,"docs":{},"r":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}}},"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"d":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":2,"docs":{"37":{"tf":2.23606797749979},"38":{"tf":1.0}}},"y":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"(":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":1,"docs":{"38":{"tf":1.0}}}},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"n":{"df":1,"docs":{"37":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":3,"docs":{"37":{"tf":1.0},"38":{"tf":1.0},"40":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":1,"docs":{"18":{"tf":1.4142135623730951}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"df":0,"docs":{},"e":{"df":7,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.0},"30":{"tf":1.0},"40":{"tf":1.0},"55":{"tf":1.0}},"k":{"df":1,"docs":{"24":{"tf":1.0}}},"n":{"df":1,"docs":{"41":{"tf":1.0}}}},"l":{"4":{"/":{"c":{"a":{"df":0,"docs":{},"p":{"/":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{".":{"c":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{".":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"#":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"d":{".":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{":":{":":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"20":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{".":{"df":0,"docs":{},"h":{"df":2,"docs":{"37":{"tf":1.0},"41":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},":":{":":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{":":{":":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"20":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"18":{"tf":1.7320508075688772},"20":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":3,"docs":{"17":{"tf":1.0},"26":{"tf":1.0},"29":{"tf":1.0}},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}}}}}},"c":{"a":{"df":0,"docs":{},"p":{":":{":":{"c":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.7320508075688772}}}}}}}},"df":0,"docs":{}}},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":3,"docs":{"24":{"tf":1.0},"32":{"tf":1.0},"46":{"tf":1.0}}}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":1,"docs":{"34":{"tf":1.0}}}}}}}}},"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":2,"docs":{"34":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"r":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"a":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}},"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":2,"docs":{"34":{"tf":1.0},"35":{"tf":1.0}}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":4,"docs":{"18":{"tf":1.0},"37":{"tf":1.4142135623730951},"38":{"tf":1.0},"46":{"tf":1.4142135623730951}},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{":":{":":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"df":1,"docs":{"19":{"tf":1.0}}}}}},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"19":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"t":{"c":{"b":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"u":{"df":0,"docs":{},"m":{"df":1,"docs":{"15":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":4,"docs":{"17":{"tf":1.0},"29":{"tf":1.0},"30":{"tf":1.0},"31":{"tf":1.0}},"e":{"d":{":":{":":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"<":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"15":{"tf":1.0}},"e":{":":{":":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"24":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"t":{"df":1,"docs":{"15":{"tf":1.0}}}},"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":2,"docs":{"23":{"tf":1.0},"32":{"tf":1.0}},"e":{":":{":":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"_":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"24":{"tf":1.0}}}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"t":{"c":{"b":{"df":1,"docs":{"15":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"v":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":1,"docs":{"23":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":1,"docs":{"15":{"tf":1.0}},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":0,"docs":{},"s":{":":{":":{"a":{"df":0,"docs":{},"l":{"df":2,"docs":{"20":{"tf":1.0},"21":{"tf":1.0}}}},"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"21":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"27":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":2,"docs":{"15":{"tf":1.0},"23":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"x":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"s":{"df":1,"docs":{"24":{"tf":1.0}}}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}}}}}}},"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}}}},"d":{"df":0,"docs":{},"e":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"14":{"tf":1.0}},"l":{"df":0,"docs":{},"n":{"!":{"(":{"\\"":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"7":{"tf":1.0}}}}}}},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"37":{"tf":1.4142135623730951},"38":{"tf":1.4142135623730951}}}},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"16":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"16":{"tf":1.0}}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{".":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"25":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{":":{":":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{":":{":":{"c":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":1,"docs":{"31":{"tf":1.7320508075688772}},"e":{".":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{".":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"34":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"v":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":0,"docs":{},"e":{".":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"27":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"<":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"26":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":2,"docs":{"20":{"tf":1.0},"31":{"tf":1.4142135623730951}}}}},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":1,"docs":{"7":{"tf":1.4142135623730951}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{":":{":":{"df":0,"docs":{},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"20":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{":":{":":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"18":{"tf":1.0},"24":{"tf":1.0}}}}}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"40":{"tf":1.0}}}}}}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"c":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":0,"docs":{},"e":{"_":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"16":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":1,"docs":{"30":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"v":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":1,"docs":{"27":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"p":{"c":{"_":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":3,"docs":{"38":{"tf":1.0},"39":{"tf":1.0},"51":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":3,"docs":{"38":{"tf":1.0},"39":{"tf":1.0},"51":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"_":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"a":{"c":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"55":{"tf":1.0}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"27":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"40":{"tf":1.0}}}},"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"r":{"df":0,"docs":{},"q":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"a":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}},"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":1,"docs":{"34":{"tf":1.0}}}}}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"l":{"df":0,"docs":{},"i":{"b":{"df":2,"docs":{"37":{"tf":1.0},"6":{"tf":1.0}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"g":{"df":1,"docs":{"14":{"tf":1.0}}}}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"_":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{":":{":":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":1,"docs":{"49":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"y":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":1,"docs":{"55":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"51":{"tf":1.0}}}}}}}}},"df":0,"docs":{}}}}},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{":":{":":{"c":{"a":{"df":0,"docs":{},"t":{"c":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"50":{"tf":1.0}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":1,"docs":{"50":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"v":{"a":{"df":0,"docs":{},"r":{"df":2,"docs":{"53":{"tf":1.0},"55":{"tf":1.0}}}},"df":0,"docs":{}},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"s":{"df":0,"docs":{},"{":{",":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"52":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"{":{"d":{"df":0,"docs":{},"e":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"l":{"df":0,"docs":{},"n":{"df":1,"docs":{"48":{"tf":1.0}}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":3,"docs":{"48":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":1.0}}}}}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":1,"docs":{"34":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"a":{"c":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"s":{"df":1,"docs":{"12":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{":":{":":{"c":{"a":{"df":0,"docs":{},"t":{"c":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"9":{"tf":1.0}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":1,"docs":{"10":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"df":1,"docs":{"7":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"13":{"tf":1.0},"7":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":21,"docs":{"0":{"tf":3.4641016151377544},"1":{"tf":1.0},"14":{"tf":1.0},"15":{"tf":2.23606797749979},"16":{"tf":1.0},"18":{"tf":1.7320508075688772},"2":{"tf":1.4142135623730951},"20":{"tf":1.0},"23":{"tf":2.23606797749979},"3":{"tf":1.0},"30":{"tf":1.4142135623730951},"37":{"tf":1.7320508075688772},"38":{"tf":1.4142135623730951},"4":{"tf":1.0},"40":{"tf":1.0},"41":{"tf":2.8284271247461903},"47":{"tf":1.7320508075688772},"5":{"tf":1.4142135623730951},"55":{"tf":1.4142135623730951},"6":{"tf":3.0},"7":{"tf":1.7320508075688772}},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"s":{"/":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{".":{"df":0,"docs":{},"h":{"df":1,"docs":{"41":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{".":{"df":0,"docs":{},"h":{"df":1,"docs":{"37":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":2,"docs":{"18":{"tf":1.0},"4":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"f":{":":{":":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":2,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.0}}}},"n":{"d":{"df":4,"docs":{"38":{"tf":2.0},"39":{"tf":1.0},"41":{"tf":1.0},"52":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"\'":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}},"df":1,"docs":{"38":{"tf":1.7320508075688772}}}}},"df":0,"docs":{}},"p":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"4":{"tf":1.0}}}},"df":0,"docs":{}},"q":{"df":0,"docs":{},"u":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"c":{"df":2,"docs":{"36":{"tf":1.0},"46":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}}},"r":{"d":{"df":1,"docs":{"52":{"tf":1.0}}},"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"l":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":2,"docs":{"33":{"tf":1.0},"36":{"tf":1.0}},"e":{".":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":1,"docs":{"36":{"tf":1.0}}}}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"33":{"tf":1.0}}}}}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"_":{"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"r":{"(":{"*":{"c":{"df":1,"docs":{"33":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"c":{"a":{"df":0,"docs":{},"p":{".":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"32":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":3,"docs":{"32":{"tf":1.0},"33":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"df":4,"docs":{"28":{"tf":1.0},"34":{"tf":1.0},"45":{"tf":1.0},"46":{"tf":1.4142135623730951}}}}},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"_":{"df":0,"docs":{},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":5,"docs":{"28":{"tf":1.0},"30":{"tf":1.4142135623730951},"31":{"tf":1.7320508075688772},"32":{"tf":1.4142135623730951},"45":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"33":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":10,"docs":{"28":{"tf":2.6457513110645907},"30":{"tf":1.4142135623730951},"33":{"tf":1.4142135623730951},"36":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":2.23606797749979},"52":{"tf":1.0}}}},"df":1,"docs":{"1":{"tf":1.0}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"\'":{"df":1,"docs":{"52":{"tf":1.0}}},".":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}},"p":{"df":0,"docs":{},"p":{"_":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"52":{"tf":1.0}},"l":{"(":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":4,"docs":{"4":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":1.0},"54":{"tf":1.0}}}},"i":{"c":{"df":1,"docs":{"7":{"tf":1.0}}},"df":0,"docs":{}}}},"t":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"r":{"df":1,"docs":{"51":{"tf":1.0}}}}},"df":6,"docs":{"10":{"tf":1.4142135623730951},"23":{"tf":1.0},"28":{"tf":1.0},"41":{"tf":1.0},"46":{"tf":1.0},"5":{"tf":1.0}},"u":{"df":0,"docs":{},"p":{"df":1,"docs":{"1":{"tf":1.0}}}},"v":{"a":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"=":{"\\"":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"a":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"b":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"h":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":1,"docs":{"1":{"tf":1.0}}}},"p":{"df":0,"docs":{},"e":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}},"r":{"df":0,"docs":{},"e":{"df":4,"docs":{"23":{"tf":1.0},"53":{"tf":2.8284271247461903},"54":{"tf":1.4142135623730951},"55":{"tf":2.0}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":1,"docs":{"2":{"tf":1.4142135623730951}}}}},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"0":{"tf":1.0}}}}}},"w":{"df":1,"docs":{"41":{"tf":1.0}}}}},"i":{"d":{"df":0,"docs":{},"e":{"b":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"5":{"tf":1.0}}}},"df":0,"docs":{}},"df":1,"docs":{"38":{"tf":1.4142135623730951}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"a":{"df":0,"docs":{},"l":{"df":2,"docs":{"19":{"tf":1.0},"20":{"tf":1.7320508075688772}}},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":2,"docs":{"49":{"tf":1.0},"7":{"tf":1.0}}}}}},"df":0,"docs":{}}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":2,"docs":{"42":{"tf":1.0},"46":{"tf":1.0}},"l":{"df":0,"docs":{},"i":{"df":2,"docs":{"41":{"tf":1.0},"46":{"tf":1.0}}}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"l":{"df":2,"docs":{"14":{"tf":1.0},"28":{"tf":1.0}},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"49":{"tf":1.0}}}}},"i":{"df":1,"docs":{"44":{"tf":1.0}},"f":{"df":0,"docs":{},"i":{"df":1,"docs":{"3":{"tf":1.0}}}}}}},"u":{"df":0,"docs":{},"l":{"df":9,"docs":{"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.0},"48":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}},"t":{"a":{"df":0,"docs":{},"n":{"df":1,"docs":{"18":{"tf":1.0}}}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"l":{"df":1,"docs":{"18":{"tf":1.0}}}}},"t":{"df":0,"docs":{},"u":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}},"df":0,"docs":{}}},"z":{"df":0,"docs":{},"e":{"=":{"\\"":{"0":{"df":0,"docs":{},"x":{"1":{"_":{"0":{"0":{"0":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"_":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"18":{"tf":1.4142135623730951},"31":{"tf":1.7320508075688772}}}}},"df":0,"docs":{}},"df":8,"docs":{"12":{"tf":1.7320508075688772},"13":{"tf":1.0},"16":{"tf":3.0},"18":{"tf":1.7320508075688772},"20":{"tf":1.4142135623730951},"23":{"tf":1.0},"25":{"tf":1.0},"38":{"tf":1.0}}}}},"l":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"e":{"df":1,"docs":{"55":{"tf":1.0}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"t":{"<":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}}}}}}}},"df":5,"docs":{"15":{"tf":1.7320508075688772},"18":{"tf":3.0},"20":{"tf":1.7320508075688772},"26":{"tf":1.0},"31":{"tf":1.4142135623730951}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"<":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}}}}}}}},"df":0,"docs":{}}}}}}}}}},"m":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":1,"docs":{"32":{"tf":1.0}},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"23":{"tf":1.0}}}}}}}},"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"38":{"tf":1.0}}}}}}},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"p":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":2,"docs":{"24":{"tf":1.0},"29":{"tf":1.0}}}}}}}},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":2,"docs":{"33":{"tf":1.0},"52":{"tf":1.0}}}},"w":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}}}}}},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"41":{"tf":1.0}}}},"u":{"df":0,"docs":{},"r":{"c":{"df":2,"docs":{"48":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}},"p":{"a":{"c":{"df":0,"docs":{},"e":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"5":{":":{"2":{"0":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"6":{":":{"4":{"9":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"5":{"1":{":":{"5":{"4":{"df":1,"docs":{"26":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{"3":{":":{"8":{"4":{"df":1,"docs":{"26":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":10,"docs":{"15":{"tf":1.4142135623730951},"23":{"tf":3.0},"25":{"tf":1.0},"26":{"tf":1.0},"28":{"tf":1.0},"33":{"tf":1.4142135623730951},"43":{"tf":1.4142135623730951},"46":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.7320508075688772}}}},"df":0,"docs":{},"w":{"df":0,"docs":{},"n":{"df":4,"docs":{"34":{"tf":1.0},"37":{"tf":2.0},"41":{"tf":2.6457513110645907},"6":{"tf":1.0}}}}},"df":0,"docs":{},"e":{"c":{"df":1,"docs":{"3":{"tf":1.0}},"i":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"34":{"tf":1.0},"38":{"tf":1.0},"55":{"tf":1.0}}}},"df":0,"docs":{},"f":{"df":4,"docs":{"0":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.7320508075688772},"34":{"tf":1.0}},"i":{"df":5,"docs":{"18":{"tf":1.4142135623730951},"20":{"tf":1.0},"38":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.4142135623730951}}}}}},"df":0,"docs":{}}},"r":{"c":{"_":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"t":{"a":{"c":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":2,"docs":{"12":{"tf":1.0},"13":{"tf":1.0}}}}}},"df":4,"docs":{"11":{"tf":1.0},"12":{"tf":2.0},"37":{"tf":1.0},"41":{"tf":1.0}}}},"df":0,"docs":{},"n":{"d":{"a":{"df":0,"docs":{},"r":{"d":{"df":2,"docs":{"41":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"t":{"df":8,"docs":{"1":{"tf":1.4142135623730951},"15":{"tf":1.0},"2":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.4142135623730951},"54":{"tf":1.0}}}},"t":{"df":0,"docs":{},"e":{"df":3,"docs":{"20":{"tf":1.4142135623730951},"42":{"tf":1.0},"53":{"tf":1.0}}},"i":{"c":{"df":4,"docs":{"14":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0},"47":{"tf":1.0}}},"df":0,"docs":{}}}},"d":{"df":1,"docs":{"7":{"tf":1.7320508075688772}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"\'":{"df":1,"docs":{"55":{"tf":1.0}}},"df":39,"docs":{"1":{"tf":2.6457513110645907},"10":{"tf":1.0},"11":{"tf":1.0},"12":{"tf":1.0},"13":{"tf":1.0},"14":{"tf":1.4142135623730951},"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":1.4142135623730951},"19":{"tf":1.0},"20":{"tf":1.0},"21":{"tf":1.0},"22":{"tf":1.0},"24":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0},"27":{"tf":1.0},"29":{"tf":1.0},"30":{"tf":1.4142135623730951},"31":{"tf":1.0},"32":{"tf":1.0},"33":{"tf":2.0},"34":{"tf":1.0},"35":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.4142135623730951},"39":{"tf":1.0},"40":{"tf":1.0},"41":{"tf":1.4142135623730951},"42":{"tf":2.0},"43":{"tf":1.7320508075688772},"44":{"tf":2.0},"45":{"tf":1.4142135623730951},"46":{"tf":2.449489742783178},"52":{"tf":1.0},"54":{"tf":1.0},"55":{"tf":1.0},"8":{"tf":1.0},"9":{"tf":1.0}}}},"o":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"g":{"df":1,"docs":{"41":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":1,"docs":{"53":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"u":{"c":{"df":0,"docs":{},"t":{"df":6,"docs":{"23":{"tf":1.0},"25":{"tf":1.0},"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.0},"54":{"tf":1.0}},"u":{"df":0,"docs":{},"r":{"df":3,"docs":{"23":{"tf":1.7320508075688772},"25":{"tf":1.0},"7":{"tf":1.0}}}}}},"df":0,"docs":{}}},"u":{"b":{"df":1,"docs":{"6":{"tf":1.0}}},"d":{"df":0,"docs":{},"i":{"df":1,"docs":{"5":{"tf":1.0}}}},"df":0,"docs":{}}},"u":{"b":{"df":1,"docs":{"46":{"tf":1.4142135623730951}},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"3":{"tf":1.0}}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"q":{"df":0,"docs":{},"u":{"df":1,"docs":{"42":{"tf":1.0}}}}}}},"c":{"c":{"df":0,"docs":{},"e":{"df":1,"docs":{"32":{"tf":1.0}}}},"df":0,"docs":{},"h":{"df":7,"docs":{"14":{"tf":1.0},"16":{"tf":1.0},"37":{"tf":1.4142135623730951},"47":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":1,"docs":{"55":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"m":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":3,"docs":{"0":{"tf":1.0},"50":{"tf":1.0},"7":{"tf":1.0}}}},"s":{"df":1,"docs":{"54":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"7":{"tf":1.0}}},"df":0,"docs":{}}}}}},"y":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":3,"docs":{"53":{"tf":2.449489742783178},"54":{"tf":1.0},"55":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"s":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"40":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"\'":{"df":1,"docs":{"16":{"tf":1.0}}},"df":6,"docs":{"15":{"tf":1.0},"47":{"tf":1.0},"51":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772},"54":{"tf":1.0},"6":{"tf":1.0}}}}}}}},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":2,"docs":{"15":{"tf":1.0},"23":{"tf":1.0}}}},"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":4,"docs":{"31":{"tf":1.0},"38":{"tf":1.4142135623730951},"43":{"tf":1.0},"50":{"tf":1.0}}}},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":5,"docs":{"0":{"tf":1.0},"18":{"tf":1.7320508075688772},"3":{"tf":1.7320508075688772},"31":{"tf":1.0},"7":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"k":{"\'":{"df":14,"docs":{"12":{"tf":1.4142135623730951},"13":{"tf":1.0},"16":{"tf":1.0},"20":{"tf":1.0},"23":{"tf":1.7320508075688772},"25":{"tf":1.4142135623730951},"26":{"tf":1.7320508075688772},"27":{"tf":1.0},"28":{"tf":1.4142135623730951},"33":{"tf":1.4142135623730951},"43":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951},"6":{"tf":1.4142135623730951},"7":{"tf":1.0}}},".":{"df":0,"docs":{},"m":{"df":0,"docs":{},"k":{":":{"3":{"1":{":":{"3":{"6":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"/":{".":{"c":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"o":{"/":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"df":1,"docs":{"3":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":3,"docs":{"23":{"tf":1.0},"25":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"j":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"4":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"7":{"tf":1.0}}}}}}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":5,"docs":{"15":{"tf":1.0},"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":2.0},"20":{"tf":1.0}}}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":5,"docs":{"28":{"tf":1.7320508075688772},"29":{"tf":1.4142135623730951},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"33":{"tf":1.0}}}}},"p":{"a":{"df":0,"docs":{},"w":{"df":0,"docs":{},"n":{"df":5,"docs":{"37":{"tf":1.7320508075688772},"38":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0}}}}},"df":0,"docs":{}},"r":{"c":{"/":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"_":{"df":0,"docs":{},"v":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":0,"docs":{},"e":{".":{"df":0,"docs":{},"r":{"df":1,"docs":{"43":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"r":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":17,"docs":{"0":{"tf":1.4142135623730951},"14":{"tf":1.0},"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":1.0},"20":{"tf":1.0},"23":{"tf":1.0},"26":{"tf":1.4142135623730951},"28":{"tf":1.0},"3":{"tf":1.0},"34":{"tf":1.4142135623730951},"41":{"tf":4.0},"44":{"tf":1.0},"45":{"tf":1.0},"46":{"tf":2.23606797749979},"6":{"tf":2.449489742783178},"7":{"tf":1.7320508075688772}}}}},"df":4,"docs":{"15":{"tf":1.7320508075688772},"18":{"tf":1.0},"49":{"tf":1.4142135623730951},"7":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":2,"docs":{"18":{"tf":1.0},"34":{"tf":1.0}}}},"m":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"31":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"7":{"tf":1.4142135623730951}}}}}},"s":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"51":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":2,"docs":{"1":{"tf":1.4142135623730951},"41":{"tf":1.0}}}},"x":{"df":0,"docs":{},"t":{"df":7,"docs":{"0":{"tf":1.0},"1":{"tf":1.0},"2":{"tf":1.0},"38":{"tf":1.0},"47":{"tf":1.0},"5":{"tf":1.0},"6":{"tf":1.0}}}}},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"v":{"df":1,"docs":{"1":{"tf":1.0}}}}}}}},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"51":{"tf":1.0},"55":{"tf":1.0}}}},"o":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":2,"docs":{"1":{"tf":1.4142135623730951},"41":{"tf":1.0}}}},"u":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":1,"docs":{"37":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"e":{"a":{"d":{"\'":{"df":3,"docs":{"12":{"tf":1.4142135623730951},"15":{"tf":1.0},"18":{"tf":2.449489742783178}}},"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"7":{"5":{":":{"7":{"9":{"df":2,"docs":{"37":{"tf":1.0},"38":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"8":{"1":{":":{"8":{"5":{"df":1,"docs":{"37":{"tf":1.0}}},"7":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":6,"docs":{"15":{"tf":1.7320508075688772},"23":{"tf":1.0},"37":{"tf":3.0},"38":{"tf":1.7320508075688772},"41":{"tf":1.4142135623730951},"7":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":2,"docs":{"47":{"tf":1.0},"7":{"tf":1.0}}}},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":3,"docs":{"37":{"tf":1.0},"42":{"tf":1.0},"47":{"tf":1.0}}}}}}},"u":{"df":1,"docs":{"15":{"tf":1.0}}}},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":6,"docs":{"13":{"tf":1.0},"16":{"tf":1.0},"2":{"tf":1.0},"53":{"tf":1.0},"54":{"tf":1.0},"6":{"tf":1.7320508075688772}}}}},"l":{"df":2,"docs":{"37":{"tf":1.0},"41":{"tf":1.0}}},"o":{"d":{"df":0,"docs":{},"o":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":2,"docs":{"38":{"tf":1.0},"55":{"tf":1.0}}}}}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":1,"docs":{"15":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"l":{"df":2,"docs":{"2":{"tf":1.0},"53":{"tf":1.4142135623730951}}}},"p":{"df":4,"docs":{"14":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.0},"5":{"tf":1.0}}},"w":{"a":{"df":0,"docs":{},"r":{"d":{"df":2,"docs":{"18":{"tf":1.0},"41":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"r":{"a":{"c":{"df":0,"docs":{},"k":{"df":2,"docs":{"18":{"tf":1.0},"42":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"24":{"tf":1.0},"49":{"tf":1.0}}}},"n":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"t":{"df":3,"docs":{"15":{"tf":1.4142135623730951},"23":{"tf":1.4142135623730951},"25":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"df":1,"docs":{"23":{"tf":1.0}}}},"i":{"df":3,"docs":{"26":{"tf":1.0},"33":{"tf":1.0},"46":{"tf":1.4142135623730951}},"m":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.7320508075688772}}}}}}}},"df":0,"docs":{}},"v":{"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"e":{"df":1,"docs":{"16":{"tf":2.6457513110645907}}}}},"u":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":3,"docs":{"17":{"tf":1.0},"20":{"tf":1.0},"54":{"tf":1.0}}}},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":5,"docs":{"0":{"tf":1.4142135623730951},"1":{"tf":2.0},"18":{"tf":1.0},"47":{"tf":1.0},"6":{"tf":1.0}}}}}}},"w":{"df":0,"docs":{},"o":{"df":12,"docs":{"1":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.4142135623730951},"30":{"tf":1.0},"31":{"tf":1.4142135623730951},"37":{"tf":1.0},"38":{"tf":1.7320508075688772},"41":{"tf":1.0},"5":{"tf":1.4142135623730951},"51":{"tf":1.0},"53":{"tf":1.4142135623730951}}}},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"\'":{"df":1,"docs":{"18":{"tf":1.0}}},"df":17,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"15":{"tf":2.8284271247461903},"16":{"tf":1.0},"18":{"tf":2.449489742783178},"20":{"tf":1.0},"23":{"tf":2.0},"30":{"tf":1.0},"38":{"tf":1.4142135623730951},"42":{"tf":1.0},"44":{"tf":1.4142135623730951},"48":{"tf":1.0},"51":{"tf":2.449489742783178},"52":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951},"54":{"tf":1.7320508075688772},"55":{"tf":2.0}}},"i":{"c":{"df":1,"docs":{"7":{"tf":1.0}}},"df":0,"docs":{}}}}},"u":{"1":{"6":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"6":{"4":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"8":{"df":3,"docs":{"25":{"tf":1.0},"54":{"tf":1.0},"55":{"tf":1.0}}},"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"38":{"tf":1.0},"51":{"tf":1.0}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"55":{"tf":1.0}}}},"s":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"1":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"g":{"df":1,"docs":{"15":{"tf":1.0}}}}}},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"k":{"df":1,"docs":{"6":{"tf":1.0}}}}},"m":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"26":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"s":{"a":{"df":0,"docs":{},"f":{"df":4,"docs":{"26":{"tf":1.0},"33":{"tf":1.0},"54":{"tf":1.4142135623730951},"55":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":3,"docs":{"31":{"tf":1.0},"38":{"tf":1.0},"42":{"tf":1.0}}}},"y":{"df":0,"docs":{},"p":{"df":6,"docs":{"16":{"tf":2.0},"17":{"tf":1.0},"18":{"tf":2.23606797749979},"30":{"tf":2.449489742783178},"31":{"tf":2.0},"42":{"tf":2.449489742783178}},"e":{"d":{"\'":{"df":2,"docs":{"30":{"tf":1.0},"31":{"tf":1.0}}},"_":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":4,"docs":{"17":{"tf":1.0},"18":{"tf":1.0},"29":{"tf":1.0},"31":{"tf":1.0}}}},"df":0,"docs":{}}},"y":{"df":0,"docs":{},"t":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.0}}}}}},"p":{"d":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"20":{"tf":1.0}}}},"df":0,"docs":{}},"df":7,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"28":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"46":{"tf":1.0},"54":{"tf":1.0}}},"s":{"df":44,"docs":{"0":{"tf":1.4142135623730951},"1":{"tf":1.4142135623730951},"13":{"tf":1.4142135623730951},"14":{"tf":1.0},"15":{"tf":1.4142135623730951},"16":{"tf":1.4142135623730951},"18":{"tf":1.7320508075688772},"19":{"tf":1.0},"20":{"tf":2.449489742783178},"21":{"tf":1.0},"22":{"tf":1.0},"23":{"tf":1.4142135623730951},"24":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.7320508075688772},"27":{"tf":1.4142135623730951},"28":{"tf":1.0},"29":{"tf":1.0},"30":{"tf":1.7320508075688772},"33":{"tf":1.0},"34":{"tf":1.7320508075688772},"35":{"tf":1.0},"36":{"tf":2.0},"37":{"tf":2.23606797749979},"38":{"tf":2.23606797749979},"39":{"tf":1.0},"4":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":2.0},"47":{"tf":1.0},"48":{"tf":1.0},"49":{"tf":1.0},"5":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":2.449489742783178},"53":{"tf":1.0},"54":{"tf":1.4142135623730951},"55":{"tf":1.0},"6":{"tf":2.23606797749979},"7":{"tf":1.0},"9":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"26":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":1,"docs":{"15":{"tf":1.4142135623730951}},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":6,"docs":{"0":{"tf":1.7320508075688772},"15":{"tf":1.0},"16":{"tf":1.0},"34":{"tf":1.4142135623730951},"41":{"tf":1.0},"6":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"i":{"df":0,"docs":{},"z":{"df":9,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"25":{"tf":1.4142135623730951},"26":{"tf":2.0},"28":{"tf":1.4142135623730951},"31":{"tf":1.4142135623730951},"53":{"tf":2.449489742783178},"54":{"tf":1.0},"55":{"tf":1.0}}}}},"t":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"c":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"16":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":0,"docs":{},"e":{"_":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"16":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"x":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":1,"docs":{"31":{"tf":1.0}},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"14":{"tf":1.0}}}}}},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"=":{"\\"":{"0":{"df":0,"docs":{},"x":{"2":{"_":{"0":{"0":{"0":{"_":{"0":{"0":{"0":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"0":{"0":{"_":{"0":{"0":{"0":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"d":{"df":1,"docs":{"15":{"tf":1.0}}},"df":0,"docs":{}},"u":{"df":8,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"20":{"tf":2.0},"24":{"tf":1.0},"28":{"tf":1.0},"38":{"tf":1.0},"53":{"tf":1.4142135623730951},"55":{"tf":1.0}}}},"r":{"!":{"(":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"a":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"b":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"53":{"tf":1.0},"54":{"tf":1.0}},"i":{"a":{"b":{"df":0,"docs":{},"l":{"df":2,"docs":{"3":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"s":{"df":1,"docs":{"37":{"tf":1.0}}}}},"df":0,"docs":{},"s":{"a":{"df":1,"docs":{"52":{"tf":1.0}}},"df":0,"docs":{}}}},"i":{"a":{"df":3,"docs":{"15":{"tf":1.0},"34":{"tf":1.0},"38":{"tf":1.0}}},"c":{"df":0,"docs":{},"e":{"df":1,"docs":{"52":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"df":2,"docs":{"38":{"tf":1.0},"52":{"tf":1.0}}}},"r":{"df":0,"docs":{},"t":{"df":0,"docs":{},"u":{"a":{"df":0,"docs":{},"l":{"df":10,"docs":{"15":{"tf":1.4142135623730951},"23":{"tf":2.449489742783178},"25":{"tf":1.0},"26":{"tf":1.0},"33":{"tf":1.4142135623730951},"46":{"tf":1.0},"53":{"tf":1.4142135623730951},"54":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{}}}}},"s":{"c":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{"df":1,"docs":{"4":{"tf":2.23606797749979}}}},"df":0,"docs":{}}},"df":0,"docs":{},"p":{"a":{"c":{"df":0,"docs":{},"e":{"df":3,"docs":{"23":{"tf":2.23606797749979},"26":{"tf":1.4142135623730951},"27":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":3,"docs":{"19":{"tf":1.0},"20":{"tf":1.4142135623730951},"36":{"tf":1.0}}}},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"4":{"tf":1.0},"53":{"tf":1.0}}}},"t":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"21":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"k":{"df":3,"docs":{"18":{"tf":1.4142135623730951},"31":{"tf":1.7320508075688772},"42":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}}}},"y":{"df":6,"docs":{"14":{"tf":1.0},"18":{"tf":2.0},"38":{"tf":1.0},"46":{"tf":1.0},"55":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{},"e":{"\'":{"df":0,"docs":{},"v":{"df":3,"docs":{"31":{"tf":1.0},"37":{"tf":1.0},"49":{"tf":1.0}}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":1,"docs":{"15":{"tf":1.0}}}}},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"df":2,"docs":{"16":{"tf":1.0},"3":{"tf":1.0}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"16":{"tf":1.0}}}}}}},"o":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":7,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.0},"28":{"tf":1.4142135623730951},"30":{"tf":1.0},"42":{"tf":1.0},"6":{"tf":1.0}}}}}},"i":{"d":{"df":0,"docs":{},"e":{"df":1,"docs":{"38":{"tf":1.0}},"r":{"df":1,"docs":{"52":{"tf":1.0}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":1,"docs":{"20":{"tf":1.0}}},"h":{"df":1,"docs":{"18":{"tf":1.0}}}},"t":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"g":{"_":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}},"e":{"df":0,"docs":{},"s":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":1,"docs":{"51":{"tf":1.0}},"s":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"5":{"tf":1.0}}}},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":2,"docs":{"42":{"tf":1.0},"55":{"tf":1.0}}}}}}}},"o":{"df":0,"docs":{},"n":{"\'":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}},"df":0,"docs":{}},"r":{"d":{"df":3,"docs":{"15":{"tf":1.0},"20":{"tf":1.4142135623730951},"38":{"tf":1.4142135623730951}}},"df":0,"docs":{},"k":{"df":9,"docs":{"1":{"tf":1.0},"18":{"tf":1.0},"2":{"tf":1.0},"27":{"tf":1.4142135623730951},"37":{"tf":1.0},"4":{"tf":1.0},"46":{"tf":1.0},"47":{"tf":1.0},"6":{"tf":1.0}},"f":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":1,"docs":{"1":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":3,"docs":{"3":{"tf":1.7320508075688772},"4":{"tf":1.7320508075688772},"5":{"tf":1.7320508075688772}},"e":{"df":0,"docs":{},"s":{"/":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"/":{".":{"c":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"o":{"/":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"df":1,"docs":{"3":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"48":{"tf":1.0}}}}}}},"i":{"df":0,"docs":{},"p":{"c":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":1,"docs":{"3":{"tf":1.0}}}}}}}},"df":0,"docs":{}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":20,"docs":{"15":{"tf":1.0},"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":2.0},"20":{"tf":1.0},"23":{"tf":1.0},"25":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951},"28":{"tf":1.7320508075688772},"29":{"tf":1.4142135623730951},"3":{"tf":1.4142135623730951},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"33":{"tf":1.0},"37":{"tf":1.7320508075688772},"38":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0},"7":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"l":{"d":{"!":{"\\\\":{"df":0,"docs":{},"n":{"df":1,"docs":{"33":{"tf":1.0}}}},"df":0,"docs":{}},"/":{"df":0,"docs":{},"p":{"d":{"df":0,"docs":{},"s":{"/":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"7":{":":{"2":{"2":{"df":1,"docs":{"48":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"7":{":":{"2":{"0":{"df":1,"docs":{"14":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"1":{"df":1,"docs":{"14":{"tf":1.0}}},"df":0,"docs":{}},"7":{":":{"1":{"7":{"df":1,"docs":{"7":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":3,"docs":{"33":{"tf":1.0},"48":{"tf":2.0},"7":{"tf":2.0}}},"df":0,"docs":{}},"s":{"df":1,"docs":{"42":{"tf":1.0}}}}},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"15":{"tf":1.0}},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"15":{"tf":1.0},"51":{"tf":1.0},"55":{"tf":1.0}}}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"(":{"df":0,"docs":{},"|":{"df":1,"docs":{"14":{"tf":1.0}}}},"df":3,"docs":{"1":{"tf":1.0},"36":{"tf":1.4142135623730951},"6":{"tf":1.0}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":4,"docs":{"24":{"tf":1.0},"48":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0}}}}}}}}},"x":{"df":1,"docs":{"7":{"tf":1.0}},"m":{"df":0,"docs":{},"l":{"df":1,"docs":{"7":{"tf":1.0}}}}},"y":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"\'":{"df":0,"docs":{},"r":{"df":1,"docs":{"37":{"tf":1.0}}}},"df":0,"docs":{}}}},"z":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"i":{"df":1,"docs":{"52":{"tf":1.0}}},"y":{":":{":":{"df":0,"docs":{},"{":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":2,"docs":{"18":{"tf":1.0},"20":{"tf":1.0}}}}}}}},"breadcrumbs":{"root":{"0":{"1":{"6":{"df":0,"docs":{},"x":{"df":1,"docs":{"16":{"tf":1.0}}}},"df":0,"docs":{}},"2":{"df":1,"docs":{"16":{"tf":1.0}}},"df":2,"docs":{"25":{"tf":1.0},"53":{"tf":2.0}},"x":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"8":{"0":{"0":{"1":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"8":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"1":{"1":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"0":{"0":{"0":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"9":{"0":{"0":{"_":{"0":{"0":{"0":{"0":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"df":1,"docs":{"25":{"tf":1.0}}}},"f":{"0":{"0":{"d":{"df":1,"docs":{"13":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"1":{"0":{".":{"a":{"df":1,"docs":{"52":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"1":{".":{"a":{"df":1,"docs":{"54":{"tf":1.4142135623730951}}},"b":{"df":1,"docs":{"55":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"3":{"df":1,"docs":{"38":{"tf":1.0}}},"df":1,"docs":{"16":{"tf":1.4142135623730951}}},"3":{"3":{"7":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"df":3,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"16":{"tf":1.4142135623730951}}},"4":{"df":1,"docs":{"16":{"tf":1.0}}},"5":{"df":1,"docs":{"16":{"tf":1.0}}},"6":{"df":1,"docs":{"54":{"tf":1.0}}},"df":2,"docs":{"18":{"tf":1.0},"31":{"tf":1.4142135623730951}}},"2":{".":{"3":{"df":1,"docs":{"15":{"tf":1.0}}},"4":{".":{"1":{"df":1,"docs":{"18":{"tf":1.0}}},"2":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":3,"docs":{"16":{"tf":1.0},"18":{"tf":1.0},"30":{"tf":1.0}}},"a":{"df":1,"docs":{"8":{"tf":1.4142135623730951}}},"b":{"df":1,"docs":{"9":{"tf":1.4142135623730951}}},"c":{"df":1,"docs":{"10":{"tf":1.4142135623730951}}},"d":{"df":1,"docs":{"11":{"tf":1.4142135623730951}}},"df":0,"docs":{},"e":{"df":1,"docs":{"12":{"tf":1.4142135623730951}}},"f":{"df":1,"docs":{"13":{"tf":1.4142135623730951}}},"g":{"df":1,"docs":{"14":{"tf":2.0}}}},"7":{"df":1,"docs":{"16":{"tf":1.0}}},"df":3,"docs":{"16":{"tf":1.0},"47":{"tf":1.0},"50":{"tf":1.0}}},"3":{".":{"a":{"df":1,"docs":{"16":{"tf":1.7320508075688772}}},"b":{"df":1,"docs":{"17":{"tf":1.7320508075688772}}},"c":{"df":1,"docs":{"18":{"tf":2.449489742783178}}},"d":{"df":1,"docs":{"19":{"tf":1.4142135623730951}}},"df":0,"docs":{},"e":{"df":1,"docs":{"20":{"tf":1.7320508075688772}}},"f":{"df":1,"docs":{"21":{"tf":1.4142135623730951}}},"g":{"df":1,"docs":{"22":{"tf":1.4142135623730951}}}},"3":{"df":1,"docs":{"28":{"tf":1.0}}},"7":{"df":2,"docs":{"12":{"tf":1.0},"13":{"tf":1.0}}},"df":1,"docs":{"24":{"tf":1.0}}},"4":{".":{"2":{".":{"4":{"df":1,"docs":{"40":{"tf":1.0}}},"df":0,"docs":{}},"df":1,"docs":{"38":{"tf":1.0}}},"a":{"df":1,"docs":{"24":{"tf":1.4142135623730951}}},"b":{"df":2,"docs":{"25":{"tf":2.0},"33":{"tf":1.0}}},"c":{"df":2,"docs":{"26":{"tf":2.0},"33":{"tf":1.0}}},"d":{"df":2,"docs":{"27":{"tf":1.4142135623730951},"33":{"tf":1.0}}},"df":0,"docs":{}},"0":{"9":{"6":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"38":{"tf":1.0}}},"5":{".":{"a":{"df":1,"docs":{"29":{"tf":2.0}}},"b":{"df":1,"docs":{"30":{"tf":1.4142135623730951}}},"c":{"df":2,"docs":{"31":{"tf":2.0},"42":{"tf":1.0}}},"d":{"df":1,"docs":{"32":{"tf":1.7320508075688772}}},"df":0,"docs":{},"e":{"df":3,"docs":{"33":{"tf":1.7320508075688772},"44":{"tf":1.0},"46":{"tf":1.0}}},"f":{"df":2,"docs":{"34":{"tf":1.4142135623730951},"46":{"tf":1.0}}},"g":{"df":2,"docs":{"35":{"tf":1.4142135623730951},"46":{"tf":1.0}}},"h":{"df":2,"docs":{"36":{"tf":1.4142135623730951},"46":{"tf":1.0}}}},"2":{"5":{"3":{"df":0,"docs":{},"e":{"d":{"c":{"1":{"df":0,"docs":{},"e":{"d":{"1":{"2":{"df":1,"docs":{"1":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":3,"docs":{"20":{"tf":1.0},"44":{"tf":1.0},"45":{"tf":1.0}},"h":{"df":2,"docs":{"41":{"tf":1.0},"46":{"tf":1.0}}}},"6":{".":{"a":{"df":1,"docs":{"38":{"tf":2.0}}},"b":{"df":1,"docs":{"39":{"tf":1.4142135623730951}}},"c":{"df":1,"docs":{"40":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":2,"docs":{"41":{"tf":1.0},"47":{"tf":1.0}}},"7":{".":{"1":{".":{"3":{"df":1,"docs":{"23":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"a":{"df":3,"docs":{"41":{"tf":1.0},"42":{"tf":1.4142135623730951},"43":{"tf":1.0}}},"b":{"df":3,"docs":{"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.4142135623730951}}},"c":{"df":2,"docs":{"41":{"tf":1.0},"44":{"tf":1.4142135623730951}}},"d":{"df":2,"docs":{"41":{"tf":1.0},"45":{"tf":1.4142135623730951}}},"df":0,"docs":{},"e":{"df":5,"docs":{"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"8":{"c":{"a":{"0":{"df":0,"docs":{},"e":{"1":{"9":{"3":{"9":{"d":{"c":{"1":{".":{".":{"5":{"2":{"5":{"3":{"df":0,"docs":{},"e":{"d":{"c":{"1":{"df":0,"docs":{},"e":{"d":{"1":{"2":{"df":1,"docs":{"1":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"1":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"9":{".":{"1":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"_":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"26":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"b":{"a":{"d":{"df":0,"docs":{},"g":{"df":1,"docs":{"38":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"c":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}},"df":0,"docs":{}}}},"df":2,"docs":{"33":{"tf":1.0},"53":{"tf":1.0}},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}}}}}}},"a":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"v":{"df":1,"docs":{"18":{"tf":1.0}}}},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"(":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"a":{".":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"b":{".":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":1,"docs":{"31":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"t":{"df":0,"docs":{},"r":{"a":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"55":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"c":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":2,"docs":{"12":{"tf":1.0},"13":{"tf":1.0}}}},"s":{"df":0,"docs":{},"s":{"df":6,"docs":{"15":{"tf":1.4142135623730951},"20":{"tf":1.0},"26":{"tf":1.0},"28":{"tf":1.0},"34":{"tf":1.0},"55":{"tf":1.7320508075688772}}}}},"o":{"df":0,"docs":{},"r":{"d":{"df":3,"docs":{"18":{"tf":1.0},"42":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{},"k":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"g":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}}}}}}},"q":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":1,"docs":{"18":{"tf":1.0}}}}}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"15":{"tf":1.0}}}}}}},"d":{"d":{"df":6,"docs":{"13":{"tf":1.0},"14":{"tf":1.0},"17":{"tf":1.0},"29":{"tf":1.0},"45":{"tf":1.0},"7":{"tf":1.0}},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"2":{"tf":1.0},"55":{"tf":1.0}}}},"r":{"_":{"df":0,"docs":{},"o":{"df":0,"docs":{},"f":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"y":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"d":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"(":{"1":{"df":1,"docs":{"46":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":1,"docs":{"26":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":19,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":2.23606797749979},"23":{"tf":3.3166247903554},"24":{"tf":1.0},"25":{"tf":1.4142135623730951},"26":{"tf":1.7320508075688772},"27":{"tf":1.0},"28":{"tf":1.4142135623730951},"30":{"tf":2.0},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"33":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951},"54":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.0}}}}}}},"df":1,"docs":{"41":{"tf":1.4142135623730951}},"j":{"df":0,"docs":{},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"12":{"tf":1.0}}}}}},"v":{"a":{"df":0,"docs":{},"n":{"c":{"df":2,"docs":{"18":{"tf":1.0},"31":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{},"g":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"41":{"tf":1.0}},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"48":{"tf":1.0}}}}}}},"df":0,"docs":{}},"h":{"df":0,"docs":{},"e":{"a":{"d":{"df":1,"docs":{"1":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}},"l":{"df":0,"docs":{},"i":{"a":{"df":2,"docs":{"23":{"tf":1.4142135623730951},"51":{"tf":1.7320508075688772}},"s":{"df":1,"docs":{"15":{"tf":1.0}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"(":{"4":{"0":{"9":{"6":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":2,"docs":{"18":{"tf":1.0},"25":{"tf":1.0}}}}},"l":{"df":0,"docs":{},"o":{"c":{"df":20,"docs":{"13":{"tf":1.0},"15":{"tf":1.7320508075688772},"16":{"tf":1.4142135623730951},"17":{"tf":1.0},"18":{"tf":2.8284271247461903},"19":{"tf":1.0},"20":{"tf":1.7320508075688772},"21":{"tf":1.0},"22":{"tf":1.0},"24":{"tf":1.0},"29":{"tf":1.0},"30":{"tf":2.0},"31":{"tf":1.4142135623730951},"32":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":2.8284271247461903},"46":{"tf":1.4142135623730951},"53":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.7320508075688772}}},"df":0,"docs":{},"w":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}},"o":{"df":0,"docs":{},"n":{"df":2,"docs":{"37":{"tf":1.0},"41":{"tf":1.0}},"g":{"df":3,"docs":{"26":{"tf":1.0},"30":{"tf":1.0},"55":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"e":{"a":{"d":{"df":0,"docs":{},"i":{"df":2,"docs":{"18":{"tf":1.0},"36":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"w":{"a":{"df":0,"docs":{},"y":{"df":3,"docs":{"31":{"tf":1.0},"38":{"tf":1.0},"55":{"tf":1.0}}}},"df":0,"docs":{}}},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"15":{"tf":1.0}}}}}}},"n":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"y":{"df":0,"docs":{},"z":{"df":1,"docs":{"4":{"tf":2.0}}}}}},"d":{"/":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"55":{"tf":1.0}}}}},"y":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"28":{"tf":1.0}}}}}},"p":{"df":0,"docs":{},"i":{"df":8,"docs":{"0":{"tf":2.449489742783178},"23":{"tf":1.4142135623730951},"30":{"tf":1.0},"34":{"tf":1.0},"47":{"tf":1.0},"48":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"p":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"3":{"tf":1.0}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"24":{"tf":1.0}}}}}}}}},"r":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"23":{"tf":2.23606797749979}},"e":{"\'":{"df":1,"docs":{"23":{"tf":1.0}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"\'":{"df":0,"docs":{},"t":{"df":1,"docs":{"37":{"tf":1.0}}}},"df":0,"docs":{}}},"g":{"df":0,"docs":{},"u":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}}}}}},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"d":{"df":4,"docs":{"15":{"tf":1.0},"31":{"tf":1.0},"51":{"tf":1.0},"55":{"tf":1.0}}},"df":0,"docs":{}}}},"r":{"a":{"df":0,"docs":{},"y":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"a":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"4":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"s":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"q":{"!":{"(":{"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{".":{"df":0,"docs":{},"l":{"a":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"38":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"25":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"f":{"df":1,"docs":{"25":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":1,"docs":{"32":{"tf":1.0}}}}},"df":1,"docs":{"32":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"df":2,"docs":{"53":{"tf":1.0},"54":{"tf":1.0}}}}},"o":{"c":{"df":1,"docs":{"15":{"tf":1.0}},"i":{"df":8,"docs":{"15":{"tf":1.4142135623730951},"16":{"tf":1.0},"23":{"tf":1.0},"34":{"tf":1.4142135623730951},"35":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"46":{"tf":1.0}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"m":{"df":4,"docs":{"0":{"tf":1.4142135623730951},"2":{"tf":1.0},"47":{"tf":1.4142135623730951},"53":{"tf":1.0}}}}}},"t":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":2,"docs":{"1":{"tf":1.4142135623730951},"13":{"tf":1.0}}}}}},"r":{"df":1,"docs":{"27":{"tf":1.0}},"i":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":6,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"49":{"tf":1.0},"50":{"tf":1.0},"53":{"tf":1.4142135623730951},"7":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":2,"docs":{"15":{"tf":1.0},"34":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"7":{"tf":1.0}}}},"df":0,"docs":{}}}}},"v":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"15":{"tf":1.4142135623730951}}}}},"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"d":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}}}},"w":{"a":{"df":0,"docs":{},"y":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}},"b":{"\\"":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"33":{"tf":1.0}}}}}}}},"a":{"c":{"df":0,"docs":{},"k":{"df":4,"docs":{"26":{"tf":1.4142135623730951},"30":{"tf":1.7320508075688772},"41":{"tf":1.0},"7":{"tf":1.0}},"g":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"2":{"tf":1.0}}},"df":0,"docs":{}}}}}}}},"d":{"df":0,"docs":{},"g":{"df":1,"docs":{"20":{"tf":2.6457513110645907}}}},"df":0,"docs":{},"r":{"df":1,"docs":{"55":{"tf":1.4142135623730951}}},"s":{"df":0,"docs":{},"e":{"df":5,"docs":{"16":{"tf":1.0},"20":{"tf":1.0},"28":{"tf":1.0},"47":{"tf":1.0},"6":{"tf":1.0}}},"i":{"c":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"38":{"tf":1.0}}}}},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"36":{"tf":1.0}}}}},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"34":{"tf":1.0}}},"df":0,"docs":{}}}},"t":{"df":0,"docs":{},"w":{"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":4,"docs":{"3":{"tf":1.0},"30":{"tf":1.0},"38":{"tf":1.7320508075688772},"51":{"tf":1.0}}}},"n":{"df":1,"docs":{"38":{"tf":1.0}}}}}}},"f":{"df":1,"docs":{"7":{"tf":1.0}}},"i":{"df":0,"docs":{},"n":{"d":{"df":4,"docs":{"0":{"tf":1.7320508075688772},"34":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}},"t":{"df":5,"docs":{"16":{"tf":2.8284271247461903},"18":{"tf":1.0},"20":{"tf":1.0},"38":{"tf":1.4142135623730951},"53":{"tf":1.0}}}},"l":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"k":{"df":3,"docs":{"37":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"42":{"tf":1.0}}}}}}}}}},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":2,"docs":{"16":{"tf":1.0},"6":{"tf":1.7320508075688772}},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}},"e":{"d":{"(":{")":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"(":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"x":{")":{".":{"c":{"a":{"df":0,"docs":{},"p":{"df":2,"docs":{"17":{"tf":1.4142135623730951},"29":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"_":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"16":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":9,"docs":{"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":1.4142135623730951},"23":{"tf":1.0},"26":{"tf":1.4142135623730951},"29":{"tf":1.4142135623730951},"30":{"tf":1.0},"42":{"tf":1.0},"6":{"tf":1.0}},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}},"l":{"df":0,"docs":{},"o":{"a":{"d":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"6":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"t":{"df":0,"docs":{},"h":{"df":4,"docs":{"13":{"tf":1.0},"18":{"tf":1.0},"3":{"tf":1.0},"54":{"tf":1.0}}}},"u":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"55":{"tf":1.0}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"38":{"tf":2.8284271247461903},"43":{"tf":1.0},"51":{"tf":1.0}}}}}},"i":{"df":0,"docs":{},"l":{"d":{"df":6,"docs":{"14":{"tf":1.4142135623730951},"2":{"tf":2.0},"28":{"tf":1.0},"37":{"tf":1.0},"4":{"tf":1.0},"41":{"tf":1.7320508075688772}}},"df":0,"docs":{},"t":{"df":4,"docs":{"2":{"tf":1.0},"4":{"tf":1.0},"41":{"tf":1.0},"6":{"tf":1.0}}}}}},"y":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":4,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"38":{"tf":1.0},"52":{"tf":1.0}}}}}},"c":{"a":{"b":{"a":{"b":{"df":0,"docs":{},"l":{"df":1,"docs":{"15":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"d":{"=":{"\\"":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":1,"docs":{"53":{"tf":2.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":15,"docs":{"1":{"tf":1.0},"15":{"tf":2.23606797749979},"18":{"tf":1.0},"20":{"tf":2.0},"23":{"tf":1.0},"32":{"tf":1.0},"34":{"tf":1.0},"38":{"tf":2.0},"40":{"tf":1.0},"41":{"tf":1.0},"42":{"tf":1.4142135623730951},"49":{"tf":1.0},"51":{"tf":1.4142135623730951},"52":{"tf":1.4142135623730951},"6":{"tf":1.0}}}},"p":{"\'":{"df":1,"docs":{"15":{"tf":1.4142135623730951}}},":":{":":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"<":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}}}}}}}},"a":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0}},"y":{"\'":{"df":1,"docs":{"20":{"tf":1.0}}},"df":0,"docs":{}}}}}},"l":{"df":12,"docs":{"15":{"tf":3.0},"16":{"tf":1.0},"18":{"tf":3.3166247903554},"20":{"tf":2.8284271247461903},"23":{"tf":1.0},"26":{"tf":1.7320508075688772},"27":{"tf":1.0},"31":{"tf":1.0},"34":{"tf":2.6457513110645907},"38":{"tf":1.7320508075688772},"42":{"tf":1.4142135623730951},"6":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"31":{"tf":1.7320508075688772}},"s":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"38":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"o":{"/":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{":":{"8":{"df":1,"docs":{"3":{"tf":1.0}}},"df":0,"docs":{}},"df":1,"docs":{"3":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":1,"docs":{"3":{"tf":1.0}}}},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"15":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"e":{"df":5,"docs":{"13":{"tf":1.0},"18":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"53":{"tf":1.4142135623730951}}},"t":{"df":1,"docs":{"18":{"tf":1.0}}}},"t":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"9":{"tf":1.0}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"s":{"df":3,"docs":{"11":{"tf":1.0},"12":{"tf":1.0},"8":{"tf":1.0}}}},"v":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}}}},"d":{"df":10,"docs":{"1":{"tf":1.0},"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.0},"48":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}}},"df":4,"docs":{"2":{"tf":1.7320508075688772},"26":{"tf":1.0},"33":{"tf":1.0},"53":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"18":{"tf":1.4142135623730951},"52":{"tf":1.0}}}}},"df":0,"docs":{}}}},"h":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"df":6,"docs":{"41":{"tf":2.23606797749979},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"45":{"tf":1.0},"46":{"tf":1.7320508075688772}}}}}}},"n":{"df":0,"docs":{},"g":{"df":4,"docs":{"38":{"tf":1.0},"40":{"tf":1.0},"42":{"tf":1.0},"53":{"tf":1.0}}},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{":":{":":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"(":{"1":{"3":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"3":{"7":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":2,"docs":{"51":{"tf":3.3166247903554},"53":{"tf":2.0}},"s":{".":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"(":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":1,"docs":{"51":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"d":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"y":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}}}}},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"\'":{"df":3,"docs":{"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0}}},"df":12,"docs":{"23":{"tf":1.4142135623730951},"24":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.4142135623730951},"41":{"tf":1.7320508075688772},"44":{"tf":1.0},"45":{"tf":1.0},"47":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}}}}}}},"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"1":{"tf":1.0}}}}}},"i":{"df":0,"docs":{},"l":{"d":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{".":{"df":0,"docs":{},"r":{"df":1,"docs":{"41":{"tf":1.0}}}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"_":{"df":0,"docs":{},"t":{"c":{"b":{"df":1,"docs":{"46":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":5,"docs":{"31":{"tf":1.0},"41":{"tf":2.6457513110645907},"43":{"tf":1.4142135623730951},"44":{"tf":1.0},"46":{"tf":2.23606797749979}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":1,"docs":{"31":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"l":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"7":{"tf":1.0}}}}},"r":{"df":3,"docs":{"20":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0}}}},"df":0,"docs":{}},"i":{"c":{"df":0,"docs":{},"k":{"df":2,"docs":{"1":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"\'":{"df":1,"docs":{"52":{"tf":1.0}}},".":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.4142135623730951}}}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":1,"docs":{"51":{"tf":1.0}}}}}}}}},"df":3,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951},"54":{"tf":1.0}}}}},"p":{"b":{"df":0,"docs":{},"o":{"a":{"df":0,"docs":{},"r":{"d":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}}}}},"n":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{".":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"(":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{".":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"20":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":2.8284271247461903},"20":{"tf":1.0}}}},"df":0,"docs":{}}},"o":{"d":{"df":0,"docs":{},"e":{"df":10,"docs":{"1":{"tf":2.0},"24":{"tf":1.0},"3":{"tf":1.0},"33":{"tf":1.0},"37":{"tf":1.7320508075688772},"4":{"tf":1.4142135623730951},"41":{"tf":2.0},"53":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":3,"docs":{"13":{"tf":1.0},"46":{"tf":1.0},"54":{"tf":1.0}}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"1":{"tf":2.449489742783178}}}},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"41":{"tf":1.0}}}},"u":{"df":0,"docs":{},"n":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}}},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}}}}},"r":{"df":2,"docs":{"20":{"tf":1.0},"41":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.7320508075688772}}}},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"41":{"tf":1.0}}},"x":{"df":1,"docs":{"41":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"34":{"tf":1.4142135623730951}}}},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":1,"docs":{"23":{"tf":1.4142135623730951}}}}},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"n":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":1,"docs":{"23":{"tf":1.0}}}},"r":{"df":0,"docs":{},"n":{"df":1,"docs":{"37":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"s":{"df":1,"docs":{"38":{"tf":1.0}}}},"u":{"df":0,"docs":{},"r":{"df":0,"docs":{},"r":{"df":1,"docs":{"37":{"tf":1.0}}}}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"df":1,"docs":{"3":{"tf":1.0}}}}}}},"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":4,"docs":{"3":{"tf":1.4142135623730951},"38":{"tf":1.0},"4":{"tf":1.4142135623730951},"5":{"tf":1.7320508075688772}}}}}}},"s":{"df":0,"docs":{},"i":{"d":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":2,"docs":{"41":{"tf":1.0},"5":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"l":{"df":1,"docs":{"33":{"tf":1.0}}}},"t":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":3,"docs":{"18":{"tf":1.0},"45":{"tf":1.0},"46":{"tf":1.0}}}}},"df":4,"docs":{"25":{"tf":1.0},"28":{"tf":1.4142135623730951},"51":{"tf":1.4142135623730951},"54":{"tf":1.0}},"r":{"df":0,"docs":{},"u":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.0}}}},"df":0,"docs":{}}}}},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":13,"docs":{"1":{"tf":1.0},"15":{"tf":1.0},"18":{"tf":1.0},"2":{"tf":2.0},"20":{"tf":1.0},"26":{"tf":1.0},"30":{"tf":1.7320508075688772},"31":{"tf":1.0},"38":{"tf":1.0},"4":{"tf":2.8284271247461903},"41":{"tf":1.0},"42":{"tf":1.4142135623730951},"6":{"tf":1.0}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"7":{"tf":1.0}}}},"x":{"df":0,"docs":{},"t":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.4142135623730951},"41":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":4,"docs":{"34":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"6":{"tf":1.0}}}}}}},"p":{"df":0,"docs":{},"i":{"df":4,"docs":{"1":{"tf":1.0},"38":{"tf":2.0},"44":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"r":{"df":0,"docs":{},"e":{"df":2,"docs":{"15":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"d":{"df":10,"docs":{"1":{"tf":1.0},"15":{"tf":1.0},"23":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951},"27":{"tf":1.0},"30":{"tf":1.0},"4":{"tf":1.0},"42":{"tf":1.0},"49":{"tf":1.0},"51":{"tf":1.0}}},"df":0,"docs":{}}}}}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":7,"docs":{"0":{"tf":1.7320508075688772},"25":{"tf":1.0},"31":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}}}},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}}}}}},"t":{"df":0,"docs":{},"r":{"df":3,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":2.6457513110645907},"38":{"tf":1.4142135623730951}}}}},"r":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":16,"docs":{"13":{"tf":1.0},"14":{"tf":1.7320508075688772},"15":{"tf":1.0},"23":{"tf":1.4142135623730951},"3":{"tf":1.4142135623730951},"37":{"tf":1.0},"41":{"tf":1.7320508075688772},"48":{"tf":1.0},"5":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":1.4142135623730951},"54":{"tf":1.0},"55":{"tf":1.4142135623730951},"6":{"tf":1.0},"7":{"tf":2.0}}}}},"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"t":{"df":9,"docs":{"15":{"tf":1.0},"16":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0},"24":{"tf":1.0},"30":{"tf":1.4142135623730951},"34":{"tf":1.4142135623730951},"35":{"tf":1.4142135623730951},"47":{"tf":1.0}},"e":{"_":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"_":{"df":0,"docs":{},"v":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":1,"docs":{"43":{"tf":1.4142135623730951}},"e":{"(":{")":{"\'":{"df":1,"docs":{"46":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}}},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"29":{"tf":1.0}}}}},"p":{"a":{"c":{"df":0,"docs":{},"e":{"\'":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}},"df":7,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":3.0},"20":{"tf":1.0},"23":{"tf":1.0},"26":{"tf":1.0},"38":{"tf":1.4142135623730951},"46":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"l":{"df":1,"docs":{"7":{"tf":1.0}}}}},"u":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{")":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"g":{"2":{"(":{")":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"y":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":1,"docs":{"31":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":3,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":2.449489742783178},"20":{"tf":1.0}}}}}}},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":3,"docs":{"0":{"tf":1.0},"10":{"tf":1.4142135623730951},"3":{"tf":1.0}}}}}}}},"d":{"a":{"df":0,"docs":{},"t":{"a":{"df":6,"docs":{"36":{"tf":1.0},"38":{"tf":2.449489742783178},"39":{"tf":1.0},"52":{"tf":1.0},"53":{"tf":1.4142135623730951},"7":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{},"e":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"l":{"df":0,"docs":{},"n":{"!":{"(":{"\\"":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":2,"docs":{"51":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772}}}}},"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"48":{"tf":1.0}}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":2,"docs":{"51":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772}}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"53":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}}}},"c":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":5,"docs":{"46":{"tf":1.0},"49":{"tf":1.0},"53":{"tf":1.4142135623730951},"55":{"tf":1.4142135623730951},"7":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":5,"docs":{"10":{"tf":1.0},"12":{"tf":1.0},"13":{"tf":1.0},"49":{"tf":1.0},"53":{"tf":1.0}}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"26":{"tf":1.0},"54":{"tf":1.0}}}}},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"v":{"df":1,"docs":{"34":{"tf":1.0}}}}},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":2,"docs":{"14":{"tf":1.0},"3":{"tf":1.0}}}}}}}},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":5,"docs":{"15":{"tf":1.0},"2":{"tf":1.0},"23":{"tf":1.0},"37":{"tf":1.0},"7":{"tf":1.7320508075688772}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"(":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"s":{"c":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":0,"docs":{},"e":{"_":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":2,"docs":{"17":{"tf":1.4142135623730951},"29":{"tf":1.4142135623730951}},"r":{"df":0,"docs":{},"i":{"b":{"df":4,"docs":{"16":{"tf":1.4142135623730951},"20":{"tf":1.0},"38":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":3,"docs":{"40":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0}},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"16":{"tf":1.0}}}}}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"52":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"r":{"df":3,"docs":{"18":{"tf":1.0},"31":{"tf":1.0},"42":{"tf":1.0}}}},"t":{"_":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"18":{"tf":1.0}}}}}},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":4,"docs":{"0":{"tf":1.0},"18":{"tf":1.0},"50":{"tf":1.0},"6":{"tf":1.0}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"26":{"tf":1.0},"38":{"tf":1.0}}}}}}}},"v":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"/":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"/":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"j":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"4":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"4":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":1,"docs":{"4":{"tf":2.23606797749979}},"i":{"c":{"df":15,"docs":{"16":{"tf":3.1622776601683795},"28":{"tf":2.23606797749979},"29":{"tf":1.0},"30":{"tf":2.23606797749979},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"33":{"tf":1.0},"34":{"tf":1.0},"35":{"tf":1.0},"36":{"tf":1.7320508075688772},"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":2.0}},"e":{"\'":{"df":4,"docs":{"28":{"tf":1.7320508075688772},"30":{"tf":1.0},"33":{"tf":1.0},"44":{"tf":1.0}}},".":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"#":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":2,"docs":{"41":{"tf":1.0},"46":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"r":{"df":1,"docs":{"28":{"tf":1.0}}}},"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"0":{"2":{":":{"1":{"0":{"8":{"df":1,"docs":{"33":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"6":{":":{"1":{"6":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"8":{":":{"1":{"8":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"2":{":":{"2":{"7":{"df":1,"docs":{"29":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"3":{"4":{":":{"4":{"4":{"df":1,"docs":{"29":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"3":{":":{"4":{"9":{"df":1,"docs":{"31":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"6":{"8":{":":{"9":{"7":{"df":1,"docs":{"31":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{"0":{":":{"7":{"3":{"df":1,"docs":{"32":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"46":{"tf":1.0}}}}}},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"(":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"l":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{".":{"c":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"33":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":1,"docs":{"46":{"tf":1.0}}}}}},"df":0,"docs":{}},"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"_":{"c":{"a":{"df":0,"docs":{},"p":{"df":2,"docs":{"31":{"tf":1.0},"32":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"c":{".":{"df":0,"docs":{},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":1,"docs":{"55":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"38":{"tf":1.0},"7":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}},"s":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"i":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"3":{"tf":1.0}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"h":{"df":1,"docs":{"30":{"tf":1.0}}}}}}}}},"r":{"df":0,"docs":{},"i":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"v":{"df":0,"docs":{},"i":{"d":{"df":2,"docs":{"3":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}}},"l":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"df":1,"docs":{"41":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"o":{"c":{"df":1,"docs":{"3":{"tf":1.0}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"/":{"d":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"2":{"tf":1.0}},"e":{":":{"9":{"4":{":":{"1":{"0":{"8":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":1,"docs":{"2":{"tf":2.449489742783178}},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"2":{"tf":1.0}}}}}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"n":{"\'":{"df":0,"docs":{},"t":{"df":3,"docs":{"0":{"tf":1.0},"28":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{}}}},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"\'":{"df":1,"docs":{"49":{"tf":1.4142135623730951}}},"df":5,"docs":{"0":{"tf":1.4142135623730951},"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":2.23606797749979},"55":{"tf":1.0}}}}},"df":0,"docs":{}},"n":{"\'":{"df":0,"docs":{},"t":{"df":1,"docs":{"30":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":1,"docs":{"42":{"tf":1.0}}}},"w":{"df":0,"docs":{},"n":{"c":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{":":{":":{"<":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":2,"docs":{"31":{"tf":1.4142135623730951},"42":{"tf":1.0}}}}}}},"df":0,"docs":{},"e":{"a":{"c":{"df":0,"docs":{},"h":{"df":8,"docs":{"1":{"tf":1.4142135623730951},"15":{"tf":1.4142135623730951},"18":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.0},"38":{"tf":1.0},"4":{"tf":1.0},"5":{"tf":1.0}}}},"df":0,"docs":{}},"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":4,"docs":{"28":{"tf":1.0},"36":{"tf":1.0},"41":{"tf":1.0},"46":{"tf":1.0}}}}},"df":0,"docs":{},"l":{"a":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":2,"docs":{"16":{"tf":1.0},"18":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"0":{"tf":1.0},"50":{"tf":1.0}}}}}}},"f":{"df":1,"docs":{"53":{"tf":1.0}}}},"m":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":7,"docs":{"15":{"tf":1.0},"18":{"tf":1.4142135623730951},"20":{"tf":1.0},"23":{"tf":1.0},"29":{"tf":1.0},"31":{"tf":1.0},"38":{"tf":1.0}}},"y":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":2,"docs":{"18":{"tf":1.0},"29":{"tf":1.0}},"s":{".":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":0,"docs":{},"t":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":2,"docs":{"18":{"tf":1.0},"31":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}}}},"n":{"a":{"b":{"df":0,"docs":{},"l":{"df":1,"docs":{"4":{"tf":1.0}}}},"df":0,"docs":{}},"c":{"a":{"df":0,"docs":{},"p":{"df":0,"docs":{},"s":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":2,"docs":{"18":{"tf":1.4142135623730951},"53":{"tf":1.0}}}}}}},"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"g":{"df":1,"docs":{"1":{"tf":1.0}}}},"df":0,"docs":{}}}}},"d":{"df":5,"docs":{"1":{"tf":1.0},"41":{"tf":1.0},"43":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{":":{":":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"40":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":2,"docs":{"38":{"tf":2.0},"41":{"tf":1.0}}}}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":2,"docs":{"15":{"tf":1.0},"53":{"tf":1.0}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"36":{"tf":1.0}}}},"i":{"df":0,"docs":{},"r":{"df":1,"docs":{"41":{"tf":1.0}}}},"r":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"49":{"tf":1.0},"7":{"tf":1.7320508075688772}}}}}}}}}},"u":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}}}},"v":{"df":1,"docs":{"41":{"tf":1.0}},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":5,"docs":{"14":{"tf":1.0},"3":{"tf":1.4142135623730951},"41":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}}}}}},"q":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"v":{"a":{"df":0,"docs":{},"l":{"df":2,"docs":{"49":{"tf":1.0},"51":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}}},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":3,"docs":{"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.0}}}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"49":{"tf":2.0}}}}}},"x":{"a":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":2,"docs":{"25":{"tf":1.0},"7":{"tf":1.0}}}}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"1":{"tf":1.0}}}},"p":{"df":0,"docs":{},"l":{"df":15,"docs":{"1":{"tf":1.4142135623730951},"12":{"tf":1.0},"13":{"tf":1.0},"15":{"tf":1.4142135623730951},"18":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":2.0},"41":{"tf":1.7320508075688772},"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"52":{"tf":1.0},"53":{"tf":2.0},"55":{"tf":1.0},"7":{"tf":1.0}}}}}},"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":3,"docs":{"16":{"tf":1.0},"41":{"tf":1.0},"55":{"tf":1.0}}}}}},"df":0,"docs":{},"e":{"c":{"df":1,"docs":{"2":{"tf":1.0}}},"df":0,"docs":{},"r":{"c":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"30":{"tf":1.0}}},"df":0,"docs":{},"s":{"df":25,"docs":{"1":{"tf":2.0},"10":{"tf":1.7320508075688772},"11":{"tf":1.7320508075688772},"12":{"tf":1.7320508075688772},"13":{"tf":1.7320508075688772},"19":{"tf":1.7320508075688772},"20":{"tf":2.23606797749979},"21":{"tf":1.7320508075688772},"22":{"tf":1.7320508075688772},"24":{"tf":1.7320508075688772},"27":{"tf":1.7320508075688772},"30":{"tf":1.4142135623730951},"32":{"tf":1.0},"33":{"tf":1.7320508075688772},"34":{"tf":1.7320508075688772},"35":{"tf":1.7320508075688772},"36":{"tf":1.7320508075688772},"37":{"tf":1.0},"39":{"tf":1.7320508075688772},"40":{"tf":1.7320508075688772},"41":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951},"52":{"tf":2.0},"8":{"tf":1.7320508075688772},"9":{"tf":1.7320508075688772}}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"20":{"tf":1.0}}}},"t":{"df":1,"docs":{"7":{"tf":1.4142135623730951}}}},"p":{"a":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"46":{"tf":1.4142135623730951}}},"df":0,"docs":{}}},"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":2,"docs":{"1":{"tf":1.0},"42":{"tf":1.0}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":3,"docs":{"23":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0}}}}},"l":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"6":{"tf":1.0}}}}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"r":{"df":3,"docs":{"37":{"tf":1.4142135623730951},"41":{"tf":1.0},"50":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"0":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":6,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"17":{"tf":1.0},"24":{"tf":1.0},"27":{"tf":1.0},"53":{"tf":1.0}}}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":4,"docs":{"41":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.0},"46":{"tf":1.4142135623730951}}},"df":0,"docs":{},"s":{"df":2,"docs":{"4":{"tf":1.4142135623730951},"41":{"tf":1.0}}}},"r":{"df":0,"docs":{},"n":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"10":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":1,"docs":{"26":{"tf":1.0}}}}},"r":{"a":{"_":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"38":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":2,"docs":{"43":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}},"df":1,"docs":{"43":{"tf":1.0}}},"df":0,"docs":{}}}}},"f":{"a":{"c":{"df":0,"docs":{},"t":{"df":2,"docs":{"18":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":2,"docs":{"21":{"tf":1.0},"42":{"tf":1.0}},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"13":{"tf":1.0}}}}}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"r":{"df":3,"docs":{"0":{"tf":1.4142135623730951},"29":{"tf":1.0},"47":{"tf":1.0}}}},"df":0,"docs":{}}}}},"r":{"df":5,"docs":{"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"53":{"tf":1.0}}},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":2,"docs":{"26":{"tf":1.0},"49":{"tf":1.0}}}}}},"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"55":{"tf":1.0}}}}}},"df":0,"docs":{},"w":{"df":5,"docs":{"37":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"53":{"tf":1.0},"55":{"tf":1.0}}}},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"d":{"_":{"1":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"df":1,"docs":{"38":{"tf":2.0}}},"df":0,"docs":{}}},"l":{"df":0,"docs":{},"e":{"df":2,"docs":{"3":{"tf":1.0},"53":{"tf":1.0}},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"(":{"df":0,"docs":{},"|":{"(":{"_":{"df":0,"docs":{},"i":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"n":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"28":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0}}}},"d":{"_":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"(":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.4142135623730951}}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"df":3,"docs":{"17":{"tf":1.0},"26":{"tf":1.0},"42":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"34":{"tf":1.0}},"r":{"df":1,"docs":{"6":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":2,"docs":{"28":{"tf":1.0},"29":{"tf":1.0}}}}}},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":0,"docs":{},"i":{"b":{"df":0,"docs":{},"l":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}}},"n":{"(":{"&":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":11,"docs":{"17":{"tf":1.0},"26":{"tf":1.0},"29":{"tf":1.0},"31":{"tf":1.0},"37":{"tf":1.4142135623730951},"38":{"tf":1.4142135623730951},"48":{"tf":1.0},"49":{"tf":1.0},"51":{"tf":2.0},"53":{"tf":1.7320508075688772},"7":{"tf":1.0}}},"o":{"c":{"df":0,"docs":{},"u":{"df":2,"docs":{"23":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":5,"docs":{"32":{"tf":1.0},"34":{"tf":1.0},"37":{"tf":1.0},"42":{"tf":1.0},"46":{"tf":1.4142135623730951}}}}}},"o":{"df":1,"docs":{"54":{"tf":1.0}}},"r":{"df":0,"docs":{},"m":{"df":4,"docs":{"15":{"tf":1.0},"49":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}},"u":{"df":0,"docs":{},"n":{"d":{"a":{"df":0,"docs":{},"t":{"df":2,"docs":{"0":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"27":{"tf":1.0}}}},"df":0,"docs":{}}},"df":11,"docs":{"16":{"tf":1.4142135623730951},"23":{"tf":2.23606797749979},"24":{"tf":1.7320508075688772},"26":{"tf":1.4142135623730951},"30":{"tf":1.7320508075688772},"31":{"tf":1.7320508075688772},"32":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.7320508075688772},"46":{"tf":1.0},"6":{"tf":1.0}},"w":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"k":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.4142135623730951}}}}}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"a":{"df":1,"docs":{"31":{"tf":1.0}}},"b":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"31":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":1,"docs":{"31":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":3,"docs":{"16":{"tf":1.0},"18":{"tf":1.4142135623730951},"7":{"tf":1.0}}}},"o":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"n":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":8,"docs":{"17":{"tf":1.0},"26":{"tf":1.4142135623730951},"31":{"tf":1.0},"37":{"tf":1.0},"43":{"tf":1.0},"49":{"tf":1.7320508075688772},"51":{"tf":1.0},"7":{"tf":1.4142135623730951}}}}}}},"d":{"df":1,"docs":{"0":{"tf":1.0}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":2,"docs":{"30":{"tf":1.0},"50":{"tf":1.0}}}}}}}}}},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}}},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":4,"docs":{"15":{"tf":1.0},"30":{"tf":1.4142135623730951},"5":{"tf":1.0},"7":{"tf":1.0}}}}},"t":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"r":{"df":1,"docs":{"51":{"tf":1.0}}}},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"(":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"26":{"tf":1.0}}}}}}}}}},"df":0,"docs":{}},"df":1,"docs":{"26":{"tf":1.4142135623730951}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"1":{"tf":2.0}},"h":{"df":0,"docs":{},"u":{"b":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}},"v":{"df":0,"docs":{},"e":{"df":1,"docs":{"26":{"tf":1.0}},"n":{"df":5,"docs":{"23":{"tf":1.0},"26":{"tf":1.0},"3":{"tf":1.0},"34":{"tf":1.0},"42":{"tf":1.0}}}}}},"l":{"df":0,"docs":{},"o":{"b":{"a":{"df":0,"docs":{},"l":{"df":2,"docs":{"41":{"tf":1.0},"53":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"o":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"23":{"tf":1.0},"28":{"tf":1.0},"41":{"tf":1.0}}}},"df":0,"docs":{}},"r":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"34":{"tf":1.0}}}},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"16":{"tf":1.0}}},"u":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}},"df":1,"docs":{"25":{"tf":1.0}},"e":{"_":{"df":0,"docs":{},"s":{"df":2,"docs":{"25":{"tf":2.0},"26":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"i":{"df":1,"docs":{"46":{"tf":1.0}}},"l":{"df":4,"docs":{"41":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":1.0},"7":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":5,"docs":{"48":{"tf":1.7320508075688772},"49":{"tf":2.449489742783178},"51":{"tf":2.0},"52":{"tf":1.4142135623730951},"53":{"tf":2.0}},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"df":4,"docs":{"48":{"tf":1.7320508075688772},"49":{"tf":1.0},"51":{"tf":2.449489742783178},"53":{"tf":1.7320508075688772}}}}}}}}}},"df":0,"docs":{}},"p":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"r":{"d":{"df":0,"docs":{},"w":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"h":{"df":1,"docs":{"1":{"tf":1.0}}}},"v":{"df":0,"docs":{},"e":{"df":1,"docs":{"42":{"tf":1.0}}}}},"df":1,"docs":{"7":{"tf":1.0}},"e":{"a":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"1":{"tf":1.0}}}}},"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":1,"docs":{"13":{"tf":1.7320508075688772}}}}}},"df":3,"docs":{"13":{"tf":1.7320508075688772},"41":{"tf":1.0},"7":{"tf":1.4142135623730951}}}},"df":0,"docs":{},"l":{"d":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":12,"docs":{"10":{"tf":1.0},"11":{"tf":1.0},"12":{"tf":1.0},"13":{"tf":1.0},"14":{"tf":1.7320508075688772},"33":{"tf":1.0},"48":{"tf":2.23606797749979},"49":{"tf":1.0},"50":{"tf":1.0},"7":{"tf":2.23606797749979},"8":{"tf":1.0},"9":{"tf":1.0}}}},"p":{"df":2,"docs":{"4":{"tf":1.0},"41":{"tf":1.0}}}},"r":{"df":0,"docs":{},"e":{"df":7,"docs":{"27":{"tf":1.4142135623730951},"37":{"tf":1.0},"41":{"tf":1.0},"47":{"tf":1.0},"48":{"tf":1.0},"5":{"tf":1.4142135623730951},"7":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":2,"docs":{"23":{"tf":1.0},"7":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"28":{"tf":1.0},"37":{"tf":1.0},"6":{"tf":1.0}}}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"34":{"tf":1.0}}}}}},"n":{"df":0,"docs":{},"t":{"df":3,"docs":{"1":{"tf":1.0},"27":{"tf":1.0},"46":{"tf":1.4142135623730951}}}}},"o":{"c":{"df":1,"docs":{"41":{"tf":1.4142135623730951}}},"df":0,"docs":{},"l":{"d":{"df":2,"docs":{"31":{"tf":1.0},"34":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"26":{"tf":1.4142135623730951}}}},"o":{"d":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{},"k":{"df":1,"docs":{"10":{"tf":1.7320508075688772}}}},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"5":{"tf":1.4142135623730951}}}}},"t":{"df":0,"docs":{},"e":{"df":1,"docs":{"36":{"tf":1.0}}},"t":{"df":0,"docs":{},"p":{"df":0,"docs":{},"s":{":":{"/":{"/":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"u":{"b":{".":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{"/":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"0":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{".":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"u":{"b":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"/":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"5":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"i":{".":{"df":1,"docs":{"20":{"tf":1.0}}},"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}}}},"d":{"=":{"\\"":{"1":{"3":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}},"3":{"7":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":3,"docs":{"26":{"tf":1.0},"30":{"tf":1.0},"31":{"tf":1.0}}}}}}}}},"df":0,"docs":{},"i":{"df":2,"docs":{"0":{"tf":1.0},"5":{"tf":1.0}}},"m":{"a":{"df":0,"docs":{},"g":{"df":6,"docs":{"2":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0},"43":{"tf":1.0},"53":{"tf":1.7320508075688772},"6":{"tf":1.0}}}},"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"df":3,"docs":{"48":{"tf":1.4142135623730951},"51":{"tf":2.0},"53":{"tf":1.7320508075688772}},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":11,"docs":{"0":{"tf":1.0},"18":{"tf":1.0},"28":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":1.0},"46":{"tf":1.0},"48":{"tf":1.4142135623730951},"49":{"tf":1.7320508075688772},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.4142135623730951}}}}}}}},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":2,"docs":{"24":{"tf":1.0},"7":{"tf":1.0}}}}}}},"n":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"d":{"df":8,"docs":{"1":{"tf":1.0},"13":{"tf":1.0},"3":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"50":{"tf":1.0},"52":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"41":{"tf":1.0}}}}}}}}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"23":{"tf":1.0}}},"df":0,"docs":{}}}},"x":{"(":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":3,"docs":{"17":{"tf":1.0},"18":{"tf":1.0},"5":{"tf":1.0}}}}},"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"48":{"tf":1.4142135623730951},"51":{"tf":1.4142135623730951},"53":{"tf":1.0}}}},"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"df":4,"docs":{"18":{"tf":1.4142135623730951},"3":{"tf":1.0},"30":{"tf":1.0},"7":{"tf":1.0}}}}}},"i":{"df":0,"docs":{},"t":{"df":3,"docs":{"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}},"i":{"df":15,"docs":{"12":{"tf":1.4142135623730951},"14":{"tf":1.4142135623730951},"18":{"tf":1.0},"26":{"tf":1.0},"30":{"tf":1.4142135623730951},"37":{"tf":1.0},"41":{"tf":1.0},"42":{"tf":1.4142135623730951},"46":{"tf":1.0},"49":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951},"54":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.4142135623730951}}}}},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":2,"docs":{"28":{"tf":1.0},"36":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}},"i":{"d":{"df":2,"docs":{"2":{"tf":1.7320508075688772},"4":{"tf":1.0}}},"df":0,"docs":{}},"t":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"2":{"tf":1.0}}},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":1,"docs":{"55":{"tf":1.0}}}}}},"df":0,"docs":{},"e":{"a":{"d":{"df":2,"docs":{"21":{"tf":1.0},"42":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"u":{"c":{"df":0,"docs":{},"t":{"df":3,"docs":{"1":{"tf":1.0},"41":{"tf":1.0},"53":{"tf":1.0}}}},"df":0,"docs":{}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"r":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":1,"docs":{"46":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{".":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"40":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"v":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"(":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"(":{")":{".":{"df":0,"docs":{},"l":{"a":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"(":{"1":{"2":{"3":{")":{".":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":2,"docs":{"38":{"tf":1.0},"40":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":1,"docs":{"38":{"tf":1.0}}}},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"df":2,"docs":{"37":{"tf":1.0},"38":{"tf":1.0}}}}}},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"37":{"tf":1.0},"38":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":1,"docs":{"38":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"a":{"c":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"d":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"y":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"(":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":1,"docs":{"38":{"tf":1.0}}}},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"n":{"df":1,"docs":{"37":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":3,"docs":{"37":{"tf":1.0},"38":{"tf":1.0},"40":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":12,"docs":{"25":{"tf":1.0},"28":{"tf":1.0},"33":{"tf":1.0},"37":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"54":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":3,"docs":{"28":{"tf":1.0},"37":{"tf":1.0},"52":{"tf":1.0}},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}}}},"f":{"a":{"c":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"m":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"i":{"df":1,"docs":{"25":{"tf":1.0}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":4,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.7320508075688772},"38":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":3,"docs":{"28":{"tf":1.0},"34":{"tf":2.8284271247461903},"36":{"tf":2.23606797749979}}}}}}}},"o":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"df":0,"docs":{}},"r":{"a":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":1,"docs":{"46":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"u":{"c":{"df":2,"docs":{"0":{"tf":1.0},"38":{"tf":1.0}},"t":{"df":1,"docs":{"0":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"v":{"df":0,"docs":{},"o":{"c":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.4142135623730951},"3":{"tf":1.0}}},"df":0,"docs":{},"k":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"38":{"tf":1.0}}}}}},"p":{"c":{".":{"df":0,"docs":{},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{":":{"7":{":":{"2":{"0":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":5,"docs":{"37":{"tf":1.0},"38":{"tf":3.4641016151377544},"43":{"tf":1.0},"51":{"tf":2.449489742783178},"52":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"q":{"_":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":1,"docs":{"46":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"_":{"c":{"a":{"df":0,"docs":{},"p":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"a":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":1,"docs":{"46":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"n":{"_":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"46":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"46":{"tf":1.0}}}},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"c":{"a":{"df":0,"docs":{},"p":{".":{"df":0,"docs":{},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"36":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":1,"docs":{"34":{"tf":1.7320508075688772}}}}}}}}},"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":3,"docs":{"34":{"tf":2.0},"35":{"tf":1.0},"36":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"s":{"df":0,"docs":{},"n":{"\'":{"df":0,"docs":{},"t":{"df":1,"docs":{"0":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"17":{"tf":1.0},"18":{"tf":1.0},"29":{"tf":1.0}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":2,"docs":{"53":{"tf":1.0},"6":{"tf":1.0}}}}}}}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":2,"docs":{"31":{"tf":1.0},"42":{"tf":1.0}}}},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"\'":{"df":1,"docs":{"15":{"tf":1.0}}},"df":18,"docs":{"15":{"tf":3.4641016151377544},"16":{"tf":2.449489742783178},"17":{"tf":1.0},"18":{"tf":1.7320508075688772},"19":{"tf":1.0},"20":{"tf":1.0},"21":{"tf":1.0},"22":{"tf":1.0},"23":{"tf":1.0},"24":{"tf":1.0},"29":{"tf":1.0},"3":{"tf":1.0},"30":{"tf":1.4142135623730951},"31":{"tf":1.0},"34":{"tf":1.0},"38":{"tf":2.23606797749979},"42":{"tf":1.0},"6":{"tf":2.449489742783178}}}}}}},"i":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}}},"l":{"a":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"w":{"df":0,"docs":{},"i":{"d":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"38":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":1,"docs":{"38":{"tf":1.0}}}}},"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"df":1,"docs":{"41":{"tf":1.0}}}}},"df":0,"docs":{},"u":{"a":{"df":0,"docs":{},"g":{"df":8,"docs":{"0":{"tf":1.0},"37":{"tf":1.0},"4":{"tf":1.0},"41":{"tf":1.7320508075688772},"48":{"tf":1.0},"50":{"tf":1.7320508075688772},"6":{"tf":1.4142135623730951},"7":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":4,"docs":{"18":{"tf":1.4142135623730951},"29":{"tf":1.0},"30":{"tf":1.0},"35":{"tf":1.0}}}}},"df":0,"docs":{}}}}}}}},"df":2,"docs":{"17":{"tf":1.0},"42":{"tf":1.0}}}}}}},"s":{"df":0,"docs":{},"t":{"df":2,"docs":{"20":{"tf":1.0},"30":{"tf":1.0}}}},"y":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}},"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}}},"v":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{},"g":{"a":{"c":{"df":0,"docs":{},"i":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":2,"docs":{"38":{"tf":2.0},"55":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"34":{"tf":1.0}}}},"t":{"\'":{"df":4,"docs":{"25":{"tf":1.0},"26":{"tf":1.0},"38":{"tf":1.0},"54":{"tf":1.0}}},"df":0,"docs":{}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"(":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"14":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}}}}}}},"df":0,"docs":{}}}}}}}},"df":9,"docs":{"23":{"tf":1.4142135623730951},"28":{"tf":1.0},"3":{"tf":1.0},"36":{"tf":1.0},"37":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951},"5":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.4142135623730951}}},"r":{"a":{"df":0,"docs":{},"g":{"df":3,"docs":{"18":{"tf":1.0},"41":{"tf":1.0},"54":{"tf":1.0}}}},"df":0,"docs":{}}}}},"i":{"b":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"\'":{"df":1,"docs":{"51":{"tf":1.0}}},"df":2,"docs":{"48":{"tf":1.0},"51":{"tf":1.7320508075688772}}}}}}}},"df":0,"docs":{}}},"r":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":3,"docs":{"37":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{"df":2,"docs":{"3":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":0,"docs":{},"w":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":1,"docs":{"52":{"tf":1.0}}}}}}}}}}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"15":{"tf":1.0}}}}},"n":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"1":{"tf":1.0}}}},"df":1,"docs":{"53":{"tf":1.0}}},"k":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":3,"docs":{"1":{"tf":1.0},"13":{"tf":1.0},"48":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"26":{"tf":1.0},"6":{"tf":1.0}}}}}},"v":{"df":0,"docs":{},"e":{"df":1,"docs":{"31":{"tf":1.0}}}}},"o":{"a":{"d":{"df":1,"docs":{"6":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"6":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"41":{"tf":1.0}}},"t":{"df":4,"docs":{"15":{"tf":1.4142135623730951},"23":{"tf":1.0},"3":{"tf":1.0},"53":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"g":{"df":3,"docs":{"1":{"tf":1.0},"14":{"tf":1.0},"16":{"tf":1.0}},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"14":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{":":{":":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":1,"docs":{"14":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":1,"docs":{"14":{"tf":2.0}}}}}},"o":{"df":0,"docs":{},"p":{"df":5,"docs":{"28":{"tf":1.0},"36":{"tf":1.7320508075688772},"41":{"tf":1.0},"46":{"tf":1.0},"49":{"tf":1.0}}}},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"31":{"tf":1.0}}}},"w":{"df":4,"docs":{"37":{"tf":1.0},"41":{"tf":1.4142135623730951},"6":{"tf":1.0},"7":{"tf":1.0}}}}},"m":{"a":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"15":{"tf":1.0},"38":{"tf":1.4142135623730951}}}}},"r":{"df":0,"docs":{},"o":{"\'":{"df":1,"docs":{"53":{"tf":1.0}}},"df":7,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"49":{"tf":1.0},"50":{"tf":1.0},"53":{"tf":1.0},"55":{"tf":1.7320508075688772},"7":{"tf":1.0}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"(":{"_":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},".":{"df":0,"docs":{},"r":{"df":1,"docs":{"37":{"tf":1.0}}}},"df":1,"docs":{"49":{"tf":1.0}},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}}},"k":{"df":0,"docs":{},"e":{"df":11,"docs":{"15":{"tf":1.0},"2":{"tf":1.7320508075688772},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.4142135623730951},"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"52":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}}}},"n":{"a":{"df":0,"docs":{},"g":{"df":4,"docs":{"15":{"tf":1.0},"16":{"tf":1.0},"34":{"tf":1.4142135623730951},"6":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":1,"docs":{"38":{"tf":1.4142135623730951}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"23":{"tf":1.0}}}}}},"u":{"a":{"df":0,"docs":{},"l":{"df":11,"docs":{"0":{"tf":1.0},"15":{"tf":1.0},"16":{"tf":1.0},"18":{"tf":1.7320508075688772},"20":{"tf":1.0},"23":{"tf":1.0},"30":{"tf":1.0},"38":{"tf":1.4142135623730951},"40":{"tf":1.0},"47":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{}}},"p":{"(":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{":":{":":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{":":{":":{"<":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"d":{">":{":":{":":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"29":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":8,"docs":{"23":{"tf":1.4142135623730951},"27":{"tf":1.0},"28":{"tf":1.0},"33":{"tf":1.4142135623730951},"43":{"tf":1.4142135623730951},"46":{"tf":1.0},"53":{"tf":2.23606797749979},"6":{"tf":1.0}}},"r":{"df":0,"docs":{},"k":{"df":1,"docs":{"1":{"tf":1.4142135623730951}}}},"s":{"df":0,"docs":{},"k":{"df":1,"docs":{"20":{"tf":1.0}}}},"t":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"30":{"tf":1.0}}}}}},"x":{"_":{"b":{"df":0,"docs":{},"y":{"_":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"y":{"(":{"df":0,"docs":{},"|":{"(":{"_":{"df":0,"docs":{},"i":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"m":{"df":1,"docs":{"6":{"tf":1.0}}}}}}}},"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"n":{"df":1,"docs":{"1":{"tf":1.0}}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":11,"docs":{"15":{"tf":1.4142135623730951},"16":{"tf":3.605551275463989},"18":{"tf":1.0},"23":{"tf":1.4142135623730951},"30":{"tf":1.7320508075688772},"31":{"tf":1.0},"38":{"tf":1.0},"53":{"tf":3.3166247903554},"54":{"tf":1.7320508075688772},"55":{"tf":2.8284271247461903},"6":{"tf":1.4142135623730951}}},"y":{".":{"df":0,"docs":{},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{":":{"7":{":":{"2":{"8":{"df":1,"docs":{"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"!":{"(":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":1,"docs":{"55":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":1,"docs":{"55":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"df":1,"docs":{"53":{"tf":1.4142135623730951}}}}}}}}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"5":{"tf":1.0}}}}}}},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":5,"docs":{"38":{"tf":3.1622776601683795},"39":{"tf":1.0},"40":{"tf":1.0},"41":{"tf":1.0},"52":{"tf":1.0}},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":3,"docs":{"38":{"tf":2.6457513110645907},"51":{"tf":1.7320508075688772},"53":{"tf":1.0}}}}}}}}},"df":0,"docs":{}}},"t":{"a":{"d":{"a":{"df":0,"docs":{},"t":{"a":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"d":{"df":6,"docs":{"15":{"tf":1.0},"18":{"tf":1.7320508075688772},"34":{"tf":1.4142135623730951},"42":{"tf":2.23606797749979},"49":{"tf":1.4142135623730951},"51":{"tf":1.0}}},"df":0,"docs":{}}}}},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{".":{"df":0,"docs":{},"h":{"df":1,"docs":{"49":{"tf":1.0}}}},"_":{"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"51":{"tf":1.0}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"a":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"m":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"51":{"tf":1.4142135623730951}}}}}}}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":1,"docs":{"51":{"tf":1.0}}}}}}}},"p":{"df":0,"docs":{},"p":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":5,"docs":{"0":{"tf":2.449489742783178},"2":{"tf":1.0},"47":{"tf":2.23606797749979},"48":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772}}}}}}}},"d":{"d":{"df":0,"docs":{},"l":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":2,"docs":{"14":{"tf":1.0},"41":{"tf":1.0}},"u":{"df":0,"docs":{},"m":{"df":1,"docs":{"22":{"tf":1.0}}}}}},"t":{"df":1,"docs":{"20":{"tf":2.0}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"47":{"tf":1.4142135623730951}}}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"23":{"tf":1.0}}}}}},"s":{"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"v":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"x":{"df":1,"docs":{"38":{"tf":1.0}}}},"k":{"/":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}}}}},"df":0,"docs":{}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":7,"docs":{"28":{"tf":1.4142135623730951},"30":{"tf":1.4142135623730951},"33":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":1.0}}}}},"o":{"d":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":1,"docs":{"1":{"tf":1.0}},"i":{"df":7,"docs":{"23":{"tf":1.7320508075688772},"24":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0},"27":{"tf":1.0},"40":{"tf":1.0},"42":{"tf":1.0}}}}},"u":{"df":0,"docs":{},"l":{"df":3,"docs":{"15":{"tf":1.0},"28":{"tf":1.0},"5":{"tf":1.0}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":8,"docs":{"18":{"tf":2.0},"30":{"tf":1.0},"34":{"tf":1.0},"37":{"tf":1.7320508075688772},"41":{"tf":1.7320508075688772},"52":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.0}}}}},"r":{"=":{"\\"":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"a":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"b":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"g":{"_":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":2,"docs":{"38":{"tf":1.0},"52":{"tf":1.0}},"s":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":2,"docs":{"38":{"tf":1.0},"52":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":2,"docs":{"38":{"tf":1.0},"51":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":1,"docs":{"38":{"tf":1.0}},"s":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"u":{"c":{"df":0,"docs":{},"h":{"df":4,"docs":{"0":{"tf":1.4142135623730951},"18":{"tf":1.0},"37":{"tf":1.0},"38":{"tf":1.0}}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"df":2,"docs":{"18":{"tf":1.0},"38":{"tf":1.0}}}}}}},"t":{"df":8,"docs":{"18":{"tf":1.0},"25":{"tf":1.0},"29":{"tf":1.0},"31":{"tf":1.0},"33":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"55":{"tf":1.0}}}}},"n":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"=":{"\\"":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"a":{"df":1,"docs":{"53":{"tf":1.0}}},"b":{"df":1,"docs":{"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":3,"docs":{"12":{"tf":1.0},"16":{"tf":1.0},"53":{"tf":1.4142135623730951}}}},"v":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":8,"docs":{"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"48":{"tf":1.0},"5":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0}}}}}},"df":1,"docs":{"55":{"tf":1.0}},"e":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.0}},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"t":{"df":1,"docs":{"41":{"tf":1.0}}}},"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":3,"docs":{"1":{"tf":1.0},"18":{"tf":1.0},"22":{"tf":1.0}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"0":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"e":{"d":{"df":4,"docs":{"18":{"tf":1.0},"30":{"tf":1.0},"31":{"tf":1.0},"42":{"tf":1.0}}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"w":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"k":{"df":1,"docs":{"7":{"tf":1.0}}}}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}}},"w":{"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":1,"docs":{"27":{"tf":1.0}},"e":{".":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"27":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":3,"docs":{"18":{"tf":2.23606797749979},"20":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"20":{"tf":1.4142135623730951}}}}},"x":{"df":0,"docs":{},"t":{"df":2,"docs":{"30":{"tf":1.0},"32":{"tf":1.0}}}}},"o":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"48":{"tf":1.0},"7":{"tf":1.4142135623730951}}}},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.0}}}}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"t":{"d":{"df":2,"docs":{"48":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}},"d":{"df":0,"docs":{},"e":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"n":{"df":1,"docs":{"20":{"tf":1.0}},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"<":{"[":{"df":0,"docs":{},"u":{"8":{"df":1,"docs":{"55":{"tf":1.0}}},"df":0,"docs":{}}},"_":{"df":1,"docs":{"55":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"r":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"18":{"tf":1.0},"30":{"tf":1.4142135623730951},"4":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"e":{"df":8,"docs":{"1":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0},"24":{"tf":1.0},"36":{"tf":1.0},"37":{"tf":1.0},"51":{"tf":1.0}}},"i":{"c":{"df":1,"docs":{"37":{"tf":1.0}}},"df":0,"docs":{},"f":{"df":8,"docs":{"18":{"tf":2.23606797749979},"19":{"tf":1.0},"20":{"tf":2.23606797749979},"34":{"tf":2.0},"35":{"tf":1.0},"36":{"tf":1.0},"37":{"tf":1.0},"38":{"tf":1.0}},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"\'":{"df":1,"docs":{"20":{"tf":1.4142135623730951}}},"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":2,"docs":{"18":{"tf":1.7320508075688772},"20":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":3,"docs":{"49":{"tf":1.0},"51":{"tf":1.4142135623730951},"52":{"tf":1.0}},"e":{"d":{"(":{"&":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"w":{"df":8,"docs":{"18":{"tf":1.7320508075688772},"22":{"tf":1.0},"32":{"tf":1.0},"33":{"tf":1.0},"38":{"tf":1.0},"4":{"tf":1.0},"41":{"tf":1.0},"43":{"tf":1.0}}}},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{":":{":":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"df":1,"docs":{"53":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"m":{"_":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"b":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"15":{"tf":1.0},"18":{"tf":1.7320508075688772}}}}},"df":0,"docs":{}}}},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"(":{"df":1,"docs":{"18":{"tf":1.0}}},"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{".":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"46":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"y":{"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"46":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"df":1,"docs":{"42":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":18,"docs":{"15":{"tf":3.1622776601683795},"16":{"tf":1.7320508075688772},"17":{"tf":1.0},"18":{"tf":4.358898943540674},"19":{"tf":1.0},"20":{"tf":1.0},"21":{"tf":1.0},"22":{"tf":1.0},"23":{"tf":2.23606797749979},"24":{"tf":1.4142135623730951},"29":{"tf":1.0},"30":{"tf":1.4142135623730951},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"35":{"tf":1.0},"38":{"tf":1.4142135623730951},"42":{"tf":2.449489742783178},"6":{"tf":1.4142135623730951}},"s":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"4":{":":{"2":{"2":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"7":{":":{"2":{"7":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"9":{":":{"3":{"3":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"3":{"2":{":":{"4":{"2":{"df":1,"docs":{"17":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"6":{":":{"4":{"3":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"5":{":":{"4":{"7":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"6":{"3":{":":{"6":{"3":{"df":1,"docs":{"20":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":2,"docs":{"1":{"tf":1.0},"26":{"tf":1.0}}}}}},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"46":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}},"c":{"c":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":1,"docs":{"20":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"i":{"df":1,"docs":{"0":{"tf":1.0}}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"26":{"tf":1.0}}}}}}},"k":{"(":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}},"a":{"df":0,"docs":{},"y":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":1,"docs":{"51":{"tf":1.0}}},"n":{"c":{"df":1,"docs":{"42":{"tf":1.0}}},"df":9,"docs":{"14":{"tf":1.0},"18":{"tf":1.0},"25":{"tf":1.0},"3":{"tf":1.0},"31":{"tf":1.0},"38":{"tf":1.4142135623730951},"41":{"tf":1.0},"5":{"tf":1.0},"55":{"tf":1.0}}},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":2,"docs":{"4":{"tf":1.0},"41":{"tf":1.0}}},"r":{"df":3,"docs":{"15":{"tf":1.0},"54":{"tf":1.0},"55":{"tf":1.4142135623730951}}}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":1,"docs":{"53":{"tf":1.0}}},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"52":{"tf":1.0}}}}}}},"r":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"25":{"tf":1.0}}}}},"df":1,"docs":{"20":{"tf":1.0}}},"s":{"df":1,"docs":{"7":{"tf":1.0}}},"u":{"df":0,"docs":{},"t":{"df":2,"docs":{"38":{"tf":1.0},"41":{"tf":1.0}},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"15":{"tf":1.0},"18":{"tf":1.0}}}}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":3,"docs":{"16":{"tf":1.0},"28":{"tf":1.0},"36":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"i":{"d":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":4,"docs":{"28":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"52":{"tf":1.0}},"f":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":2,"docs":{"11":{"tf":1.0},"12":{"tf":1.0}}}}}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"21":{"tf":1.4142135623730951}}}},"v":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"df":2,"docs":{"47":{"tf":1.0},"6":{"tf":1.0}}}}}}}}},"w":{"df":0,"docs":{},"n":{"_":{"df":0,"docs":{},"t":{"c":{"b":{"df":1,"docs":{"46":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":2,"docs":{"16":{"tf":2.8284271247461903},"42":{"tf":2.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"df":2,"docs":{"25":{"tf":1.0},"26":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}},":":{"#":{"df":0,"docs":{},"x":{"df":1,"docs":{"25":{"tf":1.0}}}},"df":0,"docs":{}},"df":3,"docs":{"25":{"tf":1.0},"26":{"tf":1.0},"27":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{".":{"c":{"a":{"df":0,"docs":{},"p":{"(":{")":{".":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"p":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"26":{"tf":1.0}}}}}}},"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":5,"docs":{"23":{"tf":1.7320508075688772},"25":{"tf":1.0},"26":{"tf":2.0},"38":{"tf":1.0},"5":{"tf":1.4142135623730951}},"p":{"df":0,"docs":{},"l":{"a":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"d":{"df":1,"docs":{"25":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"(":{"#":{"[":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"(":{"d":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"c":{"df":0,"docs":{},"o":{"d":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"[":{"0":{"df":0,"docs":{},"x":{"df":0,"docs":{},"e":{"df":1,"docs":{"25":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"i":{"c":{"\'":{"df":1,"docs":{"10":{"tf":1.0}}},"df":4,"docs":{"10":{"tf":1.4142135623730951},"49":{"tf":1.0},"8":{"tf":1.0},"9":{"tf":1.0}},"k":{"df":1,"docs":{"41":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"r":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":0,"docs":{},"h":{"df":2,"docs":{"18":{"tf":1.0},"30":{"tf":1.0}}}}},"df":0,"docs":{}}},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}}}}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":9,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.0},"20":{"tf":1.0},"27":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951},"50":{"tf":1.0}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}}}}},"df":0,"docs":{},"t":{"df":7,"docs":{"0":{"tf":1.7320508075688772},"41":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":1.0},"47":{"tf":1.7320508075688772},"5":{"tf":1.4142135623730951},"6":{"tf":1.7320508075688772}},"i":{"c":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":5,"docs":{"15":{"tf":1.0},"30":{"tf":1.4142135623730951},"34":{"tf":1.0},"4":{"tf":1.0},"5":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"s":{"df":0,"docs":{},"s":{"df":5,"docs":{"17":{"tf":1.0},"34":{"tf":1.0},"38":{"tf":1.7320508075688772},"43":{"tf":1.0},"6":{"tf":1.0}}}},"t":{"c":{"df":0,"docs":{},"h":{"df":2,"docs":{"1":{"tf":1.7320508075688772},"53":{"tf":1.0}}}},"df":0,"docs":{},"h":{"=":{"\\"":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":1,"docs":{"53":{"tf":1.0}}}}}}}},"d":{"=":{"\\"":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{},"s":{"/":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"4":{":":{"3":{"6":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{":":{"3":{"1":{"df":1,"docs":{"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"b":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"9":{":":{"1":{"8":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"2":{":":{"3":{"9":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{":":{"4":{"6":{"df":1,"docs":{"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"36":{"tf":1.0}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":2,"docs":{"21":{"tf":1.0},"27":{"tf":1.0}}}}},"s":{"=":{"\\"":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}},"w":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"h":{"df":0,"docs":{},"y":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"30":{"tf":1.0}}}},"df":7,"docs":{"15":{"tf":1.0},"23":{"tf":1.4142135623730951},"28":{"tf":1.0},"30":{"tf":1.7320508075688772},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"42":{"tf":1.0}}},"df":0,"docs":{}}}}},"i":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"1":{"tf":1.0}}}},"df":0,"docs":{},"e":{"c":{"df":1,"docs":{"41":{"tf":1.0}}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":4,"docs":{"15":{"tf":1.4142135623730951},"18":{"tf":1.7320508075688772},"3":{"tf":1.0},"38":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":5,"docs":{"15":{"tf":1.0},"33":{"tf":1.0},"53":{"tf":1.0},"54":{"tf":1.0},"55":{"tf":1.0}}}}}}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"38":{"tf":1.0}}}}},"s":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"b":{"df":0,"docs":{},"l":{"df":2,"docs":{"23":{"tf":1.0},"49":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"c":{"a":{"df":0,"docs":{},"r":{"d":{"df":1,"docs":{"52":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"p":{"=":{"\\"":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"e":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":4,"docs":{"1":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.0},"5":{"tf":1.0}}}}},"s":{"df":1,"docs":{"7":{"tf":1.0}}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"12":{"tf":1.0},"7":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"s":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":2,"docs":{"37":{"tf":1.0},"38":{"tf":1.0}}}}},"df":0,"docs":{},"e":{"df":1,"docs":{"32":{"tf":1.0}}}},"n":{"df":0,"docs":{},"t":{"df":3,"docs":{"10":{"tf":1.0},"16":{"tf":1.0},"33":{"tf":1.0}}}},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"=":{"\\"":{"1":{"0":{"0":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{"0":{"0":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"v":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":2,"docs":{"34":{"tf":1.4142135623730951},"6":{"tf":1.0}}}}}}}},"o":{"c":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":3,"docs":{"42":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":1.0}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":2,"docs":{"18":{"tf":1.0},"41":{"tf":1.0}}}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"\'":{"df":1,"docs":{"7":{"tf":1.0}}},"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":2,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}}},"df":10,"docs":{"2":{"tf":1.0},"21":{"tf":1.0},"22":{"tf":1.0},"25":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.0},"43":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"31":{"tf":1.0}}}}}}},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":5,"docs":{"0":{"tf":1.0},"3":{"tf":1.0},"41":{"tf":1.0},"5":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":7,"docs":{"0":{"tf":1.4142135623730951},"48":{"tf":1.0},"49":{"tf":1.7320508075688772},"51":{"tf":2.0},"52":{"tf":1.4142135623730951},"53":{"tf":2.449489742783178},"55":{"tf":1.0}},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"d":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":5,"docs":{"48":{"tf":1.4142135623730951},"49":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":2.449489742783178},"53":{"tf":2.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"v":{"df":0,"docs":{},"i":{"d":{"df":9,"docs":{"18":{"tf":1.0},"20":{"tf":1.0},"23":{"tf":1.4142135623730951},"4":{"tf":1.0},"41":{"tf":1.0},"53":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.0}}},"df":0,"docs":{}}}}},"t":{"df":0,"docs":{},"r":{":":{":":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"o":{"df":0,"docs":{},"f":{"!":{"(":{"_":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"x":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"26":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{")":{".":{"c":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{":":{":":{"<":{"df":0,"docs":{},"u":{"8":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"54":{"tf":1.0}}}},"u":{"b":{"df":1,"docs":{"54":{"tf":2.0}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":1,"docs":{"48":{"tf":1.0}}},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"s":{"df":2,"docs":{"27":{"tf":1.0},"30":{"tf":1.4142135623730951}}}}}},"t":{"df":2,"docs":{"53":{"tf":1.0},"55":{"tf":1.0}}}}},"q":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":1,"docs":{"7":{"tf":1.0}}}}},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}}}},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"df":3,"docs":{"18":{"tf":1.7320508075688772},"29":{"tf":1.0},"52":{"tf":1.0}},"e":{"<":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"e":{"a":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"42":{"tf":1.0}}}},"d":{"df":4,"docs":{"18":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"6":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"0":{"tf":1.0},"1":{"tf":1.0},"47":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"46":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"v":{"df":2,"docs":{"34":{"tf":1.0},"38":{"tf":2.23606797749979}},"e":{"df":0,"docs":{},"r":{"\'":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}}}},"k":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"42":{"tf":1.0}},"l":{"df":0,"docs":{},"y":{"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"a":{"df":0,"docs":{},"t":{"(":{")":{"\'":{"df":1,"docs":{"42":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"v":{"df":1,"docs":{"38":{"tf":1.7320508075688772}}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":10,"docs":{"15":{"tf":2.0},"16":{"tf":1.0},"18":{"tf":2.23606797749979},"20":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.4142135623730951},"30":{"tf":1.0},"38":{"tf":1.4142135623730951},"40":{"tf":1.0},"6":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"n":{"c":{"df":1,"docs":{"15":{"tf":1.0}}},"df":0,"docs":{}}}}}},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"\'":{"df":1,"docs":{"55":{"tf":1.0}}},"_":{"a":{":":{"#":{"df":0,"docs":{},"x":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"_":{"df":0,"docs":{},"s":{"df":1,"docs":{"54":{"tf":1.4142135623730951}}},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":2,"docs":{"53":{"tf":2.6457513110645907},"54":{"tf":1.0}}},"b":{":":{"#":{"df":0,"docs":{},"x":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":2,"docs":{"53":{"tf":2.449489742783178},"54":{"tf":1.0}}},"df":0,"docs":{}},"b":{"df":1,"docs":{"54":{"tf":1.4142135623730951}}},"df":8,"docs":{"16":{"tf":1.4142135623730951},"17":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.7320508075688772},"31":{"tf":1.0},"53":{"tf":1.7320508075688772},"54":{"tf":1.4142135623730951},"55":{"tf":1.0}}}},"s":{"df":0,"docs":{},"t":{"df":7,"docs":{"28":{"tf":1.4142135623730951},"30":{"tf":1.0},"33":{"tf":1.4142135623730951},"38":{"tf":1.7320508075688772},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0}}}}}},"l":{"_":{"a":{".":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"_":{"(":{"&":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"_":{"b":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":1,"docs":{"31":{"tf":1.0}}},"b":{"df":1,"docs":{"31":{"tf":1.0}}},"df":0,"docs":{}},"a":{"df":0,"docs":{},"t":{"df":2,"docs":{"37":{"tf":1.0},"6":{"tf":1.7320508075688772}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":2,"docs":{"18":{"tf":1.0},"3":{"tf":1.0}}}}},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"z":{"df":0,"docs":{},"v":{"df":1,"docs":{"38":{"tf":1.0}}}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":1,"docs":{"4":{"tf":1.0}}}}}},"p":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"40":{"tf":1.0}}},"y":{"_":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":1,"docs":{"38":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":2,"docs":{"1":{"tf":1.0},"4":{"tf":1.4142135623730951}}},"y":{"\'":{"df":1,"docs":{"3":{"tf":1.0}}},"df":0,"docs":{}}}}}}}},"r":{"(":{"c":{"df":2,"docs":{"25":{"tf":1.0},"54":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":3,"docs":{"15":{"tf":1.0},"23":{"tf":1.4142135623730951},"34":{"tf":1.0}}}}}},"q":{"df":0,"docs":{},"u":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":7,"docs":{"0":{"tf":1.0},"1":{"tf":1.0},"3":{"tf":1.0},"4":{"tf":1.0},"53":{"tf":1.0},"54":{"tf":1.0},"7":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"v":{"df":2,"docs":{"25":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951}}}},"t":{"df":1,"docs":{"31":{"tf":1.0}}}},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"c":{"df":3,"docs":{"0":{"tf":1.0},"16":{"tf":1.0},"47":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}},"p":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"s":{"df":1,"docs":{"16":{"tf":1.0}}}}}},"t":{"df":1,"docs":{"2":{"tf":1.0}},"r":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"t":{"df":2,"docs":{"16":{"tf":1.0},"21":{"tf":1.0}}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"<":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}}}}}},"df":0,"docs":{}}}}}},"df":2,"docs":{"13":{"tf":1.0},"51":{"tf":1.0}}}}}},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":1,"docs":{"17":{"tf":1.0}}}}}},"u":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":3,"docs":{"16":{"tf":1.4142135623730951},"20":{"tf":1.7320508075688772},"55":{"tf":1.4142135623730951}}}}}},"u":{"df":0,"docs":{},"s":{"df":1,"docs":{"18":{"tf":1.0}}}}},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":5,"docs":{"15":{"tf":1.0},"20":{"tf":1.4142135623730951},"22":{"tf":1.0},"27":{"tf":1.4142135623730951},"41":{"tf":1.0}}}}}},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"(":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"s":{"df":1,"docs":{"13":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"t":{"a":{"c":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"s":{"df":2,"docs":{"12":{"tf":1.0},"13":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":4,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"50":{"tf":1.0},"7":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}},"df":20,"docs":{"0":{"tf":1.4142135623730951},"12":{"tf":1.4142135623730951},"13":{"tf":1.0},"14":{"tf":1.0},"16":{"tf":1.4142135623730951},"17":{"tf":1.0},"18":{"tf":2.449489742783178},"20":{"tf":1.4142135623730951},"23":{"tf":2.23606797749979},"25":{"tf":1.4142135623730951},"26":{"tf":2.23606797749979},"27":{"tf":1.0},"28":{"tf":1.7320508075688772},"33":{"tf":1.4142135623730951},"34":{"tf":1.4142135623730951},"41":{"tf":2.0},"45":{"tf":1.0},"46":{"tf":1.4142135623730951},"6":{"tf":3.0},"7":{"tf":2.0}}}},"u":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"n":{"df":11,"docs":{"15":{"tf":1.0},"2":{"tf":1.4142135623730951},"22":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":2.0},"4":{"tf":1.4142135623730951},"48":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":11,"docs":{"0":{"tf":2.0},"13":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":2.449489742783178},"48":{"tf":1.0},"49":{"tf":1.0},"50":{"tf":1.7320508075688772},"53":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.7320508075688772}}}}}},"s":{"df":0,"docs":{},"t":{"\'":{"df":1,"docs":{"18":{"tf":1.0}}},"c":{"df":3,"docs":{"0":{"tf":1.0},"3":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"d":{"df":0,"docs":{},"o":{"c":{"_":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"k":{"df":2,"docs":{"18":{"tf":1.0},"20":{"tf":1.0}}}}}}},"df":3,"docs":{"5":{"tf":3.0},"50":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}},"df":17,"docs":{"0":{"tf":2.6457513110645907},"1":{"tf":1.7320508075688772},"3":{"tf":1.4142135623730951},"34":{"tf":1.0},"37":{"tf":1.4142135623730951},"38":{"tf":1.7320508075688772},"4":{"tf":2.0},"40":{"tf":1.0},"41":{"tf":2.0},"48":{"tf":1.4142135623730951},"5":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772},"54":{"tf":1.0},"6":{"tf":1.4142135623730951},"7":{"tf":1.7320508075688772}}}}}},"s":{"a":{"df":0,"docs":{},"f":{"df":0,"docs":{},"e":{"df":1,"docs":{"55":{"tf":1.0}}}},"k":{"df":0,"docs":{},"e":{"df":1,"docs":{"5":{"tf":1.0}}}},"m":{"df":0,"docs":{},"e":{"df":4,"docs":{"41":{"tf":1.0},"42":{"tf":1.0},"46":{"tf":1.0},"50":{"tf":1.4142135623730951}}},"p":{"df":0,"docs":{},"l":{"df":1,"docs":{"16":{"tf":1.0}}}}},"w":{"df":1,"docs":{"41":{"tf":1.0}}}},"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":1,"docs":{"18":{"tf":1.0}}}}},"r":{"a":{"df":0,"docs":{},"t":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"6":{"tf":1.4142135623730951}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":1,"docs":{"14":{"tf":1.0}},"e":{"a":{"df":0,"docs":{},"r":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}}},"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"d":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":2,"docs":{"37":{"tf":2.23606797749979},"38":{"tf":1.0}}},"y":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"(":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":1,"docs":{"38":{"tf":1.0}}}},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"n":{"df":1,"docs":{"37":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":3,"docs":{"37":{"tf":1.0},"38":{"tf":1.0},"40":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":1,"docs":{"18":{"tf":1.4142135623730951}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"df":0,"docs":{},"e":{"df":7,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.0},"30":{"tf":1.0},"40":{"tf":1.0},"55":{"tf":1.0}},"k":{"df":1,"docs":{"24":{"tf":1.0}}},"n":{"df":1,"docs":{"41":{"tf":1.0}}}},"l":{"4":{"/":{"c":{"a":{"df":0,"docs":{},"p":{"/":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{".":{"c":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{".":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"#":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"d":{".":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{":":{":":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"20":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{".":{"df":0,"docs":{},"h":{"df":2,"docs":{"37":{"tf":1.0},"41":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},":":{":":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{":":{":":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"20":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"18":{"tf":1.7320508075688772},"20":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":3,"docs":{"17":{"tf":1.0},"26":{"tf":1.0},"29":{"tf":1.0}},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}}}}}},"c":{"a":{"df":0,"docs":{},"p":{":":{":":{"c":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"38":{"tf":1.7320508075688772}}}}}}}},"df":0,"docs":{}}},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":3,"docs":{"24":{"tf":1.0},"32":{"tf":1.0},"46":{"tf":1.0}}}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":1,"docs":{"34":{"tf":1.0}}}}}}}}},"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":2,"docs":{"34":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"r":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"a":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}},"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":2,"docs":{"34":{"tf":1.0},"35":{"tf":1.0}}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":4,"docs":{"18":{"tf":1.0},"37":{"tf":1.4142135623730951},"38":{"tf":1.0},"46":{"tf":1.4142135623730951}},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{":":{":":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"df":1,"docs":{"19":{"tf":1.0}}}}}},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"19":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"t":{"c":{"b":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"u":{"df":0,"docs":{},"m":{"df":1,"docs":{"15":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":4,"docs":{"17":{"tf":1.0},"29":{"tf":1.0},"30":{"tf":1.0},"31":{"tf":1.0}},"e":{"d":{":":{":":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"<":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"15":{"tf":1.0}},"e":{":":{":":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"24":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"t":{"df":1,"docs":{"15":{"tf":1.0}}}},"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":2,"docs":{"23":{"tf":1.0},"32":{"tf":1.0}},"e":{":":{":":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"_":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"24":{"tf":1.0}}}}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"t":{"c":{"b":{"df":1,"docs":{"15":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"v":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":1,"docs":{"23":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":1,"docs":{"15":{"tf":1.0}},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":0,"docs":{},"t":{"df":0,"docs":{},"s":{":":{":":{"a":{"df":0,"docs":{},"l":{"df":2,"docs":{"20":{"tf":1.0},"21":{"tf":1.0}}}},"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"21":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"e":{"a":{"d":{"_":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"27":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":2,"docs":{"15":{"tf":1.0},"23":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"x":{"df":0,"docs":{},"e":{"d":{"df":0,"docs":{},"s":{"df":1,"docs":{"24":{"tf":1.0}}}},"df":0,"docs":{}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}}}}}}},"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"15":{"tf":1.0}}}}}},"d":{"df":0,"docs":{},"e":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"14":{"tf":1.0}},"l":{"df":0,"docs":{},"n":{"!":{"(":{"\\"":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"7":{"tf":1.0}}}}}}},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"37":{"tf":1.4142135623730951},"38":{"tf":1.4142135623730951}}}},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"16":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"16":{"tf":1.0}}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{".":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"25":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{":":{":":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{":":{":":{"c":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":1,"docs":{"31":{"tf":1.7320508075688772}},"e":{".":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"_":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{".":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"34":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"v":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":0,"docs":{},"e":{".":{"c":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"27":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"<":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{":":{":":{"c":{"a":{"df":0,"docs":{},"p":{"_":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{":":{":":{"df":0,"docs":{},"g":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":1,"docs":{"26":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":2,"docs":{"20":{"tf":1.0},"31":{"tf":1.4142135623730951}}}}},"u":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":1,"docs":{"7":{"tf":1.4142135623730951}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{":":{":":{"df":0,"docs":{},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"20":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{":":{":":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"18":{"tf":1.0},"24":{"tf":1.0}}}}}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"40":{"tf":1.0}}}}}}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"c":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":0,"docs":{},"e":{"_":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"16":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":1,"docs":{"30":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"v":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":1,"docs":{"27":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"p":{"c":{"_":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"f":{"df":0,"docs":{},"f":{"df":3,"docs":{"38":{"tf":1.0},"39":{"tf":1.0},"51":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":3,"docs":{"38":{"tf":1.0},"39":{"tf":1.0},"51":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"_":{"a":{"b":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"a":{"c":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":1,"docs":{"55":{"tf":1.0}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"27":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"40":{"tf":1.0}}}},"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"18":{"tf":1.0}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"_":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{":":{":":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.0}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"r":{"df":0,"docs":{},"q":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"_":{"a":{"c":{"df":0,"docs":{},"k":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}},"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"34":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"n":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":1,"docs":{"34":{"tf":1.0}}}}}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"l":{"df":0,"docs":{},"i":{"b":{"df":2,"docs":{"37":{"tf":1.0},"6":{"tf":1.0}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"g":{"df":1,"docs":{"14":{"tf":1.0}}}}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"_":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{":":{":":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":1,"docs":{"49":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"y":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"y":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":1,"docs":{"55":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":1,"docs":{"51":{"tf":1.0}}}}}}}}},"df":0,"docs":{}}}}},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{":":{":":{"c":{"a":{"df":0,"docs":{},"t":{"c":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"50":{"tf":1.0}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":1,"docs":{"50":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"v":{"a":{"df":0,"docs":{},"r":{"df":2,"docs":{"53":{"tf":1.0},"55":{"tf":1.0}}}},"df":0,"docs":{}},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"s":{"df":0,"docs":{},"{":{",":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"52":{"tf":1.0}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}}},"{":{"d":{"df":0,"docs":{},"e":{"b":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"_":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"l":{"df":0,"docs":{},"n":{"df":1,"docs":{"48":{"tf":1.0}}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":3,"docs":{"48":{"tf":1.0},"50":{"tf":1.0},"51":{"tf":1.0}}}}}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":1,"docs":{"34":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"a":{"c":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"s":{"df":1,"docs":{"12":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{":":{":":{"c":{"a":{"df":0,"docs":{},"t":{"c":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"9":{"tf":1.0}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":1,"docs":{"10":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"df":1,"docs":{"7":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"7":{"tf":1.0}}}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"13":{"tf":1.0},"7":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"34":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":21,"docs":{"0":{"tf":3.605551275463989},"1":{"tf":1.0},"14":{"tf":1.0},"15":{"tf":2.23606797749979},"16":{"tf":1.0},"18":{"tf":1.7320508075688772},"2":{"tf":1.4142135623730951},"20":{"tf":1.0},"23":{"tf":2.23606797749979},"3":{"tf":1.0},"30":{"tf":1.4142135623730951},"37":{"tf":1.7320508075688772},"38":{"tf":1.4142135623730951},"4":{"tf":1.0},"40":{"tf":1.0},"41":{"tf":2.8284271247461903},"47":{"tf":2.0},"5":{"tf":1.4142135623730951},"55":{"tf":1.4142135623730951},"6":{"tf":3.0},"7":{"tf":1.7320508075688772}},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"s":{"/":{"df":0,"docs":{},"p":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{".":{"df":0,"docs":{},"h":{"df":1,"docs":{"41":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{".":{"df":0,"docs":{},"h":{"df":1,"docs":{"37":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":2,"docs":{"18":{"tf":1.0},"4":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"f":{":":{":":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":2,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"51":{"tf":1.4142135623730951},"53":{"tf":1.0}}}},"n":{"d":{"df":4,"docs":{"38":{"tf":2.0},"39":{"tf":1.0},"41":{"tf":1.0},"52":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"\'":{"df":1,"docs":{"38":{"tf":1.4142135623730951}}},"df":1,"docs":{"38":{"tf":1.7320508075688772}}}}},"df":0,"docs":{}},"p":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"4":{"tf":1.0}}}},"df":0,"docs":{}},"q":{"df":0,"docs":{},"u":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"c":{"df":2,"docs":{"36":{"tf":1.0},"46":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}}},"r":{"d":{"df":1,"docs":{"52":{"tf":1.0}}},"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"l":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":2,"docs":{"33":{"tf":1.0},"36":{"tf":1.0}},"e":{".":{"c":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"a":{"df":0,"docs":{},"r":{"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"r":{"df":0,"docs":{},"u":{"df":0,"docs":{},"p":{"df":0,"docs":{},"t":{"df":1,"docs":{"36":{"tf":1.0}}}}}}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"33":{"tf":1.0}}}}}},"p":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"_":{"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"r":{"(":{"*":{"c":{"df":1,"docs":{"33":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"_":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"c":{"a":{"df":0,"docs":{},"p":{".":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"_":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"(":{")":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"32":{"tf":1.0}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":3,"docs":{"32":{"tf":1.0},"33":{"tf":1.0},"46":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"i":{"df":0,"docs":{},"r":{"df":0,"docs":{},"q":{"df":4,"docs":{"28":{"tf":1.0},"34":{"tf":1.0},"45":{"tf":1.0},"46":{"tf":1.4142135623730951}}}}},"m":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"_":{"df":0,"docs":{},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":5,"docs":{"28":{"tf":1.0},"30":{"tf":1.4142135623730951},"31":{"tf":1.7320508075688772},"32":{"tf":1.4142135623730951},"45":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"33":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":15,"docs":{"28":{"tf":3.0},"29":{"tf":1.0},"30":{"tf":1.7320508075688772},"31":{"tf":1.0},"32":{"tf":1.0},"33":{"tf":1.7320508075688772},"34":{"tf":1.0},"35":{"tf":1.0},"36":{"tf":1.7320508075688772},"41":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":2.23606797749979},"52":{"tf":1.0}}}},"df":1,"docs":{"1":{"tf":1.0}}},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"\'":{"df":1,"docs":{"52":{"tf":1.0}}},".":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"f":{"df":2,"docs":{"51":{"tf":1.0},"53":{"tf":1.0}}}}},"p":{"df":0,"docs":{},"p":{"_":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"52":{"tf":1.0}},"l":{"(":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{":":{":":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"f":{"a":{"df":0,"docs":{},"u":{"df":0,"docs":{},"l":{"df":0,"docs":{},"t":{"df":1,"docs":{"53":{"tf":1.0}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":4,"docs":{"4":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":1.0},"54":{"tf":1.0}}}},"i":{"c":{"df":1,"docs":{"7":{"tf":1.0}}},"df":0,"docs":{}}}},"t":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"r":{"df":1,"docs":{"51":{"tf":1.0}}}}},"df":6,"docs":{"10":{"tf":1.4142135623730951},"23":{"tf":1.0},"28":{"tf":1.0},"41":{"tf":1.0},"46":{"tf":1.0},"5":{"tf":1.0}},"u":{"df":0,"docs":{},"p":{"df":5,"docs":{"1":{"tf":1.7320508075688772},"2":{"tf":1.0},"3":{"tf":1.0},"4":{"tf":1.0},"5":{"tf":1.0}}}},"v":{"a":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"=":{"\\"":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"a":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"b":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"h":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":1,"docs":{"1":{"tf":1.0}}}},"p":{"df":0,"docs":{},"e":{"df":1,"docs":{"18":{"tf":1.4142135623730951}}}},"r":{"df":0,"docs":{},"e":{"df":4,"docs":{"23":{"tf":1.0},"53":{"tf":3.1622776601683795},"54":{"tf":1.7320508075688772},"55":{"tf":2.23606797749979}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":1,"docs":{"2":{"tf":1.4142135623730951}}}}},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"0":{"tf":1.0}}}}}},"w":{"df":1,"docs":{"41":{"tf":1.0}}}}},"i":{"d":{"df":0,"docs":{},"e":{"b":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"5":{"tf":1.0}}}},"df":0,"docs":{}},"df":1,"docs":{"38":{"tf":1.4142135623730951}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"n":{"a":{"df":0,"docs":{},"l":{"df":2,"docs":{"19":{"tf":1.0},"20":{"tf":1.7320508075688772}}},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"r":{"df":2,"docs":{"49":{"tf":1.0},"7":{"tf":1.0}}}}}},"df":0,"docs":{}}},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"r":{"df":2,"docs":{"42":{"tf":1.0},"46":{"tf":1.0}},"l":{"df":0,"docs":{},"i":{"df":2,"docs":{"41":{"tf":1.0},"46":{"tf":1.0}}}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"l":{"df":2,"docs":{"14":{"tf":1.0},"28":{"tf":1.0}},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"49":{"tf":1.0}}}}},"i":{"df":1,"docs":{"44":{"tf":1.0}},"f":{"df":0,"docs":{},"i":{"df":1,"docs":{"3":{"tf":1.0}}}}}}},"u":{"df":0,"docs":{},"l":{"df":9,"docs":{"15":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.0},"48":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0},"7":{"tf":1.0}},"t":{"a":{"df":0,"docs":{},"n":{"df":1,"docs":{"18":{"tf":1.0}}}},"df":0,"docs":{}}}}},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"l":{"df":1,"docs":{"18":{"tf":1.0}}}}},"t":{"df":0,"docs":{},"u":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}},"df":0,"docs":{}}},"z":{"df":0,"docs":{},"e":{"=":{"\\"":{"0":{"df":0,"docs":{},"x":{"1":{"_":{"0":{"0":{"0":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"_":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"18":{"tf":1.4142135623730951},"31":{"tf":1.7320508075688772}}}}},"df":0,"docs":{}},"df":8,"docs":{"12":{"tf":1.7320508075688772},"13":{"tf":1.0},"16":{"tf":3.0},"18":{"tf":1.7320508075688772},"20":{"tf":1.4142135623730951},"23":{"tf":1.0},"25":{"tf":1.0},"38":{"tf":1.0}}}}},"l":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"e":{"df":1,"docs":{"55":{"tf":1.0}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"t":{"<":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}}}}}}}},"df":5,"docs":{"15":{"tf":1.7320508075688772},"18":{"tf":3.0},"20":{"tf":1.7320508075688772},"26":{"tf":1.0},"31":{"tf":1.4142135623730951}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"<":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"17":{"tf":1.0}}}}}}}},"df":0,"docs":{}}}}}}}}}},"m":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":1,"docs":{"32":{"tf":1.0}},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":1,"docs":{"23":{"tf":1.0}}}}}}}},"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":1,"docs":{"38":{"tf":1.0}}}}}}},"n":{"df":0,"docs":{},"i":{"df":0,"docs":{},"p":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":2,"docs":{"24":{"tf":1.0},"29":{"tf":1.0}}}}}}}},"o":{"df":0,"docs":{},"l":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":2,"docs":{"33":{"tf":1.0},"52":{"tf":1.0}}}},"w":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.0}}}}}}}},"r":{"df":0,"docs":{},"t":{"df":1,"docs":{"41":{"tf":1.0}}}},"u":{"df":0,"docs":{},"r":{"c":{"df":2,"docs":{"48":{"tf":1.0},"7":{"tf":1.4142135623730951}}},"df":0,"docs":{}}}},"p":{"a":{"c":{"df":0,"docs":{},"e":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"5":{":":{"2":{"0":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"6":{":":{"4":{"9":{"df":1,"docs":{"25":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"5":{"1":{":":{"5":{"4":{"df":1,"docs":{"26":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{"3":{":":{"8":{"4":{"df":1,"docs":{"26":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":12,"docs":{"15":{"tf":1.4142135623730951},"23":{"tf":3.3166247903554},"24":{"tf":1.0},"25":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951},"27":{"tf":1.0},"28":{"tf":1.0},"33":{"tf":1.4142135623730951},"43":{"tf":1.4142135623730951},"46":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.7320508075688772}}}},"df":0,"docs":{},"w":{"df":0,"docs":{},"n":{"df":12,"docs":{"34":{"tf":1.0},"37":{"tf":2.449489742783178},"38":{"tf":1.0},"39":{"tf":1.0},"40":{"tf":1.0},"41":{"tf":3.0},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"45":{"tf":1.0},"46":{"tf":1.0},"6":{"tf":1.0}}}}},"df":0,"docs":{},"e":{"c":{"df":1,"docs":{"3":{"tf":1.0}},"i":{"a":{"df":0,"docs":{},"l":{"df":3,"docs":{"34":{"tf":1.0},"38":{"tf":1.0},"55":{"tf":1.0}}}},"df":0,"docs":{},"f":{"df":4,"docs":{"0":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.7320508075688772},"34":{"tf":1.0}},"i":{"df":5,"docs":{"18":{"tf":1.4142135623730951},"20":{"tf":1.0},"38":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.4142135623730951}}}}}},"df":0,"docs":{}}},"r":{"c":{"_":{"df":1,"docs":{"18":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"t":{"a":{"c":{"df":0,"docs":{},"k":{"_":{"df":0,"docs":{},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":2,"docs":{"12":{"tf":1.0},"13":{"tf":1.0}}}}}},"df":4,"docs":{"11":{"tf":1.0},"12":{"tf":2.0},"37":{"tf":1.0},"41":{"tf":1.0}}}},"df":0,"docs":{},"n":{"d":{"a":{"df":0,"docs":{},"r":{"d":{"df":2,"docs":{"41":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"t":{"df":8,"docs":{"1":{"tf":1.4142135623730951},"15":{"tf":1.0},"2":{"tf":1.0},"23":{"tf":1.0},"28":{"tf":1.0},"37":{"tf":1.0},"41":{"tf":1.4142135623730951},"54":{"tf":1.0}}}},"t":{"df":0,"docs":{},"e":{"df":3,"docs":{"20":{"tf":1.4142135623730951},"42":{"tf":1.0},"53":{"tf":1.0}}},"i":{"c":{"df":4,"docs":{"14":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0},"47":{"tf":1.0}}},"df":0,"docs":{}}}},"d":{"df":1,"docs":{"7":{"tf":1.7320508075688772}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"\'":{"df":1,"docs":{"55":{"tf":1.0}}},"df":39,"docs":{"1":{"tf":2.6457513110645907},"10":{"tf":1.4142135623730951},"11":{"tf":1.4142135623730951},"12":{"tf":1.4142135623730951},"13":{"tf":1.4142135623730951},"14":{"tf":1.7320508075688772},"16":{"tf":1.4142135623730951},"17":{"tf":1.4142135623730951},"18":{"tf":1.7320508075688772},"19":{"tf":1.4142135623730951},"20":{"tf":1.4142135623730951},"21":{"tf":1.4142135623730951},"22":{"tf":1.4142135623730951},"24":{"tf":1.4142135623730951},"25":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951},"27":{"tf":1.4142135623730951},"29":{"tf":1.4142135623730951},"30":{"tf":1.7320508075688772},"31":{"tf":1.4142135623730951},"32":{"tf":1.4142135623730951},"33":{"tf":2.23606797749979},"34":{"tf":1.4142135623730951},"35":{"tf":1.4142135623730951},"36":{"tf":1.4142135623730951},"38":{"tf":1.7320508075688772},"39":{"tf":1.4142135623730951},"40":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951},"42":{"tf":2.23606797749979},"43":{"tf":2.0},"44":{"tf":2.23606797749979},"45":{"tf":1.7320508075688772},"46":{"tf":2.6457513110645907},"52":{"tf":1.4142135623730951},"54":{"tf":1.4142135623730951},"55":{"tf":1.4142135623730951},"8":{"tf":1.4142135623730951},"9":{"tf":1.4142135623730951}}}},"o":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"g":{"df":1,"docs":{"41":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":1,"docs":{"53":{"tf":1.0}}}}},"r":{"df":0,"docs":{},"u":{"c":{"df":0,"docs":{},"t":{"df":6,"docs":{"23":{"tf":1.0},"25":{"tf":1.0},"48":{"tf":1.0},"51":{"tf":1.4142135623730951},"53":{"tf":1.0},"54":{"tf":1.0}},"u":{"df":0,"docs":{},"r":{"df":3,"docs":{"23":{"tf":1.7320508075688772},"25":{"tf":1.0},"7":{"tf":1.0}}}}}},"df":0,"docs":{}}},"u":{"b":{"df":1,"docs":{"6":{"tf":1.0}}},"d":{"df":0,"docs":{},"i":{"df":1,"docs":{"5":{"tf":1.0}}}},"df":0,"docs":{}}},"u":{"b":{"df":1,"docs":{"46":{"tf":1.4142135623730951}},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"3":{"tf":1.0}}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"q":{"df":0,"docs":{},"u":{"df":1,"docs":{"42":{"tf":1.0}}}}}}},"c":{"c":{"df":0,"docs":{},"e":{"df":1,"docs":{"32":{"tf":1.0}}}},"df":0,"docs":{},"h":{"df":7,"docs":{"14":{"tf":1.0},"16":{"tf":1.0},"37":{"tf":1.4142135623730951},"47":{"tf":1.0},"53":{"tf":1.0},"6":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":1,"docs":{"55":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"m":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"18":{"tf":1.0}}}}},"df":0,"docs":{}}},"p":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"t":{"df":3,"docs":{"0":{"tf":1.0},"50":{"tf":1.0},"7":{"tf":1.0}}}},"s":{"df":1,"docs":{"54":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"7":{"tf":1.0}}},"df":0,"docs":{}}}}}},"y":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"l":{"df":3,"docs":{"53":{"tf":2.449489742783178},"54":{"tf":1.0},"55":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}},"s":{"c":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"40":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"\'":{"df":1,"docs":{"16":{"tf":1.0}}},"df":6,"docs":{"15":{"tf":1.0},"47":{"tf":1.0},"51":{"tf":1.7320508075688772},"53":{"tf":1.7320508075688772},"54":{"tf":1.0},"6":{"tf":1.0}}}}}}}},"t":{"a":{"b":{"df":0,"docs":{},"l":{"df":2,"docs":{"15":{"tf":1.0},"23":{"tf":1.0}}}},"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":4,"docs":{"31":{"tf":1.0},"38":{"tf":1.4142135623730951},"43":{"tf":1.0},"50":{"tf":1.0}}}},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.7320508075688772}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":5,"docs":{"0":{"tf":1.0},"18":{"tf":1.7320508075688772},"3":{"tf":1.7320508075688772},"31":{"tf":1.0},"7":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"k":{"\'":{"df":14,"docs":{"12":{"tf":1.4142135623730951},"13":{"tf":1.0},"16":{"tf":1.0},"20":{"tf":1.0},"23":{"tf":1.7320508075688772},"25":{"tf":1.4142135623730951},"26":{"tf":1.7320508075688772},"27":{"tf":1.0},"28":{"tf":1.4142135623730951},"33":{"tf":1.4142135623730951},"43":{"tf":1.4142135623730951},"46":{"tf":1.4142135623730951},"6":{"tf":1.4142135623730951},"7":{"tf":1.0}}},".":{"df":0,"docs":{},"m":{"df":0,"docs":{},"k":{":":{"3":{"1":{":":{"3":{"6":{"df":1,"docs":{"6":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"/":{".":{"c":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"o":{"/":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"df":1,"docs":{"3":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":3,"docs":{"23":{"tf":1.0},"25":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"j":{"df":0,"docs":{},"s":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":1,"docs":{"4":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}}}},"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"7":{"tf":1.0}}}}}}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":5,"docs":{"15":{"tf":1.0},"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":2.0},"20":{"tf":1.0}}}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":5,"docs":{"28":{"tf":1.7320508075688772},"29":{"tf":1.4142135623730951},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"33":{"tf":1.0}}}}},"p":{"a":{"df":0,"docs":{},"w":{"df":0,"docs":{},"n":{"df":5,"docs":{"37":{"tf":1.7320508075688772},"38":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0}}}}},"df":0,"docs":{}},"r":{"c":{"/":{"c":{"df":0,"docs":{},"h":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"d":{"_":{"df":0,"docs":{},"v":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":0,"docs":{},"e":{".":{"df":0,"docs":{},"r":{"df":1,"docs":{"43":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"_":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"a":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{".":{"df":0,"docs":{},"r":{"df":1,"docs":{"42":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":19,"docs":{"0":{"tf":1.4142135623730951},"14":{"tf":1.0},"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":1.0},"20":{"tf":1.0},"23":{"tf":1.0},"26":{"tf":1.4142135623730951},"28":{"tf":1.0},"3":{"tf":1.0},"34":{"tf":1.4142135623730951},"41":{"tf":4.242640687119285},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.4142135623730951},"45":{"tf":1.4142135623730951},"46":{"tf":2.449489742783178},"6":{"tf":2.6457513110645907},"7":{"tf":1.7320508075688772}}}}},"df":4,"docs":{"15":{"tf":1.7320508075688772},"18":{"tf":1.0},"49":{"tf":1.4142135623730951},"7":{"tf":1.4142135623730951}},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":2,"docs":{"18":{"tf":1.0},"34":{"tf":1.0}}}},"m":{"df":0,"docs":{},"p":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"31":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}},"r":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"7":{"tf":1.4142135623730951}}}}}},"s":{"df":0,"docs":{},"t":{"_":{"df":0,"docs":{},"p":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"51":{"tf":1.0}}}}},"df":0,"docs":{}}},"df":2,"docs":{"1":{"tf":1.4142135623730951},"41":{"tf":1.0}}}},"x":{"df":0,"docs":{},"t":{"df":7,"docs":{"0":{"tf":1.0},"1":{"tf":1.0},"2":{"tf":1.0},"38":{"tf":1.0},"47":{"tf":1.0},"5":{"tf":1.0},"6":{"tf":1.0}}}}},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"v":{"df":1,"docs":{"1":{"tf":1.0}}}}}}}},"i":{"df":0,"docs":{},"n":{"df":2,"docs":{"51":{"tf":1.0},"55":{"tf":1.0}}}},"o":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":2,"docs":{"1":{"tf":1.4142135623730951},"41":{"tf":1.0}}}},"u":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":1,"docs":{"37":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"e":{"a":{"d":{"\'":{"df":3,"docs":{"12":{"tf":1.4142135623730951},"15":{"tf":1.0},"18":{"tf":2.449489742783178}}},"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"7":{"5":{":":{"7":{"9":{"df":2,"docs":{"37":{"tf":1.0},"38":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"8":{"1":{":":{"8":{"5":{"df":1,"docs":{"37":{"tf":1.0}}},"7":{"df":1,"docs":{"38":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":8,"docs":{"15":{"tf":1.7320508075688772},"23":{"tf":1.0},"37":{"tf":3.3166247903554},"38":{"tf":2.0},"39":{"tf":1.0},"40":{"tf":1.0},"41":{"tf":1.4142135623730951},"7":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{},"e":{"df":2,"docs":{"47":{"tf":1.0},"7":{"tf":1.0}}}},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"g":{"df":0,"docs":{},"h":{"df":3,"docs":{"37":{"tf":1.0},"42":{"tf":1.0},"47":{"tf":1.0}}}}}}},"u":{"df":1,"docs":{"15":{"tf":1.0}}}},"i":{"df":0,"docs":{},"m":{"df":0,"docs":{},"e":{"df":6,"docs":{"13":{"tf":1.0},"16":{"tf":1.0},"2":{"tf":1.0},"53":{"tf":1.0},"54":{"tf":1.0},"6":{"tf":1.7320508075688772}}}}},"l":{"df":2,"docs":{"37":{"tf":1.0},"41":{"tf":1.0}}},"o":{"d":{"df":0,"docs":{},"o":{"df":1,"docs":{"51":{"tf":1.0}}}},"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"h":{"df":2,"docs":{"38":{"tf":1.0},"55":{"tf":1.0}}}}}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":1,"docs":{"15":{"tf":1.0}}}}},"o":{"df":0,"docs":{},"l":{"df":2,"docs":{"2":{"tf":1.0},"53":{"tf":1.4142135623730951}}}},"p":{"df":4,"docs":{"14":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.0},"5":{"tf":1.0}}},"w":{"a":{"df":0,"docs":{},"r":{"d":{"df":2,"docs":{"18":{"tf":1.0},"41":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"r":{"a":{"c":{"df":0,"docs":{},"k":{"df":2,"docs":{"18":{"tf":1.0},"42":{"tf":1.0}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":2,"docs":{"24":{"tf":1.0},"49":{"tf":1.0}}}},"n":{"df":0,"docs":{},"s":{"df":0,"docs":{},"l":{"a":{"df":0,"docs":{},"t":{"df":3,"docs":{"15":{"tf":1.4142135623730951},"23":{"tf":1.4142135623730951},"25":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"e":{"df":1,"docs":{"23":{"tf":1.0}}}},"i":{"df":3,"docs":{"26":{"tf":1.0},"33":{"tf":1.0},"46":{"tf":1.4142135623730951}},"m":{"_":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.7320508075688772}}}}}}}},"df":0,"docs":{}},"v":{"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"e":{"df":1,"docs":{"16":{"tf":2.6457513110645907}}}}},"u":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":3,"docs":{"17":{"tf":1.0},"20":{"tf":1.0},"54":{"tf":1.0}}}},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":5,"docs":{"0":{"tf":1.7320508075688772},"1":{"tf":2.0},"18":{"tf":1.0},"47":{"tf":1.0},"6":{"tf":1.0}}}}}}},"w":{"df":0,"docs":{},"o":{"df":12,"docs":{"1":{"tf":1.0},"18":{"tf":1.0},"23":{"tf":1.0},"3":{"tf":1.7320508075688772},"30":{"tf":1.0},"31":{"tf":1.4142135623730951},"37":{"tf":1.0},"38":{"tf":1.7320508075688772},"41":{"tf":1.0},"5":{"tf":1.4142135623730951},"51":{"tf":1.0},"53":{"tf":1.4142135623730951}}}},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"\'":{"df":1,"docs":{"18":{"tf":1.0}}},"df":17,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"15":{"tf":2.8284271247461903},"16":{"tf":1.0},"18":{"tf":2.449489742783178},"20":{"tf":1.0},"23":{"tf":2.0},"30":{"tf":1.0},"38":{"tf":1.4142135623730951},"42":{"tf":1.0},"44":{"tf":1.4142135623730951},"48":{"tf":1.0},"51":{"tf":2.449489742783178},"52":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951},"54":{"tf":1.7320508075688772},"55":{"tf":2.0}}},"i":{"c":{"df":1,"docs":{"7":{"tf":1.0}}},"df":0,"docs":{}}}}},"u":{"1":{"6":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"6":{"4":{"df":1,"docs":{"54":{"tf":1.0}}},"df":0,"docs":{}},"8":{"df":3,"docs":{"25":{"tf":1.0},"54":{"tf":1.0},"55":{"tf":1.0}}},"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":2,"docs":{"38":{"tf":1.0},"51":{"tf":1.0}},"l":{"df":0,"docs":{},"i":{"df":1,"docs":{"55":{"tf":1.0}}}},"s":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"n":{"d":{"df":1,"docs":{"1":{"tf":1.0}}},"df":0,"docs":{}}},"df":0,"docs":{}}}}}},"df":0,"docs":{},"f":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"g":{"df":1,"docs":{"15":{"tf":1.0}}}}}},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"k":{"df":1,"docs":{"6":{"tf":1.0}}}}},"m":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"26":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"s":{"a":{"df":0,"docs":{},"f":{"df":4,"docs":{"26":{"tf":1.0},"33":{"tf":1.0},"54":{"tf":1.4142135623730951},"55":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"l":{"df":3,"docs":{"31":{"tf":1.0},"38":{"tf":1.0},"42":{"tf":1.0}}}},"y":{"df":0,"docs":{},"p":{"df":6,"docs":{"16":{"tf":2.0},"17":{"tf":1.0},"18":{"tf":2.23606797749979},"30":{"tf":2.449489742783178},"31":{"tf":2.0},"42":{"tf":2.449489742783178}},"e":{"d":{"\'":{"df":2,"docs":{"30":{"tf":1.0},"31":{"tf":1.0}}},"_":{"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":0,"docs":{},"t":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}}}},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"w":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"p":{"df":4,"docs":{"17":{"tf":1.0},"18":{"tf":1.0},"29":{"tf":1.0},"31":{"tf":1.0}}}},"df":0,"docs":{}}},"y":{"df":0,"docs":{},"t":{"df":0,"docs":{},"p":{"df":1,"docs":{"18":{"tf":1.0}}}}}},"p":{"d":{"a":{"df":0,"docs":{},"t":{"df":1,"docs":{"20":{"tf":1.0}}}},"df":0,"docs":{}},"df":7,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"28":{"tf":1.0},"38":{"tf":1.0},"41":{"tf":1.0},"46":{"tf":1.0},"54":{"tf":1.0}}},"s":{"df":46,"docs":{"0":{"tf":1.7320508075688772},"1":{"tf":1.4142135623730951},"13":{"tf":1.4142135623730951},"14":{"tf":1.0},"15":{"tf":1.4142135623730951},"16":{"tf":1.4142135623730951},"18":{"tf":1.7320508075688772},"19":{"tf":1.0},"20":{"tf":2.449489742783178},"21":{"tf":1.0},"22":{"tf":1.0},"23":{"tf":1.4142135623730951},"24":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.7320508075688772},"27":{"tf":1.4142135623730951},"28":{"tf":1.7320508075688772},"29":{"tf":1.4142135623730951},"30":{"tf":2.0},"31":{"tf":1.0},"32":{"tf":1.0},"33":{"tf":1.4142135623730951},"34":{"tf":2.0},"35":{"tf":1.4142135623730951},"36":{"tf":2.23606797749979},"37":{"tf":2.23606797749979},"38":{"tf":2.23606797749979},"39":{"tf":1.0},"4":{"tf":1.4142135623730951},"41":{"tf":1.4142135623730951},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"46":{"tf":2.0},"47":{"tf":1.0},"48":{"tf":1.0},"49":{"tf":1.0},"5":{"tf":1.0},"51":{"tf":1.0},"52":{"tf":2.449489742783178},"53":{"tf":1.0},"54":{"tf":1.4142135623730951},"55":{"tf":1.0},"6":{"tf":2.23606797749979},"7":{"tf":1.0},"9":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"_":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"g":{"df":0,"docs":{},"e":{"_":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"26":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"a":{"df":0,"docs":{},"m":{"df":1,"docs":{"26":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":1,"docs":{"15":{"tf":1.4142135623730951}},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":6,"docs":{"0":{"tf":2.0},"15":{"tf":1.0},"16":{"tf":1.0},"34":{"tf":1.4142135623730951},"41":{"tf":1.0},"6":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"i":{"df":0,"docs":{},"z":{"df":9,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"25":{"tf":1.4142135623730951},"26":{"tf":2.0},"28":{"tf":1.4142135623730951},"31":{"tf":1.4142135623730951},"53":{"tf":2.449489742783178},"54":{"tf":1.0},"55":{"tf":1.0}}}}},"t":{".":{"df":0,"docs":{},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":0,"docs":{},"e":{"d":{"_":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"t":{"df":0,"docs":{},"y":{"df":0,"docs":{},"p":{"df":1,"docs":{"31":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"c":{".":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"_":{"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"i":{"c":{"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}}},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"16":{"tf":1.0}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"i":{"df":0,"docs":{},"z":{"df":0,"docs":{},"e":{"_":{"b":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"16":{"tf":1.0}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}},"df":1,"docs":{"16":{"tf":1.0}}},"df":0,"docs":{}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"x":{"df":2,"docs":{"17":{"tf":1.0},"29":{"tf":1.0}}}},"p":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"31":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":1,"docs":{"31":{"tf":1.0}},"i":{"df":0,"docs":{},"l":{"df":1,"docs":{"14":{"tf":1.0}}}}}},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"=":{"\\"":{"0":{"df":0,"docs":{},"x":{"2":{"_":{"0":{"0":{"0":{"_":{"0":{"0":{"0":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"0":{"0":{"_":{"0":{"0":{"0":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{},"l":{"df":0,"docs":{},"i":{"d":{"df":1,"docs":{"15":{"tf":1.0}}},"df":0,"docs":{}},"u":{"df":8,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"20":{"tf":2.0},"24":{"tf":1.0},"28":{"tf":1.0},"38":{"tf":1.0},"53":{"tf":1.4142135623730951},"55":{"tf":1.0}}}},"r":{"!":{"(":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":0,"docs":{},"i":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"_":{"a":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"b":{"_":{"df":0,"docs":{},"v":{"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}}},"df":0,"docs":{}},"df":2,"docs":{"53":{"tf":1.0},"54":{"tf":1.0}},"i":{"a":{"b":{"df":0,"docs":{},"l":{"df":2,"docs":{"3":{"tf":1.4142135623730951},"53":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"b":{"df":0,"docs":{},"o":{"df":0,"docs":{},"s":{"df":1,"docs":{"37":{"tf":1.0}}}}},"df":0,"docs":{},"s":{"a":{"df":1,"docs":{"52":{"tf":1.0}}},"df":0,"docs":{}}}},"i":{"a":{"df":3,"docs":{"15":{"tf":1.0},"34":{"tf":1.0},"38":{"tf":1.0}}},"c":{"df":0,"docs":{},"e":{"df":1,"docs":{"52":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"w":{"df":2,"docs":{"38":{"tf":1.0},"52":{"tf":1.0}}}},"r":{"df":0,"docs":{},"t":{"df":0,"docs":{},"u":{"a":{"df":0,"docs":{},"l":{"df":10,"docs":{"15":{"tf":1.4142135623730951},"23":{"tf":2.449489742783178},"25":{"tf":1.0},"26":{"tf":1.0},"33":{"tf":1.4142135623730951},"46":{"tf":1.0},"53":{"tf":1.4142135623730951},"54":{"tf":1.0},"55":{"tf":1.0},"6":{"tf":1.0}}}},"df":0,"docs":{}}}}},"s":{"c":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{"df":1,"docs":{"4":{"tf":2.449489742783178}}}},"df":0,"docs":{}}},"df":0,"docs":{},"p":{"a":{"c":{"df":0,"docs":{},"e":{"df":3,"docs":{"23":{"tf":2.23606797749979},"26":{"tf":1.4142135623730951},"27":{"tf":1.4142135623730951}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"w":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":3,"docs":{"19":{"tf":1.0},"20":{"tf":1.4142135623730951},"36":{"tf":1.0}}}},"n":{"df":0,"docs":{},"t":{"df":2,"docs":{"4":{"tf":1.0},"53":{"tf":1.0}}}},"t":{"c":{"df":0,"docs":{},"h":{"df":1,"docs":{"21":{"tf":1.0}}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"k":{"df":3,"docs":{"18":{"tf":1.4142135623730951},"31":{"tf":1.7320508075688772},"42":{"tf":1.4142135623730951}}}}},"df":0,"docs":{}}}}},"y":{"df":6,"docs":{"14":{"tf":1.0},"18":{"tf":2.0},"38":{"tf":1.0},"46":{"tf":1.0},"55":{"tf":1.0},"7":{"tf":1.0}}}},"df":0,"docs":{},"e":{"\'":{"df":0,"docs":{},"v":{"df":3,"docs":{"31":{"tf":1.0},"37":{"tf":1.0},"49":{"tf":1.0}}}},"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":1,"docs":{"15":{"tf":1.0}}}}},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"df":2,"docs":{"16":{"tf":1.0},"3":{"tf":1.0}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"16":{"tf":1.0}}}}}}},"o":{"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":7,"docs":{"12":{"tf":1.0},"13":{"tf":1.0},"18":{"tf":1.0},"28":{"tf":1.4142135623730951},"30":{"tf":1.0},"42":{"tf":1.0},"6":{"tf":1.0}}}}}},"i":{"d":{"df":0,"docs":{},"e":{"df":1,"docs":{"38":{"tf":1.0}},"r":{"df":1,"docs":{"52":{"tf":1.0}}}}},"df":0,"docs":{},"s":{"df":0,"docs":{},"e":{"df":1,"docs":{"20":{"tf":1.0}}},"h":{"df":1,"docs":{"18":{"tf":1.0}}}},"t":{"df":0,"docs":{},"h":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"s":{"df":0,"docs":{},"g":{"_":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}},"e":{"df":0,"docs":{},"s":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"g":{"df":1,"docs":{"51":{"tf":1.0}},"s":{"_":{"df":0,"docs":{},"m":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":1,"docs":{"51":{"tf":1.0}}}}}},"df":0,"docs":{}}}}}},"df":0,"docs":{}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":3,"docs":{"15":{"tf":1.0},"18":{"tf":1.0},"5":{"tf":1.0}}}},"o":{"df":0,"docs":{},"u":{"df":0,"docs":{},"t":{"df":2,"docs":{"42":{"tf":1.0},"55":{"tf":1.0}}}}}}}},"o":{"df":0,"docs":{},"n":{"\'":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}},"df":0,"docs":{}},"r":{"d":{"df":3,"docs":{"15":{"tf":1.0},"20":{"tf":1.4142135623730951},"38":{"tf":1.4142135623730951}}},"df":0,"docs":{},"k":{"df":9,"docs":{"1":{"tf":1.0},"18":{"tf":1.0},"2":{"tf":1.0},"27":{"tf":1.4142135623730951},"37":{"tf":1.0},"4":{"tf":1.0},"46":{"tf":1.0},"47":{"tf":1.0},"6":{"tf":1.0}},"f":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":0,"docs":{},"w":{"df":1,"docs":{"1":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":3,"docs":{"3":{"tf":2.0},"4":{"tf":1.7320508075688772},"5":{"tf":1.7320508075688772}},"e":{"df":0,"docs":{},"s":{"/":{"df":0,"docs":{},"m":{"df":0,"docs":{},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"/":{".":{"c":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"g":{"df":0,"docs":{},"o":{"/":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":0,"docs":{},"g":{".":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"df":0,"docs":{},"l":{"df":1,"docs":{"3":{"tf":1.0}}}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":1,"docs":{"48":{"tf":1.0}}}}}}},"i":{"df":0,"docs":{},"p":{"c":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}}},"s":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"r":{"df":1,"docs":{"53":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":1,"docs":{"3":{"tf":1.0}}}}}}}},"df":0,"docs":{}}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":20,"docs":{"15":{"tf":1.0},"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":2.0},"20":{"tf":1.0},"23":{"tf":1.0},"25":{"tf":1.4142135623730951},"26":{"tf":1.4142135623730951},"28":{"tf":1.7320508075688772},"29":{"tf":1.4142135623730951},"3":{"tf":1.4142135623730951},"31":{"tf":1.4142135623730951},"32":{"tf":1.0},"33":{"tf":1.0},"37":{"tf":1.7320508075688772},"38":{"tf":1.4142135623730951},"41":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0},"7":{"tf":1.0}}}}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"l":{"d":{"!":{"\\\\":{"df":0,"docs":{},"n":{"df":1,"docs":{"33":{"tf":1.0}}}},"df":0,"docs":{}},"/":{"df":0,"docs":{},"p":{"d":{"df":0,"docs":{},"s":{"/":{"df":0,"docs":{},"h":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"/":{"df":0,"docs":{},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"7":{":":{"2":{"2":{"df":1,"docs":{"48":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"s":{"df":0,"docs":{},"r":{"c":{"/":{"df":0,"docs":{},"m":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{".":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{":":{"1":{"7":{":":{"2":{"0":{"df":1,"docs":{"14":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"4":{"1":{"df":1,"docs":{"14":{"tf":1.0}}},"df":0,"docs":{}},"7":{":":{"1":{"7":{"df":1,"docs":{"7":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":0,"docs":{}}}},"df":0,"docs":{}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"df":12,"docs":{"10":{"tf":1.0},"11":{"tf":1.0},"12":{"tf":1.0},"13":{"tf":1.0},"14":{"tf":1.0},"33":{"tf":1.0},"48":{"tf":2.449489742783178},"49":{"tf":1.0},"50":{"tf":1.0},"7":{"tf":2.449489742783178},"8":{"tf":1.0},"9":{"tf":1.0}}},"df":0,"docs":{}},"s":{"df":1,"docs":{"42":{"tf":1.0}}}}},"r":{"a":{"df":0,"docs":{},"p":{"df":1,"docs":{"15":{"tf":1.0}},"p":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":3,"docs":{"15":{"tf":1.0},"51":{"tf":1.0},"55":{"tf":1.0}}}}}}},"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":0,"docs":{},"e":{"(":{"df":0,"docs":{},"|":{"df":1,"docs":{"14":{"tf":1.0}}}},"df":3,"docs":{"1":{"tf":1.0},"36":{"tf":1.4142135623730951},"6":{"tf":1.0}}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":4,"docs":{"24":{"tf":1.0},"48":{"tf":1.0},"51":{"tf":1.0},"53":{"tf":1.0}}}}}}}}},"x":{"df":1,"docs":{"7":{"tf":1.0}},"m":{"df":0,"docs":{},"l":{"df":1,"docs":{"7":{"tf":1.0}}}}},"y":{"df":0,"docs":{},"o":{"df":0,"docs":{},"u":{"\'":{"df":0,"docs":{},"r":{"df":1,"docs":{"37":{"tf":1.0}}}},"df":0,"docs":{}}}},"z":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"c":{"df":0,"docs":{},"o":{"df":0,"docs":{},"p":{"df":0,"docs":{},"i":{"df":1,"docs":{"52":{"tf":1.0}}},"y":{":":{":":{"df":0,"docs":{},"{":{"df":0,"docs":{},"f":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"m":{"b":{"df":0,"docs":{},"y":{"df":0,"docs":{},"t":{"df":1,"docs":{"54":{"tf":1.0}}}}},"df":0,"docs":{}}}}}}},"df":0,"docs":{}},"df":0,"docs":{}}}}},"df":2,"docs":{"18":{"tf":1.0},"20":{"tf":1.0}}}}}}}},"title":{"root":{"1":{"0":{".":{"a":{"df":1,"docs":{"52":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"1":{".":{"a":{"df":1,"docs":{"54":{"tf":1.0}}},"b":{"df":1,"docs":{"55":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"df":0,"docs":{}},"2":{".":{"a":{"df":1,"docs":{"8":{"tf":1.0}}},"b":{"df":1,"docs":{"9":{"tf":1.0}}},"c":{"df":1,"docs":{"10":{"tf":1.0}}},"d":{"df":1,"docs":{"11":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"12":{"tf":1.0}}},"f":{"df":1,"docs":{"13":{"tf":1.0}}},"g":{"df":1,"docs":{"14":{"tf":1.0}}}},"df":0,"docs":{}},"3":{".":{"a":{"df":1,"docs":{"16":{"tf":1.0}}},"b":{"df":1,"docs":{"17":{"tf":1.0}}},"c":{"df":1,"docs":{"18":{"tf":1.0}}},"d":{"df":1,"docs":{"19":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"20":{"tf":1.0}}},"f":{"df":1,"docs":{"21":{"tf":1.0}}},"g":{"df":1,"docs":{"22":{"tf":1.0}}}},"df":0,"docs":{}},"4":{".":{"a":{"df":1,"docs":{"24":{"tf":1.0}}},"b":{"df":1,"docs":{"25":{"tf":1.0}}},"c":{"df":1,"docs":{"26":{"tf":1.0}}},"d":{"df":1,"docs":{"27":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"5":{".":{"a":{"df":1,"docs":{"29":{"tf":1.0}}},"b":{"df":1,"docs":{"30":{"tf":1.0}}},"c":{"df":1,"docs":{"31":{"tf":1.0}}},"d":{"df":1,"docs":{"32":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"33":{"tf":1.0}}},"f":{"df":1,"docs":{"34":{"tf":1.0}}},"g":{"df":1,"docs":{"35":{"tf":1.0}}},"h":{"df":1,"docs":{"36":{"tf":1.0}}}},"df":0,"docs":{}},"6":{".":{"a":{"df":1,"docs":{"38":{"tf":1.0}}},"b":{"df":1,"docs":{"39":{"tf":1.0}}},"c":{"df":1,"docs":{"40":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}},"7":{".":{"a":{"df":1,"docs":{"42":{"tf":1.0}}},"b":{"df":1,"docs":{"43":{"tf":1.0}}},"c":{"df":1,"docs":{"44":{"tf":1.0}}},"d":{"df":1,"docs":{"45":{"tf":1.0}}},"df":0,"docs":{},"e":{"df":1,"docs":{"46":{"tf":1.0}}}},"df":0,"docs":{}},"a":{"d":{"d":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":0,"docs":{},"s":{"df":0,"docs":{},"s":{"df":1,"docs":{"23":{"tf":1.0}}}}}}},"df":0,"docs":{}},"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"c":{"df":1,"docs":{"15":{"tf":1.0}}},"df":0,"docs":{}}}}},"c":{"df":0,"docs":{},"h":{"a":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"df":2,"docs":{"41":{"tf":1.0},"46":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"o":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"a":{"df":0,"docs":{},"i":{"df":0,"docs":{},"n":{"df":1,"docs":{"4":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"d":{"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":1,"docs":{"4":{"tf":1.0}},"i":{"c":{"df":1,"docs":{"28":{"tf":1.0}}},"df":0,"docs":{}}}},"o":{"c":{"df":0,"docs":{},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"2":{"tf":1.0}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"v":{"df":0,"docs":{},"e":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":1,"docs":{"49":{"tf":1.0}}}}}},"x":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"c":{"df":0,"docs":{},"i":{"df":0,"docs":{},"s":{"df":20,"docs":{"10":{"tf":1.0},"11":{"tf":1.0},"12":{"tf":1.0},"13":{"tf":1.0},"19":{"tf":1.0},"20":{"tf":1.0},"21":{"tf":1.0},"22":{"tf":1.0},"24":{"tf":1.0},"27":{"tf":1.0},"30":{"tf":1.0},"33":{"tf":1.0},"34":{"tf":1.0},"35":{"tf":1.0},"36":{"tf":1.0},"39":{"tf":1.0},"40":{"tf":1.0},"52":{"tf":1.0},"8":{"tf":1.0},"9":{"tf":1.0}}}}},"df":0,"docs":{}}}}},"h":{"a":{"df":0,"docs":{},"n":{"d":{"df":0,"docs":{},"l":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":1,"docs":{"49":{"tf":1.0}}}}}},"df":0,"docs":{}}},"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":0,"docs":{},"l":{"df":0,"docs":{},"o":{"df":2,"docs":{"48":{"tf":1.0},"7":{"tf":1.0}}}}}}},"i":{"df":0,"docs":{},"p":{"c":{"df":1,"docs":{"51":{"tf":1.0}}},"df":0,"docs":{}}},"k":{"df":0,"docs":{},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"n":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"df":1,"docs":{"15":{"tf":1.0}}}}}}}},"l":{"a":{"df":0,"docs":{},"n":{"df":0,"docs":{},"g":{"df":0,"docs":{},"u":{"a":{"df":0,"docs":{},"g":{"df":1,"docs":{"50":{"tf":1.0}}}},"df":0,"docs":{}}}}},"df":0,"docs":{}},"m":{"df":0,"docs":{},"e":{"df":0,"docs":{},"m":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"53":{"tf":1.0}}}}}}},"i":{"c":{"df":0,"docs":{},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"k":{"df":0,"docs":{},"i":{"df":0,"docs":{},"t":{"df":1,"docs":{"47":{"tf":1.0}}}}}}}},"df":0,"docs":{}},"o":{"d":{"df":0,"docs":{},"i":{"df":0,"docs":{},"f":{"df":0,"docs":{},"i":{"df":1,"docs":{"23":{"tf":1.0}}}}}},"df":0,"docs":{}}},"o":{"b":{"df":0,"docs":{},"j":{"df":0,"docs":{},"e":{"c":{"df":0,"docs":{},"t":{"df":1,"docs":{"15":{"tf":1.0}}}},"df":0,"docs":{}}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"o":{"df":0,"docs":{},"o":{"df":0,"docs":{},"t":{"df":1,"docs":{"6":{"tf":1.0}}}}},"u":{"df":0,"docs":{},"n":{"df":0,"docs":{},"t":{"df":0,"docs":{},"i":{"df":0,"docs":{},"m":{"df":1,"docs":{"50":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"t":{"d":{"df":0,"docs":{},"o":{"c":{"df":1,"docs":{"5":{"tf":1.0}}},"df":0,"docs":{}}},"df":1,"docs":{"0":{"tf":1.0}}}}}},"s":{"df":0,"docs":{},"e":{"df":0,"docs":{},"l":{"4":{"df":2,"docs":{"0":{"tf":1.0},"47":{"tf":1.0}}},"df":0,"docs":{}},"r":{"df":0,"docs":{},"i":{"a":{"df":0,"docs":{},"l":{"df":1,"docs":{"28":{"tf":1.0}}}},"df":0,"docs":{}}},"t":{"df":0,"docs":{},"u":{"df":0,"docs":{},"p":{"df":1,"docs":{"1":{"tf":1.0}}}}}},"h":{"a":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"df":1,"docs":{"53":{"tf":1.0}}}}},"df":0,"docs":{}},"p":{"a":{"c":{"df":0,"docs":{},"e":{"df":1,"docs":{"23":{"tf":1.0}}}},"df":0,"docs":{},"w":{"df":0,"docs":{},"n":{"df":2,"docs":{"37":{"tf":1.0},"41":{"tf":1.0}}}}},"df":0,"docs":{}},"t":{"df":0,"docs":{},"e":{"df":0,"docs":{},"p":{"df":37,"docs":{"10":{"tf":1.0},"11":{"tf":1.0},"12":{"tf":1.0},"13":{"tf":1.0},"14":{"tf":1.0},"16":{"tf":1.0},"17":{"tf":1.0},"18":{"tf":1.0},"19":{"tf":1.0},"20":{"tf":1.0},"21":{"tf":1.0},"22":{"tf":1.0},"24":{"tf":1.0},"25":{"tf":1.0},"26":{"tf":1.0},"27":{"tf":1.0},"29":{"tf":1.0},"30":{"tf":1.0},"31":{"tf":1.0},"32":{"tf":1.0},"33":{"tf":1.0},"34":{"tf":1.0},"35":{"tf":1.0},"36":{"tf":1.0},"38":{"tf":1.0},"39":{"tf":1.0},"40":{"tf":1.0},"42":{"tf":1.0},"43":{"tf":1.0},"44":{"tf":1.0},"45":{"tf":1.0},"46":{"tf":1.0},"52":{"tf":1.0},"54":{"tf":1.0},"55":{"tf":1.0},"8":{"tf":1.0},"9":{"tf":1.0}}}}}},"t":{"a":{"df":0,"docs":{},"s":{"df":0,"docs":{},"k":{"df":2,"docs":{"41":{"tf":1.0},"6":{"tf":1.0}}}}},"df":0,"docs":{},"h":{"df":0,"docs":{},"r":{"df":0,"docs":{},"e":{"a":{"d":{"df":1,"docs":{"37":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"u":{"df":0,"docs":{},"t":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"i":{"df":1,"docs":{"0":{"tf":1.0}}}}}}},"w":{"df":0,"docs":{},"o":{"df":1,"docs":{"3":{"tf":1.0}}}}},"u":{"df":0,"docs":{},"s":{"df":2,"docs":{"0":{"tf":1.0},"28":{"tf":1.0}},"e":{"df":0,"docs":{},"r":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":1,"docs":{"0":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}}}}},"v":{"df":0,"docs":{},"s":{"c":{"df":0,"docs":{},"o":{"d":{"df":0,"docs":{},"e":{"df":1,"docs":{"4":{"tf":1.0}}}},"df":0,"docs":{}}},"df":0,"docs":{}}},"w":{"df":0,"docs":{},"o":{"df":0,"docs":{},"r":{"df":0,"docs":{},"k":{"df":0,"docs":{},"s":{"df":0,"docs":{},"p":{"a":{"c":{"df":1,"docs":{"3":{"tf":1.0}}},"df":0,"docs":{}},"df":0,"docs":{}}}},"l":{"d":{"df":2,"docs":{"48":{"tf":1.0},"7":{"tf":1.0}}},"df":0,"docs":{}}}}}}}},"lang":"English","pipeline":["trimmer","stopWordFilter","stemmer"],"ref":"id","version":"0.9.5"},"results_options":{"limit_results":30,"teaser_word_count":30},"search_options":{"bool":"OR","expand":true,"fields":{"body":{"boost":1},"breadcrumbs":{"boost":1},"title":{"boost":2}}}}'); \ No newline at end of file diff --git a/projects/rust/tutorial/setup.html b/projects/rust/tutorial/setup.html new file mode 100644 index 00000000000..c92358a8c8d --- /dev/null +++ b/projects/rust/tutorial/setup.html @@ -0,0 +1,290 @@ + + + + + + Setup - Using Rust in seL4 Userspace + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+

Press S or / to search in the book

+

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+ +

Setup

+

This tutorial is presented as a linear series of patches to https://github.com/seL4/seL4-rust-tutorial-code, starting at commit 8ca0e1939dc1, and ending with commit 5253edc1ed12. +Each patch, or step, as we shall call them, is an instructive modification to a code example. +You are encouraged (but by no means required) to attempt those marked as exercises in this text on your own. +Note that while most step patches include tests, the reader is not expected to write tests for exercises themselves.

+

Clone the repository and checkout the starting commit:

+
git clone https://github.com/seL4/seL4-rust-tutorial-code
+cd seL4-rust-tutorial-code
+git checkout 8ca0e1939dc1
+
+

Observe the steps ahead:

+
git log 8ca0e1939dc1..5253edc1ed12
+
+

Each step header contains two icons. +Clicking the clipboard copies the commit hash corresponding to the step to the clipboard. +The GitHub icon is a link to the commit on GitHub.

+

Use any Git workflow that works for you. +For example, you could cherry-pick the steps that are not marked as exercises after examining and understanding them, and then attempt the exercises on your own, using those step commits as hints when necessary.

+

Docker

+

We will work inside of a Docker container built with docker/Dockerfile. +This Dockerfile installs some build-time dependencies, and then builds seL4, seL4 Microkit, and some additional programs and tools.

+

Build the image:

+
make -C docker build
+
+

Run a container in the background:

+
make -C docker run
+
+

Start a shell inside the container:

+
make -C docker exec
+
+

The rest of this text assumes that you are in a shell inside the container.

+

Two Workspaces

+

To simplify our Cargo invocations, this repository's Rust code has been divided between two distinct workspaces: workspaces/root-task and workspaces/microkit. +Both are subject to the top-level .cargo/config.toml, whereas workspaces/root-task/.cargo/config.toml and workspaces/microkit/.cargo/config.toml each apply to only one. +These workspace-specific config.toml files demonstrate all that is required to configure the crates in the rust-sel4 project:

+ +

VSCode + Dev Containers

+

If you want help from rust-analyzer, the Rust Language Server, you can use VSCode with the Dev Containers extension. +This will enable you to run VSCode inside of the container you just built, which contains the seL4 build artifacts that rust-analyzer will require to analyzer your code.

+

This repository provides a separate Dev Container configuration for each workspace:

+ +

To work in a particular workspace, open this repository in VSCode, run > Dev Containers: Reopen in Container, and select the corresponding configuration. +You should now be able to use the rust-analyzer VSCode extension normally for the code in the selected workspace.

+

Rustdoc

+

Rustdoc for the rust-sel4 project is hosted here:

+

https://sel4.github.io/rust-sel4/

+

However, for the sake of consistency, rustdoc for the particular configurations studied in this text are hosted here too. +There is one set of rustdoc for each of the two workspace configurations mentioned in Two Workspaces. +Rustdoc does not generate an index page, but you can navigate across crates within a workspace configuration using the sidebar present on top-level rustdoc page for any module.

+ + +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + +
+ + diff --git a/projects/rust/tutorial/toc.html b/projects/rust/tutorial/toc.html new file mode 100644 index 00000000000..7c417bd8be1 --- /dev/null +++ b/projects/rust/tutorial/toc.html @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + +
  1. Introduction
  2. Setup
  4. Part I: The Root Task
  5. Overview
  6. Hello, World!
  7. Allocating Kernel Objects
  8. Modifying the Address Space
  9. Using a Serial Device
  10. Spawning a Thread
  11. Spawning a Task (Challenge)
  13. Part II: Microkit
  14. Overview
  15. Hello, World!
  16. IPC
  17. Shared Memory
+ + diff --git a/projects/rust/tutorial/toc.js b/projects/rust/tutorial/toc.js new file mode 100644 index 00000000000..abd87abf9e1 --- /dev/null +++ b/projects/rust/tutorial/toc.js @@ -0,0 +1,70 @@ +// Populate the sidebar +// +// This is a script, and not included directly in the page, to control the total size of the book. +// The TOC contains an entry for each page, so if each page includes a copy of the TOC, +// the total size of the page becomes O(n**2). +class MDBookSidebarScrollbox extends HTMLElement { + constructor() { + super(); + } + connectedCallback() { + this.innerHTML = '
  1. Introduction
  2. Setup
  4. Part I: The Root Task
  5. Overview
  6. Hello, World!
  7. Allocating Kernel Objects
  8. Modifying the Address Space
  9. Using a Serial Device
  10. Spawning a Thread
  11. Spawning a Task (Challenge)
  13. Part II: Microkit
  14. Overview
  15. Hello, World!
  16. IPC
  17. Shared Memory
  18. Back to seL4 docsite
'; + // Set the current, active page, and reveal it if it's hidden + let current_page = document.location.href.toString().split("#")[0].split("?")[0]; + if (current_page.endsWith("/")) { + current_page += "index.html"; + } + var links = Array.prototype.slice.call(this.querySelectorAll("a")); + var l = links.length; + for (var i = 0; i < l; ++i) { + var link = links[i]; + var href = link.getAttribute("href"); + if (href && !href.startsWith("#") && !/^(?:[a-z+]+:)?\/\//.test(href)) { + link.href = path_to_root + href; + } + // The "index" page is supposed to alias the first chapter in the book. + if (link.href === current_page || (i === 0 && path_to_root === "" && current_page.endsWith("/index.html"))) { + link.classList.add("active"); + var parent = link.parentElement; + if (parent && parent.classList.contains("chapter-item")) { + parent.classList.add("expanded"); + } + while (parent) { + if (parent.tagName === "LI" && parent.previousElementSibling) { + if (parent.previousElementSibling.classList.contains("chapter-item")) { + parent.previousElementSibling.classList.add("expanded"); + } + } + parent = parent.parentElement; + } + } + } + // Track and set sidebar scroll position + this.addEventListener('click', function(e) { + if (e.target.tagName === 'A') { + sessionStorage.setItem('sidebar-scroll', this.scrollTop); + } + }, { passive: true }); + var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll'); + sessionStorage.removeItem('sidebar-scroll'); + if (sidebarScrollTop) { + // preserve sidebar scroll position when navigating via links within sidebar + this.scrollTop = sidebarScrollTop; + } else { + // scroll sidebar to current active section when navigating via "next/previous chapter" buttons + var activeSection = document.querySelector('#sidebar .active'); + if (activeSection) { + activeSection.scrollIntoView({ block: 'center' }); + } + } + // Toggle buttons + var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle'); + function toggleSection(ev) { + ev.currentTarget.parentElement.classList.toggle('expanded'); + } + Array.from(sidebarAnchorToggles).forEach(function (el) { + el.addEventListener('click', toggleSection); + }); + } +} +window.customElements.define("mdbook-sidebar-scrollbox", MDBookSidebarScrollbox); diff --git a/projects/rust/tutorial/toc.js.bak b/projects/rust/tutorial/toc.js.bak new file mode 100644 index 00000000000..065a426af2d --- /dev/null +++ b/projects/rust/tutorial/toc.js.bak @@ -0,0 +1,70 @@ +// Populate the sidebar +// +// This is a script, and not included directly in the page, to control the total size of the book. +// The TOC contains an entry for each page, so if each page includes a copy of the TOC, +// the total size of the page becomes O(n**2). +class MDBookSidebarScrollbox extends HTMLElement { + constructor() { + super(); + } + connectedCallback() { + this.innerHTML = '
  1. Introduction
  2. Setup
  4. Part I: The Root Task
  5. Overview
  6. Hello, World!
  7. Allocating Kernel Objects
  8. Modifying the Address Space
  9. Using a Serial Device
  10. Spawning a Thread
  11. Spawning a Task (Challenge)
  13. Part II: Microkit
  14. Overview
  15. Hello, World!
  16. IPC
  17. Shared Memory
'; + // Set the current, active page, and reveal it if it's hidden + let current_page = document.location.href.toString().split("#")[0].split("?")[0]; + if (current_page.endsWith("/")) { + current_page += "index.html"; + } + var links = Array.prototype.slice.call(this.querySelectorAll("a")); + var l = links.length; + for (var i = 0; i < l; ++i) { + var link = links[i]; + var href = link.getAttribute("href"); + if (href && !href.startsWith("#") && !/^(?:[a-z+]+:)?\/\//.test(href)) { + link.href = path_to_root + href; + } + // The "index" page is supposed to alias the first chapter in the book. + if (link.href === current_page || (i === 0 && path_to_root === "" && current_page.endsWith("/index.html"))) { + link.classList.add("active"); + var parent = link.parentElement; + if (parent && parent.classList.contains("chapter-item")) { + parent.classList.add("expanded"); + } + while (parent) { + if (parent.tagName === "LI" && parent.previousElementSibling) { + if (parent.previousElementSibling.classList.contains("chapter-item")) { + parent.previousElementSibling.classList.add("expanded"); + } + } + parent = parent.parentElement; + } + } + } + // Track and set sidebar scroll position + this.addEventListener('click', function(e) { + if (e.target.tagName === 'A') { + sessionStorage.setItem('sidebar-scroll', this.scrollTop); + } + }, { passive: true }); + var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll'); + sessionStorage.removeItem('sidebar-scroll'); + if (sidebarScrollTop) { + // preserve sidebar scroll position when navigating via links within sidebar + this.scrollTop = sidebarScrollTop; + } else { + // scroll sidebar to current active section when navigating via "next/previous chapter" buttons + var activeSection = document.querySelector('#sidebar .active'); + if (activeSection) { + activeSection.scrollIntoView({ block: 'center' }); + } + } + // Toggle buttons + var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle'); + function toggleSection(ev) { + ev.currentTarget.parentElement.classList.toggle('expanded'); + } + Array.from(sidebarAnchorToggles).forEach(function (el) { + el.addEventListener('click', toggleSection); + }); + } +} +window.customElements.define("mdbook-sidebar-scrollbox", MDBookSidebarScrollbox); diff --git a/projects/rust/tutorial/tomorrow-night.css b/projects/rust/tutorial/tomorrow-night.css new file mode 100644 index 00000000000..11752b8a8c7 --- /dev/null +++ b/projects/rust/tutorial/tomorrow-night.css @@ -0,0 +1,104 @@ +/* Tomorrow Night Theme */ +/* https://github.com/jmblog/color-themes-for-highlightjs */ +/* Original theme - https://github.com/chriskempson/tomorrow-theme */ +/* https://github.com/jmblog/color-themes-for-highlightjs */ + +/* Tomorrow Comment */ +.hljs-comment { + color: #969896; +} + +/* Tomorrow Red */ +.hljs-variable, +.hljs-attribute, +.hljs-attr, +.hljs-tag, +.hljs-regexp, +.ruby .hljs-constant, +.xml .hljs-tag .hljs-title, +.xml .hljs-pi, +.xml .hljs-doctype, +.html .hljs-doctype, +.css .hljs-id, +.css .hljs-class, +.css .hljs-pseudo { + color: #cc6666; +} + +/* Tomorrow Orange */ +.hljs-number, +.hljs-preprocessor, +.hljs-pragma, +.hljs-built_in, +.hljs-literal, +.hljs-params, +.hljs-constant { + color: #de935f; +} + +/* Tomorrow Yellow */ +.ruby .hljs-class .hljs-title, +.css .hljs-rule .hljs-attribute { + color: #f0c674; +} + +/* Tomorrow Green */ +.hljs-string, +.hljs-value, +.hljs-inheritance, +.hljs-header, +.hljs-name, +.ruby .hljs-symbol, +.xml .hljs-cdata { + color: #b5bd68; +} + +/* Tomorrow Aqua */ +.hljs-title, +.hljs-section, +.css .hljs-hexcolor { + color: #8abeb7; +} + +/* Tomorrow Blue */ +.hljs-function, +.python .hljs-decorator, +.python .hljs-title, +.ruby .hljs-function .hljs-title, +.ruby .hljs-title .hljs-keyword, +.perl .hljs-sub, +.javascript .hljs-title, +.coffeescript .hljs-title { + color: #81a2be; +} + +/* Tomorrow Purple */ +.hljs-keyword, +.javascript .hljs-function { + color: #b294bb; +} + +.hljs { + display: block; + overflow-x: auto; + background: #1d1f21; + color: #c5c8c6; +} + +.coffeescript .javascript, +.javascript .xml, +.tex .hljs-formula, +.xml .javascript, +.xml .vbscript, +.xml .css, +.xml .hljs-cdata { + opacity: 0.5; +} + +.hljs-addition { + color: #718c00; +} + +.hljs-deletion { + color: #c82829; +} diff --git a/projects/sel4-tutorials.html b/projects/sel4-tutorials.html new file mode 100644 index 00000000000..28b548c6290 --- /dev/null +++ b/projects/sel4-tutorials.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4-tutorials/benchmarking-guide.html b/projects/sel4-tutorials/benchmarking-guide.html new file mode 100644 index 00000000000..60a03335daf --- /dev/null +++ b/projects/sel4-tutorials/benchmarking-guide.html @@ -0,0 +1,896 @@ + + + + + + + Benchmarking Tools | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Benchmarking Tools

+ +

The sel4bench-manifest repository +collection provides a set of tools which can be used to analyse kernel and +workload performance. The use the kernel benchmarking extensions that can be +enabled via kernel build configuration option.

+ +

CPU Utilisation

+ +

Threads, including the idle thread, and the overall system time can be tracked +by enabling the “track CPU utilisation feature”. This feature can be enabled by +setting the CMake configuration option KernelConfiguration to +track_utilisation.

+ +

By enabling CPU utilisation tracking, the kernel is instrumented with variables +and functions to log the utilisation time for each thread in cycles.

+ +

This means TCB kernel objects gain additional fields and TCB size may increase +in benchmarking configurations in general and for track_utlisation in +particular. During each context switch, the kernel adds how long the current +thread has run before being switched, and resets the start time for the next +thread. The in-kernel buffer is not used for CPU utilisation tracking.

+ +

How to use

+ +

After enabling this feature, new system calls can be used to start, stop, and +retrieve data.

+ +

seL4_BenchmarkResetLog()

+ +

This system call resets global counters as well as idle thread counters since +the previous call to the same function, and (re)starts CPU utilisation tracking. +It does not reset counters for individual threads.

+ +

seL4_BenchmarkResetThreadUtilisation(seL4_CPtr thread_cptr)

+ +

Resets the utilisation counters for the requested thread. It is the responsibility +of the user to reset the thread’s counters using this system call before calling +seL4_BenchmarkResetLog(), especially if seL4_BenchmarkResetLog() is called +multiple times to track the same set of threads.

+ +

seL4_BenchmarkFinalizeLog()

+ +

Stops the CPU tracking feature but does not reset the counters. Performing this +system call without a previous seL4_BenchmarkResetLog() call has no effect.

+ +

seL4_BenchmarkGetThreadUtilisation(seL4_CPtr thread_cptr)

+ +

Gets the utilisation time of the thread that thread_cptr capability points to +between calls to seL4_BenchmarkResetLog() and seL4_BenchmarkFinalizeLog(). +The utilisation time is written to the first 64-bit word of IPC buffer of the +calling thread. The idle thread and overall CPU utilisation times are written to +the subsequent 64-bit words in the IPCBuffer.

+ +

Example code of using this feature:

+ +
#include <sel4/benchmark_utilisation_types.h>
+
+uint64_t *ipcbuffer = (uint64_t*) &(seL4_GetIPCBuffer()->msg[0]);
+
+seL4_BenchmarkResetThreadUtilisation(seL4_CapInitThreadTCB);
+
+seL4_BenchmarkResetLog();
+...
+seL4_BenchmarkFinalizeLog();
+
+seL4_BenchmarkGetThreadUtilisation(seL4_CapInitThreadTCB);
+printf("Init thread utilisation = %llun", ipcbuffer[BENCHMARK_TCB_UTILISATION]);
+printf("Idle thread utilisation = %llun", ipcbuffer[BENCHMARK_IDLE_UTILISATION]);
+printf("Overall utilisation = %llun", ipcbuffer[BENCHMARK_TOTAL_UTILISATION]);
+
+ +

In-kernel log buffer

+ +

An in-kernel log buffer can be provided by the user when the KernelBenchmarks +CMake config option is set to track_kernel_entries or tracepoints with the +system call seL4_BenchmarkSetLogBuffer. Users must provide a capability to a +large frame for the kernel to use as a log buffer. The frame will be mapped +write-through to avoid impacting the caches. The kernel only writes to the log +buffer and does not read from it during benchmarking. Once a benchmark is +complete, data can be read out at user level.

+ +

The trace-points and kernel-entry tracking features of the sel4bench suite use +the in-kernel log buffer.

+ +

Tracepoints

+ +

These allow the user to specify tracepoints in the kernel to track the time +between points.

+ +

How to use

+ +

Set the KernelBenchmarks CMake config option to tracepoints. Then set the +KernelMaxNumTracePoints CMake config option to a non-zero value.

+ +

Wrap the regions you wish to time with TRACE_POINT_START(i) and +TRACE_POINT_STOP(i) where i is an integer from 0 to less than the value of +“Maximum number of tracepoints”.

+ +

The number of cycles consumed between a TRACE_POINT_START and +TRACE_POINT_STOP will be stored in an in-kernel log. Entries of this +log consist of a key (the argument to TRACE_POINT_START and +TRACE_POINT_STOP) and a value (the number of cycles counted between +TRACE_POINT_START and TRACE_POINT_STOP).

+ +

Functionality for extracting and processing entries from this buffer is provided +in libsel4bench located in +seL4/seL4_libs.

+ +

An example of this feature in use can be found in the IRQ path benchmark +in sel4bench.

+ +

Tracepoint Overhead

+ +

Measuring Overhead

+ +

Using tracepoints adds a small amount of overhead to the kernel. To measure +this overhead, use a pair of nested tracepoints:

+ +
TRACE_POINT_START(0);
+TRACE_POINT_START(1);
+TRACE_POINT_STOP(1);
+TRACE_POINT_STOP(0);
+
+ +

The outer tracepoints will measure the time taken to start and stop the inner +tracepoints. The cycle count recorded by the outer tracepoints will be slightly +skewed, as starting and stopping itself (the outer tracepoints) takes some +number of cycles. To determine how many, we look to the inner tracepoints. Since +this pair is empty, it will record the number of cycles added to a result by the +tracepoint instrumentation. Thus, to compute the total overhead of starting and +stopping a tracepoint, subtract the values measured by the inner tracepoints +from those measured by the outer tracepoints.

+ +

Results

+ +

All results are in cycles. Results were obtained using the method described +above. The total overhead is the number of cycles added to execution per +tracepoint start/stop pair (inner pair result subtracted from outer pair +result). The effective overhead is the number of cycles added to a measurement +by the tracepoint instrumentation (inner pair result).

+ +
Total Overhead
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Machine# SamplesMinMaxMeanStd DevStd Dev %
Sabre74018181800%
Haswell2740532852550.3317.193%
+ +
+ +
Effective overhead
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Machine# SamplesMinMaxMeanStd DevStd Dev %
Sabre74044400
Haswell2740208212208.691.661%
+ +
+ +

Advanced Use

+ +

Conditional Logging

+ +

A log is stored when TRACE_POINT_STOP(i) is called, only if a corresponding +TRACE_POINT_START(i) was called since the last call to TRACE_POINT_STOP(i) +or system boot. This allows for counting cycles of a particular path through +some region of code. Here are some examples:

+ +

The cycles consumed by functions f and g are logged with the key 0, only +when the condition c is true:

+ +
TRACE_POINT_START(0);
+f();
+if (c) {
+    g();
+    TRACE_POINT_STOP(0);
+}
+
+ +

The cycles consumed by functions f and g are +logged with the key 1, only when the condition c is true:

+ +
if (c) {
+    f();
+    TRACE_POINT_START(1);
+}
+g();
+TRACE_POINT_STOP(1);
+
+ +

These two techniques can be combined to record cycle counts only when a +particular path between 2 points is followed. In the following example, cycles +consumed by functions f, g and h are logged, only when the condition c +is true. Cycle counts are stored with 2 keys (2 and 3) which can be combined +after extracting the data to user level.

+ +
TRACE_POINT_START(2);
+f();
+if (c) {
+    h();
+    TRACE_POINT_STOP(2);
+    TRACE_POINT_START(3);
+}
+g();
+TRACE_POINT_STOP(3);
+
+ +

Interleaving/Nesting

+ +

It’s possible to interleave tracepoints:

+ +
TRACE_POINT_START(0);
+...
+TRACE_POINT_START(1);
+...
+TRACE_POINT_STOP(0);
+...
+TRACE_POINT_STOP(1);
+
+ +

and to nest tracepoints:

+ +
TRACE_POINT_START(0);
+...
+TRACE_POINT_START(1);
+...
+TRACE_POINT_STOP(1);
+...
+TRACE_POINT_STOP(0);
+
+ +

When interleaving or nesting tracepoints, be sure to account for the overhead +that will be introduced.

+ +

Kernel entry tracking

+ +

Kernel entries can be tracked, registering info about interrupts, syscall, +timestamp, invocations and capability types. The number of kernel entries is +restricted by the log buffer size. The kernel provides a reserved area within +its address space to map the log buffer. It is the responsibility of the user to +allocate a user-level log buffer (currently can be only of seL4_LargePageBits +size) and pass it to the kernel to use before doing any operations that involve +the log buffer, otherwise an error will be triggered. To enable this feature, +set the KernelBenchmarks CMake config option to track_kernel_entries.

+ +

An example how to create a user-level log buffer (using the seL4 libraries) and +tell the kernel about it is as follows:

+ +
#ifdef CONFIG_BENCHMARK_TRACK_KERNEL_ENTRIES
+
+#include <sel4/benchmark_track_types.h>
+
+  /* Create large page to use for benchmarking and give to kernel */
+  void* log_buffer = vspace_new_pages(&env.vspace, seL4_AllRights, 1, seL4_LargePageBits);
+  if (log_buffer == NULL) {
+    ZF_LOGF("Could not map log_buffer page");
+  }
+  seL4_CPtr buffer_cap = vspace_get_cap(&env.vspace, log_buffer);
+  if (buffer_cap == NULL) {
+    ZF_LOGF("Could not get cap for log buffer");
+  }
+  int res_buf = seL4_BenchmarkSetLogBuffer(buffer_cap);
+  if (res_buf) {
+    ZF_LOGF("Could not set log buffer");
+  }
+
+#endif CONFIG_BENCHMARK_TRACK_KERNEL_ENTRIES
+
+ +

seL4_BenchmarkResetLog() can be used to reset the log buffer index and start +tracking. To stop tracking, call seL4_BenchmarkFinalizeLog() which returns the +log buffer index. Note that, if the buffer is full/saturated, it will return the +last entry index of the log buffer. Finally, the log buffer can be analysed to +extract desired info. For reference, there are utility functions to extract such +information in +sel4utils/benchmark_track.h.

+ +

Hints

+ +

If you want only entry or exit times instead of function call durations, modify +line +63 +of include/benchmark.h in function trace_point_stop in the kernel. This +might be useful if you wish to time hardware events. For example, should you +wish to time how long it takes for hardware to generate a fault to the kernel, +perhaps record the cycle counter before causing the fault in userspace, then +store the ksEntry as soon as you enter somewhere relevant in the kernel, and +then compare the difference of these two once you return to userspace.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4-tutorials/benchmarking-guide.md b/projects/sel4-tutorials/benchmarking-guide.md deleted file mode 100644 index 49b05c12fae..00000000000 --- a/projects/sel4-tutorials/benchmarking-guide.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -redirect_from: - - /BenchmarkingGuide -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Benchmarking Tools - -The [sel4bench-manifest](https://github.com/seL4/sel4bench-manifest) repository -collection provides a set of tools which can be used to analyse kernel and -workload performance. The use the kernel benchmarking extensions that can be -enabled via kernel build configuration option. - -## CPU Utilisation - -Threads, including the idle thread, and the overall system time can be tracked -by enabling the "track CPU utilisation feature". This feature can be enabled by -setting the CMake configuration option `KernelConfiguration` to -`track_utilisation`. - -By enabling CPU utilisation tracking, the kernel is instrumented with variables -and functions to log the utilisation time for each thread in cycles. - -This means TCB kernel objects gain additional fields and TCB size may increase -in benchmarking configurations in general and for `track_utlisation` in -particular. During each context switch, the kernel adds how long the current -thread has run before being switched, and resets the start time for the next -thread. The in-kernel buffer is not used for CPU utilisation tracking. - -### How to use - -After enabling this feature, new system calls can be used to start, stop, and -retrieve data. - -#### `seL4_BenchmarkResetLog()` - -This system call resets global counters as well as idle thread counters since -the previous call to the same function, and (re)starts CPU utilisation tracking. -It does not reset counters for individual threads. - -#### `seL4_BenchmarkResetThreadUtilisation(seL4_CPtr thread_cptr)` - -Resets the utilisation counters for the requested thread. It is the responsibility -of the user to reset the thread's counters using this system call before calling -`seL4_BenchmarkResetLog()`, especially if `seL4_BenchmarkResetLog()` is called -multiple times to track the same set of threads. - -#### `seL4_BenchmarkFinalizeLog()` - -Stops the CPU tracking feature but does not reset the counters. Performing this -system call without a previous `seL4_BenchmarkResetLog()` call has no effect. - -#### `seL4_BenchmarkGetThreadUtilisation(seL4_CPtr thread_cptr)` - -Gets the utilisation time of the thread that `thread_cptr` capability points to -between calls to `seL4_BenchmarkResetLog()` and `seL4_BenchmarkFinalizeLog()`. -The utilisation time is written to the first 64-bit word of IPC buffer of the -calling thread. The idle thread and overall CPU utilisation times are written to -the subsequent 64-bit words in the IPCBuffer. - -Example code of using this feature: - -```c -#include - -uint64_t *ipcbuffer = (uint64_t*) &(seL4_GetIPCBuffer()->msg[0]); - -seL4_BenchmarkResetThreadUtilisation(seL4_CapInitThreadTCB); - -seL4_BenchmarkResetLog(); -... -seL4_BenchmarkFinalizeLog(); - -seL4_BenchmarkGetThreadUtilisation(seL4_CapInitThreadTCB); -printf("Init thread utilisation = %llun", ipcbuffer[BENCHMARK_TCB_UTILISATION]); -printf("Idle thread utilisation = %llun", ipcbuffer[BENCHMARK_IDLE_UTILISATION]); -printf("Overall utilisation = %llun", ipcbuffer[BENCHMARK_TOTAL_UTILISATION]); -``` - -## In-kernel log buffer - -An in-kernel log buffer can be provided by the user when the `KernelBenchmarks` -CMake config option is set to `track_kernel_entries` or `tracepoints` with the -system call `seL4_BenchmarkSetLogBuffer`. Users must provide a capability to a -large frame for the kernel to use as a log buffer. The frame will be mapped -write-through to avoid impacting the caches. The kernel only writes to the log -buffer and does not read from it during benchmarking. Once a benchmark is -complete, data can be read out at user level. - -The trace-points and kernel-entry tracking features of the `sel4bench` suite use -the in-kernel log buffer. - -## Tracepoints - -These allow the user to specify tracepoints in the kernel to track the time -between points. - -### How to use - -Set the `KernelBenchmarks` CMake config option to `tracepoints`. Then set the -`KernelMaxNumTracePoints` CMake config option to a non-zero value. - -Wrap the regions you wish to time with `TRACE_POINT_START(i)` and -`TRACE_POINT_STOP(i)` where `i` is an integer from 0 to less than the value of -"Maximum number of tracepoints". - -The number of cycles consumed between a `TRACE_POINT_START` and -`TRACE_POINT_STOP` will be stored in an in-kernel log. Entries of this -log consist of a key (the argument to `TRACE_POINT_START` and -`TRACE_POINT_STOP`) and a value (the number of cycles counted between -`TRACE_POINT_START` and `TRACE_POINT_STOP`). - -Functionality for extracting and processing entries from this buffer is provided -in `libsel4bench` located in -[seL4/seL4_libs](https://github.com/seL4/seL4_libs). - -An example of this feature in use can be found in the IRQ path benchmark -in [sel4bench](https://github.com/seL4/sel4bench/blob/master/apps/irq/src/main.c). - -### Tracepoint Overhead - -#### Measuring Overhead - -Using tracepoints adds a small amount of overhead to the kernel. To measure -this overhead, use a pair of nested tracepoints: - -```c -TRACE_POINT_START(0); -TRACE_POINT_START(1); -TRACE_POINT_STOP(1); -TRACE_POINT_STOP(0); -``` - -The outer tracepoints will measure the time taken to start and stop the inner -tracepoints. The cycle count recorded by the outer tracepoints will be slightly -skewed, as starting and stopping itself (the outer tracepoints) takes some -number of cycles. To determine how many, we look to the inner tracepoints. Since -this pair is empty, it will record the number of cycles added to a result by the -tracepoint instrumentation. Thus, to compute the total overhead of starting and -stopping a tracepoint, subtract the values measured by the inner tracepoints -from those measured by the outer tracepoints. - -#### Results - -All results are in cycles. Results were obtained using the method described -above. The total overhead is the number of cycles added to execution per -tracepoint start/stop pair (inner pair result subtracted from outer pair -result). The effective overhead is the number of cycles added to a measurement -by the tracepoint instrumentation (inner pair result). - -##### **Total Overhead** - -
-|Machine |# Samples |Min|Max|Mean|Std Dev|Std Dev %| -|-|-|-|-|-|-|-|-| -|Sabre|740|18|18|18|0|0%| -|Haswell2|740|532|852|550.33|17.19|3%| - -
- -##### **Effective overhead** - -
-|Machine |# Samples |Min|Max|Mean|Std Dev|Std Dev %| -|-|-|-|-|-|-|-|-| -|Sabre|740|4|4|4|0|0 | -|Haswell2|740|208|212|208.69|1.66|1% | - -
- -### Advanced Use - -#### Conditional Logging - -A log is stored when `TRACE_POINT_STOP(i)` is called, only if a corresponding -`TRACE_POINT_START(i)` was called since the last call to `TRACE_POINT_STOP(i)` -or system boot. This allows for counting cycles of a particular path through -some region of code. Here are some examples: - -The cycles consumed by functions `f` and `g` are logged with the key 0, only -when the condition `c` is true: - -```c -TRACE_POINT_START(0); -f(); -if (c) { - g(); - TRACE_POINT_STOP(0); -} -``` - -The cycles consumed by functions `f` and `g` are -logged with the key 1, only when the condition `c` is true: - -```c -if (c) { - f(); - TRACE_POINT_START(1); -} -g(); -TRACE_POINT_STOP(1); -``` - -These two techniques can be combined to record cycle counts only when a -particular path between 2 points is followed. In the following example, cycles -consumed by functions `f`, `g` and `h` are logged, only when the condition `c` -is true. Cycle counts are stored with 2 keys (2 and 3) which can be combined -after extracting the data to user level. - -```c -TRACE_POINT_START(2); -f(); -if (c) { - h(); - TRACE_POINT_STOP(2); - TRACE_POINT_START(3); -} -g(); -TRACE_POINT_STOP(3); -``` - -#### Interleaving/Nesting - -It's possible to interleave tracepoints: - -```c -TRACE_POINT_START(0); -... -TRACE_POINT_START(1); -... -TRACE_POINT_STOP(0); -... -TRACE_POINT_STOP(1); -``` - -and to nest tracepoints: - -```c -TRACE_POINT_START(0); -... -TRACE_POINT_START(1); -... -TRACE_POINT_STOP(1); -... -TRACE_POINT_STOP(0); -``` - -When interleaving or nesting tracepoints, be sure to account for the overhead -that will be introduced. - -## Kernel entry tracking - -Kernel entries can be tracked, registering info about interrupts, syscall, -timestamp, invocations and capability types. The number of kernel entries is -restricted by the log buffer size. The kernel provides a reserved area within -its address space to map the log buffer. It is the responsibility of the user to -allocate a user-level log buffer (currently can be only of seL4_LargePageBits -size) and pass it to the kernel to use before doing any operations that involve -the log buffer, otherwise an error will be triggered. To enable this feature, -set the `KernelBenchmarks` CMake config option to `track_kernel_entries`. - -An example how to create a user-level log buffer (using the seL4 libraries) and -tell the kernel about it is as follows: - -```c -#ifdef CONFIG_BENCHMARK_TRACK_KERNEL_ENTRIES - -#include - - /* Create large page to use for benchmarking and give to kernel */ - void* log_buffer = vspace_new_pages(&env.vspace, seL4_AllRights, 1, seL4_LargePageBits); - if (log_buffer == NULL) { - ZF_LOGF("Could not map log_buffer page"); - } - seL4_CPtr buffer_cap = vspace_get_cap(&env.vspace, log_buffer); - if (buffer_cap == NULL) { - ZF_LOGF("Could not get cap for log buffer"); - } - int res_buf = seL4_BenchmarkSetLogBuffer(buffer_cap); - if (res_buf) { - ZF_LOGF("Could not set log buffer"); - } - -#endif CONFIG_BENCHMARK_TRACK_KERNEL_ENTRIES -``` - -`seL4_BenchmarkResetLog()` can be used to reset the log buffer index and start -tracking. To stop tracking, call `seL4_BenchmarkFinalizeLog()` which returns the -log buffer index. Note that, if the buffer is full/saturated, it will return the -last entry index of the log buffer. Finally, the log buffer can be analysed to -extract desired info. For reference, there are utility functions to extract such -information in -[sel4utils/benchmark_track.h](https://github.com/seL4/seL4_libs/blob/master/libsel4utils/include/sel4utils/benchmark_track.h). - -### Hints - -If you want only entry or exit times instead of function call durations, modify -[line -63](https://github.com/seL4/seL4/blob/b63043c41a5db1f64253ea98b104eab54c256c56/include/benchmark/benchmark.h#L63) -of `include/benchmark.h` in function `trace_point_stop` in the kernel. This -might be useful if you wish to time hardware events. For example, should you -wish to time how long it takes for hardware to generate a fault to the kernel, -perhaps record the cycle counter before causing the fault in userspace, then -store the `ksEntry` as soon as you enter somewhere relevant in the kernel, and -then compare the difference of these two once you return to userspace. diff --git a/projects/sel4-tutorials/debugging-guide.html b/projects/sel4-tutorials/debugging-guide.html new file mode 100644 index 00000000000..358ccb51c77 --- /dev/null +++ b/projects/sel4-tutorials/debugging-guide.html @@ -0,0 +1,822 @@ + + + + + + + Debugging guide | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Debugging guide

+ +

This guide is for debugging the seL4 kernel itself, for instance during +development of new features. See Debugging user +space for how to debug user-level code on top of +seL4.

+ +

Compiler Settings

+ +

Ensure that the build directory you are building in is not a release build. To +do so, check you build directory CMakeCache.txt file for the following lines:

+ +
    +
  • CMAKE_BUILD_TYPE:STRING=Debug
    • +
  • KernelDebugBuild:BOOL=ON
    • +
+ +

Debug builds enable helpful features for debugging including:

+ +
    +
  • printf + a serial driver,
    • +
  • -g is passed to the compiler,
    • +
  • compile- and run-time asserts,
    • +
  • the kernel will print out error messages when invocations fail.
    • +
+ +

QEMU

+ +

QEMU is a simulator that provides software emulation of +a hardware platform. It is useful for developing and debugging embedded software +when you do not have access to the target platform. Even if you do have the +target hardware, QEMU can shorten your edit-compile-debug cycle. Be aware that +it is not cycle-accurate and cannot emulate every device, so sometimes you have +no alternative than to debug on real hardware.

+ +

For the seL4 tutorials, a simulate script is always generated for use in the +build directory of a project. In most other projects, this script can be +generated by passing the flag -DSIMULATION=1 to the ../init-build.sh +invocation.

+ +
mkdir build_dir
+cd build_dir
+../init-build.sh -DSIMULATION=1
+./simulate
+
+ +

If the platform does not support QEMU, the script will output

+ +
    Unsupported platform or architecture for simulation
+
+ +

When simulating an seL4 system in QEMU, you should see output that is +directed to the (emulated) UART device on your terminal:

+ +
ELF-loader started on CPU: ARM Ltd. ARMv6 Part: 0xb36 r1p3
+  paddr=[82000000..8225001f]
+ELF-loading image 'kernel'
+  paddr=[80000000..80033fff]
+  vaddr=[f0000000..f0033fff]
+  virt_entry=f0000000
+ELF-loading image 'sel4test-driver'
+  paddr=[80034000..8036efff]
+  vaddr=[10000..34afff]
+  virt_entry=1c880
+Enabling MMU and paging
+Jumping to kernel-image entry point...
+
+Bootstrapping kernel
+Switching to a safer, bigger stack...
+seL4 Test
+=========
+...
+
+ +

To exit from QEMU, type the sequence Ctrl+”a”, then “x”. Note that you +can exit at any point; you do not need to wait for the system to finish +or reach some stable state. If you exit QEMU while a system is running, +it will simply be terminated.

+ +

QEMU has some powerful debugging features built in. You can type +Ctrl+”a”, then “c” to switch to the QEMU monitor. From here you can +inspect CPU or device state, read and write memory, and single-step +execution. More information about this functionality is available in the +QEMU documentation.

+ +

When debugging an seL4 project, the QEMU debugger is inherently limited. +It has no understanding of your source code, so it is difficult to +relate what you are seeing back to the C code you compiled. It is +possible to get a richer debugging environment by connecting GDB to +QEMU.

+ +

Using GDB with QEMU

+ +

GDB is a debugger commonly used +in C application development. Though not as seamless as debugging a +native Linux application, it is possible to use GDB to debug within +QEMU’s emulated environment.

+ +

Start QEMU with the extra options “-S” (pause execution on start) and +“-s” (start a GDB server on TCP port 1234):

+ +
./simulate --extra-qemu-args="-S -s"
+
+ +

In a separate terminal window, start your target platform’s version of +GDB. You should either pass a binary of the seL4 kernel if you intend on +debugging seL4 itself or the user-space application if you intend on +debugging an application on seL4.

+ +

In this example we’re going +to debug the seL4 kernel that has been built in debug mode:

+ +
${CROSS_COMPILER_PREFIX}gdb kernel/kernel.elf
+
+ +

Where CROSS_COMPILER_PREFIX is the prefix used for the toolchain for the +architecture you are debugging. For x86 this is blank, for other architectures +you can check the CMakeCache.txt file in the build directory for the variable +CROSS_COMPILER_PREFIX. In the following example, the prefix is +arm-none-eabi-:

+ +
CROSS_COMPILER_PREFIX:UNINITIALIZED=arm-none-eabi-
+
+ +

At the GDB prompt, enter “target remote :1234” to connect to the server +QEMU is hosting:

+ +
Reading symbols from kernel/kernel.elf...done.
+(gdb) target remote :1234
+Remote debugging using :1234
+0x82000000 in ?? ()
+(gdb)
+
+ +

Suppose we want to halt when kprintf is called. Enter break kprintf at +the GDB prompt:

+ +
(gdb) break kprintf
+Breakpoint 1 at 0xf0011248: file kernel/src/machine/io.c, line 269.
+
+ +

We can now start QEMU running and wait until we hit the breakpoint. To +do this, type “cont” at the GDB prompt:

+ +
(gdb) cont
+Continuing.
+
+Breakpoint 1, kprintf (format=0xf0428000 "") at kernel/src/machine/io.c:269
+269     {
+
+ +

Note that some output has appeared in the other terminal window running +QEMU as it has partially executed. It may be surprising to see that some +printing somehow happened without our breakpoint triggering. The reason +for this is that output we’re seeing is from the ELF loader that runs +prior to the kernel. GDB does not know the address of its print function +(as we only gave GDB the kernel’s symbol table) and it is not looking to +break on its address. The breakpoint we have just hit is the first time +the ‘‘kernel’’ tried to print. Similarly, the breakpoint we have +configured will have no effect on user-space calls to printf.

+ +

Now that we are stopped at a breakpoint, all the standard GDB operations +are possible (inspect registers or the stack, single-step, continue +until function exit, …). More information is available in the +GDB manual.

+ +

Be warned that if you are debugging the kernel’s early boot steps, +something that may not be immediately obvious is that debugging across a +context in which page mappings change (e.g. switching page directories +or turning the MMU on/off) will confuse GDB and you may find breakpoints +triggering unexpectedly or being missed.

+ +

The process we have described is similar for x86, though if you are on +an x86 or x86_64 host you can simply use your platform’s native GDB, +gdb.

+ +

User space debugging

+ +

The steps for debugging a user-space application on seL4 are identical to +the ones we have just seen, except that we pass GDB a symbol table for +user-space rather than the kernel. For example, using the same sel4test +environment we start QEMU in the same way but start GDB with the sel4test +binary:

+ +
${CROSS_COMPILER_PREFIX}gdb projects/sel4test/apps/sel4test-driver/sel4test-driver
+
+ +

After connecting to QEMU, we can instruct GDB to break on the user space +printf function:

+ +
Reading symbols from projects/sel4test/apps/sel4test-driver/sel4test-driver.bin...done.
+(gdb) target remote :1234
+Remote debugging using :1234 0x82000000 in ?? ()
+(gdb) break printf
+Breakpoint 1 at 0x30870: file libs/libmuslc/src/stdio/printf.c, line 9.
+(gdb)
+
+ +

Note that GDB has correctly identified the printf function in Musl C. We +now continue as before:

+ +
(gdb) cont
+Continuing.
+
+Breakpoint 1, printf (fmt=0x363e8 "%s") at libs/libmuslc/src/stdio/printf.c:9
+9               ret = vfprintf(stdout, fmt, ap);
+(gdb)
+
+ +

If you examine the terminal window running QEMU at this point, you will +note that we see an extra bit of output from the kernel. The kernel’s +print functionality is unaffected, but GDB has stopped execution the +first time user space called printf.

+ +

From here, the experience is essentially identical to debugging the +kernel. One small complication to be aware of is that debugging across a +context switch may be confusing. If you are single-stepping in GDB and +find execution suddenly diverted to an address where code is unknown, +check the address itself. It is usually easy to identify from the +address alone when execution is in kernel code or the exception vector +table. Unfortunately there is no easy way to continue until you’re back +in user space, particularly if the kernel schedules a different thread +than the one you were debugging. Depending on the scenario you are +debugging, it may be simpler to modify your system setup to ensure only +one thread is running.

+ +

Objdump

+ +

The objdump tool can be used to disassemble an ELF file, be it a kernel or an +application. This can be used to lookup the instruction where a fault occurred. +Make sure -g is passed to the compiler so that debug information is included +in the image.

+ +

Like gdb, the appropriate objdump from the toolchain must be called by +using CROSS_COMPILER_PREFIX.

+ +

For ARM, supposing that arm-none-eabi- is used as the +cross-compiler prefix.

+ +
arm-none-eabi-objdump -D binary_file_name > dump.s
+
+ +

For x86, on an x86 host:

+ +
objdump -D binary_file_name > dump.s
+
+ +

The file dump.s has the human-readable assembly instructions.

+ +

If you have symbols and want (C) source information in your disassembly +(and who doesn’t!) then use the -S flag. for example:

+ +
${CROSS_COMPILER_PREFIX}objdump -DS binary_file_name
+
+ +

Hardware debugging

+ +

For some platforms, seL4 supports hardware debugging. +See Hardware debugging of user-space threads.

+ +

In kernel debugging

+ +

seL4 does not currently have a kernel debugger. As a result, most of our +debugging is done with:

+ +
    +
  • objdump as described above,
    • +
  • printf,
    • +
  • __builtin_return_address (to figure out stack traces).
    • +
+ +

In the kernel, we provide debug_printKernelEntryReason found in +debug.h +which can be used at any point in the kernel to output the current +operation that the kernel is doing.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4-tutorials/debugging-guide.md b/projects/sel4-tutorials/debugging-guide.md deleted file mode 100644 index 874242334a4..00000000000 --- a/projects/sel4-tutorials/debugging-guide.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -redirect_from: - - /DebuggingGuide -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Debugging guide - -This guide is for debugging the seL4 kernel itself, for instance during -development of new features. See [Debugging user -space](debugging-userspace.html) for how to debug user-level code on top of -seL4. - -## Compiler Settings - -Ensure that the build directory you are building in is not a release build. To -do so, check you build directory `CMakeCache.txt` file for the following lines: - -- `CMAKE_BUILD_TYPE:STRING=Debug` -- `KernelDebugBuild:BOOL=ON` - -Debug builds enable helpful features for debugging including: - -- `printf` + a serial driver, -- `-g` is passed to the compiler, -- compile- and run-time asserts, -- the kernel will print out error messages when invocations fail. - -## QEMU - -[QEMU](http://www.qemu.org/) is a simulator that provides software emulation of -a hardware platform. It is useful for developing and debugging embedded software -when you do not have access to the target platform. Even if you do have the -target hardware, QEMU can shorten your edit-compile-debug cycle. Be aware that -it is not cycle-accurate and cannot emulate every device, so sometimes you have -no alternative than to debug on real hardware. - -For the seL4 tutorials, a `simulate` script is always generated for use in the -build directory of a project. In most other projects, this script can be -generated by passing the flag `-DSIMULATION=1` to the `../init-build.sh` -invocation. - -```bash -mkdir build_dir -cd build_dir -../init-build.sh -DSIMULATION=1 -./simulate -``` - -If the platform does not support QEMU, the script will output - -```bash - Unsupported platform or architecture for simulation -``` - -When simulating an seL4 system in QEMU, you should see output that is -directed to the (emulated) UART device on your terminal: - -```log -ELF-loader started on CPU: ARM Ltd. ARMv6 Part: 0xb36 r1p3 - paddr=[82000000..8225001f] -ELF-loading image 'kernel' - paddr=[80000000..80033fff] - vaddr=[f0000000..f0033fff] - virt_entry=f0000000 -ELF-loading image 'sel4test-driver' - paddr=[80034000..8036efff] - vaddr=[10000..34afff] - virt_entry=1c880 -Enabling MMU and paging -Jumping to kernel-image entry point... - -Bootstrapping kernel -Switching to a safer, bigger stack... -seL4 Test -========= -... -``` - -To exit from QEMU, type the sequence Ctrl+"a", then "x". Note that you -can exit at any point; you do not need to wait for the system to finish -or reach some stable state. If you exit QEMU while a system is running, -it will simply be terminated. - -QEMU has some powerful debugging features built in. You can type -Ctrl+"a", then "c" to switch to the QEMU monitor. From here you can -inspect CPU or device state, read and write memory, and single-step -execution. More information about this functionality is available in the -[QEMU documentation](https://qemu-project.gitlab.io/qemu/system/monitor.html). - -When debugging an seL4 project, the QEMU debugger is inherently limited. -It has no understanding of your source code, so it is difficult to -relate what you are seeing back to the C code you compiled. It is -possible to get a richer debugging environment by connecting GDB to -QEMU. - -### Using GDB with QEMU - -[GDB](https://www.gnu.org/s/gdb/) is a debugger commonly used -in C application development. Though not as seamless as debugging a -native Linux application, it is possible to use GDB to debug within -QEMU's emulated environment. - -Start QEMU with the extra options "-S" (pause execution on start) and -"-s" (start a GDB server on TCP port 1234): - -```bash -./simulate --extra-qemu-args="-S -s" -``` - -In a separate terminal window, start your target platform's version of -GDB. You should either pass a binary of the seL4 kernel if you intend on -debugging seL4 itself or the user-space application if you intend on -debugging an application on seL4. - -In this example we're going -to debug the seL4 kernel that has been built in debug mode: - -```bash -${CROSS_COMPILER_PREFIX}gdb kernel/kernel.elf -``` - -Where `CROSS_COMPILER_PREFIX` is the prefix used for the toolchain for the -architecture you are debugging. For x86 this is blank, for other architectures -you can check the `CMakeCache.txt` file in the build directory for the variable -`CROSS_COMPILER_PREFIX`. In the following example, the prefix is -`arm-none-eabi-`: - -```bash -CROSS_COMPILER_PREFIX:UNINITIALIZED=arm-none-eabi- -``` - -At the GDB prompt, enter "target remote :1234" to connect to the server -QEMU is hosting: - -```gdb -Reading symbols from kernel/kernel.elf...done. -(gdb) target remote :1234 -Remote debugging using :1234 -0x82000000 in ?? () -(gdb) -``` - -Suppose we want to halt when `kprintf` is called. Enter `break kprintf` at -the GDB prompt: - -```gdb -(gdb) break kprintf -Breakpoint 1 at 0xf0011248: file kernel/src/machine/io.c, line 269. -``` - -We can now start QEMU running and wait until we hit the breakpoint. To -do this, type "cont" at the GDB prompt: - -```gdb -(gdb) cont -Continuing. - -Breakpoint 1, kprintf (format=0xf0428000 "") at kernel/src/machine/io.c:269 -269 { -``` - -Note that some output has appeared in the other terminal window running -QEMU as it has partially executed. It may be surprising to see that some -printing somehow happened without our breakpoint triggering. The reason -for this is that output we're seeing is from the ELF loader that runs -prior to the kernel. GDB does not know the address of its print function -(as we only gave GDB the kernel's symbol table) and it is not looking to -break on its address. The breakpoint we have just hit is the first time -the ''kernel'' tried to print. Similarly, the breakpoint we have -configured will have no effect on user-space calls to `printf`. - -Now that we are stopped at a breakpoint, all the standard GDB operations -are possible (inspect registers or the stack, single-step, continue -until function exit, ...). More information is available in the -[GDB manual](http://www.gnu.org/software/gdb/documentation/). - -Be warned that if you are debugging the kernel's early boot steps, -something that may not be immediately obvious is that debugging across a -context in which page mappings change (e.g. switching page directories -or turning the MMU on/off) will confuse GDB and you may find breakpoints -triggering unexpectedly or being missed. - -The process we have described is similar for x86, though if you are on -an x86 or x86_64 host you can simply use your platform's native GDB, -gdb. - -#### User space debugging - -The steps for debugging a user-space application on seL4 are identical to -the ones we have just seen, except that we pass GDB a symbol table for -user-space rather than the kernel. For example, using the same `sel4test` -environment we start QEMU in the same way but start GDB with the `sel4test` -binary: - -```bash -${CROSS_COMPILER_PREFIX}gdb projects/sel4test/apps/sel4test-driver/sel4test-driver -``` - -After connecting to QEMU, we can instruct GDB to break on the user space -`printf` function: - -```gdb -Reading symbols from projects/sel4test/apps/sel4test-driver/sel4test-driver.bin...done. -(gdb) target remote :1234 -Remote debugging using :1234 0x82000000 in ?? () -(gdb) break printf -Breakpoint 1 at 0x30870: file libs/libmuslc/src/stdio/printf.c, line 9. -(gdb) -``` - -Note that GDB has correctly identified the printf function in Musl C. We -now continue as before: - -```gdb -(gdb) cont -Continuing. - -Breakpoint 1, printf (fmt=0x363e8 "%s") at libs/libmuslc/src/stdio/printf.c:9 -9 ret = vfprintf(stdout, fmt, ap); -(gdb) -``` - -If you examine the terminal window running QEMU at this point, you will -note that we see an extra bit of output from the kernel. The kernel's -print functionality is unaffected, but GDB has stopped execution the -first time user space called `printf`. - -From here, the experience is essentially identical to debugging the -kernel. One small complication to be aware of is that debugging across a -context switch may be confusing. If you are single-stepping in GDB and -find execution suddenly diverted to an address where code is unknown, -check the address itself. It is usually easy to identify from the -address alone when execution is in kernel code or the exception vector -table. Unfortunately there is no easy way to continue until you're back -in user space, particularly if the kernel schedules a different thread -than the one you were debugging. Depending on the scenario you are -debugging, it may be simpler to modify your system setup to ensure only -one thread is running. - -## Objdump - -The `objdump` tool can be used to disassemble an ELF file, be it a kernel or an -application. This can be used to lookup the instruction where a fault occurred. -Make sure `-g` is passed to the compiler so that debug information is included -in the image. - -Like gdb, the appropriate `objdump` from the toolchain must be called by -using `CROSS_COMPILER_PREFIX`. - -For ARM, supposing that **arm-none-eabi-** is used as the -cross-compiler prefix. - -```bash -arm-none-eabi-objdump -D binary_file_name > dump.s -``` - -For x86, on an x86 host: - -```bash -objdump -D binary_file_name > dump.s -``` - -The file `dump.s` has the human-readable assembly instructions. - -If you have symbols and want (C) source information in your disassembly -(and who doesn't!) then use the -S flag. for example: - -```bash -${CROSS_COMPILER_PREFIX}objdump -DS binary_file_name -``` - -## Hardware debugging - -For some platforms, seL4 supports hardware debugging. -See [Hardware debugging of user-space threads](debugging-userspace.html). - -## In kernel debugging - -seL4 does not currently have a kernel debugger. As a result, most of our -debugging is done with: - -- `objdump` as described above, -- `printf`, -- `__builtin_return_address` (to figure out stack traces). - -In the kernel, we provide `debug_printKernelEntryReason` found in -[debug.h](https://github.com/seL4/seL4/blob/master/include/api/debug.h) -which can be used at any point in the kernel to output the current -operation that the kernel is doing. diff --git a/projects/sel4-tutorials/debugging-userspace.html b/projects/sel4-tutorials/debugging-userspace.html new file mode 100644 index 00000000000..605f7e87b93 --- /dev/null +++ b/projects/sel4-tutorials/debugging-userspace.html @@ -0,0 +1,628 @@ + + + + + + + Hardware debugging of user-space threads | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Hardware debugging of user-space threads

+ +

This guide is for debugging user-level code on top of seL4. See the kernel +debugging guide for how to debug the kernel itself.

+ +

Overview

+ +

The seL4 microkernel leverages the hardware debugging capabilities of modern +processors, and exports hardware breakpoint, watchpoint, and single-stepping to +user threads via conditionally compiled-in APIs. These kernel-level APIs can be +used as the backend for implementing a full-featured debugger, or porting an +existing one such as the GNU Debugger.

+ +

Enabling this feature

+ +

You can enable and disable the hardware debugging API by going through the +kernel’s configuration system by passing -DHardwareDebugAPI=1.

+ +

Not all platforms support this feature for two main reasons:

+ +
    +
  • The feature is gated behind certain hardware signals, such as #DBGEN, being +active. If the hardware isn’t asserting these signals, the kernel will be +unable to use them.
    • +
  • Your processor supports only the “Baseline” set of Coprocessor 14 registers, +and doesn’t reliably expose the debug features through the debug coprocessor.
    • +
+ +
+
+ + Caution +
+
+ +

If you compile the kernel with support for the debug API, and your ARM platform +doesn’t support it, your kernel will abort at boot.

+ +
+
+ +

Summary of the invocations

+ +

The invocations are documented in detail in the seL4 manual. This article will +cover how to practically call them and use them in a prospective debugger.

+ +

To view a current version of the seL4 manuals, please download the kernel source +code and then cd manual and execute make.

+ +

Additionally, there is available source code that demonstrates how the +invocations can be used practically: the seL4-Test repository holds code tests +the debug APIs, and shows how to use them to set breakpoints, watchpoints and +single-stepping, on both x86 and ARM:

+ + + +

The invocations take capabilities to TCBs, and perform operations on the TCB +register context to virtualise the hardware debug feature for each thread.

+ +
    +
  • seL4_TCB_SetBreakpoint: Takes a capability to a TCB, and a hardware +breakpoint register ID, and sets a breakpoint on a specified virtual address, +for a range of addresses, for a certain access type (Read, Write, or both).
    • +
  • seL4_TCB_UnsetBreakpoint: Takes a capability to a TCB, and both disables and +clears the specific hardware breakpoint for that thread.
    • +
  • seL4_TCB_GetBreakpoint: Takes a capability to a TCB, and returns information +on whether or not the hardware breakpoint is enabled, and if enabled, what +virtual address it will trigger on, and what types of accesses will trigger +it.
    • +
  • seL4_TCB_ConfigureSingleStepping: Takes a capability to a TCB, and +configures a hardware debugging register to break on every instruction (or +every Nth instruction), and send a message on the thread’s fault endpoint +everytime it faults. You may reply to the fault endpoint to resume the +thread’s execution.
    • +
+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4-tutorials/debugging-userspace.md b/projects/sel4-tutorials/debugging-userspace.md deleted file mode 100644 index f169ac921dd..00000000000 --- a/projects/sel4-tutorials/debugging-userspace.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -redirect_from: - - /DebuggingUserspace -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Hardware debugging of user-space threads - -This guide is for debugging user-level code on top of seL4. See the [kernel -debugging guide](debugging-guide.html) for how to debug the kernel itself. - -## Overview - -The seL4 microkernel leverages the hardware debugging capabilities of modern -processors, and exports hardware breakpoint, watchpoint, and single-stepping to -user threads via conditionally compiled-in APIs. These kernel-level APIs can be -used as the backend for implementing a full-featured debugger, or porting an -existing one such as the GNU Debugger. - -## Enabling this feature - -You can enable and disable the hardware debugging API by going through the -kernel's configuration system by passing `-DHardwareDebugAPI=1`. - -Not all platforms support this feature for two main reasons: - -- The feature is gated behind certain hardware signals, such as `#DBGEN`, being - active. If the hardware isn't asserting these signals, the kernel will be - unable to use them. -- Your processor supports only the "Baseline" set of Coprocessor 14 registers, - and doesn't reliably expose the debug features through the debug coprocessor. - -{% include note.html kind="Caution" %} -If you compile the kernel with support for the debug API, and your ARM platform -doesn't support it, **your kernel will abort at boot**. -{% include endnote.html %} - -## Summary of the invocations - -The invocations are documented in detail in the seL4 manual. This article will -cover how to practically call them and use them in a prospective debugger. - -To view a current version of the seL4 manuals, please download the kernel source -code and then `cd manual` and execute `make`. - -Additionally, there is available source code that demonstrates how the -invocations can be used practically: the seL4-Test repository holds code tests -the debug APIs, and shows how to use them to set breakpoints, watchpoints and -single-stepping, on both x86 and ARM: - -- -- - -The invocations take capabilities to TCBs, and perform operations on the TCB -register context to virtualise the hardware debug feature for each thread. - -- `seL4_TCB_SetBreakpoint`: Takes a capability to a TCB, and a hardware - breakpoint register ID, and sets a breakpoint on a specified virtual address, - for a range of addresses, for a certain access type (Read, Write, or both). -- `seL4_TCB_UnsetBreakpoint`: Takes a capability to a TCB, and both disables and - clears the specific hardware breakpoint for that thread. -- `seL4_TCB_GetBreakpoint`: Takes a capability to a TCB, and returns information - on whether or not the hardware breakpoint is enabled, and if enabled, what - virtual address it will trigger on, and what types of accesses will trigger - it. -- `seL4_TCB_ConfigureSingleStepping`: Takes a capability to a TCB, and - configures a hardware debugging register to break on every instruction (or - every Nth instruction), and send a message on the thread's fault endpoint - everytime it faults. You may reply to the fault endpoint to resume the - thread's execution. - - diff --git a/projects/sel4-tutorials/index.html b/projects/sel4-tutorials/index.html new file mode 100644 index 00000000000..28b548c6290 --- /dev/null +++ b/projects/sel4-tutorials/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4/api-doc.html b/projects/sel4/api-doc.html new file mode 100644 index 00000000000..d6e47129b8e --- /dev/null +++ b/projects/sel4/api-doc.html @@ -0,0 +1,10038 @@ + + + + + + + seL4 API Reference | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 API Reference

+ +

This is the C API reference for the seL4 kernel, available in the library +libsel4.

+ +

General System Calls

+ +

Send

+

LIBSEL4_INLINE_FUNC void seL4_Send

+ +

Send to a capability.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrdestThe capability to be invoked.
seL4_MessageInfo_tmsgInfoThe messageinfo structure for the IPC.
+ +

Return value: This method does not return anything.

+ +

Recv

+

LIBSEL4_INLINE_FUNC seL4_MessageInfo_t seL4_Recv

+ +

Block until a message is received on an endpoint.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrsrcThe capability to be invoked.
seL4_Word *senderThe address to write sender information to. The sender information is the badge of the endpoint capability that was invoked by the sender, or the notification word of the notification object that was signalled. This parameter is ignored if NULL.
+ +

Return value: A seL4_MessageInfo_t structure

+ +

Call

+

LIBSEL4_INLINE_FUNC seL4_MessageInfo_t seL4_Call

+ +

Call a capability.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrdestThe capability to be invoked.
seL4_MessageInfo_tmsgInfoThe messageinfo structure for the IPC.
+ +

Return value: A seL4_MessageInfo_t structure

+ +

Reply

+

LIBSEL4_INLINE_FUNC void seL4_Reply

+ +

Perform a send to a one-off reply capability stored when the thread was last called. Does nothing if there is no reply capability which can happen if the blocked thread was unblocked via an operation such as destroying it.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_MessageInfo_tmsgInfoThe messageinfo structure for the IPC.
+ +

Return value: This method does not return anything.

+ +

Non-Blocking Send

+

LIBSEL4_INLINE_FUNC void seL4_NBSend

+ +

Perform a non-blocking send to a capability.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrdestThe capability to be invoked.
seL4_MessageInfo_tmsgInfoThe messageinfo structure for the IPC.
+ +

Return value: This method does not return anything.

+ +

Reply Recv

+

LIBSEL4_INLINE_FUNC seL4_MessageInfo_t seL4_ReplyRecv

+ +

Perform a reply followed by a receive in one system call.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrdestThe capability to be invoked.
seL4_MessageInfo_tmsgInfoThe messageinfo structure for the IPC.
seL4_Word *senderThe address to write sender information to. The sender information is the badge of the endpoint capability that was invoked by the sender, or the notification word of the notification object that was signalled. This parameter is ignored if NULL.
+ +

Return value: A seL4_MessageInfo_t structure

+ +

Non-Blocking Recv

+

LIBSEL4_INLINE_FUNC seL4_MessageInfo_t seL4_NBRecv

+ +

Receive a message from an endpoint but do not block in the case that no messages are pending.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrsrcThe capability to be invoked.
seL4_Word *senderThe address to write sender information to. The sender information is the badge of the endpoint capability that was invoked by the sender, or the notification word of the notification object that was signalled. This parameter is ignored if NULL.
+ +

Return value: A seL4_MessageInfo_t structure

+ +

Yield

+

LIBSEL4_INLINE_FUNC void seL4_Yield

+ +

Donate the remaining timeslice to a thread of the same priority.

+ +

Return value: This method does not return anything.

+ +

Signal

+

LIBSEL4_INLINE_FUNC void seL4_Signal

+ +

Signal a notification.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrdestThe capability to be invoked.
+ +

Return value: This method does not return anything.

+ +

Description: This is not a proper system call known by the kernel. Rather, it is a convenience wrapper which calls seL4_Send. It is useful for signalling a notification.

+ +

Wait

+

LIBSEL4_INLINE_FUNC void seL4_Wait

+ +

Perform a receive on a notification object.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrsrcThe capability to be invoked.
seL4_Word *senderThe address to write sender information to. The sender information is the badge of the endpoint capability that was invoked by the sender, or the notification word of the notification object that was signalled. This parameter is ignored if NULL.
+ +

Return value: This method does not return anything.

+ +

Description: This is not a proper system call known by the kernel. Rather, it is a convenience wrapper which calls seL4_Recv.

+ +

Poll

+

LIBSEL4_INLINE_FUNC seL4_MessageInfo_t seL4_Poll

+ +

Perform a non-blocking receive on a notification object.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrsrcThe capability to be invoked.
seL4_Word *senderThe address to write sender information to. The sender information is the badge of the endpoint capability that was invoked by the sender, or the notification word of the notification object that was signalled. This parameter is ignored if NULL.
+ +

Return value: A seL4_MessageInfo_t structure

+ +

Description: This is not a proper system call known by the kernel. Rather, it is a convenience wrapper which calls seL4_NBRecv. It is useful for doing a non-blocking wait on a notification.

+ +

Debugging System Calls

+ +

This section documents debugging system calls available when the kernel is build with the DEBUG_BUILD configuration. For any system calls that rely on a kernel serial driver, PRINTING must also be enabled.

+

Put Char

+

LIBSEL4_INLINE_FUNC void seL4_DebugPutChar

+ +

Output a single char through the kernel.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
charcThe character to output.
+ +

Return value: This method does not return anything.

+ +

Description: Use the kernel serial driver to output a single character. This is useful for debugging when a user level serial driver is not available.

+ +

Dump Scheduler

+

LIBSEL4_INLINE_FUNC void seL4_DebugDumpScheduler

+ +

Output the contents of the kernel scheduler.

+ +

Return value: This method does not return anything.

+ +

Description: Dump the state of the all TCB objects to kernel serial output. This system call will output a table containing:

+
    +
  • Address: the address of the TCB object for that thread,
    • +
  • Name: the name of the thread (if set),
    • +
  • IP: the contents of the instruction pointer the thread is at,
    • +
  • Priority: the priority of that thread,
    • +
  • State : the state of the thread.
    • +
+ +

Halt

+

LIBSEL4_INLINE_FUNC void seL4_DebugHalt

+ +

Halt the system.

+ +

Return value: This method does not return anything.

+ +

Description: This debugging system call will cause the kernel immediately cease responding to system calls. The kernel will switch permanently to the idle thread with interrupts disabled. Depending on the platform, the kernel may switch the hardware into a low-power state.

+ +

Snapshot

+

LIBSEL4_INLINE_FUNC void seL4_DebugSnapshot

+ +

Output a capDL dump of the current kernel state.

+ +

Return value: This method does not return anything.

+ +

Description: This debugging system call will output all of the capabilities in the current kernel using capDL.

+ +

Cap Identify

+

LIBSEL4_INLINE_FUNC seL4_Uint32 seL4_DebugCapIdentify

+ +

Identify the type of a capability in the current CSpace.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrcapA capability slot in the current CSpace.
+ +

Return value: The type of capability passed in.

+ +

Description: This debugging system call returns the type of capability in a capability slot in the current CSpace. The type returned is not a libsel4 type, but refers to an internal seL4 type. This can be looked up in a built kernel by looking for the (generated) enum cap_tag, type cap_tag_t.

+ +

Name Thread

+

LIBSEL4_INLINE_FUNC void seL4_DebugNameThread

+ +

Name a thread.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CPtrtcbA capability to the tcb object for the thread to name.
const char *nameThe name for the thread.
+ +

Return value: This method does not return anything.

+ +

Description: Name a thread. This name will then be output by the kernel in all debugging output. Note that the max name length that can be passed to this function is limited by the number of chars that will fit in an IPC message (seL4_MsgMaxLength multiplied by the amount of chars that fit in a word). However the name is also truncated in order to fit into a TCB object. For some platforms you may need to increase seL4_TCBBits by 1 in a debug build in order to fit a long enough name.

+ +

Send SGI 0-15

+

LIBSEL4_INLINE_FUNC void seL4_DebugSendIPI

+ +

Sends arbitrary SGI.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_Uint8targetThe target core ID.
unsignedirqThe SGI number (0-15).
+ +

Return value: This method does not return anything.

+ +

Description: Send an arbitrary SGI (core-specific interrupt 0-15) to the specified target core.

+ +

Run

+

LIBSEL4_INLINE_FUNC void seL4_DebugRun

+ +

Run a user level function in kernel mode.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
void(*)(void *)userfnThe address in userspace of the function to run.
void *userargA single argument to pass to the function.
+ +

Return value: This method does not return anything.

+ +

Description: This extremely dangerous function is for running benchmarking and debugging code that needs to be executed in kernel mode from userlevel. It should never be used in a release kernel. This works because the kernel can access all user mappings of device memory, and does not switch page directories on kernel entry. + Unlike the other system calls in this section, seL4_DebugRun does not depend on the DEBUG_BUILD configuration option, but its own config variable DANGEROUS_CODE_INJECTION.

+ +

Benchmarking System Calls

+ +

This section documents system calls available when the kernel is configured with benchmarking enabled. There are several different benchmarking modes which can be configured when building the kernel:

+ +
    +
  1. +

    BENCHMARK_TRACEPOINTS: Enable using tracepoints in the kernel and timing code.

    +
    2. +
  2. +

    BENCHMARK_TRACK_KERNEL_ENTRIES: Keep track of information on kernel entries.

    +
    3. +
  3. +

    BENCHMARK_TRACK_UTILISATION: Allow users to get CPU timing info for the system, threads and/or idle thread.

    +
    4. +
+ +

Reset Log

+

LIBSEL4_INLINE_FUNC seL4_Error seL4_BenchmarkResetLog

+ +

Reset benchmark logging.

+ +

Return value: A seL4_Error error if the user-level log buffer has not been set by the user (BENCHMARK_TRACEPOINTS/BENCHMARK_TRACK_KERNEL_ENTRIES).

+ +

Description: The behaviour of this system call depends on benchmarking mode in action while invoking this system call:

+
    +
  1. BENCHMARK_TRACEPOINTS: resets the log index to 0,
    2. +
  2. BENCHMARK_TRACK_KERNEL_ENTRIES: as above,
    3. +
  3. BENCHMARK_TRACK_UTILISATION: resets benchmark and current thread start time (to the time of invoking this syscall), resets idle thread utilisation to 0, and starts tracking utilisation.
    4. +
+ +

Finalize Log

+

LIBSEL4_INLINE_FUNC seL4_Word seL4_BenchmarkFinalizeLog

+ +

Stop benchmark logging.

+ +

Return value: The index of the final entry in the log buffer (if BENCHMARK_TRACEPOINTS/BENCHMARK_TRACK_KERNEL_ENTRIES are enabled).

+ +

Description: The behaviour of this system call depends on benchmarking mode in action while invoking this system call:

+
    +
  1. BENCHMARK_TRACEPOINTS: Sets the final log buffer index to the current index,
    2. +
  2. BENCHMARK_TRACK_KERNEL_ENTRIES: as above,
    3. +
  3. BENCHMARK_TRACK_UTILISATION: sets benchmark end time to current time, stops tracking utilisation.
    4. +
+ +

Set Log Buffer

+

LIBSEL4_INLINE_FUNC seL4_Error seL4_BenchmarkSetLogBuffer

+ +

Set log buffer.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_Wordframe_cptrA capability pointer to a user allocated frame of seL4_LargePage size.
+ +

Return value: A seL4_IllegalOperation error if frame_cptr is not valid and couldn’t set the buffer.

+ +

Description: Provide a large frame object for the kernel to use as a log-buffer. The object must not be device memory, and must be seL4_LargePageBits in size.

+ +

Null Syscall

+

LIBSEL4_INLINE_FUNC void seL4_BenchmarkNullSyscall

+ +

Null system call that enters and exits the kernel immediately, for timing kernel traps in microbenchmarks.

+ +

Return value: This method does not return anything.

+ +

Description: Used to time kernel traps (in and out).

+ +

Flush Caches

+

LIBSEL4_INLINE_FUNC void seL4_BenchmarkFlushCaches

+ +

Flush hardware caches.

+ +

Return value: This method does not return anything.

+ +

Description: Flush all possible hardware caches for this platform.

+ +

Flush L1 Caches

+

LIBSEL4_INLINE_FUNC void seL4_BenchmarkFlushL1Caches

+ +

Flush L1 caches.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_Wordcache_typeL1 Cache Type to be flushed
+ +

Return value: This method does not return anything.

+ +

Description: Flush L1 caches for this platform (currently only support for ARM). Allow to specify the cache type to be flushed (i.e. instruction cache only, data cache only and both instruction cache and data cache).

+ +

Get Thread Utilisation

+

LIBSEL4_INLINE_FUNC void seL4_BenchmarkGetThreadUtilisation

+ +

Get utilisation timing information.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_Wordtcb_cptrTCB cap pointer to a thread to get CPU utilisation for.
+ +

Return value: This method does not return anything.

+ +

Description: Get timing information for the system, requested thread and idle thread. Such information is written into the caller’s IPC buffer; see the definition of benchmark_track_util_ipc_index enum for more details on the data/format returned on the IPC buffer.

+ +

Reset Thread Utilisation

+

LIBSEL4_INLINE_FUNC void seL4_BenchmarkResetThreadUtilisation

+ +

Reset utilisation timing for a specific thread.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_Wordtcb_cptrTCB cap pointer to a thread to get CPU utilisation for.
+ +

Return value: This method does not return anything.

+ +

Description: Reset the kernel’s timing information data (start time and utilisation) for a specific thread.

+ +

Dump All Threads Utilisation

+

LIBSEL4_INLINE_FUNC void seL4_BenchmarkDumpAllThreadsUtilisation

+ +

Print the current accumulated cycle count for every thread on the current node.

+ +

Return value: This method does not return anything.

+ +

Description: Uses kernel’s printf to print number of cycles on each line in the following format: thread_name,thread_cycles

+ +

Reset All Threads Utilisation

+

LIBSEL4_INLINE_FUNC void seL4_BenchmarkResetAllThreadsUtilisation

+ +

Reset the accumulated cycle count for every thread on the current node.

+ +

Return value: This method does not return anything.

+ +

Description: Reset the cycle count for each thread to 0.

+ +

X86 System Calls

+ +

VM Enter

+

LIBSEL4_INLINE_FUNC seL4_Word seL4_VMEnter

+ +

Change current thread to execute from its bound VCPU.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_Word *senderThe address to write sender information to. If the syscall returns due to receiving a notification on the bound notification then the sender information is the badge of the notification capability that was invoked. This parameter is ignored if NULL.
+ +

Return value: SEL4_VMENTER_RESULT_NOTIF if a notification was received or SEL4_VMENTER_RESULT_FAULT if the guest mode execution faulted for any reason

+ +

Description: Changes the execution mode of the current thread from normal TCB execution, to guest execution using its bound VCPU.

+ +

Invoking seL4_VMEnter is similar to replying to a fault in that updates to the registers can be given in the message, but unlike a fault no message info is sent as the registers are not optional and the number that must be sent is fixed. The mapping of hardware register to message register is

+
    +
  • SEL4_VMENTER_CALL_EIP_MR Address to start executing instructions at in the guest mode
    • +
  • SEL4_VMENTER_CALL_CONTROL_PPC_MR New value for the Primary Processor Based VM Execution Controls
    • +
  • SEL4_VMENTER_CALL_INTERRUPT_INFO_MR New value for the VM Entry Interruption-Information
    • +
+ +

On return these same three message registers will be filled with the values at the point that the privileged mode ceased executing. If this function returns with SEL4_VMENTER_RESULT_FAULT then the following additional message registers will be filled out

+
    +
  • SEL4_VMENTER_FAULT_REASON_MR
    • +
  • SEL4_VMENTER_FAULT_QUALIFICATION_MR
    • +
  • SEL4_VMENTER_FAULT_INSTRUCTION_LEN_MR
    • +
  • SEL4_VMENTER_FAULT_GUEST_PHYSICAL_MR
    • +
  • SEL4_VMENTER_FAULT_RFLAGS_MR
    • +
  • SEL4_VMENTER_FAULT_GUEST_INT_MR
    • +
  • SEL4_VMENTER_FAULT_CR3_MR
    • +
  • SEL4_VMENTER_FAULT_EAX
    • +
  • SEL4_VMENTER_FAULT_EBX
    • +
  • SEL4_VMENTER_FAULT_ECX
    • +
  • SEL4_VMENTER_FAULT_EDX
    • +
  • SEL4_VMENTER_FAULT_ESI
    • +
  • SEL4_VMENTER_FAULT_EDI
    • +
  • SEL4_VMENTER_FAULT_EBP
    • +
+ +

Architecture-Independent Object Methods

+ +

seL4_CNode

+ +

Cancel Badged Sends

+

static inline int seL4_CNode_CancelBadgedSends

+ +

The cancel badged sends method is intended to allow for the reuse of badges by an +authority. When used with a badged endpoint capability it +will cancel any outstanding send operations for that endpoint and badge. +This operation has no effect on un-badged or other objects.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode at the root of the CSpace where the capability will be found. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the capability. Resolved from the root of the _service parameter.
seL4_Uint8depthNumber of bits of index to resolve to find the capability being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe index or depth is invalid .
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the capability does not have full rights to the Endpoint .
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe depth is invalid .
+ +

Copy

+

static inline int seL4_CNode_Copy

+ +

Copy a capability, setting its access rights whilst doing so

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_Worddest_indexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8dest_depthNumber of bits of dest_index to resolve to find the destination slot.
seL4_CNodesrc_rootCPtr to the CNode that forms the root of the source CSpace. Must be at a depth equivalent to the wordsize.
seL4_Wordsrc_indexCPtr to the source slot. Resolved from the root of the source CSpace.
seL4_Uint8src_depthNumber of bits of src_index to resolve to find the source slot.
seL4_CapRights_trightsThe rights inherited by the new capability.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth of the source or destination is invalid . Or, src_root is a CPtr to a capability of the wrong type. Or, the source slot is empty.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the source capability cannot be derived .
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe dest_depth or src_depth is invalid .
seL4_RevokeFirstThe source capability cannot be derived .
+ +

Delete

+

static inline int seL4_CNode_Delete

+ +

Delete a capability

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode at the root of the CSpace where the capability will be found. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the capability. Resolved from the root of the _service parameter.
seL4_Uint8depthNumber of bits of index to resolve to find the capability being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe index or depth is invalid .
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe depth is invalid .
+ +

Mint

+

static inline int seL4_CNode_Mint

+ +

Copy a capability, setting its access rights and badge whilst doing so

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_Worddest_indexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8dest_depthNumber of bits of dest_index to resolve to find the destination slot.
seL4_CNodesrc_rootCPtr to the CNode that forms the root of the source CSpace. Must be at a depth equivalent to the wordsize.
seL4_Wordsrc_indexCPtr to the source slot. Resolved from the root of the source CSpace.
seL4_Uint8src_depthNumber of bits of src_index to resolve to find the source slot.
seL4_CapRights_trightsThe rights inherited by the new capability.
seL4_WordbadgeBadge or guard to be applied to the new capability. For badges on 32-bit platforms, the high 4 bits are ignored.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth of the source or destination is invalid . Or, src_root is a CPtr to a capability of the wrong type. Or, the source slot is empty.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the source capability cannot be derived . Or, the badge or guard value is invalid.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe dest_depth or src_depth is invalid .
seL4_RevokeFirstThe source capability cannot be derived .
+ +

Move

+

static inline int seL4_CNode_Move

+ +

Move a capability

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_Worddest_indexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8dest_depthNumber of bits of dest_index to resolve to find the destination slot.
seL4_CNodesrc_rootCPtr to the CNode that forms the root of the source CSpace. Must be at a depth equivalent to the wordsize.
seL4_Wordsrc_indexCPtr to the source slot. Resolved from the root of the source CSpace.
seL4_Uint8src_depthNumber of bits of src_index to resolve to find the source slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth of the source or destination is invalid . Or, src_root is a CPtr to a capability of the wrong type. Or, the source slot is empty.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe dest_depth or src_depth is invalid .
+ +

Mutate

+

static inline int seL4_CNode_Mutate

+ +

Move a capability, setting its guard in the process. This +operation is mostly useful for setting the guard of a CNode +capability without losing revokability of that CNode capability. +All other uses can be replaced by a combination of Mint and +Delete.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_Worddest_indexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8dest_depthNumber of bits of dest_index to resolve to find the destination slot.
seL4_CNodesrc_rootCPtr to the CNode that forms the root of the source CSpace. Must be at a depth equivalent to the wordsize.
seL4_Wordsrc_indexCPtr to the source slot. Resolved from the root of the source CSpace.
seL4_Uint8src_depthNumber of bits of src_index to resolve to find the source slot.
seL4_WordbadgeGuard to be applied to the new capability.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth of the source or destination is invalid . Or, src_root is a CPtr to a capability of the wrong type. Or, the source slot is empty.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the guard value is invalid.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe dest_depth or src_depth is invalid .
+ +

Revoke

+

static inline int seL4_CNode_Revoke

+ +

Delete all child capabilities of a capability

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode at the root of the CSpace where the capability will be found. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the capability. Resolved from the root of the _service parameter.
seL4_Uint8depthNumber of bits of index to resolve to find the capability being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe index or depth is invalid .
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe depth is invalid .
+ +

Rotate

+

static inline int seL4_CNode_Rotate

+ +

Given 3 capability slots - a destination, pivot and source - move the capability in the +pivot slot to the destination slot and the capability in the source slot to the pivot slot

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode at the root of the CSpace where the destination slot will be found. Must be at a depth equivalent to the wordsize.
seL4_Worddest_indexCPtr to the destination slot. Resolved relative to _service. Must be empty unless it refers to the same slot as the source slot.
seL4_Uint8dest_depthDepth to resolve dest_index to.
seL4_Worddest_badgeThe new capdata for the capability that ends up in the destination slot.
seL4_CNodepivot_rootCPtr to the CNode at the root of the CSpace where the pivot slot will be found. Must be at a depth equivalent to the wordsize.
seL4_Wordpivot_indexCPtr to the pivot slot. Resolved relative to pivot_root. The resolved slot must not refer to the source or destination slots.
seL4_Uint8pivot_depthDepth to resolve pivot_index to.
seL4_Wordpivot_badgeThe new capdata for the capability that ends up in the pivot slot.
seL4_CNodesrc_rootCPtr to the CNode at the root of the CSpace where the source slot will be found. Must be at a depth equivalent to the wordsize.
seL4_Wordsrc_indexCPtr to the source slot. Resolved relative to src_root.
seL4_Uint8src_depthDepth to resolve src_index to.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstIf the destination is not the same slot as the source and the destination slot contains a capability.
seL4_FailedLookupThe index or depth of the source, destination, or pivot is invalid . Or, src_root or pivot_root is a CPtr to a capability of the wrong type. Or, the source or pivot slot is empty.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the pivot is the same slot as the source or destination. Or, the guard value on the destination or pivot is invalid.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe dest_depth, src_depth, or pivot_depth is invalid .
+ +

Save Caller

+

static inline int seL4_CNode_SaveCaller

+ +

Save the reply capability from the last time the thread was called in the given CSpace so that it can be invoked later

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_CNode_serviceCPtr to the CNode at the root of the CSpace where the capability is to be saved. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the slot in which to save the capability. Resolved from the root of the _service parameter.
seL4_Uint8depthNumber of bits of index to resolve to find the slot being targeted.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid .
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe depth is invalid .
+ +

seL4_DomainSet

+ +

Set

+

static inline int seL4_DomainSet_Set

+ +

Change the domain of a thread.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_DomainSet_serviceCapability allowing domain configuration.
seL4_Uint8domainThe thread’s new domain.
seL4_TCBthreadCapability to the TCB which is being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe domain is greater than CONFIG_NUM_DOMAINS. Or, thread is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_IRQControl

+ +

Get IRQ Handler

+

static inline int seL4_IRQControl_Get

+ +

Create an IRQ handler capability

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQControl_serviceAn IRQControl capability. This gives you the authority to make this call.
seL4_WordirqThe IRQ that you want this capability to handle.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe root, index, or depth is invalid .
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, on x86, an IOAPIC is being used.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe irq is invalid for the target architecture. Or, on x86, irq is not in the ISA IRQ range. Or, depth is invalid .
seL4_RevokeFirstAn IRQ handler capability for irq has already been created.
+ +

seL4_IRQHandler

+ +

Acknowledge

+

static inline int seL4_IRQHandler_Ack

+ +

Acknowledge the receipt of an interrupt and re-enable it

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQHandler_serviceThe IRQ handler capability.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Clear

+

static inline int seL4_IRQHandler_Clear

+ +

Clear the handler capability from the IRQ slot

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQHandler_serviceThe IRQ handler capability.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Set Notification

+

static inline int seL4_IRQHandler_SetNotification

+ +

Set the notification which the kernel will signal on interrupts +controlled by the supplied IRQ handler capability

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQHandler_serviceThe IRQ handler capability.
seL4_CPtrnotificationThe notification which the IRQs will signal.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or notification is a CPtr to a capability of the wrong type. Or, notification does not have the Write right .
+ +

seL4_SchedContext (MCS)

+ +

Bind

+

static inline int seL4_SchedContext_Bind

+ +

Bind an object to a scheduling context. The object can be a notification object or a +thread.

+ +

If the object is a thread and the thread is in a runnable state and the scheduling +context has available budget, this will start the thread running.

+ +

If the object is a notification, when passive threads wait on the notification object and +a signal arrives, the passive thread will receive the scheduling context and possess it +until it waits on the notification object again.

+ +

This operation will fail for notification objects if the scheduling context is already +bound to a notification object, and for thread objects if the scheduling context is +already bound to a thread.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_SchedContext_serviceCapability to the scheduling context which is being operated on.
seL4_CPtrcapCapability to a TCB or a notification object
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service or cap is already bound to the same type of object. Or, cap is a TCB in the blocked state and _service is not schedulable.
seL4_InvalidCapabilityThe _service or cap is a CPtr to a capability of the wrong type.
+ +

Consumed

+

static inline seL4_SchedContext_Consumed_t seL4_SchedContext_Consumed

+ +

Return the amount of time used by this scheduling context since this function was last called or a timeout exception triggered.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_SchedContext_serviceCapability to the scheduling context which is being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Unbind Object

+

static inline int seL4_SchedContext_UnbindObject

+ +

Unbind an object from a scheduling context. The object can be either a thread or a +notification.

+ +

If the thread being unbound is the thread that is bound to this scheduling context, +this will render the thread passive. However if the thread being +unbound received the scheduling context via scheduling context donation over IPC, +the scheduling context will be returned to the thread that it was originally bound to.

+ +

If the object is a notification and it is bound to the scheduling context, unbind it.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_SchedContext_serviceCapability to the scheduling context which is being operated on.
seL4_CPtrcapCapability to a notification that is bound to the scheduling context or capability to a TCB that is bound to this scheduling context or has received it through scheduling context donation.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, cap is not bound to _service. Or, cap is the current thread’s TCB.
seL4_InvalidCapabilityThe _service or cap is a CPtr to a capability of the wrong type.
+ +

Unbind

+

static inline int seL4_SchedContext_Unbind

+ +

Unbind any objects (threads or notification objects) from a scheduling context. This +will render the bound thread passive, see Section 6.1.5.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_SchedContext_serviceCapability to the scheduling context which is being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the current thread’s TCB is bound to _service.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Yield To

+

static inline seL4_SchedContext_YieldTo_t seL4_SchedContext_YieldTo

+ +

If a thread is currently runnable and running on this scheduling context and the scheduling context has available budget, place it at the head of the scheduling queue. +If the caller is at an equal priority to the thread this will result in the thread being scheduled. +If the caller is at a higher priority the thread will not run until the threads priority is the highest priority in the system. +The caller must have a maximum control priority greater than or equal to the threads priority.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_SchedContext_serviceCapability to the scheduling context which is being operated on.
+ +

Return value:

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not bound to a TCB or is bound to the current thread’s TCB. Or, the target thread’s priority is greater than the current thread’s maximum controlled priority .
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Capability to the scheduling context which is being operated on.

+

seL4_SchedControl (MCS)

+ +

Configure Flags

+

static inline int seL4_SchedControl_ConfigureFlags

+ +

Set the parameters of a scheduling context by invoking the scheduling control capability. If the scheduling context is bound to a currently running thread, the parameters will take effect immediately: that is the current budget will be increased or reduced by the difference between the new and previous budget and the replenishment time will be updated according to any difference in the period. This can result in active threads being post-poned or released depending on the nature of the parameter change and the state of the thread. Additionally, if the scheduling context was previously empty (no budget) but bound to a runnable thread, this can result in a thread running for the first time since it now has access to CPU time. This call will return seL4 Invalid Argument if the parameters are too small (smaller than the kernel WCET for this platform) or too large (will overflow the timer).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_SchedControl_serviceCapability to a scheduling control object.
seL4_SchedContextschedcontextCapability to the scheduling context which is being operated on.
seL4_TimebudgetTimeslice in microseconds, when the budget expires the thread will be pre-empted.
seL4_TimeperiodPeriod in microseconds, if equal to budget, this thread will be treated as a round-robin thread. Otherwise, sporadic servers will be used to assure the scheduling context does not exceed the budget over the specified period.
seL4_Wordextra_refillsNumber of extra sporadic replenishments this scheduling context should use. Ignored for round-robin threads.
seL4_WordbadgeIdentifier for this scheduling context. Delivered to timeout exception handler. Can be used to determine which scheduling context triggered the timeout.
seL4_WordflagsBitwise OR’d set of seL4_SchedContextFlag.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or schedcontext is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe budget or period or extra_refills is too big or too small. Or, budget is greater than period.
+ +

seL4_TCB

+ +

Bind Notification

+

static inline int seL4_TCB_BindNotification

+ +

Binds a notification object to a TCB

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_CPtrnotificationNotification to bind.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service or notification is a CPtr to a capability of the wrong type. Or, _service or notification is already bound. Or, notification does not have Read rights to the Notification .
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Configure Single Stepping

+

static inline seL4_TCB_ConfigureSingleStepping_t seL4_TCB_ConfigureSingleStepping

+ +

Set or modify single stepping options for the target TCB. Subsequent calls to this +function overwrite previous configuration. Depending on your processor architecture, +this may or may not require the consumption of a hardware register.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Uint16bp_numThe API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1. This value is unused on AARCH64
seL4_Wordnum_instructionsNumber of instructions to step over before delivering a fault to the target thread’s fault endpoint. Setting this to 0 disables single-stepping.
+ +

Return value: A seL4_TCB_ConfigureSingleStepping_t: Struct that contains seL4_Error error, an seL4 API error value, seL4_Bool bp_was_consumed, a boolean which indicates whether or not the bp_num breakpoint ID that was passed to the function, was consumed in the setup of the single-stepping functionality: if this is true, the caller should not attempt to re-use bp_num until it has disabled the single-stepping functionality via a subsequent call to seL4_TCB_ConfigureSingleStepping with an num_instructions argument of 0.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the argument values are inappropriate for the target architecture.
seL4_InvalidArgumentThe argument values are inappropriate for the target architecture.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Configure

+

static inline int seL4_TCB_Configure

+ +

Set the parameters of a TCB

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Wordfault_epCPtr to the endpoint which receives IPCs when this thread faults. This capability is in the CSpace of the thread being configured.
seL4_CNodecspace_rootThe new CSpace root.
seL4_Wordcspace_root_dataOptionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect.
seL4_CPtrvspace_rootThe new VSpace root.
seL4_Wordvspace_root_dataHas no effect on x86 or ARM processors.
seL4_WordbufferLocation of the thread’s IPC buffer. Must be aligned to seL4_IPCBufferSizeBits. The IPC buffer may not cross a page boundary.
seL4_CPtrbufferFrameCapability to a page containing the thread’s IPC buffer.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service, bufferFrame, cspace_root, or vspace_root is a CPtr to a capability of the wrong type. Or, vspace_root is not assigned to an ASID pool. Or, cspace_root_data is invalid. Or, buffer is not aligned. Or, bufferFrame is retyped from a device untyped .
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstThe bufferFrame, cspace_root, or vspace_root is a CPtr to a capability of the wrong type.
+ +

Copy Registers

+

static inline int seL4_TCB_CopyRegisters

+ +

Copy the registers from one thread to another

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on. This is the destination TCB.
seL4_TCBsourceCap to the source TCB.
seL4_Boolsuspend_sourceThe invocation should also suspend the source thread.
seL4_Boolresume_targetThe invocation should also resume the destination thread.
seL4_Booltransfer_frameFrame registers should be transferred.
seL4_Booltransfer_integerInteger registers should be transferred.
seL4_Uint8arch_flagsArchitecture dependent flags. These have no meaning on x86, ARM, and RISC-V.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or source is a CPtr to a capability of the wrong type.
+ +

Description: In the context of this function, frame registers are those that are read, modified or preserved by a system call and integer registers are those that are not. Refer to the seL4 userland library source for specifics.

+ +

Get Breakpoint

+

static inline seL4_TCB_GetBreakpoint_t seL4_TCB_GetBreakpoint

+ +

Read a breakpoint or watchpoint’s current configuration.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Uint16bp_numThe API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1.
+ +

Return value: A seL4_TCB_GetBreakpoint_t: Struct that contains seL4_Error error, an seL4 API error value, seL4_Word vaddr, the virtual address at which the breakpoint will currently be triggered; seL4_Word type, the type of operation which will currently trigger the breakpoint, whether instruction execution, or data access; seL4_Word size, integer value for the span-size of the breakpoint. Usually a power of two (1, 2, 4, etc.); seL4_Word rw, the access direction that will currently trigger the breakpoint, whether read, write, or both and seL4_Bool is_enabled, which indicates whether or not the breakpoint will currently be triggered if the match conditions are met.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe argument values are inappropriate for the target architecture.
+ +

Read Registers

+

static inline int seL4_TCB_ReadRegisters

+ +

Read a thread’s registers into the first count fields of a given +seL4_UserContext

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Boolsuspend_sourceThe invocation should also suspend the source thread.
seL4_Uint8arch_flagsArchitecture dependent flags. These have no meaning on x86, ARM, and RISC-V.
seL4_WordcountThe number of registers to read.
seL4_UserContext *regsThe structure to read the registers into.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is the current thread’s TCB.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe count requested too few or too many registers.
+ +

Resume

+

static inline int seL4_TCB_Resume

+ +

Resume a thread

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Set Breakpoint

+

static inline int seL4_TCB_SetBreakpoint

+ +

Set or modify a thread’s breakpoints or watchpoints. Calls to this function +overwrite previous configurations for the target breakpoint. Do not use this +with seL4_SingleStep: the API will reject the call and return an error. +Instead, use seL4_TCB_ConfigureSingleStepping to configure single-stepping.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Uint16bp_numThe API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1.
seL4_WordvaddrA virtual address which forms part of the match conditions for the triggering of the breakpoint.
seL4_WordtypeOne of: seL4_InstructionBreakpoint, which specifies that the breakpoint should occur on instruction execution at the specified vaddr or seL4_DataBreakpoint, which states that the breakpoint should occur on data access at the specified vaddr.
seL4_WordsizeA positive integer indicating the trigger-span of the watchpoint. Must be zero when ‘type’ is seL4_InstructionBreakpoint.
seL4_WordrwOne of seL4_BreakOnRead, meaning the breakpoint will only be triggered on read-access; seL4_BreakOnWrite meaning the breakpoint will only be triggered on write-access, and seL4_BreakOnReadWrite meaning the breakpoint will be triggered on any access.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_AlignmentErrorThe vaddr is not aligned to size bytes.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe bp_num, size, or rw is not valid for the given type. Or, argument values are inappropriate for the target architecture. Or, vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe argument values are inappropriate for the target architecture.
+ +

Set CPU Affinity

+

static inline int seL4_TCB_SetAffinity

+ +

Change a thread’s current CPU in multicore machine

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_WordaffinityThe thread’s new CPU to run.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, affinity is not a valid CPU number.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Set Feature Flags

+

static inline seL4_TCB_SetFlags_t seL4_TCB_SetFlags

+ +

Set or clear seL4_TCBFlag feature flags of the target TCB.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_WordclearBitwise OR’d set of seL4_TCBFlag to clear.
seL4_WordsetBitwise OR’d set of seL4_TCBFlag to set.
+ +

Return value: The resulting TCB flags value is returned in the first message register.

+ + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: A newly created TCB has all flags cleared. Currently the only flag supported is seL4_TCBFlag_fpuDisabled. The flags are cleared and set in the given order, i.e. when a flag is both cleared and set, it will be set. Unknown flags are ignored. Use zero for both clear and set to retrieve the current flags value.

+ +

Set IPC Buffer

+

static inline int seL4_TCB_SetIPCBuffer

+ +

Set a thread’s IPC buffer

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_WordbufferLocation of the thread’s IPC buffer. Must be aligned to seL4_IPCBufferSizeBits. The IPC buffer may not cross a page boundary.
seL4_CPtrbufferFrameCapability to a page containing the thread’s IPC buffer.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_AlignmentErrorThe buffer is not aligned.
seL4_IllegalOperationThe _service or bufferFrame is a CPtr to a capability of the wrong type. Or, bufferFrame is retyped from a device untyped .
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstThe bufferFrame is a CPtr to a capability of the wrong type.
+ +

Description: See Sections threads and messageinfo

+ +

Set Maximum Controlled Priority

+

static inline int seL4_TCB_SetMCPriority

+ +

Change a thread’s maximum controlled priority

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_TCBauthorityCapability to the TCB to use the MCP from when setting the MCP.
seL4_WordmcpThe thread’s new maximum controlled priority.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or authority is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe mcp is greater than the maximum controlled priority of authority.
+ +

Set Priority

+

static inline int seL4_TCB_SetPriority

+ +

Change a thread’s priority

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_TCBauthorityCapability to the TCB to use the MCP from when setting the priority.
seL4_WordpriorityThe thread’s new priority.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or authority is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe priority is greater than the maximum controlled priority of authority.
+ +

Set Sched Params

+

static inline int seL4_TCB_SetSchedParams

+ +

Change a thread’s priority and maximum controlled priority.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_TCBauthorityCapability to the TCB to use the MCP from when setting the priority and MCP.
seL4_WordmcpThe thread’s new maximum controlled priority.
seL4_WordpriorityThe thread’s new priority.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or authority is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe mcp is greater than the maximum controlled priority of authority. Or, priority is greater than the maximum controlled priority of authority.
+ +

Set Space

+

static inline int seL4_TCB_SetSpace

+ +

Set the fault endpoint, CSpace and VSpace of a thread

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Wordfault_epCPtr to the endpoint which receives IPCs when this thread faults. This capability is in the CSpace of the thread being configured.
seL4_CNodecspace_rootThe new CSpace root.
seL4_Wordcspace_root_dataOptionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect.
seL4_CPtrvspace_rootThe new VSpace root.
seL4_Wordvspace_root_dataHas no effect on x86 or ARM processors.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service, cspace_root, or vspace_root is a CPtr to a capability of the wrong type. Or, vspace_root is not assigned to an ASID pool. Or, cspace_root_data is invalid.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstThe cspace_root or vspace_root is a CPtr to a capability of the wrong type.
+ +

Set TLS Base

+

static inline int seL4_TCB_SetTLSBase

+ +

Set the TLS base of the target TCB.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Wordtls_baseThe TLS base to set.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: An invocation for setting the Thread Local Storage (TLS) base address. This ensures that across all platforms, the TLSBase register is viewed as being completely mutable, just like all of the general purpose registers, even on platforms where modification is a privileged operation.

+ +

Suspend

+

static inline int seL4_TCB_Suspend

+ +

Suspend a thread

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Unbind Notification

+

static inline int seL4_TCB_UnbindNotification

+ +

Unbinds any notification object from a TCB

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not bound to a notification.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Unset Breakpoint

+

static inline int seL4_TCB_UnsetBreakpoint

+ +

Disables a hardware breakpoint or watchpoint. The caller should assume that +the underlying configuration of the hardware registers has also been cleared. +Do not use this to clear single-stepping: the API will reject the call and +return an error. Instead, use seL4_TCB_ConfigureSingleStepping to disable +single-stepping.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Uint16bp_numThe API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the argument values are inappropriate for the target architecture.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe argument values are inappropriate for the target architecture.
+ +

Write Registers

+

static inline int seL4_TCB_WriteRegisters

+ +

Set a thread’s registers to the first count fields of a given seL4_UserContext

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_Boolresume_targetThe invocation should also resume the destination thread.
seL4_Uint8arch_flagsArchitecture dependent flags. These have no meaning on x86, ARM, and RISC-V.
seL4_WordcountThe number of registers to be set.
seL4_UserContext *regsData structure containing the new register values.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is the current thread’s TCB.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_TCB (MCS)

+ +

Configure (MCS)

+

static inline int seL4_TCB_Configure

+ +

Set the parameters of a TCB

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_CNodecspace_rootThe new CSpace root.
seL4_Wordcspace_root_dataOptionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect.
seL4_CPtrvspace_rootThe new VSpace root.
seL4_Wordvspace_root_dataHas no effect on x86 or ARM processors.
seL4_WordbufferLocation of the thread’s IPC buffer. Must be aligned to seL4_IPCBufferSizeBits. The IPC buffer may not cross a page boundary.
seL4_CPtrbufferFrameCapability to a page containing the thread’s IPC buffer.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_AlignmentErrorThe buffer is not aligned.
seL4_IllegalOperationThe _service, bufferFrame, cspace_root, or vspace_root is a CPtr to a capability of the wrong type. Or, vspace_root is not assigned to an ASID pool. Or, cspace_root_data is invalid. Or, bufferFrame is retyped from a device untyped .
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstThe bufferFrame, cspace_root, or vspace_root is a CPtr to a capability of the wrong type.
+ +

Set Sched Params (MCS)

+

static inline int seL4_TCB_SetSchedParams

+ +

Change a thread’s priority, maximum controlled priority, scheduling context +and fault handler.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_TCBauthorityCapability to the TCB to use the MCP from when setting the priority and MCP.
seL4_WordmcpThe thread’s new maximum controlled priority.
seL4_WordpriorityThe thread’s new priority.
seL4_CPtrsched_contextCapability to the scheduling context that the TCB should run on. If the scheduling context is already bound to a notification or TCB that is not this TCB this operation will fail. Similarly, if this TCB is already bound to a scheduling context that is not this scheduling context, this will also fail.
seL4_CPtrfault_epCPtr to the endpoint which receives IPCs when this thread faults.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service or sched_context is already bound. Or, _service is the current thread’s TCB. Or, _service is a TCB in the blocked state and sched_context is not schedulable.
seL4_InvalidCapabilityThe _service, authority, sched_context, or fault_ep is a CPtr to a capability of the wrong type. Or, fault_ep does not have both Write rights and either Grant or GrantReply rights to the Endpoint .
seL4_RangeErrorThe mcp is greater than the maximum controlled priority of authority. Or, priority is greater than the maximum controlled priority of authority.
+ +

Set Space (MCS)

+

static inline int seL4_TCB_SetSpace

+ +

Set the fault endpoint, CSpace and VSpace of a thread

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_CPtrfault_epCPtr to the endpoint which receives IPCs when this thread faults. On MCS this cap gets copied into the TCB.
seL4_CNodecspace_rootThe new CSpace root.
seL4_Wordcspace_root_dataOptionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect.
seL4_CPtrvspace_rootThe new VSpace root.
seL4_Wordvspace_root_dataHas no effect on x86 or ARM processors.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service, cspace_root, or vspace_root is a CPtr to a capability of the wrong type. Or, vspace_root is not assigned to an ASID pool. Or, cspace_root_data is invalid.
seL4_InvalidCapabilityThe _service or fault_ep is a CPtr to a capability of the wrong type. Or, fault_ep does not have both Write rights and either Grant or GrantReply rights to the Endpoint .
seL4_RevokeFirstThe cspace_root or vspace_root is a CPtr to a capability of the wrong type.
+ +

Set Timeout Endpoint

+

static inline int seL4_TCB_SetTimeoutEndpoint

+ +

Set a thread’s timeout endpoint.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_CPtrtimeout_fault_epCPtr to the endpoint which receives IPCs when this thread triggers timeout faults. Can be null.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or timeout_fault_ep is a CPtr to a capability of the wrong type. Or, timeout_fault_ep does not have both Write rights and either Grant or GrantReply rights to the Endpoint .
+ +

Description: Timeout exception messages will be delivered to this endpoint if it is not a null capability.

+

seL4_Untyped

+ +

Retype

+

static inline int seL4_Untyped_Retype

+ +

Retype an untyped object

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_Untyped_serviceCPtr to an untyped object.
seL4_WordtypeThe seL4 object type that we are retyping to.
seL4_Wordsize_bitsUsed to determine the size of variable-sized objects.
seL4_CNoderootCPtr to the CNode at the root of the destination CSpace.
seL4_Wordnode_indexCPtr to the destination CNode. Resolved relative to the root parameter.
seL4_Wordnode_depthNumber of bits of node_index to translate when addressing the destination CNode.
seL4_Wordnode_offsetNumber of slots into the node at which capabilities start being placed.
seL4_Wordnum_objectsNumber of capabilities to create.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA capability exists in the destination window of the CNode.
seL4_FailedLookupThe root, node_index, or node_depth is invalid .
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe size_bits is too big or too small for the requested object type. Or, type cannot be created from a device untyped . Or, the requested object type does not exist.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_NotEnoughMemoryThe total size of the new objects exceeds the space available.
seL4_RangeErrorThe num_objects do not fit in the destination CNode at node_offset. Or, num_objects is greater than CONFIG_RETYPE_FAN_OUT_LIMIT. Or, size_bits is too large.
+ +

Description: Given a capability, _service, to an untyped object, creates num_objects of the requested type. Creates num_objects capabilities to the new objects starting at node_offset in the CNode specified by root, node_index, and node_depth. + For variable-sized kernel objects, the size_bits argument is used to determine the size of objects to create. The relationship between size_bits and object size depends on the type of object being created.

+ +

General x86 Object Methods

+ +

seL4_IRQControl

+ +

Get I/O APIC Handler

+

static inline int seL4_IRQControl_GetIOAPIC

+ +

Create an IRQ handler capability for an interrupt from an IOAPIC.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQControl_serviceAn IRQControl capability. This gives you the authority to make this call.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
seL4_WordioapicZero based index of IOAPIC to get interrupt from, ordered the same as in ACPI tables
seL4_WordpinIOAPIC pin that generates the interrupt.
seL4_WordlevelIndicates whether the IOAPIC should be programmed to treat this interrupt as level triggered.
seL4_WordpolarityIndicates whether the IOAPIC should be programmed to treat this interrupt as high or low triggered
seL4_WordvectorCPU vector to deliver the interrupt to.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, an IOAPIC is not in use.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe vector, ioapic, or pin is invalid. Or, level or polarity is not 0 or 1. Or, depth is invalid .
seL4_RevokeFirstAn IRQ handler capability for vector has already been created.
+ +

Get MSI Handler

+

static inline int seL4_IRQControl_GetMSI

+ +

Create an IRQ handler capability for an interrupt from an MSI.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQControl_serviceAn IRQControl capability. This gives you the authority to make this call.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
seL4_Wordpci_busPCI bus ID of the device that will generate the interrupt.
seL4_Wordpci_devPCI device ID of the device that will generate the interrupt.
seL4_Wordpci_funcPCI function ID of the device that will generate the interrupt.
seL4_WordhandleValue of the handle programmed into the data portion of the MSI.
seL4_WordvectorCPU vector to deliver the interrupt to.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, an IOAPIC is not in use.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe vector, pic_bus, pci_dev, or pci_func is invalid. Or, the depth is invalid .
seL4_RevokeFirstAn IRQ handler capability for vector has already been created.
+ +

seL4_TCB

+ +

Set EPT Root

+

static inline int seL4_TCB_SetEPTRoot

+ +

Set the EPT root of a thread

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_TCB_serviceCapability to the TCB which is being operated on.
seL4_X86_EPTPML4eptpml4CPtr to an EPT PML4 object to act as the guest mode vspace root
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service or eptpml4 is a CPtr to a capability of the wrong type. Or, eptpml4 is not assigned to an ASID pool.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_X86_ASIDControl

+ +

Make Pool

+

static inline int seL4_X86_ASIDControl_MakePool

+ +

Create an X86 ASID pool.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_ASIDControl_serviceThe master ASIDControl capability.
seL4_UntypeduntypedCapability to an untyped memory object that will become the pool. Must be 4K bytes.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability. Or, there are no more ASID pools available.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or untyped is a CPtr to a capability of the wrong type. Or, untyped is not the exact size of an ASID pool object. Or, untyped is a device untyped .
seL4_RangeErrorThe depth is invalid .
seL4_RevokeFirstThe untyped has been used to retype an object. Or, a copy of the untyped capability exists.
+ +

Description: Together with a capability to Untyped Memory, which is passed as an argument, create an ASID Pool. The untyped capability must represent a 4K memory object. This will create an ASID pool with enough space for 1024 VSpaces.

+

seL4_X86_ASIDPool

+ +

Assign

+

static inline int seL4_X86_ASIDPool_Assign

+ +

Assign an ASID pool.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_ASIDPool_serviceThe ASID pool which is being assigned to. Must not be full. Each ASID pool can contain 1024 entries.
seL4_CPtrvspaceThe page directory that is being assigned to an ASID pool. Must not already be assigned to an ASID pool.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThere are no more ASIDs available in _service.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is already assigned to an ASID pool.
+ +

Description: Assigns an ASID to the VSpace associated with the Page Directory passed in as an argument.

+

seL4_X86_EPTPD

+ +

Map

+

static inline int seL4_X86_EPTPD_Map

+ +

Map an EPT page directory.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_EPTPD_serviceCapability to the EPT PD being operated on.
seL4_X86_EPTPML4eptpml4Capability to the EPT root which will contain the mapping
seL4_WordgpaGuest physical address to map the page into.
seL4_X86_EPT_VMAttributesattrVM attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists for this level in eptpml4 at gpa.
seL4_FailedLookupThe eptpml4 is not assigned to an ASID pool. Or, eptpml4 does not have an EPTPDPT mapped at gpa.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or eptpml4 is a CPtr to a capability of the wrong type. Or, _service is already mapped in a VSpace. Or, eptpml4 is not assigned to an ASID pool.
+ +

Unmap

+

static inline int seL4_X86_EPTPD_Unmap

+ +

Unmap an EPT page directory.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_EPTPD_serviceCapability to the EPT PD being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstA copy of the _service capability exists.
+ +

seL4_X86_EPTPDPT

+ +

Map

+

static inline int seL4_X86_EPTPDPT_Map

+ +

Map an EPT page directory page table.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_EPTPDPT_serviceCapability to the EPT PDPT being operated on.
seL4_X86_EPTPML4eptpml4Capability to the EPT root which will contain the mapping
seL4_WordgpaGuest physical address to map the page into.
seL4_X86_EPT_VMAttributesattrVM attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists for this level in eptpml4 at gpa.
seL4_FailedLookupThe eptpml4 is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or eptpml4 is a CPtr to a capability of the wrong type. Or, _service is already mapped in a VSpace. Or, eptpml4 is not assigned to an ASID pool.
+ +

Unmap

+

static inline int seL4_X86_EPTPDPT_Unmap

+ +

Unmap an EPT page directory page table.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_EPTPDPT_serviceCapability to the EPT PDPT being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstA copy of the _service capability exists.
+ +

seL4_X86_EPTPT

+ +

Map

+

static inline int seL4_X86_EPTPT_Map

+ +

Map an EPT page table.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_EPTPT_serviceCapability to the EPT PT being operated on.
seL4_X86_EPTPML4eptpml4Capability to the EPT root which will contain the mapping
seL4_WordgpaGuest physical address to map the page into.
seL4_X86_EPT_VMAttributesattrVM attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists for this level in eptpml4 at gpa.
seL4_FailedLookupThe eptpml4 is not assigned to an ASID pool. Or, eptpml4 does not have an EPTPD mapped at gpa.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or eptpml4 is a CPtr to a capability of the wrong type. Or, _service is already mapped in a VSpace. Or, eptpml4 is not assigned to an ASID pool.
+ +

Unmap

+

static inline int seL4_X86_EPTPT_Unmap

+ +

Unmap an EPT page table.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_EPTPT_serviceCapability to the EPT PT being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstA copy of the _service capability exists.
+ +

seL4_X86_IOPageTable

+ +

Map

+

static inline int seL4_X86_IOPageTable_Map

+ +

Map an IO page table into an IOSpace.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPageTable_serviceCapability to the I/O page table being operated on.
seL4_X86_IOSpaceiospaceThe IOSpace to map the page table into.
seL4_WordioaddrThe address to map the page table at.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstAll required page tables are already mapped in iospace at ioaddr.
seL4_FailedLookupThe iospace does not have a paging structure at the required level mapped at ioaddr.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or iospace is a CPtr to a capability of the wrong type. Or, iospace is not assigned to a PCI device. Or, _service is already mapped in an IOSpace.
+ +

Unmap

+

static inline int seL4_X86_IOPageTable_Unmap

+ +

Unmap an IO page table from an IOSpace.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPageTable_serviceCapability to the I/O page table being operated on.The page table to unmap.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_X86_IOPort

+ +

In16

+

static inline seL4_X86_IOPort_In16_t seL4_X86_IOPort_In16

+ +

Read 16 bits from an IO port.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPort_serviceAn I/O Port capability.
seL4_Uint16portThe port to read from.
+ +

Return value: A seL4_X86_IOPort_In16_t structure

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, reading from port and port+1 is not authorized by the capability.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

In32

+

static inline seL4_X86_IOPort_In32_t seL4_X86_IOPort_In32

+ +

Read 32 bits from an IO port.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPort_serviceAn I/O Port capability.
seL4_Uint16portThe port to read from.
+ +

Return value: A seL4_X86_IOPort_In32_t structure

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, reading from ports port through port+3 is not authorized by the capability.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

In8

+

static inline seL4_X86_IOPort_In8_t seL4_X86_IOPort_In8

+ +

Read 8 bits from an IO port.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPort_serviceAn I/O Port capability.
seL4_Uint16portThe port to read from.
+ +

Return value: A seL4_X86_IOPort_In8_t structure

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, reading from port is not authorized by the capability.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Out16

+

static inline int seL4_X86_IOPort_Out16

+ +

Write 16 bits to an IO port.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPort_serviceAn I/O Port capability.
seL4_WordportThe port to write to.
seL4_WorddataData to write to the IO port.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, writing to port and port+1 is not authorized by the capability.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Out32

+

static inline int seL4_X86_IOPort_Out32

+ +

Write 32 bits to an IO port.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPort_serviceAn I/O Port capability.
seL4_WordportThe port to write to.
seL4_WorddataData to write to the IO port.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, writing to ports port through port+3 is not authorized by the capability.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Out8

+

static inline int seL4_X86_IOPort_Out8

+ +

Write 8 bits to an IO port.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPort_serviceAn I/O Port capability.
seL4_WordportThe port to write to.
seL4_WorddataData to write to the IO port.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, writing to port is not authorized by the capability.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_X86_IOPortControl

+ +

Issue

+

static inline int seL4_X86_IOPortControl_Issue

+ +

Issue an IO port sub range.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_IOPortControl_serviceControl capability for I/O ports.
seL4_Wordfirst_portFirst port of the range of the issued capability.
seL4_Wordlast_portLast port of the range of the issued capability.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe last_port is less than first_port.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe depth is invalid .
seL4_RevokeFirstOne or more ports in the requested range have already been issued.
+ +

seL4_X86_Page

+ +

Get Address

+

static inline seL4_X86_Page_GetAddress_t seL4_X86_Page_GetAddress

+ +

Get the physical address of the underlying frame.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_Page_serviceCapability to the page being operated on.
+ +

Return value: A seL4_IA32_Page_GetAddress_t struct that contains a seL4_Word paddr, which holds the physical address of the page, and int error.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Map EPT

+

static inline int seL4_X86_Page_MapEPT

+ +

Map an extended page table.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_Page_serviceCapability to the page being operated on.
seL4_X86_EPTPML4vspaceCapability to the VSpace which will contain the mapping
seL4_WordvaddrVirtual address at which to map page.
seL4_CapRights_trightsRights for the mapping.
seL4_X86_EPT_VMAttributesattrVM attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_AlignmentErrorThe vaddr is not aligned to the page size of _service.
seL4_DeleteFirstA mapping already exists in vspace at vaddr.
seL4_FailedLookupThe vspace does not have a paging structure at the required level mapped at vaddr. Or, vspace is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not assigned to an ASID pool. Or, _service is already mapped. Or, _service has an unsupported page size.
+ +

Map I/O

+

static inline int seL4_X86_Page_MapIO

+ +

Map a page into an IOSpace.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_Page_serviceCapability to the page being operated on.
seL4_X86_IOSpaceiospaceThe IOSpace that the frame is being mapped into
seL4_CapRights_trightsRights for the mapping.
seL4_WordioaddrThe address that the frame is being mapped at.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists in iospace at ioaddr.
seL4_FailedLookupThe iospace does not have a sufficient number of IO Page Tables mapped at ioaddr.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentNo rights were specified in rights. Or, the rights in the _service capability do not include rights.
seL4_InvalidCapabilityThe _service or iospace is a CPtr to a capability of the wrong type. Or, _service is already mapped. Or, _service is not a page of size 4 KiB. Or, iospace is not assigned to a PCI device.
+ +

Map

+

static inline int seL4_X86_Page_Map

+ +

Map a page into an address space or update the mapping attributes.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_Page_serviceCapability to the page being operated on.
seL4_CPtrvspaceCapability to the VSpace which will contain the mapping
seL4_WordvaddrVirtual address to map the page into.
seL4_CapRights_trightsRights for the mapping.
seL4_X86_VMAttributesattrVM attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_AlignmentErrorThe vaddr is not aligned to the page size of _service.
seL4_DeleteFirstA mapping already exists in vspace at vaddr.
seL4_FailedLookupThe vspace does not have a paging structure at the required level mapped at vaddr. Or, vspace is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is already mapped in an IOSpace.
seL4_InvalidArgumentThe _service is already mapped in vspace at a different virtual address. Or, vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not assigned to an ASID pool. Or, _service is already mapped in a different VSpace.
+ +

Description: Takes a VSpace capability, as an argument and installs a reference to the given Page in the lowest-level unmapped paging structure corresponding to the given address, or updates the mapping attributes if the page is already mapped at this address. If the required paging structures are not present this operation will fail, returning a seL4_FailedLookup error.

+ +

Unmap

+

static inline int seL4_X86_Page_Unmap

+ +

Unmap a page.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_Page_serviceCapability to the page being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Removes an existing mapping.

+

seL4_X86_PageDirectory

+ +

Get Status Bits

+

static inline seL4_X86_PageDirectory_GetStatusBits_t seL4_X86_PageDirectory_GetStatusBits

+ +

Retrieve the accessed and dirty bits of a page mapped into an address space.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_PageDirectory_serviceCapability to the page directory being operated on.Capability to the address space to query.
seL4_WordvaddrVirtual address of the page to query
+ +

Return value: A seL4_X86_PageDirectory_GetStatusBits_t structure.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe _service does not have a mapping at vaddr. Or, vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Map

+

static inline int seL4_X86_PageDirectory_Map

+ +

Map a page directory.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_PageDirectory_serviceCapability to the page directory being operated on.
seL4_CPtrvspaceCapability to the VSpace which will contain the mapping
seL4_WordvaddrVirtual address to map the page into.
seL4_X86_VMAttributesattrVM attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists for this level in vspace at vaddr.
seL4_FailedLookupThe vspace does not have a PDPT mapped at vaddr. Or, vspace is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not assigned to an ASID pool. Or, _service is already mapped in a VSpace.
+ +

Unmap

+

static inline int seL4_X86_PageDirectory_Unmap

+ +

Unmap a page directory.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_PageDirectory_serviceCapability to the page directory being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstA copy of the _service capability exists.
+ +

seL4_X86_PageTable

+ +

Map

+

static inline int seL4_X86_PageTable_Map

+ +

Map a page table into an address space.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_PageTable_serviceCapability to the page table being operated on.
seL4_CPtrvspaceCapability to the VSpace which will contain the mapping
seL4_WordvaddrVirtual address to map the page into.
seL4_X86_VMAttributesattrVM attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists for this level in vspace at vaddr.
seL4_FailedLookupThe vspace does not have a Page Directory mapped at vaddr. Or, vspace is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not assigned to an ASID pool. Or, _service is already mapped in a VSpace.
+ +

Description: Takes a PageDirectory capability as an argument, and installs a reference to the invoked PageTable in a specified slot in the PageDirectory.

+ +

Unmap

+

static inline int seL4_X86_PageTable_Unmap

+ +

Unmap a page table from its address space and zero it out.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_PageTable_serviceCapability to the page table being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstA copy of the _service capability exists.
+ +

Description: Removes the reference to the invoked PageTable from its containing PageDirectory.

+

seL4_X86_VCPU

+ +

Disable I/O Port

+

static inline int seL4_X86_VCPU_DisableIOPort

+ +

Disable I/O port range in privileged execution

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_VCPU_serviceVCPU object to operate on
seL4_WordlowStart of the I/O port range to disable
seL4_WordhighLast I/O port in the range to disable
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Disable a range of I/O ports for direct access by the execution mode in the VCPU.

+ +

Enable I/O Port

+

static inline int seL4_X86_VCPU_EnableIOPort

+ +

Enable I/O port range in guest execution

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_VCPU_serviceVCPU object to operate on
seL4_X86_IOPortioPortI/O port capability whose authority is being delegating
seL4_WordlowStart of the I/O port range to enable
seL4_WordhighLast I/O port in the range to enable
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service or ioPort is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe low or high IO port exceeds the range authorized by ioPort.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Enables a range of I/O ports for direct access by the execution mode in the VCPU. The requested port range must be a sub range of the provided I/O port capability. + This also establishes a link between the provided I/O port capability and the VCPU

+ +

Read VMCS

+

static inline seL4_X86_VCPU_ReadVMCS_t seL4_X86_VCPU_ReadVMCS

+ +

Read VMCS field from the hardware

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_VCPU_serviceVCPU object to operate on
seL4_WordfieldField to give to vmread instruction
+ +

Return value: A seL4_X86_VCPU_ReadVMCS_t struct that contains a seL4_Word value, which holds the return result of the vmread instruction, and int error.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, field is invalid or unsupported.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Thin wrapper around the vmread instruction that is performed on the VMCS region that is part of the VCPU object. After validating that a legal field is requested the value of vmread is returned directly in the result.

+ +

Set TCB

+

static inline int seL4_X86_VCPU_SetTCB

+ +

Bind TCB to VCPU

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_VCPU_serviceVCPU object to operate on
seL4_TCBtcbCPtr of the TCB to bind to
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service or tcb is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Configures the one-to-one binding of a VCPU and TCB, overwriting any previous binding in both.

+ +

Write Registers

+

static inline int seL4_X86_VCPU_WriteRegisters

+ +

Set guest mode registers to the fields of a given seL4_VCPUContext

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_VCPU_serviceVCPU object to operate on
seL4_VCPUContext *regsData structure containing the new register values.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Sets the guest mode registers, which is any registers not already part of the VMCS.

+ +

Write VMCS

+

static inline seL4_X86_VCPU_WriteVMCS_t seL4_X86_VCPU_WriteVMCS

+ +

Write VMCS field to the hardware

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_VCPU_serviceVCPU object to operate on
seL4_WordfieldField to give to vmwrite instruction
seL4_WordvalueValue to write using vmwrite instruction
+ +

Return value: A seL4_X86_VCPU_WriteVMCS_t struct that contains a seL4_Word written, which holds the final value written with the vmwrite instruction, and int error.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, field is invalid or unsupported.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Thin wrapper around the vmwrite instruction that is performed on the VMCS region that is part of the VCPU object. As well as validating that a legal field is requested, the value may be modified to ensure any bits that are fixed in the hardware are correct, and that any features required for kernel correctness are not disabled . + The final value written to the hardware is returned and can be compared to the input parameter to determine what bits the kernel changed.

+ +

IA32-Specific Object Methods

+ +

No methods.

+ +

x86_64-Specific Object Methods

+ +

seL4_X86_PDPT

+ +

Map

+

static inline int seL4_X86_PDPT_Map

+ +

Map a page directory page table.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_PDPT_serviceCapability to the PDPT being operated on.
seL4_X64_PML4pml4Capability to the VSpace which will contain the mapping.
seL4_WordvaddrVirtual address at which to map page.
seL4_X86_VMAttributesattrVM attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists for this level in vspace at vaddr.
seL4_FailedLookupThe pml4 is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service or pml4 is a CPtr to a capability of the wrong type. Or, pml4 is not assigned to an ASID pool. Or, _service is already mapped in a VSpace.
+ +

Unmap

+

static inline int seL4_X86_PDPT_Unmap

+ +

Unmap a page directory page table.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_PDPT_serviceCapability to the PDPT being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstA copy of the _service capability exists.
+ +

seL4_X86_VCPU

+ +

Read MSR

+

static inline seL4_X86_VCPU_ReadMSR_t seL4_X86_VCPU_ReadMSR

+ +

Read 64-bit specific MSR field from the hardware

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_VCPU_serviceVCPU object to operate on
seL4_WordfieldField to give to rdmsr instruction
+ +

Return value: A seL4_X86_VCPU_ReadMSR_t struct that contains a seL4_Word value, which holds the return result of the rdmsr instruction, and int error.

+ +

Description: Thin wrapper around the rdmsr instruction that is performed on specific, needed registers. Certain registers might simply be cached and restored later.

+ +

Write MSR

+

static inline seL4_X86_VCPU_WriteMSR_t seL4_X86_VCPU_WriteMSR

+ +

Write 64-bit specific MSR field to the hardware

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_X86_VCPU_serviceVCPU object to operate on
seL4_WordfieldField to give to wrsmr instruction
seL4_WordvalueValue to write using wrsmr instruction
+ +

Return value: A seL4_X86_VCPU_WriteMSR_t struct that contains a seL4_Word written, which holds the final value written with the wrmsr instruction, and int error.

+ +

Description: Thin wrapper around the wrmsr instruction that is performed on specific, needed registers. As well as validating that a legal field is requested, the value may be modified to ensure any bits that are fixed in the hardware are correct, and that any features required for kernel correctness are not disabled . + The final value written to the hardware is returned and can be compared to the input parameter to determine what bits the kernel changed.

+ +

General ARM Object Methods

+ +

seL4_ARM_ASIDControl

+ +

Make Pool

+

static inline int seL4_ARM_ASIDControl_MakePool

+ +

Create an ASID Pool.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_ASIDControl_serviceThe master ASIDControl capability being operated on.
seL4_UntypeduntypedCapability to an untyped memory object that will become the pool. Must be 4K bytes.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability. Or, there are no more ASID pools available.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or untyped is a CPtr to a capability of the wrong type. Or, untyped is not the exact size of an ASID pool object. Or, untyped is a device untyped .
seL4_RangeErrorThe depth is invalid .
seL4_RevokeFirstThe untyped has been used to retype an object. Or, a copy of the untyped capability exists.
+ +

Description: Together with a capability to Untyped Memory, which is passed as an argument, create an ASID Pool. The untyped capability must represent a 4K memory object. This will create an ASID pool with enough space for 1024 VSpaces.

+

seL4_ARM_ASIDPool

+ +

ASID Pool Assign

+

static inline int seL4_ARM_ASIDPool_Assign

+ +

Assign an ASID Pool.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_ASIDPool_serviceThe ASID pool which is being assigned to. Must not be full. Each ASID pool can contain 1024 entries.
seL4_CPtrvspaceThe VSpace that is being assigned to an ASID pool. Must not already be assigned to an ASID pool.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThere are no more ASIDs available in _service.
seL4_FailedLookupThe ASID pool of _service is no longer assigned.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is already assigned to an ASID pool.
+ +

Description: Assigns an ASID to the VSpace passed in as an argument.

+

seL4_ARM_CB

+ +

Assign VSpace

+

static inline int seL4_ARM_CB_AssignVspace

+ +

Assigning a VSpace to a context bank.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_CB_serviceA CB capability. This gives you the authority to make this call.
seL4_CPtrvspaceThe VSpace that is being assigned to a context bank. Must already has an assigned ASID.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe _service is already assigned to a VSpace.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not assigned to an ASID pool.
+ +

CB Clear Fault

+

static inline int seL4_ARM_CB_CBClearFault

+ +

Clear the fault status of the context bank.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_CB_serviceA CB capability. This gives you the authority to make this call.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

CB Get Fault

+

static inline seL4_ARM_CB_CBGetFault_t seL4_ARM_CB_CBGetFault

+ +

Get the fault status of the context bank.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_CB_serviceA CB capability. This gives you the authority to make this call.
+ +

Return value: A seL4_ARM_SMMU_CB_GetFault_t struct that contains a seL4_Word status, which holds the fault status of the context bank, seL4_Word address, which holds the faulty address, and int error.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

TLB Invalidate

+

static inline int seL4_ARM_CB_TLBInvalidate

+ +

Invalidating TLB entries used by the current ASID in this context bank.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_CB_serviceA CB capability. This gives you the authority to make this call.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to a VSpace.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Unassign VSpace

+

static inline int seL4_ARM_CB_UnassignVspace

+ +

Unassigning a VSpace to a context bank.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_CB_serviceA CB capability. This gives you the authority to make this call.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to a VSpace.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_ARM_CBControl

+ +

Get CB

+

static inline int seL4_ARM_CBControl_GetCB

+ +

Create a CB capability.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_CBControl_serviceA CBControl capability. This gives you the authority to make this call.
seL4_WordcbThe CB that you want this capability to manage.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe depth is invalid . Or, cb is invalid.
seL4_RevokeFirstA CB capability for cb has already been created.
+ +

TLB Invalidate All

+

static inline int seL4_ARM_CBControl_TLBInvalidateAll

+ +

Invalidate all TLB entries.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_CBControl_serviceA CBControl capability. This gives you the authority to make this call.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_ARM_IOPageTable

+ +

Map

+

static inline int seL4_ARM_IOPageTable_Map

+ +

Map an IO page table into an IOSpace.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_IOPageTable_serviceCapability to the I/O page table being operated on.
seL4_ARM_IOSpaceiospaceThe IOSpace to map the page table into.
seL4_WordioaddrVirtual address at which to map the page table.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstAll required page tables are already mapped in iospace at ioaddr.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or iospace is a CPtr to a capability of the wrong type. Or, _service is already mapped in an IOSpace.
+ +

Unmap

+

static inline int seL4_ARM_IOPageTable_Unmap

+ +

Unmap an IO page table from an IOSpace.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_IOPageTable_serviceCapability to the I/O page table being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_ARM_Page

+ +

Clean Data

+

static inline int seL4_ARM_Page_Clean_Data

+ +

Cleans the data cache out to RAM. The start and end are relative to the page being serviced.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_Page_serviceCapability to the page being operated on.
seL4_Wordstart_offsetThe offset, relative to the start of the page inclusive.
seL4_Wordend_offsetThe offset, relative to the start of the page exclusive.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe VSpace of _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not mapped in a VSpace. Or, if hypervisor support is configured, the requested range overlaps the kernel physical address range.
seL4_InvalidArgumentThe start_offset is greater than or equal to end_offset. Or, start_offset or end_offset exceeds the page size of _service.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Clean and Invalidate Data

+

static inline int seL4_ARM_Page_CleanInvalidate_Data

+ +

Clean and invalidates the cache range within the given page. The range will be flushed out to RAM. +The start and end offsets are relative to the page being serviced.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_Page_serviceCapability to the page being operated on.
seL4_Wordstart_offsetThe offset, relative to the start of the page inclusive.
seL4_Wordend_offsetThe offset, relative to the start of the page exclusive.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe VSpace of _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not mapped in a VSpace. Or, if hypervisor support is configured, the requested range overlaps the kernel physical address range.
seL4_InvalidArgumentThe start_offset is greater than or equal to end_offset. Or, start_offset or end_offset exceeds the page size of _service.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Get Address

+

static inline seL4_ARM_Page_GetAddress_t seL4_ARM_Page_GetAddress

+ +

Get the physical address of the underlying frame.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_Page_serviceCapability to the page being operated on.
+ +

Return value: A seL4_ARM_Page_GetAddress_t struct that contains a seL4_Word paddr, which holds the physical address of the page, and int error.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Invalidate Data

+

static inline int seL4_ARM_Page_Invalidate_Data

+ +

Invalidates the cache range within the given page. The start and end offsets are relative to the page being serviced +and should be aligned to a cache line boundary where possible. +An additional clean is performed on the outer cache lines if the start and end are +not aligned, to clean out the bytes between the requested and the cache line boundary.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_Page_serviceCapability to the page being operated on.
seL4_Wordstart_offsetThe offset, relative to the start of the page inclusive.
seL4_Wordend_offsetThe offset, relative to the start of the page exclusive.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe VSpace of _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not mapped in a VSpace. Or, if hypervisor support is configured, the requested range overlaps the kernel physical address range.
seL4_InvalidArgumentThe start_offset is greater than or equal to end_offset. Or, start_offset or end_offset exceeds the page size of _service.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Map I/O

+

static inline int seL4_ARM_Page_MapIO

+ +

Map a page into an IOSpace.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_Page_serviceCapability to the page being operated on.
seL4_ARM_IOSpaceiospaceThe IOSpace to map the page into.
seL4_CapRights_trightsRights for the mapping.
seL4_WordioaddrVirtual address at which to map page.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists in iospace at ioaddr.
seL4_FailedLookupThe iospace does not have a sufficient number of IO Page Tables mapped at ioaddr.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentNo rights were specified in rights. Or, the rights in the _service capability do not include rights.
seL4_InvalidCapabilityThe _service or iospace is a CPtr to a capability of the wrong type. Or, _service is already mapped. Or, _service is not a page of size 4 KiB.
+ +

Map

+

static inline int seL4_ARM_Page_Map

+ +

Map a page into an address space or update the mapping attributes.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_Page_serviceCapability to the page being operated on.
seL4_CPtrvspaceCapability to the VSpace which will contain the mapping. Must be assigned to an ASID pool.
seL4_WordvaddrVirtual address to map the page into.
seL4_CapRights_trightsRights for the mapping.
seL4_ARM_VMAttributesattrVM Attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_AlignmentErrorThe vaddr is not aligned to the page size of _service.
seL4_DeleteFirstA mapping already exists in vspace at vaddr.
seL4_FailedLookupThe vspace does not have a paging structure at the required level mapped at vaddr. Or, vspace is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe _service is already mapped in vspace at a different virtual address. Or, vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not assigned to an ASID pool. Or, _service is already mapped in a different VSpace.
+ +

Description: Takes a VSpace capability as an argument and installs a reference to the given Page in the lowest-level unmapped paging structure corresponding to the given address, or updates the mapping attributes if the page is already mapped at this address. The page must not already be mapped through this capability in a different VSpace or at a different address; the page may be mapped in multiple VSpaces by copying the capability.

+ +

Unify Instruction

+

static inline int seL4_ARM_Page_Unify_Instruction

+ +

Unify Instruction Cache. Cleans data lines to point of unification, invalidate +corresponding instruction lines to point of unification, then invalidates branch +predictors. The start and end offsets are relative to the page being +serviced.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_Page_serviceCapability to the page being operated on.
seL4_Wordstart_offsetThe offset, relative to the start of the page inclusive.
seL4_Wordend_offsetThe offset, relative to the start of the page exclusive.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe VSpace of _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not mapped in a VSpace. Or, if hypervisor support is configured, the requested range overlaps the kernel physical address range.
seL4_InvalidArgumentThe start_offset is greater than or equal to end_offset. Or, start_offset or end_offset exceeds the page size of _service.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Unmap

+

static inline int seL4_ARM_Page_Unmap

+ +

Unmap a page.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_Page_serviceCapability to the page being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Removes an existing mapping.

+

seL4_ARM_PageTable

+ +

Map

+

static inline int seL4_ARM_PageTable_Map

+ +

Map a page table into an address space.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_PageTable_serviceCapability to the page table being operated on.
seL4_CPtrvspaceCapability to the VSpace which will contain the mapping. Must be assigned to an ASID pool.
seL4_WordvaddrVirtual address to map the page into.
seL4_ARM_VMAttributesattrVM Attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA mapping already exists for this level in vspace at vaddr.
seL4_FailedLookupOn aarch64, vspace does not have a Page Directory mapped at vaddr. Or, vspace is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not assigned to an ASID pool. Or, _service is already mapped in a VSpace.
+ +

Description: Takes a VSpace capability as an argument, and installs a reference to the page table in the VSpace at the provided virtual address.

+ +

Unmap

+

static inline int seL4_ARM_PageTable_Unmap

+ +

Unmap a page table from its Page Directory and zero it out.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_PageTable_serviceCapability to the page table being operated on.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstA copy of the _service capability exists.
+ +

Description: Removes the reference to the invoked Page Table from its containing Page Directory.

+

seL4_ARM_SID

+ +

Bind CB

+

static inline int seL4_ARM_SID_BindCB

+ +

Binding a context bank to a stream ID.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_SID_serviceA SID capability. This gives you the authority to make this call.
seL4_CPtrcbThe CB that is being binded to a stream ID. Must already has an assigned vspace.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe _service is already bound to a context bank.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or cb is a CPtr to a capability of the wrong type. Or, cb is not assigned to a VSpace.
+ +

Unbind CB

+

static inline int seL4_ARM_SID_UnbindCB

+ +

Unbinding a context bank from a stream ID.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_SID_serviceA SID capability. This gives you the authority to make this call.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, _service is not bound to a context block.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

seL4_ARM_SIDControl

+ +

Clear Fault

+

static inline int seL4_ARM_SIDControl_ClearFault

+ +

Clear the fault status of the SMMU.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_SIDControl_serviceA SIDControl capability. This gives you the authority to make this call.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Get Fault

+

static inline seL4_ARM_SIDControl_GetFault_t seL4_ARM_SIDControl_GetFault

+ +

Get the fault status of the SMMU.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_SIDControl_serviceA SIDControl capability. This gives you the authority to make this call.
+ +

Return value: A seL4_ARM_SMMU_GetFault_t struct that contains a seL4_Word status, which holds the global fault status of the SMMU, seL4_Word syndrome_0, which holds the global fault syndrome 0 of the SMMU, seL4_Word syndrome_1, which holds the global fault syndrome 1 of the SMMU, and int error.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Get SID

+

static inline int seL4_ARM_SIDControl_GetSID

+ +

Create a SID capability.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_SIDControl_serviceA SIDControl capability. This gives you the authority to make this call.
seL4_WordsidThe SID that you want this capability to manage.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe depth is invalid . Or, sid is invalid.
seL4_RevokeFirstAn SID capability for sid has already been created.
+ +

seL4_ARM_VCPU

+ +

Acknowledge Virtual PPI IRQ

+

static inline int seL4_ARM_VCPU_AckVPPI

+ +

Acknowledge a PPI IRQ previously forwarded from a VPPIEvent fault.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VCPU_serviceCapability to the VCPU being operated on.
seL4_Wordirqirq to ack.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe irq is invalid.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Acknowledge and unmask the PPI interrupt so that further interrupts can be forwarded through VPPIEvent faults.

+ +

Inject IRQ

+

static inline int seL4_ARM_VCPU_InjectIRQ

+ +

Inject an IRQ to a virtual CPU.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VCPU_serviceCapability to the VCPU being operated on.
seL4_Uint16virqVirtual IRQ ID
seL4_Uint8priorityPriority of the IRQ to be injected
seL4_Uint8groupIRQ group
seL4_Uint8indexVGIC list register
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe index is in use and not yet handled by the guest.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe virq, priority, group, or index is invalid.
+ +

Description: Used to queue IRQs towards the VCPU. Writes ICH_LRn_EL2 for GICv3 or LRn for GICv2, where n is determined by index. The list register becomes available again when the guest acknowledges the injected interrupt.

+ +

Read Registers

+

static inline seL4_ARM_VCPU_ReadRegs_t seL4_ARM_VCPU_ReadRegs

+ +

Read a virtual CPU register.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VCPU_serviceCapability to the VCPU being operated on.
seL4_VCPURegfieldRegister to read from a VCPU
+ +

Return value: A seL4_ARM_VCPU_ReadRegs_t struct that contains a seL4_Word value, which holds the value of the system register, and int error, which will be non-zero when an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe field is invalid.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Provides a way to read EL1 system registers, as well as VMPIDR_EL2.

+ +

Set TCB

+

static inline int seL4_ARM_VCPU_SetTCB

+ +

Bind a TCB to a virtual CPU.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VCPU_serviceCapability to the VCPU being operated on.
seL4_TCBtcbCapability to TCB to bind to a virtual CPU
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service or tcb is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: There is a 1:1 relationship between a virtual CPU and a TCB. If either (or both) of them is associated with another one, they will be dissociated, and then associated to the ones called in this system calls.

+ +

Write Registers

+

static inline int seL4_ARM_VCPU_WriteRegs

+ +

Write a virtual CPU register.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VCPU_serviceCapability to the VCPU being operated on.
seL4_VCPURegfieldRegister ID to write to a VCPU
seL4_WordvalueValue to be written to the VCPU register
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe field is invalid.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Provides a way to write EL1 system registers, as well as VMPIDR_EL2.

+

seL4_IRQControl

+ +

Get IRQ Handler (SMP)

+

static inline int seL4_IRQControl_GetTriggerCore

+ +

Create an IRQ handler capability and specify the trigger method (edge or level) and the target core.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQControl_serviceAn IRQControl capability. This gives you the authority to make this call.
seL4_WordirqThe IRQ that you want this capability to handle.
seL4_WordtriggerIndicates whether this IRQ is edge (1) or level (0) triggered.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
seL4_WordtargetIndicates the target core ID to which this IRQ will be sent.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, SMP support is not enabled.
seL4_InvalidArgumentThe target is invalid.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe depth is invalid .
seL4_RevokeFirstAn IRQ handler capability for irq has already been created.
+ +

Get IRQ Handler with Trigger Type

+

static inline int seL4_IRQControl_GetTrigger

+ +

Create an IRQ handler capability and specify the trigger method (edge or level).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQControl_serviceAn IRQControl capability. This gives you the authority to make this call.
seL4_WordirqThe IRQ that you want this capability to handle.
seL4_WordtriggerIndicates whether this IRQ is edge (1) or level (0) triggered.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the platform does not support setting the IRQ trigger.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe irq is invalid. Or, depth is invalid .
seL4_RevokeFirstAn IRQ handler capability for irq has already been created.
+ +

IssueSGISignal

+

static inline int seL4_IRQControl_IssueSGISignal

+ +

Create a software generated interrupt (SGI) signal capability.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQControl_serviceAn IRQControl capability. This gives you the authority to make this call.
seL4_WordirqThe SGI INTID (0-15) that can be signalled.
seL4_WordtargetThe node ID that will be targeted. 0-7 for GICv2 and the affinity value for GICv3 (concatenation of Aff3+Aff2+Aff1+Aff0 from MPIDR). Targets within that range that are not supported by thde hardware will be not be rejected. For example, on a GICv2 board with 4 CPUs, the capability for target 5 can be created. The result of later signalling this target depends on the hardware implementation.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of dest_index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, SGIs are not supported on this platform.
seL4_InvalidArgumentThe SGI target is not supported on this GIC. Note that this only checks architectural limits, not the presence of the target core on the current board.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe value of irq or target is out of range. Or, depth is invalid .
+ +

Description: Create an SGISignal capability and place it in the specific target CSpace slot. The capability can be used to raise an SGI with a specific ID on a specific target core. Currently this feature is supported on GICv2 and GICv3 hardware. Only available on non-SMP configurations. + The resulting capability can be invoked like a notification capability that supports only signal/send. SGIs can be received by IRQ notification objects on the target core like other IRQs. See also autoref[sec:interrupts]. + Note that the kernel only checks architectural limits for SGI IRQ id and target. It does not know whether the corresponding target core exists. Depending on hardware implementation, signalling a non-existent target may create an unrecoverable SError. This means it is the responsibility of the developer to not issue capabilities for targets that do not exist.

+ +

Aarch32-Specific Object Methods

+ +

seL4_ARM_PageDirectory

+ +

Clean Data

+

static inline int seL4_ARM_PageDirectory_Clean_Data

+ +

Clean cached pages within a page directory

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_PageDirectory_serviceCapability to the page directory being operated on.
seL4_WordstartStart address
seL4_WordendEnd address
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, start or end is in the kernel virtual address range.
seL4_InvalidArgumentThe start is greater than or equal to end.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to an ASID pool.
seL4_RangeErrorThe specified range crosses a page boundary.
+ +

Clean and Invalidate Data

+

static inline int seL4_ARM_PageDirectory_CleanInvalidate_Data

+ +

Clean and invalidate cached pages within a page directory

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_PageDirectory_serviceCapability to the page directory being operated on.
seL4_WordstartStart address
seL4_WordendEnd address
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, start or end is in the kernel virtual address range.
seL4_InvalidArgumentThe start is greater than or equal to end.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to an ASID pool.
seL4_RangeErrorThe specified range crosses a page boundary.
+ +

Invalidate Data

+

static inline int seL4_ARM_PageDirectory_Invalidate_Data

+ +

Invalidate cached pages within a page directory

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_PageDirectory_serviceCapability to the page directory being operated on.
seL4_WordstartStart address
seL4_WordendEnd address
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, start or end is in the kernel virtual address range.
seL4_InvalidArgumentThe start is greater than or equal to end.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to an ASID pool.
seL4_RangeErrorThe specified range crosses a page boundary.
+ +

Unify Instruction

+

static inline int seL4_ARM_PageDirectory_Unify_Instruction

+ +

Clean and invalidate cached instruction pages to point of unification

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_PageDirectory_serviceCapability to the page directory being operated on.
seL4_WordstartStart address
seL4_WordendEnd address
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, start or end is in the kernel virtual address range.
seL4_InvalidArgumentThe start is greater than or equal to end.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to an ASID pool.
seL4_RangeErrorThe specified range crosses a page boundary.
+ +

Aarch64-Specific Object Methods

+ +

seL4_ARM_SMC

+ +

SMC Call

+

static inline int seL4_ARM_SMC_Call

+ +

Tell the kernel to make the real SMC call.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_SMC_serviceCapability to allow threads to make Secure Monitor Calls.
seL4_ARM_SMCContext *smc_argsThe structure that has the provided arguments.
seL4_ARM_SMCContext *smc_responseThe structure to capture the responses.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ +

Description: Takes x0-x7 as arguments to an SMC call which are defined as a seL4_ARM_SMCContext struct. The kernel makes the SMC call and then returns the results as a new seL4_ARM_SMCContext.

+

seL4_ARM_VSpace

+ +

Clean Data

+

static inline int seL4_ARM_VSpace_Clean_Data

+ +

Clean cached pages within a top level translation table

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VSpace_serviceCapability to the top level translation table being operated on.
seL4_WordstartStart address
seL4_WordendEnd address
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, end is in the kernel virtual address range.
seL4_InvalidArgumentThe start is greater than or equal to end.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to an ASID pool.
seL4_RangeErrorThe specified range crosses a page boundary.
+ +

Clean and Invalidate Data

+

static inline int seL4_ARM_VSpace_CleanInvalidate_Data

+ +

Clean and invalidate cached pages within a top level translation table

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VSpace_serviceCapability to the top level translation table being operated on.
seL4_WordstartStart address
seL4_WordendEnd address
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, end is in the kernel virtual address range.
seL4_InvalidArgumentThe start is greater than or equal to end.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to an ASID pool.
seL4_RangeErrorThe specified range crosses a page boundary.
+ +

Invalidate Data

+

static inline int seL4_ARM_VSpace_Invalidate_Data

+ +

Invalidate cached pages within a top level translation table

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VSpace_serviceCapability to the top level translation table being operated on.
seL4_WordstartStart address
seL4_WordendEnd address
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, end is in the kernel virtual address range.
seL4_InvalidArgumentThe start is greater than or equal to end.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to an ASID pool.
seL4_RangeErrorThe specified range crosses a page boundary.
+ +

Unify Instruction

+

static inline int seL4_ARM_VSpace_Unify_Instruction

+ +

Clean and invalidate cached instruction pages to point of unification

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_ARM_VSpace_serviceCapability to the top level translation table being operated on.
seL4_WordstartStart address
seL4_WordendEnd address
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_FailedLookupThe _service is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, end is in the kernel virtual address range.
seL4_InvalidArgumentThe start is greater than or equal to end.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type. Or, _service is not assigned to an ASID pool.
seL4_RangeErrorThe specified range crosses a page boundary.
+ +

RISCV-Specific Object Methods

+ +

seL4_IRQControl

+ +

Get IRQ Handler with Trigger Type

+

static inline int seL4_IRQControl_GetTrigger

+ +

Create an IRQ handler capability and specify the trigger method (edge or level).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_IRQControl_serviceAn IRQControl capability. This gives you the authority to make this call.
seL4_WordirqThe IRQ that you want this capability to handle.
seL4_WordtriggerIndicates whether this IRQ is edge (1) or level (0) triggered.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type. Or, the platform does not support setting the IRQ trigger.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RangeErrorThe irq is invalid. Or, depth is invalid .
seL4_RevokeFirstAn IRQ handler capability for irq has already been created.
+ +

seL4_RISCV_ASIDControl

+ +

Make Pool

+

static inline int seL4_RISCV_ASIDControl_MakePool

+ +

Create an ASID Pool.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_RISCV_ASIDControl_serviceThe master ASIDControl capability to invoke.
seL4_UntypeduntypedCapability to an untyped memory object that will become the pool. Must be 4K bytes.
seL4_CNoderootCPtr to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize.
seL4_WordindexCPtr to the destination slot. Resolved from the root of the destination CSpace.
seL4_Uint8depthNumber of bits of index to resolve to find the destination slot.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThe destination slot contains a capability. Or, there are no more ASID pools available.
seL4_FailedLookupThe index or depth is invalid . Or, root is a CPtr to a capability of the wrong type.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or untyped is a CPtr to a capability of the wrong type. Or, untyped is not the exact size of an ASID pool object. Or, untyped is a device untyped .
seL4_RangeErrorThe depth is invalid .
seL4_RevokeFirstThe untyped has been used to retype an object. Or, a copy of the untyped capability exists.
+ +

Description: Together with a capability to Untyped Memory, which is passed as an argument, create an ASID Pool. The untyped capability must represent a 4K memory object. This will create an ASID pool with enough space for 1024 VSpaces.

+

seL4_RISCV_ASIDPool

+ +

Assign

+

static inline int seL4_RISCV_ASIDPool_Assign

+ +

Assign an ASID Pool.

+ + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_RISCV_ASIDPool_serviceThe ASID Pool capability to invoke, which must be to an ASID pool that is not full.
seL4_CPtrvspaceThe top-level PageTable that is being assigned to an ASID pool. Must not already be assigned to an ASID pool.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstThere are no more ASIDs available in _service.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is already assigned to an ASID pool. Or, vspace is mapped in a VSpace.
+ +

Description: Assigns an ASID to the VSpace passed in as an argument.

+

seL4_RISCV_Page

+ +

Get Address

+

static inline seL4_RISCV_Page_GetAddress_t seL4_RISCV_Page_GetAddress

+ +

Get the physical address of a page.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_RISCV_Page_serviceCapability to the page to invoke.
+ +

Return value: A seL4_RISCV_Page_GetAddress_t struct that contains a seL4_Word paddr, which holds the physical address of the page, and int error.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Map

+

static inline int seL4_RISCV_Page_Map

+ +

Map a page into a page table.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_RISCV_Page_serviceCapability to the page to invoke.
seL4_RISCV_PageTablevspaceVSpace to map the page into.
seL4_WordvaddrVirtual address at which to map the page.
seL4_CapRights_trightsRights for the mapping.
seL4_RISCV_VMAttributesattrVM Attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_AlignmentErrorThe vaddr is not aligned to the page size of _service.
seL4_DeleteFirstA mapping already exists in vspace at vaddr.
seL4_FailedLookupThe vspace does not have a paging structure at the required level mapped at vaddr. Or, vspace is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe _service is already mapped in vspace at a different virtual address. Or, vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not the root of a VSpace. Or, vspace is not assigned to an ASID pool. Or, _service is already mapped in a different VSpace.
+ +

Description: Takes a VSpace, or top-level Page Table, capability as an argument and installs a reference to the given Page in the page table slot corresponding to the given address. If a page is already mapped at the same virtual address, update the mapping attributes. If the required paging structures are not present this operation will fail, returning a seL4_FailedLookup error.

+ +

Unmap

+

static inline int seL4_RISCV_Page_Unmap

+ +

Unmap a page.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_RISCV_Page_serviceCapability to the page to invoke.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
+ +

Description: Removes an existing mapping.

+

seL4_RISCV_PageTable

+ +

Map

+

static inline int seL4_RISCV_PageTable_Map

+ +

Map a page table at a specific virtual address.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_RISCV_PageTable_serviceCapability to the page table to invoke.
seL4_RISCV_PageTablevspaceVSpace to map the lower-level page table into.
seL4_WordvaddrVirtual address at which to map the page table.
seL4_RISCV_VMAttributesattrVM Attributes for the mapping.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_DeleteFirstA page is mapped in vspace at vaddr. Or, all required page tables are already mapped in vspace at vaddr.
seL4_FailedLookupThe vspace is not assigned to an ASID pool.
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidArgumentThe vaddr is in the kernel virtual address range.
seL4_InvalidCapabilityThe _service or vspace is a CPtr to a capability of the wrong type. Or, vspace is not assigned to an ASID pool. Or, _service is already mapped in a VSpace.
+ +

Description: Starting from the VSpace, map the page table object at any unpopulated level for the provided virtual address. If all paging structures and mappings are present for this virtual address, return an seL4_DeleteFirst error.

+ +

Unmap

+

static inline int seL4_RISCV_PageTable_Unmap

+ +

Unmap a page table.

+ + + + + + + + + + + + + + + + +
TypeNameDescription
seL4_RISCV_PageTable_serviceCapability to the page table to invoke.
+ +

Return value: A return value of 0 indicates success. A non-zero value indicates that an error occurred.

+ + + + + + + + + + + + + + + + + + + + + + +
Error CodePossible Cause
seL4_IllegalOperationThe _service is a CPtr to a capability of the wrong type.
seL4_InvalidCapabilityThe _service is a CPtr to a capability of the wrong type.
seL4_RevokeFirstThe _service is the root of a VSpace. Or, a copy of the _service capability exists.
+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/sel4/api-doc.md b/projects/sel4/api-doc.md deleted file mode 100644 index 0ba91c684cb..00000000000 --- a/projects/sel4/api-doc.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -layout: api -toc: true -redirect_from: - - /ApiDoc -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4 API Reference - -This is the C API reference for the seL4 kernel, available in the library -`libsel4`. - -## General System Calls - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/GeneralSystemCalls.md %} - -## Debugging System Calls - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/DebuggingSystemCalls.md %} - -## Benchmarking System Calls - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/BenchmarkingSystemCalls.md %} - -## X86 System Calls - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/X86SystemCalls.md %} - -## Architecture-Independent Object Methods - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/ObjectApi.md %} - -## General x86 Object Methods - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/ObjectApiX86.md %} - -## IA32-Specific Object Methods - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/ObjectApiIa32.md %} - -## x86_64-Specific Object Methods - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/ObjectApiX64.md %} - -## General ARM Object Methods - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/ObjectApiArm.md %} - -## Aarch32-Specific Object Methods - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/ObjectApiAarch32.md %} - -## Aarch64-Specific Object Methods - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/ObjectApiAarch64.md %} - -## RISCV-Specific Object Methods - -{% include_absolute _repos/sel4/sel4/manual/generated_markdown/ObjectApiRISCV.md %} diff --git a/projects/sel4/bfgen.html b/projects/sel4/bfgen.html new file mode 100644 index 00000000000..8785676a17e --- /dev/null +++ b/projects/sel4/bfgen.html @@ -0,0 +1,1525 @@ + + + + + + + The seL4 Bitfield Generator | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

The seL4 Bitfield Generator

+ +

The seL4 kernel code and the libsel4 library use the so-called bitfield +generator to automatically produce code and formal proofs for tagged unions and +structs of bitfields from a higher-level specification.

+ +

The code for this tool is available in the seL4 repository in the tools +directory. This page contains the manual of the bitfield generator. The manual +sources are also available for the tools directory.

+ + + +

Bitfield Generator Manual

+ +

Introduction

+ +

The tool bitfield_gen.py in the seL4/tools/ directory generates bitfield +accessor code in C with formal specifications and proofs in Isabelle/HOL.

+ +

It takes specifications of bitfield layouts in memory such as the following

+ +
block VMFault {
+    field     address           32
+
+    field     FSR               5
+    padding                     7
+    field     instructionFault  1
+    padding                     15
+    field     seL4_FaultType    4
+}
+
+ +

and generates a C struct with constructor and getter/setter functions with +call-by-value and call-by-pointer semantics. It also, separately, generates a +corresponding data type definition in Isabelle/HOL with corresponding functions +in HOL for that data type, as well as proofs that the generated C code correctly +implements these functions. This includes absence of undefined behaviour in C.

+ +

The purpose of the tool is to provide bit-level access to structures in memory +with precise, deterministic and reliable layout semantics, with proofs of +correctness, and without the need for manual masking and shifting operations. +The C standard leaves C bitfields too underspecified to be fit for that purpose.

+ +

In addition to basic blocks of bitfields such as above, the tool +supports tagged unions and various layout options for these +blocks.

+ +

Bit Field Generator by Example

+ +

This section walks through the features of the bitfield specification languages +by example. The full syntax is described in the next +section for reference.

+ +

Blocks

+ +

The basic concepts of the specification languages are blocks which contain a +list of fields. The example used in the introduction declares a block with +name VMFault, which contains four fields and two padding entries:

+ +
block VMFault {
+    field     address           32
+
+    field     FSR               5
+    padding                     7
+    field     instructionFault  1
+    padding                     15
+    field     seL4_FaultType    4
+}
+
+ +

This will generate a type VMFault_t in C. Assuming that the word size of the +underlying architecture is 32 bits, this VMFault_t type will have a size of +two machine words. The sizes of the content and padding fields in a block must +add up to a multiple of the machine word size.

+ +

The bits in the block are laid out in memory in the order they are mentioned in +the specification. That is, the left-most 32 bits (i.e. bits 63 to 32) of +VMFault will correspond to the address field, the next 5 bits to FSR, the +next 7 bits are inaccessible padding which is set to 0 on creation of the +bitfield, then one bit for instructionFault, 15 bits of padding, and finally 4 +bits (bits 0 to 3 of the entire type) for seL4_FaultType.

+ +

The following diagram corresponds to the block specification above.

+ +
   │------------------------  address  ----------------------------│
+   ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
+   │                                                               │ ..
+   └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
+   63                                                             32
+
+                     instruction fault                  seL4_FaultType
+   │-- FSR --│             │-|                             │-------|
+   ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
+.. │         │             │ │                             │       │
+   └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
+    31      27              19                              3     0
+
+ +

For creating new values of the type VMFault, the generator will provide a +function VMFault that takes an argument of the word size of the machine for +the value of each field – for the example above, this is uint32_t

+ +
VMFault_t VMFault(uint32_t address, uint32_t FSR, uint32_t instructionFault,
+                  uint32_t seL4_FaultType);
+
+ +

Values that do not fit in the bit size of the target field will be cut off +accordingly, i.e., as if using val & mask(size).

+ +

To read the value of each field, the generator will provide the following +functions:

+ +
uint32_t VMFault_get_address(VMFault_t vm_fault);
+uint32_t VMFault_get_FSR(VMFault_t vm_fault);
+uint32_t VMFault_get_instructionFault(VMFault_t vm_fault);
+uint32_t VMFault_get_seL4_FaultType(VMFault_t vm_fault);
+
+ +

For setting one of the fields in an existing value of type VMFault_t:

+ +
VMFault_t VMFault_set_address(VMFault_t vm_fault, uint32_t address);
+VMFault_t VMFault_set_FSR(VMFault_t vm_fault, uint32_t FSR);
+VMFault_t VMFault_set_instructionFault(VMFault_t vm_fault, uint32_t instructionFault);
+VMFault_t VMFault_set_seL4_FaultType(VMFault_t vm_fault, uint32_t seL4_FaultType);
+
+ +

All of the above (constructor, getter, setter) are pure functions without side +effects or dependency on global state. They do contain assert statements that +are in effect in debug configurations. The generator declares all of them as +static inline CONST to enable corresponding compiler optimisations.

+ +

Often we expect such bitfields to be accessed via pointers, e.g. as part of a +buffer or a larger struct in memory or for instance a page table. Therefore the +generator also produces getter/setter functions with pointer access:

+ +
uint32_t VMFault_ptr_get_address(VMFault_t *vm_fault);
+uint32_t VMFault_ptr_get_FSR(VMFault_t *vm_fault);
+uint32_t VMFault_ptr_get_instructionFault(VMFault_t *vm_fault);
+uint32_t VMFault_ptr_get_seL4_FaultType(VMFault_t *vm_fault);
+
+ +

These are declared PURE, but not CONST, since they depend on global state.

+ +

The pointer set functions are:

+ +
void VMFault_set_address(VMFault_t *vm_fault, uint32_t address);
+void VMFault_set_FSR(VMFault_t *vm_fault, uint32_t FSR);
+void VMFault_set_instructionFault(VMFault_t *vm_fault, uint32_t instructionFault);
+void VMFault_set_seL4_FaultType(VMFault_t *vm_fault, uint32_t seL4_FaultType);
+
+ +

These are neither PURE nor CONST, but still declared as static inline.

+ +
+

Note that the generator has a command line option --prune to skip functions +that are not used, and the seL4 build system makes use of that option. That +means, not necessarily all of the combinations above will appear in the +generated files for seL4, only the ones that are actually used in the rest of +the code.

+
+ +

Expressions

+ +

All positions in the specification that allow numbers also allow basic +arithmetic integer expressions with +, -, *, /, and %. The commands +field, padding, field_high, and field_ptr also allow the constants +word_size and canonical_size. word_size stands for the number of bits in a +word, and canonical_size for the number of canonical bits in a pointer, both +according most recent base declaration (see also Architecture Parameters).

+ +

For example, the VMFault example from Section Blocks could have +been written as follows, assuming a base 32 definition for `word_size.

+ +
block VMFault {
+    field     address           word_size
+
+    field     FSR               5
+    padding                     7
+    field     instructionFault  1
+    padding                     word_size - (5 + 7 + 1) - 4
+    field     seL4_FaultType    4
+}
+
+ +

Field High

+ +

The usual access patterns for fields is that if we provide e.g. a value of 5 to +a setter function, we expect a corresponding 8-bit field to be set to the bit +pattern 0000 0101.

+ +

In general, on a 32-bit architecture, we are providing a 32-bit value to store +in an n-bit field. One way of looking at this is that we know the top 32-n bits +of the value are always 0.

+ +

Sometimes we instead know that the bottom n bits of the value we provide are

+
    +
  1. This can happen for instance when we want to store an address that is always +aligned to a page boundary, as it would in a page table entry. This means we are +interested in the high bits of the address. The field_high tag allows us to +store only the significant high bits of such addresses.
    2. +
+ +

For instance the base pointer stored in a page table cap in seL4 for 32-bit +RISC-V is such a case:

+ +
block page_table_cap {
+    field       capPTMappedASID     9
+    field_high  capPTBasePtr        20
+    padding                         3
+
+    padding                         7
+    field       capPTIsMapped       1
+    field_high  capPTMappedAddress  20
+    field       capType             4
+}
+
+ +

The generated access methods of the field_high capPTBasePtr have the same type +as the ones for field, but only the top 20 bits of the provided value will be +stored in the setter methods as opposed to the bottom 20 bits for normal fields.

+ +

The getter methods will automatically correctly return a value that has the top +20 bits set to the stored value and the bottom 12 bits set to 0. That is, getter +and setter remain inverses of each other as long as the values provided to the +setter have the bottom 12 bits set to 0.

+ +

On most 64-bit architectures, the top bits of pointers are also determined, +because not all 64 bits are available (e.g. only 48 of them on x64). The +generator assumes field_high values to be used for pointers and to need to store +only the significant bits of the pointer, along with potential sign extension. +See the Architecture Parameters section below for details.

+ +

For instance, if the platform is declared to have base 64 and 48 significant +bits, and we have a pointer that we know is aligned to 12 bits, we need to store +only 48-12 = 36 bits to recreate the correct original pointer value. That means +if we declare

+ +
block store_more {
+    field       some_info  16
+    field_high  ptr        36
+    field       other_info 12
+}
+
+ +

we can store a 12-aligned pointer with sm = store_more_set_ptr(sm, p) and +extract it again with p = store_more_get_ptr(sm) without losing information. +This means, we can store 28 bits of additional information in the space that +would be taken up by a single pointer. For this it does not matter where in the +store_more block the ptr field is declared, just that it is a field_high +that stores 36 bits (on a 64 bit base platform with 48 significant bits).

+ +

Field Ptr

+ +

Often we want to store a pointer with some known alignment (i.e. not all bits +need to be stored), and pad out to a specific overall field size. +The field_ptr abbreviation makes this convenient.

+ +
block some_block {
+    ...
+    field_ptr(align) some_name size
+    ...
+}
+
+ +

stands for “a field some_name for a pointer with alignment align padded out +to size”. It is an abbreviation for

+ +
block some_block {
+    ...
+    padding size - canonical_size + align
+    field_high some_name canonical_size - align
+    ...
+}
+
+ +

The (align) parameter can be left out and is equivalent to field_ptr(0). The +constant canonical_size in the expression above stands for the number of +significant bits (the canonical size) of a pointer according to the most recent +base definition. For example the long form

+ +
base 64(48,1)
+
+block mdb_node {
+    padding 16
+    field_high mdbNext 46
+    field mdbRevocable 1
+    field mdbFirstBadged 1
+
+    field mdbPrev 64
+}
+
+ +

can be written more concisely as

+ +
base 64(48,1)
+
+block mdb_node {
+    field_ptr(2) mdbNext 62
+    field mdbRevocable 1
+    field mdbFirstBadged 1
+
+    field mdbPrev 64
+}
+
+ +

The field_ptr abbreviation is especially useful for sharing the same block +definition under different base declarations, e.g. for different +architectures. For example, with a base 64(39,1) the field_ptr definition +text remains the same, but expands to a different field_high/padding +combination that achieves the same overall width:

+ +
base 64(39,1)
+
+block mdb_node {
+    padding 25
+    field_high mdbNext 37
+    field mdbRevocable 1
+    field mdbFirstBadged 1
+
+    field mdbPrev 64
+}
+
+ +

can be also be written as

+ +
base 64(39,1)
+
+block mdb_node {
+    field_ptr(2) mdbNext 62
+    field mdbRevocable 1
+    field mdbFirstBadged 1
+
+    field mdbPrev 64
+}
+
+ +

This means the same block definition can produce a constant field size while +correctly accommodating multiple different base configurations.

+ +

Visible Field Order

+ +

Sometimes it is useful for the constructor to take its arguments in a particular +order that is different from the field layout order in memory. It is possible to +specify such an order, enumerating the constructor field order in parentheses +after the block name:

+ +
block page_table_cap(capPTBasePtr, capPTMappedASID) {
+    field       capPTMappedASID     9
+    field_high  capPTBasePtr        20
+    padding                         3
+}
+
+ +

All fields must be enumerated, including the tag field in tagged unions +described in the next section.

+ +

Only the constructor is affected, the memory layout as well as getters and +setters remain the same.

+ +

Tagged Unions

+ +

Multiple blocks that share a type field can be aggregated as a type in C into a +tagged union. For example to express an algebraic data type such as the +following

+ +
datatype cap = NullCap | ObjectCap (ref : "20 word")
+
+ +

in C, one might specify the following:

+ +
block null_cap {
+    padding    28
+    cap_type    4
+}
+
+block object_cap {
+    field ref  20
+    padding     8
+    cap_type    4
+}
+
+tagged_union cap cap_type {
+    tag null_cap     0
+    tag object_cap   1
+}
+
+ +
+

Note that both of the block declarations for null_cap and object_cap contain +a field with the name cap_type at the same bit position with the same size, +and that all blocks have the same size. We will later relax the size of the tag +field, but the tool does require all blocks in a tagged union to be of the same +size and the tag field to always be at the same position.

+
+ +

The fragment tagged_union cap cap_type means that we want the generator to +produce a C type cap_t that is a tagged union, and that we want to use +cap_type as the tag field that distinguishes which variant of the union we are +operating on.

+ +

Listing tag null_cap 0 means that we want the block null_cap to be part of +the tagged union and that the value 0 in field cap_type will indicate that +the rest of the fields are null_cap fields. Similarly tag object_cap 1 +means that a value of 1 in the tag field makes the fields of the block +object_cap available.

+ +

This mapping must be unique, i.e., it is an error for a block to be mentioned in +more than one tagged union.

+ +

If a block is mentioned in a tagged union, its memory layout stays the same as +before, but the code that is generated for it changes types to represent the +tagged union instead. All getters and setters for the block will be prefixed +with the name of the union, and instead of the block type, they will take and +return the union type instead (e.g. cap_t instead of object_cap_t or +null_cap_t). The tag field will be omitted from the constructor, because it is +determined by the constructor name, and no setter methods for the tag field will +be generated. Instead there will be a generic getter function for the tag field +which does not need to know which variant of the type it is presented with. It +returns an enum whose names correspond to the block names and whose values +correspond to the associated tag values.

+ +

For instance for the specification above, we will get:

+ +
// variant tags:
+enum cap_tag {
+    cap_null_cap = 0,
+    cap_object_cap = 1
+};
+typedef enum cap_tag cap_tag_t;
+
+// discrimator:
+cap_tag_t cap_get_cap_type(cap_t cap);
+
+// constructors:
+cap_t cap_null_cap_new(void);
+cap_t cap_object_cap_new(uint64_t ref);
+
+// getters and setters for object_cap variant:
+uint64_t cap_object_cap_get_ref(cap_t cap);
+cap_t cap_object_cap_set_ref(cap_t cap, uint64_t ref);
+
+uint64_t cap_object_cap_ptr_get_ref(cap_t *cap);
+void cap_object_cap_ptr_set_ref(cap_t *cap, uint64_t ref);
+
+ +

The getter names are constructed as <union>_<block>_get_<field>. Setters and +pointer versions have names with set, ptr_get, and ptr_set respectively. +All functions for the tagged union cap will start with cap_.

+ +
+

It is a runtime error to use a getter or setter function on the wrong block +variant. That means it is the caller’s responsibility to know or check which +variant a value of cap_t represents before using e.g. +cap_object_cap_get_ref() on it. The tool generates assert statements in the +getters and setters. Common idioms are to check the tag in a switch or if +statement and work on the contents accordingly.

+
+ +

Advanced Tag Fields

+ +
Tag Slices
+ +

Occasionally the tag value for a tagged union cannot be encoded in a single +field of a block, for instance when the hardware prescribes using e.g. bits 0 +and 5..6 for the type of a structure and bits 1..4 for something else.

+ +

An example would be the following

+ +
block null {
+    padding     25
+    field typ_h  2
+    padding      4
+    field typ_l  1
+}
+
+block content {
+    padding     25
+    field typ_h  2
+    field some   4
+    field typ_l  1
+}
+
+tagged_union example ex_type(typ_h, typ_l) {
+    null    (0,0)
+    content (2,0)
+}
+
+ +

Instead of a single tag field, the example union has two tag fields. We also +say that the tag ex_type has two slices typ_h and typ_l. The same +restrictions as for normal tags apply: they must fit the tag values and all tag +slice fields must be mentioned in all blocks of the union.

+ +

The fragment ex_type(typ_h, typ_l) means that we want the discriminator +function to be called example_get_ex_type and that the tag is made up of the +two fields (typ_h, typ_l). Any positive number of fields is allowed. The +generated enumeration will still be called example_tag as it would be for a +single tag, and it will still contain a name for each alternative bound to a +value unique for that variant. (The values consist of the concatenation of the +bit pattern of the tag slice values).

+ +

Similarly to a single tag field, the tool will not generate getters and setters +for any of the tag fields mentioned in the union specification.

+ +

The values in the null (0,0) and content (2,0) are positional, i.e., the +example assigns the bit pattern 0b10 in field typ_h and 0 in field typ_l +to mean the content block and 0 in both to mean the null block.

+ +
Masks
+ +

The restriction that all tag fields have to have the same size can be relaxed +slightly. One can declare multiple possible tag sizes together with a bit mask +each that determines which of these sizes applies.

+ +

Say for instance that we have more than 16 different cap types, and that some +of the cap alternatives only have 4 bits of storage left to store the cap tag, +but others have further bits available, e.g. 8. We can declare a bit mask that +determines if the tag size is 4 or 8 and use the size 4 tags in the blocks that +have fewer bits left.

+ +

The following example achieves this:

+ +
block null_cap {
+    padding    24
+    cap_type    8
+}
+
+block object_cap {
+    field ref  28
+    cap_type    4
+}
+
+tagged_union cap cap_type {
+    mask 4 0x0e
+    mask 8 0x0e
+    tag null_cap    15
+    tag object_cap   1
+}
+
+ +

The block null_cap has an 8-bit tag field and the block object_cap has a +4-bit tag field of the same name. Note that both still must start at the same +bit positions.

+ +

The declarations mask 4 0x0e and mask 8 0x0e are read from the smallest to +the largest mask size. mask 4 0x0e declares that the default tag size is 4 +bits wide, but if the bits 0b1110 (0x0e) are set, i.e. if tag_value & 0x0e == +0x0e, then the next larger mask will be used. This means values 0 to 13 are +using 4 bit tags, 14 and 15 are using 8 bit tags, and all 8 bit tag values must +have at least the bits 1, 2, and 3 set.

+ +

Since there is no larger mask size after 8 in the example, the mask value there +is not important. However, the generator expects the mask of each larger level +to have at least all bits set that the masks of all smaller sizes have set, so +we chose the same value 0x0e in the example. If we had another level, e.g. 16 +bits wide afterwards, we might have chosen 0b11110 (0x1e) for the mask value +at 8 bit.

+ +

The sub mask inclusion means that the generator can check mask sizes +consecutively. I.e. if tag_value & 0xe != 0xe, we always know it is a 4 bit +tag, no matter how many other tag sizes are declared.

+ +

The tag mask value declared for each alternative in the tagged union must fit +the mask for the size of the tag field in the block. Remember that with mask 4 + 0x0e the 0x0e bit pattern means that size 4 does not apply, and instead +the next larger size applies. So in the example, because object_cap has a +4-bit tag field, object_cap must have a tag value where the bits 0x0e are +not all set (e.g. 1 is a legal value). Conversely, null_cap has an 8-bit tag, +and so at least the bits 0x0e must all be set in the tag value (e.g. 14 or 15 +works, as does 255, but not 1).

+ +

Masks and tag slices are mutually exclusive, i.e. only one of these can be used +for any particular tagged union.

+ +

Raw Value Access

+ +

The C representation of blocks, whether in a tagged union or not, is a struct +containing an array of the architecture word type (uint32 or uint64) of the +length computed from the number and width of fields in the block. Given that the +memory layout is fully specified it is possible to operate on these raw values +directly without breaking the semantics of the generated functions.

+ +

This is usually neither recommended nor necessary, and for code undergoing +formal verification strongly discouraged, because it introduces additional +verification overhead.

+ +

However, one special case is occasionally convenient: when initialising an area +of memory with 0, and reinterpreting that memory as a bitfield structure, we are +guaranteed to get a value where all fields are 0. Similarly, returning an all-0 +struct from a function instead of calling the constructor with only 0 parameters +may be acceptable, although one should check the generated assembly if the +compiler was not able to optimise the constructor away – if it does then the +constructor form is clearer and easier to use in proofs.

+ +

The tool will not access padding fields, but is not guaranteed to preserve them +when copying. Writing/reading padding fields is not guaranteed to be stable.

+ +

Architecture Parameters and Canonical Pointers

+ +

The tool supports architectures with 32 and 64 bit word sizes. The command

+ +
base 32
+
+ +

selects a 32 bit native word size. The declaration covers all subsequent blocks +and unions in the specification. It is possible to give multiple declarations, +each covering the subsequent blocks and unions, but it rarely makes sense to +pick any other value than the word size of the architecture.

+ +

Many 64 bit architectures have the concept of canonical pointers where not all +64 bits of the available space are usable for pointers, but only for example 48 +bits. In this setting a pointer value would be canonical if and only if all top +bits are set when bit 47 (counting from 0) is set. This is equivalent to sign +extension, i.e. treating bit 47 as the sign bit and extending that sign bit up +to bit 63.

+ +

A potential use for this is for kernel pointers to always have bit 47 set (and +all bits above) and for user pointers to always have bit 47 unset (and all bits +above).

+ +

The bitfield generator allows specifying this canonical bit and whether the top +bits for pointers should be sign extended or not like this:

+ +
base 64(48,1)
+
+ +

This means: word size is 64, pointers are 48 bits [0..47], and bit 48 and +above should be set to 1 if bit 47 is set.

+ +

This only affects field_high fields which are assumed to be pointers.

+ +
base 64(48,0)
+
+ +

means word size is 64, pointers are at most 48 bits, and no sign extension. This +is currently equivalent to just base 64.

+ +

It may make sense to use the base command multiple times for the sign +extension case. For instance, if the intention is to usually store pointers on +x64, one would declare base 64(48,1), but if there is a specific block that +wants to not store a pointer, but some other value as field_high, one could +declare base 64 just before and base 64(48,1) again just after that block.

+ +

The base declaration sets the values of the constants word_size and +canonical_size that can be used in size expressions. For example, after the +declaration base 64(48,1), word_size will be 64 and canonical_size 48. +After base 32, word_size and canonical_size will both be 32.

+ +

Syntax Reference

+ +

Lexical Structure

+ +

The generator distinguishes identifiers, integer literals, comments, white +space, keywords, and operators. Keywords and operators are shown inline in the +grammar in the next section. The rest are defined below.

+ +

A multi-character ident must start with a letter or underscore, followed by +letters, underscores or numbers. A one-character ident must consist of one +letter. Letters are Latin letters [a-z] and [A-Z], digits are [0-9].

+ +
IDENT ::= [A-Za-z_][a-zA-Z0-9_]+ | [A-Za-z]
+
+ +

In addition to the regular expression above, identifiers that consist only of +underscores are invalid. Valid examples are a, a_20, _a_20_b. Invalid +examples are 0, _, 0a or 0_a.

+ +

Integer literals can be decimal, octal, hex, or binary, followed by an optional +l or L specifier.

+ +
INTLIT ::= (  [1-9][0-9]*
+            | 0[oO]?[0-7]+
+            | 0[xX][0-9a-fA-F]+
+            | 0[bB][01]+
+            | 0 ) [lL]?'
+
+ +

Valid examples are 15, 017, 0o17, 0x0F, 0xF, 0XF, 0b1111, 0, +0l, and 15L. Invalid examples are 10A0, 0xFG0, 0b20, 090.

+ +

Comments start with -- or with # and go until the end of the line. There +are no block comments.

+ +
-- this is a valid comment
+### as is this
+
+ +

Whitespace are spaces and tab characters. They delimit other tokens. Consecutive +whitespace is ignored.

+ +

Syntactic Structure

+ +
spec :== ( base | block | tagged_union )*
+
+base ::= "base" ("32"|"64") canonical_spec?
+canonical_spec ::= "(" expr "," ("0"|"1") ")"
+
+block ::= "block" IDENT visible_order_spec_opt? "{" fields "}"
+visible_order_spec_opt ::= "(" visible_order_spec? ")"
+visible_order_spec ::= IDENT ("," IDENT)*
+fields ::= ( "field" IDENT expr |
+             "field_high" IDENT expr |
+             "field_ptr" ("(" expr ")")? IDENT expr |
+             "padding" expr )*
+
+tagged_union ::= "tagged_union" IDENT IDENT tag_slices? "{" masks tags "}"
+
+masks ::= ( "mask" expr expr )*
+tags ::= ( "tag" IDENT tag_value )*
+tag_slices ::= "(" IDENT ("," IDENT)* ")"
+tag_value ::= expr | "(" expr ( "," expr )* ")"
+
+expr ::= expr ("+" | "-" | "*" | "/" | "%") expr
+       | "-" expr | "(" expr ")" | INTLIT
+       | "word_size" | "canonical_size"
+
+ +

Forward references to names that are declared later in the file are allowed. +Multiplicative operators “*”, “/”, “%” bind stronger than “+” and “-“. Binary +operators are left-associative. Unary minus binds stronger than all of the +other operators. The constants “word_size” and “canonical_size” are only +available in “field”, “field_high”, “field_ptr”, and “padding” expressions and +refer to the most recent corresponding “base” declaration.

+ +

Restrictions

+ +

The following restrictions are not represented by the grammar in the previous +section, but will be checked by the generator.

+ +
    +
  • the canonical bit must be smaller than the base size
    • +
  • field sizes must not be larger than the base size
    • +
  • all field sizes must be positive
    • +
  • all padding sizes must be non-negative
    • +
  • the field sizes in a block must add up to multiples of the base size
    • +
  • all identifiers mentioned as tags in a union must be blocks
    • +
  • all blocks in a tagged union must have the same size
    • +
  • all blocks in a tagged union must mention the tag field(s)
    • +
  • all blocks in a tagged union must have the tag field(s) at the same bit +position
    • +
  • all blocks in a tagged union must have tag fields of one of the sizes declared +in the union, or if no mask size is declared, the tag fields must all be of +the same size.
    • +
  • each block can be used in at most one tagged union
    • +
  • visible_order_spec must enumerate all fields if used
    • +
  • tag values must fit into the size of the tag fields
    • +
  • tag values must not be larger than an int of the underlying platform, +because they will be used in an enum in C.
    • +
+ +

Correctness

+ +

Since the tool generates both the implementation and the specification, the +question arises what kind of correctness property we gain. Even if the generated +proofs are checked for correctness by Isabelle/HOL, they could still be +expressing properties that are not useful or specify behaviour that we do not +want the code to have. What we do know after Isabelle/HOL has checked the proofs +is that the code implements the generated specification and that the generated C +code is free from undefined behaviour.

+ +

To gain confidence that the generated specification is meaningful and itself has +the right properties it needs human inspection or it needs to be used in further +proofs. In the seL4 verification both are the case. In particular, the generated +specification together with the generated implementation proofs are the +interface that the C verification uses when it encounters bitfield functions. If +the generated specifications are trivial, not useful, wrong, or do not express +the behaviour of the generated C (e.g. if the generated correctness proof was +trivial), these proofs could not succeed, because the specification would then +not provide the needed semantics of the code (e.g. that loading a value after +storing it does not lose information). If the specification provides strong +enough properties to make the rest of the C verification succeed, we know that +the specification is strong enough for our needs, even though it might still be +missing additional facts or properties that the generated C code might have. +This is sufficient for strong functional correctness.

+ +

Limitations

+ +

The tool does not currently support proofs for all combinations of pointer +access functions for variants, but it does support all those that are used in +seL4. If proof support for new combinations is needed, the tool could be +extended relatively easily.

+ +

Command Line

+ +

Usage

+ +

The tool can be invoked from the command line as follows

+ +
bitfield_gen.py [options] <input.bf> <outfile>
+
+ +

where <input.bf> is a bitfield specification file as described in this manual. +If no file is given, the tool reads from stdin, and if no output file is given, +the tool prints to stdout.

+ +

By default, the output is generated C code. See options below for how to +additionally produce Isabelle/HOL theory files for specifications and proofs.

+ +

Options

+ +

-h, --help:
+ Show help message and exit.

+ +

--environment={seL4,libseL4}:
+ Whether to produce code for the seL4 or libseL4 environment. This + influences which header files are included, what statement to use for + assert, what type names uint32 etc have, and how a function is declared + inline. The values are determined by the INCLUDES, ASSERTS, INLINE, + and TYPES dictionaries in the generator source.

+ +

--hol_defs:
+ Produce Isabelle/HOL theory files with specifications and definitions.

+ +

--hol_proofs:
+ Produce Isabelle/HOL theory files with proofs, assuming specification + and definition files exist. Requires the --umm_types option.

+ +

--sorry_lemmas:
+ When producing proofs, only state lemmas, but do not prove them. This + requires explicitly setting quick_and_dirty in Isabelle and + is useful for reducing processing time during other proof development.

+ +

--prune=<file>:
+ Append <file> to the list of files with pruning information, which contain + the names of bitfield functions that are used in the client code base. The + option can be used multiple times. If this option is used, the generator + will only produce the functions that are listed in one of these files. This + is useful to reduce code size, processing time, and especially proof + processing time drastically. It does make it harder to discover which + functions are generated by the tool, so if that is important, consider + leaving this option off until proofs are needed.

+ +

--toplevel=<type>:
+ Append Isabelle/HOL <type> name to the list of top-level heap types. The + proofs will generate appropriate frame conditions for all of these top-level + heap types. The option can be used multiple times.

+ +

--umm_types=<file>:
+ Path to the file umm_types.txt which contains dependency information + between the top-level heap types (e.g. which structs contain which other + structs or type fields). The file can be generated using + spec/cspec/mk_umm_types.py in the l4v repository. (UMM = unified memory + model).

+ +

--cspec-dir=<dir>:
+ Location of the cspec directory containing the theory file + KernelState_C. This is specific to the seL4 proof setup.

+ +

--thy-output-path=<path>:
+ Where to put the generated theory files.

+ +

--skip_modifies:
+ Do not emit “modifies” proofs. These proofs state and show which global + state is modified by each generated function. They are weaker versions + of the full specifications and may not be needed if the full specifications + are always used instead.

+ +

--showclasses:
+ Print the parsed classes and fields.

+ +

--debug:
+ Print debug information during code and proof generation.

+ +

--from_file=<FROM_FILE>:
+ Original source file before preprocessing. Use this to produce a + Generated from FROM_FILE comment in the output.

+ +

seL4 build

+ +

In the seL4 build system, .bf files are usually first passed through the C +preprocessor to process #include and #ifdef statements, as well as perform +macro expansion, which are currently not part of the bitfield specification +language.

+ +

The source files containing C preprocessor macros and includes are called .bf. +There are the following main files in seL4:

+ +
    +
  • include/structures_32.bf and include/structures_64.bf contain generic +kernel objects and capabilities for 32 and 64 bit systems
    • +
  • include/arch/**/object/structures.bf contain architecture dependent object +and capability definitions.
    • +
  • some plat/** directories contain hardware.bf files for hardware structures.
    • +
  • libseL4 contains some bitfield definitions that are shared with the kernel in +libsel4/sel4_arch_include/*/sel4/sel4_arch/types.bf, +libsel4/arch_include/*/sel4/arch/shared_types.bf, and +libsel4/mode_include/*32*/sel4/shared_types.bf.
    • +
+ +

The generated C code contains a comment which .bf include hierarchy the +definitions are coming from.

+ +

The generated code can be found in a build directory under the generated +directory, where e.g. structures_gen.h will have been generated from +structures.bf.pbf, which in turn is the preprocessed source of +structures.bf.

+ +

Note that the seL4 build uses the --prune option, which means that the +generator will only produce functions that are mentioned in the rest of the seL4 +sources. To generate a function that is not yet mentioned, simply use a +supported function name pattern in the source (e.g. <block>_get_<field>) and +the generator will supply it. To discover which functions can be generated, +either use the name template descriptions in this manual or consider temporarily +removing the --prune option in the cmake build to look at the generated +sources. This should only be done when no proofs are required, because it will +drastically increase proof processing time.

+ + + + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/sel4/bfgen.md b/projects/sel4/bfgen.md deleted file mode 100644 index 027b2833e7d..00000000000 --- a/projects/sel4/bfgen.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -repo: seL4/seL4 -include_file: tools/bitfield_gen.md -toc: true -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# The seL4 Bitfield Generator - -The seL4 kernel code and the libsel4 library use the so-called bitfield -generator to automatically produce code and formal proofs for tagged unions and -structs of bitfields from a higher-level specification. - -The code for this tool is available in the [seL4 repository] in the [tools] -directory. This page contains the manual of the bitfield generator. The manual -sources are also available for the [tools] directory. - -{% include include_github_repo_markdown.md indent_headings=1 %} - -[seL4 repository]: https://github.com/seL4/seL4/ -[tools]: https://github.com/seL4/seL4/blob/master/tools/ diff --git a/projects/sel4/configurations.html b/projects/sel4/configurations.html new file mode 100644 index 00000000000..6f592100dcf --- /dev/null +++ b/projects/sel4/configurations.html @@ -0,0 +1,2067 @@ + + + + + + + seL4 Configurations | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Configurations

+ +

seL4 has several different options available for configuring seL4 to execute in different +scenarios. Many of these options are only expected to used during application or kernel +development and may not be suitable for a final release deployment that wants to leverage +seL4’s full capabilities.

+ +

Due to the experimental nature of many of the options, there may be undocumented incompatibilities +when trying to configure several options together. seL4test, seL4bench or other user level examples +can be used to test a baseline level of configuration correctness.

+ +

Generic configuration options

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
KernelVerificationBuild
+
+
+

When enabled this configuration option prevents the usage of any other options that would compromise the verification story of the kernel. Enabling this option does NOT imply you are using a verified kernel.

+ +
+
+ Always set. (Default: ON) +
+
+ 
KernelIsMCS
+
+
+

Enable MCS feature for seL4.

+ +
+
+ Available on all MCS supported platforms (Default: Off) +
+
+ 
KernelRootCNodeSizeBits
+
+
+

Root CNode Size (2^n slots) The acceptable range is 12-27 and 12-26, for 32-bit and 64-bit respectively. The root CNode needs at least enough space to contain up to BI_CAP_DYN_START.

+ +
+
+ Always set (Default: 12) +
+
+ 
KernelRetypeFanOutLimit
+
+
+

Maximum number of objects that can be created in a single Retype() invocation.

+ +
+
+ Always set. (Default: 256) +
+
+ 
KernelMaxNumBootinfoUntypedCaps
+
+
+

Max number of untyped capabilities given to initial boot thread. Additional caps won’t be handed to the system.

+ +
+
+ Always set. (Default: 230 caps) +
+ +

Scheduling configuration options

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
KernelTimerTickMS
+
+
+

Kernel timer tick period in milliseconds.

+ +
+
+ Only available on non-MCS kernels. (Default: 2 milliseconds) +
+
+ 
KernelTimeSlice
+
+
+

Number of kernel timer ticks until a thread is preempted.

+ +
+
+ Only available on non-MCS kernels. (Default: 5 ticks) +
+
+ 
KernelBootThreadTimeSlice
+
+
+

Budget of booth thread: Number of milliseconds until the boot thread is preempted.

+ +
+
+ Available on all MCS supported platforms. (Default: 5 milliseconds) +
+
+ 
KernelMaxNumWorkUnitsPerPreemption
+
+
+

Maximum number of work units (delete/revoke iterations) until the kernel checks for pending interrupts (and preempts the currently running syscall if interrupts are pending).

+ +
+
+ Always set. (Default: 100) +
+
+ 
KernelResetChunkBits
+
+
+

Maximum size in bits of chunks of memory to zero before checking a preemption point.

+ +
+
+ Always set. (Default: 8 bits) +
+
+ 
KernelNumDomains
+
+
+

The number of scheduler domains in the system

+ +
+
+ Always set. (Default: 1 domain) +
+
+ 
KernelDomainSchedule
+
+
+

A C file providing the symbols ksDomSchedule and ksDomeScheudleLength to be linked with the kernel as a scheduling configuration.

+ +
+
+ Always set. (Default: src/config/default_domain.c) +
+
+ 
KernelNumPriorities
+
+
+

The number of priority levels per domain.

+ +
+
+ Always set, Valid range 1-256. (Default: 256) +
+
+ 
KernelWcetScale
+
+
+

Multiplier to scale kernel WCET estimate by: the kernel WCET estimate is used to ensure a thread has enough budget to get in and out of the kernel. When running in a simulator the WCET estimate, which is tuned for hardware, may not be sufficient. This option provides a hacky knob that can be fiddled with when running inside a simulator.

+ +
+
+ Enabled if KernelIsMCS. (Default: 1) +
+ +

Debug configuration options

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
KernelDebugBuild
+
+
+

Enable debug facilities (symbols and assertions) in the kernel

+ +
+
+ Disabled if KernelVerificationBuild is set. (Default: ON) +
+
+ 
HardwareDebugAPI
+
+
+

Builds the kernel with support for a userspace debug API, which can allows userspace processes to set breakpoints, watchpoints and to single-step through thread execution.

+ +
+
+ Requires platform support. (Default: Off) +
+
+ 
KernelPrinting
+
+
+

Allow the kernel to print out messages to the serial console during bootup and execution.

+ +
+
+ Disabled if KernelVerificationBuild is set. (Default: Set to initial value of KernelDebugBuild) +
+
+ 
KernelIRQReporting
+
+
+

seL4 does not properly check for and handle spurious interrupts. This can result in unnecessary output from the kernel during debug builds. If you are CERTAIN these messages are benign then use this config to turn them off.

+ +
+
+ Enabled if KernelPrinting is set. (Default: On) +
+
+ 
KernelColourPrinting
+
+
+

In debug mode, seL4 prints diagnostic messages to its serial output describing, e.g., the cause of system call errors. This setting determines whether ANSI escape codes are applied to colour code these error messages. You may wish to disable this setting if your serial output is redirected to a file or pipe.

+ +
+
+ Enabled if KernelPrinting is set. (Default: On) +
+
+ 
KernelUserStackTraceLength
+
+
+

On a double fault the kernel can try and print out the users stack to aid debugging. This option determines how many words of stack should be printed.

+ +
+
+ Enabled if KernelPrinting is set. (Default: 16) +
+
+ 
KernelDebugDisablePrefetchers
+
+
+

On ia32 platforms, this option disables the L2 hardware prefetcher, the L2 adjacent cache line prefetcher, the DCU prefetcher and the DCU IP prefetcher. On the cortex a53 this disables the L1 Data prefetcher.

+ +
+
+ Available if KernelArchX86 OR KernelPlatformHikey is set. (Default: Off) +
+ +

Performance analysis and profiling configuration options

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
KernelFastpath
+
+
+

Enable IPC fastpath. Can be disabled for performance analyses.

+ +
+
+ Always set. (Default: ON) +
+
+ 
KernelFPUMaxRestoresSinceSwitch
+
+
+

This option is a heuristic to attempt to detect when the FPU is no longer in use, allowing the kernel to save the FPU state out so that the FPU does not have to be enabled/disabled every thread switch. Every time we restore a thread and there is active FPU state, we increment this setting and if it exceeds this threshold we switch to the NULL state.

+ +
+
+ Only set if the system is using the FPU. (Default: 64 switches) +
+
+ 
KernelBenchmarks
+
+
+

Enable benchamrks including logging and tracing info. Setting this value > 1 enables a 1MB log buffer and functions for extracting data from it at user level. NOTE this is only tested on the sabre and will not work on platforms with < 512mb memory. This is not fully implemented for x86.
none -> No Benchmarking features enabled.
generic -> Enable global benchmarks config variable with no specific features.
track_kernel_entries -> Log kernel entries information including timing, number of invocations and arguments for system calls, interrupts, user faults and VM faults.
tracepoints -> Enable manually inserted tracepoints that the kernel will track time consumed between.
track_utilisation -> Enable the kernel to track each thread’s utilisation time.

+ +
+
+ Disabled if KernelVerificationBuild is set. (Default: None) +
+
+ 
KernelMaxNumTracePoints
+
+
+

The maximum number of different trace point identifiers which can be used. Use TRACE_POINT_START(k) and TRACE_POINT_STOP(k) macros for recording data, where k is an integer between 0 and this value - 1

+ +
+
+ Requires KernelBenchmarksTracepoints is set. (Default: 1) +
+
+ 
KernelOptimisation
+
+
+

Select the kernel optimisation level. This should only be changed as part of performance analysis. -O2 is required for normal use.

+ +
+
+ Always set. (Default: -O2) +
+
+ 
KernelFWholeProgram
+
+
+

Enable -fwhole-program when linking kernel. This should work modulo gcc bugs, which are not uncommon with -fwhole-program. Consider this feature experimental!

+ +
+
+ Always set. (Default: OFF) +
+
+ 
KernelDangerousCodeInjection
+
+
+

Adds a system call that allows users to specify code to be run in kernel mode. Useful for profiling.

+ +
+
+ Can only be set if: NOT KernelARMHypervisorSupport;NOT KernelVerificationBuild;NOT KernelPlatformHikey;NOT KernelSkimWindow. (Default: Off) +
+
+ 
KernelStackBits
+
+
+

This describes the log2 size of the kernel stack. Great care should be taken as there is no guard below the stack so setting this too small will cause random memory corruption

+ +
+
+ Always set. (Default: 12 bits) +
+ +

Target hardware architecture/platform options

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
KernelPlatform
+
+
+

Hardware platform to target. This setting influences other kernel configuration values.

+ +
+
+ See list of supported platforms. +
+
+ 
KernelSel4Arch
+
+
+

Architecture mode for building the kernel.

+ +
+
+ Supported values: (aarch32, aarch64, arm_hyp, riscv32, riscv64, x86_64, ia32). +
+
+ 
KernelHaveFPU
+
+
+

Set if the platform and toolchain supports floating point unit.

+ +
+
+ Set on x86, Unset on RISC-V, toolchain + verirification dependent on Arm +
+
+ 
KernelMaxNumNodes
+
+
+

Max number of CPU cores to boot.

+ +
+
+ Always set. (Default: 1 node) +
+ +

Arm

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
KernelDebugDisableL2Cache
+
+
+

Do not enable the L2 cache on startup for debugging purposes.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelDebugDisableL1ICache
+
+
+

Do not enable the L1 instruction cache on startup for debugging purposes.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelDebugDisableL1DCache
+
+
+

Do not enable the L1 data cache on startup for debugging purposes.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelDebugDisableBranchPrediction
+
+
+

Do not enable branch prediction (also called program flow control) on startup for debugging purposes. This makes execution time more deterministic at the expense of dramatically decreasing performance.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelArmHypervisorSupport
+
+
+

Utilise Arm virtualisation extensions to build the kernel as a hypervisor.

+ +
+
+ Arm option. (Default: the value of ARM_HYP (TRUE or FALSE)) +
+
+ 
KernelArmHypervisorSupport
+
+
+

Utilise Arm virtualisation extensions to build the kernel as a hypervisor.

+ +
+
+ Arm option. (Default: the value of ARM_HYP (TRUE or FALSE)) +
+
+ 
KernelArmHypEnableVCPUCP14SaveAndRestore
+
+
+

The kernel does not save or restore VCPUs’ CP14 accesses. As a result, accessing VPU threads’ CP14 context triggers a trap, which allows the kernel to intercept the access and deliver it as a fault message to the VM monitor.

+ +
+
+ Arm option. (Default: ON) +
+
+ 
KernelArmErrata430973
+
+
+

Enable a workaround for 430973 Cortex-A8 (r1p0..r1p2) erratum An error occurs if an instruction contains Arm/Thumb interworking branch that is replaced by a different instruction from the same virtual address.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelArmErrata773022
+
+
+

Enable a workaround for 773022 Cortex-A15 (r0p0..r0p4) erratum. An error occurs on rare sequences of instructions which results on the loop buffer delivering incorrect instructions. The workaround is to disable the loop buffer.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelArmSMMU
+
+
+

Enable the System MMU on the Tegra TK1 SoC.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelArmEnableA9Prefetcher
+
+
+

Enable the prefetcher on Arm Cortex-A9 core. The Cortex-A9 has L1 and L2 prefetchers, which are disabled by default. This config option enables those prefetchers, requiring the kernel to be executed in the secure mode. Arm document indicates that the bit used for enabling those prefetchers is no longer supported from version r4p1 of the Cortex-A9. However, the correctness of that is uncertain.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelArmExportPMUUser
+
+
+

Grant user access to the performance monitoring unit. While useful for benchmarking, this option opens the possibility of timing channels.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelArmDisableWFIWFETraps
+
+
+

Disable the trapping of WFI and WFE instructions by configuring the Hyp Configuration Registor (HCR) of a VCPU.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelARMSMMUInterruptEnable
+
+
+

Enable system MMU (SMMU) interrupts. System MMU interrupts currently only serve for debugging purpose because they are not forwarded to user level. Enabling this will cause some SMMU fault types to print out a message in the kernel. High frequency faults can result in all time spent in the kernel printing fault messages.

+ +
+
+ Arm option. (Default: OFF) +
+
+ 
KernelAArch32FPUEnableContextSwitch
+
+
+

Enable hardware VFP and SIMD context switch. This enables the VFP and SIMD context switch on platforms with hardware support, allowing the user to execute hardware VFP and SIMD operations in a multithreading environment, instead of relying on software emulation of FPU/VFP from the C library (e.g. mfloat-abi=soft).

+ +
+
+ Arm option. (Default: ON) +
+ +

x86

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
KernelX86MicroArch
+
+
+

Select the x86 micro architecture.

+ +
+
+ x86 Option. Supported values:nehalem, generic, westmere, sandy, ivy, haswell, broadwell, skylake. (Default: nehalem) +
+
+ 
KernelIRQController
+
+
+

Select the IRQ controller seL4 will use. Code for others may still be included if needed to disable at run time.

+ +
+
+ x86 Option. Supported values: PIC, IOAPIC. (Default: IOAPIC) +
+
+ 
KernelMaxNumIOAPIC
+
+
+

Configure the maximum number of IOAPIC controllers that can be supported. SeL4 will detect IOAPICs regardless of whether the IOAPIC will actually be used as the final IRQ controller.

+ +
+
+ x86 Option. (Default: 1) +
+
+ 
KernelLAPICMode
+
+
+

Select the mode local APIC will use: XAPIC, X2APIC

+ +
+
+ x86 Option. Not all machines support X2APIC mode (Default: XAPIC) +
+
+ 
KernelUseLogcalIDs
+
+
+

Use logical IDs to broadcast IPI between cores. Not all machines support logical IDs. In xAPIC mode only 8 cores can be addressed using logical IDs.

+ +
+
+ x86 Option. (Default: OFF) +
+
+ 
KernelCacheLnSz
+
+
+

Define cache line size for x86.

+ +
+
+ x86 Option. (Default: 64) +
+
+ 
KernelVTX
+
+
+

VT-x support compiled into the kernel.

+ +
+
+ x86 Option. (Default: Off) +
+
+ 
KernelIOMMU
+
+
+

IOMMU support for VT-d enabled chipset.

+ +
+
+ x86 Option. (Default: ON) +
+
+ 
KernelMaxRMRREntries
+
+
+

Sets the maximum number of Reserved Memory Region Reporting structures we support recording from the ACPI tables. These structures are used for setting up passthrouh IOMMU mappings for legacy devices.

+ +
+
+ x86 Option. (Default: 32) +
+
+ 
KernelMaxVPIDs
+
+
+

The kernel maintains a mapping of 16-bit VPIDs to VCPUs. This option should be sized as small as possible to save memory, but be at least the number of VCPUs that will be run for optimum performance.

+ +
+
+ x86 Option. (Default: 1024) +
+
+ 
KernelHugePage
+
+
+

Add support for 1GB huge page.

+ +
+
+ x86 Option. Not all recent processor models support this feature (Default: On) +
+
+ 
KernelSupportPCID
+
+
+

Add support for PCIDs (aka hardware ASIDs).

+ +
+
+ x86_64 Option. Not all recent processor models support this feature (Default: On) +
+
+ 
KernelSyscall
+
+
+

Which syscall method that the kernel supports. This config should be set to the most efficient one that is support by the hardware the system will run on.

+ +
+
+ x86 Option. The kernel only ever supports one method at a time: syscall, sysenter (Default: syscall) +
+
+ 
KernelFPU
+
+
+

Choose the method that FPU state is stored in. This directly affects the method used to save and restore it.
FXSAVE -> This chooses the legacy 512-byte region used by the fxsave and fxrstor functions
XSAVE -> This chooses the variable xsave region, and enables the ability to use any of the xsave variants to save and restore. The actual size of the region is dependent on the features enabled.

+ +
+
+ x86 Option. (Default: XSAVE) +
+
+ 
KernelXSave
+
+
+

The XSAVE area supports multiple instructions to save and restore to it. These instructions are dependent upon specific CPU support. See Chapter 13 of Volume 1 of the Intel Architectures SOftware Developers Manual for discussion on the init and modified optimizations.
XSAVE -> Original XSAVE instruction. This is the only XSAVE instruction that is guaranteed to exist if XSAVE is present
XSAVEC -> Save state with compaction. This compaction has to do with minimizing the total size of XSAVE buffer, if using non contiguous features, XSAVEC will attempt to use the init optimization when saving
XSAVEOPT -> Save state taking advantage of both the init optimization and modified optimization
XSAVES -> Save state taking advantage of the modified optimization. This instruction is only available in OS code, and is the preferred save method if it exists.

+ +
+
+ x86 Option. (Default: XSAVEOPT) +
+
+ 
KernelXSaveFeatureSet
+
+
+

XSAVE can save and restore the state for various features through the use of the feature mask. This config option represents the feature mask that we want to support. The CPU must support all bits in this feature mask. Current known bits are
0 - FPU
1 - SSE
2 - AVX
FPU and SSE is guaranteed to exist if XSAVE exists.

+ +
+
+ x86 Option. (Default: 3) +
+
+ 
KernelFSGSBase
+
+
+

There are three ways to to set FS/GS base addresses: IA32_FS/GS_GDT, IA32_FS/GS_BASE_MSR, and fsgsbase instructions. IA32_FS/GS_GDT and IA32_FS/GS_BASE_MSR are availble for 32-bit. IA32_FS/GS_BASE_MSR and fsgsbase instructions are available for 64-bit.

+ +
+
+ x86 Option. (Default x86_64: fsgsbase, ia32: gdt) +
+
+ 
KernelMultibootGFXMode
+
+
+

The type of graphics mode to request from the boot loader. This is encoded into the multiboot header and is merely a hint, the boot loader is free to ignore or set some other mode

+ +
+
+ x86 Option. Options: none, text, linear (Default: none) +
+
+ 
KernelMultibootGFXDepth
+
+
+

The bits per pixel of the linear graphics mode ot request. Value of zero indicates no preference.

+ +
+
+ x86 Option. (Default: 32) +
+
+ 
KernelMultibootGFXWidth
+
+
+

The width of the graphics mode to request. For a linear graphics mode this is the number of pixels. For a text mode this is the number of characters, value of zero indicates no preference.

+ +
+
+ x86 Option. (Default: 0) +
+
+ 
KernelMultibootGFXHeight
+
+
+

The height of the graphics mode to request. For a linear graphics mode this is the number of pixels. For a text mode this is the number of characters, value of zero indicates no preference.

+ +
+
+ x86 Option. (Default: 0) +
+
+ 
KernelMultiboot1Header
+
+
+

Inserts a header that indicates to the bootloader that the kernel supports a multiboot 1 boot header

+ +
+
+ x86 Option. (Default: On) +
+
+ 
KernelMultiboot2Header
+
+
+

Inserts a header that indicates to the bootloader that the kernel supports a multiboot 2 boot header. This is can be enabled together with a multiboot 1 header and the boot loader may use either one

+ +
+
+ x86 Option. (Default: On) +
+
+ 
KernelSkimWindow
+
+
+

Prevent against the Meltdown vulnerability by using a reduced Static Kernel Image and Micro-state window instead of having all kernel state in the kernel window. This only needs to be enabled if deploying to a vulnerable processor

+ +
+
+ x86_64 Option. (Default: On) +
+
+ 
KernelExportPMCUser
+
+
+

Grant user access to the Performance Monitoring Counters. This allows the user to read performance counters, although not control what the counters are and whether or not they are counting. Nevertheless whilst this is useful for evalulating performance this option opens timing and covert channels.

+ +
+
+ x86 Option. (Default: Off) +
+
+ 
KernelExportPMCUser
+
+
+

Grant user access to the Performance Monitoring Counters. This allows the user to read performance counters, although not control what the counters are and whether or not they are counting. Nevertheless whilst this is useful for evalulating performance this option opens timing and covert channels.

+ +
+
+ x86 Option. (Default: Off) +
+
+ 
KernelX86DangerousMSR
+
+
+

rdmsr/wrmsr kernel interface. Provides a syscall interface for reading and writing arbitrary MSRs. This is extremely dangerous as no checks are performed and exists to aid debugging and benchmarking.

+ +
+
+ x86 Option. (Default: Off) +
+
+ 
KernelX86IBRSMode
+
+
+

Indirect Branch Restricted Speculation mode Used to prevent a user from manipulating the branch predictor to manipulate speculative execution of other processes. On current processors IBRS has a prohibitive performance penalty and it is recommended that it be disabled such that software mitigations are used instead. Software mitigation is done by disabling jump tables (the only form of indirect jump in seL4 except for ‘ret’) and flushing the RSB on vmexit. Flushing the RSB at other times is not needed as seL4 does not switch kernel stacks and so is not vulnerable to RSB underflow. The STIBP is essentially software mitigation but enables the single thread isolation for branch predictions. This is only needed if attempting to protect user level process from each other in a multicore environment.

+ +
+
+ x86 Option. (Default: ibrs_none) +
+
+ 
KernelX86IBPBOnContextSwitch
+
+
+

Performs a IBPB on every context switch to prevent Spectre attacks between user processes. This is extremely expensive and is recommended you only turn this on if absolutely necessary. Note that in a multicore environment you should also enable STIBP to prevent other cores retraining the branch predictor even after context switch.

+ +
+
+ x86 Option. (Default: OFF) +
+
+ 
KernelX86RSBOnContextSwitch
+
+
+

Flushes the RSB on context switch to prevent Spectre attacks between user processes. Whilst not nearly as expensive as an IBPB it is not enabled by default as it is largely pointless to flush the RSB without also doing an IBPB as the RSB is already a harder attack vector.

+ +
+
+ x86 Option. (Default: OFF) +
+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4/configurations.md b/projects/sel4/configurations.md deleted file mode 100644 index 58576f95fe2..00000000000 --- a/projects/sel4/configurations.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -project: sel4 -wide: true -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- - -# seL4 Configurations - -seL4 has several different options available for configuring seL4 to execute in different -scenarios. Many of these options are only expected to used during application or kernel -development and may not be suitable for a final release deployment that wants to leverage -seL4's full capabilities. - -*Due to the experimental nature of many of the options, there may be undocumented incompatibilities -when trying to configure several options together. seL4test, seL4bench or other user level examples -can be used to test a baseline level of configuration correctness.* - -## Generic configuration options - -{% include config_list.md project='sel4' type='generic' %} - -## Scheduling configuration options - -{% include config_list.md project='sel4' type='scheduling' %} - -## Debug configuration options - -{% include config_list.md project='sel4' type='debug' %} - -## Performance analysis and profiling configuration options - -{% include config_list.md project='sel4' type='profiling' %} - -## Target hardware architecture/platform options - -{% include config_list.md project='sel4' type='platform' %} - -### Arm - -{% include config_list.md project='sel4' type='platform-arm' %} - -### x86 - -{% include config_list.md project='sel4' type='platform-x86' %} diff --git a/projects/sel4/documentation.html b/projects/sel4/documentation.html new file mode 100644 index 00000000000..4cb920b6a39 --- /dev/null +++ b/projects/sel4/documentation.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4/documentation.md b/projects/sel4/documentation.md deleted file mode 100644 index d74fd312e0f..00000000000 --- a/projects/sel4/documentation.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Learn/ ---- diff --git a/projects/sel4/frequently-asked-questions.html b/projects/sel4/frequently-asked-questions.html new file mode 100644 index 00000000000..723cbe5c347 --- /dev/null +++ b/projects/sel4/frequently-asked-questions.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4/frequently-asked-questions.md b/projects/sel4/frequently-asked-questions.md deleted file mode 100644 index e79c182829d..00000000000 --- a/projects/sel4/frequently-asked-questions.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/About/FAQ.html ---- diff --git a/projects/sel4/index.html b/projects/sel4/index.html new file mode 100644 index 00000000000..1138250b0ad --- /dev/null +++ b/projects/sel4/index.html @@ -0,0 +1,774 @@ + + + + + + + The seL4 microkernel | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

The seL4 microkernel

+ +

The seL4 kernel itself is the core software program, running in privilege mode, +providing applications with a minimal abstraction layer above the +hardware. Applications can be built directly on top of seL4, or, for an easier +entry point, using frameworks like Microkit or CAmkES.

+ +

General information about the seL4 microkernel, including details about +its formal verification are found on the seL4 main +site, which also contains other sources of learning, such as +publications, courses, and a white paper, as well as an extensive FAQ.

+ +

We welcome contributions to seL4. Please see how to contribute.

+ +

The seL4 kernel itself is open source and licensed under the GPL, +version 2. Application code, operating system components, and drivers can have +any license, proprietary or open source. The GPL propagation clause of the +kernel license stops at the kernel/user code boundary.

+ +
+ +
+ +
+ +
+ +
+ +
+ +
+

+ Tutorial +

+
+ Learn about the base API mechanisms provided by the seL4 kernel + through short exercises and basic examples. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ Manual +

+
+ The seL4 kernel reference manual. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ API +

+
+ The C API reference for the seL4 kernel. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ Sources +

+
+ The source code of seL4 microkernel. +
+
+ Learn more + + +
+
+
+ + +
+ +
+ +
+ +
+ +
+ +
+

+ Supported Platforms +

+
+ The table of all hardware and platforms supported by seL4. +
+
+ Learn more + + +
+
+
+ +
+ +
+ +
+ +
+ +
+ +
+

+ Verified Configurations +

+
+ Description of the architecture/platform/configuration combinations + for which seL4 has verified properties. +
+
+ Learn more + + +
+
+
+ + +
+ +

To build the seL4 kernel, please follow the set up instructions.

+ +

If you believe you have found a security vulnerability in seL4 or related +software, we ask you to follow our vulnerability disclosure policy.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4/index.md b/projects/sel4/index.md deleted file mode 100644 index f95ed448182..00000000000 --- a/projects/sel4/index.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- - -# The seL4 microkernel - -The seL4 kernel itself is the core software program, running in privilege mode, -providing applications with a minimal abstraction layer above the -hardware. Applications can be built directly on top of seL4, or, for an easier -entry point, using frameworks like [Microkit] or [CAmkES]. - -General information about the [seL4 microkernel][about], including details about -its [formal verification][verification] are found on the [seL4 main -site][sel4.systems], which also contains other sources of learning, such as -[publications], [courses], and a [white paper], as well as an extensive [FAQ]. - -We welcome contributions to seL4. Please see [how to contribute][contribute]. - -The seL4 kernel itself is open source and [licensed][license] under the GPL, -version 2. Application code, operating system components, and drivers can have -any license, proprietary or open source. The GPL propagation clause of the -kernel license stops at the kernel/user code boundary. - - -
- - {% include card.html - icon="arrow-right-end-on-rectangle" - title="Tutorial" - body="Learn about the base API mechanisms provided by the seL4 kernel - through short exercises and basic examples." - link="/Tutorials/setting-up.html" - %} - - {% include card.html - icon="book-open" - title="Manual" - body="The seL4 kernel reference manual." - link="/projects/sel4/manual.html" - %} - - {% include card.html - icon="document-magnifying-glass" - title="API" - body="The C API reference for the seL4 kernel." - link="/projects/sel4/api-doc.html" - %} - - {% include card.html - icon="other/github" - title="Sources" - body="The source code of seL4 microkernel." - link="https://github.com/seL4/seL4" - %} - - {% include card.html - icon="cpu-chip" - title="Supported Platforms" - body="The table of all hardware and platforms supported by seL4." - link="/Hardware/" - %} - {% include card.html - icon="check-circle" - title="Verified Configurations" - body="Description of the architecture/platform/configuration combinations - for which seL4 has verified properties." - link="/projects/sel4/verified-configurations.html" - %} - -
- - -To build the seL4 kernel, please follow the [set up instructions][build]. - -If you believe you have found a security vulnerability in seL4 or related -software, we ask you to follow our [vulnerability disclosure policy][VDP]. - - - -[about]: https://sel4.systems/About/ -[verification]: https://sel4.systems/Verification/ -[sel4.systems]: https://sel4.systems/ - -[license]: https://sel4.systems/Legal/license.html - -[Microkit]: /projects/microkit/ -[CAmkES]: /projects/camkes/ - -[contribute]: /projects/sel4/kernel-contribution.html - -[learn]: https://sel4.systems/Learn/ -[white paper]: https://sel4.systems/About/whitepaper.html -[publications]: https://sel4.systems/Research/publications.html -[courses]: https://sel4.systems/Research/courses.html -[FAQ]: https://sel4.systems/About/FAQ.html - - -[build]: /projects/buildsystem/host-dependencies.html -[VDP]: https://github.com/seL4/seL4/blob/master/SECURITY.md diff --git a/projects/sel4/kernel-contribution.html b/projects/sel4/kernel-contribution.html new file mode 100644 index 00000000000..7bad4619909 --- /dev/null +++ b/projects/sel4/kernel-contribution.html @@ -0,0 +1,742 @@ + + + + + + + Contributing to kernel code | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Contributing to kernel code

+ +

If the platform, architecture, feature that you are after is not listed on the +Supported Platforms page, and if, from your available +options, you choose to contribute +the port or feature yourself, here are the guidelines for it.

+ +

There four classes of kernel contributions:

+ +
    +
  1. Board Support Package (BSP) ports, also known as platform ports.
    2. +
  2. Architecture features
    3. +
  3. Architecture ports
    4. +
  4. Kernel features
    5. +
+ +

For any kernel contributions it is important to note that a modified kernel will +not be formally verified until the proofs themselves are also appropriately +modified, or until it can be shown that the modifications do not affect the +proofs.

+ +

Platform/BSP ports

+ +

Platform ports, also known as Board Support Package (BSP) ports are the +simplest, and require the least modifications, discussion and approval. This +assumes that you are porting the kernel to a new board on an existing +architecture.

+ +

You will need to:

+ + + +

Questions, discussion, and sharing of work in progress during this stage are +welcome.

+ +

If you run into problems please ask questions – many of us may have run into +the same problems before and can provide information on how to fix them and +save hours to weeks of frustration. Please us one of our +communication channels for this.

+ +

Make sure to write appropriate tests and include them in seL4test as +part of the port. Consider (and discuss) a plan for how to support +this port (e.g. with regression testing) so that it continues to be +updated and work as seL4 evolves.

+ +

Once the code is ready for submission follow the Contribution Guidelines to +submit the changes.

+ +

Architecture features

+ +

In some cases a kernel port requires more than just a platform/BSP port. If the +port is on a supported architecture, but you wish to make use of architecture +features that the kernel does not yet support, then these will be architecture +feature contributions. This will typically require moderate modifications to +kernel design and implementation.

+ +

We do not have specific guidelines or how-tos for adding architecture features. +Each such feature is different and the design decisions and implementations will +vary.

+ +

Before starting on design and implementation of architecture features please +start an initial discussion on one of our communication channels +to check if such a feature is not already being worked on, if it is considered +appropriate to include in the kernel, etc.

+ +

Then start a Request For Comment (RFC) describing your design and plans, +and engage in discussion with others about this. The goal is to get feedback +into specific design decisions, as well as to get agreement on the general +direction and design, considering the fit with the overall philosophy and +architecture of the kernel, performance impacts, verification impacts, etc.

+ +

Once there is agreement on how to design and implement such a feature, the next +step is to implement it. Discussion, revisions of design, and sharing of code +(intermediate, proof of concept, prototype, etc) during this stage is +encouraged.

+ +

Evaluate any performance and security impacts of the implementation, and if +there are significant impacts, discuss these and consider how to redesign or +re-implement to avoid them.

+ +

If the feature implementation affects the proofs in any way, then the +modifications will also have to be evaluated and approved by proof engineers to +ensure that the existing proofs are not invalidated – ideally already during +the design phase. Note that this is even the case if the architecture feature +implementation itself is not verified.

+ +

Consider whether you want to have the architecture feature implementation +verified, and the plans for achieving that.

+ +

As with a platform/BSP port make sure to write appropriate tests and include +them in seL4test as part of the work. Consider (and discuss) a plan for how to +support this port (e.g. with regression testing) so that it continues to be +updated and work as seL4 evolves.

+ +

Once the implementation is complete follow the Contribution Guidelines for +submitting changes.

+ +

Architecture Ports

+ +

If you wish to port seL4 to a new hardware architecture that seL4 does not yet +support, then this will be a new architecture port. This will require +extensive kernel design and implementation modifications.

+ +

We feel that seL4 currently supports the most important hardware architectures +(ARM, x86, RISC-V), however, there may be reasons to port to other (new or +existing) architectures.

+ +

Some architectures will be similar enough to currently supported architectures +that a port will be relatively straight forward. Other architectures may be +radically different and require extensive kernel modifications or additions. +Such changes may render the kernel for that architecture incompatible with much +of the existing user-level code.

+ +

Architecture ports also have significant impact on verification.

+ +

For these reasons, it is critical to first engage in discussion before +commencing on such a port.

+ +

Start an initial discussion on one of our communication channels to +check if such a port is already being worked on, whether there are known +challenges with such a port, etc. After initial discussion, start a Request +For Comment (RFC) describing your design and plans.

+ +

Once there is agreement on the general suitability of and design of the port, +then go on to implementing it. Discussion, revisions of design, sharing +intermediate, proof of concept, and prototype code during this stage is +required.

+ +

Evaluate the performance and security properties of the port, and if there are +significant impacts, discuss these and consider how to redesign or re-implement +to avoid them.

+ +

Consider whether you want to have the port verified, and the plans for achieving +that. Verifying an architecture port is a significant undertaking.

+ +

As with a platform/BSP port, make sure to write appropriate tests and include +them in seL4test as part of the port. Consider (and discuss) a plan for how to +support this port (e.g. with regression testing) so that it continues to be +updated and work as seL4 evolves.

+ +

Once the implementation is complete follow the Contribution Guidelines for +submitting changes.

+ +

Kernel Features

+ +

If you wish to add new features to the kernel that are architecture independent +(i.e. they span different architectures) then these are called kernel feature +contributions. These will require the most extensive kernel design and +implementation modifications.

+ +

As with architecture feature contributions, we do not have specific guidelines +or how-tos for adding kernel features. Each such feature is different and the +design decisions and implementations will vary.

+ +

Such features are not to be considered lightly, and will often be the result of +significant research, e.g. a PhD project. Smaller tweaks are possible, of +course.

+ +

Before starting on design and implementation of new kernel features please +start an initial discussion on one of our communication channels to +check if such a feature is not already being worked on, if it is considered +appropriate to include in the kernel, known issues and challenges with such +features, etc.

+ +

Then start a Request For Comment (RFC) describing your design and plans, +and engage in discussion with others about this. The goal is to get feedback +into specific design decisions, as well as to get agreement on the general +direction and design, considering the fit with the overall philosophy and +architecture of the kernel, performance impacts, verification impacts, etc.

+ +

It is particularly important to consider how such a kernel feature will affect, +and be affected on, all the kernel ports, how it will affect user-level +components and systems, and how it will impact key properties such as security.

+ +

Once there is agreement on how to design and implement such a feature, the next +step is to implement it. Discussion, revisions of design, and sharing of code +(intermediate, proof of concept, prototype, etc) during this stage is required.

+ +

As with any kernel modification, make sure to write appropriate tests and +include them in seL4test. Consider (and discuss) a plan for how to support this +port (e.g. with regression testing) so that it continues to be updated and work +as seL4 evolves.

+ +

This is particularly important for features that span all the kernel ports and +need to be tested on all the supported platforms. It is not sufficient to +implement a kernel feature on a single platform, with no plans of how to ensure +that it works on all supported platforms.

+ +

Once the implementation is complete follow the Contribution Guidelines for +submitting changes.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4/kernel-contribution.md b/projects/sel4/kernel-contribution.md deleted file mode 100644 index 229ea8af2d6..00000000000 --- a/projects/sel4/kernel-contribution.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Contributing to kernel code - -If the platform, architecture, feature that you are after is not listed on the -[Supported Platforms page](../../Hardware/), and if, from your available -[options](../../Hardware/index.html#not-in-the-lists-above), you choose to contribute -the port or feature yourself, here are the guidelines for it. - -There four classes of kernel contributions: - -1. Board Support Package (BSP) ports, also known as platform ports. -2. Architecture features -3. Architecture ports -4. Kernel features - -For any kernel contributions it is important to note that a modified kernel will -*not* be formally verified until the proofs themselves are also appropriately -modified, or until it can be shown that the modifications do not affect the -proofs. - -## Platform/BSP ports - -*Platform ports*, also known as *Board Support Package (BSP) ports* are the -simplest, and require the least modifications, discussion and approval. This -assumes that you are porting the kernel to a new board on an existing -architecture. - -You will need to: - -* follow the [platform porting guide](porting.html); -* follow the guidelines to [become a platform - owner](https://sel4.systems/Contribute/platform-ports.html). - -Questions, discussion, and sharing of work in progress during this stage are -welcome. - -If you run into problems please ask questions -- many of us may have run into -the same problems before and can provide information on how to fix them and -save hours to weeks of frustration. Please us one of our -[communication channels][contact] for this. - -Make sure to write appropriate tests and include them in seL4test as -part of the port. Consider (and discuss) a plan for how to support -this port (e.g. with regression testing) so that it continues to be -updated and work as seL4 evolves. - -Once the code is ready for submission follow the [Contribution Guidelines] to -submit the changes. - -## Architecture features - -In some cases a kernel port requires more than just a platform/BSP port. If the -port is on a supported architecture, but you wish to make use of architecture -features that the kernel does not yet support, then these will be *architecture -feature contributions*. This will typically require moderate modifications to -kernel design and implementation. - -We do not have specific guidelines or how-tos for adding architecture features. -Each such feature is different and the design decisions and implementations will -vary. - -Before starting on design and implementation of architecture features please -start an initial discussion on one of our [communication channels][contact] -to check if such a feature is not already being worked on, if it is considered -appropriate to include in the kernel, etc. - -Then start a [Request For Comment (RFC)][RFC] describing your design and plans, -and engage in discussion with others about this. The goal is to get feedback -into specific design decisions, as well as to get agreement on the general -direction and design, considering the fit with the overall philosophy and -architecture of the kernel, performance impacts, verification impacts, etc. - -Once there is agreement on how to design and implement such a feature, the next -step is to implement it. Discussion, revisions of design, and sharing of code -(intermediate, proof of concept, prototype, etc) during this stage is -encouraged. - -Evaluate any performance and security impacts of the implementation, and if -there are significant impacts, discuss these and consider how to redesign or -re-implement to avoid them. - -If the feature implementation affects the proofs in any way, then the -modifications will also have to be evaluated and approved by proof engineers to -ensure that the existing proofs are not invalidated -- ideally already during -the design phase. Note that this is even the case if the architecture feature -implementation itself is not verified. - -Consider whether you want to have the architecture feature implementation -verified, and the plans for achieving that. - -As with a platform/BSP port make sure to write appropriate tests and include -them in seL4test as part of the work. Consider (and discuss) a plan for how to -support this port (e.g. with regression testing) so that it continues to be -updated and work as seL4 evolves. - -Once the implementation is complete follow the [Contribution Guidelines] for -submitting changes. - -## Architecture Ports - -If you wish to port seL4 to a new hardware architecture that seL4 does not yet -support, then this will be a new *architecture port*. This will require -extensive kernel design and implementation modifications. - -We feel that seL4 currently supports the most important hardware architectures -(ARM, x86, RISC-V), however, there may be reasons to port to other (new or -existing) architectures. - -Some architectures will be similar enough to currently supported architectures -that a port will be relatively straight forward. Other architectures may be -radically different and require extensive kernel modifications or additions. -Such changes may render the kernel for that architecture incompatible with much -of the existing user-level code. - -Architecture ports also have significant impact on verification. - -For these reasons, it is critical to first engage in discussion before -commencing on such a port. - -Start an initial discussion on one of our [communication channels][contact] to -check if such a port is already being worked on, whether there are known -challenges with such a port, etc. After initial discussion, start a [Request -For Comment (RFC)][RFC] describing your design and plans. - -Once there is agreement on the general suitability of and design of the port, -then go on to implementing it. Discussion, revisions of design, sharing -intermediate, proof of concept, and prototype code during this stage is -required. - -Evaluate the performance and security properties of the port, and if there are -significant impacts, discuss these and consider how to redesign or re-implement -to avoid them. - -Consider whether you want to have the port verified, and the plans for achieving -that. Verifying an architecture port is a significant undertaking. - -As with a platform/BSP port, make sure to write appropriate tests and include -them in seL4test as part of the port. Consider (and discuss) a plan for how to -support this port (e.g. with regression testing) so that it continues to be -updated and work as seL4 evolves. - -Once the implementation is complete follow the [Contribution Guidelines] for -submitting changes. - -## Kernel Features - -If you wish to add new features to the kernel that are architecture independent -(i.e. they span different architectures) then these are called *kernel feature -contributions*. These will require the most extensive kernel design and -implementation modifications. - -As with architecture feature contributions, we do not have specific guidelines -or how-tos for adding kernel features. Each such feature is different and the -design decisions and implementations will vary. - -Such features are not to be considered lightly, and will often be the result of -significant research, e.g. a PhD project. Smaller tweaks are possible, of -course. - -Before starting on design and implementation of new kernel features please -start an initial discussion on one of our [communication channels][contact] to -check if such a feature is not already being worked on, if it is considered -appropriate to include in the kernel, known issues and challenges with such -features, etc. - -Then start a [Request For Comment (RFC)][RFC] describing your design and plans, -and engage in discussion with others about this. The goal is to get feedback -into specific design decisions, as well as to get agreement on the general -direction and design, considering the fit with the overall philosophy and -architecture of the kernel, performance impacts, verification impacts, etc. - -It is particularly important to consider how such a kernel feature will affect, -and be affected on, all the kernel ports, how it will affect user-level -components and systems, and how it will impact key properties such as security. - -Once there is agreement on how to design and implement such a feature, the next -step is to implement it. Discussion, revisions of design, and sharing of code -(intermediate, proof of concept, prototype, etc) during this stage is required. - -As with any kernel modification, make sure to write appropriate tests and -include them in seL4test. Consider (and discuss) a plan for how to support this -port (e.g. with regression testing) so that it continues to be updated and work -as seL4 evolves. - -This is particularly important for features that span all the kernel ports and -need to be tested on all the supported platforms. It is not sufficient to -implement a kernel feature on a single platform, with no plans of how to ensure -that it works on all supported platforms. - -Once the implementation is complete follow the [Contribution Guidelines] for -submitting changes. - -[contact]: https://sel4.systems/support.html -[RFC]: https://sel4.systems/Contribute/rfc-process.html -[Contribution Guidelines]: https://sel4.systems/Contribute/ diff --git a/projects/sel4/manual-api-generation.html b/projects/sel4/manual-api-generation.html new file mode 100644 index 00000000000..8c00ab7d988 --- /dev/null +++ b/projects/sel4/manual-api-generation.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4/manual-api-generation.md b/projects/sel4/manual-api-generation.md deleted file mode 100644 index a9fc71e1a44..00000000000 --- a/projects/sel4/manual-api-generation.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -redirect_from: - - /seL4ManualAPIGeneration -redirect_to: https://github.com/seL4/seL4/blob/master/manual/README.md -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/projects/sel4/manual.html b/projects/sel4/manual.html new file mode 100644 index 00000000000..bfac7dab842 --- /dev/null +++ b/projects/sel4/manual.html @@ -0,0 +1,587 @@ + + + + + + + seL4 Manual | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Manual

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4/manual.md b/projects/sel4/manual.md deleted file mode 100644 index 0c82e31288d..00000000000 --- a/projects/sel4/manual.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd ---- - -# seL4 Manual - - -* [Latest version of the seL4 Manual (PDF)](https://sel4.systems/Info/Docs/seL4-manual-latest.pdf) - - -* Previous versions of the seL4 Manual: - * Version [13.0.0](https://sel4.systems/Info/Docs/seL4-manual-13.0.0.pdf) - * Version [12.1.0](https://sel4.systems/Info/Docs/seL4-manual-12.1.0.pdf) - * Version [12.0.0](https://sel4.systems/Info/Docs/seL4-manual-12.0.0.pdf) - * Version [11.0.0](https://sel4.systems/Info/Docs/seL4-manual-11.0.0.pdf) - * Version [10.1.1](https://sel4.systems/Info/Docs/seL4-manual-10.1.1.pdf) - * Version [10.1.1-mcs](https://sel4.systems/Info/Docs/seL4-manual-10.1.1-mcs.pdf) - * Version [10.1.0](https://sel4.systems/Info/Docs/seL4-manual-10.1.0.pdf) - * Version [10.0.0](https://sel4.systems/Info/Docs/seL4-manual-10.0.0.pdf) - * Version [9.0.1](https://sel4.systems/Info/Docs/seL4-manual-9.0.1.pdf) - * Version [9.0.0](https://sel4.systems/Info/Docs/seL4-manual-9.0.0.pdf) - * Version [9.0.0-mcs](https://sel4.systems/Info/Docs/seL4-manual-9.0.0-mcs.pdf) - * Version [8.0.0](https://sel4.systems/Info/Docs/seL4-manual-8.0.0.pdf) - * Version [7.0.0](https://sel4.systems/Info/Docs/seL4-manual-7.0.0.pdf) - * Version [6.0.0](https://sel4.systems/Info/Docs/seL4-manual-6.0.0.pdf) - * Version [5.2.0](https://sel4.systems/Info/Docs/seL4-manual-5.2.0.pdf) - * Version [5.2.0-mcs](https://sel4.systems/Info/Docs/seL4-manual-5.2.0-mcs.pdf) - * Version [5.1.0](https://sel4.systems/Info/Docs/seL4-manual-5.1.0.pdf) - * Version [5.0.0](https://sel4.systems/Info/Docs/seL4-manual-5.0.0.pdf) - * Version [4.0.0](https://sel4.systems/Info/Docs/seL4-manual-4.0.0.pdf) - * Version [3.2.0](https://sel4.systems/Info/Docs/seL4-manual-3.2.0.pdf) - * Version [3.1.0](https://sel4.systems/Info/Docs/seL4-manual-3.1.0.pdf) - * Version [3.0.1](https://sel4.systems/Info/Docs/seL4-manual-3.0.1.pdf) - * Version [3.0.0](https://sel4.systems/Info/Docs/seL4-manual-3.0.0.pdf) - * Version [2.1.0](https://sel4.systems/Info/Docs/seL4-manual-2.1.0.pdf) - * Version [2.0.0](https://sel4.systems/Info/Docs/seL4-manual-2.0.0.pdf) - * Version [1.0.4](https://sel4.systems/Info/Docs/seL4-manual-1.0.4.pdf) - * Version [1.0.0-rt-dev](https://sel4.systems/Info/Docs/seL4-manual-1.0.0-rt-dev.pdf) - * Version [0.0.1-rt-dev](https://sel4.systems/Info/Docs/seL4-manual-0.0.1-rt-dev.pdf) \ No newline at end of file diff --git a/projects/sel4/platf-owner.html b/projects/sel4/platf-owner.html new file mode 100644 index 00000000000..b7129a5e845 --- /dev/null +++ b/projects/sel4/platf-owner.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4/platf-owner.md b/projects/sel4/platf-owner.md deleted file mode 100644 index ea41fe3ee30..00000000000 --- a/projects/sel4/platf-owner.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://sel4.systems/Contribute/platform-ports.html ---- diff --git a/projects/sel4/porting.html b/projects/sel4/porting.html new file mode 100644 index 00000000000..571693a2a4e --- /dev/null +++ b/projects/sel4/porting.html @@ -0,0 +1,772 @@ + + + + + + + Porting seL4 to a new platform | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Porting seL4 to a new platform

+ +

This section covers porting seL4 to a new ARM or RISC-V platform if it is not +already covered in the list of supported seL4 platforms.

+ +

Setup

+ +

In order to load the seL4 image (via some means) it is important to have a working bootloader. +We tend to use U-Boot as it is open source, reliable and supports many different architectures.

+ +

There are a variety of ways of loading an seL4 image from U-Boot such as eMMC, TFTP, and USB.

+ +

TFTP setup

+ +

For setting up a TFTP server to transfer images over the network, you can follow the +UNSW Advanced Operating Systems course guide.

+ +

Once you get U-Boot up and running it is a good idea (if the platform is supported) to flash a +Linux image onto the board. This way you can find the correct address to load the image into memory. +This is also useful for debugging, as you can use the FDT file system to dump addresses from a running system.

+ +

Once you have found the correct address to load, declare the boot command (where address 0x20000000 as an example):

+ +
bootcmd="tftpboot 0x20000000 /path/to/image && go 0x20000000"
+saveenv
+
+ +

For TFTP, you will also need to set some U-Boot environment variables:

+ +
setenv ipaddr <BOARD ADDRESS>
+setenv serverip <SERVER ADDRESS>
+saveenv
+
+ +

The easiest way to find the proper load address is to query the kernel_addr_r variable. That’s the environment variable specifying the expected address at which the kernel’s binary will be found.

+ +

eMMC/SD card setup

+ +

We can load an image with the following command (using 0x20000000 as an example):

+ +
fatload mmc 0 0x20000000 /path/to/image
+
+ +

You can find more details in the U-Boot documentation.

+ +

seL4

+ +

In order to have a successful port of seL4 to your target ARM or RISC-V platform you will need to go through the following steps.

+ +

Device Tree

+ +

Device Trees are used by ARM and RISC-V platforms to describe the hardware platform. +seL4 makes use of Device Trees at build time, which is why acquiring a Device Tree Source (DTS) +for your platform is one of the first steps.

+ +

seL4 relies on the DTS for the location and size of main memory as well as information +about certain devices used by the kernel such as the timer. In debug mode, seL4 also +makes use of the default serial device for debug output.

+ +

Often the Device Tree Source will be included in the +Linux kernel source, from there you can decompile +the device tree blob (DTB) from building the Linux kernel to get the Device Tree that +Linux uses.

+ +

You can compile the Linux Device Tree Sources into a final Device Tree Blob with:

+ +
make ARCH=<arm/arm64/riscv> CROSS_COMPILE=<TOOLCHAIN> defconfig
+make ARCH=<arm/arm64/riscv> CROSS_COMPILE=<TOOLCHAIN> dtbs
+
+ +

The DTBs can be found in arch/<ARCH>/boots/dts/.

+ +

The following command allows you to decompile the DTB:

+ +
dtc -I dtb -O dts /path/to/dtb -o linux.dts
+
+ +

It should be noted that you may need to add device nodes depending on what Linux uses +and what is required by seL4. For example, some platforms do not include a node for +main memory in the Linux Device Tree. This is because Linux can get +this information at run-time from a previous bootloader. This is not the case for seL4 +as it consumes the Device Tree at build-time.

+ +

In the seL4 source, each platform has an overlay DTS that is responsible for dealing +with seL4-specific device nodes. Below is an example +(from the ROCKPro64):

+ +
/ {
+    chosen {
+        seL4,elfloader-devices =
+            "serial2",
+            &{/psci},
+            &{/timer};
+        seL4,kernel-devices =
+            "serial2",
+            &{/interrupt-controller@fee00000},
+            &{/timer};
+    };
+};
+
+ +

These overlay files give a good idea of what nodes seL4 requires in the DTS other than +main memory.

+ +

You will need to create a similar overlay DTS in src/plat/<platform>/overlay-<platform>.dts +as part of the platform port.

+ +

Hardware generation script

+ +

Depending on your platform and the way the DTS is defined you may need to modify the +seL4/tools/hardware_gen.py script.

+ +

From the above example the ROCKPro64 needed a memory node so that this script could +define working memory. Other gotchas could include interrupt cells, interrupt numbers being +mapped wrongly, or incorrect addresses.

+ +

The kernel also expects drivers for:

+ +
    +
  • the timer device.
    • +
  • the serial device.
    • +
  • the interrupt controller.
    • +
  • the IOMMU if the kernel is being built with IOMMU support.
    • +
+ +

You can check all the supported drivers in seL4/tools/hardware.yml.

+ +

If the platform has devices that do not already have corresponding drivers, you can add +them in seL4/src/drivers/ and seL4/include/drivers/.

+ +

Kernel

+ +

You will need to add seL4/libsel4/sel4_plat_include/<platform>/sel4/plat/api/constants.h. +Depending on your platform, this is either empty or requires defining the value for seL4_UserTop. +Look in the other platform files for examples similar to your platform.

+ +

You will need to add a CMake configuration file for the platform at kernel/src/plat/<platform>/config.cmake. +It is best to base the contents of this file off of other platforms of the same architecture.

+ +

Testing your seL4 port

+ +

When you contribute your port to seL4, sel4test must execute successfully and so the next +step to check that your port works would be to get +the seL4test project working.

+ +

ELF-loader

+ +

Before we can run sel4test, we need to have seL4 booting first.

+ +

Although we use U-Boot as a bootloader, there are additional steps needed to initialise the +hardware and setup system images before we can boot seL4. This is the purpose of the +ELF-loader.

+ +

The code for the ELF-loader can be found in the elfloader-tool directory at the root of +the seL4_tools repository.

+ +

Depending on your platform, you may have to make changes to the ELF-loader, which is +responsible for loading the kernel and any user-programs. The ELF-loader outputs to the +serial, so needs to be able to access the UART.

+ +

On RISC-V, outputting to UART is done via a call to the SBI layer so no changes are necessary.

+ +

On ARM, there are a variety of existing UART drivers in tools/elfloader-tool/src/drivers/uart/. +If the default serial is not supported by any of these drivers, you will have to +provide a simple putchar implementation.

+ +

If the system image that is produced by the ELF-loader build system needs be a particular file +format (e.g binary or EFI) or needs to start at a particular physical address, you can +configure the default platform options in seL4_tools/cmake-tool/helpers/application_settings.cmake.

+ +

seL4test

+ +

seL4test needs user level serial and timer drivers to run. Add these drivers and the following +files to libplatsupport +in order to get the test suite running. The directory structure and +files will look something like the following. Some of these files may not have anything in +them but include them anyway to keep the build system happy.

+ +

Use the other platforms as examples; generally you will have to configure the timer driver by +reading the manual, it may have its own unique programming sequence and can sometimes be a bit tricky.

+ +

If the technical reference manual does not contain enough detail, you may be able to gain more +information by looking at the respective Linux driver for the device. This can be done by searching +for the value of the ‘compatible’ field that is on each device node in a DTS in the Linux source code.

+ +

You can find the physical addresses and interrupt numbers for each device in its platform reference +manual and copy them into the right places.

+ +

util_libs/libplatsupport/plat_include/<platform>/

+ +
    +
  • clock.h
    • +
  • gpio.h
    • +
  • i2c.h
    • +
  • mux.h
    • +
  • serial.h
    • +
  • timer.h
    • +
+ +

util_libs/libplatsupport/src/plat/<platform>/

+ +
    +
  • chardev.c
    • +
  • ltimer.c
    • +
  • serial.c
    • +
  • timer.c
    • +
+ +

sel4test configurations

+ +

The default configuration of seL4 in sel4test is non-MCS, single-core, with no hypervisor mode.

+ +

After confirming that the default configuration successfully runs (in both debug and release mode), +it is a good idea to test the more complex configurations with your port as well.

+ +

Gotchas

+ +

Incorrect address alignment and incorrect memory regions can cause instruction faults. One way to debug this, is +to shorten memory regions in DTS memory nodes to check you are touching the correct area.

+ +

Contributing

+ +

Once you have a working port that passes seL4test, see the guides for +contributing in general +and contributing kernel changes.

+ +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4/porting.md b/projects/sel4/porting.md deleted file mode 100644 index e5bc9292653..00000000000 --- a/projects/sel4/porting.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -redirect_from: - - /PortingSeL4 -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Porting seL4 to a new platform - -This section covers porting seL4 to a new ARM or RISC-V platform if it is not -already covered in the list of [supported seL4 platforms](../../Hardware/). - -## Setup - -In order to load the seL4 image (via some means) it is important to have a working bootloader. -We tend to use [U-Boot](https://www.denx.de/wiki/U-Boot) as it is open source, reliable and supports many different architectures. - -There are a variety of ways of loading an seL4 image from U-Boot such as eMMC, TFTP, and USB. - -### TFTP setup - -For setting up a TFTP server to transfer images over the network, you can follow the -[UNSW Advanced Operating Systems course guide](https://www.cse.unsw.edu.au/~cs9242/19/project/linux.shtml). - -Once you get U-Boot up and running it is a good idea (if the platform is supported) to flash a -Linux image onto the board. This way you can find the correct address to load the image into memory. -This is also useful for debugging, as you can use the FDT file system to dump addresses from a running system. - -Once you have found the correct address to load, declare the boot command (where address 0x20000000 as an example): - -```sh -bootcmd="tftpboot 0x20000000 /path/to/image && go 0x20000000" -saveenv -``` - -For TFTP, you will also need to set some U-Boot environment variables: - -```sh -setenv ipaddr -setenv serverip -saveenv -``` - -The easiest way to find the proper load address is to query the `kernel_addr_r` variable. That's the environment variable specifying the expected address at which the kernel's binary will be found. - -### eMMC/SD card setup - -We can load an image with the following command (using `0x20000000` as an example): - -```sh -fatload mmc 0 0x20000000 /path/to/image -``` - -You can find more details in the [U-Boot documentation](https://docs.u-boot.org/en/latest/usage/cmd/fatload.html). - -## seL4 - -In order to have a successful port of seL4 to your target ARM or RISC-V platform you will need to go through the following steps. - -### Device Tree - -Device Trees are used by ARM and RISC-V platforms to describe the hardware platform. -seL4 makes use of Device Trees at build time, which is why acquiring a Device Tree Source (DTS) -for your platform is one of the first steps. - -seL4 relies on the DTS for the location and size of main memory as well as information -about certain devices used by the kernel such as the timer. In debug mode, seL4 also -makes use of the default serial device for debug output. - -Often the Device Tree Source will be included in the -[Linux kernel source](https://github.com/torvalds/linux), from there you can decompile -the device tree blob (DTB) from building the Linux kernel to get the Device Tree that -Linux uses. - -You can compile the Linux Device Tree Sources into a final Device Tree Blob with: - -```sh -make ARCH= CROSS_COMPILE= defconfig -make ARCH= CROSS_COMPILE= dtbs -``` - -The DTBs can be found in `arch//boots/dts/`. - -The following command allows you to decompile the DTB: - -```sh -dtc -I dtb -O dts /path/to/dtb -o linux.dts -``` - -It should be noted that you may need to add device nodes depending on what Linux uses -and what is required by seL4. For example, some platforms do not include a node for -main memory in the Linux Device Tree. This is because Linux can get -this information at run-time from a previous bootloader. This is not the case for seL4 -as it consumes the Device Tree at build-time. - -In the seL4 source, each platform has an overlay DTS that is responsible for dealing -with seL4-specific device nodes. Below is an example -(from the [ROCKPro64](https://github.com/seL4/seL4/blob/master/src/plat/rockpro64/overlay-rockpro64.dts)): - -```dts -/ { - chosen { - seL4,elfloader-devices = - "serial2", - &{/psci}, - &{/timer}; - seL4,kernel-devices = - "serial2", - &{/interrupt-controller@fee00000}, - &{/timer}; - }; -}; -``` - -These overlay files give a good idea of what nodes seL4 requires in the DTS other than -main memory. - -You will need to create a similar overlay DTS in `src/plat//overlay-.dts` -as part of the platform port. - -### Hardware generation script - -Depending on your platform and the way the DTS is defined you may need to modify the -`seL4/tools/hardware_gen.py` script. - -From the above example the ROCKPro64 needed a memory node so that this script could -define working memory. Other gotchas could include interrupt cells, interrupt numbers being -mapped wrongly, or incorrect addresses. - -The kernel also expects drivers for: - -* the timer device. -* the serial device. -* the interrupt controller. -* the IOMMU if the kernel is being built with IOMMU support. - -You can check all the supported drivers in `seL4/tools/hardware.yml`. - -If the platform has devices that do not already have corresponding drivers, you can add -them in `seL4/src/drivers/` and `seL4/include/drivers/`. - -### Kernel - -You will need to add `seL4/libsel4/sel4_plat_include//sel4/plat/api/constants.h`. -Depending on your platform, this is either empty or requires defining the value for `seL4_UserTop`. -Look in the other platform files for examples similar to your platform. - -You will need to add a CMake configuration file for the platform at `kernel/src/plat//config.cmake`. -It is best to base the contents of this file off of other platforms of the same architecture. - -## Testing your seL4 port - -When you contribute your port to seL4, sel4test must execute successfully and so the next -step to check that your port works would be to get -[the seL4test project](../sel4test/) working. - -### ELF-loader - -Before we can run sel4test, we need to have seL4 booting first. - -Although we use U-Boot as a bootloader, there are additional steps needed to initialise the -hardware and setup system images before we can boot seL4. This is the purpose of the -[ELF-loader](../elfloader/). - -The code for the ELF-loader can be found in the `elfloader-tool` directory at the root of -the [seL4_tools](https://github.com/seL4/seL4_tools) repository. - -Depending on your platform, you may have to make changes to the ELF-loader, which is -responsible for loading the kernel and any user-programs. The ELF-loader outputs to the -serial, so needs to be able to access the UART. - -On RISC-V, outputting to UART is done via a call to the SBI layer so no changes are necessary. - -On ARM, there are a variety of existing UART drivers in `tools/elfloader-tool/src/drivers/uart/`. -If the default serial is not supported by any of these drivers, you will have to -provide a simple putchar implementation. - -If the system image that is produced by the ELF-loader build system needs be a particular file -format (e.g binary or EFI) or needs to start at a particular physical address, you can -configure the default platform options in `seL4_tools/cmake-tool/helpers/application_settings.cmake`. - -### seL4test - -seL4test needs user level serial and timer drivers to run. Add these drivers and the following -files to [libplatsupport](https://github.com/seL4/util_libs/tree/master/libplatsupport) -in order to get the test suite running. The directory structure and -files will look something like the following. Some of these files may not have anything in -them but include them anyway to keep the build system happy. - -Use the other platforms as examples; generally you will have to configure the timer driver by -reading the manual, it may have its own unique programming sequence and can sometimes be a bit tricky. - -If the technical reference manual does not contain enough detail, you may be able to gain more -information by looking at the respective Linux driver for the device. This can be done by searching -for the value of the 'compatible' field that is on each device node in a DTS in the Linux source code. - -You can find the physical addresses and interrupt numbers for each device in its platform reference -manual and copy them into the right places. - -`util_libs/libplatsupport/plat_include//` - -* `clock.h` -* `gpio.h` -* `i2c.h` -* `mux.h` -* `serial.h` -* `timer.h` - -`util_libs/libplatsupport/src/plat//` - -* `chardev.c` -* `ltimer.c` -* `serial.c` -* `timer.c` - -### sel4test configurations - -The default configuration of seL4 in sel4test is non-MCS, single-core, with no hypervisor mode. - -After confirming that the default configuration successfully runs (in both debug and release mode), -it is a good idea to test the more complex configurations with your port as well. - -### Gotchas - -Incorrect address alignment and incorrect memory regions can cause instruction faults. One way to debug this, is -to shorten memory regions in DTS memory nodes to check you are touching the correct area. - -## Contributing - -Once you have a working port that passes seL4test, see the guides for -[contributing in general](https://sel4.systems/Contribute/) -and [contributing kernel changes](kernel-contribution.html). diff --git a/projects/sel4/releases.md b/projects/sel4/releases.md deleted file mode 100644 index 64b5dd001e9..00000000000 --- a/projects/sel4/releases.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -permalink: /releases/seL4.html -redirect_from: - - /sel4_release -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4 releases - -This page documents tagged releases of the seL4 kernel and proofs. - -## Landmark releases - -This section documents the version at which specific features were introduced to -seL4. For future features, see the [roadmap](https://sel4.systems/roadmap.html) -on the main seL4 website. For other previous features, see the release notes -below. - -For the verification status of all platforms, see [Verified -Configurations](../projects/sel4/verified-configurations.html). - -| Feature | Hardware | Available From | -| - | - | - | -| AARCH64 RPI3 | [RPI3](../Hardware/Rpi3.html) | [10.1.0](sel4/10.1.0.html) | -| TX2 support (Aarch64 only) | [TX2](../Hardware/JetsonTX2.html) | [10.1.0](sel4/10.1.0.html) | -| Support for more than 1 VM | ARM | [10.1.0](sel4/10.1.0.html) | -| 32-bit RISC-V architecture support | RISC-V (Spike simulation target) | [10.0.0](sel4/10.0.0.html) | -| 64-bit RISC-V architecture support | RISC-V (Spike simulation target) | [9.0.1](sel4/9.0.1.html) | -| Meltdown mitigation | x86 | [9.0.0](sel4/9.0.0.html) | -| Spectre mitigation | x86 | [9.0.0](sel4/9.0.0.html) | -| Zynq UltraScale+ MPSoC | Xilinx ZCU102, ARMv8a, Cortex A53 | [8.0.0](sel4/8.0.0.html) | -| Multiboot2 support | x86 | [8.0.0](sel4/8.0.0.html) | -| CMake based build system | all | [7.0.0](sel4/7.0.0.html) | -| ARM 32-bit SMP | [Sabre](../Hardware/sabreLite.html) | [6.0.0](sel4/6.0.0.html) | -| ARMv7 32-bit FPU support | ARM | [6.0.0](sel4/6.0.0.html) | -| ARM 64-bit support | Aarch64 | [5.0.0](sel4/5.0.0.html) | -| 64-bit x86 support | x86\_64 | [4.0.0](sel4/4.0.0.html) | -| Raspberry Pi 3 support | [RPI3](../Hardware/Rpi3.html) | [4.0.0](sel4/4.0.0.html) | -| ARM Hypervisor initial support | ARM | [3.2.0](sel4/3.2.0.html) | -| First ARMv8 support | [HiKey](../Hardware/HiKey/) | [3.1.0](sel4/3.1.0.html) | -| NVIDIA Tegra K1 support | [TK1](../Hardware/jetsontk1.html) | [3.0.1](sel4/3.0.1.html) | -| Notification binding | all | [2.0.0](sel4/2.0.0.html) | - -## Main releases - -{% assign coll = site['releases'] | where: "project", "sel4" %} -{% comment %} -Sort sorts by string sorting so a version of 2.3.0 is higher than 10.0.0. -Because of this we need to split the list into two before sorting. -{% endcomment %} -{% assign releases_1 = coll | where_exp:"item", "item.version_digits != 2" | sort: "version" %} -{% assign releases_2 = coll | where_exp:"item", "item.version_digits == 2" | sort: "version" %} -{% assign releases = releases_1 | concat: releases_2 %} - -{% for release in releases reversed %} -{% if release.variant != "mcs" %} -- seL4 Release [{{ release.title }}]({{ release.url | relative_url }}), - with [PDF manual](http://sel4.systems/Info/Docs/seL4-manual-{{ release.version }}.pdf) {% if forloop.first %}(latest){% endif %} -{% endif %} -{% endfor %} - -### Older Mixed Criticality Support (MCS) / Realtime releases - -As of seL4 version 11.0.0, the MCS features are included in the main kernel release, via the build option `KernelIsMCS`. Set `KernelIsMCS` to `ON` to switch the scheduler implementation to MCS and enable the MCS API. - -{% for release in releases reversed %} -{% if release.variant == "mcs" %} -- seL4 Release [{{ release.title }}]({{ release.url | relative_url }}), - corresponding [PDF manual](http://sel4.systems/Info/Docs/seL4-manual-{{ release.version }}.pdf) -{% endif %} -{% endfor %} diff --git a/projects/sel4/status.html b/projects/sel4/status.html new file mode 100644 index 00000000000..d6834212ad0 --- /dev/null +++ b/projects/sel4/status.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4/verified-configurations.html b/projects/sel4/verified-configurations.html new file mode 100644 index 00000000000..2b7ed834995 --- /dev/null +++ b/projects/sel4/verified-configurations.html @@ -0,0 +1,781 @@ + + + + + + + Verified Configurations | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Verified Configurations

+ +

This page describes which architecture/platform/configuration combinations of +seL4 have verified properties, which configurations possess which properties, +and how to obtain an seL4 version for a specified configuration. For an overview +of these properties and their explanations, please see the verification page on +the seL4 website. The Frequently Asked +Questions also as a section +on the formal verification of seL4.

+ +

The formal proofs for seL4 are hosted at https://github.com/seL4/l4v. They +are written in the Isabelle/HOL theorem prover. See +the README file in the l4v repository for build +and setup instructions if you want to run and check the proofs against a +specific version and configuration of seL4.

+ +

Examining and Building Verified Configurations

+ +

Current verified configurations can be found in seL4 sources in the +configs folder:

+ +
cd configs/
+ls *_verified.cmake
+# AARCH64_bcm2711_verified.cmake    ARM_exynos5410_verified.cmake
+# AARCH64_hikey_verified.cmake      ARM_exynos5422_verified.cmake
+# AARCH64_imx8mm_verified.cmake     ARM_hikey_verified.cmake
+# AARCH64_imx8mq_verified.cmake     ARM_HYP_exynos5_verified.cmake
+# AARCH64_imx93_verified.cmake      ARM_HYP_exynos5410_verified.cmake
+# AARCH64_maaxboard_verified.cmake  ARM_HYP_verified.cmake
+# AARCH64_odroidc2_verified.cmake   ARM_imx8mm_verified.cmake
+# AARCH64_odroidc4_verified.cmake   ARM_MCS_verified.cmake
+# AARCH64_rockpro64_verified.cmake  ARM_omap3_verified.cmake
+# AARCH64_tqma_verified.cmake       ARM_tk1_verified.cmake
+# AARCH64_tx1_verified.cmake        ARM_verified.cmake
+# AARCH64_ultra96v2_verified.cmake  ARM_zynq7000_verified.cmake
+# AARCH64_verified.cmake            ARM_zynqmp_verified.cmake
+# AARCH64_zynqmp_verified.cmake     RISCV64_MCS_verified.cmake
+# ARM_am335x_verified.cmake         RISCV64_verified.cmake
+# ARM_bcm2837_verified.cmake        X64_verified.cmake
+# ARM_exynos4_verified.cmake
+
+ +

To obtain specific source code and build for a given configuration (e.g. +ARM) in a build directory:

+ +
mkdir build
+cd build
+cmake -P ../config/ARM_verified.cmake
+
+ +

Notably kernel.elf is the kernel binary, and kernel_all_pp.c is +the kernel source code after preprocessing, which is used as the basis +for verification efforts.

+ +

Also see standalone seL4 builds for +general guidelines on generating an seL4 binary and build system information +from an existing configuration.

+ +

Available Verified Configurations

+ +

Unverified Features

+ +

At present, none of our verified configurations take into account +address translation for devices (System MMU or IOMMU), debug/profiling/printing +interfaces, or the kernel startup at boot.

+ +

The proofs for RISCV64_MCS/ARM_MCS (mixed-criticality extensions to real-time +seL4 features), as well as confidentiality proofs for AARCH64 are in progress. +Refer to the roadmap for status and +upcoming features.

+ +

Arm Aarch32 (ARM)

+ +

Configurations that start with ARM are verified configurations for the +AArch23 architecture. Those with MCS in the name indicate configurations for +the ongoing MCS verification. Proofs for all other ARM_* configurations are +completed.

+ +

The following features are supported by verification in AArch32 configurations:

+ + + +

The following properties are verified:

+ +
    +
  • C-level functional correctness, including fast path
    • +
  • integrity and availability (access control)
    • +
  • confidentiality (information flow)
    • +
  • binary correctness, covering C functions that have C-level verification
    • +
  • model-level functional correctness of the capDL user-level system initialiser/root task
    • +
+ +

The following seL4 AArch32 platforms are supported by verification:

+ + +

Arm Aarch32 in Hypervisor mode (ARM_HYP)

+ +

Configurations that start with ARM_HYP are verified configurations for the +AArch32 architecture with hypervisor mode enabled. The seL4 kernel runs as +hypervisor in EL2.

+ +

The following features are supported by verification in ARM_HYP configurations:

+ +
    +
  • Architecture: ARMv7-A 32-bit, kernel running in EL2
    • +
  • Floating point support: No
    • +
  • Hypervisor mode: Yes
    • +
+ +

The following properties are verified:

+ +
    +
  • C-level functional correctness, including fast path
    • +
+ +

The following seL4 AArch32 platforms with hypervisor mode are supported by +verification:

+ + +

Arm AArch64 (AARCH64)

+ +

Configurations that start with AARCH64 are verified configurations for the +AArch64 architecture with hypervisor mode enabled. The seL4 kernel runs as +hypervisor in EL2.

+ +

The following features are supported by verification in AARCH64 configurations:

+ +
    +
  • Architecture: ARMv8-A 64-bit, kernel running in EL2
    • +
  • Floating point support: Yes
    • +
  • Hypervisor mode: Yes
    • +
+ +

The following properties are verified:

+ +
    +
  • C-level functional correctness, including fast path
    • +
  • integrity and availability (access control)
    • +
+ +

Further properties are under development. See also the +roadmap for status and schedule.

+ +

The following seL4 AArch64 platforms are supported by verification:

+ + +

RISC-V 64-bit (RISCV64)

+ +

Configurations that start with RISCV64 are verified configurations for the +RISC-V 64-bit architecture. Those with MCS in the name indicate configurations +for the ongoing MCS verification.

+ +

The following features are supported by verification in RISCV64 configurations:

+ +
    +
  • Architecture: RISC-V 64 bit
    • +
  • Floating point support: No
    • +
  • Hypervisor mode: No
    • +
+ +

The following properties are verified:

+ +
    +
  • C-level functional correctness, no fast path
    • +
  • integrity and availability (access control)
    • +
  • confidentiality (information flow)
    • +
+ +

The following seL4 RISCV64 platforms are supported by verification:

+ + +

Intel x64 (X64)

+ +

Configurations that start with X64 are verified configurations for the +x86-64 architecture.

+ +

The following features are supported by verification in X64 configurations:

+ +
    +
  • Architecture: Intel x64
    • +
  • Floating point support: Yes
    • +
  • Hypervisor/VT-x mode: No
    • +
+ +

The following properties are verified:

+ +
    +
  • C-level functional correctness, no fast path
    • +
+ +

The following seL4 X64 platforms are supported by verification:

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4/verified-configurations.md b/projects/sel4/verified-configurations.md deleted file mode 100644 index e0d38f1c56b..00000000000 --- a/projects/sel4/verified-configurations.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -redirect_from: - - /VerifiedConfigurations -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# Verified Configurations - -This page describes which architecture/platform/configuration combinations of -seL4 have verified properties, which configurations possess which properties, -and how to obtain an seL4 version for a specified configuration. For an overview -of these properties and their explanations, please see the [verification page on -the seL4 website](https://sel4.systems/Verification/). The [Frequently Asked -Questions](https://sel4.systems/About/FAQ.html#verification) also as a section -on the formal verification of seL4. - -The formal proofs for seL4 are hosted at . They -are written in the [Isabelle/HOL](https://isabelle.in.tum.de) theorem prover. See -the [README](https://github.com/seL4/l4v/) file in the l4v repository for build -and setup instructions if you want to run and check the proofs against a -specific version and configuration of seL4. - -## Examining and Building Verified Configurations - -Current verified configurations can be found in seL4 sources in the -`configs` folder: - -```sh -cd configs/ -ls *_verified.cmake -# AARCH64_bcm2711_verified.cmake ARM_exynos5410_verified.cmake -# AARCH64_hikey_verified.cmake ARM_exynos5422_verified.cmake -# AARCH64_imx8mm_verified.cmake ARM_hikey_verified.cmake -# AARCH64_imx8mq_verified.cmake ARM_HYP_exynos5_verified.cmake -# AARCH64_imx93_verified.cmake ARM_HYP_exynos5410_verified.cmake -# AARCH64_maaxboard_verified.cmake ARM_HYP_verified.cmake -# AARCH64_odroidc2_verified.cmake ARM_imx8mm_verified.cmake -# AARCH64_odroidc4_verified.cmake ARM_MCS_verified.cmake -# AARCH64_rockpro64_verified.cmake ARM_omap3_verified.cmake -# AARCH64_tqma_verified.cmake ARM_tk1_verified.cmake -# AARCH64_tx1_verified.cmake ARM_verified.cmake -# AARCH64_ultra96v2_verified.cmake ARM_zynq7000_verified.cmake -# AARCH64_verified.cmake ARM_zynqmp_verified.cmake -# AARCH64_zynqmp_verified.cmake RISCV64_MCS_verified.cmake -# ARM_am335x_verified.cmake RISCV64_verified.cmake -# ARM_bcm2837_verified.cmake X64_verified.cmake -# ARM_exynos4_verified.cmake -``` - -To obtain specific source code and build for a given configuration (e.g. -ARM) in a build directory: - -```sh -mkdir build -cd build -cmake -P ../config/ARM_verified.cmake -``` - -Notably ``kernel.elf`` is the kernel binary, and ``kernel_all_pp.c`` is -the kernel source code after preprocessing, which is used as the basis -for verification efforts. - -Also see [standalone seL4 builds](../buildsystem/standalone.md) for -general guidelines on generating an seL4 binary and build system information -from an existing configuration. - -## Available Verified Configurations - -### Unverified Features - -At present, none of our verified configurations take into account -address translation for devices (System MMU or IOMMU), debug/profiling/printing -interfaces, or the kernel startup at boot. - -The proofs for RISCV64\_MCS/ARM\_MCS (mixed-criticality extensions to real-time -seL4 features), as well as confidentiality proofs for AARCH64 are in progress. -Refer to the [roadmap](https://sel4.systems/roadmap.html) for status and -upcoming features. - -### Arm Aarch32 (`ARM`) {#ARM} - -Configurations that start with `ARM` are verified configurations for the -AArch23 architecture. Those with `MCS` in the name indicate configurations for -the ongoing MCS verification. Proofs for all other `ARM_*` configurations are -completed. - -The following features are supported by verification in AArch32 configurations: - -- Architecture: ARMv7-A 32-bit, kernel running in EL1 -- Floating point support: No -- Hypervisor mode: No ([see separate AArch32/Hypervisor configurations](#ARM_HYP)) - -The following properties are verified: - -- C-level functional correctness, including fast path -- integrity and availability (access control) -- confidentiality (information flow) -- binary correctness, covering C functions that have C-level verification -- model-level functional correctness of the capDL user-level system initialiser/root task - -The following seL4 AArch32 platforms are supported by verification: - -{%- assign sorted = site.pages | sort: 'platform' %} -{%- for plat in sorted %} -{%- if plat.arm_hardware and plat.Maintained -%} -{%- if plat.verification contains "ARM" %} -- [{{plat.platform}}]({{plat.url}}) -{%- endif %} -{%- endif %} -{%- endfor %} - - -### Arm Aarch32 in Hypervisor mode (`ARM_HYP`) {#ARM_HYP} - -Configurations that start with `ARM_HYP` are verified configurations for the -AArch32 architecture with hypervisor mode enabled. The seL4 kernel runs as -hypervisor in EL2. - -The following features are supported by verification in ARM_HYP configurations: - -- Architecture: ARMv7-A 32-bit, kernel running in EL2 -- Floating point support: No -- Hypervisor mode: Yes - -The following properties are verified: - -- C-level functional correctness, including fast path - -The following seL4 AArch32 platforms with hypervisor mode are supported by -verification: - -{%- assign sorted = site.pages | sort: 'platform' %} -{%- for plat in sorted %} -{%- if plat.arm_hardware and plat.Maintained -%} -{%- if plat.verification contains "ARM_HYP" %} -- [{{plat.platform}}]({{plat.url}}) -{%- endif %} -{%- endif %} -{%- endfor %} - - -### Arm AArch64 (`AARCH64`) {#AARCH64} - -Configurations that start with `AARCH64` are verified configurations for the -AArch64 architecture with hypervisor mode enabled. The seL4 kernel runs as -hypervisor in EL2. - -The following features are supported by verification in AARCH64 configurations: - -- Architecture: ARMv8-A 64-bit, kernel running in EL2 -- Floating point support: Yes -- Hypervisor mode: Yes - -The following properties are verified: - -- C-level functional correctness, including fast path -- integrity and availability (access control) - -Further properties are under development. See also the -[roadmap](https://sel4.systems/roadmap.html) for status and schedule. - -The following seL4 AArch64 platforms are supported by verification: - -{%- assign sorted = site.pages | sort: 'platform' %} -{%- for plat in sorted %} -{%- if plat.arm_hardware and plat.Maintained -%} -{%- if plat.verification contains "AARCH64" %} -- [{{plat.platform}}]({{plat.url}}) -{%- endif %} -{%- endif %} -{%- endfor %} - - -### RISC-V 64-bit (`RISCV64`) {#RISCV64} - -Configurations that start with `RISCV64` are verified configurations for the -RISC-V 64-bit architecture. Those with `MCS` in the name indicate configurations -for the ongoing MCS verification. - -The following features are supported by verification in RISCV64 configurations: - -- Architecture: RISC-V 64 bit -- Floating point support: No -- Hypervisor mode: No - -The following properties are verified: - -- C-level functional correctness, no fast path -- integrity and availability (access control) -- confidentiality (information flow) - -The following seL4 RISCV64 platforms are supported by verification: - -{%- assign sorted = site.pages | sort: 'platform' %} -{%- for plat in sorted %} -{%- if plat.riscv_hardware and plat.Maintained -%} -{%- if plat.verification contains "RISCV64" %} -- [{{plat.platform}}]({{plat.url}}) -{%- endif %} -{%- endif %} -{%- endfor %} - - -### Intel x64 (`X64`) {#X64} - -Configurations that start with `X64` are verified configurations for the -x86-64 architecture. - -The following features are supported by verification in X64 configurations: - -- Architecture: Intel x64 -- Floating point support: Yes -- Hypervisor/VT-x mode: No - -The following properties are verified: - -- C-level functional correctness, no fast path - -The following seL4 X64 platforms are supported by verification: - -{%- assign sorted = site.pages | sort: 'platform' %} -{%- for plat in sorted %} -{%- if plat.arch == "x64" and plat.Maintained -%} -{%- if plat.verification contains "X64" %} -- [{{plat.platform}}]({{plat.url}}) -{%- endif %} -{%- endif %} -{%- endfor %} diff --git a/projects/sel4_tools/index.html b/projects/sel4_tools/index.html new file mode 100644 index 00000000000..5214077825d --- /dev/null +++ b/projects/sel4_tools/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4_tools/index.md b/projects/sel4_tools/index.md deleted file mode 100644 index f1a51b31893..00000000000 --- a/projects/sel4_tools/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: https://github.com/seL4/seL4_tools/tree/master/misc -project: sel4_tools -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/projects/sel4bench/index.html b/projects/sel4bench/index.html new file mode 100644 index 00000000000..cc5e39c5c09 --- /dev/null +++ b/projects/sel4bench/index.html @@ -0,0 +1,1029 @@ + + + + + + + The sel4bench Suite | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

The sel4bench Suite

+ +

sel4bench is an application and support library for benchmarking the +performance of the seL4 kernel.

+ +

A selection of benchmarking results are continually updated on the main seL4 +website. The page also +shows the build options used to obtain those results.

+ +

Sources:

+ + + +

Getting the code

+ +

First make sure you have set up your +machine. Then run the following.

+ +
mkdir sel4bench
+cd sel4bench
+repo init -u https://github.com/seL4/sel4bench-manifest.git
+repo sync
+
+ +

This clones the seL4 kernel, the benchmarking suite including libraries, and +tools used in the build process. By default, the current master branch of the +kernel is cloned. To clone a specific version of the kernel and compatible +libraries and tools, replace the line

+ +
repo init https://github.com/seL4/sel4bench-manifest.git
+
+ +

above with e.g.:

+ +
repo init -u https://github.com/seL4/sel4bench-manifest.git -b refs/tags/14.0.0
+
+ +

This example clones version 14.0.0 of the kernel. For more information on +version numbers, see the release page and the list of +seL4 releases.

+ +

Building and running sel4bench

+ +

Configuration

+ +

The CMake build environment supports a number of platforms. For information on +which ones these are and their corresponding CMake configuration arguments, see +the Supported Platforms page.

+ +

For the available meta configuration options, see below.

+ +

For example, to enable the optional Fault benchmark set and build for the +sabre platform, we would use the following invocation.

+ +
# create build directory
+mkdir build
+cd build
+# configure build directory
+../init-build.sh -DPLATFORM=sabre -DFAULT=ON
+
+ +

Building

+ +

After you have configured the system, you can build it by running:

+ +
ninja
+
+ +

Running it

+ +

The build step above will produce a bootable image file in the images/ +directory. Please refer to the documentation of the respective build platform +for how to boot the specific board with such an image.

+ +

Available Benchmarks

+ +

The following table lists the available benchmark sets. Measured from user +space means that the benchmark is not instrumenting the kernel. This means it +measures unmodified kernel code, but may consequently have lower precision +than some of the other benchmarks.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
Fault
+
+
+

Fault delivery, measured from user space

+ +
+
+
Hardware
+
+
+

Hardware-related seL4 operations

+ +
+
+
IPC
+
+
+

A benchmark of the kernel IPC path

+ +
+
+
IRQ
+
+
+

The IRQ path, measured from inside the kernel.

+ +
+
+
IRQ user
+
+
+

The IRQ path, measured from user space.

+ +
+
+
Page mapping
+
+
+

Performance of mapping a series of pages

+ +
+
+
Scheduler
+
+
+

Benchmark for scheduling decisions, using a producer/consumer pattern between two notification objects. Also measures seL4_Yield().

+ +
+
+
Signal
+
+
+

The seL4 signal operation, measured from user space

+ +
+
+
SMP
+
+
+

Intra-core IPC round-trip benchmark to measure overhead of kernel synchronization on IPC throughput.

+ +
+
+
Synchronisation library
+
+
+

Measuring the user-level seL4 sync library

+ +
+
+
Aarch64 VCPU
+
+
+

seL4 VCPU performance, including privilege escalation from EL1 to EL2 with HVC, privilege de-escalation from EL2 to EL1 with ERET, null invocation of the EL2 kernel using HVC, cost of seL4_Call() from an EL1 guest thread to a native seL4 thread, and cost of an seL4_Reply() from an seL4 native thread to an EL1 guest thread. See the sel4bench repository README for instructions.

+ +
+ +

Configuration Options

+ +

Kernel configuration settings can have a large effect on the end results +reported by the benchmarks. Some benchmarks will only work in certain +configurations. To make it easier to configure a build of seL4bench that has the +right configuration values set, use the meta-configuration options listed below.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
RELEASE
+
+
+

Performance optimized build

+ +
+
+ (Default: ON) +
+
+ 
HARDWARE
+
+
+

Configuration for sel4bench hardware app

+ +
+
+ (Default: OFF) +
+
+ 
FAULT
+
+
+

Configuration sel4bench fault app

+ +
+
+ (Default: OFF) +
+
+ 
VCPU
+
+
+

Whether or not to run the VCPU benchmarks

+ +
+
+ (Default: OFF) +
+
+ 
SMP
+
+
+

Configuration sel4bench smp app

+ +
+
+ (Default: OFF) +
+
+ 
PLATFORM
+
+
+

Platform to test

+ +
+
+ (Default: x86_64) +
+
+ 
FASTPATH
+
+
+

Turn fastpath on or off

+ +
+
+ (Default: ON) +
+
+ 
ARM_HYP
+
+
+

ARM EL2 hypervisor features on or off

+ +
+
+ (Default: OFF) +
+ +

Implementation

+ +

Benchmark runner

+ +

seL4bench must be started directly by seL4 as the root-task in the system. This +is the sel4bench binary, which also serves as the main benchmark runner. It +runs the configured benchmarks and sets up a new environment for each benchmark +to run in. When a benchmark completes, it reports the results back to the runner +and the runner prints the results out as JSON once all the benchmarks have +completed.

+ +

Benchmarking environment

+ +

Each benchmark runs in a separate process environment. Currently there is only a +single kind of environment that all benchmarking apps are expected to execute +in. This environment defines the set of system resources that each benchmark is +given to run with. It also provides the configuration options for each +benchmark. Each benchmark can provide an init function and a parse_results +function that will get called in the main sel4bench app. Otherwise all +benchmark functionality runs in the environment.

+ +

The libsel4benchsupport library provides environment functions that the +benchmarks can call.

+ +

Adding a new benchmark

+ +

For adding new benchmarks see the sel4bench repository +README.

+ +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/sel4bench/index.md b/projects/sel4bench/index.md deleted file mode 100644 index e6a61ec8e62..00000000000 --- a/projects/sel4bench/index.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -project: sel4bench -toc: true -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# The sel4bench Suite - -_sel4bench_ is an application and support library for benchmarking the -performance of the seL4 kernel. - -A selection of benchmarking results are continually updated on the main [seL4 -website](https://sel4.systems/performance.html#perf-numbers). The page also -shows the build options used to obtain those results. - -Sources: - -- -- - -## Getting the code - -First make sure you have [set up your -machine](../buildsystem/host-dependencies.html). Then run the following. - -{%- assign manifest = "https://github.com/seL4/sel4bench-manifest.git" %} - -```bash -mkdir sel4bench -cd sel4bench -repo init -u {{manifest}} -repo sync -``` - -This clones the seL4 kernel, the benchmarking suite including libraries, and -tools used in the build process. By default, the current master branch of the -kernel is cloned. To clone a specific version of the kernel and compatible -libraries and tools, replace the line - -```bash -repo init {{manifest}} -``` - -above with e.g.: - -```bash -repo init -u {{manifest}} -b refs/tags/{{site.sel4}} -``` - -This example clones version {{site.sel4}} of the kernel. For more information on -version numbers, see the [release page](../../releases.html) and the list of -[seL4 releases](../../releases/seL4.html). - -## Building and running sel4bench - -### Configuration - -The CMake build environment supports a number of platforms. For information on -which ones these are and their corresponding CMake configuration arguments, see -the [Supported Platforms](../../Hardware) page. - -For the available meta configuration options, see [below](#configuration-options). - -For example, to enable the optional _Fault_ benchmark set and build for the -`sabre` platform, we would use the following invocation. - -```bash -# create build directory -mkdir build -cd build -# configure build directory -../init-build.sh -DPLATFORM=sabre -DFAULT=ON -``` - -### Building - -After you have configured the system, you can build it by running: - -```bash -ninja -``` - -### Running it - -The build step above will produce a bootable image file in the `images/` -directory. Please refer to the documentation of the respective build platform -for how to boot the specific board with such an image. - -## Available Benchmarks - -The following table lists the available benchmark sets. _Measured from user -space_ means that the benchmark is not instrumenting the kernel. This means it -measures unmodified kernel code, but may consequently have lower precision -than some of the other benchmarks. - -{% include config_list.md project='sel4bench' list='components' - type='sel4bench-application' code=false no_status=true %} - -## Configuration Options - -Kernel configuration settings can have a large effect on the end results -reported by the benchmarks. Some benchmarks will only work in certain -configurations. To make it easier to configure a build of seL4bench that has the -right configuration values set, use the meta-configuration options listed below. - -{% include config_list.md project='sel4bench' %} - -## Implementation - -### Benchmark runner - -seL4bench must be started directly by seL4 as the root-task in the system. This -is the `sel4bench` binary, which also serves as the main benchmark runner. It -runs the configured benchmarks and sets up a new environment for each benchmark -to run in. When a benchmark completes, it reports the results back to the runner -and the runner prints the results out as JSON once all the benchmarks have -completed. - -### Benchmarking environment - -Each benchmark runs in a separate process environment. Currently there is only a -single kind of environment that all benchmarking apps are expected to execute -in. This environment defines the set of system resources that each benchmark is -given to run with. It also provides the configuration options for each -benchmark. Each benchmark can provide an `init` function and a `parse_results` -function that will get called in the main `sel4bench` app. Otherwise all -benchmark functionality runs in the environment. - -The `libsel4benchsupport` library provides environment functions that the -benchmarks can call. - -### Adding a new benchmark - -For adding new benchmarks see the [sel4bench repository -README](https://github.com/sel4/sel4bench/). diff --git a/projects/sel4bench/status.html b/projects/sel4bench/status.html new file mode 100644 index 00000000000..3758aef08a2 --- /dev/null +++ b/projects/sel4bench/status.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4runtime/index.html b/projects/sel4runtime/index.html new file mode 100644 index 00000000000..cfd6a89f961 --- /dev/null +++ b/projects/sel4runtime/index.html @@ -0,0 +1,674 @@ + + + + + + + The seL4 run-time | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

The seL4 Run-time

+ +

This provides a minimal runtime for running a C or C-compatible process, +i.e. one with a C-like main, in a minimal seL4 environment.

+ +

This runtime provides mechanisms for accessing everything a standard +process would expect to need at start and provides additional utilities +for delegating the creation of processes and threads.

+ +

Standard Processes

+ +

All processes (except for the root task) will use the entry-points +provided here as normal and require the _start entry-point provided in +the architecture-dependant crt0.S. This will then bootstrap into the +runtime entry-point __sel4_start_c which simply processes the stack to +find the argument, environment, and auxiliary vectors.

+ +

The found vectors, along withmain, are passed into +__sel4_start_main which configures the runtime before starting +main.

+ +

Root Task

+ +

The root task requires an alternate entry-point _sel4_start which +assumes that the seL4_BootInfo argument has been passed to it and that +it has not been given a stack.

+ +

This entry-point moves onto a static 16 kilobyte stack before invoking +__sel4_start_root, which constructs the argument, environment, and +auxiliary vectors. It then passes the constructed vectors, along with +main, into __sel4_start_main which configures the runtime before +starting main.

+ +

Thread-local storage layout

+ +

There are two standard layouts for thread local storage commonly used. +One where the TLS base address refers to the first address in memory of +the region and one where it refers to the address that immediately +follows the region. Intel’s x86_64 and ia32 architectures use the latter +method as it aligns with the segmentation view of memory presented by +the processor. Most other platforms use former method, where the TLS can +be said to be ‘above’ the thread pointer.

+ +

In order to store metadata for the current thread in the same memory +allocation as the TLS, the run-time utilises memory on the other side of +the thread pointer for it’s thread structure.

+ + + +

C Run-time

+ +

The standard convention for a static C run-time provides the following 3 +files:

+ +
    +
  • crt0.o; This provides the _start symbol which is used as the entry +point into a C program.
    • +
  • crti.o; This provides the prologue to the _init and _fini +symbols. As it occurs in the linker arguments before other object +files, other object files may add function calls to the body of these +symbols.
    • +
  • crtn.o; This provides the epilogue to the _init and _fini +symbols and occurs in the linker arguments after all other object +files.
    • +
+ +

Constructors and Destructors.

+ +

The C runtime provides a mechanism for providing functions to be +executed before and after main as constructors and destructors for +object files and global state.

+ +

There are two mechanisms that provide this as documented in the System +V ABI.

+ +

The first is the aforementioned _init and _fini symbols. The second +is a set of regions called .preinit_array, .init_array, and +.fini_array. Each of these is simply a vector of void function +pointers to be executed.

+ +

The runtime must, before main, execute _init, all function pointers +in .preinit_array, then all function pointers in .init_array. The +runtime must also, at exit, execute all function pointers in +.fini_array in reverse, then execute _fini.

+ +

To assist in iterating through these arrays, GCC’s internal linker +script defines the symbols __(preinit,init,fini)_array_(start,end) in +the appropriate sections marking the first function in each and the end +of the array.

+ +

The _start Symbol

+ +

Arguments to _start are on the stack for all platforms. +The top of the stack is structured as so:

+ +
    +
  • argument count
    • +
  • array of argument pointers
    • +
  • an empty string
    • +
  • array of environment pointers
    • +
  • a null terminator
    • +
  • array of auxiliary vector entries
    • +
  • an ‘zero’ auxiliary vector
    • +
  • unspecified data
    • +
+ +

For simplicity, we simply pass a pointer to the stack to the C entry in +the runtime and dissasemble the stack there. The entry we use is as +follows:

+ +
void __sel4_start_c(void *stack);
+
+ +

NOTE: __sel4_start_c is a void function as it should call the +non-returning _exit symbol after calling main.

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/sel4runtime/index.md b/projects/sel4runtime/index.md deleted file mode 100644 index 41eff3efdb7..00000000000 --- a/projects/sel4runtime/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: The seL4 run-time -repo: 'sel4/sel4runtime' -include_file: README.md -project: sel4runtime -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -{% include include_github_repo_markdown.md %} - -{% include include_github_repo_markdown.md file= 'crt/README.md' indent_headings=true %} diff --git a/projects/sel4test/index.html b/projects/sel4test/index.html new file mode 100644 index 00000000000..25a9bf719de --- /dev/null +++ b/projects/sel4test/index.html @@ -0,0 +1,1099 @@ + + + + + + + seL4Test | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4Test

+ +

seL4test is a test suite for seL4. It is useful for developing seL4 itself, for +making sure that your development environment is set up correctly, and for +validating properties that are not part of the formal verification of seL4.

+ +

Sources:

+ + + +

Getting the Code

+ +

First make sure you have set up your +machine. Then run the following.

+ +
mkdir sel4test
+cd sel4test
+repo init -u https://github.com/seL4/sel4test-manifest.git
+repo sync
+ls
+# apps/ CMakeLists.txt init-build.sh kernel libs/ projects/ tools/
+
+ +

This clones the seL4 kernel, the test suite, some libraries used by the +tests, and some tools used in the build process. By default, the current +master branch of the kernel is cloned. To clone a specific version of +the kernel and compatible libraries and tools, replace the line

+ +
repo init https://github.com/seL4/sel4test-manifest.git
+
+ +

above with e.g.:

+ +
repo init -u https://github.com/seL4/sel4test-manifest.git -b refs/tags/14.0.0
+
+ +

In this example we clone version 14.0.0 of the kernel. For more +information on version numbers, see the release page and +the list of seL4 releases.

+ +

Building seL4test

+ +

Configuration

+ +

The CMake build environment supports a number of platforms. For information on +which ones these are and their corresponding CMake configuration arguments, see +the Supported Platforms page.

+ +

To start a build with a specific configuration we can create a new subdirectory +from the project root and initialise it with init-build. In the example below +we are using ia32 as the platform, building in release mode, and with +simulation support switched on.

+ +
# create build directory
+mkdir build
+cd build
+# configure build directory
+../init-build.sh -DPLATFORM=ia32 -DRELEASE=TRUE -DSIMULATION=TRUE
+
+ +

The general more form of the last command is

+ +
../init-build.sh -DPLATFORM=<platform-name> -DRELEASE=[TRUE|FALSE] -DSIMULATION=[TRUE|FALSE]
+
+ +

See below for the full list of available options.

+ +

This configures your build directory with the necessary CMake configuration for +your chosen platform.

+ +

You can look at and edit the CMake configuration options from your build +directory using

+ +
ccmake .
+
+ +

It is also important to note that meta options such as PLATFORM and +SIMULATION will override various settings in the seL4test build system in +order to maintain the meta configuration. If you want to control these settings +yourself, this behaviour can be disabled by setting the +Sel4testAllowSettingsOverride variable.

+ +

Building

+ +

When you’ve configured the system, you can build it by running:

+ +
ninja
+
+ +

Running it

+ +

IA32 Example

+ +

If you have followed the example instructions above, and ninja has completed +successfully, the build will have produced boot images in the images/ +directory and a simulate script. It was produced, because we passed +-DSIMULATION=TRUE to CMake. The option is available for hardware platforms +that are marked as “Simulation target: yes” on their platform info page (e.g. +for IA32).

+ +

Executing the simulate script will run QEMU and point it towards the image we +just built:

+ +
./simulate
+
+ +

It should produce output such as the following

+ +
...
+ELF-loading userland images from boot modules:
+size=0x1dd000 v_entry=0x806716f v_start=0x8048000 v_end=0x8225000 p_start=0x21f000 p_end=0x3fc000
+Moving loaded userland images to final location: from=0x21f000 to=0x12e000 size=0x1dd000
+Starting node #0 with APIC ID 0
+Booting all finished, dropped to user space
+...
+Starting test 18: BIND0001
+Running test BIND0001 (Test that a bound tcb waiting on a sync endpoint receives normal sync ipc and notification notifications.)
+Test BIND0001 passed
+Starting test 19: BIND0002
+Running test BIND0002 (Test that a bound tcb waiting on its bound notification recieves notifications)
+Test BIND0002 passed
+Starting test 20: BIND0003
+Running test BIND0003 (Test IPC ordering 1) bound tcb waits on bound notification 2, true) another tcb sends a message)
+Test BIND0003 passed
+...
+
+ +

To exit QEMU, press Ctrl-a, then x. In DEBUG configurations, there will be +error messages printed for negative tests. These are expected. The text All is +well in the universe at the end indicates a successful run.

+ +

Testing a Customised Kernel

+ +

Suppose you’ve got seL4 checked out in ~/projects/seL4, and sel4test in +~/tests/sel4test, and you have been making changes on a feature branch of seL4 +named awesome-new-feature. You want to test if your modified kernel still +passes all the tests in sel4test:

+ +
cd ~/tests/sel4tests/kernel
+git remote add feature ~/projects/seL4
+git fetch feature
+git checkout feature/awesome-new-feature
+cd ..
+
+ +

Now the kernel in sel4test has been changed to your custom kernel. +Now just build and run the test suite as above.

+ +

Running a subset of the tests

+ +

You can use a regular expression to select a subset of the tests. This can be +configured by setting the CMake variable LibSel4TestPrinterRegex. We can +modify this variable by running ccmake . in our build directory. By default +the test suite runs all tests.

+ +

Configuration Options

+ +

The set of tests that get run will be different for different kernel +configurations. Each test can specify config requirements that will prevent the +test from being run if a certain config option is incompatible. This means that +changing the build configuration can change which tests will be run. To make it +easier to configure a build of seL4test that enables the right coverage of +tests, seL4test provides a selection of meta-configuration options, listed +below.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
SIMULATION
+
+
+

Include only simulation compatible tests

+ +
+
+ (Default: OFF) +
+
+ 
RELEASE
+
+
+

Performance optimized build

+ +
+
+ (Default: OFF) +
+
+ 
VERIFICATION
+
+
+

Only verification friendly kernel features

+ +
+
+ (Default: OFF) +
+
+ 
BAMBOO
+
+
+

Enable machine parseable xml output

+ +
+
+ (Default: OFF) +
+
+ 
DOMAINS
+
+
+

Test multiple domains

+ +
+
+ (Default: OFF) +
+
+ 
SMP
+
+
+

(if supported) Test SMP kernel

+ +
+
+ (Default: OFF) +
+
+ 
NUM_NODES
+
+
+

(if SMP) The number of nodes

+ +
+
+ (Default: 4) +
+
+ 
PLATFORM
+
+
+

Platform to test

+ +
+
+ (Default: x86_64) +
+
+ 
ARM_HYP
+
+
+

Hyp mode for ARM platforms

+ +
+
+ (Default: OFF) +
+
+ 
MCS
+
+
+

MCS kernel

+ +
+
+ (Default: OFF) +
+
+ 
KernelSel4Arch
+
+
+

aarch32, aarch64, arm_hyp, ia32, x86_64, riscv32, riscv64

+ +
+
+ (Default: set by PLATFORM) +
+
+ 
LibSel4TestPrinterRegex
+
+
+

A POSIX regex pattern used to filter tests

+ +
+
+ (Default: .*) +
+
+ 
LibSel4TestPrinterHaltOnTestFailure
+
+
+

Halt on the first test failure

+ +
+
+ (Default: OFF) +
+
+ 
Sel4testAllowSettingsOverride
+
+
+

Do not use meta options above, expect manual user config settings for the kernel instead

+ +
+
+ (Default: OFF) +
+ +

For an overview of the CMake build system and further configuration options for +the kernel, including configuring for cross compilation (e.g., targeting Arm or +RISC-V on an x86 build machine), see the page on seL4’s CMake Build +System.

+ +

Implementation

+ +

This section gives a short overview of the implementation architecture of the +test suite.

+ +

Test runner

+ +

seL4test must be started directly by seL4 as the root-task in the +system. This is the sel4test-driver binary, which also serves as the main +test runner. It runs the configured tests and sets up the required +environment for each test. It prints out test results over a serial connection.

+ +

Test environments

+ +

Each test runs in a test environment. This environment provides the test with an +expected set of system resources required for it to run. There are currently two +test environments, listed below. It is possible to define more, for instance for +different system dependencies of the tests.

+ + + + + + + + + + + + + + + + + + + +
+
+
BASIC test type
+
+
+

General test type where test is launched in own process and can report test results to driver over IPC.

+ +
+
+
BOOTSTRAP test type
+
+
+

Bootstrapping test type where each test is called in the same address space as the test driver. Used for testing functionality required for BASIC test type.

+ +
+ +

Test declarations

+ +

Tests can be declared in any library that can be linked with sel4test +applications. A test is defined by using a preprocessor macro defined by its +test environment. This will place the test into a named linker section that the +test runner will use to launch the test at runtime inside its requested +environment.

+ +

See the sel4test repository README for more +information on how to add new tests.

+ +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/sel4test/index.md b/projects/sel4test/index.md deleted file mode 100644 index 06df5c9cec9..00000000000 --- a/projects/sel4test/index.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -redirect_from: - - /seL4Test -toc: true -project: sel4test -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# seL4Test - -seL4test is a test suite for seL4. It is useful for developing seL4 itself, for -making sure that your development environment is set up correctly, and for -validating properties that are not part of the formal verification of seL4. - -Sources: - -- -- - - -## Getting the Code - -First make sure you have [set up your -machine](../buildsystem/host-dependencies.html). Then run the following. - -{%- assign manifest = "https://github.com/seL4/sel4test-manifest.git" %} - -```bash -mkdir sel4test -cd sel4test -repo init -u {{manifest}} -repo sync -ls -# apps/ CMakeLists.txt init-build.sh kernel libs/ projects/ tools/ -``` - -This clones the seL4 kernel, the test suite, some libraries used by the -tests, and some tools used in the build process. By default, the current -master branch of the kernel is cloned. To clone a specific version of -the kernel and compatible libraries and tools, replace the line - -```bash -repo init {{manifest}} -``` - -above with e.g.: - -```bash -repo init -u {{manifest}} -b refs/tags/{{site.sel4}} -``` - -In this example we clone version {{site.sel4}} of the kernel. For more -information on version numbers, see the [release page](../../releases.html) and -the list of [seL4 releases](../../releases/seL4.html). - -## Building seL4test - -### Configuration - -The CMake build environment supports a number of platforms. For information on -which ones these are and their corresponding CMake configuration arguments, see -the [Supported Platforms](../../Hardware) page. - -To start a build with a specific configuration we can create a new subdirectory -from the project root and initialise it with `init-build`. In the example below -we are using `ia32` as the platform, building in release mode, and with -simulation support switched on. - -```bash -# create build directory -mkdir build -cd build -# configure build directory -../init-build.sh -DPLATFORM=ia32 -DRELEASE=TRUE -DSIMULATION=TRUE -``` - -The general more form of the last command is - -```sh -../init-build.sh -DPLATFORM= -DRELEASE=[TRUE|FALSE] -DSIMULATION=[TRUE|FALSE] -``` - -See below for the full list of [available options](#configuration-options). - -This configures your build directory with the necessary CMake configuration for -your chosen platform. - -You can look at and edit the CMake configuration options from your build -directory using - -```bash -ccmake . -``` - -It is also important to note that meta options such as `PLATFORM` and -`SIMULATION` will override various settings in the seL4test build system in -order to maintain the meta configuration. If you want to control these settings -yourself, this behaviour can be disabled by setting the -`Sel4testAllowSettingsOverride` variable. - - -### Building - -When you've configured the system, you can build it by running: - -```bash -ninja -``` - -## Running it - -### IA32 Example - -If you have followed the example instructions above, and `ninja` has completed -successfully, the build will have produced boot images in the `images/` -directory and a `simulate` script. It was produced, because we passed -`-DSIMULATION=TRUE` to CMake. The option is available for hardware platforms -that are marked as "Simulation target: yes" on their platform info page (e.g. -for [IA32](../../Hardware/IA32.md)). - -Executing the `simulate` script will run QEMU and point it towards the image we -just built: - -```bash -./simulate -``` - -It should produce output such as the following - -``` -... -ELF-loading userland images from boot modules: -size=0x1dd000 v_entry=0x806716f v_start=0x8048000 v_end=0x8225000 p_start=0x21f000 p_end=0x3fc000 -Moving loaded userland images to final location: from=0x21f000 to=0x12e000 size=0x1dd000 -Starting node #0 with APIC ID 0 -Booting all finished, dropped to user space -... -Starting test 18: BIND0001 -Running test BIND0001 (Test that a bound tcb waiting on a sync endpoint receives normal sync ipc and notification notifications.) -Test BIND0001 passed -Starting test 19: BIND0002 -Running test BIND0002 (Test that a bound tcb waiting on its bound notification recieves notifications) -Test BIND0002 passed -Starting test 20: BIND0003 -Running test BIND0003 (Test IPC ordering 1) bound tcb waits on bound notification 2, true) another tcb sends a message) -Test BIND0003 passed -... -``` - -To exit QEMU, press `Ctrl-a`, then `x`. In `DEBUG` configurations, there will be -error messages printed for negative tests. These are expected. The text `All is -well in the universe` at the end indicates a successful run. - -## Testing a Customised Kernel - -Suppose you've got seL4 checked out in `~/projects/seL4`, and `sel4test` in -`~/tests/sel4test`, and you have been making changes on a feature branch of seL4 -named `awesome-new-feature`. You want to test if your modified kernel still -passes all the tests in `sel4test`: - -```bash -cd ~/tests/sel4tests/kernel -git remote add feature ~/projects/seL4 -git fetch feature -git checkout feature/awesome-new-feature -cd .. -``` - -Now the kernel in `sel4test` has been changed to your custom kernel. -Now just build and run the test suite as above. - -## Running a subset of the tests - -You can use a regular expression to select a subset of the tests. This can be -configured by setting the CMake variable `LibSel4TestPrinterRegex`. We can -modify this variable by running `ccmake .` in our build directory. By default -the test suite runs all tests. - -## Configuration Options - -The set of tests that get run will be different for different kernel -configurations. Each test can specify config requirements that will prevent the -test from being run if a certain config option is incompatible. This means that -changing the build configuration can change which tests will be run. To make it -easier to configure a build of seL4test that enables the right coverage of -tests, seL4test provides a selection of meta-configuration options, listed -below. - -{% include config_list.md project='sel4test' %} - -For an overview of the CMake build system and further configuration options for -the kernel, including configuring for cross compilation (e.g., targeting Arm or -RISC-V on an x86 build machine), see the page on seL4's [CMake Build -System](../buildsystem/using.html). - -## Implementation - -This section gives a short overview of the implementation architecture of the -test suite. - -### Test runner - -seL4test must be started directly by seL4 as the root-task in the -system. This is the `sel4test-driver` binary, which also serves as the main -test runner. It runs the configured tests and sets up the required -environment for each test. It prints out test results over a serial connection. - -### Test environments - -Each test runs in a test environment. This environment provides the test with an -expected set of system resources required for it to run. There are currently two -test environments, listed below. It is possible to define more, for instance for -different system dependencies of the tests. - -{% include component_list.md project='sel4test' type='test-environment' no_status=true code=false %} - - -### Test declarations - -Tests can be declared in any library that can be linked with sel4test -applications. A test is defined by using a preprocessor macro defined by its -test environment. This will place the test into a named linker section that the -test runner will use to launch the test at runtime inside its requested -environment. - -See the [sel4test repository README](https://github.com/seL4/sel4test) for more -information on how to add new tests. diff --git a/projects/sel4test/status.html b/projects/sel4test/status.html new file mode 100644 index 00000000000..b38d9f0fec8 --- /dev/null +++ b/projects/sel4test/status.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4webserver/index.html b/projects/sel4webserver/index.html new file mode 100644 index 00000000000..c237e37601b --- /dev/null +++ b/projects/sel4webserver/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/sel4webserver/index.md b/projects/sel4webserver/index.md deleted file mode 100644 index f149a2a1e64..00000000000 --- a/projects/sel4webserver/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -archive: true -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. -redirect_to: https://github.com/seL4/sel4webserver/blob/master/README.md ---- diff --git a/projects/user_libs/index.html b/projects/user_libs/index.html new file mode 100644 index 00000000000..7b7820bd9a5 --- /dev/null +++ b/projects/user_libs/index.html @@ -0,0 +1,3084 @@ + + + + + + + User-level C libraries | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

User-level C libraries

+ +

The following collection of C libraries is useful for prototyping directly on +the seL4 API. They are meant for trying things out, not for production code. +They are not verified and come with no particular code assurance. They are +provided because they might be useful for experimentation.

+ +

For production code we recommend the seL4 Microkit, or CAmkES when the +Microkit is not applicable, and the Rust libraries for more dynamic systems.

+ +

Microkit does not use these libraries and expects a separate development +environment for user-level code. Some CAmkES example applications do use the +libraries below. Most of the CAmkES applications and also the libraries above +use the seL4 port of libmuslc.

+ +

The library collections maintained by the seL4 Foundation are +util_libs, projects_libs, +seL4_libs, seL4_projects_libs, +and libplatsupport.

+ +

OS independent libraries

+ +

OS independent low-level utilities in the repositories util_libs and +projects_libs. New libraries should go into project_libs.

+ +

util_libs

+ +

Sources: https://github.com/seL4/util_libs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
libcpio
+
+
+

A library for parsing files in CPIO format.

+ +
+
+ 
libelf
+
+
+

A library for reading ELF files.

+ +
+
+ 
libethdrivers
+
+
+

A library for ethernet drivers on selected platforms, supporting lwIP and picoTCP.

+ +
+
+ 
libpci
+
+
+

A library for PCI drivers.

+ +
+
+ 
libpicotcp
+
+
+

A library of picoTCP header files.

+ +
+
+ 
libplatsupport
+
+
+

A library of platform support utilities, interfaces for interacting with drivers, timer drivers, serial drivers and clock drivers.

+ +
+
+ 
libutils
+
+
+

A library of generic utilities, such as debugging macros and compile time asserts.

+ +
+ +

projects_libs

+ +

Sources: https://github.com/seL4/projects_libs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
libfdtgen
+
+
+

A library for generating flattened device trees which can be passed to virtual machines.

+ +
+
+ 
libplatsupportports
+
+
+

A collection of drivers proted from GPL-based sources such as U-Boot and Linux.

+ +
+
+ 
libtx2bpmp
+
+
+

A port of the Tegra186 Boot and Power Management Processor (BPMP) interfaces from U-Boot to seL4.

+ +
+
+ 
libvirtqueue
+
+
+

A library implementation of a virtqueue inspired from the virtio specification.

+ +
+
+ 
libvswitch
+
+
+

A library implementation of a vswitch, which is designed for providing an interface to manage and route data between components identified by a MAC address.

+ +
+ +

seL4-specific libraries

+ +

Basic libraries with abstractions for interacting with seL4 from C.

+ +

seL4_libs

+ +

Sources: https://github.com/seL4/seL4_libs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
libsel4allocman
+
+
+

An allocator for managing virtual memory, malloc memory and cspaces.

+ +
+
+ 
libsel4bench
+
+
+

A library of benchmarking utilities on seL4, such as logging and PMU event counters.

+ +
+
+ 
libsel4debug
+
+
+

A library for debugging userspace applications on seL4.

+ +
+
+ 
libsel4muslcsys
+
+
+

A library of minimal muslc syscall implementation for seL4.

+ +
+
+ 
libsel4platsupport
+
+
+

A wrapper around libplatsupport specificially for seL4.

+ +
+
+ 
libsel4serialserver
+
+
+

A library for creating serial servers. A server thread is able to connect to a serial device and act as a multiplexer for writes.

+ +
+
+ 
libsel4simple
+
+
+

An interface which abstracts over the boot environment of an seL4 application.

+ +
+
+ 
libsel4simple-default
+
+
+

An implementation of libsel4simple for the master branch of the seL4 kernel.

+ +
+
+ 
libsel4sync
+
+
+

A synchronisation library that uses notifications to construct basic locks.

+ +
+
+ 
libsel4test
+
+
+

A library for running tests and generating test output in either human readable or xml format.

+ +
+
+ 
libsel4utils
+
+
+

A library of OS-like utilities for building benchmarks and applications on seL4.

+ +
+
+ 
libsel4vka
+
+
+

An allocation interface for seL4.

+ +
+
+ 
libsel4vspace
+
+
+

A virtual memory management interface for seL4.

+ +
+ +

seL4_projects_libs

+ +

Sources: https://github.com/seL4/seL4_projects_libs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
libsel4dma
+
+
+

An allocator for managing DMA memory.

+ +
+
+ 
libsel4keyboard
+
+
+

A basic keyboard driver.

+ +
+
+ 
libsel4nanopb
+
+
+

An interface between seL4 IPC buffers and nanopb. Nanopb is a small code-size Protocol Buffers implementation in ANSI C.

+ +
+
+ 
libsel4rpc
+
+
+

A library for allocating resources over process boundaries. It defines a Protocol Buffer protocol, and contains wrappers for processing RPC messages used by servers.

+ +
+ +

Platform support

+ +

Drivers for some of the devices on boards that seL4 supports.

+ +

The categories below are Serial, Timer, Clock, +I2C, Pinmux, Reset, GPIO, +ltimer, Ethernet, and Other. Not all drivers +are supported on all boards. Serial and Timer/ltimer drivers are necessary to +support the sel4test and sel4bench test suites and are supported on nearly +all boards.

+ +

The seL4-independent parts of the libpatsupport libraries live in util_libs, +and the seL4-specific parts in sel4_libs.

+ +

Sources:

+ + + +

Serial

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
plat/rockpro64/serial.c
+
+
+

rockchip,rk3399-uart driver

+ +
+
+ Supported on rockpro64 platform +
+
+ 
plat/bcm2837/serial.c
+
+
+

rpi3 brcm,bcm2835-aux-uart UART driver

+ +
+
+ Supported on rpi3 platform +
+
+ 
plat/odroidc2/serial.c
+
+
+

odroidc2 amlogic,meson-gx-uart uart driver

+ +
+
+ Supported on odroidc2 platform +
+
+ 
plat/am335x/serial.c
+
+
+

am335x ti,am3352-uart serial driver

+ +
+
+ Supported on am335x platforms. +
+
+ 
plat/fvp/serial.c
+
+
+

fvp arm,pl011 serial driver

+ +
+
+ Derived from the pl011 driver for the hikey platform. +
+
+ 
plat/hikey/serial.c
+
+
+

hikey arm,pl011 Serial driver

+ +
+
+ Supported on Hikey platform. Could likely be extended to other platforms. +
+
+ 
plat/qemu-arm-virt/serial.c
+
+
+

qemu-arm-virt arm,pl011 serial driver

+ +
+
+ Derived from the pl011 driver for the hikey platform. +
+
+ 
plat/hifive/uart.c
+
+
+

hifive sifive,uart0 UART serial driver

+ +
+
+ Supported on hifive platform +
+
+ 
plat/pc99/serial.c
+
+
+

UART serial driver for the serial devices on the pc99 platform

+ +
+
+ Supported on pc99 platform +
+
+ 
plat/pc99/ega.c
+
+
+

EGA driver for the EGA (Enhanced Graphics Adapter) device on the pc99 platform

+ +
+
+ Supported on pc99 platform +
+
+ 
plat/omap3/serial.c
+
+
+

omap3 ti,omap3-uart UART serial driver

+ +
+
+ Supported on omap3 platform +
+
+ 
mach/imx/serial/serial.c
+
+
+

UART serial drivers for the UART devices in the i.MX SoCs

+ +
+
+ Supported on i.MX SoCs +
+
+ 
mach/exynos/serial.c
+
+
+

UART serial driver for the UART devices in the Exynos SoCs

+ +
+
+ Supported on Exynos SoCs +
+
+ 
mach/zynq/serial.c
+
+
+

UART serial drivers for the UART devices in the ZYNQ SoCs

+ +
+
+ Supported on ZYNQ SoCs +
+
+ 
mach/zynq/axi_uartlite.c
+
+
+

UART serial driver to the AXI UART lite device on ZYNQ SoCs

+ +
+
+ Suppored on ZYNQ SoCs +
+
+ 
mach/nvidia/serial.c
+
+
+

Serial drivers for the UART serial devices on the NVIDIA SoCs

+ +
+
+ Supported on the NVIDIA SoCs +
+ +

Timer

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
arch/arm/generic_timer.c
+
+
+

Arm generic timer driver. Should be used for debugging or development configurations only as register access is global.

+ +
+
+ Requires configuring seL4 to make the Physical timer registers available to user level. +
+
+ 
plat/rockpro64/timer.c
+
+
+

rockchip,rk3399-timer driver

+ +
+
+ Supported on rockpro64 platform +
+
+ 
plat/bcm2837/spt.c
+
+
+

rpi3 spt timer driver. The timer is based on a SP804 timer with some modifications.

+ +
+
+ Supported on rpi3 platform +
+
+ 
plat/bcm2837/system_timer.c
+
+
+

rpi3 system timer driver.

+ +
+
+ Supported on rpi3 platform +
+
+ 
plat/odroidc2/meson_timer.c
+
+
+

odroidc2 meson timer implementation

+ +
+
+ Supported on odroidc2 platform +
+
+ 
plat/am335x/timer.c
+
+
+

am335x ti,am335x-timer driver for DMTimer

+ +
+
+ Supported on am335x platforms. +
+
+ 
plat/fvp/sp804.c
+
+
+

fvp arm,sp804 timer driver

+ +
+
+ Derived from the sp804 driver for the hikey platform. +
+
+ 
plat/hikey/rtc.c
+
+
+

hikey arm,pl031 RTC driver

+ +
+
+ Supported on Hikey platform. Could likely be extended to other platforms. +
+
+ 
plat/hikey/dmt.c
+
+
+

hikey arm,sp804 timer driver

+ +
+
+ Supported on Hikey platform. Could likely be extended to other platforms. +
+
+ 
plat/hifive/pwm.c
+
+
+

hifive sifive,pwm0 timer driver

+ +
+
+ Supported on hifive platform +
+
+ 
plat/pc99/pit.c
+
+
+

PIT driver for the PIT (Programmable Interval Timer) on the pc99 platform

+ +
+
+ Supported on pc99 platform +
+
+ 
plat/pc99/rtc.c
+
+
+

RTC driver for the RTC on the pc99 platform

+ +
+
+ Supported on pc99 platform +
+
+ 
plat/pc99/hpet.c
+
+
+

HPET driver for the HPET (High Precision Event Timer) device on the pc99 platform

+ +
+
+ Supported on pc99 platform +
+
+ 
mach/omap/gpt.c
+
+
+

GPT driver for the GPT timers in the OMAP SoCs

+ +
+
+ Supported on OMAP SoCs +
+
+ 
mach/imx/epit/epit.c
+
+
+

EPIT driver for the EPIT timers in the i.MX SoCs

+ +
+
+ Supported on i.MX SoCs +
+
+ 
mach/imx/gpt.c
+
+
+

GPT driver for the GPT timers in the i.MX SoCs

+ +
+
+ Supported on i.MX SoCs +
+
+ 
mach/exynos/clock/exynos_common_clock.c
+
+
+

Exynos platform-common functions to manipulate the clock device in the Exynos SoCs

+ +
+
+ Supported on Exynos SoCs +
+
+ 
mach/exynos/clock/exynos_5422_clock.c
+
+
+

Exynos5422 platform-specific functions to manipulate the clock device in the Exynos5422 SoC

+ +
+
+ Supported on Exynos SoCs +
+
+ 
mach/exynos/clock.h
+
+
+

Clock subsystem driver for the clock controller in the Exynos SoCs

+ +
+
+ Supported on Exynos SoCs +
+
+ 
mach/exynos/pwm.c
+
+
+

PWM drivers for the PWM timers in the Exynos SoCs

+ +
+
+ Supported on Exynos SoCs +
+
+ 
mach/zynq/timer.c
+
+
+

TTC driver for the TTC timers in the ZYNQ SoCs

+ +
+
+ Supported on ZYNQ SoCs +
+
+ 
mach/nvidia/timer.c
+
+
+

Timer drivers for the timers on the NVIDIA SoCs

+ +
+
+ Supported on the NVIDIA SoCs +
+ +

Clock

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
plat/zynq7000/clock.c
+
+
+

zynq7000 clock subsystem driver

+ +
+
+ Supported on zynq7000 platform. +
+
+ 
plat/exynos5/clock.c
+
+
+

exynos5 clock subsystem driver

+ +
+
+ Supported on exynos5 platform. +
+
+ 
plat/tk1/clock.c
+
+
+

tk1 nvidia,tegra124-car clock subsystem driver

+ +
+
+ Supported on tk1 platform. +
+
+ 
plat/exynos4/clock.c
+
+
+

exynos4 clock subsystem driver

+ +
+
+ Supported on exynos4 platform. +
+
+ 
plat/imx6/clock.c
+
+
+

i.MX6 fsl,imx6q-ccm clock subsystem driver

+ +
+
+ Supported on sabre platform +
+
+ 
src/plat/tx2/clock_bindings.c
+
+
+

libplatsupport clock ID to TX2 BPMP clock ID bindings

+ +
+
+ Supported on tx2 platform +
+
+ 
src/plat/tx2/clock_bindings.c
+
+
+

Clock driver for the TX2 CAR (Clock And Reset) controller which relies on libtx2bpmp

+ +
+
+ Supported on the tx2 platform +
+ +

I2C

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
arch/arm/i2c_bitbang.c
+
+
+

Transforms a GPIO interface into an I2C bitbang interface

+ +
+
+ Currently used by libusbdrivers. +
+
+ 
plat/am335x/i2c.c
+
+
+

am335x ti,omap4-i2c driver for I2C.

+ +
+
+ Supported on am335x platforms. +
+
+ 
plat/tk1/i2c.c
+
+
+

tk1 nvidia,tegra124-i2c I2C driver

+ +
+
+ Supported on tk1 platform. +
+
+ 
plat/imx6/i2c.c
+
+
+

i.MX6 fsl,imx6q-i2c driver I2C

+ +
+
+ Supported on sabre platform +
+
+ 
mach/exynos/i2c.c
+
+
+

I2C driver for the I2C devices in the Exynos SoCs

+ +
+
+ Supported on the Exynos SoCs +
+ +

Pinmux

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
plat/tk1/mux.c
+
+
+

tk1 nvidia,tegra124-pinmux pinmux driver

+ +
+
+ Supported on tk1 platform +
+
+ 
plat/imx6/mux.c
+
+
+

i.MX6 fsl,imx6q-iomuxc IO MUX driver

+ +
+
+ Supported on sabre +
+
+ 
mach/exnyos4/mux.c
+
+
+

Pinctrl configurations for the Exynos4xxx SoCs

+ +
+
+ Supported on the Exynos4xxx SoCs +
+
+ 
mach/exynos5/mux.c
+
+
+

Pinctrl configurations for the Exynos5xxx SoCs

+ +
+
+ Supported on the Exynos5xxx SoCs +
+
+ 
mach/exynos/mux.c
+
+
+

Pinctrl driver for the pinctrl device in the Exynos SoCs

+ +
+
+ Supported on the Exynos SoCs +
+
+ 
mach/exynos/ltimer.c
+
+
+

ltimer implementation for the Exynos platforms using the PWM timers

+ +
+
+ Supported on the Exynos SoCs +
+
+ 
src/plat/tx2/mux.c
+
+
+

Pin controller driver for the TX2 MUX based off on NVIDIA’s L4T implementation

+ +
+
+ Supported on the tx2 platform +
+ +

Reset

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
plat/imx6/src.c
+
+
+

i.MX6 fsl,imx6q-src reset controller driver

+ +
+
+ Supported on sabre platform +
+
+ 
src/plat/tx2/reset_bindings.c
+
+
+

libplatsupport reset ID to TX2 BPMP reset ID bindings

+ +
+
+ Supported on the tx2 platform +
+
+ 
src/plat/tx2/reset.c
+
+
+

Reset driver for the TX2 CAR (Clock And Reset) controller which relies on libtx2bpmp

+ +
+
+ Supported on the tx2 platform +
+ +

GPIO

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
plat/tk1/gpio.c
+
+
+

tk1 nvidia,tegra124-gpio GPIO driver

+ +
+
+ Supported on i2c platform. +
+
+ 
plat/imx6/gpio.c
+
+
+

i.MX6 fsl,imx6q-gpio GPIO driver

+ +
+
+ Supported on sabre platform +
+
+ 
src/plat/tx2/gpio.c
+
+
+

GPIO driver for the TX2 GPIO controller based off on U-Boot’s implementation

+ +
+
+ Supported on the tx2 platform +
+ +

ltimer

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
arch/arm/generic_ltimer.c
+
+
+

ltimer implementation for Arm generic timer physical timer. Should be used for debugging or development configurations only as register access is global

+ +
+
+ Requires configuring seL4 to make the Physical timer registers available to user level. +
+
+ 
local_time_manager.c
+
+
+

Uses an ltimer to provide timeout multiplexing across several clients

+ +
+
+ Requires ltimer implementation for the target platform. +
+
+ 
plat/rockpro64/ltimer.c
+
+
+

rockpro64 ltimer implementation using 2 rk3399-timers

+ +
+
+ Supported on rockpro64 platform +
+
+ 
plat/bcm2837/ltimer.c
+
+
+

rpi3 ltimer implementation using the system timer and spt timer

+ +
+
+ Supported on rpi3 platform +
+
+ 
plat/odroidc2/ltimer.c
+
+
+

odroidc2 ltimer implementation using the meson timer

+ +
+
+ Supported on odroidc2 platform +
+
+ 
plat/am335x/ltimer.c
+
+
+

am335x ltimer implementation using 2 DMTimers

+ +
+
+ Supported on am335x platforms. +
+
+ 
plat/fvp/ltimer.c
+
+
+

fvp ltimer implementation using 2 sp804 timers.

+ +
+
+ Supported on fvp platform. +
+
+ 
plat/hikey/ltimer.c
+
+
+

hikey ltimer implementation using 2 sp804 timers

+ +
+
+ Supported on hikey platform. +
+
+ 
plat/hifive/ltimer.c
+
+
+

ltimer implementation for the hifive platform using two PWM timers

+ +
+
+ Supported on hifive platform +
+
+ 
plat/pc99/ltimer.c
+
+
+

ltimer implementation for the pc99 platform using either PIT or HPET timers

+ +
+
+ Supported on pc99 platform +
+
+ 
mach/imx/ltimer.c
+
+
+

ltimer implementation for the i.MX platforms using a combination of GPT and EPIT timers

+ +
+
+ Supported on i.MX SoCs +
+
+ 
mach/zynq/ltimer.c
+
+
+

ltimer implementation for the ZYNQ platforms using TTC timers

+ +
+
+ Supported on ZYNQ SoCs +
+
+ 
mach/nvidia/ltimer.c
+
+
+

ltimer implementation for the NVIDIA platforms using the NVIDIA timers

+ +
+
+ Supported on the NVIDIA SoCs +
+ +

Ethernet

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
src/pico_dev_eth.c
+
+
+

Ethernet device interface to connect with the PicoTCP TCP/IP stack

+ +
+
+ Supported +
+
+ 
src/lwip.c
+
+
+

Ethernet device interface to connect with the lwIP TCP/IP stack

+ +
+
+ Deprecated in favour of the PicoTCP Ethernet device interface +
+
+ 
src/plat/imx6/*
+
+
+

Ethernet driver for the i.MX6 platform based off on U-Boot’s implementation

+ +
+
+ Supported on the sabre platform +
+
+ 
src/plat/pc99/*
+
+
+

Ethernet driver for the e1000 Ethernet devices

+ +
+
+ Supported on pc99 platform +
+
+ 
src/plat/tx2/*
+
+
+

Ethernet driver for the TX2 platform based off on U-Boot’s implementation

+ +
+
+ Supported on the tx2 platform +
+
+ 
src/plat/zynq700/*
+
+
+

Ethernet driver for the zynq7000 platform based off on U-Boot’s implementation

+ +
+
+ Supported on the zynq7000 platform +
+ +

Other

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ 
arch/x86/delay.c
+
+
+

x86 busy wait delay driver by spinning on tsc value

+ +
+
+ Supported on x86 but currently unused by anything. +
+
+ 
arch/x86/tsc.c
+
+
+

Calculates tsc frequency using HPET or PIT

+ +
+
+ Supported on x86. It may be better to use the tsc_freq Bootinfo field that seL4 provides. +
+
+ 
arch/arm/delay.c
+
+
+

arm busy wait delay driver by repeatedly performing no-op instructions

+ +
+
+ Supported on arm but currently relies on each instruction taking a constant amount of time +
+
+ 
plat/zynq7000/devcfg.c
+
+
+

devcfg (Device configuration Interface) zynq7000 driver

+ +
+
+ Supported only for zynq7000 platform. Only functionality is mapping registers and providing a reference. +
+
+ 
plat/zynq7000/tmu.c
+
+
+

Temperature sensor driver for zynq7000 tmu.

+ +
+
+ Supported on zynq7000 platform. +
+
+ 
plat/zynq7000/xadc.c
+
+
+

zynq7000 XADC driver

+ +
+
+ Supported on zynq7000 platform. Currently only used to read values from a temperature monitoring unit. +
+
+ 
plat/zynq7000/src.c
+
+
+

zynq7000 System Level Control Registers driver

+ +
+
+ Supported on zynq7000 platform. Currently used to unlock clock and reset registers only. +
+
+ 
plat/exynos5/sysreg.c
+
+
+

exynos5 samsung,exynos5-sysreg system control driver

+ +
+
+ Supported on exynos5 platforms. Currently can only be used to enable power for USB PHYs. +
+
+ 
plat/tk1/spi.c
+
+
+

tk1 nvidia,tegra124-spi SPI driver

+ +
+
+ Supported on tk1 platform. +
+
+ 
plat/exynos4/src.c
+
+
+

exynos4 samsung,exynos4-sysreg system control driver

+ +
+
+ Supported on exynos4 platforms. Currently can only be used to enable power for USB PHYs. +
+
+ 
mach/omap/ltimer.c
+
+
+

ltimer implementation for the OMAP platforms using GPT timers

+ +
+
+ Supported on OMAP SoCs +
+
+ 
mach/exynos/tmu.c
+
+
+

TMU driver for the TMU (Thermal Management Unit) device in the Exynos SoCs

+ +
+
+ Supported on Exynos SoCs +
+
+ 
mach/exynos/pmic.c
+
+
+

PMIC driver for the PMIC (Power Management IC) device in the Exynos SoCs

+ +
+
+ Supported on the Exynos SoCs +
+
+ 
mach/exynos/pmic_rtc.c
+
+
+

RTC driver for the RTC located inside the PMIC device in the Exynos SoCs

+ +
+
+ Supported on the Exynos SoCs +
+
+ 
mach/exnyos/irq_combiner.c
+
+
+

IRQ combiner driver for the IRQ combiner device in the Exynos SoCs

+ +
+
+ Supported on the Exynos SoCs +
+
+ 
src/helpers.c
+
+
+

Helper functions for the Ethernet drivers in libethdrivers

+ +
+
+ Supported +
+
+ 
src/bpmp.c
+
+
+

BPMP driver for the BPMP (Boot and Power Management Processor) co-processor on the TX2 based off on U-Boot’s implementation

+ +
+
+ Supported on the tx2 platform +
+
+ 
src/hsp.c
+
+
+

HSP driver for the HSP (Hardware Synchronisation Primitives) module on the TX2

+ +
+
+ Supported on the tx2 platform +
+
+ 
src/ivc.c
+
+
+

IVC implementation for the IVC (Inter-VM Communication) protocol used for communicating with the BPMP

+ +
+
+ Supported on the tx2 platform +
+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/user_libs/index.md b/projects/user_libs/index.md deleted file mode 100644 index 4d2d55dd914..00000000000 --- a/projects/user_libs/index.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -redirect_from: - - /SeL4Libraries -toc: true -wide: true -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# User-level C libraries - -The following collection of C libraries is useful for prototyping directly on -the seL4 API. They are meant for trying things out, not for production code. -They are not verified and come with no particular code assurance. They are -provided because they might be useful for experimentation. - -For production code we recommend the seL4 [Microkit], or [CAmkES] when the -Microkit is not applicable, and the [Rust] libraries for more dynamic systems. - -Microkit does not use these libraries and expects a separate development -environment for user-level code. Some CAmkES example applications do use the -libraries below. Most of the CAmkES applications and also the libraries above -use the seL4 port of [libmuslc](https://github.com/seL4/musllibc). - -The library collections maintained by the seL4 Foundation are -[util_libs](#util_libs), [projects_libs](#projects_libs), -[seL4_libs](#sel4_libs), [seL4_projects_libs](#sel4_projects_libs), -and [libplatsupport](#libplatsupport). - -## OS independent libraries - -OS independent low-level utilities in the repositories [util_libs] and -[projects_libs]. New libraries should go into `project_libs`. - -[util_libs]: https://github.com/seL4/util_libs -[projects_libs]: https://github.com/seL4/projects_libs - -### util_libs - -Sources: - -{% include component_list.md - project='user_libs' type='util_libs' filter='active' no_status=true %} - -### projects_libs - -Sources: - -{% include component_list.md - project='user_libs' type='projects_libs' filter='active' no_status=true %} - -## seL4-specific libraries - -Basic libraries with abstractions for interacting with seL4 from C. - -### seL4_libs - -Sources: - -{% include component_list.md - project='user_libs' type='seL4_libs' filter='active' no_status=true %} - -### seL4_projects_libs - -Sources: - -{% include component_list.md - project='user_libs' type='seL4_projects_libs' filter='active' no_status=true %} - - -## Platform support {#libplatsupport} - -Drivers for some of the devices on boards that seL4 supports. - -The categories below are [Serial](#serial), [Timer](#timer), [Clock](#clock), -[I2C](#i2c), [Pinmux](#pinmux), [Reset](#reset), [GPIO](#gpio), -[ltimer](#ltimer), [Ethernet](#ethernet), and [Other](#other). Not all drivers -are supported on all boards. Serial and Timer/ltimer drivers are necessary to -support the `sel4test` and `sel4bench` test suites and are supported on nearly -all boards. - -The seL4-independent parts of the `libpatsupport` libraries live in `util_libs`, -and the seL4-specific parts in `sel4_libs`. - -Sources: - -- -- - -### Serial - -{% include component_list.md project='user_libs' type='user-driver-serial' %} - -### Timer - -{% include component_list.md project='user_libs' type='user-driver-timer' %} - -### Clock - -{% include component_list.md project='user_libs' type='user-driver-clock' %} - -### I2C - -{% include component_list.md project='user_libs' type='user-driver-i2c' %} - -### Pinmux - -{% include component_list.md project='user_libs' type='user-driver-pinmux' %} - -### Reset - -{% include component_list.md project='user_libs' type='user-driver-reset' %} - -### GPIO - -{% include component_list.md project='user_libs' type='user-driver-gpio' %} - -### ltimer - -{% include component_list.md project='user_libs' type='user-driver-ltimer' %} - -### Ethernet - -{% include component_list.md project='user_libs' type='user-driver-ethernet' %} - -### Other - -{% include component_list.md project='user_libs' type='user-driver-other' %} - - - - -[Microkit]: {{ '/projects/microkit/' | relative_url }} -[CAmkES]: {{ '/projects/camkes/' | relative_url }} -[Rust]: {{ '/projects/rust/' | relative_url }} diff --git a/projects/user_libs/status.html b/projects/user_libs/status.html new file mode 100644 index 00000000000..8e9c58dd86f --- /dev/null +++ b/projects/user_libs/status.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/virtualization/docs/api/libsel4vm_arm_guest_vm.html b/projects/virtualization/docs/api/libsel4vm_arm_guest_vm.html new file mode 100644 index 00000000000..38fa67d1496 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_arm_guest_vm.html @@ -0,0 +1,656 @@ + + + + + + + libsel4vm_arm_guest_vm | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_vm_arch.h

+ +

The guest arm vm interface is central to using libsel4vm on an ARM platform, providing definitions of the arm guest vm +datastructures and primitives to configure the VM instance.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_register_unhandled_vcpu_fault_callback(vcpu, vcpu_fault_callback, cookie)

+
+ +

Structs:

+ +
+

vm_vcpu_arch

+
+ +

Functions

+ +

The interface guest_vm_arch.h defines the following functions.

+ + + +

Register a callback for processing unhandled vcpu faults

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: A handle to the VCPU
    • +
  • A {unhandled_vcpu_fault_callback_fn}: user supplied callback to process unhandled vcpu faults
    • +
  • A {void *}: cookie to supply to the vcpu fault handler
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface guest_vm_arch.h defines the following structs.

+ +

Struct vm_vcpu_arch

+ +

Structure representing ARM specific vcpu properties

+ +

Elements:

+ +
    +
  • fault {fault_t *}: Current VCPU fault
    • +
  • unhandled_vcpu_callback {unhandled_vcpu_fault_callback_fn}: A callback for processing unhandled vcpu faults
    • +
  • unhandled_vcpu_callback_cookie {void *}: A cookie to supply to the vcpu fault handler
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_boot.html b/projects/virtualization/docs/api/libsel4vm_boot.html new file mode 100644 index 00000000000..fdd0293e20e --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_boot.html @@ -0,0 +1,678 @@ + + + + + + + libsel4vm_boot | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface boot.h

+ +

The libsel4vm boot interface provides us with base abstractions to create, initialise and configure VM and VCPU instances.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_init(vm, vka, host_simple, host_vspace, io_ops, host_endpoint, name)

+
+ +
+

vm_create_vcpu(vm, priority)

+
+ +
+

vm_assign_vcpu_target(vcpu, target_cpu)

+
+ +

Functions

+ +

The interface boot.h defines the following functions.

+ +

Function vm_init(vm, vka, host_simple, host_vspace, io_ops, host_endpoint, name)

+ +

Initialise/Create VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: Handle to the VM being initialised
    • +
  • vka {vka_t *}: Initialised handle to virtual kernel allocator for seL4 kernel object allocation
    • +
  • host_simple {simple_t *}: Initialised handle to hosts simple environment
    • +
  • host_vspace {vspace_t}: Initialised handle to hosts vspace
    • +
  • ps_io_ops {ps_io_ops_t *}: Initialised handle to platforms io ops
    • +
  • host_enpoint {seL4_CPtr}: Host’s endpoint. The library will wait and manage the endpoint when running a VM instance
    • +
  • name {const char *}: String used to describe VM. Useful for debugging
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_create_vcpu(vm, priority)

+ +

Create a VCPU for a given VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to VM being configured with a new vcpu
    • +
  • priority {int}: The scheduling priority assigned to the VCPU thread
    • +
+ +

Returns:

+ +
    +
  • NULL for error, otherwise pointer to created vm_vcpu_t object
    • +
+ +

Back to interface description.

+ +

Function vm_assign_vcpu_target(vcpu, target_cpu)

+ +

Assign a vcpu with logical target cpu to run on

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: A handle to the VCPU
    • +
  • target {int}: Logical target CPU ID
    • +
+ +

Returns:

+ +
    +
  • -1 for error, otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_arm_context.html b/projects/virtualization/docs/api/libsel4vm_guest_arm_context.html new file mode 100644 index 00000000000..da048e0b572 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_arm_context.html @@ -0,0 +1,751 @@ + + + + + + + libsel4vm_guest_arm_context | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_arm_context.h

+ +

The libsel4vm ARM context interface provides a set of useful getters and setters on ARM vcpu thread contexts. +This interface is commonly leveraged by VMM’s to initialise a vcpu state, process a vcpu fault and +accordingly update its state.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_set_thread_context(vcpu, context)

+
+ +
+

vm_set_thread_context_reg(vcpu, reg, value)

+
+ +
+

vm_get_thread_context(vcpu, context)

+
+ +
+

vm_get_thread_context_reg(vcpu, reg, value)

+
+ +
+

vm_set_arm_vcpu_reg(vcpu, reg, value)

+
+ +
+

vm_get_arm_vcpu_reg(vcpu, reg, value)

+
+ +

Functions

+ +

The interface guest_arm_context.h defines the following functions.

+ +

Function vm_set_thread_context(vcpu, context)

+ +

Set a VCPU’s thread registers given a TCB user context

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • context {seL4_UserContext}: seL4_UserContext applied to VCPU’s TCB
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_set_thread_context_reg(vcpu, reg, value)

+ +

Set a single VCPU’s TCB register

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • reg {unsigned int}: Index offset of register in seL4_UserContext e.g pc (seL4_UserContext.pc) => 0
    • +
  • value {uintptr_t}: Value to set TCB register with
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_get_thread_context(vcpu, context)

+ +

Get a VCPU’s TCB user context

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t}: Handle to the vcpu
    • +
  • context {seL4_UserContext}: Pointer to user supplied seL4_UserContext to populate with VCPU’s TCB user context
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_get_thread_context_reg(vcpu, reg, value)

+ +

Get a single VCPU’s TCB register

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • reg {unsigned int}: Index offset of register in seL4_UserContext e.g pc (seL4_UserContext.pc) => 0
    • +
  • value {uintptr_t *}: Pointer to user supplied variable to populate TCB register value with
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_set_arm_vcpu_reg(vcpu, reg, value)

+ +

Set an ARM VCPU register

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • reg {seL4_Word}: VCPU Register field defined in seL4_VCPUReg
    • +
  • value {uintptr_t *}: Value to set VCPU register with
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_get_arm_vcpu_reg(vcpu, reg, value)

+ +

Get an ARM VCPU register

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • reg {seL4_Word}: VCPU Register field defined in seL4_VCPUReg
    • +
  • value {uintptr_t *}: Pointer to user supplied variable to populate VCPU register value with
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_iospace.html b/projects/virtualization/docs/api/libsel4vm_guest_iospace.html new file mode 100644 index 00000000000..a8cc848e50f --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_iospace.html @@ -0,0 +1,627 @@ + + + + + + + libsel4vm_guest_iospace | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_iospace.h

+ +

The libsel4vm iospace interface enables the registration and management of a guest VM’s IO Space. This +being used when supporting IOMMU (x86) and SMMU (ARM) VM features.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_guest_add_iospace(vm, loader, iospace)

+
+ +

Functions

+ +

The interface guest_iospace.h defines the following functions.

+ +

Function vm_guest_add_iospace(vm, loader, iospace)

+ +

Attach an additional IO space to the given VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • loader {vspace_t *}: Host loader vspace to create a new iospace
    • +
  • iospace {seL4_CPtr}: Capability to iospace being added
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_irq_controller.html b/projects/virtualization/docs/api/libsel4vm_guest_irq_controller.html new file mode 100644 index 00000000000..2697f8a7716 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_irq_controller.html @@ -0,0 +1,700 @@ + + + + + + + libsel4vm_guest_irq_controller | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_irq_controller.h

+ +

The libsel4vm IRQ controller interface provides a base abstraction around initialising a guest VM irq controller +and methods for injecting IRQs into a running VM instance.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_inject_irq(vcpu, irq)

+
+ +
+

vm_set_irq_level(vcpu, irq, irq_level)

+
+ +
+

vm_register_irq(vcpu, irq, ack_fn, cookie)

+
+ +
+

vm_create_default_irq_controller(vm)

+
+ +

Functions

+ +

The interface guest_irq_controller.h defines the following functions.

+ +

Function vm_inject_irq(vcpu, irq)

+ +

Inject an IRQ into a VM’s interrupt controller

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the VCPU
    • +
  • irq {int}: IRQ number to inject
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_set_irq_level(vcpu, irq, irq_level)

+ +

Set level of IRQ number into a VM’s interrupt controller

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t}: Handle to the VCPU
    • +
  • irq {int}: IRQ number to set level on
    • +
  • irq_level {int}: Value of IRQ level
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ + + +

Register irq with an acknowledgment function

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the VCPU
    • +
  • irq {int}: IRQ number to register acknowledgement function on
    • +
  • ack_fn {irq_ack_fn_t}: IRQ acknowledgement function
    • +
  • cookie {void *}: Cookie to pass back with IRQ acknowledgement function
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_create_default_irq_controller(vm)

+ +

Install the default interrupt controller into the VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: Handle to the VM
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_memory.html b/projects/virtualization/docs/api/libsel4vm_guest_memory.html new file mode 100644 index 00000000000..a0b34579b58 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_memory.html @@ -0,0 +1,816 @@ + + + + + + + libsel4vm_guest_memory | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_memory.h

+ +

The libsel4vm memory interface provides useful abstractions to manage your guest VM’s address space. +This interface can be leveraged for uses such as mapping device memory into your VM instance +or for creating emulated device regions binded with custom handlers/callbacks. +The main mechanisms this interface provides involves reserving memory regions and using those reservations +to either map memory into your guest VM’s address space or emulate subsequent accesses. Reservations +are created through either using vm_reserve_memory_at or vm_reserve_anon_memory. +The user can then further back the reservation with seL4 frames by performing vm_map_reservation.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_reserve_memory_at(vm, addr, size, fault_callback, cookie)

+
+ +
+

vm_reserve_anon_memory(vm, size, fault_callback, cookie, addr)

+
+ +
+

vm_free_reserved_memory(vm, reservation)

+
+ +
+

vm_map_reservation(vm, reservation, map_iterator, cookie)

+
+ +
+

vm_map_reservation_frames(vm, reservation, frames, num_frames, frame_size_bits)

+
+ +
+

vm_get_reservation_memory_region(reservation, addr, size)

+
+ +
+

vm_memory_init(vm)

+
+ +

Structs:

+ +
+

vm_frame_t

+
+ +

Functions

+ +

The interface guest_memory.h defines the following functions.

+ + + +

Reserve a region of the VM’s memory at a given base address

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • addr {uintptr}: Base address of the memory region being reserved
    • +
  • size {size_t}: Size of the memory region being reserved
    • +
  • fault_callback {memory_fault_callback_fn}: Callback function that will be invoked if memory region is faulted on
    • +
  • cookie {void *}: User cookie to pass onto to callback
    • +
+ +

Returns:

+ +
    +
  • NULL on failure otherwise a pointer to a reservation object representing the reserved region
    • +
+ +

Back to interface description.

+ + + +

Reserve an anonymous region of the VM’s memory. This uses memory previously made anonymous +through the vm_memory_make_anon function.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • size {size_t}: Size of the anoymous emory region being reserved
    • +
  • align {size_t}: Requested alignment of the memory region
    • +
  • fault_callback {memory_fault_callback_fn}: Callback function that will be invoked if memory region is faulted on
    • +
  • cookie {void *}: User cookie to pass onto to callback
    • +
  • addr {uintptr_t *}: Pointer that will be set with the base address of the reserved anonymous region
    • +
+ +

Returns:

+ +
    +
  • NULL on failure otherwise a pointer to a reservation object representing the reserved region
    • +
+ +

Back to interface description.

+ +

Function vm_free_reserved_memory(vm, reservation)

+ +

Free memory reservation from the VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • reservation {vm_memory_reservation_t *}: Pointer to the reservation being free’d
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ + + +

Map a reservation into the VM’s virtual address space

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • reservation {vm_memory_reservation_t *}: Pointer to reservation object being mapped
    • +
  • map_iterator {memory_map_iterator_fn}: Iterator function that returns a cap to the memory region being mapped
    • +
  • cookie {void *}: Cookie to pass onto map_iterator function
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Function vm_map_reservation_frames(vm, reservation, frames, num_frames, frame_size_bits)

+ +

Map a reservation into the VM’s virtual address space from given frames

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • reservation {vm_memory_reservation_t *}: Pointer to reservation object being mapped
    • +
  • frames {seL4_CPtr *}: Array of frame caps
    • +
  • num_frames {size_t}: Number of frame caps
    • +
  • frame_size_bits {size_t}: Bit size of a single frame
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Function vm_get_reservation_memory_region(reservation, addr, size)

+ +

Get the memory region information (address & size) from a given reservation

+ +

Parameters:

+ +
    +
  • reservation {vm_memory_reservation_t *}: Pointer to reservation object
    • +
  • addr {uintptr_t *}: Pointer that will be set with the address of reservation
    • +
  • size {size_t *}: Pointer that will be set with the size of reservation
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Function vm_memory_init(vm)

+ +

Initialise a VM’s memory management interface

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface guest_memory.h defines the following structs.

+ +

Struct vm_frame_t

+ +

Structure representing a mappable memory frame

+ +

Elements:

+ +
    +
  • cptr {seL4_CPtr}: Capability to frame
    • +
  • rights {seL4_CapRights_t}: Mapping rights of frame
    • +
  • vaddr {uintptr_t}: Virtual address of which to map the frame into
    • +
  • size_bits {size_t}: Size of frame in bits
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_memory_helpers.html b/projects/virtualization/docs/api/libsel4vm_guest_memory_helpers.html new file mode 100644 index 00000000000..ceb05b848f2 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_memory_helpers.html @@ -0,0 +1,629 @@ + + + + + + + libsel4vm_guest_memory_helpers | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_memory_helpers.h

+ +

The libsel4vm guest memory helpers interface provides simple utilities for using the guest memory interface.

+ +

Brief content:

+ +

Functions:

+ +
+

default_error_fault_callback(vm, vcpu, fault_addr, fault_length, cookie)

+
+ +

Functions

+ +

The interface guest_memory_helpers.h defines the following functions.

+ + + +

Default fault callback that throws a fault error. +Useful to avoid having to re-define a fault callback on regions that should be mapped with all rights.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • vcpu {vm_vcpu_t *}: A handle to the fault vcpu
    • +
  • fault {uintptr_t}: addr Faulting address
    • +
  • fault_length {size_t}: Length of faulted access
    • +
  • cookie {void *}: User cookie to pass onto callback
    • +
+ +

Returns:

+ +
    +
  • Always returns FAULT_ERROR
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_ram.html b/projects/virtualization/docs/api/libsel4vm_guest_ram.html new file mode 100644 index 00000000000..882c83961cc --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_ram.html @@ -0,0 +1,830 @@ + + + + + + + libsel4vm_guest_ram | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_ram.h

+ +

The libsel4vm RAM interface provides us with a set of methods to manage a guest VM’s RAM. This involves functions +to register, allocate and copy to and from RAM regions.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_guest_ram_read_callback(vm, guest_addr, vaddr, size, offset, buf)

+
+ +
+

vm_guest_ram_write_callback(vm, guest_addr, vaddr, size, offset, buf)

+
+ +
+

vm_ram_touch(vm, addr, size, touch_callback, cookie)

+
+ +
+

vm_ram_find_largest_free_region(vm, addr, size)

+
+ +
+

vm_ram_register(vm, bytes)

+
+ +
+

vm_ram_register_at(vm, start, bytes, untyped)

+
+ +
+

vm_ram_mark_allocated(vm, start, bytes)

+
+ +
+

vm_ram_allocate(vm, bytes)

+
+ +
+

vm_ram_free(vm, start, bytes)

+
+ +

Functions

+ +

The interface guest_ram.h defines the following functions.

+ +

Function vm_guest_ram_read_callback(vm, guest_addr, vaddr, size, offset, buf)

+ +

Common guest ram touch callback for reading from a guest address into a user supplied buffer

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • guest_addr {uintptr_t}: Guest physical address to read from
    • +
  • vmm_vaddr {void *}: Virtual address in hosts (vmm) vspace corresponding with the ‘guest_addr’
    • +
  • size {size_t}: Size of region being currently accessed
    • +
  • offset {size_t}: Current offset from the base guest physical address supplied to ‘vm_ram_touch’
    • +
  • cookie {void *}: User supplied buffer to store read data into
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Function vm_guest_ram_write_callback(vm, guest_addr, vaddr, size, offset, buf)

+ +

Common guest ram touch callback for writing a user supplied buffer into a guest address

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • guest_addr {uintptr_t}: Guest physical address to write to
    • +
  • vmm_vaddr {void *}: Virtual address in hosts (vmm) vspace corresponding with the ‘guest_addr’
    • +
  • size {size_t}: Size of region being currently accessed
    • +
  • offset {size_t}: Current offset from the base guest physical address supplied to ‘vm_ram_touch’
    • +
  • cookie {void *}: User supplied buffer to write data from
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ + + +

Touch a series of pages in the guest vm and invoke a callback for each page accessed

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • addr {uintptr_t}: Address to access in the guest vm
    • +
  • size {size_t}: Size of memory region to access
    • +
  • callback {ram_touch_callback_fn}: Callback to invoke on each page access
    • +
  • cookie {void *}: User data to pass onto callback
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Function vm_ram_find_largest_free_region(vm, addr, size)

+ +

Find the largest free ram region

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • addr {uintptr_t *}: Pointer to be set with largest region address
    • +
  • size {size_t *}: Pointer to be set with largest region size
    • +
+ +

Returns:

+ +
    +
  • -1 on failure, otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Function vm_ram_register(vm, bytes)

+ +

Reserve a region of memory for RAM in the guest VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • bytes {size_t}: Size of RAM region to allocate
    • +
+ +

Returns:

+ +
    +
  • Starting address of registered ram region
    • +
+ +

Back to interface description.

+ +

Function vm_ram_register_at(vm, start, bytes, untyped)

+ +

Reserve a region of memory for RAM in the guest VM at a starting guest physical address

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM that ram needs to be allocated for
    • +
  • start {uintptr_t}: Starting guest physical address of the ram region being allocated
    • +
  • size {size_t}: The size of the RAM region to be allocated
    • +
  • untyped {bool}: Allocate RAM frames such that it uses untyped memory
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Function vm_ram_mark_allocated(vm, start, bytes)

+ +

Mark a registered region of RAM as allocated

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • start {uintptr_t}: Starting address of guest ram region
    • +
  • bytes {size_t}: Size of RAM region
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Function vm_ram_allocate(vm, bytes)

+ +

Allocate a region of registered ram

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • bytes {size_t}: Size of allocation
    • +
+ +

Returns:

+ +
    +
  • Starting address of allocated ram region
    • +
+ +

Back to interface description.

+ +

Function vm_ram_free(vm, start, bytes)

+ +

Free a RAM a previously allocated RAM region

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM that ram needs to be free’d for
    • +
  • start {uintptr_t}: Starting guest physical address of the ram region being free’d
    • +
  • size {size_t}: The size of the RAM region to be free’d
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_vcpu_fault.html b/projects/virtualization/docs/api/libsel4vm_guest_vcpu_fault.html new file mode 100644 index 00000000000..9eb45777dbb --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_vcpu_fault.html @@ -0,0 +1,831 @@ + + + + + + + libsel4vm_guest_vcpu_fault | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_vcpu_fault.h

+ +

The libsel4vm VCPU fault interface provides a set of useful methods to query and configure vcpu objects that +have faulted during execution. This interface is commonly leveraged by VMM’s to process a vcpu fault and handle +it accordingly.

+ +

Brief content:

+ +

Functions:

+ +
+

get_vcpu_fault_address(vcpu)

+
+ +
+

get_vcpu_fault_ip(vcpu)

+
+ +
+

get_vcpu_fault_data(vcpu)

+
+ +
+

get_vcpu_fault_data_mask(vcpu)

+
+ +
+

get_vcpu_fault_size(vcpu)

+
+ +
+

is_vcpu_read_fault(vcpu)

+
+ +
+

set_vcpu_fault_data(vcpu, data)

+
+ +
+

emulate_vcpu_fault(vcpu, data)

+
+ +
+

advance_vcpu_fault(vcpu)

+
+ +
+

restart_vcpu_fault(vcpu)

+
+ +

Functions

+ +

The interface guest_vcpu_fault.h defines the following functions.

+ +

Function get_vcpu_fault_address(vcpu)

+ +

Get current fault address of vcpu

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
+ +

Returns:

+ +
    +
  • Current fault address of vcpu
    • +
+ +

Back to interface description.

+ +

Function get_vcpu_fault_ip(vcpu)

+ +

Get instruction pointer of current vcpu fault

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
+ +

Returns:

+ +
    +
  • Intruction pointer of vcpu fault
    • +
+ +

Back to interface description.

+ +

Function get_vcpu_fault_data(vcpu)

+ +

Get the data of the current vcpu fault

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
+ +

Returns:

+ +
    +
  • Data of vcpu fault
    • +
+ +

Back to interface description.

+ +

Function get_vcpu_fault_data_mask(vcpu)

+ +

Get data mask of the current vcpu fault

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
+ +

Returns:

+ +
    +
  • Data mask of vcpu fault
    • +
+ +

Back to interface description.

+ +

Function get_vcpu_fault_size(vcpu)

+ +

Get access size of the current vcpu fault

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
+ +

Returns:

+ +
    +
  • Access size of vcpu fault
    • +
+ +

Back to interface description.

+ +

Function is_vcpu_read_fault(vcpu)

+ +

Is current vcpu fault a read fault

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
+ +

Returns:

+ +
    +
  • True if read fault, False if write fault
    • +
+ +

Back to interface description.

+ +

Function set_vcpu_fault_data(vcpu, data)

+ +

Set the data of the current vcpu fault

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
  • data {seL4_Word}: Data to set for current vcpu fault
    • +
+ +

Returns:

+ +
    +
  • 0 for success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function emulate_vcpu_fault(vcpu, data)

+ +

Emulate a read or write fault on a given data value

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
  • data {seL4_Word}: Data to perform emulate fault on
    • +
+ +

Returns:

+ +
    +
  • Emulation result of vcpu fault over given data value
    • +
+ +

Back to interface description.

+ +

Function advance_vcpu_fault(vcpu)

+ +

Advance the current vcpu fault to the next stage/instruction

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Function restart_vcpu_fault(vcpu)

+ +

Restart the current vcpu fault

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to vcpu
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_vm.html b/projects/virtualization/docs/api/libsel4vm_guest_vm.html new file mode 100644 index 00000000000..72158adbdb2 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_vm.html @@ -0,0 +1,860 @@ + + + + + + + libsel4vm_guest_vm | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_vm.h

+ +

The guest vm interface is central to libsel4vm, providing definitions of the guest vm datastructure and +primitives to run the VM instance and start its vcpus.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_run(vm_t *vm)

+
+ +
+

vcpu_start(vcpu)

+
+ +
+

vm_register_unhandled_mem_fault_callback(vm, fault_handler, cookie)

+
+ +
+

vm_register_notification_callback(vm, notification_callback, cookie)

+
+ +

Structs:

+ +
+

vm_ram_region

+
+ +
+

vm_mem

+
+ +
+

vm_tcb

+
+ +
+

vm_vcpu

+
+ +
+

vm_run

+
+ +
+

vm_cspace

+
+ +
+

vm

+
+ +

Functions

+ +

The interface guest_vm.h defines the following functions.

+ +

Function vm_run(vm_t *vm)

+ +

Enter the VM event runtime loop. +This funtion is a blocking call, returning on the event of an unhandled VM exit or error

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM to run
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Function vcpu_start(vcpu)

+ +

Start an initialised vcpu thread

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: A handle to vcpu to start
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ + + +

Register a callback for processing unhandled memory faults (memory regions not previously registered or reserved)

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • fault_handler {unhandled_mem_fault_callback_fn}: A user supplied callback to process unhandled memory faults
    • +
  • cookie {void *}: A cookie to supply to the memory fault handler
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ + + +

Register a callback for processing unhandled notifications (events unknown to libsel4vm)

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • notification_callback {notification_callback_fn}: A user supplied callback to process unhandled notifications
    • +
  • cookie {void *}: A cookie to supply to the callback
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface guest_vm.h defines the following structs.

+ +

Struct vm_ram_region

+ +

Structure representing individual RAM region. A VM can have multiple regions to represent its total RAM

+ +

Elements:

+ +
    +
  • start {uintptr_t}: Guest physical start address of region
    • +
  • size {size_t}: Size of region in bytes
    • +
  • allocated {int}: Whether or not this region has been ‘allocated’
    • +
+ +

Back to interface description.

+ +

Struct vm_mem

+ +

Structure representing VM memory managment

+ +

Elements:

+ +
    +
  • vm_vspace {vspace_t}: Guest VM’s vspace
    • +
  • vm_vspace_root {vka_object_t}: VKA allocated guest VM root vspace
    • +
  • vmm_vspace {vspace_t}: Hosts/VMMs vspace
    • +
  • num_ram_regions {int}: Total number of registered vm_ram_regions
    • +
  • Set {struct vm_ram_region *}: of registered vm_ram_regions
    • +
  • Initialised {vm_memory_reservation_cookie_t *}: instance of vm memory interface
    • +
  • unhandled_mem_fault_handler {unhandled_mem_fault_callback_fn}: Registered callback for unhandled memory faults
    • +
  • unhandled_mem_fault_cookie {void *}: User data passed onto unhandled mem fault callback
    • +
+ +

Back to interface description.

+ +

Struct vm_tcb

+ +

Structure used for TCB management within a VCPU

+ +

Elements:

+ +
    +
  • tcb {vka_object_t}: VKA allocated TCB object
    • +
  • sc {vka_object_t}: VKA allocated scheduling context
    • +
  • priority {int}: VCPU scheduling priority
    • +
+ +

Back to interface description.

+ +

Struct vm_vcpu

+ +

Structure used to represent a VCPU

+ +

Elements:

+ +
    +
  • vm {struct vm *}: Parent VM
    • +
  • vcpu {vka_object_t}: VKA allocated vcpu object
    • +
  • tcb {struct vm_tcb}: VCPUs TCB management structure
    • +
  • vcpu_id {unsigned int}: VCPU Identifier
    • +
  • target_cpu {int}: The target core the vcpu is assigned to
    • +
  • vcpu_online {bool}: Flag representing if the vcpu has been started
    • +
  • vcpu_arch {struct vm_vcpu_arch}: Architecture specific vcpu properties
    • +
+ +

Back to interface description.

+ +

Struct vm_run

+ +

VM Runtime management structure

+ +

Elements:

+ +
    +
  • exit_reason {int}: Records last vm exit reason
    • +
  • notification_callback {notification_callback_fn}: Callback for processing unhandled notifications
    • +
  • notification_callback_cookie {void *}: A cookie to supply to the notification callback
    • +
+ +

Back to interface description.

+ +

Struct vm_cspace

+ +

VM cspace management structure

+ +

Elements:

+ +
    +
  • cspace_obj {vka_object_t}: VKA allocated cspace object
    • +
  • cspace_root_data {seL4_Word}: cspace root data capability
    • +
+ +

Back to interface description.

+ +

Struct vm

+ +

Structure representing a VM instance

+ +

Elements:

+ +
    +
  • arch {struct vm_arch}: Architecture specfic vm structure
    • +
  • num_vcpus {unsigned int}: Number of vcpus created for the VM
    • +
  • vcpus {struct vm_vcpu*}: vcpu’s belonging to the VM
    • +
  • mem {struct vm_mem}: Memory management structure
    • +
  • run {struct vm_run}: VM Runtime management structure
    • +
  • cspace {struct vm_cspace}: VM CSpace management structure
    • +
  • host_endpoint {seL4_CPtr}: Host/VMM endpoint. vm_run waits on this enpoint
    • +
  • vka {vka_t *}: Handle to virtual kernel allocator for seL4 kernel object allocation
    • +
  • io_ops {ps_io_ops_t *}: Handle to platforms io ops
    • +
  • simple {simple_t *}: Handle to hosts simple environment
    • +
  • vm_name {char *}: String used to describe VM. Useful for debugging
    • +
  • vm_id {unsigned int}: Identifier for VM. Useful for debugging
    • +
  • vm_initialised {bool}: Boolean flagging whether VM is intialised or not
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_vm_util.html b/projects/virtualization/docs/api/libsel4vm_guest_vm_util.html new file mode 100644 index 00000000000..e9b06e16a1b --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_vm_util.html @@ -0,0 +1,764 @@ + + + + + + + libsel4vm_guest_vm_util | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_vm_util.h

+ +

The libsel4vm VM util interface provides a set of useful methods to query a guest vm instance.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_get_vcpu_tcb(vcpu)

+
+ +
+

vm_get_vcpu(vm, vcpu_id)

+
+ +
+

vm_vcpu_for_target_cpu(vm, target_cpu)

+
+ +
+

vm_find_free_unassigned_vcpu(vm)

+
+ +
+

is_vcpu_online(vcpu)

+
+ +
+

vm_get_vspace(vm)

+
+ +
+

vm_get_vmm_vspace(vm)

+
+ +

Functions

+ +

The interface guest_vm_util.h defines the following functions.

+ +

Function vm_get_vcpu_tcb(vcpu)

+ +

Get the TCB CPtr a given VCPU is associated with

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t}: A handle to the vcpu
    • +
+ +

Returns:

+ +
    +
  • seL4_CPtr of TCB object
    • +
+ +

Back to interface description.

+ +

Function vm_get_vcpu(vm, vcpu_id)

+ +

Get the VCPU CPtr associatated with a given logical ID

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the vm owning the vcpu
    • +
  • vcpu_id {int}: Logical ID of the vcpu
    • +
+ +

Returns:

+ +
    +
  • seL4_CapNull if no vcpu exists, otherwise the seL4_CPtr of the VCPU object
    • +
+ +

Back to interface description.

+ +

Function vm_vcpu_for_target_cpu(vm, target_cpu)

+ +

Get the VCPU object that is assigned to a given target core ID

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the vm owning the vcpu
    • +
  • target_cpu {int}: Target core ID
    • +
+ +

Returns:

+ +
    +
  • NULL if no vcpu is assigned to the target core, otherwise the vm_vcpu_t object
    • +
+ +

Back to interface description.

+ +

Function vm_find_free_unassigned_vcpu(vm)

+ +

Find a VCPU object that hasn’t been assigned to a target core

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the vm owning the vcpu
    • +
+ +

Returns:

+ +
    +
  • NULL if no vcpu can be found, otherwise the vm_vcpu_t object
    • +
+ +

Back to interface description.

+ +

Function is_vcpu_online(vcpu)

+ +

Find if a given VCPU is online

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: A handle to the vcpu
    • +
+ +

Returns:

+ +
    +
  • True if the vcpu is online, otherwise False
    • +
+ +

Back to interface description.

+ +

Function vm_get_vspace(vm)

+ +

Get the vspace of a given VM instance

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
+ +

Returns:

+ +
    +
  • A vspace_t object
    • +
+ +

Back to interface description.

+ +

Function vm_get_vmm_vspace(vm)

+ +

Get the vspace of the host VMM associated with a given VM instance

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
+ +

Returns:

+ +
    +
  • A vspace_t object
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_guest_x86_context.html b/projects/virtualization/docs/api/libsel4vm_guest_x86_context.html new file mode 100644 index 00000000000..36d0e8f2254 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_guest_x86_context.html @@ -0,0 +1,751 @@ + + + + + + + libsel4vm_guest_x86_context | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_x86_context.h

+ +

The libsel4vm x86 context interface provides a set of useful getters and setters on x86 vcpu thread contexts. +This interface is commonly leveraged by VMM’s to initialise a vcpu state, process a vcpu fault and +accordingly update its state.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_set_thread_context(vcpu, context)

+
+ +
+

vm_set_thread_context_reg(vcpu, reg, value)

+
+ +
+

vm_get_thread_context(vcpu, context)

+
+ +
+

vm_get_thread_context_reg(vcpu, reg, value)

+
+ +
+

vm_set_vmcs_field(vcpu, field, value)

+
+ +
+

vm_get_vmcs_field(vcpu, field, value)

+
+ +

Functions

+ +

The interface guest_x86_context.h defines the following functions.

+ +

Function vm_set_thread_context(vcpu, context)

+ +

Set a VCPU’s thread registers given a seL4_VCPUContext

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • context {seL4_VCPUContext}: seL4_VCPUContext applied to VCPU Registers
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_set_thread_context_reg(vcpu, reg, value)

+ +

Set a single VCPU’s thread register in a seL4_VCPUContext

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • reg {vcpu_context_reg_t}: Register enumerated by vcpu_context_reg
    • +
  • value {uint32_t}: Value to set register with
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_get_thread_context(vcpu, context)

+ +

Get a VCPU’s thread context

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • context {seL4_VCPUContext *}: Pointer to user supplied seL4_VCPUContext to populate with VCPU’s current context
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_get_thread_context_reg(vcpu, reg, value)

+ +

Get a single VCPU’s thread register

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • reg {vcpu_context_reg_t}: Register enumerated by vcpu_context_reg
    • +
  • value {uint32_t *}: Pointer to user supplied variable to populate register value with
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_set_vmcs_field(vcpu, field, value)

+ +

Set a VMCS field

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • reg {seL4_Word}: VMCS field
    • +
  • value {uint32_t}: Value to set VMCS field with
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_get_vmcs_field(vcpu, field, value)

+ +

Get a VMCS register

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Handle to the vcpu
    • +
  • reg {seL4_Word}: VMCS field
    • +
  • value {uint32_t *}: Pointer to user supplied variable to populate VMCS field value with
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_x86_guest_vm.html b/projects/virtualization/docs/api/libsel4vm_x86_guest_vm.html new file mode 100644 index 00000000000..e11fb698e96 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_x86_guest_vm.html @@ -0,0 +1,644 @@ + + + + + + + libsel4vm_x86_guest_vm | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_vm_arch.h

+ +

The guest x86 vm interface is central to using libsel4vm on an x86 platform, providing definitions of the x86 guest vm +datastructures and primitives to configure the VM instance.

+ +

Brief content:

+ +

Structs:

+ +
+

vm_vcpu

+
+ +
+

vm_vcpu_arch

+
+ +

Structs

+ +

The interface guest_vm_arch.h defines the following structs.

+ +

Struct vm_vcpu

+ +

Structure representing x86 specific vm properties

+ +

Elements:

+ +
    +
  • vmexit_handler {vmexit_handler_ptr}: Set of exit handler hooks
    • +
  • vmcall_handlers {vmcall_handler_t *}: Set of registered vmcall handlers
    • +
  • vmcall_num_handler {unsigned int}: Total number of registered vmcall handlers
    • +
  • guest_pd {uintptr_t}: Guest physical address of where we built the vm’s page directory
    • +
  • unhandled_ioport_callback {unhandled_ioport_callback_fn}: A callback for processing unhandled ioport faults
    • +
  • unhandled_ioport_callback_cookie {void *}: A cookie to supply to the ioport callback
    • +
  • ioport_list {vm_io_port_list_t}: List of registered ioport handlers
    • +
  • i8259_gs {i8259_t *}: PIC machine state
    • +
+ +

Back to interface description.

+ +

Struct vm_vcpu_arch

+ +

Structure representing x86 specific vcpu properties

+ +

Elements:

+ +
    +
  • guest_state {guest_state_t *}: Current VCPU State
    • +
  • lapic {vm_lapic_t *}: VM local apic
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_x86_ioports.html b/projects/virtualization/docs/api/libsel4vm_x86_ioports.html new file mode 100644 index 00000000000..c5b3393e94c --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_x86_ioports.html @@ -0,0 +1,677 @@ + + + + + + + libsel4vm_x86_ioports | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface ioports.h

+ +

The x86 ioports interface provides a useful abstraction for initialising, registering and handling ioport events +for a guest VM instance. IOPort faults are directed through this interface.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_io_port_add_handler(vm, ioport_range, ioport_interface)

+
+ +
+

vm_register_unhandled_ioport_callback(vm, ioport_callback, cookie)

+
+ +
+

vm_enable_passthrough_ioport(vcpu, port_start, port_end)

+
+ +

Functions

+ +

The interface ioports.h defines the following functions.

+ +

Function vm_io_port_add_handler(vm, ioport_range, ioport_interface)

+ +

Add an io port range for emulation

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • ioport_range {vm_ioport_range_t}: Range of ioport being emulated with the given handler
    • +
  • ioport_interface {vm_ioport_interface_t}: Interface for ioport range, containing io_in and io_out handler functions
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ + + +

Register a callback for processing unhandled ioport faults (faults unknown to libsel4vm)

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • ioport_callback {unhandled_ioport_callback_fn}: A user supplied callback to process unhandled ioport faults
    • +
  • cookie {void *}: A cookie to supply to the callback
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_enable_passthrough_ioport(vcpu, port_start, port_end)

+ +

Enable the passing-through of specific ioport ranges to the VM

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: A handle to the VCPU being given ioport passthrough access
    • +
  • port_start {uint16_t}: Base address of ioport
    • +
  • port_end {uint16_t}: End address of ioport
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vm_x86_vmcall.html b/projects/virtualization/docs/api/libsel4vm_x86_vmcall.html new file mode 100644 index 00000000000..8fdb188f6ca --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vm_x86_vmcall.html @@ -0,0 +1,629 @@ + + + + + + + libsel4vm_x86_vmcall | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface vmcall.h

+ +

The x86 vmcall interface provides methods for registering and managing vmcall handlers. These being used +to process x86 guest hypercalls though the vmcall instruction.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_reg_new_vmcall_handler(vm, func, token)

+
+ +

Functions

+ +

The interface vmcall.h defines the following functions.

+ +

Function vm_reg_new_vmcall_handler(vm, func, token)

+ +

Register a new vmcall handler. The being hypercalls invoked by the +guest through the vmcall instruction. +This being matched with the value found in the vcpu EAX register on a vmcall exception

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • func {vmcall_handler}: A handler function for the given vmcall being registered
    • +
  • token {int}: A token to associate with a vmcall handler.
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_ac_device.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_ac_device.html new file mode 100644 index 00000000000..86977849588 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_ac_device.html @@ -0,0 +1,640 @@ + + + + + + + libsel4vmmplatsupport_arm_ac_device | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface ac_device.h

+ +

The ARM access control device interface facilitates the creation of generic virtual devices in a VM instance with +access control permissions over the devices addressable memory. An access controlled device is often used to abstract +the memory of a specific platform hardware device e.g a clock device. This allows the user to present hardware devices +to a VM instance but limit their permissions with regards to modifying its register state.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_install_generic_ac_device(vm, d, mask, size, action)

+
+ +

Functions

+ +

The interface ac_device.h defines the following functions.

+ +

Function vm_install_generic_ac_device(vm, d, mask, size, action)

+ +

Installs a generic access controlled device +are modifiable by the guest. +‘1’ represents bits that the guest can read and write + ‘0’ represents bits that can only be read by the guest +Underlying memory for the mask should remain accessible for +the life of this device. The mask may be updated at run time +on demand. +cases where the underlying device does not occupy a full +page. If an access lies outside of the range of the mask, +guest access.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: The VM to install the device into
    • +
  • d {const struct device *}: A description of the device to install
    • +
  • mask {void *}: An access mask. The mask provides a map of device bits that
    • +
  • size {size_t}: The size of the mask. This is useful for conserving memory in
    • +
  • action {enum vacdev_action}: Action to take when access is violated.
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_generic_forward_device.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_generic_forward_device.html new file mode 100644 index 00000000000..41cd1dc3e9f --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_generic_forward_device.html @@ -0,0 +1,658 @@ + + + + + + + libsel4vmmplatsupport_arm_generic_forward_device | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface generic_forward_device.h

+ +

This interface facilitates the creation of a virtual device used for +dispatching faults to external handlers. For example when using CAmkES, +a device frame for a real device can be given to a different CAmkES component +and this virtual device will forward read and write faults over a CAmkES +interface so the component can perform or emulate the actions.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_install_generic_forward_device(vm, d, cfg)

+
+ +

Structs:

+ +
+

generic_forward_cfg

+
+ +

Functions

+ +

The interface generic_forward_device.h defines the following functions.

+ +

Function vm_install_generic_forward_device(vm, d, cfg)

+ +

Install the virtual forwarding device into a VM instance

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • Virtual {const struct device *}: device being forwarded
    • +
  • Interface {struct generic_forward_cfg}: for forwarding the devices read and write faults
    • +
+ +

Returns:

+ +
    +
  • -1 for error, otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface generic_forward_device.h defines the following structs.

+ +

Struct generic_forward_cfg

+ +

Interface for forwarding read and write faults

+ +

Elements:

+ +
    +
  • write_fn {forward_write_fn}: A callback for forwarding write faults
    • +
  • read_fn {forward_read_fn}: A callback for forwarding read faults
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_boot_init.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_boot_init.html new file mode 100644 index 00000000000..ba9e8050dcc --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_boot_init.html @@ -0,0 +1,653 @@ + + + + + + + libsel4vmmplatsupport_arm_guest_boot_init | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_boot_init.h

+ +

The libsel4vmmplatsupport arm guest boot init interface provides helpers to initialise the booting state of +a VM instance. This currently only targets booting a Linux guest OS.

+ +

Brief content:

+ +

Functions:

+ +
+

vcpu_set_bootargs(vcpu, pc, mach_type, atags)

+
+ +

Functions

+ +

The interface guest_boot_init.h defines the following functions.

+ +

Function vcpu_set_bootargs(vcpu, pc, mach_type, atags)

+ +

Set the boot args and pc for the VM. The Linux kernel documentation contains a detailed description about +the boot ABI for AARCH32 and +AARCH64

+ +

The register setup for the booting core on AARCH32 is

+ +
    +
  • r0 = 0
    • +
  • r1 = MACH_TYPE
    • +
  • r2 = ATAGS or FTD/DTB address
    • +
+ +

For AARCH64 it is:

+ +
    +
  • x0 = FTD/DTB address
    • +
  • x1 = 0
    • +
  • x2 = 0
    • +
  • x3 = 0
    • +
+ +

Passing a pointer to ATAGs is deprecated, modern kernels use a device tree that is passed as Flattened Device +Tree (FDT), sometimes also called Device Tree Blob (DTB). The parameter MACH_TYPE contains a machine +specific ID, various MACH_TYPE_xxx constants can be found in the +Linux Source code at arch/arm/tools/mach-types +FTDs usually contain all necessary information about the machine, so-1 (0xfff...fff) can be passed.

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: A handle to the boot VCPU
    • +
  • pc {seL4_Word}: The initial PC for the VM
    • +
  • mach_type {seL4_Word}: Linux specific machine ID
    • +
  • atags {seL4_Word}: Linux specific IPA of ATAGS or FTD/DTB address
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for failure
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_reboot.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_reboot.html new file mode 100644 index 00000000000..b7870de2af4 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_reboot.html @@ -0,0 +1,721 @@ + + + + + + + libsel4vmmplatsupport_arm_guest_reboot | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_reboot.h

+ +

The guest reboot interface provides a series of helpers for registering callbacks when rebooting the VMM. +This interface giving various VMM components and drivers the ability to reset necessary state on a reboot.

+ +

Brief content:

+ +

Functions:

+ +
+

vmm_init_reboot_hooks_list(rb_hooks_list)

+
+ +
+

vmm_register_reboot_callback(rb_hooks_list, hook, token)

+
+ +
+

vmm_process_reboot_callbacks(vm, rb_hooks_list)

+
+ +

Structs:

+ +
+

reboot_hook

+
+ +
+

reboot_hooks_list

+
+ +

Functions

+ +

The interface guest_reboot.h defines the following functions.

+ +

Function vmm_init_reboot_hooks_list(rb_hooks_list)

+ +

Initialise state of a given reboot hooks list

+ +

Parameters:

+ +
    +
  • rb_hooks_list {reboot_hooks_list_t *}: Handle to reboot hooks list
    • +
+ +

Returns:

+ +
    +
  • 0 for success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vmm_register_reboot_callback(rb_hooks_list, hook, token)

+ +

Register a reboot callback within a given reboot hooks list

+ +

Parameters:

+ +
    +
  • rb_hooks_list {reboot_hooks_list_t *}: Handle to reboot hooks list
    • +
  • hook {rb_hook_fn}: Reboot callback to be invoked when list is processed
    • +
  • token {void *}: Cookie passed to reboot callback when invoked
    • +
+ +

Returns:

+ +
    +
  • 0 for success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vmm_process_reboot_callbacks(vm, rb_hooks_list)

+ +

Process the reboot hooks registered in a reboot hooks list

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: Handle to vm - passed onto reboot callback
    • +
  • rb_hooks_list {reboot_hooks_list_t *}: Handle to reboot hooks list
    • +
+ +

Returns:

+ +
    +
  • 0 for success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface guest_reboot.h defines the following structs.

+ +

Struct reboot_hook

+ +

Datastructure representing a reboot hook, containing a callback function to invoke when processing the +hook

+ +

Elements:

+ +
    +
  • fn {reboot_hook_fn}: Function pointer to reboot callback
    • +
  • token {void *}: Cookie passed to reboot callback when invoked
    • +
+ +

Back to interface description.

+ +

Struct reboot_hooks_list

+ +

Reboot hooks management datastructure. Contains a list of reboot hooks that a VMM registers

+ +

Elements:

+ +
    +
  • rb_hooks {reboot_hook_t *}: List of reboot hooks
    • +
  • nhooks {size_t}: Number of reboot hooks in rb_hooks member
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_vcpu_fault.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_vcpu_fault.html new file mode 100644 index 00000000000..a5abe79e76a --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_vcpu_fault.html @@ -0,0 +1,651 @@ + + + + + + + libsel4vmmplatsupport_arm_guest_vcpu_fault | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_vcpu_fault.h

+ +

The arm guest vcpu fault interface provides a module for registering +and processing vcpu faults. The module can be used such that it directly hooks +into an ARM VMMs unhandled vcpu callback interface or wrapped over by another driver. This +module particularly provides useful handlers to vcpu faults relating to SMC and MSR/MRS instructions.

+ +

Brief content:

+ +

Functions:

+ +
+

vmm_handle_arm_vcpu_exception(vcpu, hsr, cookie)

+
+ +
+

register_arm_vcpu_exception_handler(ec_class, exception_handler)

+
+ +

Functions

+ +

The interface guest_vcpu_fault.h defines the following functions.

+ + + +

Handle a vcpu exception given the HSR value - Syndrome information

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: A handle to the faulting VCPU
    • +
  • hsr {uint32_t }: Syndrome information value describing the exception/fault
    • +
  • cookie {void *}: User supplied cookie to pass onto exception
    • +
+ +

Returns:

+ +
    +
  • -1 on error, otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Function register_arm_vcpu_exception_handler(ec_class, exception_handler)

+ +

Register a handler to a vcpu exception class

+ +

Parameters:

+ +
    +
  • ec_class {uint32_t}: The exception class the handler will be called on
    • +
  • exception_handler {vcpu_exception_handler_fn}: Function pointer to the exception handler
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_vcpu_util.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_vcpu_util.html new file mode 100644 index 00000000000..1ef0a944308 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_vcpu_util.html @@ -0,0 +1,626 @@ + + + + + + + libsel4vmmplatsupport_arm_guest_vcpu_util | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_vcpu_util.h

+ +

The ARM guest vcpu util interface provides abstractions and helpers for managing libsel4vm vcpus on an ARM platform.

+ +

Brief content:

+ +

Functions:

+ +
+

fdt_generate_plat_vcpu_node(vm, fdt)

+
+ +

Functions

+ +

The interface guest_vcpu_util.h defines the following functions.

+ +

Function fdt_generate_plat_vcpu_node(vm, fdt)

+ +

Generate a CPU device node for a given fdt. This taking into account +the vcpus created for the VM.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • fdt {void *}: FDT blob to append generated device node
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_vpci.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_vpci.html new file mode 100644 index 00000000000..cd1cea6e418 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_vpci.html @@ -0,0 +1,654 @@ + + + + + + + libsel4vmmplatsupport_arm_vpci | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface vpci.h

+ +

The libsel4vmmplatsupport vpci interface presents a Virtual PCI driver for ARM-based VM’s. +Using the vmm_pci_space_t management interface, the vpci driver establishes the configuration +space in the guest VM. The driver also handles and processes all subsequent memory and ioport accesses to the +virtual pci device.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_install_vpci(vm, io_port, pci)

+
+ +
+

fdt_generate_vpci_node(vm, pci, fdt, gic_phandle)

+
+ +

Functions

+ +

The interface vpci.h defines the following functions.

+ +

Function vm_install_vpci(vm, io_port, pci)

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • io_port {vmm_io_port_list_t *}: IOPort library instance to emulate io accesses with
    • +
  • pci {vmm_pci_space_t }: PCI library instance to emulate PCI device accesses with
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ +

Function fdt_generate_vpci_node(vm, pci, fdt, gic_phandle)

+ +

Generate a PCI device node for a given fdt. This taking into account +the virtual PCI device configuration space.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • PCI {vmm_pci_space_t *}: library instance to generate fdt node
    • +
  • fdt {void *}: FDT blob to append generated device node
    • +
  • gic_phandle {int}: Phandle of IRQ controller to generate a correct interrupt map property
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_vusb.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_vusb.html new file mode 100644 index 00000000000..ff8a97245c5 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_vusb.html @@ -0,0 +1,655 @@ + + + + + + + libsel4vmmplatsupport_arm_vusb | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface vusb.h

+ +

The libsel4vmmplatsupport vusb interface presents a Virtual USB driver for ARM-based VM’s.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_install_vusb(vm, hcd, pbase, virq, vmm_ncap, vm_ncap, badge)

+
+ +
+

vm_vusb_notify(vusb)

+
+ +

Functions

+ +

The interface vusb.h defines the following functions.

+ +

Function vm_install_vusb(vm, hcd, pbase, virq, vmm_ncap, vm_ncap, badge)

+ +

Install a virtual usb device +Calls made to this hcd may be redirected for filtering.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: The VM in which to install the device
    • +
  • hcd {usb_host_t *}: The USB host controller that should be used for USB transactions.
    • +
  • pbase {uintptr_t}: The guest physical address of the device (2 pages)
    • +
  • virq {int}: The virtual IRQ number for this device
    • +
  • vmm_ncap {seL4_CPtr}: The capability to the endpoint at which the VMM waits for notifications.
    • +
  • vm_ncap {seL4_CPtr}: The index at which to install a notification capability into the VM
    • +
  • badge {int}: The seL4 badge which should be applied to the notification capability.
    • +
+ +

Returns:

+ +
    +
  • A handle to the virtual usb device, or NULL on failure
    • +
+ +

Back to interface description.

+ +

Function vm_vusb_notify(vusb)

+ +

This function should be called when a notification is received from the +VM. The notification is identifyable by a message on the fault endpoint +of the VM which has a badge that matches that which was passed into the +vm_install_vusb function.

+ +

Parameters:

+ +
    +
  • vusb {vusb_device_t *}: A handle to a virtual usb device
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_cross_vm_connection.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_cross_vm_connection.html new file mode 100644 index 00000000000..57ed33a4776 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_cross_vm_connection.html @@ -0,0 +1,706 @@ + + + + + + + libsel4vmmplatsupport_cross_vm_connection | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface cross_vm_connection.h

+ +

The crossvm connection module facilitates the creation of communication channels between VM’s and other +components on a seL4-based system. The module exports registered cross vm connections to a Linux VM such that +processes can access them from userlevel. This being facilitated over a virtual PCI device.

+ +

Brief content:

+ +

Functions:

+ +
+

cross_vm_connections_init_common(vm, connection_base_addr, connections, num_connections, pci, alloc_irq)

+
+ +
+

consume_connection_event(vm, event_id, inject_irq)

+
+ +

Structs:

+ +
+

crossvm_dataport_handle

+
+ +
+

crossvm_handle

+
+ +

Functions

+ +

The interface cross_vm_connection.h defines the following functions.

+ +

Function cross_vm_connections_init_common(vm, connection_base_addr, connections, num_connections, pci, alloc_irq)

+ +

Install a set of cross vm connections into a guest VM (for either x86 or ARM VM platforms) +for the crossvm connectors +PCI device

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • connection_base_addr {uintptr_t}: The base guest physical address that can be used to reserve memory
    • +
  • connections {crossvm_handle_t *}: The set of crossvm connections to be initialised and installed in the guest
    • +
  • num_connection {int}: The number of connections passed in through the ‘connections’ parameter
    • +
  • pci {vmm_pci_space_t *}: A handle to the VM’s host PCI device. The connections are advertised through the
    • +
  • alloc_irq {alloc_free_interrupt_fn}: A function that is used to allocated an irq number for the crossvm connections
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Function consume_connection_event(vm, event_id, inject_irq)

+ +

Handler to consume a cross vm connection event. This being called by the VMM when it recieves a notification from an +external process. The event is then relayed onto the VM.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • event_id {seL4_Word}: The id that corresponds to the occuring event
    • +
  • inject_irq {bool}: Whether to inject an interrupt into the VM
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Structs

+ +

The interface cross_vm_connection.h defines the following structs.

+ +

Struct crossvm_dataport_handle

+ +

Datastructure representing a dataport of a crossvm connection

+ +

Elements:

+ +
    +
  • frame_size_bits {size_t}: Bit size of a single frame in the frames member
    • +
  • num_frames {int}: Total number of frames in the frames member
    • +
  • frames {seL4_CPtr *}: The set of frames backing the dataport
    • +
+ +

Back to interface description.

+ +

Struct crossvm_handle

+ +

Datastructure representing a single crossvm connection +This is matched on when invoking consume_connection_event

+ +

Elements:

+ +
    +
  • dataport {crossvm_dataport_handle_t *}: The dataport associated with the crossvm connection
    • +
  • emit_fn {emit_fn}: The function pointer to the crossvm emit method
    • +
  • consume_id {seL4_Word}: The identifier used for the crossvm connection when receiving incoming notifications
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_device.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_device.html new file mode 100644 index 00000000000..42f2245a811 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_device.html @@ -0,0 +1,721 @@ + + + + + + + libsel4vmmplatsupport_device | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface device.h

+ +

The device.h interface provides a series of datastructures and helpers to manage VMM devices.

+ +

Brief content:

+ +

Functions:

+ +
+

device_list_init(list)

+
+ +
+

add_device(dev_list, d)

+
+ +
+

find_device_by_pa(dev_list, addr)

+
+ +

Structs:

+ +
+

device

+
+ +
+

device_list

+
+ +

Functions

+ +

The interface device.h defines the following functions.

+ +

Function device_list_init(list)

+ +

Initialise an empty device list

+ +

Parameters:

+ +
    +
  • list {device_list_t *}: device list to initialise
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function add_device(dev_list, d)

+ +

Add a generic device to a given device list without performing any initialisation of the device

+ +

Parameters:

+ +
    +
  • dev_list {device_list_t *}: A handle to the device list that the device should be installed into
    • +
  • device {const struct device *}: A description of the device
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function find_device_by_pa(dev_list, addr)

+ +

Find a device by a given addr within a device list

+ +

Parameters:

+ +
    +
  • dev_list {device_list_t *}: Device list to search within
    • +
  • addr {uintptr_t}: Add to search with
    • +
+ +

Returns:

+ +
    +
  • Pointer to device if found, otherwise NULL if not found
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface device.h defines the following structs.

+ +

Struct device

+ +

Device Management Object

+ +

Elements:

+ +
    +
  • name {const char *}: A string representation of the device. Useful for debugging
    • +
  • pstart {seL4_Word}: The physical address of the device
    • +
  • size {seL4_Word}: Device mapping size
    • +
  • handle_device_fault {int *(vm_t, vm_vcpu_t, dev, addr, len)}: Fault handler
    • +
  • priv {void *}: Device emulation private data
    • +
+ +

Back to interface description.

+ +

Struct device_list

+ +

Management for a list of devices

+ +

Elements:

+ +
    +
  • devices {struct device *}: List of registered devices
    • +
  • num_devices {int}: Total number of registered devices
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_device_utils.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_device_utils.html new file mode 100644 index 00000000000..3cbad858d13 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_device_utils.html @@ -0,0 +1,674 @@ + + + + + + + libsel4vmmplatsupport_device_utils | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface device_utils.h

+ +

The device utils interface provides various helpers to establish different types devices for a given VM +instance.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_install_passthrough_device(vm, device)

+
+ +
+

vm_install_ram_only_device(vm, device)

+
+ +
+

vm_install_listening_device(vm, device)

+
+ +

Functions

+ +

The interface device_utils.h defines the following functions.

+ +

Function vm_install_passthrough_device(vm, device)

+ +

Install a passthrough device into a VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM that the device should be install to
    • +
  • device {const struct device *}: A description of the device
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_install_ram_only_device(vm, device)

+ +

Install a device backed by ram into a VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM that the device should be install to
    • +
  • device {const struct device *}: A description of the device
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 for error
    • +
+ +

Back to interface description.

+ +

Function vm_install_listening_device(vm, device)

+ +

Install a passthrough device into a VM, but trap and print all access

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM that the device should be install to
    • +
  • device {const struct device *}: A description of the device
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_image.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_image.html new file mode 100644 index 00000000000..973b529227a --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_image.html @@ -0,0 +1,703 @@ + + + + + + + libsel4vmmplatsupport_guest_image | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_image.h

+ +

The guest image interface provides general utilites to load guest vm images (e.g. kernel, initrd, modules). +This interface probably stops being relevant/useful after we start running a VM instance.

+ +

Brief content:

+ +

Functions:

+ +
+

vm_load_guest_kernel(vm, kernel_name, load_address, alignment, guest_kernel_image)

+
+ +
+

vm_load_guest_module(vm, module_name, load_address, alignment, guest_image)

+
+ +

Structs:

+ +
+

guest_image

+
+ +
+

guest_kernel_image

+
+ +

Functions

+ +

The interface guest_image.h defines the following functions.

+ +

Function vm_load_guest_kernel(vm, kernel_name, load_address, alignment, guest_kernel_image)

+ +

Load guest kernel image

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: Handle to the VM
    • +
  • kernel_name {const char *}: Name of the kernel image
    • +
  • load_address {uintptr_t}: Address to load guest kernel image at
    • +
  • alignment {size_t}: Alignment for loading kernel image
    • +
  • guest_kernel_image {guest_kernel_image_t *}: Handle to information regarding the resulted loading of the guest kernel image
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 on error
    • +
+ +

Back to interface description.

+ +

Function vm_load_guest_module(vm, module_name, load_address, alignment, guest_image)

+ +

Load guest kernel module e.g. initrd

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: Handle to the VM
    • +
  • module_name {const char *}: Name of the module image
    • +
  • load_address {uintptr_t}: Address to load guest kernel image at
    • +
  • alignment {size_t}: Alignment for loading module image
    • +
  • guest_image {guest_image_t *}: Handle to information regarding the resulted loading of the guest module image
    • +
+ +

Returns:

+ +
    +
  • 0 on success, otherwise -1 on error
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface guest_image.h defines the following structs.

+ +

Struct guest_image

+ +

General datastructure for managing a guest image

+ +

Elements:

+ +
    +
  • load_paddr {uintptr_t}: Base address (in guest physical) where the image was loaded
    • +
  • alignment {size_t}: Alignment we used when loading the image
    • +
  • size {size_t}: Size of guest image
    • +
+ +

Back to interface description.

+ +

Struct guest_kernel_image

+ +

Stores information about the guest kernel image we are loading.

+ +

Elements:

+ +
    +
  • kernel_image {guest_image_t}: Datastructure referring to guest kernel image
    • +
  • kernel_image_arch {guest_kernel_image_arch_t}: Architecture specific information for loaded guest image
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_memory_util.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_memory_util.html new file mode 100644 index 00000000000..b9d50c9d8e2 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_memory_util.html @@ -0,0 +1,753 @@ + + + + + + + libsel4vmmplatsupport_guest_memory_util | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_memory_util.h

+ +

The guest memory util interface provides various utilities and helpers for using the libsel4vm guest memory +interface. The methods in the interface cover common usage patterns when managing memory for a VM instance.

+ +

Brief content:

+ +

Functions:

+ +
+

create_allocated_reservation_frame(vm, addr, rights, alloc_fault_callback, alloc_fault_cookie)

+
+ +
+

create_device_reservation_frame(vm, addr, rights, fault_callback, fault_cookie)

+
+ +
+

map_ut_alloc_reservation_with_base_paddr(vm, paddr, reservation)

+
+ +
+

map_ut_alloc_reservation(vm, reservation)

+
+ +
+

map_frame_alloc_reservation(vm, reservation)

+
+ +
+

map_maybe_device_reservation(vm, reservation)

+
+ +

Functions

+ +

The interface guest_memory_util.h defines the following functions.

+ + + +

Create and map a reservation for a vka allocated frame. The allocated frame is mapped in both the vm and vmm vspace

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • addr {uintptr_t}: Address of emulated frame
    • +
  • rights {seL4_CapRights_t}: Rights for mapping the allocated frame into the vm’s vspace
    • +
  • alloc_fault_callback {memory_fault_callback_fn}: Fault callback for allocated frame
    • +
  • alloc_fault_cookie {void *}: Cookie for fault callback
    • +
+ +

Returns:

+ +
    +
  • Address of allocated frame in vmm vspace
    • +
+ +

Back to interface description.

+ + + +

Create and map a reservation for a device frame. The device frame is mapped in both the vm and vmm vspace

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • addr {uintptr_t}: Address of emulated frame
    • +
  • rights {seL4_CapRights_t}: Rights for mapping the device frame into the vm’s vspace
    • +
  • fault_callback {memory_fault_callback_fn}: Fault callback for the frame
    • +
  • fault_cookie {void *}: Cookie for fault callback
    • +
+ +

Returns:

+ +
    +
  • Address of device frame in vmm vspace
    • +
+ +

Back to interface description.

+ +

Function map_ut_alloc_reservation_with_base_paddr(vm, paddr, reservation)

+ +

Map a guest reservation backed with untyped frames allocated from a base paddr

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • paddr {uintptr_t}: Base paddr to allocate from
    • +
  • reservation {vm_memory_reservation_t *}: Pointer to reservation object being mapped
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Function map_ut_alloc_reservation(vm, reservation)

+ +

Map a guest reservation backed with untyped frames

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • reservation {vm_memory_reservation_t *}: Pointer to reservation object being mapped
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Function map_frame_alloc_reservation(vm, reservation)

+ +

Map a guest reservation backed with free vka frames

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • reservation {vm_memory_reservation_t *}: Pointer to reservation object being mapped
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Function map_maybe_device_reservation(vm, reservation)

+ +

Map a guest reservation backed with device frames

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • reservation {vm_memory_reservation_t *}: Pointer to reservation object being mapped
    • +
+ +

Returns:

+ +
    +
  • -1 on failure otherwise 0 for success
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_vcpu_util.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_vcpu_util.html new file mode 100644 index 00000000000..b7d3a4cf0db --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_vcpu_util.html @@ -0,0 +1,626 @@ + + + + + + + libsel4vmmplatsupport_guest_vcpu_util | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_vcpu_util.h

+ +

The guest vcpu util interface provides abstractions and helpers for managing libsel4vm vcpus.

+ +

Brief content:

+ +

Functions:

+ +
+

create_vmm_plat_vcpu(vm, priority)

+
+ +

Functions

+ +

The interface guest_vcpu_util.h defines the following functions.

+ +

Function create_vmm_plat_vcpu(vm, priority)

+ +

Create a new platform vcpu. This is a wrapper around the libsel4vm function vm_create_vcpu however +further intialises and configures the vcpu with platform specific attributes

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • priority {int}: Priority of the new vcpu thread
    • +
+ +

Returns:

+ +
    +
  • NULL for error, otherwise pointer to created vm_vcpu_t object
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_ioports.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_ioports.html new file mode 100644 index 00000000000..e2dad68b03b --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_ioports.html @@ -0,0 +1,768 @@ + + + + + + + libsel4vmmplatsupport_ioports | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface ioports.h

+ +

The ioports interface provides a useful abstraction for initialising, registering and handling ioport events +for a guest VM instance. This is independent from the x86 libsel4vm ioports interface. This interface is intended +to be more generic and architecture independent, useful for usecases that require ioports without architecture +support (virtio PCI).

+ +

Brief content:

+ +

Functions:

+ +
+

vmm_io_port_init(io_list, ioport_alloc_addr)

+
+ +
+

vmm_io_port_add_handler(io_list, ioport_range, ioport_interface, port_type)

+
+ +
+

emulate_io_handler(io_port, port_no, is_in, size, data)

+
+ +

Structs:

+ +
+

ioport_range

+
+ +
+

ioport_interface

+
+ +
+

ioport_entry

+
+ +
+

vmm_io_list

+
+ +

Functions

+ +

The interface ioports.h defines the following functions.

+ +

Function vmm_io_port_init(io_list, ioport_alloc_addr)

+ +

Initialize the io port list manager. +This is used when registering ioport handlers of type ‘IOPORT_FREE’

+ +

Parameters:

+ +
    +
  • io_list {vmm_io_port_list_t **}: Pointer to io_port list handle. This will be allocated and initialised
    • +
  • ioport_alloc_addr {uint16_t}: Base ioport address we can safely bump allocate from (doesn’t conflict with other ioports).
    • +
+ +

Returns:

+ +
    +
  • 0 for success, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Function vmm_io_port_add_handler(io_list, ioport_range, ioport_interface, port_type)

+ +

Add an io port range for emulation

+ +

Parameters:

+ +
    +
  • io_list {vmm_io_port_list_t *}: Handle to ioport list. This is where the new ioport handler will be appended to
    • +
  • ioport_range {ioport_range_t}: Range the ioport handler will emulate
    • +
  • ioport_interface {ioport_interface_t}: IOPort emulation interface
    • +
  • port_type {ioport_type_t}: The type of ioport being registered - IOPORT_FREE, IOPORT_ADDR
    • +
+ +

Returns:

+ +
    +
  • NULL for error, otherwise pointer to newly created ioport entry
    • +
+ +

Back to interface description.

+ +

Function emulate_io_handler(io_port, port_no, is_in, size, data)

+ +

From a set of registered ioports, emulate an io instruction given a current ioport access.

+ +

Parameters:

+ +
    +
  • io_port {vmm_io_port_list_t *}: List of registered ioports with in/out handlers
    • +
  • port_no {unsigned int}: IOPort address being accessed
    • +
  • is_in {bool}: True if we are performing an io in operation, otherwise False
    • +
  • size {size_t}: Size of io access
    • +
  • data {unsigned int *}: Pointer with the data being written if io-out op, otherwise will be populated with data from an io-in op
    • +
+ +

Returns:

+ +
    +
  • 0 if handled, 1 if unhandled, otherwise -1 for error
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface ioports.h defines the following structs.

+ +

Struct ioport_range

+ +

Range of ioport handler

+ +

Elements:

+ +
    +
  • start {uint16_t}: Start address of ioport range
    • +
  • end {uint16_t}: End address of ioport range
    • +
  • size {uint16_t}: Size of ioport range
    • +
+ +

Back to interface description.

+ +

Struct ioport_interface

+ +

Datastructure used for ioport emulation, containing handlers for the ioport range

+ +

Elements:

+ +
    +
  • cookie {void *}: User supplied cookie to pass onto handlers
    • +
  • port_in {ioport_in_fn}: IO in operation handler
    • +
  • port_out {ioport_out_fn}: IO out operation handler
    • +
  • desc {const char *}: IOPort description, useful for debugging
    • +
+ +

Back to interface description.

+ +

Struct ioport_entry

+ +

Datastructure used to present a registered ioport range

+ +

Elements:

+ +
    +
  • range {ioport_range_t}: IO address range of ioport entry
    • +
  • interface {ioport_interface_t}: Emulation interface for ioport range
    • +
+ +

Back to interface description.

+ +

Struct vmm_io_list

+ +

Parent datastructure used to maintain a list of registered ioports

+ +

Elements:

+ +
    +
  • num_ioports {int}: Total number of registered ioports
    • +
  • List {ioport_entry_t **}: of registered ioport objects
    • +
  • alloc_addr {uint16_t}: Base ioport address we can safely bump allocate from, used when registering ioport handlers of type ‘IOPORT_FREE’
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_pci.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_pci.html new file mode 100644 index 00000000000..9ea3309e047 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_pci.html @@ -0,0 +1,764 @@ + + + + + + + libsel4vmmplatsupport_pci | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface pci.h

+ +

This interface presents a VMM PCI Driver. This manages the host’s PCI devices, and handles guest OS PCI config space +read & writes.

+ +

Brief content:

+ +

Functions:

+ +
+

vmm_pci_init(space)

+
+ +
+

vmm_pci_add_entry(space, entry, addr)

+
+ +
+

make_addr_reg_from_config(conf, addr, reg)

+
+ +
+

find_device(self, addr)

+
+ +

Structs:

+ +
+

vmm_pci_address

+
+ +
+

vmm_pci_entry

+
+ +
+

vmm_pci_sapce

+
+ +

Functions

+ +

The interface pci.h defines the following functions.

+ +

Function vmm_pci_init(space)

+ +

Initialize PCI space

+ +

Parameters:

+ +
    +
  • space {vmm_pci_space_t **}: Pointer to PCI space being initialised
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Function vmm_pci_add_entry(space, entry, addr)

+ +

Add a PCI entry. Optionally reports where it is located

+ +

Parameters:

+ +
    +
  • space {vmm_pci_space_t *}: PCI space handle
    • +
  • entry {vmm_pci_entry_t}: PCI entry being addr
    • +
  • addr {vmm_pci_addr_t *}: Resulting PCI address where entry gets located
    • +
+ +

Returns:

+ +
    +
  • 0 on success, -1 on error
    • +
+ +

Back to interface description.

+ +

Function make_addr_reg_from_config(conf, addr, reg)

+ +

Convert config to pci address

+ +

Parameters:

+ +
    +
  • conf {uint32_t}: Configuration value to convert to pci address
    • +
  • addr {vmm_pci_address_t *}: Resulting PCI address
    • +
  • reg {uint8_t *}: Resulting register value
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Function find_device(self, addr)

+ +

Find PCI device given a PCI address (Bus/Dev/Func)

+ +

Parameters:

+ +
    +
  • self {vmm_pci_space_t *}: PCI space handle
    • +
  • addr {vmm_pci_address_t}: PCI address of device
    • +
+ +

Returns:

+ +
    +
  • NULL on error, otherwise pointer to registered pci entry
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface pci.h defines the following structs.

+ +

Struct vmm_pci_address

+ +

Represents a PCI address by Bus/Device/Function

+ +

Elements:

+ +
    +
  • bus {uint8_t}: Bus value
    • +
  • dev {uint8_t}: Device value
    • +
  • fun {uint8_t}: Function value
    • +
+ +

Back to interface description.

+ +

Struct vmm_pci_entry

+ +

Abstracts the virtual PCI device. This is is inserted into the virtual PCI configuration space

+ +

Elements:

+ +
    +
  • cookie {void *}: User supplied cookie to pass onto callback functions
    • +
  • ioread {int *(void *cookie, int offset, int size, uint32_t *result)}: Configuration space read callback
    • +
  • iowrite {int *(void *cookie, int offset, int size, uint32_t value)}: Configuration space write callback
    • +
+ +

Back to interface description.

+ +

Struct vmm_pci_sapce

+ +

Represents a single host virtual PCI space + This only supports one bus at the moment.

+ +

Elements:

+ +
    +
  • bus {vmm_pci_entry_t *}: The PCI bus, representing 32 devices, each of which has 8 functions
    • +
  • conf_port_addr {uint32_t}: The current config address for IO port emulation
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_pci_helper.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_pci_helper.html new file mode 100644 index 00000000000..a21b6a07990 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_pci_helper.html @@ -0,0 +1,965 @@ + + + + + + + libsel4vmmplatsupport_pci_helper | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface pci.h

+ +

This interface presents a series of helpers when using the VMM PCI Driver. These helpers assisting with +the creation of pci device entries and accessors the their configuration spaces.

+ +

Brief content:

+ +

Functions:

+ +
+

vmm_pci_entry_ignore_write(cookie, offset, size, value)

+
+ +
+

vmm_pci_mem_device_read(cookie, offset, size, result)

+
+ +
+

vmm_pci_mem_device_write(cookie, offset, size, value)

+
+ +
+

define_pci_host_bridge(bridge)

+
+ +
+

vmm_pci_create_passthrough(addr, config)

+
+ +
+

vmm_pci_create_bar_emulation(existing, num_bars, bars)

+
+ +
+

vmm_pci_create_irq_emulation(existing, irq)

+
+ +
+

vmm_pci_create_cap_emulation(existing, num_caps, cap, num_ranges, range_starts, range_ends)

+
+ +

Structs:

+ +
+

vmm_pci_device_def

+
+ +
+

vmm_pci_bar

+
+ +
+

pci_bar_emulation

+
+ +
+

pci_irq_emulation

+
+ +
+

pci_passthrough_device

+
+ +
+

pci_cap_emulation

+
+ +

Functions

+ +

The interface pci.h defines the following functions.

+ +

Function vmm_pci_entry_ignore_write(cookie, offset, size, value)

+ +

Helper write function that just ignores any writes

+ +

Parameters:

+ +
    +
  • cookie {void *}: User supplied PCI entry cookie
    • +
  • offset {int}: Offset into PCI device header
    • +
  • size {int}: Size of data to be written
    • +
  • value {uint32_t}: value to write to PCI device header offset
    • +
+ +

Returns:

+ +
    +
  • Returns 0
    • +
+ +

Back to interface description.

+ +

Function vmm_pci_mem_device_read(cookie, offset, size, result)

+ +

Read method for a PCI devices memory +@result {uint32_t *} result Resulting value read back from PCI device header

+ +

Parameters:

+ +
    +
  • cookie {void *}: PCI device header
    • +
  • offset {int}: Offset into PCI device header
    • +
  • size {int}: Size of data to be read
    • +
+ +

Returns:

+ +
    +
  • 0 if success, -1 if error
    • +
+ +

Back to interface description.

+ +

Function vmm_pci_mem_device_write(cookie, offset, size, value)

+ +

Write method for a PCI devices memory +@value {uint32_t} value Value to write to PCI device header offset

+ +

Parameters:

+ +
    +
  • cookie {void *}: PCI device header
    • +
  • offset {int}: Offset into PCI device header
    • +
  • size {int}: Size of data to be read
    • +
+ +

Returns:

+ +
    +
  • 0 if success, -1 if error
    • +
+ +

Back to interface description.

+ +

Function define_pci_host_bridge(bridge)

+ +

Defines the configuration space values of the PCI host bridge

+ +

Parameters:

+ +
    +
  • bridge {vmm_pci_device_def_t *}: PCI bridge device definition
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Function vmm_pci_create_passthrough(addr, config)

+ +

Construct a pure passthrough device based on the real PCI. This is almost always useless as +you will almost certainly want to rebase io memory

+ +

Parameters:

+ +
    +
  • addr {vmm_pci_address_t}: Address of passthrough PCI device
    • +
  • config {vmm_pci_config_t}: Ops for accessing the passthrough config space
    • +
+ +

Returns:

+ +
    +
  • vmm_pci_entry_t for passthrough device
    • +
+ +

Back to interface description.

+ +

Function vmm_pci_create_bar_emulation(existing, num_bars, bars)

+ +

Construct a pci entry that emulates configuration space bar read/write’s. The rest of the configuration space is passed on

+ +

Parameters:

+ +
    +
  • existing {vmm_pci_entry_t}: Existing PCI entry to wrap over and emulate its bar accesses
    • +
  • num_bars {int}: Number of emulated bars in PCI entry
    • +
  • bars {vmm_pci_bar_t *}: Set of bars to emulate access to
    • +
+ +

Returns:

+ +
    +
  • vmm_pci_entry_t for emulated bar device
    • +
+ +

Back to interface description.

+ +

Function vmm_pci_create_irq_emulation(existing, irq)

+ +

Construct a pci entry the emulates configuration space interrupt read/write’s. The rest of the configuration space is passed on

+ +

Parameters:

+ +
    +
  • existing {vmm_pci_entry_t}: Existing PCI entry to wrap over and emulate its IRQ accesses
    • +
  • irq {int}: IRQ line value in PCI entry
    • +
+ +

Returns:

+ +
    +
  • vmm_pci_entry_t for emulated irq device
    • +
+ +

Back to interface description.

+ +

Function vmm_pci_create_cap_emulation(existing, num_caps, cap, num_ranges, range_starts, range_ends)

+ +

Capability space emulation. Takes list of addresses to use to form a capability linked list, as well as a +ranges of the capability space that should be directly disallowed. Assumes a type 0 device.

+ +

Parameters:

+ +
    +
  • existing {vmm_pci_entry_t}: Existing PCI entry to wrap over and emulated it capability space accesses
    • +
  • num_caps {int}: Number of caps in capability space
    • +
  • caps {uint8_t *}: Capability list
    • +
  • num_ranges {int}: Number of disallowed/ignored capability ranges e.g. MSI capabilities
    • +
  • range_starts {uint8_t *}: Array of starting indexes of ignored capability ranges
    • +
  • range_end {uint8_t *}: Array of ending idexes of ignored capabilities range
    • +
+ +

Returns:

+ +
    +
  • vmm_pci_entry_t with an emulated capability space
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface pci.h defines the following structs.

+ +

Struct vmm_pci_device_def

+ +

Struct definition of a PCI device. This is used for emulating a device from +purely memory reads. This is not generally useful on its own, but provides +a nice skeleton

+ +

Elements:

+ +
    +
  • vendor_id {uint16_t}
    • +
  • device_id {uint16_t}
    • +
  • command {uint16_t}
    • +
  • status {uint16_t}
    • +
  • revision_id {uint8_t}
    • +
  • prog_if {uint8_t}
    • +
  • subclass {uint8_t}
    • +
  • class_code {uint8_t}
    • +
  • cache_line_size {uint8_t}
    • +
  • latency_timer {uint8_t}
    • +
  • header_type {uint8_t}
    • +
  • bist {uint8_t}
    • +
  • bar0 {uint32_t}
    • +
  • bar1 {uint32_t}
    • +
  • bar2 {uint32_t}
    • +
  • bar3 {uint32_t}
    • +
  • bar4 {uint32_t}
    • +
  • bar5 {uint32_t}
    • +
  • cardbus {uint32_t}
    • +
  • subsystem_vendor_id {uint16_t}
    • +
  • subsystem_id {uint16_t}
    • +
  • expansion_rom {uint32_t}
    • +
  • caps_pointer {uint8_t}
    • +
  • reserved1 {uint8_t}
    • +
  • reserved2 {uint16_t}
    • +
  • reserved3 {uint32_t}
    • +
  • interrupt_line {uint8_t}
    • +
  • interrupt_pin {uint8_t}
    • +
  • min_grant {uint8_t}
    • +
  • max_latency {uint8_t}
    • +
  • caps_len {int}
    • +
  • caps {void *}
    • +
+ +

Back to interface description.

+ +

Struct vmm_pci_bar

+ +

Represents a PCI bar within a device

+ +

Elements:

+ +
    +
  • mem_type {pci_mem_type_t}: Type of memory supporting PCI bar
    • +
  • address {uintptr_t}: Address of PCI bar
    • +
  • size_bits {size_t}: Size of PCI bar in bits
    • +
+ +

Back to interface description.

+ +

Struct pci_bar_emulation

+ +

Wrapper datastructure over a pci entry and its configuration space. This is leveraged to emulate +BAR accesses in an entries configuration space +the guest OS over-writing elements in the configuration space

+ +

Elements:

+ +
    +
  • passthrough {vmm_pci_entry_t}: PCI entry being emulated
    • +
  • num_bars {int}: Number of PCI bars
    • +
  • bars {vmm_pci_bar_t}: Set of PCI bars being emulated in the PCI entry
    • +
  • bar_writes {uint32_t}: Most recent write to each PCI bar in the configuration space. This avoids
    • +
+ +

Back to interface description.

+ +

Struct pci_irq_emulation

+ +

Wrapper datastructure over a pci entry and its configuration space. This is leveraged to emulate +IRQ line accesses in an entries configuration space

+ +

Elements:

+ +
    +
  • passthrough {vmm_pci_entry_t}: PCI entry being emulated
    • +
  • irq {int}: IRQ line value in PCI entry
    • +
+ +

Back to interface description.

+ +

Struct pci_passthrough_device

+ +

Datastructure providing direct passthrough access to a pci entry configuration space

+ +

Elements:

+ +
    +
  • addr {vmm_pci_address_t}: Address of PCI device
    • +
  • config {vmm_pci_config_t}: Ops for accessing config space
    • +
+ +

Back to interface description.

+ +

Struct pci_cap_emulation

+ +

Wrappper datastructure over a pci entry and its configuration space. This is leveraged to emulate +capabilities in an entries configuration space.

+ +

Elements:

+ +
    +
  • passthrough {vmm_pci_entry_t}: PCI entry being emulation
    • +
  • num_caps {int}: Number of caps in capability space
    • +
  • caps {uint8_t *}: Capability list
    • +
  • num_ignore {int}: Number of disallowed/ignored capability ranges e.g. MSI capabilities
    • +
  • ignore_start {uint8_t *}: Array of starting indexes of ignored capability ranges
    • +
  • ignore_end {uint8_t *}: Array of ending idexes of ignored capabilities range
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_virtio_con.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_virtio_con.html new file mode 100644 index 00000000000..dbc4bebcd25 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_virtio_con.html @@ -0,0 +1,664 @@ + + + + + + + libsel4vmmplatsupport_virtio_con | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface virtio_con.h

+ +

This interface provides the ability to initalise a VMM virtio console driver. This creating a virtio +PCI device in the VM’s virtual pci. This can subsequently be accessed through ‘/dev/hvc0’ in the guest.

+ +

Brief content:

+ +

Functions:

+ +
+

common_make_virtio_con(vm, pci, ioport, ioport_range, port_type, interrupt_pin, interrupt_lin, backend)

+
+ +

Structs:

+ +
+

virtio_con

+
+ +

Functions

+ +

The interface virtio_con.h defines the following functions.

+ +

Function common_make_virtio_con(vm, pci, ioport, ioport_range, port_type, interrupt_pin, interrupt_lin, backend)

+ +

Initialise a new virtio_con device with Base Address Registers (BARs) starting at iobase and backend functions +specified by the console_passthrough struct. +virtio_con_default_backend for default methods.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: Handle to the VM
    • +
  • pci {vmm_pci_space_t *}: PCI library instance to register virtio con device
    • +
  • ioport {vmm_io_port_list_t *}: IOPort library instance to register virtio con ioport
    • +
  • ioport_range {ioport_range_t}: BAR port for front end emulation
    • +
  • iotype {ioport_type_t}: Type of ioport i.e. whether to alloc or use given range
    • +
  • interrupt_pin {unsigned int}: PCI interrupt pin e.g. INTA = 1, INTB = 2 ,…
    • +
  • interrupt_line {unsigned int}: PCI interrupt line for virtio con IRQS
    • +
  • backend {struct console_passthrough}: Function pointers to backend implementation. Can be initialised by
    • +
+ +

Returns:

+ +
    +
  • Pointer to an initialised virtio_con_t, NULL if error.
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface virtio_con.h defines the following structs.

+ +

Struct virtio_con

+ +

Virtio Console Driver Interface

+ +

Elements:

+ +
    +
  • iobase {unsigned int}: IO Port base for virtio con device
    • +
  • emul {virtio_emul_t *}: Virtio console emulation interface: VMM <-> Guest
    • +
  • emul_driver_funcs {struct console_passthrough}: Virtio console emulation functions: VMM <-> Guest
    • +
  • ioops {ps_io_ops_t}: Platform support io ops datastructure
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_virtio_net.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_virtio_net.html new file mode 100644 index 00000000000..62ffd582b37 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_virtio_net.html @@ -0,0 +1,687 @@ + + + + + + + libsel4vmmplatsupport_virtio_net | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface virtio_net.h

+ +

This interface provides the ability to initalise a VMM virtio net driver. This creating a virtio +PCI device in the VM’s virtual pci. This can subsequently be accessed as an ethernet interface in the +guest.

+ +

Brief content:

+ +

Functions:

+ +
+

common_make_virtio_net(vm, pci, ioport, ioport_range, port_type, interrupt_pin, interrupt_line, backend)

+
+ +
+

virtio_net_default_backend()

+
+ +

Structs:

+ +
+

virtio_net

+
+ +

Functions

+ +

The interface virtio_net.h defines the following functions.

+ +

Function common_make_virtio_net(vm, pci, ioport, ioport_range, port_type, interrupt_pin, interrupt_line, backend)

+ +

Initialise a new virtio_net device with Base Address Registers (BARs) starting at iobase and backend functions +specified by the raw_iface_funcs struct. +virtio_net_default_backend for default methods.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • pci {vmm_pci_space_t *}: PCI library instance to register virtio net device
    • +
  • ioport {vmm_io_port_list_t *}: IOPort library instance to register virtio net ioport
    • +
  • ioport_range {ioport_range_t}: BAR port for front end emulation
    • +
  • port_type {ioport_type_t}: Type of ioport i.e. whether to alloc or use given range
    • +
  • interrupt_pin {unsigned int}: PCI interrupt pin e.g. INTA = 1, INTB = 2 ,…
    • +
  • interrupt_line {unsigned int}: PCI interrupt line for virtio net IRQS
    • +
  • backend {struct raw_iface_funcs}: Function pointers to backend implementation. Can be initialised by
    • +
+ +

Returns:

+ +
    +
  • Pointer to an initialised virtio_net_t, NULL if error.
    • +
+ +

Back to interface description.

+ +

Function virtio_net_default_backend()

+ +

update these function pointers with its own custom backend.

+ +

Parameters:

+ +

No parameters

+ +

Returns:

+ +
    +
  • A struct with a default virtio_net backend. It is the responsibility of the caller to
    • +
+ +

Back to interface description.

+ +

Structs

+ +

The interface virtio_net.h defines the following structs.

+ +

Struct virtio_net

+ +

Virtio Net Driver Interface

+ +

Elements:

+ +
    +
  • iobase {unsigned int}: IO Port base for Virtio Net device
    • +
  • emul {virtio_emul_t *}: Virtio Ethernet emulation interface: VMM <-> Guest
    • +
  • emul_driver {struct eth_driver *}: Backend Ethernet driver interface: VMM <-> Ethernet driver
    • +
  • emul_driver_funcs {struct raw_iface_funcs}: Virtio Ethernet emulation functions: VMM <-> Guest
    • +
  • ioops {ps_io_ops_t}: Platform support ioops for dma management
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_acpi.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_acpi.html new file mode 100644 index 00000000000..862a1f99a89 --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_acpi.html @@ -0,0 +1,625 @@ + + + + + + + libsel4vmmplatsupport_x86_acpi | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface acpi.h

+ +

The ACPI module provides support for generating ACPI table in a guest x86 VM. This being particularly leveraged +for booting a guest Linux VM.

+ +

Brief content:

+ +

Functions:

+ +
+

make_guest_acpi_tables(vm)

+
+ +

Functions

+ +

The interface acpi.h defines the following functions.

+ +

Function make_guest_acpi_tables(vm)

+ +

Creates ACPI table for the guest VM

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the guest VM instance
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_guest_boot_init.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_guest_boot_init.html new file mode 100644 index 00000000000..b5991dfc97b --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_guest_boot_init.html @@ -0,0 +1,656 @@ + + + + + + + libsel4vmmplatsupport_x86_guest_boot_init | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface guest_boot_init.h

+ +

The libsel4vmmplatsupport x86 guest boot init interface provides helpers to initialise the booting state of +a VM instance. This currently only targets booting a Linux guest OS.

+ +

Brief content:

+ +

Functions:

+ +
+

vmm_plat_init_guest_boot_structure(vm, cmdline, guest_kernel_image, guest_ramdisk_image, guest_boot_info_addr)

+
+ +
+

vmm_plat_init_guest_thread_state(vcpu, guest_entry_addr, guest_boot_info_addr)

+
+ +

Functions

+ +

The interface guest_boot_init.h defines the following functions.

+ +

Function vmm_plat_init_guest_boot_structure(vm, cmdline, guest_kernel_image, guest_ramdisk_image, guest_boot_info_addr)

+ +

Establish the necessary BIOS boot structures to initialise and boot a guest Linux OS. This includes the creation of a BIOS +boot info structure, an e820 map and ACPI tables. +(in guest physical address space)

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the guest VM
    • +
  • cmdline {const char *}: The guest Linux boot commandline
    • +
  • guest_kernel_image {guest_kernel_image_t}: Guest kernel image (preloaded into the VM’s memory)
    • +
  • guest_ramdisk_image {guest_image_t}: Guest ramdisk image (preloaded into the VM’s memory)
    • +
  • guest_boot_info_addr {uintptr_t *}: Resulting address of loaded generated guest boot info structure
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ +

Function vmm_plat_init_guest_thread_state(vcpu, guest_entry_addr, guest_boot_info_addr)

+ +

Initialise the booting state of a guest VM, establishing the necessary thread state to launch a guest Linux OS

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: A handle to the boot vcpu
    • +
  • guest_entry_addr {uintptr_t}: Address of VM entry point (often entry point defined in kernel elf image)
    • +
  • guest_boot_info_addr {uintptr_t}: Address of loaded guest boot info structure
    • +
+ +

Returns:

+ +
    +
  • 0 for success, -1 for error
    • +
+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_vmm_pci_helper.html b/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_vmm_pci_helper.html new file mode 100644 index 00000000000..59f1a1b921b --- /dev/null +++ b/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_vmm_pci_helper.html @@ -0,0 +1,675 @@ + + + + + + + libsel4vmmplatsupport_x86_vmm_pci_helper | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+ + + +

Interface vmm_pci_helper.h

+ +

The interface presents a series of helpers for establishing VMM PCI support on x86 platforms.

+ +

Brief content:

+ +

Functions:

+ +
+

vmm_pci_helper_map_bars(vm, cfg, bars)

+
+ +
+

vmm_pci_io_port_in(vcpu, cookie, port_no, size, result)

+
+ +
+

vmm_pci_io_port_out(vcpu, cookie, port_no, size, value)

+
+ +

Functions

+ +

The interface vmm_pci_helper.h defines the following functions.

+ +

Function vmm_pci_helper_map_bars(vm, cfg, bars)

+ +

Given a PCI device config, map the PCI device bars into the VM, effectively passing-through the +PCI device. This will map MMIO and IO-based bars.

+ +

Parameters:

+ +
    +
  • vm {vm_t *}: A handle to the VM
    • +
  • cfg {libpci_device_iocfg_t *}: PCI device config
    • +
  • bars {vmm_pci_bar_t *}: Resulting PCI bars mapped into the VM
    • +
+ +

Returns:

+ +
    +
  • -1 for error, otherwise the number of bars mapped into the VM (>=0)
    • +
+ +

Back to interface description.

+ + + +

Emulates IOPort in access on the VMM Virtual PCI device

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Faulting vcpu performing ioport access
    • +
  • port_no {unsigned int}: Port address being accessed
    • +
  • size {unsigned int}: Size of ioport access
    • +
  • result {unsigned int *}: Pointer that will be populated with resulting data of io-in op
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ + + +

Emulates IOPort out access on the VMM Virtual PCI device

+ +

Parameters:

+ +
    +
  • vcpu {vm_vcpu_t *}: Faulting vcpu performing ioport access
    • +
  • port_no {unsigned int}: Port address being accessed
    • +
  • size {unsigned int}: Size of ioport access
    • +
  • value {unsigned int}: Value being written in io-out op
    • +
+ +

Returns:

+ +

No return

+ +

Back to interface description.

+ +

Back to top.

+ + +
+ +
+
+ + + + + + +
+
+
+ + diff --git a/projects/virtualization/docs/libsel4vm.html b/projects/virtualization/docs/libsel4vm.html new file mode 100644 index 00000000000..e903d065ffb --- /dev/null +++ b/projects/virtualization/docs/libsel4vm.html @@ -0,0 +1,617 @@ + + + + + + + VM library (libsel4vm) | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

VM library (libsel4vm)

+ +

A guest hardware virtualisation library for IA32 and ARM (AArch32 & +AArch64) for use on seL4-based systems. The library as such is not specific to +CAmkES, but the main users of this library are the CAmkES VMs on x86 and Arm.

+ +

This is a consolidated library composed of the now deprecated libraries +libsel4vmm (x86) and libsel4arm-vmm (Arm).

+ +

Sources: https://github.com/seL4/seL4_projects_libs/blob/master/libsel4vm/

+ +

Features

+ +

The library supports IRQ Controller emulation (GICv2 on AArch32 and AArch64, and +PIC & LAPIC on IA32), guest VM memory management, guest VCPU fault and context +management, as well as VM runtime management.

+ +

The Arm library has SMP support for GICv2 platforms, the IA32 library provides +an IOPort fault registration handler and a VMCall handler registration interface.

+ +

API documentation

+ +

See below for usage documentation on libsel4vm.

+ +

Common Interfaces

+ + + +

Architecture Specific Interfaces

+ +

ARM

+ + + +

X86

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/virtualization/docs/libsel4vm.md b/projects/virtualization/docs/libsel4vm.md deleted file mode 100644 index 3cc453e2b80..00000000000 --- a/projects/virtualization/docs/libsel4vm.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# VM library (libsel4vm) - -A guest hardware virtualisation library for IA32 and ARM (AArch32 & -AArch64) for use on seL4-based systems. The library as such is not specific to -CAmkES, but the main users of this library are the [CAmkES VMs] on x86 and Arm. - -This is a consolidated library composed of the now deprecated libraries -`libsel4vmm` (x86) and `libsel4arm-vmm` (Arm). - -Sources: - -[CAmkES VMs]: {{ '/projects/camkes-vm/' | relative_url }} - -## Features - -The library supports IRQ Controller emulation (GICv2 on AArch32 and AArch64, and -PIC & LAPIC on IA32), guest VM memory management, guest VCPU fault and context -management, as well as VM runtime management. - -The Arm library has SMP support for GICv2 platforms, the IA32 library provides -an IOPort fault registration handler and a VMCall handler registration interface. - -## API documentation - -See below for usage documentation on `libsel4vm`. - -### Common Interfaces - -* [sel4vm/boot.h](api/libsel4vm_boot.html): An interface for creating, initialising - and configuring VM instances -* [sel4vm/guest_irq_controller.h](api/libsel4vm_guest_irq_controller.html): - Abstractions around initialising a guest VM IRQ controller -* [sel4vm/guest_memory_helpers.h](api/libsel4vm_guest_memory_helpers.html): Helpers - for using the guest memory interface -* [sel4vm/guest_vcpu_fault.h](api/libsel4vm_guest_vcpu_fault.html): Useful methods to - query and configure vcpu objects that have faulted during execution -* [sel4vm/guest_vm.h](api/libsel4vm_guest_vm.html): Provides base definitions of the - guest vm datastructure and primitives to run the VM instance -* [sel4vm/guest_iospace.h](api/libsel4vm_guest_iospace.html): Enables the - registration and management of a guest VM's IO Space -* [sel4vm/guest_memory.h](api/libsel4vm_guest_memory.html): Useful abstractions to - manage your guest VM's physical address space -* [sel4vm/guest_ram.h](api/libsel4vm_guest_ram.html): A set of methods to manage, - register, allocate and copy to/from a guest VM's RAM -* [sel4vm/guest_vm_util.h](api/libsel4vm_guest_vm_util.html): A set of utilties to - query a guest vm instance - -### Architecture Specific Interfaces - -#### ARM - -* [sel4vm/arch/guest_arm_context.h](api/libsel4vm_guest_arm_context.html): Provides a - set of useful getters and setters on ARM vcpu thread contexts -* [sel4vm/arch/guest_vm_arch.h](api/libsel4vm_arm_guest_vm.html): Provide definitions - of the arm guest vm datastructures and primitives to configure the VM instance - -#### X86 - -* [sel4vm/arch/guest_x86_context.h](api/libsel4vm_guest_x86_context.html): Provides a - set of useful getters and setters on x86 vcpu thread contexts -* [sel4vm/arch/guest_vm_arch.h](api/libsel4vm_x86_guest_vm.html): Provide definitions - of the x86 guest vm datastructures and primitives to configure the VM instance -* [sel4vm/arch/vmcall.h](api/libsel4vm_x86_vmcall.html): Methods for registering and - managing vmcall instruction handlers -* [sel4vm/arch/ioports.h](api/libsel4vm_x86_ioports.html): Abstractions for - initialising, registering and handling ioport events diff --git a/projects/virtualization/docs/libsel4vmm.html b/projects/virtualization/docs/libsel4vmm.html new file mode 100644 index 00000000000..c7052842033 --- /dev/null +++ b/projects/virtualization/docs/libsel4vmm.html @@ -0,0 +1,650 @@ + + + + + + + VMM library (libsel4vmmplatsupport) | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

VMM library (libsel4vmmplatsupport)

+ +

A library containing various VMM utilities and drivers that can be used to +construct a Guest VM on a supported platform. This library makes use of +‘libsel4vm’ to implement VMM support. The main reference implementations using +this library are the CAmkES VMs on Arm and IA32. The sources are available on +GitHub.

+ + + +

Main features

+ +

The library contains Virtio support and Virtio drivers for PCI, Console, and +Net. It provides a cross-VM connection/communication driver, guest image loading +utilities (e.g. kernel, initramfs), libsel4vm memory helpers and utilities, +and an IOPorts management interface.

+ +

On Arm, it further provides a VCPU fault handler module with HSR/Exception & SMC +decoding and dispatching, PSCI handlers through a VCPU fault (+SMC handler) +interface, guest reboot utilities, and guest OS boot interfaces for Linux VMs. +It defines generic virtual device interfaces for generic access controlled +devices (read/write privileges), and for generic forwarding devices via +dispatching faults to external handlers. It also provides a virtual USB driver.

+ +

On IA32, the library supports ACPI table generation, PCI device passthrough +helpers, and guest OS Boot interfaces for Linux VMs that provide boot VCPU +initialisation, BIOS boot info structure generation, E820 map generation, and +VESA initialisation.

+ +

API documentation

+ +

See below for usage documentation on libsel4vmmplatsupport interfaces.

+ +

Common Interfaces

+ + + +

Architecture Specific Interfaces

+ +

Arm

+ + + +

x86

+ + + +
+ +
+
+ + + +
+
+
+ + diff --git a/projects/virtualization/docs/libsel4vmm.md b/projects/virtualization/docs/libsel4vmm.md deleted file mode 100644 index 184eac07d63..00000000000 --- a/projects/virtualization/docs/libsel4vmm.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- - -# VMM library (libsel4vmmplatsupport) - -A library containing various VMM utilities and drivers that can be used to -construct a Guest VM on a supported platform. This library makes use of -‘libsel4vm’ to implement VMM support. The main reference implementations using -this library are the [CAmkES VMs] on Arm and IA32. The sources are [available on -GitHub][sources]. - - -[sources]: https://github.com/seL4/seL4_projects_libs/blob/master/libsel4vmmplatsupport/README.md -[CAmkES VMs]: {{ '/projects/camkes-vm/' | relative_url }} -[libsel4vm]: {{ '/projects/virtualization/docs/libsel4vm.html' | relative_url }} - -## Main features - -The library contains Virtio support and Virtio drivers for PCI, Console, and -Net. It provides a cross-VM connection/communication driver, guest image loading -utilities (e.g. kernel, initramfs), [libsel4vm] memory helpers and utilities, -and an IOPorts management interface. - -On Arm, it further provides a VCPU fault handler module with HSR/Exception & SMC -decoding and dispatching, PSCI handlers through a VCPU fault (+SMC handler) -interface, guest reboot utilities, and guest OS boot interfaces for Linux VMs. -It defines generic virtual device interfaces for generic access controlled -devices (read/write privileges), and for generic forwarding devices via -dispatching faults to external handlers. It also provides a virtual USB driver. - -On IA32, the library supports ACPI table generation, PCI device passthrough -helpers, and guest OS Boot interfaces for Linux VMs that provide boot VCPU -initialisation, BIOS boot info structure generation, E820 map generation, and -VESA initialisation. - -## API documentation - -See below for usage documentation on `libsel4vmmplatsupport` interfaces. - -### Common Interfaces - -* [sel4vmmplatsupport/device.h](api/libsel4vmmplatsupport_device.html): Provides a - series of datastructures and helpers to manage VMM devices. -* [sel4vmmplatsupport/device_utils.h](api/libsel4vmmplatsupport_device_utils.html): - Provides various helpers to establish different types devices for a given VM - instance -* [sel4vmmplatsupport/guest_image.h](api/libsel4vmmplatsupport_guest_image.html): - Provides general utilites to load guest vm images (e.g. kernel, initrd, - modules) -* [sel4vmmplatsupport/guest_memory_util.h](api/libsel4vmmplatsupport_guest_memory_util.html): - Provides various utilities and helpers for using the libsel4vm guest memory - interface -* [sel4vmmplatsupport/guest_vcpu_util.h](api/libsel4vmmplatsupport_guest_vcpu_util.html): - Provides abstractions and helpers for managing libsel4vm vcpus -* [sel4vmmplatsupport/ioports.h](api/libsel4vmmplatsupport_ioports.html): Useful - abstraction for initialising, registering and handling ioport events for a - guest VM instance -* [sel4vmmplatsupport/drivers/cross_vm_connection.h](api/libsel4vmmplatsupport_cross_vm_connection.html): - Facilitates the creation of communication channels between VM's and other - components on an seL4-based system -* [sel4vmmplatsupport/drivers/pci.h](api/libsel4vmmplatsupport_pci.html): Interface - presents a VMM PCI Driver, which manages the host's PCI devices, and handles - guest OS PCI config space read & writes -* [sel4vmmplatsupport/drivers/pci_helper.h](api/libsel4vmmplatsupport_pci_helper.html): - This interface presents a series of helpers when using the VMM PCI Driver -* [sel4vmmplatsupport/drivers/virtio_con.h](api/libsel4vmmplatsupport_virtio_con.html): - This interface provides the ability to initalise a VMM virtio console driver -* [sel4vmmplatsupport/drivers/virtio_net.h](api/libsel4vmmplatsupport_virtio_net.html): - This interface provides the ability to initalise a VMM virtio net driver - -### Architecture Specific Interfaces - -#### Arm - -* [sel4vmmplatsupport/arch/generic_forward_device.h](api/libsel4vmmplatsupport_arm_generic_forward_device.html): - This interface facilitates the creation of a virtual device used for - dispatching faults to external handlers -* [sel4vmmplatsupport/arch/guest_boot_init.h](api/libsel4vmmplatsupport_arm_guest_boot_init.html): - Provides helpers to initialise the booting state of a VM instance -* [sel4vmmplatsupport/arch/guest_reboot,h](api/libsel4vmmplatsupport_arm_guest_reboot.html): - Provides a series of helpers for registering callbacks when rebooting the VMM -* [sel4vmmplatsupport/arch/guest_vcpu_fault.h](api/libsel4vmmplatsupport_arm_guest_vcpu_fault.html): - Provides a module for registering and processing ARM vcpu faults -* [sel4vmmplatsupport/arch/guest_vcpu_util.h](api/libsel4vmmplatsupport_arm_guest_vcpu_util.html): - Provides abstractions and helpers for managing libsel4vm vcpus on an ARM - platform -* [sel4vmmplatsupport/arch/vpci.h](api/libsel4vmmplatsupport_arm_vpci.html): Presents - a Virtual PCI driver for ARM-based VM's -* [sel4vmmplatsupport/arch/vusb.h](api/libsel4vmmplatsupport_arm_vusb.html): Presents - a Virtual USB driver for ARM-based VM's -* [sel4vmmplatsupport/arch/ac_device.h](api/libsel4vmmplatsupport_arm_ac_device.html): - Facilitates the creation of generic virtual devices in a VM instance with - access control permissions over the devices addressable memory - -#### x86 - -* [sel4vmmplatsupport/arch/acpi.h](api/libsel4vmmplatsupport_x86_acpi.html): Provides - support for generating ACPI table in a guest x86 VM -* [sel4vmmplatsupport/arch/guest_boot_init.h](api/libsel4vmmplatsupport_x86_guest_boot_init.html): - Provides helpers to initialise the booting state of a VM instance -* [sel4vmmplatsupport/arch/drivers/vmm_pci_helper.h](api/libsel4vmmplatsupport_x86_vmm_pci_helper.html): - Interface presents a series of helpers for establishing VMM PCI support on x86 - platforms diff --git a/projects/virtualization/index.html b/projects/virtualization/index.html new file mode 100644 index 00000000000..88ec105e289 --- /dev/null +++ b/projects/virtualization/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/virtualization/index.md b/projects/virtualization/index.md deleted file mode 100644 index e6f8d9cd5cd..00000000000 --- a/projects/virtualization/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_from: - - /VM/ -redirect_to: projects/camkes-vm/ -project: virtualization -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/projects/virtualization/libsel4vm.html b/projects/virtualization/libsel4vm.html new file mode 100644 index 00000000000..ce5d4ae0a13 --- /dev/null +++ b/projects/virtualization/libsel4vm.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/virtualization/libsel4vm.md b/projects/virtualization/libsel4vm.md deleted file mode 100644 index 798822b496f..00000000000 --- a/projects/virtualization/libsel4vm.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: libsel4vm -redirect_to: /projects/virtualization/docs/libsel4vm.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/projects/virtualization/libsel4vmmplatsupport.html b/projects/virtualization/libsel4vmmplatsupport.html new file mode 100644 index 00000000000..294d2eaff58 --- /dev/null +++ b/projects/virtualization/libsel4vmmplatsupport.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/projects/virtualization/libsel4vmmplatsupport.md b/projects/virtualization/libsel4vmmplatsupport.md deleted file mode 100644 index f79bac4ad7c..00000000000 --- a/projects/virtualization/libsel4vmmplatsupport.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: libsel4vmmplatsupport -redirect_to: /projects/virtualization/docs/libsel4vmm.html -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC. ---- diff --git a/redirects.json b/redirects.json new file mode 100644 index 00000000000..b2eb5366183 --- /dev/null +++ b/redirects.json @@ -0,0 +1 @@ +{"/camkes_release/CAmkES_2.0.0/":"https://docs.sel4.systems/releases/camkes/camkes-2.0.0.html","/camkes_release/CAmkES_2.0.0.html":"https://docs.sel4.systems/releases/camkes/camkes-2.0.0.html","/camkes_release/CAmkES_2.1.0/":"https://docs.sel4.systems/releases/camkes/camkes-2.1.0.html","/camkes_release/CAmkES_2.1.0.html":"https://docs.sel4.systems/releases/camkes/camkes-2.1.0.html","/camkes_release/CAmkES_2.2.0/":"https://docs.sel4.systems/releases/camkes/camkes-2.2.0.html","/camkes_release/CAmkES_2.2.0.html":"https://docs.sel4.systems/releases/camkes/camkes-2.2.0.html","/camkes_release/CAmkES_2.3.0/":"https://docs.sel4.systems/releases/camkes/camkes-2.3.0.html","/camkes_release/CAmkES_2.3.0.html":"https://docs.sel4.systems/releases/camkes/camkes-2.3.0.html","/camkes_release/CAmkES_2.3.1/":"https://docs.sel4.systems/releases/camkes/camkes-2.3.1.html","/camkes_release/CAmkES_2.3.1.html":"https://docs.sel4.systems/releases/camkes/camkes-2.3.1.html","/camkes_release/CAmkES_3.0.0/":"https://docs.sel4.systems/releases/camkes/camkes-3.0.0.html","/camkes_release/CAmkES_3.0.0.html":"https://docs.sel4.systems/releases/camkes/camkes-3.0.0.html","/camkes_release/CAmkES_3.1.0/":"https://docs.sel4.systems/releases/camkes/camkes-3.1.0.html","/camkes_release/CAmkES_3.1.0.html":"https://docs.sel4.systems/releases/camkes/camkes-3.1.0.html","/camkes_release/CAmkES_3.2.0/":"https://docs.sel4.systems/releases/camkes/camkes-3.2.0.html","/camkes_release/CAmkES_3.2.0.html":"https://docs.sel4.systems/releases/camkes/camkes-3.2.0.html","/camkes_release/CAmkES_3.3.0/":"https://docs.sel4.systems/releases/camkes/camkes-3.3.0.html","/camkes_release/CAmkES_3.3.0.html":"https://docs.sel4.systems/releases/camkes/camkes-3.3.0.html","/camkes_release/CAmkES_3.4.0/":"https://docs.sel4.systems/releases/camkes/camkes-3.4.0.html","/camkes_release/CAmkES_3.4.0.html":"https://docs.sel4.systems/releases/camkes/camkes-3.4.0.html","/camkes_release/CAmkES_3.5.0/":"https://docs.sel4.systems/releases/camkes/camkes-3.5.0.html","/camkes_release/CAmkES_3.5.0.html":"https://docs.sel4.systems/releases/camkes/camkes-3.5.0.html","/camkes_release/Camkes_3.6.0/":"https://docs.sel4.systems/releases/camkes/camkes-3.6.0.html","/camkes_release/Camkes_3.6.0.html":"https://docs.sel4.systems/releases/camkes/camkes-3.6.0.html","/camkes_release/Camkes_3.7.0/":"https://docs.sel4.systems/releases/camkes/camkes-3.7.0.html","/camkes_release/Camkes_3.7.0.html":"https://docs.sel4.systems/releases/camkes/camkes-3.7.0.html","/sel4_release/seL4_0.0.1-rt-dev/":"https://docs.sel4.systems/releases/sel4/0.0.1-rt-dev.html","/sel4_release/seL4_0.0.1-rt-dev.html":"https://docs.sel4.systems/releases/sel4/0.0.1-rt-dev.html","/sel4_release/seL4_1.0.0-rt-dev/":"https://docs.sel4.systems/releases/sel4/1.0.0-rt-dev.html","/sel4_release/seL4_1.0.0-rt-dev.html":"https://docs.sel4.systems/releases/sel4/1.0.0-rt-dev.html","/sel4_release/seL4_10.0.0/":"https://docs.sel4.systems/releases/sel4/10.0.0.html","/sel4_release/seL4_10.0.0.html":"https://docs.sel4.systems/releases/sel4/10.0.0.html","/sel4_release/seL4_10.1.0/":"https://docs.sel4.systems/releases/sel4/10.1.0.html","/sel4_release/seL4_10.1.0.html":"https://docs.sel4.systems/releases/sel4/10.1.0.html","/sel4_release/seL4_10.1.1-mcs/":"https://docs.sel4.systems/releases/sel4/10.1.1-mcs.html","/sel4_release/seL4_10.1.1-mcs.html":"https://docs.sel4.systems/releases/sel4/10.1.1-mcs.html","/sel4_release/seL4_10.1.1/":"https://docs.sel4.systems/releases/sel4/10.1.1.html","/sel4_release/seL4_10.1.1.html":"https://docs.sel4.systems/releases/sel4/10.1.1.html","/sel4_release/seL4_2.0.0/":"https://docs.sel4.systems/releases/sel4/2.0.0.html","/sel4_release/seL4_2.0.0.html":"https://docs.sel4.systems/releases/sel4/2.0.0.html","/sel4_release/seL4_2.1.0/":"https://docs.sel4.systems/releases/sel4/2.1.0.html","/sel4_release/seL4_2.1.0.html":"https://docs.sel4.systems/releases/sel4/2.1.0.html","/sel4_release/seL4_3.0.0/":"https://docs.sel4.systems/releases/sel4/3.0.0.html","/sel4_release/seL4_3.0.0.html":"https://docs.sel4.systems/releases/sel4/3.0.0.html","/sel4_release/seL4_3.0.1/":"https://docs.sel4.systems/releases/sel4/3.0.1.html","/sel4_release/seL4_3.0.1.html":"https://docs.sel4.systems/releases/sel4/3.0.1.html","/sel4_release/seL4_3.1.0/":"https://docs.sel4.systems/releases/sel4/3.1.0.html","/sel4_release/seL4_3.1.0.html":"https://docs.sel4.systems/releases/sel4/3.1.0.html","/sel4_release/seL4_3.2.0/":"https://docs.sel4.systems/releases/sel4/3.2.0.html","/sel4_release/seL4_3.2.0.html":"https://docs.sel4.systems/releases/sel4/3.2.0.html","/sel4_release/seL4_4.0.0/":"https://docs.sel4.systems/releases/sel4/4.0.0.html","/sel4_release/seL4_4.0.0.html":"https://docs.sel4.systems/releases/sel4/4.0.0.html","/sel4_release/seL4_5.0.0/":"https://docs.sel4.systems/releases/sel4/5.0.0.html","/sel4_release/seL4_5.0.0.html":"https://docs.sel4.systems/releases/sel4/5.0.0.html","/sel4_release/seL4_5.1.0/":"https://docs.sel4.systems/releases/sel4/5.1.0.html","/sel4_release/seL4_5.1.0.html":"https://docs.sel4.systems/releases/sel4/5.1.0.html","/sel4_release/seL4_5.2.0-mcs/":"https://docs.sel4.systems/releases/sel4/5.2.0-mcs.html","/sel4_release/seL4_5.2.0-mcs.html":"https://docs.sel4.systems/releases/sel4/5.2.0-mcs.html","/sel4_release/seL4_5.2.0/":"https://docs.sel4.systems/releases/sel4/5.2.0.html","/sel4_release/seL4_5.2.0.html":"https://docs.sel4.systems/releases/sel4/5.2.0.html","/sel4_release/seL4_6.0.0/":"https://docs.sel4.systems/releases/sel4/6.0.0.html","/sel4_release/seL4_6.0.0.html":"https://docs.sel4.systems/releases/sel4/6.0.0.html","/sel4_release/seL4_7.0.0/":"https://docs.sel4.systems/releases/sel4/7.0.0.html","/sel4_release/seL4_7.0.0.html":"https://docs.sel4.systems/releases/sel4/7.0.0.html","/sel4_release/seL4_8.0.0/":"https://docs.sel4.systems/releases/sel4/8.0.0.html","/sel4_release/seL4_8.0.0.html":"https://docs.sel4.systems/releases/sel4/8.0.0.html","/sel4_release/seL4_9.0.0-mcs/":"https://docs.sel4.systems/releases/sel4/9.0.0-mcs.html","/sel4_release/seL4_9.0.0-mcs.html":"https://docs.sel4.systems/releases/sel4/9.0.0-mcs.html","/sel4_release/seL4_9.0.0/":"https://docs.sel4.systems/releases/sel4/9.0.0.html","/sel4_release/seL4_9.0.0.html":"https://docs.sel4.systems/releases/sel4/9.0.0.html","/sel4_release/seL4_9.0.1/":"https://docs.sel4.systems/releases/sel4/9.0.1.html","/sel4_release/seL4_9.0.1.html":"https://docs.sel4.systems/releases/sel4/9.0.1.html","/status/camkes.html":"https://docs.sel4.systems/projects/camkes/status.html","/projects/camkes/status.html":"https://docs.sel4.systems/projects/camkes/features.html","/status/sel4.html":"https://docs.sel4.systems/projects/sel4/status.html","/projects/sel4/status.html":"https://docs.sel4.systems/projects/sel4/configurations.html","/status/sel4bench.html":"https://docs.sel4.systems/projects/sel4bench/status.html","/projects/sel4bench/status.html":"https://docs.sel4.systems/projects/sel4bench/","/status/sel4test.html":"https://docs.sel4.systems/projects/sel4test/status.html","/projects/sel4test/status.html":"https://docs.sel4.systems/projects/sel4test/","/status/user_libs.html":"https://docs.sel4.systems/projects/user_libs/status.html","/projects/user_libs/status.html":"https://docs.sel4.systems/projects/user_libs/","/seL4DriverAPI/AddressingOtherDevices":"https://docs.sel4.systems/projects/driver_framework/AddressingOtherDevices.html","/seL4DriverAPI/ChildEnumeration":"https://docs.sel4.systems/projects/driver_framework/ChildEnumeration.html","/seL4DriverAPI/DriverManagement":"https://docs.sel4.systems/projects/driver_framework/DriverManagement.html","/Resources.html":"https://docs.sel4.systems/projects/buildsystem/host-dependencies.html","/ApiDoc":"https://docs.sel4.systems/projects/sel4/api-doc.html","/BenchmarkingGuide":"https://docs.sel4.systems/projects/sel4-tutorials/benchmarking-guide.html","/VM/CAmkESVMCentOS":"https://docs.sel4.systems/projects/camkes-vm/centos.html","/CAmkESCLI":"https://docs.sel4.systems/projects/camkes/cli.html","/processes/code-review.html":"https://sel4.systems/Contribute/pull-requests.html","/processes/conduct.html":"https://sel4.systems/Contribute/conduct.html","/processes/contributing.html":"https://sel4.systems/Contribute/","/DebuggingGuide":"https://docs.sel4.systems/projects/sel4-tutorials/debugging-guide.html","/DebuggingUserspace":"https://docs.sel4.systems/projects/sel4-tutorials/debugging-userspace.html","/CAmkESDifferences":"https://docs.sel4.systems/projects/camkes/differences.html","/DocsContributing":"https://docs.sel4.systems/processes/docs-contributing.html","/projects/sel4/documentation.html":"https://sel4.systems/Learn/","/projects/sel4/frequently-asked-questions.html":"https://sel4.systems/About/FAQ.html","/processes/git-conventions.html":"https://sel4.systems/Contribute/git-conventions.html","/HostDependencies":"https://docs.sel4.systems/projects/buildsystem/host-dependencies.html","/Developing/Building/Incorporating":"https://docs.sel4.systems/projects/buildsystem/incorporating.html","/projects/l4v/":"https://sel4.systems/Verification/","/projects/":"https://docs.sel4.systems/","/VM/":"https://docs.sel4.systems/projects/virtualization/","/projects/virtualization/":"https://docs.sel4.systems/projects/camkes-vm/","/projects/sel4webserver/":"https://github.com/seL4/sel4webserver/blob/master/README.md","/projects/sel4_tools/":"https://github.com/seL4/seL4_tools/tree/master/misc","/VisualCAmkES/":"https://docs.sel4.systems/projects/camkes/visual-camkes/","/CAmkES/":"https://docs.sel4.systems/projects/camkes/","/SeL4Libraries":"https://docs.sel4.systems/projects/user_libs/","/Docker":"https://docs.sel4.systems/projects/dockerfiles/","/seL4Test":"https://docs.sel4.systems/projects/sel4test/","/LevelConverter":"https://docs.sel4.systems/projects/hardware_hacks/level-converter/","/HardwareHacks":"https://docs.sel4.systems/projects/hardware_hacks/","/VM/CAmkESX86VM":"https://docs.sel4.systems/projects/camkes-vm/","/Rust":"https://docs.sel4.systems/projects/rust/","/CapDL":"https://docs.sel4.systems/projects/capdl/","/Developing/Building/OldBuildSystem":"https://docs.sel4.systems/projects/buildsystem/old/","/Developing/Building/":"https://docs.sel4.systems/projects/buildsystem/","/projects/sel4-tutorials.html":"https://docs.sel4.systems/Tutorials/","/projects/sel4-tutorials/":"https://docs.sel4.systems/Tutorials/","/processes/":"https://sel4.systems/support.html","/CAmkESInternals":"https://docs.sel4.systems/projects/camkes/internals.html","/projects/virtualization/libsel4vm.html":"https://docs.sel4.systems/projects/virtualization/docs/libsel4vm.html","/projects/virtualization/libsel4vmmplatsupport.html":"https://docs.sel4.systems/projects/virtualization/docs/libsel4vmm.html","/processes/licenses.html":"https://sel4.systems/Legal/license.html","/seL4ManualAPIGeneration":"https://docs.sel4.systems/projects/sel4/manual-api-generation.html","/projects/sel4/manual-api-generation.html":"https://github.com/seL4/seL4/blob/master/manual/README.md","/CAmkES/Terminology":"https://docs.sel4.systems/projects/camkes/manual.html","/projects/camkes/terminology.html":"https://docs.sel4.systems/projects/camkes/manual.html","/CAmkESNext":"https://docs.sel4.systems/projects/camkes/next.html","/projects/capdl/object-sizes.html":"https://github.com/seL4/capdl/tree/master/object_sizes/","/Tutorials/pathways.html":"https://docs.sel4.systems/Tutorials/index.html","/projects/sel4/platf-owner.html":"https://sel4.systems/Contribute/platform-ports.html","/PortingSeL4":"https://docs.sel4.systems/projects/sel4/porting.html","/projects/capdl/python-tool.html":"https://github.com/seL4/capdl/tree/master/python-capdl-tool","/camkes_release":"https://docs.sel4.systems/releases/camkes.html","/sel4_release":"https://docs.sel4.systems/releases/seL4.html","/processes/release-process.html":"https://docs.sel4.systems/releases.html","/RepoCheatsheet":"https://docs.sel4.systems/projects/buildsystem/repo-cheatsheet.html","/processes/rfc-process.html":"https://sel4.systems/Contribute/rfc-process.html","/projects/roadmap.html":"https://sel4.systems/roadmap.html","/processes/roles.html":"https://sel4.systems/Contribute/roles.html","/seL4SharedDataWithCaps":"https://docs.sel4.systems/projects/camkes/seL4SharedDataWithCaps.html","/Hardware/RISCV":"https://docs.sel4.systems/Hardware/spike.html","/Developing/Building/seL4Standalone":"https://docs.sel4.systems/projects/buildsystem/standalone.html","/processes/style-guide.html":"https://sel4.systems/Contribute/style.html","/projects/capdl/translator.html":"https://github.com/seL4/capdl/tree/master/capDL-tool/","/Developing/Building/Using":"https://docs.sel4.systems/projects/buildsystem/using.html","/VerifiedConfigurations":"https://docs.sel4.systems/projects/sel4/verified-configurations.html"} \ No newline at end of file diff --git a/releases.html b/releases.html new file mode 100644 index 00000000000..5e05dbbcf42 --- /dev/null +++ b/releases.html @@ -0,0 +1,717 @@ + + + + + + + Releases | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Releases

+ +

Latest Versions

+ +

The latest versioned software releases provided by the seL4 Foundation are

+ + + +

Release Channels

+ +

There are two release channels:

+ +
    +
  • Bleeding edge: These happen whenever any of the maintained repository +collections is updated and the tests for it are passing.
    • +
  • Versioned releases: Versioned releases of the seL4 kernel, the seL4 +proofs, CAmkES, Microkit, capDL, and Rust support. These happen manually and +less frequently. The latest versions of these are shown at the top of this +page.
    • +
+ +

Bleeding edge releases happen every time the code is updated and passes the test +suites and proofs. Working on the bleeding edge means that API changes occur +often and code depending on that API may break without warning.

+ +

Currently, we do not guarantee maintenance of previous releases, or individually +versioned libraries, projects, and applications. If that becomes necessary for +you, please let us know via one of the contact channels.

+ +

Which release should you use?

+ +

We recommend you develop on a specific official release version of the kernel, +rather than the bleeding edge. Each MAJOR.MINOR release has release notes which +describe changes and specific upgrade notes.

+ +

New board support, features, and bug fixes will appear in bleeding edge updates +earlier than in a released version. If you are working on a long-term project +on seL4 or are using different user-level libraries than we provide then it is +usually better to pick a versioned release and manually upgrade when new +features are required. We only guarantee working proofs for released versions, +although we try to maintain working proofs for bleeding edge releases as well. +If you are trying out seL4 and experimenting with different features, rerunning +benchmarks or doing the tutorials, using the bleeding edge versions of the +projects is often fine. They will only get updated when they are passing our +tests. Please report any issues to the relevant GitHub issue tracker or post on +one of the support channels.

+ +

Version Numbers

+ +

For versioned releases, seL4, Microkit, CAmkES, and capDL have different policies.

+ +

seL4, Microkit, and rust-sel4 follow semantic +versioning. In short:

+ +

Given a version number MAJOR.MINOR.PATCH, increment the:

+ +
    +
  • MAJOR version when you make incompatible API changes;
    • +
  • MINOR version when you add functionality in a backwards-compatible manner;
    • +
  • PATCH version when you make backwards-compatible bug fixes.
    • +
+ +

seL4 versions are tagged in git.

+ +

CAmkES and capDL versions follow the following policy:

+ +

MAJOR.MINOR.PATCH:

+ +
    +
  • MAJOR: A big rewrite
    • +
  • MINOR: The actual release number, increased when seL4 is released or there are + source/binary incompatible CAmkES updates
    • +
  • PATCH: Small bug fixes that are backwards compatible.
    • +
+ +

Library Compatibility

+ +

The libraries maintained by the seL4 Foundation have branches that track all +MAJOR.MINOR versions, with branch names in the format MAJOR.MINOR-compatible. A +MAJOR.MINOR-compatible branch will build with any MAJOR.MINOR.* version of the +kernel, and all MAJOR.MINOR-compatible branches across our libraries are +compatible with each other.

+ +

Legacy support

+ +

We only currently provide bug fixes and support for the latest version of the +kernel and latest version of libraries. Please do contact us if +commercial support of specific older versions of the kernel is important to you.

+ +

Manifests

+ +

Repository collections are tracked via manifests and the Google repo tool. Each +repository collection below is tracked in a +separate manifest repository with at least the following manifest files:

+ +
    +
  • default.xml specifies pinned revisions of the source that are updated every +time a new bleeding edge release is pushed. This happens every time there is +a code change and the regression tests for the corresponding repository +collection passes. This means, these manifests should always compile and pass +tests provided the correct build configurations are used.
    • +
  • master.xml specifies the tip of each repository in a project. These are used +for development and not guaranteed to work. They may contain combinations of +repositories that have not yet been tested together.
    • +
+ +

default.xml is tagged at each released version. To obtain the manifest for a +specific kernel version check out the corresponding X.Y.z tag.

+ +

Proof manifests

+ +

The verification-manifest repository contains a ${SEL4_VERSION}.xml manifest +for each release. It records the revisions of the proofs that match the +corresponding released version of the kernel and the version of the Isabelle/HOL +theorem prover that can be used to check the proofs.

+ +

Versioned repository collections

+ +

The following manifests track maintained repository collections, meaning +both bleeding edge and versioned releases are available:

+ + + + +
+ +
+
+ + + +
+
+
+ + diff --git a/releases.md b/releases.md deleted file mode 100644 index e4ade4164de..00000000000 --- a/releases.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -SPDX-License-Identifier: CC-BY-SA-4.0 -SPDX-FileCopyrightText: 2025 Proofcraft Pty Ltd -redirect_from: - - processes/release-process.html ---- - -# Releases - -## Latest Versions - -The latest versioned software releases provided by the seL4 Foundation are - -{% include releases.html %} - -## Release Channels - -There are two release channels: - -- **Bleeding edge**: These happen whenever any of the maintained repository - collections is updated and the tests for it are passing. -- **Versioned releases**: Versioned releases of the seL4 kernel, the seL4 - proofs, CAmkES, Microkit, capDL, and Rust support. These happen manually and - less frequently. The latest versions of these are shown at the top of this - page. - -Bleeding edge releases happen every time the code is updated and passes the test -suites and proofs. Working on the bleeding edge means that API changes occur -often and code depending on that API may break without warning. - -Currently, we do not guarantee maintenance of previous releases, or individually -versioned libraries, projects, and applications. If that becomes necessary for -you, please let us know via one of the [contact channels][contact]. - -### Which release should you use? - -We recommend you develop on a specific official release version of the kernel, -rather than the bleeding edge. Each MAJOR.MINOR release has release notes which -describe changes and specific upgrade notes. - -New board support, features, and bug fixes will appear in bleeding edge updates -earlier than in a released version. If you are working on a long-term project -on seL4 or are using different user-level libraries than we provide then it is -usually better to pick a versioned release and manually upgrade when new -features are required. We only guarantee working proofs for released versions, -although we try to maintain working proofs for bleeding edge releases as well. -If you are trying out seL4 and experimenting with different features, rerunning -benchmarks or doing the tutorials, using the bleeding edge versions of the -projects is often fine. They will only get updated when they are passing our -tests. Please report any issues to the relevant GitHub issue tracker or post on -one of the [support channels](https://sel4.systems/support.html). - -### Version Numbers - -For versioned releases, seL4, Microkit, CAmkES, and capDL have different policies. - -**seL4**, **Microkit**, and **rust-sel4** follow [semantic -versioning](http://semver.org/). In short: - -Given a version number MAJOR.MINOR.PATCH, increment the: - -- MAJOR version when you make incompatible API changes; -- MINOR version when you add functionality in a backwards-compatible manner; -- PATCH version when you make backwards-compatible bug fixes. - -seL4 versions are tagged in git. - -**CAmkES** and **capDL** versions follow the following policy: - -MAJOR.MINOR.PATCH: - -- MAJOR: A big rewrite -- MINOR: The actual release number, increased when seL4 is released or there are - source/binary incompatible CAmkES updates -- PATCH: Small bug fixes that are backwards compatible. - -### Library Compatibility - -The libraries maintained by the seL4 Foundation have branches that track all -MAJOR.MINOR versions, with branch names in the format MAJOR.MINOR-compatible. A -MAJOR.MINOR-compatible branch will build with any MAJOR.MINOR.\* version of the -kernel, and all MAJOR.MINOR-compatible branches across our libraries are -compatible with each other. - -### Legacy support - -We only currently provide bug fixes and support for the latest version of the -kernel and latest version of libraries. Please do [contact us][contact] if -commercial support of specific older versions of the kernel is important to you. - -## Manifests - -Repository collections are tracked via manifests and the Google repo tool. Each -repository collection [below](#versioned-repository-collections) is tracked in a -separate manifest repository with at least the following manifest files: - -- `default.xml` specifies pinned revisions of the source that are updated every - time a new *bleeding edge* release is pushed. This happens every time there is - a code change and the regression tests for the corresponding repository - collection passes. This means, these manifests should always compile and pass - tests provided the correct build configurations are used. -- `master.xml` specifies the tip of each repository in a project. These are used - for development and *not* guaranteed to work. They may contain combinations of - repositories that have not yet been tested together. - -`default.xml` is tagged at each released version. To obtain the manifest for a -specific kernel version check out the corresponding X.Y.z tag. - -### Proof manifests - -The `verification-manifest` repository contains a `${SEL4_VERSION}.xml` manifest -for each release. It records the revisions of the proofs that match the -corresponding released version of the kernel and the version of the Isabelle/HOL -theorem prover that can be used to check the proofs. - -### Versioned repository collections - -The following manifests track maintained repository collections, meaning -both bleeding edge and versioned releases are available: - -{% for project in site.data.maintained.github -%} -{% for repo in project.repo_projects -%} -- [{{repo}}](https://github.com/{{project.name}}/{{repo}}) -{% endfor -%} -{% endfor %} - -[contact]: https://sel4.systems/contact.html diff --git a/releases/camkes.html b/releases/camkes.html new file mode 100644 index 00000000000..c4dc2fbe1fd --- /dev/null +++ b/releases/camkes.html @@ -0,0 +1,606 @@ + + + + + + + CAmkES releases | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES releases

+ + + + +
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-2.0.0.html b/releases/camkes/camkes-2.0.0.html new file mode 100644 index 00000000000..60499ffd578 --- /dev/null +++ b/releases/camkes/camkes-2.0.0.html @@ -0,0 +1,560 @@ + + + + + + + Camkes 2.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES 2.0.0 Release Notes

+ +

The new release updates CAmkES to be compatible with seL4 version 2.0.0. +It also marks the transition to more frequent and regular releases, as +well as switching our release process to semantic versioning, so it’s +easy to tell which CAmkES releases are source-compatible, or will +require updates to user-level code, and also with which seL4 versions +they will be compatible.

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-2.1.0.html b/releases/camkes/camkes-2.1.0.html new file mode 100644 index 00000000000..5d1d481bbb1 --- /dev/null +++ b/releases/camkes/camkes-2.1.0.html @@ -0,0 +1,592 @@ + + + + + + + Camkes 2.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES 2.1.0 Release Notes

+ +

New Features

+ +
    +
  • runner takes an --architecture command line argument which selects + the target architecture. Valid arguments are: aarch32, arm_hyp, + ia32
    • +
  • added the ability to specify a hardware dataport as cached. + Previously all hardware dataports were mapped uncached. This + feature is intended to be used on dataports backed by DMA-able + memory to improve access times. Functions to flush dataports from + the cache are also provided.
    • +
  • support for seL4 3.0.0
    • +
+ +

Removed Features

+ +
    +
  • --hyp command line argument is replaced with + --architecture arm_hyp
    • +
+ +

API Removals

+ +

Unmarshalling Helpers

+

These were intended for use in templates, but are no longer used in any internal templates:

+
    +
  • camkes_marshal
    • +
  • camkes_marshal_string
    • +
  • camkes_unmarshal
    • +
  • camkes_unmarshal_string
    • +
+ +

DMA Utilities

+

These had been deprecated for a long period and are now being removed:

+
    +
  • camkes_dma_page_alloc
    • +
  • camkes_dma_page_free
    • +
+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-2.2.0.html b/releases/camkes/camkes-2.2.0.html new file mode 100644 index 00000000000..599a770f194 --- /dev/null +++ b/releases/camkes/camkes-2.2.0.html @@ -0,0 +1,573 @@ + + + + + + + Camkes 2.2.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES 2.2.0 Release Notes

+ +

New Features

+ +
    +
  • realtime extensions: CAmkES systems can now run on realtime +seL4. It is possible to configure the realtime +properties of systems built to run on realtime seL4. +
      +
    • For more details, see the “Realtime Extensions” section of the CAmkES + Manual
      • +
    +
    • +
  • support for seL4 3.1.0
    • +
+ +

Documentation Additions

+ +
    +
  • “Keywords” section in manual
    • +
+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-2.3.0.html b/releases/camkes/camkes-2.3.0.html new file mode 100644 index 00000000000..b04e6270f9b --- /dev/null +++ b/releases/camkes/camkes-2.3.0.html @@ -0,0 +1,568 @@ + + + + + + + Camkes 2.3.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES 2.3.0 Release Notes

+ +

New Features

+ +
    +
  • support for seL4 4.0.0
    • +
  • new dependency: Haskell Stack +
      +
    • Haskell Stack is a haskell version and package manager. It +takes care of installing an appropriate version of ghc and +cabal for building the capDL translator - part of CAmkES’ +build system.
      • +
    +
    • +
+ + +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-2.3.1.html b/releases/camkes/camkes-2.3.1.html new file mode 100644 index 00000000000..a59b4aa09b1 --- /dev/null +++ b/releases/camkes/camkes-2.3.1.html @@ -0,0 +1,560 @@ + + + + + + + Camkes 2.3.1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES 2.3.1 Release Notes

+ +

New Features

+ +
    +
  • support for seL4 5.2.0
    • +
+ + +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.0.0.html b/releases/camkes/camkes-3.0.0.html new file mode 100644 index 00000000000..8d31e034d99 --- /dev/null +++ b/releases/camkes/camkes-3.0.0.html @@ -0,0 +1,701 @@ + + + + + + + Camkes 3.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES 3.0.0 Release Notes

+ +

This adds all the features from our development branch “next”. Changes +include several syntactic and functional changes. The development of new +features will now continue on the “master” branch, and the “next” branch +will remain as is for compatibility reasons.

+ +

Migrating

+ +

How you migrate will depend on your situation:

+ +

I was using the “next” branch and want to switch to this release

+ +

Hopefully most people will be in this category. Now that we’ve +(finally!) done an official release of CAmkES 3, you can switch to a +stable tag with all the features of “CAmkES Next”, without the risk of +api breaking changes. If you use repo, your manifest probably has a line +resembling:

+ +
<project name="camkes-tool.git" path="tools/camkes" revision="next">
+
+ +

Change it to:

+ +
<project name="camkes-tool.git" path="tools/camkes" revision="refs/tags/camkes-3.0.0">
+
+ +

Watch the mailing list for new releases, and update your version of +CAmkES when you want to.

+ +

I was using the “next” branch, and want to stay on the bleeding edge

+ +

You need to switch to the “master” branch. The “next” branch will +continue to exist for a time for compatibility, but will no longer +receive updates. If you use repo, your manifest probably has a line +resembling:

+ +
<project name="camkes-tool.git" path="tools/camkes" revision="next">
+
+ +

Change it to:

+ +
<project name="camkes-tool.git" path="tools/camkes">
+
+ +

Note that tracking the tip of the “master” branch is risky. There’s no +guarantee that it won’t change in breaking ways in the future.

+ +

I was using the “master” branch, and want to migrate

+ +

There’s a guide on the changes introduces by this version here.

+ +

I was using the “master” branch, and don’t want to migrate

+ +

That’s fine! All the old versions of CAmkES will continue to be +available. The latest release of this branch is +camkes-2.3.1. +If you use repo, your manifest probably had a line resembling:

+ +
<project name="camkes-tool.git" path="tools/camkes">
+
+ +

Change it to:

+ +

<project name="camkes-tool.git" path="tools/camkes" +revision="refs/tags/camkes-2.3.1"> +

+ +

I was using a released version of CAmkES

+ +

You don’t have to do anything. Your project will continue to work.

+ +

New Dependencies

+ +

CAmkES dependencies have changed. For a definitive (maintained) list, +see: CAmkES.

+ +

New Features

+ +

Visualization Tool

+ +

CAmkES comes with a graphical tool for visualising the components and +connections in a CAmkES application. For installation and usage +instructions, +see its README.

+ +

Typed Settings

+ +

Previously, the values of settings (in “configuration” blocks) were +strings under the hood. Now they are stored as a value of the +appropriate (python) type, determined during parsing. +Read more.

+ +

Parametrised Buf Type

+ +

The “Buf” type for dataports can now be optionally parametrised with the +dataport’s size in bytes. +Read more.

+ +

The seL4Asynch connector has been renamed to seL4Notification

+ +

This was to maintain consistency with the rest of our APIs.

+ +

Non Volatile Dataports

+ +

Previously, the standard dataport connector, seL4SharedData, use +volatile pointers for accessing shared memory. This is no longer the +case, and components with dataport interfaces connected with +seL4SharedData must explicitly insert barriers around dataport access to +ensure the desired memory access ordering. +Read more in the manual.

+ +

Custom Attribute Types

+ +

You can now define custom types for attributes in CAmkES ADL. Custom +types resemble structs and arrays in C. +Read more in the manual.

+ +

Hierarchical Component Syntax Change

+ +

The syntax for declaring that a component exports an interface from one +of it sub-components has changed. +See an example.

+ +

Binary Semaphores

+ +

Binary Semaphores have been added as a new synchronization primitive. +This is in addition to the existing primitives: semaphores and mutexes. +Read more in the manual.

+ +

Cache Accelerator

+ +

CAmkES now comes with a small tool for caching compilation results based +on source files. This should greatly reduce compilation times by not +unnecessarily recompiling code. It is enabled by default. Control it +with the CONFIG_CAMKES_ACCELERATOR config variable. +Read more in the manual.

+ +

Python 3 Support

+ +

Previously, CAmkES only worked with python2. It’s now compatible with +python2 and python3.

+ +

Refactored Parser

+ +

The internals of the CAmkES parser have been rewritten to be easier to +read and maintain. The parser is structured as a pipeline of +transformations. +Read more in the manual.

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.1.0.html b/releases/camkes/camkes-3.1.0.html new file mode 100644 index 00000000000..ff3e117dbbe --- /dev/null +++ b/releases/camkes/camkes-3.1.0.html @@ -0,0 +1,599 @@ + + + + + + + Camkes 3.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES 3.1.0 Release Notes

+ +

Default Values for Attributes

+ +

It’s now possible to give a default value when specifying an attribute +of a component in a component { ... } block.

+ +

Specific details from manual:

+ +
    +
  • It is possible to give an attribute a default value when it +is declared. If there are no settings for an attribute, the default +setting will be used. If an attribute is aliased to a different +attribute that also has a default, then the different attribute’s +default will override the original default.
    • +
+ +

Meaningful Thread Names

+ +

In seL4 threads can be named. A thread’s name appears in the kernel’s +debugging printouts when the thread faults. Names of threads created by +CAmkES are now named +<component_instance_name>:<interface_name> for interface +threads, and <component_instance_name>:control for control +threads.

+ +

Scheduling Context Size Bits Attribute

+ +

When using CAmkES realtime extensions, the size_bits field of a +scheduling context can be set in CAmkES ADL. For interface threads, +specify the size bits of bound scheduling contexts with +<component_instance_name>.<interface_name>_sc_size_bits = ...;. +For control threads, specify the size bits of bound scheduling contexts +with <component_instance_name>._sc_size_bits = ...;.

+ +

Documentation Fixes

+ +
    +
  • Removed outdated information about dependencies
    • +
+ +

Bug Fixes

+ +
    +
  • Fixed bug in parser preventing empty lists of the form [] from + parsing correctly
    • +
+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.10.0.html b/releases/camkes/camkes-3.10.0.html new file mode 100644 index 00000000000..7fda4a567de --- /dev/null +++ b/releases/camkes/camkes-3.10.0.html @@ -0,0 +1,599 @@ + + + + + + + Camkes 3.10.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.10.0 Release

+ +

Announcing the release of camkes-3.10.0 with the following changes:

+ +

camkes-3.10.0 2021-06-10 +Using seL4 version 12.1.0

+ +

Changes

+ +
    +
  • Fixed new line generation in show_attribute_value.
    • +
  • Added const expression attributes to help convert CAmkES attributes to literals.
    • +
  • Fixed broken Python nosetests that weren’t updated when moving to Python3 from Python2.
    • +
  • Added caching when querying DMA frame physical addresses to avoid unnecessary kernel context switch overheads.
    • +
  • Changed templates and libraries to be DMA cache-aware and to not ignore requests for cache-able memory +allocations.
    • +
  • Added a macro function for every dataport to query its size.
    • +
  • Changed DMA bookkeeping to keep track of pools of frames and not individual frames.
    • +
  • Added code to sanitize the names of nested components for the naming of a components’ DMA pool.
    • +
  • Converted the repository to use SPDX license tags.
    • +
  • Fixed the passing of LD flags to the linker from CAmkES generation tools.
    • +
  • Added the failing C pre-processor command to an exception in the CAmkES parser tools for easier diagnosis.
    • +
  • Moved the CAmkES component interface header contents away from camkes.h and into separate header files that is +included by camkes.h.
    • +
  • Simplified the sys_uname library function.
    • +
  • Fix handling of array parameters for the CAmkES templates.
    • +
  • Sped up proofs for cdl-refine.
    • +
  • Fixed a CMake argument marshalling bug in the execute_process_with_stale_check function.
    • +
+ +

Upgrade Notes

+ +
    +
  • DMA pools now require an option to be set explicitly to be made to be cache-able. In a .camkes CAmkES assembly +file, add the following <component name>.dma_pool_cached = True; in the ‘configuration’ block to make a component’s +DMA pool to be cached. Additionally, use camkes_dma_alloc in libsel4camkes with the correct arguments to allocate +cached DMA memory from that pool.
    • +
+ +

Full changelog

+

Use git log camkes-3.9.0..camkes-3.10.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.11.0.html b/releases/camkes/camkes-3.11.0.html new file mode 100644 index 00000000000..459c36abec2 --- /dev/null +++ b/releases/camkes/camkes-3.11.0.html @@ -0,0 +1,639 @@ + + + + + + + Camkes 3.11.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.11.0 Release

+ +

2024-07-01

+ +

Announcing the release of camkes-3.11.0, using seL4 version 13.0.0.

+ +

Changes

+ +

Added/Removed

+ +
    +
  • Added support for SMC capabilities
    • +
  • Allow camkes components to know affinity; add build time error check for affinity
    • +
  • dataport: Add getter for frame size
    • +
  • libsel4camkes: expose get_virtqueue_channel
    • +
  • Added RISC-V in is_64_bit_arch()
    • +
  • Added helpers is_arch_arm() and is_arch_riscv()
    • +
  • Added an additional parameter with the current architectures for the macros +parse_dtb_node_interrupts() and global_endpoint_badges().
    • +
  • Added support for C++ source files in CAmkES components
    • +
  • parser: Support address translation ranges
    • +
  • serial: add config options for different ports
    • +
  • Extended DTB interrupt property parsing to support either one value or three +values per interrupt. For three values, ignore the first value on RISC-V.
    • +
  • Add vulnerability reporting policy
    • +
  • Name frames in a region for easy sorting: When generating a set of frames to +cover a region, use as many digits as necessary so that the capDL tool, when +it sorts alphabetically, will still leave frames that are meant to be +contiguous contiguous.
    • +
  • Remove references to and support of ARMv6 and the kzm platform
    • +
+ +

Fixed

+ +
    +
  • component.simple: fix mismatched type size, which may cause data overflow when +CONFIG_WORD_SIZE is 64. Use the CLZL() macro to correctly handle the +specified CONFIG_WORD_SIZE.
    • +
  • parser,fdtQueryEngine: Fix parser bug with DTB queries
    • +
  • Make sure fault handler and control run on same core as component
    • +
  • Improve error messages
    • +
  • cmake: add missing parameter DTB_FILE_PATH
    • +
  • fix CAMKES_ROOT_DTS_FILE_PATH check
    • +
  • serial: rename Serial.camkes files. This fixes an “unknown reference to +‘Serial’” issue seen on MacOS.
    • +
  • Fix IOAPIC vs MSI check in irq.c
    • +
  • component.common: align morecore region to 0x1000. This region is used for +mmap and brk allocations. If the 4k implementation alignment assumption isn’t +obeyed then memory errors are possible.
    • +
  • Avoid printing internal debug info
    • +
  • Consistently use CONFIG_PLAT in camkes_sys_uname() for all architectures.
    • +
  • More robust catching of objcopy errors during build
    • +
  • parser: fix attribute_reference regex
    • +
  • python: sanitize number formatting
    • +
+ +

Dependencies, Tests, Docs

+ +
    +
  • libsel4camkes: Add markdown documentation
    • +
  • parser: Add unit test for range translations
    • +
  • Add CAmkES unit and app tests to GitHub CI
    • +
  • Make more CAmkES tests available on pull requests
    • +
  • Small tutorial fixes
    • +
  • Improve thread priority description in docs
    • +
  • Remove unused python dependencies
    • +
  • Replace obsolete orderedset python dependency with maintained ordered_set
    • +
  • Update camkes-deps description and instructions
    • +
  • camkes-deps: set minimum jinja2 version
    • +
+ +

Upgrade Notes

+ +
    +
  • No special upgrade requirements.
    • +
+ +

Full changelog

+ +

Use git log camkes-3.10.0..camkes-3.11.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+ +

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.11.1.html b/releases/camkes/camkes-3.11.1.html new file mode 100644 index 00000000000..9c9afae1417 --- /dev/null +++ b/releases/camkes/camkes-3.11.1.html @@ -0,0 +1,583 @@ + + + + + + + Camkes 3.11.1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.11.1 Release

+ +

Announcing the release of camkes-3.11.1 with the following changes:

+ +

camkes-3.11.1 2025-11-25

+ +

Using seL4 version 14.0.0

+ +

Changes

+ +
    +
  • Add support for gcc-14, fixing new warnings in generated code.
    • +
  • Add support for more recent version of musllibc.
    • +
  • Minor documentation improvements.
    • +
+ +

Upgrade Notes

+ +
    +
  • No special upgrade requirements.
    • +
+ +

Full changelog

+ +

Use git log camkes-3.11.0..camkes-3.11.1 in https://github.com/seL4/camkes-tool

+ +

More details

+ +

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.2.0.html b/releases/camkes/camkes-3.2.0.html new file mode 100644 index 00000000000..bba656b0c22 --- /dev/null +++ b/releases/camkes/camkes-3.2.0.html @@ -0,0 +1,642 @@ + + + + + + + Camkes 3.2.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.2.0 Release

+ +

Announcing the release of camkes-3.2.0 with the following changes:

+ +

camkes-3.2.0 2018-01-17

+ +

Using seL4 version 8.0.0

+ +

Changes

+ + + +

Known issues

+ +
    +
  • Hardware dataports that are large enough to use larger frame + sizes are currently broken. There is an issue with
    • +
+ +

large frame promotion and hardware dataports where the capDL loader is +unable to map the promoted memory. This can be demonstrated by running +the testhwdataportlrgpages app on either +arm_testhwdataportlrgpages_defconfig or +x86_testhwdataportlrgpages_defconfig configurations. If this +functionality is required, hold off upgrading until this issue is fixed.

+ +

Upgrade notes

+ +
    +
  • +

    ADL files: ADL syntax changes in this release should not break + any existing ADL files. +-

    + + 
      Templates:
+
+      seL4HardwareMMIO template now has an option to map hardware
+      memory as cached. The default setting is uncached
+
    +
    • +
+ +

which is the same as the old behaviour.

+ +

Full changelog

+

Use git log camkes-3.2.0..camkes-3.1.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.3.0.html b/releases/camkes/camkes-3.3.0.html new file mode 100644 index 00000000000..8b15b769bdf --- /dev/null +++ b/releases/camkes/camkes-3.3.0.html @@ -0,0 +1,590 @@ + + + + + + + Camkes 3.3.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.3.0 Release

+ +

Announcing the release of camkes-3.3.0 with the following changes:

+ +

camkes-3.3.0 2018-04-11

+ +

Using seL4 version 9.0.0

+ +

Changes

+
    +
  • Hardware dataport with large frame sizes issue has been fixed
    • +
  • Bug fix: Enumerating connections for hierarchical components with custom connection types is now done correctly
    • +
  • Bug fix: Data structure caching is now correctly invalidated between builds
    • +
  • Initial CMake implementation for CAmkES. See the CAmkES test apps for examples.
    • +
+ +

Upgrade notes

+
    +
  • No special upgrade requirements.
    • +
+ +

Known issues

+
    +
  • Hierarchical components that export dataport connectors create compilation errors as the templates cannot accurately +tell that the connector of the parent component is exported from the child and no code should be generated. A +temporary workaround involves making the dataport connection explicitly available to the parent component.
    • +
+ +
+ +

Full changelog

+

Use git log camkes-3.2.0..camkes-3.3.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.4.0.html b/releases/camkes/camkes-3.4.0.html new file mode 100644 index 00000000000..a10d2b8893c --- /dev/null +++ b/releases/camkes/camkes-3.4.0.html @@ -0,0 +1,573 @@ + + + + + + + Camkes 3.4.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.4.0 Release

+ +

Announcing the release of `` with the following changes:

+ +

camkes-3.4.0 2018-04-18

+ +

Using seL4 version 9.0.1

+ +

Changes

+ +

Upgrade Notes

+
+ +

Full changelog

+

Use git log camkes-3.3.0..camkes-3.4.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.5.0.html b/releases/camkes/camkes-3.5.0.html new file mode 100644 index 00000000000..e1d5b091b6f --- /dev/null +++ b/releases/camkes/camkes-3.5.0.html @@ -0,0 +1,583 @@ + + + + + + + Camkes 3.5.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.5.0 Release

+ +

Announcing the release of camkes-3.5.0 with the following changes:

+ +

camkes-3.5.0 2018-05-28 +Using seL4 version 10.0.0

+ +

This release is the last release with official support for Kbuild based projects. +This release and future releases use CMake as the build system for building applications.

+ +

Changes

+
    +
  • Remove crit and max_crit fields from TCB CapDL Object +These fields were previously added to support an earlier version of seL4-mcs that gave threads criticality fields. +This feature was removed from seL4-mcs. This also means that the arguments to camkes-tool, --default-criticality +and --default-max-criticality, have also been removed.
    • +
+ +

Upgrade Notes

+
    +
  • Calls to camkes.sh that used the above arugments will need to be updated.
    • +
+ +

Full changelog

+

Use git log camkes-3.4.0..camkes-3.5.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.6.0.html b/releases/camkes/camkes-3.6.0.html new file mode 100644 index 00000000000..37f7b63a162 --- /dev/null +++ b/releases/camkes/camkes-3.6.0.html @@ -0,0 +1,600 @@ + + + + + + + Camkes 3.6.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.6.0 Release

+ +

Announcing the release of camkes-3.6.0 with the following changes:

+ +

camkes-3.6.0 2018-11-07 +Using seL4 version 10.1.0

+ +

Changes

+ +
    +
  • AARCH64 is now supported.
    • +
  • CakeML components are now supported.
    • +
  • Added query type to CAmkES ADL to allow for querying plugins for component configuration values.
    • +
  • Components can now make dtb queries to parse device information from dts files.
    • +
  • Component definitions for serial and timer added on exynos5422, exynos5410, pc99.
    • +
  • Preliminary support for Isabelle verification of generated capDL. +
      +
    • See cdl-refine-tests/README for more information
      • +
    +
    • +
  • Simplify and refactor the alignment and section linking policy for generated CAmkES binaries.
    • +
  • Dataports are now required to declare their size in the ADL.
    • +
  • Templates now use seL4_IRQHandler instead of seL4_IRQControl, which is consistent with the seL4 API. +
      +
    • This change is BREAKING.
      • +
    +
    • +
  • Remove Kbuild based build system.
    • +
  • Remove caches that optimised the Kbuild build system, which are not required with the new Cmake build system.
    • +
  • Added virtqueue infrastructure to libsel4camkes, which allows virtio style queues between components.
    • +
+ +

Upgrade Notes

+ +
    +
  • Any dataport definitions that did not specify a size must be updated to use a size.
    • +
  • Any template that used seL4_IRQControl must be updated to use seL4_IRQHandler.
    • +
  • Projects must now use the new Cmake based build system.
    • +
+ +

Full changelog

+

Use git log camkes-3.5.0..camkes-3.6.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.7.0.html b/releases/camkes/camkes-3.7.0.html new file mode 100644 index 00000000000..3c0eac6817f --- /dev/null +++ b/releases/camkes/camkes-3.7.0.html @@ -0,0 +1,571 @@ + + + + + + + Camkes 3.7.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.7.0 Release

+ +

Announcing the release of camkes-3.7.0 with the following changes:

+ +

camkes-3.7.0 2018-11-12 +Using seL4 version 10.1.1

+ +

Changes

+ +

Upgrade Notes

+ +

Full changelog

+

Use git log camkes-3.6.0..camkes-3.7.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.8.0.html b/releases/camkes/camkes-3.8.0.html new file mode 100644 index 00000000000..5f11cdc4626 --- /dev/null +++ b/releases/camkes/camkes-3.8.0.html @@ -0,0 +1,622 @@ + + + + + + + Camkes 3.8.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.8.0 Release

+ +

Announcing the release of camkes-3.8.0 with the following changes:

+ +

camkes-3.8.0 2019-11-19 +Using seL4 version 11.0.0

+ +

Changes

+ +
    +
  • Support for the new seL4 Endpoint GrantReply access right for CAmkES connector types. +
      +
    • This allows multi-sender/single-receiver connectors such as seL4RPCCall that don’t also provide the ability for +arbitrary capability transfer from sender to receiver. Previously the seL4RPC connector was used instead of +seL4RPCCall to create an Endpoint without a Grant right. This used a combination of seL4_Send and seL4_Wait +to communicate without the ability for capability transfer, however this only supports a single sender and single +receiver.
      • +
    +
    • +
  • Better support for configuring components with a provided devicetree. +
      +
    • This support includes adding an seL4DTBHardware connector that can be used instead of seL4HardwareMMIO and +seL4HardwareInterrupt and can be used to extract IRQs and MMIO register information out of the devicetree node rather +than specifying the info directly. This connector can also be used to access a devicetree within a component for +querying further device information. There is also a connector seL4VMDTBPassthrough that can be used for specifying +devices to pass through to a camkes-arm-vm VM component.
      • +
    +
    • +
  • CapDL Refinement framework (cdl-refine). +These are generated Isabelle proof scripts to prove that the generated capDL respects the isolation properties +expected from its CAmkES system specification. Only the AARCH32 platform is supported. The generated capDL is a +specification of seL4 objects and capabilities that will implement the CAmkES system specification. This +specification is then given to a system initialiser to create the objects and capabilities and load the system.
    • +
  • Support for RISC-V systems.
    • +
  • Port libsel4camkes environments to the sel4runtime
    • +
  • CAmkES can be used on any seL4 platform that uses a camkes supported seL4 architecture (x86, Arm, RISC-V)
    • +
  • By default the C preprocessor will be run over CAmkES ADL files +
      +
    • The CAmkES syntax excludes lines starting with # due to the integration of CPP. This can sometimes cause +confusion where #ifdef is used but the CPP isn’t configured to run. Projects are still able to disable the CPP.
      • +
    +
    • +
  • capDL Static initialisation +
      +
    • Using the capDL support for static allocation of objects from an Untyped list, CAmkES supports generating specs +with all objects preallocated. This can then be loaded by a static loader.
      • +
    • This is only supported on Arm by setting CAmkESCapDLStaticAlloc=ON.
      • +
    +
    • +
  • Use large pages for dataports if able +
      +
    • Instead of rounding the dataports to 4K pages all the time, try to use multiples of larger frames to back the +dataports if the size of the dataports are a multiple of the larger frames.
      • +
    +
    • +
  • Fix cache flush for seL4HardwareMMIO connectors +
      +
    • This was a feature that was available in 2.x.x but removed in 3.0.0.
      • +
    +
    • +
+ +

Full changelog

+

Use git log camkes-3.7.0..camkes-3.8.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/camkes/camkes-3.9.0.html b/releases/camkes/camkes-3.9.0.html new file mode 100644 index 00000000000..a05b4ce1c06 --- /dev/null +++ b/releases/camkes/camkes-3.9.0.html @@ -0,0 +1,704 @@ + + + + + + + Camkes 3.9.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CAmkES Version camkes-3.9.0 Release

+ +

Announcing the release of camkes-3.9.0 with the following changes:

+ +

camkes-3.9.0 2020-10-26 +Using seL4 version 12.0.0

+ +

Changes

+ +

Below is a lightly edited list of all PRs merged into master for this release.

+ +
    +
  • Enforce system-V stack ordering for libc. +
      +
    • This allows musllibc to initialise and infer the location of auxv from envp consistently.
      • +
    +
    • +
  • Add uint64_t and int64_t types to language. +
      +
    • This introduced two new data types into the CAmkES language to support larger types.
      • +
    +
    • +
  • Remove elf.h, now defined in sel4runtime.
    • +
  • CAmkES,rumprun: fix tls management implementation: +
      +
    • .tdata* and .tbss* linker symbol declarations are suppressed until the final link step.
      • +
    +
    • +
  • Fix generate_seL4_SignalRecv in Context.py and update rpc-connector.c template accordingly. +
      +
    • seL4SignalRecv only exists on MCS, split the two calls for compatibility.
      • +
    +
    • +
  • Save preprocessed camkes files to allow for easier debugging.
    • +
  • CMake: Skip fetching gpio list for pc99 platforms. +
      +
    • Most PC99 platforms do not have GPIO pins.
      • +
    +
    • +
  • Support for running odroidc2 in camkes-arm-vm. Get the IRQ trigger type through the interrupt node in the dts.
    • +
  • Add gpio query engine. +
      +
    • The engine takes in a YAML file containing a list of GPIO pins and sorts out the ‘gpio’ queries so that the connector templates for the seL4GPIOServer can generate the appropriate structures and functions.
      • +
    +
    • +
  • Add option CAmkESNoFPUByDefault. +
      +
    • By enabling CAmkESNoFPUByDefault camkes will compile all user-level libraries (except musllibc) with compilation flags to not use the FPU. A component that wishes to use the FPU must override the flags itself.
      • +
    +
    • +
  • Update seL4InitHardware template for api change. +
      +
    • The configuration name for the list of devices to bind is now a component attribute instead of an interface attribute.
      • +
    +
    • +
  • libsel4camkes Support registering DMA memory that is both cached and uncached.
    • +
  • Add sel4bench dependency into camkes/templates to allow for cycle counting.
    • +
  • component.common.c: use correct label for dma pool. +
      +
    • When calling register_shared_variable from a component context the label needs to be provided.
      • +
    +
    • +
  • Add seL4DTBHW connector. This connector variant is similar to seL4DTBHardware, but takes a hardware component on the from end.
    • +
  • seL4DTBHardware bug fix, use global interface name. This prevents the allocator from throwing an error when the same interface name is used in a different component.
    • +
  • CAmkES connector extensions + DMA improvements: +
      +
    • libsel4camkes: Implement DMA cache for Arm
      • +
    • component.common.c: Support additional DMA setting. Allow setting the cache and base paddr value of the DMA pool.
      • +
    • Add single_threaded attribute which when set adds the seL4SingleThreadedComponent templates.
      • +
    • Allow connectors to declare CMake libraries for each end of the connection. This allows a connector to have most of its implementation in a library and only use the template for initialisation and configuration.
      • +
    • camkes-gen.cmake: Create component target stub. This is equivalent to creating a Component with no customization but would still contain things based on its CAmkES definition, such as connector artifacts.
      • +
    +
    • +
  • Component.common.c: Move init() to C constructor +
      +
    • Connectors that don’t use threads use runtime constructors for their initialisation.
      • +
    +
    • +
  • Libsel4camkes: camkes_call_hardware_init_modules +Provide this public function for starting hardware modules that have been registered.
    • +
  • Add global_rpc_endpoint_badges macro. +
      +
    • This macro assigns badges for different connectors that share the global-rpc-endpoint object for a component instance.
      • +
    +
    • +
  • Libsel4camkes: irq backend for global-connectors. This adds a way for calling registered IRQ notification handlers for connectors that don’t have their own threads.
    • +
  • Add seL4DMASharedData connector and add appropriate library functionality in libsel4camkes. +
      +
    • This connector sets up a dataport connector that is added to the DMA pool that the camkes runtime tracks for each component.
      • +
    +
    • +
  • Add support for connector header files and component header templates. +
      +
    • A connector can now define template header files that will be included by camkes.h. Similarly, component header templates will be instantiated and then automatically included by camkes.h.
      • +
    +
    • +
  • Support creating TCB pools and assigning domains to them in camkes templates. +
      +
    • Assign domain IDs for TCBs in the thread pool based on values provided by the config option array values.
      • +
    +
    • +
  • Generalise jinja linter to support non-camkes use cases. The Jinja linter can now be used on any arbitrary Jinja template.
    • +
  • Add support in libsel4camkes for matching interrupts even if they are defined +with different base types.
    • +
  • Add interface registration to libsel4camkes via interface_registration.h as part of the driver framework.
    • +
  • Revive graph.dot output file for each asssembly. This can be loaded with a +program like xdot to view a diagram of the camkes system.
    • +
  • Virtqueues: +
      +
    • Add virtqueue recieve.
      • +
    • Set virtqueue size on creation to the number of rings and descriptor tables have.
      • +
    • Add virtqueue_get_client_id macro for automatically assigning client IDs to distinguish different virtqueue channels within a single component instance.
      • +
    • Link channel ID to name, this allows components to bind to channels via naming them rather than knowing their IDs.
      • +
    +
    • +
  • Add Arm irq type support to seL4HardwareInterrupt template. This allows IRQs on Arm to have the trigger mode and target core configured.
    • +
  • Allow size to be number as well as a string in marshal.c template.
    • +
  • Add global_endpoint_badges macro used by the global-endpoints mechanism to assign badge +values based on a full system composition.
    • +
  • Make public allocate_badges method which is used to standardize badge allocation across many connectors.
    • +
  • Add support for a component definition to specify a template C source file. This file will be passed through the template tool before passed to the C compiler. +
      +
    • This is how components can allocate objects required from a loader without having to define special connector types.
      • +
    +
    • +
  • Add msgqueue mechanism which allows componets to sent messages. This is essentially another layer ontop of the virtqueue functionality.
    • +
  • Accept Red Hat ARM cross-compilers in check_deps.py.
    • +
  • Simplify the logic for combining the connections in the stage9 parser. This improves processing times.
    • +
  • camkes-tool: +
      +
    • Add priority to muslc so that its initialsation comes after camkes. This relates to recent changes in sel4runtime.
      • +
    • Add an interface dataport_caps for accessing dataport caps that is used by the seL4SharedDataWithCaps template.
      • +
    +
    • +
  • Tools: define camkes_tool_processing when running the C preprocessor.
    • +
  • Remove template keyword from camkes language. +
      +
    • This is driven by wanting to make it easier to extend camkes generation build rules with more inputs than a single template file and make it possible better manage non-template code that needs to run when generating templates.
      • +
    +
    • +
+ +

Upgrade Notes

+ +

Full changelog

+

Use git log camkes-3.8.0..camkes-3.9.0 in +https://github.com/seL4/camkes-tool

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of CAmkES releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/capDL.html b/releases/capDL.html new file mode 100644 index 00000000000..2e2765a3e67 --- /dev/null +++ b/releases/capDL.html @@ -0,0 +1,567 @@ + + + + + + + capDL Releases | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

capDL Releases

+ + + + +
+ +
+
+ + + +
+
+
+ + diff --git a/releases/capdl/0.1.0.html b/releases/capdl/0.1.0.html new file mode 100644 index 00000000000..c4ef0fde956 --- /dev/null +++ b/releases/capdl/0.1.0.html @@ -0,0 +1,655 @@ + + + + + + + 0.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

CapDL Version 0.1.0 Release

+ +

Announcing the release of 0.1.0 with the following changes:

+ +

0.1.0 2019-11-19 +Using seL4 version 11.0.0

+ +

Changes

+ +
    +
  • Add GrantReply access right for endpoint capabilities. +
      +
    • This is a new right available on seL4 Endpoint object capabilities.
      • +
    • A capDL spec can now describe an endpoint capability with the ‘P’ GrantReply access right.
      • +
    • The capdl-loader-app will create capabilities with these rights based on the translated spec.
      • +
    • python-capdl-tool supports creating endpoint caps with GrantReply rights.
      • +
    +
    • +
  • Add object_sizes target. +
      +
    • This target generates a YAML file describing the object size of each seL4 object.
      • +
    • It is based on the current build configuration of the kernel.
      • +
    • This file can be used as an input to tools performing allocation of seL4 objects from untypeds.
      • +
    +
    • +
  • Add untyped_gen.py in cdl_utils. +
      +
    • This is only supported on Arm architectures currently.
      • +
    • This tool generates a predicted list of untypeds that the kernel will provide to userlevel
      • +
    • This list is calculated from an input of memory regions for the platform and sizes of the kernel image and device +tree binary.
      • +
    • The list is intended to be used as an input for an allocator to perform allocation of initial system resources.
      • +
    +
    • +
  • capDL untyped allocation +
      +
    • Add support for generating a capDL spec that specifies which untyped object each object and capability is allocated +from. This is intended to be used when implementing trustworthy system initialisers as it removes online allocation +decisions and results in a simpler init program.
      • +
    • This is only supported on Arm.
      • +
    +
    • +
  • Static allocator +
      +
    • Updates capdl-loader-app to load static specs with all objects allocated from a predicted list of untypeds.
      • +
    • This simpler version of the loader app will act as a reference implementation for a more trustworthy implementation +that is in development.
      • +
    • This is only supported on Arm.
      • +
    +
    • +
  • RISC-V support added +
      +
    • Support for generating, translating and loading RISC-V applications.
      • +
    +
    • +
  • seL4runtime updates +
      +
    • Port capdl-loader-app to sel4runtime
      • +
    +
    • +
  • cdl-refine +
      +
    • This support is closely tied to CAmkES and L4V.
      • +
    • The capDL-tool can translate specs into Isabelle .thy file formats. These are then used to calculate which access +rights different parts of the system have to each other.
      • +
    • It is used to check that the capDL system spec implements certain access policies as specified by an external +source.
      • +
    • See cdl-refine in the context of CAmkES for more information.
      • +
    +
    • +
  • 40-bit PA for aarch64 hyp +
      +
    • When seL4 is running in EL2 on aarch64, VSpace objects are an abstraction of stage 2 translations. +These translations have different input address restrictions based on the physical address range the CPU supports. +40-bit PA support supports platforms that have 40-bit stage 2 input address ranges when in hyp-mode.
      • +
    +
    • +
  • Remove –code-max-irqs from capDL tool +
      +
    • The capDL-tool that translates capDL formats no longer requires –code-max-irqs as an option for generating C specs. +It now infers the total IRQs from the input spec and specifies this value in the generated C spec.
      • +
    +
    • +
  • Add FrameFill mechanism for files and use this to implement ELF loading +
      +
    • The FrameFill mechanism allows Frame objects to be annotated with an attribute describing a way to initialise +their contents by a loader.
      • +
    • The new file FrameFill mechanism allows frames to be initialised from the contents of a file provided to the loader +in a cpio archive.
      • +
    • This mechanism is used to remove ELF loader support from the initialiser. Instead a spec describes how frames are +initialised via copies from offsets into a provided ELF file.
      • +
    • This allows a loader to load program data from different file formats also.
      • +
    +
    • +
+ +

Full changelog

+

Use git log 0.1.0 in +https://github.com/seL4/capdl

+ +

More details

+

Ask on the mailing list!

+ + +

Other releases

+

+ See the + full list of capDL releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/capdl/0.2.0.html b/releases/capdl/0.2.0.html new file mode 100644 index 00000000000..9a64a74fa1c --- /dev/null +++ b/releases/capdl/0.2.0.html @@ -0,0 +1,629 @@ + + + + + + + 0.2.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

capDL Version capdl-0.2.0 Release

+ +

Announcing the release of capdl-0.2.0 with the following changes:

+ +

capdl-0.2.0 2020-10-26 +Using seL4 version 12.0.0

+ +

Changes

+ +
    +
  • +

    Convert to SPDX license tags. This includes marking all documentation files CC-BY-SA-4.0.

    +
    • +
  • Build system: +
      +
    • Support CMakeForegroundComplexCommands. This enables long-running build steps like Haskell installation to +directly print to the console.
      • +
    • Make PLATFORM_SIFT agnostic of the build system directory layout
      • +
    • Save the binary artifacts for the capDL-tool in an out-of-build-tree directory, this will not rebuild in future if +it can find a previously built artifact.
      • +
    • Migrate scripts to python3
      • +
    +
    • +
  • Add seL4_BadgeBits constant and update python-capdl-tool to directly query the object_sizes dictionary. This allows +for templates to use badge sizes.
    • +
  • Add support for Arm smmu v2.
    • +
  • Add support for Arm GetTrigger and GetTriggerCore seL4 invocations. This enables specs to correctly specify interrupt +trigger mode and core affinities on Arm.
    • +
  • Add TCB Resume field to capDL object and support raw TCB object creation.
    • +
  • Add GitHub actions scripts. These scripts replicate internal CI checks directly on GitHub
    • +
+ +

capDL-tool

+ +
    +
  • rework validObjCap and check TCB slots, which allows vcpus for all architectures.
    • +
  • convert CapDL language specification to Markdown.
    • +
+ +

Capdl-loader-app

+ +
    +
  • Improve log output.
    • +
  • Initialise libc in debug builds.
    • +
  • Add check to only flush and invalidate kernel memory regions in capdl loader on Arm. Add platform_info header with +memory window.
    • +
  • Add vcpu support for aarch64.
    • +
  • Handle IRQ binding to badged notifications properly: If an irq is bound to a notification with a non-zero badge, a +badged capability is minted and used. Previously, the IRQ was bound to the unbadged notification.
    • +
  • Track number of used untypeds during object allocation and fail more gracefully if they run out.
    • +
  • Improve debugging printouts.
    • +
  • Fix issue where large DTB images inside BootInfo would overlap reserved memory address used to initialise frames.
    • +
  • Remove CONFIG_CAPDL_LOADER_ALLOW_NO_CSPACE config option as it has been unused for a while.
    • +
+ +

Capdl-linker:

+ +
    +
  • Optimize spec generation performance: +
      +
    • Sort elf symbols by their vaddr.
      • +
    • Replace linear search with binary when looking for virtual addresses.
      • +
    +
    • +
  • Fix Python syntax warnings when capdl_linker.py is invoked.
    • +
+ +

Upgrade Notes

+ +

Full changelog

+

Use git log 0.1.0..capdl-0.2.0 in +https://github.com/seL4/capdl

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of capDL releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/capdl/0.2.1.html b/releases/capdl/0.2.1.html new file mode 100644 index 00000000000..5fff1685174 --- /dev/null +++ b/releases/capdl/0.2.1.html @@ -0,0 +1,582 @@ + + + + + + + 0.2.1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

capDL Version 0.2.1 Release

+ +

Announcing the release of 0.2.1 with the following changes:

+ +

0.2.1 2021-06-10 +Using seL4 version 12.1.0

+ +

Changes

+ +
    +
  • Added page-upper-directory caps to the valid TCB check for platforms like QEMU arm-virt as they use different paging +structures.
    • +
  • Added const qualifiers to the capdl-loader-app to avoid compiler warnings against other libraries.
    • +
  • Improved the README for the capdl-loader-app.
    • +
+ +

Upgrade Notes

+ +
    +
  • None to be aware of. This is not a source-breaking or binary-breaking release.
    • +
+ +

Full changelog

+

Use git log capdl-0.2.0..0.2.1 in +https://github.com/seL4/capdl

+ +

More details

+

See the +documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of capDL releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/capdl/0.3.0.html b/releases/capdl/0.3.0.html new file mode 100644 index 00000000000..f009df997d9 --- /dev/null +++ b/releases/capdl/0.3.0.html @@ -0,0 +1,605 @@ + + + + + + + 0.3.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

capDL Version 0.3.0 Release

+ +

2024-07-01

+ +

Announcing the release of 0.3.0, using seL4 version 13.0.0.

+ +

Changes

+ +
    +
  • add support for SMC capability
    • +
  • add support for binding notifications to TCBs
    • +
  • enable MCS build; use seL4_TCB_SetAffinity only for non-MCS kernels
    • +
  • allow SchedControlCap to refer to a secondary core
    • +
  • minimal update for seL4 AArch64 VSpace API change, removing seL4_ARM_PageGlobalDirectoryObject
    • +
  • object_sizes: add include for deprecated constants, because some definitions +that object_sizes depends on are now found in a deprecated.h header file.
    • +
  • Clean up and clarify arm11 usage in capDL despite ARMv6 removal
    • +
  • cdl_utils: remove simpleeval python dependency
    • +
  • Run GitHub tests with python 3.9
    • +
  • added vulnerability reporting policy
    • +
+ +

capdl-loader

+ +
    +
  • use seL4_BootInfoFrameSize instead of hard-coded page size
    • +
  • python + loader: Add support for generating fault handler caps with specific +rights. Behaviour is unchanged (seL4_AllRights) if no rights are provided.
    • +
  • ensure heap is aligned
    • +
+ +

capDL-tool

+ +
    +
  • update to LTS Haskell 20.25, ghc-9.2.8
    • +
  • fix several cases in validObjPars: Period, IOAPIC, MSIHandle, CBNumber
    • +
+ +

Upgrade Notes

+ +
    +
  • existing capDL specs should continue to work
    • +
  • AArch64 VSpace changes may allow simplification of some capDL specs
    • +
+ +

Full changelog

+ +

Use git log 0.2.1..0.3.0 in https://github.com/seL4/capdl

+ +

More details

+ +

See the documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of capDL releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/capdl/0.4.0.html b/releases/capdl/0.4.0.html new file mode 100644 index 00000000000..62f5e3ae6c8 --- /dev/null +++ b/releases/capdl/0.4.0.html @@ -0,0 +1,584 @@ + + + + + + + 0.4.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

capDL Version 0.4.0 Release

+ +

Announcing the release of 0.4.0 with the following changes:

+ +

0.4.0 2025-11-25

+ +

Using seL4 version 14.0.0

+ +

Changes

+ +
    +
  • Add support for fpu_disabled flag on TCBs for platforms with CONFIG_HAVE_FPU.
    • +
  • Add support for SGISignal capability. SGISignal capabilities in capDL point +to an arm_sgi_signal object with (irg: <num>, target: <num>) properties +that define the destination of the SGI.
    • +
  • Remove pyaml python dependency and use pyyaml (import yaml) directly.
    • +
+ +

Upgrade Notes

+ +
    +
  • existing capDL specs should continue to work without change
    • +
+ +

Full changelog

+ +

Use git log 0.3.0..0.4.0 in https://github.com/seL4/capdl

+ +

More details

+ +

See the documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of capDL releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/microkit.html b/releases/microkit.html new file mode 100644 index 00000000000..90ca4d1972c --- /dev/null +++ b/releases/microkit.html @@ -0,0 +1,784 @@ + + + + + + + Microkit releases | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit releases

+ +

This page documents tagged releases of the seL4 Microkit and their +corresponding SDK downloads and GPG signatures.

+ +

The downloads are signed by Ivan Velickovic i.velickovic@unsw.edu.au with the +key fingerprint EFC6 142C FE61 C255 B4CD E959 6FBD 87E8 4FA8 89BB. The key +is available from https://keys.openpgp.org/.

+ +

2.1.0 (latest)

+ +

Release notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OSArchDownloadSignature
Linuxx86-64microkit-sdk-2.1.0-linux-x86-64.tar.gzsig
LinuxAArch64microkit-sdk-2.1.0-linux-aarch64.tar.gzsig
macOSx86-64microkit-sdk-2.1.0-macos-x86-64.tar.gzsig
macOSAArch64microkit-sdk-2.1.0-macos-aarch64.tar.gzsig
+ +

2.0.1

+ +

Release notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OSArchDownloadSignature
Linuxx86-64microkit-sdk-2.0.1-linux-x86-64.tar.gzsig
LinuxAArch64microkit-sdk-2.0.1-linux-aarch64.tar.gzsig
macOSx86-64microkit-sdk-2.0.1-macos-x86-64.tar.gzsig
macOSAArch64microkit-sdk-2.0.1-macos-aarch64.tar.gzsig
+ +

2.0.0

+ +

Release notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OSArchDownloadSignature
Linuxx86-64microkit-sdk-2.0.0-linux-x86-64.tar.gzsig
LinuxAArch64microkit-sdk-2.0.0-linux-aarch64.tar.gzsig
macOSx86-64microkit-sdk-2.0.0-macos-x86-64.tar.gzsig
macOSAArch64microkit-sdk-2.0.0-macos-aarch64.tar.gzsig
+ +

1.4.1

+ +

Release notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OSArchDownloadSignature
Linuxx86-64microkit-sdk-1.4.1-linux-x86-64.tar.gzsig
macOSx86-64microkit-sdk-1.4.1-macos-x86-64.tar.gzsig
macOSAArch64microkit-sdk-1.4.1-macos-aarch64.tar.gzsig
+ +

1.4.0

+ +

Release notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OSArchDownloadSignature
Linuxx86-64microkit-sdk-1.4.0-linux-x86-64.tar.gzsig
macOSx86-64microkit-sdk-1.4.0-macos-x86-64.tar.gzsig
macOSAArch64microkit-sdk-1.4.0-macos-aarch64.tar.gzsig
+ +

1.3.0

+ +

Release notes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OSArchDownloadSignature
Linuxx86-64microkit-sdk-1.3.0-linux-x86-64.tar.gzsig
macOSx86-64microkit-sdk-1.3.0-macos-x86-64.tar.gzsig
macOSaarch64microkit-sdk-1.3.0-macos-aarch64.tar.gzsig
+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/releases/microkit/1.3.0.html b/releases/microkit/1.3.0.html new file mode 100644 index 00000000000..338293e9cec --- /dev/null +++ b/releases/microkit/1.3.0.html @@ -0,0 +1,629 @@ + + + + + + + 1.3.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit Release 1.3.0

+ +

2024-07-01

+ +

Announcing the release of 1.3.0, using seL4 version 13.0.0.

+ +

This release represents the first release since the seL4 Microkit was adopted by the +seL4 Foundation.

+ +

This release has no breaking changes.

+ +

You can find the pre-built SDK here.

+ +

Features added

+ +
    +
  • Added support for ‘passive’ protection domains.
    • +
  • Added protection domain hierarchy allowing PDs to manage faults caused by child PDs +and control their execution.
    • +
  • Added virtualisation support and a new ‘virtual machine’ abstraction that allows +users to create systems with guest operating systems (such as Linux).
    • +
  • Add the ability to specify the type of IRQ trigger on IRQ elements in the SDF. Previously +all IRQs were registered as level triggered, now users are given the option of specifying +an IRQ as ‘edge’ triggered which is needed for writing certain device drivers.
    • +
  • Added support for building the Microkit SDK on macOS. If you are on macOS, you can now develop +with Microkit without Docker or a virtual machine.
    • +
+ +

Other changes

+ +
    +
  • +

    Rewrote the Microkit tool from Python to Rust. This is meant to be a purely internal +change and should not affect the use of the tool at all. This does however introduce +a new dependency on Rust. See the README for building the new tool from source.

    + +
      +
    • This was done primarily to decrease 3rd party dependencies and make it easier to build +the Microkit SDK from source.
      • +
    +
    • +
+ +

Bug fixes

+ +
    +
  • Fixed the libmicrokit linker script to work with the LLVM linker, LLD. This means that non-GCC +build systems can link with libmicrokit.
    • +
  • Removed compiler provided includes (such as stdint.h and stdbool.h) from libmicrokit. This means +that the libmicrokit header no longer depends on any system provided headers, making the SDK +more self-contained.
    • +
  • Various fixes and improvements to the manual.
    • +
  • Various other bug-fixes and error message improvements to the Microkit tool.
    • +
+ +

Board support

+ +

This release adds support for the following platforms:

+ +
    +
  • Avnet MaaXBoard
    • +
  • HardKernel Odroid-C2
    • +
  • HardKernel Odroid-C4
    • +
  • NXP i.MX8MM-EVK
    • +
  • NXP i.MX8MQ-EVK
    • +
  • QEMU virt (AArch64)
    • +
  • Xilinx ZCU102
    • +
+ +

Full changelog

+ +

Use git log 59f3d7ecea21068281210e7dc91f66155dff9cc9..1.3.0 in https://github.com/seL4/microkit/

+ +

More details

+ +

See the documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of Microkit releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/microkit/1.4.0.html b/releases/microkit/1.4.0.html new file mode 100644 index 00000000000..3ded0761a97 --- /dev/null +++ b/releases/microkit/1.4.0.html @@ -0,0 +1,629 @@ + + + + + + + 1.4.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit Release 1.4.0

+ +

2024-08-05

+ +

This release aims to add support for requested features by the community, in order to +allow more people to use and transition to Microkit. There is of course still more to +be done over the next couple of releases.

+ +

This release has no breaking changes.

+ +

Features added

+ +
    +
  • Added support for RISC-V 64-bit based platforms.
    • +
  • Added a new ‘benchmark’ configuration to allow access to the in-kernel +performance tracking.
    • +
  • Add the ability to configure the stack size of a PD.
    • +
  • Export ARM architectural timer to user-space for the QEMU virt AArch64 platform. +
      +
    • This platform does not have any other timer so this is allows having a timer +driver when simulating/developing Microkit systems with QEMU.
      • +
    +
    • +
  • Add new APIs for ‘deferred’ versions of microkit_notify and microkit_irq_ack. +See the manual for details on when and how to use these.
    • +
+ +

Other changes

+ +
    +
  • Made a number of internal changes to the tool to improve performance and peak memory +usage. +
      +
    • The tool’s performance was not noticeable until building larger systems with Microkit. +Now invoking the Microkit tool with a large system should not take more than 500ms-1s to +complete. There are more opportunities for optimisation if we do run into the tool slowing +down however.
      • +
    +
    • +
+ +

Bug fixes

+ +
    +
  • Fixed the loader to not print unless in debug mode (matching the behaviour of +the kernel and monitor).
    • +
  • Add error checking for duplicate symbols between setvar_vaddr attributes and +setvar elements.
    • +
  • Fixed an internal issue that prevented the Monitor from printing out correct fault +information in debug mode.
    • +
  • Fixed the parsing of parent protection domains, previously non-trivial cases were +leading to errors.
    • +
  • Fixed the tool to explicitly skip ELF segments that are not declared as loadable, +previously the tool assumed all segments would be loaded at runtime.
    • +
  • Fix permissions applied to the distributed/packaged SDK. Previously this would cause +sudo access to move/remove the SDK.
    • +
  • Fixed an internal issue that prevented a memory region from being allocated at a fixed +physical address that is not part of device memory (e.g within RAM).
    • +
+ +

Board support

+ +

This release adds support for the following platforms:

+ +
    +
  • QEMU virt (RISC-V 64-bit)
    • +
  • Pine64 Star64
    • +
+ +

Full changelog

+ +

Use git log 1.3.0..1.4.0 in https://github.com/seL4/microkit/

+ +

More details

+ +

See the documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of Microkit releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/microkit/1.4.1.html b/releases/microkit/1.4.1.html new file mode 100644 index 00000000000..dcf1a957522 --- /dev/null +++ b/releases/microkit/1.4.1.html @@ -0,0 +1,596 @@ + + + + + + + 1.4.1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit Release 1.4.1

+ +

2024-08-16

+ +

This release contains various bug fixes. It does not include any new features.

+ +
    +
  • Fixed two bugs in the tool that lead to initialisation failure on larger Microkit systems.
    • +
  • Disabled the KernelArmVtimerUpdateVOffset kernel configuration option by default. +
      +
    • This is necessary for Microkit VMs where they rely on knowing the actual surpassed time. +More details are in the pull request.
      • +
    +
    • +
  • Enabled FPU for QEMU RISC-V virt and Pine64 Star64. +
      +
    • libmicrokit builds with hardware floating point enabled and, while it does not use the FPU, +it means that every object linked with libmicrokit must also build with hardware floating +point enabled. Previously using floating point operations would cause a crash in user-space.
      • +
    +
    • +
  • Fixed the loader link address for the MaaXBoard. +
      +
    • This does mean that if you target the MaaxBoard you will have to load Microkit images at +a different address. See the manual for details.
      • +
    +
    • +
  • Added error checking for overlapping memory regions.
    • +
  • Included every TCB register in the monitor logs when a fault occurs.
    • +
  • Made the tool compile from source with a Rust version lower that 1.79.0.
    • +
  • Specified a minimum Rust version for the tool (1.73.0).
    • +
  • Fixed typo in the --help output of the tool.
    • +
  • Minor README fixes.
    • +
  • Updated PyYAML dependency in requirements.txt to 6.0.2 (from 6.0).
    • +
+ +

Full changelog

+ +

Use git log 1.4.0..1.4.1 in https://github.com/seL4/microkit/

+ +

More details

+ +

See the documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of Microkit releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/microkit/2.0.0.html b/releases/microkit/2.0.0.html new file mode 100644 index 00000000000..ff1620c86cd --- /dev/null +++ b/releases/microkit/2.0.0.html @@ -0,0 +1,725 @@ + + + + + + + 2.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit Release 2.0.0

+ +

2025-03-06

+ +

This release contains various bug fixes, quality-of-life changes, features, and +new board support.

+ +

This is a major version bump due to a breaking change. Below the release notes, +there is a section on how to upgrade from Microkit 1.4.1.

+ +

Features

+ +
    +
  • Add support for virtual machines with multiple vCPUs.
    • +
  • Add support for ARM platforms to use SMC forwarding. +
      +
    • Note that this requires a kernel option to be set that right now is not +set by default on any ARM platforms in Microkit.
      • +
    +
    • +
  • Allow tool to target Linux AArch64 hosts, also available as a pre-built SDK +starting in this release.
    • +
  • Increase max PD name length to 64 characters (from 16).
    • +
  • Add Nix flake for Nix users who want to build from source and not depend on +the pre-built SDK.
    • +
  • Allow specifying whether a channel end can notify the other.
    • +
  • Memory Regions now default to the largest possible page size for the MR’s size +and alignment of virtual addresses of its mappings. +
      +
    • This is transparent to users, but can lead to improved performance and +memory usage.
      • +
    +
    • +
  • Utilise kernel API for naming threads in debug mode. +
      +
    • Helps debugging any kernel error prints in certain cases.
      • +
    +
    • +
  • Monitor fault handling now prints if a virtual memory exception was likely due +to a PD stack overflow.
    • +
  • Monitor fault handling now decodes user-exceptions likely caused by LLVM’s +UBSAN and prints appropriate debug output (only on AArch64).
    • +
  • Add setvar_size attribute for MR mappings, similar to setvar_vaddr.
    • +
  • Add a new ‘Internals’ section in the manual to document how the Microkit +actually works.
    • +
  • libmicrokit APIs for notifying, IRQ acking and performing PPCs now print +errors when an invalid channel is used in debug mode. +
      +
    • Previously this lead to a kernel error print that was not that useful from +within a Microkit environment.
      • +
    +
    • +
  • System images are now relocatable. +
      +
    • Previously they required loading at particular address within physical +memory, the Microkit loader will now relocate itself if loaded at a +different range of physical memory. This can make the boot-loading process +of Microkit images less fragile.
      • +
    +
    • +
+ +

Bug fixes

+ +
    +
  • Allow mapping in ‘null’ page. Necessary for virtual machines with guest memory +that starts at guest physical address zero.
    • +
  • More error checking for invalid mappings (e.g virtual address outside of valid +range).
    • +
  • Re-add warning for unused memory regions. +
      +
    • This is a bug fix since it used to be part of the tool before it was rewritten.
      • +
    +
    • +
  • Actually enforce the PPC priority rule that PPC is only allowed to PDs of higher +priority. +
      +
    • Note that to fix this in the tool, we had to introduce a breaking change +in the SDF. See upgrade notes for details.
      • +
    +
    • +
  • Fix a bug with kernel boot emulation that would sometimes occur when using +the release mode of the kernel.
    • +
  • Fix the GIC device addresses the loader was using for QEMU during +initialisation.
    • +
  • Fixed a bug preventing allocating a MR at certain fixed physical addresses.
    • +
  • Better error reporting when allocation of a memory region fails.
    • +
  • Fix allocation of Scheduling Context objects, previously we were allocating +more than necessary.
    • +
+ +

Board support

+ +
    +
  • i.MX8MP-EVK
    • +
  • Pine64 RockPro64
    • +
  • Ariane (aka CVA6)
    • +
  • Cheshire
    • +
  • Raspberry Pi 4B
    • +
+ +

Upgrade notes

+ +

There is a single breaking change in this release, it affects any +System Description Files (SDF) that make use of channels with PPCs.

+ +

This was done for two reasons:

+ +
    +
  1. It allows the tool to statically check and enforce the existing rule that a +PD that performs a PPC must be lower priority that the PD it is calling into.
    2. +
  2. It allows finer granularity on the channel ends. For example, previously +all channels allowed notifies either way, now that decision is up to the +user. The default behaviour remains the same, both ends are allowed to +notify each other.
    3. +
+ +

To upgrade, follow these steps:

+ +
    +
  1. Remove the pp attribute from any PDs that have it.
    2. +
  2. Go to each channel with the PD that had the pp attribute. Set pp="true" +on the end of the channel for the PD that is performing the PPC.
    3. +
+ +

Below is an example of upgrading a system that utilises PPCs.

+ +

From Microkit 1.4.1:

+
<protection_domain name="server" priority="254" pp="true">
+    <program_image path="server.elf" />
+</protection_domain>
+<protection_domain name="client" priority="1">
+    <program_image path="client.elf" />
+</protection_domain>
+<channel>
+    <end pd="server" />
+    <end pd="client" />
+</channel>
+
+ +

To Microkit 2.0.0:

+
<protection_domain name="server" priority="254">
+    <program_image path="server.elf" />
+</protection_domain>
+<protection_domain name="client" priority="1">
+    <program_image path="client.elf" />
+</protection_domain>
+<channel>
+    <end pd="server" />
+    <end pd="client" pp="true" />
+</channel>
+
+ +

Depending on your use-case you may also want to specify what end is allowed +to notify as well. For example, if the only communication between server +and client was PPC, you may want the channel to be the following:

+
<channel>
+    <end pd="server" notify="false" />
+    <end pd="client" notify="false" pp="true" />
+</channel>
+
+ +

You can find all the details in the +channel section of the manual.

+ +

Full changelog

+ +

Use git log 1.4.1..2.0.0 in https://github.com/seL4/microkit/

+ +

More details

+ +

See the documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of Microkit releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/microkit/2.0.1.html b/releases/microkit/2.0.1.html new file mode 100644 index 00000000000..4f8716b2e96 --- /dev/null +++ b/releases/microkit/2.0.1.html @@ -0,0 +1,577 @@ + + + + + + + 2.0.1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit Release 2.0.1

+ +

2025-03-20

+ +

This release contains various bug fixes. It does not include any new features.

+ +
    +
  • Fixed a regression introduced in 2.0.0 when using channel numbers greater than 32.
    • +
  • Fixed building SDK on Linux AArch64 hosts.
    • +
  • Fixed loader output to always output return character before newline.
    • +
  • Fixed loader to initialise UART for QEMU virt AArch64 to silence warnings +when using -d guest_errors.
    • +
  • Report error when user-specified PD mappings overlap with it’s own ELF +or stack region.
    • +
  • Included kernel bug-fix that prevented Raspberry Pi 4B booting correctly.
    • +
+ +

Full changelog

+ +

Use git log 2.0.0..2.0.1 in https://github.com/seL4/microkit/

+ +

More details

+ +

See the documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of Microkit releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/microkit/2.1.0.html b/releases/microkit/2.1.0.html new file mode 100644 index 00000000000..0508e616d48 --- /dev/null +++ b/releases/microkit/2.1.0.html @@ -0,0 +1,692 @@ + + + + + + + 2.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Microkit Release 2.1.0

+ +

2025-11-26

+ +

This release contains various bug fixes, quality-of-life changes, features, and new board support.

+ +

There are no breaking changes.

+ +

You can find the SDK downloads here.

+ +

Feature changes

+ +
    +
  • Initial x86-64 support. +
      +
    • This means that Microkit now supports all 64-bit architectures of seL4.
      • +
    +
    • +
  • Transition to using capDL for system initialisation. +
      +
    • While this is a significant internal change, there should be no +difference for users of Microkit.
      • +
    • However, this does mean we can now mark the seL4 RFC for Microkit as +‘implemented’!
      • +
    +
    • +
  • Update to 14.0.0 of seL4. +
      +
    • With the changes for the transition to capDL, we no longer need patches to the kernel.
      • +
    +
    • +
  • Add support for multi-core systems on all platforms. +
      +
    • For now, the default configurations of Microkit are still using the uni-core +variant of seL4. A different value to --config is required to use the +SMP variant.
      • +
    • See the manual section +for more details.
      • +
    +
    • +
  • Add new setvar_id attribute similar to setvar_vaddr but for any system description +elements that have an identifier associated with them (e.g channel ends).
    • +
  • Add new --image-type argument to the tool to specify system image format +that will be produced. +
      +
    • For ARM and RISC-V support we have only supported emitting a raw binary. We now support +ELFs and (on RISC-V) the uImage format.
      • +
    • On RISC-V platforms, when booting with U-Boot (e.g on the Star64) the binary format does +not receive the expected arguments for booting (hart ID). The binary was working by coincidence +and only for the uImage Linux format does U-Boot pass the hart ID when booting the image. For +this reason all RISC-V hardware platforms (other than our supported FPGA platforms) default to +uImage now to prevent booting issues.
      • +
    • See the manual section +for all details.
      • +
    +
    • +
  • Enable KernelAllowSMCCalls by default for all ARM platforms. +
      +
    • This means that all Microkit systems can make use of the PD SMC feature by default +rather than having to change the kernel configuration and then build the SDK from source.
      • +
    +
    • +
  • Increase the default PD stack size from 0x1000 to 0x2000.
    • +
  • Add different memory configurations for Raspberry Pi 4B. +
      +
    • Previously only 1GB was supported, now 2GB, 4GB and 8GB variants are available.
      • +
    +
    • +
  • Support building the SDK using LLVM instead of GCC. +
      +
    • GCC still remains the default for now, but this does give the option +for people to use LLVM when building Microkit from source.
      • +
    +
    • +
  • Default to using Python 3.12 when building from source.
    • +
  • Update Nix flake to use Nix 25.05.
    • +
+ +

Bug fixes

+ +
    +
  • Fixed the libmicrokit linker script to avoid the IPC buffer symbol potentially +overlapping with loadable segments.
    • +
  • Fixes and improvements to error checking on the system description.
    • +
  • Add missing inline to certain libmicrokit calls to fix warnings on newer C +compilers.
    • +
+ +

Board support

+ +
    +
  • Compulab IOT-GATE-IMX8PLUS
    • +
  • Serengeti
    • +
  • SiFive Premier P550
    • +
  • Ultra96v2
    • +
  • x86-64 generic targets
    • +
+ +

Upgrade notes

+ +

There are no breaking changes in this release, but for users it is important to +note that there was a significant internal change (transition to capDL) that may +lead to regressions.

+ +

We have fixed all regressions that we have found, but there may be some we +have missed. If you notice any unexpected behaviour, please +open an issue on GitHub.

+ +

Due to the capDL changes, the boot log output has slightly changed, so if you have scripts +that rely on the certain debug UART output you might have to update them.

+ +

Instead of this boot log:

+ +
Booting all finished, dropped to user space
+MON|INFO: Microkit Bootstrap
+MON|INFO: bootinfo untyped list matches expected list
+MON|INFO: Number of bootstrap invocations: 0x0000000a
+MON|INFO: Number of system invocations:    0x00000228
+MON|INFO: completed bootstrap invocations
+MON|INFO: completed system invocations
+
+ +

you’ll instead see this:

+ +
Booting all finished, dropped to user space
+INFO  [sel4_capdl_initializer::initialize] Starting CapDL initializer
+INFO  [sel4_capdl_initializer::initialize] Starting threads
+MON|INFO: Microkit Monitor started!
+
+ +

before your Microkit system starts.

+ +

Full changelog

+ +

Use git log 2.0.1..2.1.0 in https://github.com/seL4/microkit/

+ +

More details

+ +

See the documentation +or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of Microkit releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/seL4.html b/releases/seL4.html new file mode 100644 index 00000000000..a6d30b093f9 --- /dev/null +++ b/releases/seL4.html @@ -0,0 +1,792 @@ + + + + + + + seL4 releases | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 releases

+ +

This page documents tagged releases of the seL4 kernel and proofs.

+ +

Landmark releases

+ +

This section documents the version at which specific features were introduced to +seL4. For future features, see the roadmap +on the main seL4 website. For other previous features, see the release notes +below.

+ +

For the verification status of all platforms, see Verified +Configurations.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureHardwareAvailable From
AARCH64 RPI3RPI310.1.0
TX2 support (Aarch64 only)TX210.1.0
Support for more than 1 VMARM10.1.0
32-bit RISC-V architecture supportRISC-V (Spike simulation target)10.0.0
64-bit RISC-V architecture supportRISC-V (Spike simulation target)9.0.1
Meltdown mitigationx869.0.0
Spectre mitigationx869.0.0
Zynq UltraScale+ MPSoCXilinx ZCU102, ARMv8a, Cortex A538.0.0
Multiboot2 supportx868.0.0
CMake based build systemall7.0.0
ARM 32-bit SMPSabre6.0.0
ARMv7 32-bit FPU supportARM6.0.0
ARM 64-bit supportAarch645.0.0
64-bit x86 supportx86_644.0.0
Raspberry Pi 3 supportRPI34.0.0
ARM Hypervisor initial supportARM3.2.0
First ARMv8 supportHiKey3.1.0
NVIDIA Tegra K1 supportTK13.0.1
Notification bindingall2.0.0
+ +

Main releases

+ + + +

Older Mixed Criticality Support (MCS) / Realtime releases

+ +

As of seL4 version 11.0.0, the MCS features are included in the main kernel release, via the build option KernelIsMCS. Set KernelIsMCS to ON to switch the scheduler implementation to MCS and enable the MCS API.

+ + + + +
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/0.0.1-rt-dev.html b/releases/sel4/0.0.1-rt-dev.html new file mode 100644 index 00000000000..b78f306fc0c --- /dev/null +++ b/releases/sel4/0.0.1-rt-dev.html @@ -0,0 +1,657 @@ + + + + + + + 0.0.1 Rt Dev | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 0.0.1-rt-dev

+ +

The development branch of the for the seL4 realtime extensions. This +branch is not verified and is under active development.

+ +

Highlights

+ +
    +
  • +

    Maximum priorities

    + +
      +
    • Previously seL4 would not allow threads to set any other +thread’s priority to higher than its own. This has been +extracted into a separate field for the RT kernel, a maximum +priority, which limits what thread cans set their own or other +threads priorities to.
      • +
    +
    • +
  • +

    Scheduling contexts

    + +
      +
    • This branch adds scheduling contexts to seL4, which represent +CPU time. Scheduling contexts are separate to threads +(although threads required one to run) and can be passed +around over IPC.
      • +
    • Scheduling contexts allow developers to create periodic +threads, temporally isolation threads and have variable +timeslices for round robin threads.
      • +
    +
    • +
+ +

For more details, please see the manual. Most of the updates are in the +threads chapter.

+ +

API Changes

+ +
    +
  • seL4_TCB_Configure arguments changed (domain removed, scheduling + context cap and max priority added).
    • +
+ +

API Additions

+ +
    +
  • seL4_CapSchedControl - initial cap for control of CPU time
    • +
  • seL4_SchedContextObject - new object for that allows threads + access to CPU time
    • +
  • seL4_SchedContextBits - size in bits of a scheduling context + object
    • +
  • seL4_NBSendRecv - new system call which allows once kernel + invocation to perform a non-blocking send on one capability, and + wait on another.
    • +
  • seL4_NBSendRecvWithMRs - uses above new system call without + touching the IPC buffer, passing only data in registers
    • +
  • seL4_Time - type for specifying temporal units to the kernel
    • +
  • seL4_TCB_SetMaxPriority - set the max priority for a tcb, + threads can only start / set priorities threads up to and + including their max priority
    • +
  • seL4_Prio_t - type for priority and max priority, used in + TCB_Configure
    • +
  • seL4_CNode_SaveTCBCaller - save the reply cap of the target tcb. + This allows another thread to reply on behalf of the owner of the + reply cap.
    • +
  • seL4_SchedControl_Configure - invokes the scheduling control cap + to populate a scheduling context with parameters
    • +
  • seL4_SchedContext_Yield - end the timeslice of the thread bound + to the sched context invoked.
    • +
  • seL4_SchedContext_BindTCB - bind a tcb to a scheduling context, + if the TCB is runnable and scheduling context has budget, this + will start the tcb running
    • +
  • seL4_SchedContext_UnbindTCB - remove binding of a scheduling + context from a tcb, tcb will no longer run but state will be + preserved
    • +
  • seL4_CapInitThreadSC - capability to the initial threads + scheduling context
    • +
  • seL4_CapSchedControl - scheduling control capability, which is + given to the root thread
    • +
  • seL4_SchedContext_BindNotification - Bind a notification to a + scheduling context. Passive threads waiting on this notification + will borrow the scheduling context.
    • +
  • seL4_SchedContext_UnbindNotification - unbind the notification.
    • +
+ +

API deletions

+ +
    +
  • seL4_Yield (replaced by seL4_SchedContext_Yield)
    • +
  • seL4_DomainSet
    • +
  • Domain scheduler removed.
    • +
+ +

Library & test compatability

+ +

The ‘rt’ branch of seL4_libs has been adapted to the rt branch of seL4, +and the rt branch of sel4test has been ported to the seL4_rt-dev-0.0.1 +kernel, along with many more tests written suited to the rt kernel. To +run it, checkout the default.xml manifest on the rt branch of +sel4test-manifest.

+ +

The rt branch is in no way compatible with the master branch of seL4.

+ +

More details See the 0.0.1-rt-dev manual included in the release.

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/1.0.0-rt-dev.html b/releases/sel4/1.0.0-rt-dev.html new file mode 100644 index 00000000000..1c7f360d048 --- /dev/null +++ b/releases/sel4/1.0.0-rt-dev.html @@ -0,0 +1,725 @@ + + + + + + + 1.0.0 Rt Dev | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 1.0.0-rt-dev

+ +

The development branch of the for the seL4 realtime extensions. This +branch is not verified and is under active development.

+ +

Highlights

+ +

Maximum priorities

+ +

Previously seL4 would not allow threads to set any other thread’s +priority to higher than its own. This has been extracted into a separate +field for the RT kernel, a maximum priority, which limits what threads +can set their own or other threads priorities to.

+ +

Criticality & Max Criticality

+ +

Criticality is a new field for threads. The kernel has a system +criticality level which can be set by the user. When the criticality +level is raised, threads with criticality >= the criticality level +have their priorities boosted such that they are chosen by the scheduler +over low criticality threads.

+ +

Scheduling contexts

+ +

This branch adds scheduling contexts to seL4, which represent CPU time +(as budget/period). Scheduling contexts are separate from threads +(although threads require one to run) and can be passed around over IPC, +if the target of an IPC does not have its own scheduling context.

+ +

Scheduling contexts allow developers to create periodic threads, +temporally isolate threads and have variable timeslices for round robin +threads. If budget == period, the scheduling context acts as timeslice.

+ +

IPC & Signal ordering

+ +

Signal and IPC delivery is now priority ordered, instead of FIFO.

+ +

Temporal exceptions

+ +

Threads can register a temporal exception handler that will be called if +a threads budget expires before its period has passed. This is optional.

+ +

For more details, please see the manual. Most of the updates are in the +threads chapter.

+ +

User level scheduling support

+ +

The new API makes it much easier to build high performing user level +schedulers.

+ +

RT API

+ +

This section documents kernel API changes as compared with the current +master of seL4.

+ +

API Changes

+ +
    +
  • seL4_TCB_Configure arguments changed (domain removed, scheduling + context cap, max priority, criticality, max criticality, temporal + exception handler added). Fault endpoints are also now specified + in the caller’s cspace, as they are installed the the TCB cspace + and looked up once rather than every fault.
    • +
  • seL4_TCB_SetSpace temporal exeception handler added.
    • +
+ +

API Additions

+ +
    +
  • seL4_CapSchedControl - initial cap for control of CPU time
    • +
  • seL4_SchedContextObject - new object for that allows threads + access to CPU time
    • +
  • seL4_SchedContextBits - size in bits of a scheduling context + object
    • +
  • seL4_SignalRecv - new system call which allows a single kernel + invocation to perform a non-blocking send on one capability, and + wait on another.
    • +
  • seL4_SignalRecvWithMRs - uses above new system call without + touching the IPC buffer, passing only data in registers
    • +
  • seL4_Time - type for specifying temporal units to the kernel
    • +
  • seL4_TCB_SetMaxPriority - set the max priority for a TCB, + threads can only start / set priorities threads up to and + including their max priority
    • +
  • seL4_TCB_SetCriticality - set the criticality for a TCB.
    • +
  • seL4_TCB_SetMaxCriticality - set the max criticality for a TCB, + threads can only set criticalities of threads threads up to and + including their max criticality
    • +
  • seL4_Prio_t - type for priority and max priority, criticality + and max criticality, used in TCB_Configure
    • +
  • seL4_CNode_SwapCaller - swap the reply cap in the TCB’s reply + slot with the reply cap or null cap in the slot in the + specified slot.
    • +
  • seL4_CNode_SwapTCBCaller - as above, but operates on the reply + cap slot of the target TCB. This allows another thread to reply on + behalf of the owner of the reply cap.
    • +
  • seL4_SchedControl_Configure - invokes the scheduling control cap + to populate a scheduling context with parameters
    • +
  • seL4_SchedContext_Yield - end the timeslice of the thread bound + to the sched context invoked. The thread will not run again until + its period passes.
    • +
  • seL4_SchedContext_YieldTo - If a thread is bound to the + scheduling context that this call is invoked on, place it at the + head of the scheduling queue for that threads priority. Returns + the amount of time the thread yielded to executes.
    • +
  • seL4_SchedContext_Consumed - returns the amount of time this + scheduling context has executed since the last call to this + function or YieldTo.
    • +
  • seL4_SchedContext_BindTCB - bind a TCB to a scheduling context, + if the TCB is runnable and scheduling context has budget, this + will start the TCB running
    • +
  • seL4_SchedContext_UnbindTCB - remove binding of a scheduling + context from a TCB, TCB will no longer run but state will be + preserved
    • +
  • seL4_CapInitThreadSC - capability to the initial threads + scheduling context
    • +
  • seL4_CapSchedControl - scheduling control capability, which is + given to the root thread
    • +
  • seL4_SchedContext_BindNotification - Bind a notification to a + scheduling context. Passive threads waiting on this notification + will borrow the scheduling context.
    • +
  • seL4_SchedContext_UnbindNotification - unbind the notification.
    • +
+ +

API deletions

+ +
    +
  • seL4_Yield (replaced by seL4_SchedContext_Yield)
    • +
  • seL4_DomainSet
    • +
  • Domain scheduler removed.
    • +
  • seL4_CNode_SaveCaller (replaced by seL4_CNode_SwapCaller).
    • +
+ +

Performance improvements

+ +

The RT kernel has various experimental performance improvements +including:

+ +
    +
  • Interrupt fastpath
    • +
  • Signal fastpath (when signals are not delivered immediately - i.e + to a lower prio thread)
    • +
  • Slowpath avoids IPC lookup if message fits in registers
    • +
  • Fault endpoints are looked up when registered and installed in the + TCB’s CNode, saving lookups on each fault.
    • +
+ +

Library & test compatability

+ +

The ‘rt’ branch of seL4_libs has been adapted to the rt branch of seL4, +and the rt branch of sel4test has been ported to the seL4_rt-dev-1.0.0 +kernel, along with many more tests written suited to the rt kernel. To +run it, checkout the default.xml manifest on the rt branch of +sel4test-manifest.

+ +

The rt branch is in no way compatible with the master branch of seL4.

+ +

Hardware support

+ +

The RT kernel currently supports:

+ +
    +
  • Beagle board
    • +
  • Sabre
    • +
  • x86 (only processors that support TSC_DEADLINE mode)
    • +
  • Odroid-XU
    • +
+ +

Other hardware platforms will be added as required (the ports require +updated kernel and user-level timer drivers)

+ +

More details

+ +

See the 1.0.0-rt-dev manual included in the release.

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/10.0.0.html b/releases/sel4/10.0.0.html new file mode 100644 index 00000000000..5b3076b44a0 --- /dev/null +++ b/releases/sel4/10.0.0.html @@ -0,0 +1,589 @@ + + + + + + + 10.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 10.0.0 Release

+

Announcing the release of seL4 10.0.0 with the following changes:

+ +

10.0.0 2018-05-28: BREAKING

+ +
    +
  • Final version of the kernel which supports integration with Kbuild based projects
    • +
  • Future versions, including this one, provide a CMake based build system
    • +
+ +

For more information see Building.

+ +

Changes

+ +
    +
  • x86 IO ports now have an explicit IOPortControl capability to gate their creation. IOPort capabilities may now only +be created through the IOPortControl capability that is passed to the rootserver. Additionally IOPort capabilities +may not be derived to have smaller ranges and the IOPortControl will not issue overlapping IOPorts
    • +
  • 32-bit support added for the initial prototype RISC-V architecture port
    • +
+ +

Upgrade Notes

+ +
    +
  • A rootserver must now create IOPort capabilities from the provided IOPortControl capability. As IOPorts can not +have their ranges further restricted after creation it must create capabilities with the final desired granularity, +remembering that since ranges cannot overlap you cannot issue a larger and smaller range that have any IO ports +in common.
    • +
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 9.0.1..10.0.0

+ +

More details

+

See the +10.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/10.1.0.html b/releases/sel4/10.1.0.html new file mode 100644 index 00000000000..69afe9db9ba --- /dev/null +++ b/releases/sel4/10.1.0.html @@ -0,0 +1,593 @@ + + + + + + + 10.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 10.1.0 Release

+

Announcing the release of seL4 10.1.0 with the following changes:

+ +

10.1.0 2018-11-07: SOURCE COMPATIBLE

+ +

Changes

+ +
    +
  • structures in the boot info are not declared ‘packed’ +
      +
    • these were previously packed (in the GCC attribute sense)
      • +
    • some field lengths are tweaked to avoid padding
      • +
    • this is a source-compatible change
      • +
    +
    • +
  • ARM platforms can now set the trigger of an IRQ Handler capability +
      +
    • seL4_IRQControl_GetTrigger allows users to obtain an IRQ Handler capability +and set the trigger (edge or level) in the interrupt controller.
      • +
    +
    • +
  • Initial support for NVIDIA Jetson TX2 (ARMv8a, Cortex A57)
    • +
  • AARCH64 support added for raspberry pi 3 platform.
    • +
  • Code generation now use jinja2 instead of tempita.
    • +
  • AARCH32 HYP support added for running multiple ARM VMs
    • +
  • AARCH32 HYP VCPU registers updated.
    • +
  • A new invocation for setting TLSBase on all platforms. +
      +
    • seL4_TCB_SetTLSBase
      • +
    +
    • +
  • Kbuild/Kconfig/Makefile build system removed.
    • +
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 10.0.0..10.1.0

+ +

More details

+

See the +10.1.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/10.1.1-mcs.html b/releases/sel4/10.1.1-mcs.html new file mode 100644 index 00000000000..f8fc8d98b58 --- /dev/null +++ b/releases/sel4/10.1.1-mcs.html @@ -0,0 +1,783 @@ + + + + + + + 10.1.1 Mcs | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 MCS pre-release (10.1.1-mcs)

+ +

This is a pre-release of the seL4 mixed-criticality systems (MCS) +extensions. This branch is not verified and is under active +verification.

+ +

Highlights

+ +

The goals of the MCS kernel is to provide strong temporal isolation and +a basis for reasoning about time.

+ +

IPC & Signal ordering

+ +

Signal and IPC delivery is now priority ordered and FIFO within a +priority, rather than plain FIFO

+ +

Scheduling contexts

+ +

This branch adds scheduling contexts to seL4, which represent CPU time +(as budget/period). Scheduling contexts are separate from threads +(although threads require one to run) and can be passed around over IPC, +if the target of an IPC does not have its own scheduling context.

+ +

Scheduling contexts allow developers to create periodic threads, +temporally isolate threads and have variable timeslices for round robin +threads. If budget == period, the scheduling context acts as timeslice +and the thread it is bound to is treated as round-robin.

+ +

Periodic scheduling

+ +

Periodic threads can be created by binding them to scheduling contexts +with a budget < period. seL4_Yield for these threads will sacrifice +the remaining budget until the next period.

+ +

Isolation through sporadic servers

+ +

Temporal isolation is provided with scheduling context by an +implementation of +sporadic servers. Please see the manual or tutorial for further +explanation.

+ +

However, in seL4, threads without budget left in their sporadic server +are not runnable at all - this is used to provide an absolute cap on CPU +time executed by a scheduling context. More complex scheduling +algorithms can be implemented at user-level.

+ +

Scheduling contexts are of a variable size, allowing for a variable +maximum number of sporadic replenishment (termed refills in the API for +brevity) pre scheduling context object.

+ +

Passive Servers

+ +

Passive servers run on their clients scheduling context, as the do not +have one of their own. This allows for basic temporal isolation of +shared resources, however clients must provide enough budget for the +server to finish the request. Futher extensions in future add timeout +exceptions, which allows a passive server to detect and recover from an +overrun, however they are not included in this release.

+ +

Threads can be converted to passive by removing their scheduling context +while they are waiting on an endpoint. Then, any calling threads will +automatically donate their scheduling context to this thread when they +send it an IPC.

+ +

Reply objects

+ +

Reply objects are a new object in the API which serve two purposes:

+ +
    +
  • They provide a container for the once-off reply capability + generated by a seL4_Call to be stored. This means that the reply + cap is always saved and cannot be overriden as it is no longer + stored in the internal CNode of a TCB, and seL4_CNode_SaveCaller + no longer needs to be used.
    • +
  • They track scheduling context donation over IPC to + passive servers.
    • +
+ +

MCS ABI and libsel4

+ +

This section documents kernel ABI and libsel4 changes as compared with +seL4 10.1.1.

+ +

Changes

+ +
    +
  • seL4_TCB_Configure arguments changed (fault ep removed)
    • +
  • seL4_TCB_SetSchedParams also sets scheduling context, and fault endpoint. The fault endpoint is +a capability in the current thread’s cspace, unlike on the master kernel, where it is in the +target thread’s cspace.
    • +
  • seL4_Recv, seL4_ReplyRecv, seL4_NBRecv now take a reply object + such that the caller can receive a call. The reply capability is + generated in the reply object, rather than being saved into the + TCB CNode internally. seL4_Call must be paired with seL4_Recv - + and seL4_CNode_SaveCaller is no longer required.
    • +
  • seL4_Wait, seL4_NBWait and variants do not require a reply + object and can be paired with seL4_Send on endpoints + and notifications. Instead of being an API wrapper, this is now a + real system call.
    • +
  • the x86 kernel ABI now only has 1 message register, due to the + need to store the reply object.
    • +
  • seL4_MsgMaxLength is now 119, as a reserved word is needed in the IPC buffer on 32-bit x86.
    • +
  • seL4_NotificationBits - increased.
    • +
+ +

API Additions

+ +

Constants

+ +
    +
  • seL4_SchedContextObject - new object for that allows threads + access to CPU time
    • +
  • seL4_MinSchedContextBits - minimum size n (2\^n) of a scheduling + context object
    • +
  • seL4_CoreSchedContextBytes - the amount of bytes required for the + fields in a scheduling context that are not sporadic refills.
    • +
  • seL4_RefillSizeBytes - the size of a single refill. Together with + the above, these can be used to determine the number of refills + that will fit in a scheduling context object of a certain size.
    • +
  • seL4_ReplyObject - new object to track scheduling context + donation over IPC and store reply capabilities.
    • +
  • seL4_ReplyObjectBits - size of a reply object (2\^n).
    • +
  • seL4_CapInitThreadSC - capability to the initial threads + scheduling context
    • +
+ +

System calls

+ +
    +
  • seL4_NBSendRecv - new system call which allows a single kernel + invocation to perform a non-blocking send on one capability, and + recieve on another.
    • +
  • seL4_NBSendRecvWithMRs - uses above new system call without + touching the IPC buffer, passing only data in registers
    • +
  • seL4_NBSendWait - new system call which allows a single kernel + invocation to perform a non-blocking send on one capability, and + wait on another (no reply object).
    • +
  • seL4_NBSendWaitWithMRs - uses above new system call without + touching the IPC buffer, passing only data in registers
    • +
  • seL4_SchedControl_Configure - invokes the scheduling control cap + to populate a scheduling context with parameters
    • +
  • seL4_SchedContext_Bind - bind a TCB to a scheduling context, if + the TCB is runnable and scheduling context has budget, this will + start the TCB running
    • +
  • seL4_SchedContext_Unbind - remove binding of a scheduling + context from a TCB, TCB will no longer run but state will be + preserved
    • +
  • seL4_SchedContext_Unbind Object - remove binding of a scheduling + context from a TCB, TCB will no longer run but state will be + preserved
    • +
  • seL4_Wait - block on an endpoint or notification without + providing a reply object. Can be paired with seL4_Send but + not seL4_Call.
    • +
  • seL4_NBWait - a non-blocking variant of the above.
    • +
  • seL4_WaitWithMRs - a variant of seL4_Wait that does not touch + the IPC buffer.
    • +
+ +

Invocations

+ +
    +
  • seL4_TCBSetTimeoutEndpoint - new TCB invocation which allows a timeout endpoint to be set for a +TCB.
    • +
  • seL4_SchedControl_Configure - allows scheduling context parameters to be set.
    • +
  • seL4_SchedContext_Bind - Allows a notification or TCB object to be bound to a scheduling context +object.
    • +
  • seL4_SchedContext_Unbind - Unbind any object bound to a scheduling context.
    • +
  • seL4_SchedContext_UnbindObject - Unbind a specific object from a scheduling context.
    • +
  • seL4_SchedContext_Consumed - Read and reset the amount of time consumed from scheduling +context.
    • +
  • seL4_SchedContext_YieldTo - Place the active thread bound to this scheduling context at the head +of the scheduling queue for its priority. Read and reset the amount of time consumed.
    • +
+ +

libsel4

+ +
    +
  • seL4_SetReserved, seL4_GetReserved: set a reserved word in + the IPC buffer that may be used by the kernel ABI for arguments + that do not fit into registers.
    • +
  • seL4_MaxExtraRefills is provided to allow users to calculate the + maximum number of extra refills for a specific scheduling + context size.
    • +
  • seL4_Time: type for specifying time arguments.
    • +
  • seL4_isTimeoutFault_tag: detect a timeout fault message.
    • +
  • seL4_TimeoutReply_new: construct a reply to a timeout fault message.
    • +
+ +

Structures

+ +
    +
  • A sched control capability per core is provided to the root task per node + via the seL4_BootInfo structure.
    • +
+ +

Deletions

+ +
    +
  • seL4_CNode_SaveCaller (deprecated by reply objects)
    • +
  • seL4_Reply (replaced by invoking a reply object)
    • +
  • seL4_ReplyWithMRs (as above)
    • +
+ +

Library & test compatability

+ +

Please contact us if you need compatible libraries for the MCS kernel for a specific version.

+ + + +

Hardware support

+ +

The MCS kernel currently supports:

+ + + +

Other hardware platforms will be added as required (the ports require +updated kernel and user-level timer drivers)

+ +

More details

+ +

See the 10.1.1-mcs manual included in the release.

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/10.1.1.html b/releases/sel4/10.1.1.html new file mode 100644 index 00000000000..4d932d780db --- /dev/null +++ b/releases/sel4/10.1.1.html @@ -0,0 +1,574 @@ + + + + + + + 10.1.1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 10.1.1 Release

+

Announcing the release of seL4 10.1.1 with the following changes:

+ +

10.1.1 2018-11-12: BINARY COMPATIBLE

+ +

Changes

+
    +
  • Remove theoretical uninitialised variable use in infer_cpu_gic_id for binary translation validation
    • +
+ +

Upgrade Notes

+
    +
  • 10.1.0 has a known broken test in the proofs. 10.1.1 fixes this test.
    • +
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 10.1.0..10.1.1

+ +

More details

+

See the +10.1.1 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/11.0.0.html b/releases/sel4/11.0.0.html new file mode 100644 index 00000000000..da9916f49d2 --- /dev/null +++ b/releases/sel4/11.0.0.html @@ -0,0 +1,685 @@ + + + + + + + 11.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 11.0.0 Release

+

Announcing the release of seL4 11.0.0 with the following changes:

+ +

11.0.0 2019-11-19: BREAKING

+ +

Changes

+ +
    +
  • Add GrantReply access right for endpoint capabilities.
    • +
  • seL4_Call is permitted on endpoints with either the Grant or the GrantReply access rights.
    • +
  • Capabilities can only be transferred in a reply message if receiver’s endpoint capability has the Grant right.
    • +
  • seL4_CapRights_new now takes 4 parameters
    • +
  • seL4_CapRightsBits added to libsel4. seL4_CapRightsBits is the number of bits + to encode seL4_CapRights.
    • +
  • seL4_UserTop added +
      +
    • a new constant in libsel4 that contains the first virtual address unavailable to +user level.
      • +
    +
    • +
  • Add Kernel log buffer to aarch64
    • +
  • Support added for Aarch64 hypervisor mode (EL2) for Nvidia TX1 and TX2. This is not verified.
    • +
  • Support for generating ARM machine header files (memory regions and interrupts) based on a device tree.
    • +
  • Support added for ARM kernel serial driver to be linked in at build time based on the device tree compatibility string.
    • +
  • Support added for compiling verified configurations of the kernel with Clang 7.
    • +
  • RISC-V: handle all faults +
      +
    • Pass all non-VM faults as user exceptions.
      • +
    +
    • +
  • arm-hyp: pass ESR in handleUserLevelFault
    • +
  • aarch64: return ESR as part of user level fault
    • +
  • Created new seL4_nbASIDPoolsBits constant to keep track of max nb of ASID pools.
    • +
  • Support added for Hardkernel ODROID-C2.
    • +
  • Added extended bootinfo header for device tree (SEL4_BOOTINFO_HEADER_FDT).
    • +
  • Support added for passing a device tree from the bootloader to the root task on ARM.
    • +
  • Add seL4_VSpaceBits, the size of the top level page table.
    • +
  • The root cnode size is now a minimum of 4K.
    • +
  • Hifive board support and RISC-V external interrupt support via a PLIC driver.
    • +
  • Update seL4_FaultType size to 4bits.
    • +
  • Fix seL4_MappingFailedLookupLevel() for EPTs on x86. +
      +
    • add SEL4MAPING_LOOKUP_NO[EPTPDPT, EPTPD, EPTPT] which now correspond to +the value returned by seL4_MappingFailedLookupLevel on X86 EPT mapping calls.
      • +
    +
    • +
  • BeagleBone Black renamed from am335x to am335x-boneblack.
    • +
  • Supported added for BeagleBone Blue (am335x-boneblue).
    • +
  • Remove IPC Buffer register in user space on all platforms
    • +
  • Add managed TLS register for all platforms
    • +
  • Add configurable system call allowing userspace to set TLS register without capability on all platforms.
    • +
  • Non-hyp support added for Arm GICv3 interrupt controller.
    • +
  • Add initial support for i.MX8M boards. +
      +
    • Support for i.MX8M Quad evk AArch64 EL2 and EL1, AArch32 smode only is accessible via the imx8mq-evk platform.
      • +
    • Support for i.MX8M Mini evk AArch64 EL2 and EL1, AArch32 smode only is accessible via the imx8mm-evk platform.
      • +
    +
    • +
  • Add FVP platform with fixed configuration. This currently assumes A57 configuration described in tools/dts/fvp.dts.
    • +
  • Arm SMP invocation IRQControl_GetTriggerCore added +
      +
    • Used to route a specify which core an IRQ should be delivered on.
      • +
    +
    • +
  • Kernel log buffer: Specify on which core an IRQ was delivered.
    • +
  • Add new seL4_DebugSendIPI syscall to send arbitrary SGIs on ARM when SMP and DEBUG_BUILD are activated.
    • +
  • Support for aarch64-hyp configurations with 40-bit physical addresses (PA) added. +
      +
    • The aarch64 api now refers to VSpaces rather than PageGlobalDirectories, +as depending on the PA the top level translation structure can change.
      • +
    • all seL4_ARM_PageGlobalDirectory invocations are now seL4_ARM_VSpace invocations.
      • +
    • new constants seL4_ARM_VSpaceObject and seL4_VSpaceIndexBits.
      • +
    +
    • +
  • Merged MCS kernel feature. +
      +
    • this is not verified and is under active verification.
      • +
    • The goals of the MCS kernel is to provide strong temporal isolation and a basis for reasoning about time.
      • +
    +
    • +
  • Moved aarch64 kernel window +
      +
    • aarch64 kernel window is now placed at 0, meaning the kernel can access memory +below where the kernel image is mapped.
      • +
    +
    • +
  • aarch64: Moved TPIDRRO_EL0 (EL0 Read-Only Thread ID register) to TCB register context from VCPU registers. This means +changes to this register from user level have to go via seL4_TCB_Write Registers instead of seL4_ARM_VCPU_WriteRegs.
    • +
  • Merge ARCH_Page_Remap functionality into ARCH_Page_Map. Remap was used for updating the mapping attributes of a page +without changing its virtual address. Now ARCH_Page_Map can be performed on an existing mapping to achieve the same +result. The ARCH_Page_Remap invocation has been removed from all configurations.
    • +
  • riscv64: Experimental SMP support for RISCV64 on HiFive.
    • +
  • Support added for QEMU ARM virt platform, with 3 CPUs: cortex-a15, cortex-a53 and cortex-a57 +
      +
    • PLATFORM=qemu-arm-virt
      • +
    • ARM_CPU={cortex-a15, cortex-a53, cortex-a57}
      • +
    • QEMU_MEMORY=1024 (default)
      • +
    +
    • +
  • Support added for rockpro64.
    • +
  • RISCV: Add support for Ariane SoC
    • +
  • Unify device untyped initialisation across x86, Arm and RISC-V +
      +
    • Access to the entire physical address range is made available via untypes.
      • +
    • The kernel reserves regions that user level is not able to access and doesn’t hand out untypeds for it.
      • +
    • Ram memory is part of this reservation and is instead handed out as regular Untypeds.
      • +
    • Memory reserved for use by the kernel or other reserved regions are not accessible via any untypeds.
      • +
    • Devices used by the kernel are also not accessible via any untypeds.
      • +
    +
    • +
+ +

Upgrade Notes

+ +
    +
  • Usages of Endpoints can now use seL4_Call without providing Grant rights by downgrading the Grant to GrantReply
    • +
  • The kernel no longer reserves a register for holding the address of a thread’s IPC buffer. It is now expected that the +location of the IPC buffer is stored in a __thread local variable and a thread register is used to refer to each +thread’s thread local variables. The sel4runtime is an seL4 runtime that provides program entry points that setup +the IPC buffer address and serves as a reference for how the IPC buffer is expected to be accessed.
    • +
  • All seL4_ARM_PageGlobalDirectory invocations need to be replaced with seL4_ARM_VSpace.
    • +
  • Usages of ARCH_Page_Remap can be replaced with ARCH_Page_Map and require the original mapping address to be provided.
    • +
  • Device untypeds are provided to user level in different sizes which may require more initial processing to break them +down for each device they refer to.
    • +
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 10.1.1..11.0.0

+ +

More details

+

See the +11.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/12.0.0.html b/releases/sel4/12.0.0.html new file mode 100644 index 00000000000..a7f8112e071 --- /dev/null +++ b/releases/sel4/12.0.0.html @@ -0,0 +1,837 @@ + + + + + + + 12.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 12.0.0 Release

+

Announcing the release of seL4 12.0.0 with the following changes:

+ +

12.0.0 2020-10-21: BREAKING

+ +

Changes

+ +
    +
  • Update licensing to reflect project transfer to seL4 Foundation. SPDX tags are now used to identify the licenses for +each file in the project. Generally, kernel-level code is licensed under GPLv2 and user-level code under the 2-clause +BSD license.
    • +
  • Update contribution guidelines: +
      +
    • the seL4 foundation requires DCO process instead of a CLA
      • +
    +
    • +
  • Functional correctness verification for the RISC-V 64-bit HiFive Unleashed platform configuration +(RISCV64_verified.cmake with no fastpath or FPU enabled)
    • +
  • Update caveats file: +
      +
    • The recycle operation has been removed
      • +
    • More detail on what versions are verified
      • +
    • Update comments on real time use of seL4
      • +
    +
    • +
  • Improve seL4 manual. +
      +
    • Fix aarch64 seL4_ARM_PageDirectory object API docs: +seL4_ARM_PageDirectory_Map is passed a vspace cap not an upper page directory cap.
      • +
    • Increase documentation coverage for Arm object invocations
      • +
    • Rework introduction of system calls in Kernel Services and Objects chapter.
      • +
    • Improve discussion of Receive and Wait syscall behaviour between MCS and non-MCS systems.
      • +
    • Explicitly mention grantreply rights in the exceptions section.
      • +
    • Document schedcontext size_bits meaning.
      • +
    • Remove metion of system criticality.
      • +
    • Add SchedContext to object size discussion.
      • +
    • Fix initial thread’s CNode guard size.
      • +
    • Update BootInfo struct table.
      • +
    • Update padding field in UntypedDesc table
      • +
    +
    • +
  • Update seL4_DebugSnapshot to provide a CapDL dump of the capability layout of +a running system for Arm, x86_64 and riscv32 configurations.
    • +
  • KernelBenchmarksTrackUtilisation: +
      +
    • Add feature support for SMP configurations
      • +
    • For each thread also track number of times scheduled, number of kernel entries and amount of cycles spent inside the +kernel and also add core-wide totals for each.
      • +
    +
    • +
  • Add 2 new benchmark utilization syscalls +
      +
    • seL4_BenchmarkDumpAllThreadsUtilisation: Prints a JSON formatted record of total and per-thread utilisation +statistics about the system. This currently includes a thread’s total cycles scheduled, total number of times +scheduled, total cycles spent in the kernel and total number of times entering the kernel and then totals of each +for all threads on the current core.
      • +
    • seL4_BenchmarkResetAllThreadsUtilisation: Resets the current counts of every user thread on the current core.
      • +
    +
    • +
  • Added seL4_DebugPutString libsel4 function for printing a null-terminated string via calling seL4_DebugPutChar().
    • +
  • Introduced a new config flag, KernelInvocationReportErrorIPC, to enable userError format strings to be written to +the IPC buffer. Another config bool has been introduced to toggle printing the error out and this can also be set at +runtime. LibSel4PrintInvocationErrors is a libsel4 config used to print any kernel error messages reported in the IPC +buffer.
    • +
  • Repair barriers in clh_lock_acquire (SMP kernel lock). Strengthen the clh_lock_acquire to use release on the +atomic_exchange that makes the node public. Otherwise, (on ARM & RISCV) the store to the node value which sets its +state to CLHState_Pending can become visible some time after the node is visible. In that window of time, the next +thread which attempts to acquire the lock will still see the old state (CLHState_Granted) and enters the critical +section, leading to a mutual exclusion violation.
    • +
  • Replace all #ifdef header guards with #pragma once directives in libsel4 header files
    • +
  • gcc.cmake: +
      +
    • Add option for coloured gcc output. Setting GCC_COLORS in the environment will result in -fdiagnostics-color=always +being provided to gcc. Ordinarily gcc would suppress coloured output when ninja redirects its stderr during normal +builds.
      • +
    • Remember CROSS_COMPILER_PREFIX across CMake invocations. The variable would become unset in certain contexts.
      • +
    • Add support for Arm cross-compilers on Red Hat distros.
      • +
    +
    • +
  • Fastpath optimisation: +
      +
    • Reorganise the code layout on Arm.
      • +
    • bitfield_gen: explicit branch predictions.
      • +
    • Optimize instruction cache access for fastpath.
      • +
    +
    • +
  • Extend Clang support to all kernel configurations. Support targets LLVM versions between 9 and 11.
    • +
  • hardware_gen.py: Add elfloader output target for hardware_gen script. This generates header files describing the +platform’s CPU configuration as well as device information such as compatibility strings and memory regions to the +elfloader that are consistent with the kernel’s own definitions.
    • +
  • Fix bootinfo allocation bug when user image pushed against page directory boundary. The bootinfo is mapped in at the +end of the user image in the initial thread’s vspace. The kernel initialisation code wasn’t calculating the +bootinfo size correctly which could lead to a kernel fault when trying to map the bootinfo in when the parent page +table object hadn’t been allocated.
    • +
  • Use autoconf definition for RetypeMaxObjects in <sel4/types.h>. This ensures that the definition stays consistent +with what the kernel is configured with.
    • +
  • Fix up timers and clock frequencies +
      +
    • Remove beaglebone kernel timer prescaling. Previously the timer frequency was incorrectly set to to half (12MHz) its +configured frequency (24MHz).
      • +
    • Set TX1 kernel timer frequency config to 12MHz and not 19.2MHz as this is the standard frequency of the input clock +source (m_clock).
      • +
    • Set KZM kernel timer frequency config to 35MHz and not 18.6MHz based on sampling the timer frequency.
      • +
    • imx31: add missing dts entry for the epit2 timer.
      • +
    • Set non-mcs i.MX6 kernel timer frequency config to 498MHz and not 400MHz as this is based on the frequency of the +input clock source (PLL1)
      • +
    • Zynq7000: Set kernel timer frequency to 320MHz.
      • +
    • Qemu-arm-virt: Set kernel timer frequency to 6.25MHz.
      • +
    +
    • +
  • Do not generate data symbols for enums in libsel4 as they end up as bss symbols and cause linker errors on newer +compiler versions.
    • +
  • Update padding field definition in seL4_UntypedDesc to make the struct word aligned. Previously, this struct wasn’t +correctly word aligned on 64-bit platforms. This change removes the padding1 and padding2 fields and replaces them +with a padding field that is a variable number of bytes depending on the platform.
    • +
  • Add GitHub actions scripts. These scripts replicate internal CI checks directly on GitHub
    • +
+ +

MCS

+ +
    +
  • Stop scheduling contexts from being bound to tcb’s that already have scheduling contexts.
    • +
  • Fix x86 KERNEL_TIMER_IRQ definition. Previously, MCS preemption point handling would check the wrong interrupt on +x86 platforms.
    • +
  • smp: tcb affinity modification bug. When changing the affinity of a thread on a remote core, the reschedule +operation wasn’t being performed.
    • +
  • Allow replyGrant for fault handlers. The MCS kernel so far insisted on full grant rights for fault handler caps, +but replyGrant is sufficient and consistent with the default kernel config.
    • +
  • All scheduling contexts compare their time with time in assigned core instead of currently executing core.
    • +
  • Prevent recursion on timeout faults by suspending a passive server that receives a timeout fault.
    • +
  • Add KernelStaticMaxBudgetUs to bound the time the user provides to configure scheduling contexts to avoid malicious +or erroneous overflows of the scheduling math. Make the default max period/budget 1 hour.
    • +
  • rockpro64: enable mcs configurations
    • +
+ +

Arm

+ +
    +
  • arm: Add seL4_BenchmarkFlushL1Caches syscall to manually flush L1 caches in benchmark configurations.
    • +
  • New fault type when running in Arm hypervisor mode: seL4_Fault_VPPIEvent +
      +
    • The kernel can keep track of IRQ state for each VCPU for a reduced set of PPI IRQs and deliver IRQ events as +VCPU faults for these interrupt numbers.
      • +
    • Additionally a new VCPU invocation is introduced: seL4_ARM_VCPU_AckVPPI. +This is used to acknowledge a virtual PPI that was delivered as a fault.
      • +
    +
    • +
  • Virtualise Arm Timer and VTimer interrupts to support sharing across VCPUs. +
      +
    • A VCPU will now save and restore VTimer registers for the generic timer and also deliver a VTimer IRQ via a +seL4_Fault_VPPIEvent fault. This enables multiple VCPUs bound to the same physical core to share this device.
      • +
    +
    • +
  • Build config option for whether WFE/WFI traps on VCPUs when running in Arm hypervisor mode
    • +
  • Arm: Add VMPIDR and VMPIDR_EL2 registers to VCPU objects for programming a VCPU’s ‘Virtualization Multiprocessor +ID Register’ on aarch32 and aarch64.
    • +
  • Arm, vcpu, smp: Remote IPI call support for VIRQS. Injecting a VIRQ into a vcpu running on a different core will +IPI the remote core to perform the IRQ injection.
    • +
  • zynqmp: Disable hardware debug APIs as the platform doesn’t support kernel hardware debug API.
    • +
  • zynqmp: Add support for aarch32 hyp
    • +
  • Gicv3: include cluster id when sending ipis.
    • +
  • qemu-arm-virt: +
      +
    • Generate platform dtb based on KernelMaxNumNodes config value.
      • +
    • Reserve the first 512MiB of Ram as device untyped for use in virtualization configurations.
      • +
    +
    • +
+ +

Aarch32

+ +
    +
  • Moved TPIDRURO (PL0 Read-Only Thread ID register) to TCB register context from VCPU registers. This means +changes to this register from user level have to go via seL4_TCB_Write Registers instead of seL4_ARM_VCPU_WriteRegs.
    • +
  • aarch32: Restrict cache flush operation address range in hyp mode. It’s required that cache flushing in hyp mode +is performed through the kernel window mapping as the kernel is unable to flush addresses outside of this mapping +without causing an access fault.
    • +
  • arm_hyp: Move PGD definitions out of libsel4 as they don’t correspond to any public interfaces and are only used +internally by the kernel to manage its own address space.
    • +
+ +

Aarch64

+ +
    +
  • aarch64: Fix a bug where saving ELR_EL1 when managing a VCPU object was reading from ELR_EL1 instead of writing to it.
    • +
  • aarch64: Fix a bug where saving FAR_EL1 when managing a VCPU object was only writing to the low 32 bits of the 64-bit +FAR_EL1 register.
    • +
  • aarch64: Add missing faults to seL4_getArchFault. seL4_getArchFault is a libsel4 helper that constructs fault messages +out of the IPC buffer message registers but it wasn’t aware of all possible fault types.
    • +
  • aarch64,vcpu: Add CNTKCTL_EL1 register to vcpu_t. This register tracks timer delegation to EL0 from EL1 and +needs to be switched for different VCPUs.
    • +
  • aarch64: Adds missing vcpu cases for some aarch64-specific functions on capabilities.
    • +
  • cortex-a53,hyp: Reduce seL4_UserTop when on a cortex-a53 platform and KernelArmHypervisorSupport is set. +
      +
    • This is because the kernel uses the last slot in the top level VSpace object for storing the assigned VMID and so +any addresses that are addressed by the final slot are not accessible. This would apply to any CPU that have 40bit +stage 2 translation input address.
      • +
    +
    • +
  • Arm SMMUv2 kernel API and TX2 smmuv2 driver. This supports using an SMMU to provide address translation and memory +protection for device memory access to platforms that implement a compatible Arm SMMUv2 System mmu. The kernel +implementation supports using an SMMU to restrict memory access of VM guest pass-through devices, or for isolating +devices and their drivers’ memory accesses to the rest of a running system.
    • +
+ +

x86

+ +
    +
  • Fix printf typo in apic_init.
    • +
  • x86_64: Fix PCID feature constant to use the correct bit.
    • +
  • Fix interrupt flag reset upon nested interrupt resume, c_nested_interrupt. This fixes an issue where ia32 kernels +would crash if receiving a nested interrupt.
    • +
+ +

RISC-V

+ +
    +
  • Functional correctness of seL4/RISCV now formally verified at the C level.
    • +
  • Hifive: Enable seL4_IRQControl_GetTrigger object method. This method allocates an IRQ handler by ID and whether it is +level or edge triggered. Note: HiFive PLIC interrupts are all positive-level triggered.
    • +
  • Add search for additonal gcc riscv toolchains if the first one cannot be found.
    • +
  • Add support for rocketchip soc. Support Rocketchip SoC maps to Xilinx ZC706 board and ZCU102 board
    • +
  • Add support for polarfire soc.
    • +
  • Clear reservation state on slowpath exit as the RISC-V ISA manual requires supervisor code to execute a dummy sc +instruction to clear reservations “during a preemptive context switch”.
    • +
  • Pass DTB through to userlevel in extra bootinfo fields similar to on Arm.
    • +
  • Use full width of scause to prevent large exception numbers to be misinterpreted as syscalls.
    • +
  • Fix page map bug. +
      +
    • Previously, it was possible in decodeRISCVFrameInvocation for the rwx rights of the new PTE to become 000 after +masking with cap rights. This would turn the frame PTE into a page table PTE instead, and allow the user to create +almost arbitrary mappings, including to kernel data and code. The defect was discovered in the C verification of the +RISC-V port.
      • +
    +
    • +
  • Remove seL4_UserException_FLAGS. This field was unused and was never set to anything by the kernel.
    • +
  • Add FPU config options for RISCV +
      +
    • Two options, KernelRiscvExtD and KernelRiscvExtF, are added to represent the D and F floating-point extensions. +KernelHaveFPU is enabled when the floating-point extensions are enabled. The compiler ABI will also be changed to +lp64d for hardfloat builds.
      • +
    +
    • +
  • Add RISCV64_MCS_verified.cmake config for in-progress MCS verification
    • +
  • riscv32: Remove incorrectly provided constants for 512MiB ‘huge pages’ which is not part of the specification.
    • +
  • riscv: Lower .boot alignment to 4KiB. This makes the final kernel image more compact.
    • +
+ +

Upgrade Notes

+ +
    +
  • The project’s licensing updates don’t change the general licensing availability of the sources. +More information can be found: https://github.com/seL4/seL4/blob/master/LICENSE.md
    • +
  • Any references to the padding1 or padding2 fields in seL4_UntypedDesc require updating to +the new padding field. It is expected that these fields are unused.
    • +
  • Any platforms that have had changed kernel timer frequencies will see different scheduling +behavior as kernel timer ticks will occur at different times as kernel ticks are configured +in microseconds but then converted to timer ticks via the timer frequency. Any time-sensitive +programs may need to be re-calibrated.
    • +
  • Any riscv32 programs that were using the constants RISCVGigaPageBits or seL4_HugePageBits will +see a compilation error as the constants have been deleted as they aren’t supported in the riscv32 spec.
    • +
  • Any riscv programs that refer to the seL4_UserException_FLAGS field will need to remove this reference. This field was +never initialised by the kernel previously and has now been removed.
    • +
  • Any riscv programs using the LR/SC atomics instructions will see reservations invalidated after kernel entries. It is +expected that this will not require any changes as reservations becoming invalid is normal behavior.
    • +
  • On cortex-a53 platforms when KernelArmHypervisorSupport is set have 1 less GiB of virtual memory addresses available +or 2GiB less on TX2 with the SMMU feature enabled. This is captured by the change in definition of the seL4_UserTop +constant that holds the larges virtual address accessible by user level.
    • +
  • On aarch32 the TPIDRURO register(PL0 Read-Only Thread ID register) has been removed from the VCPU object and added to +the TCB object. A VCPU is typically bound to a TCB so after updating the access, a thread with a VCPU attached will +still support having a TPIDRURO managed.
    • +
  • On Arm hypervisor configurations, PPI virtual timer interrupts are now delivered via seL4_Fault_VPPIEvent faults and +it is not possible to allocate an interrupt handler for these interrupts using the normal interrupt APIs. A VPPI +interrupt is received via receiving a fault message on a VCPU fault handler, and acknowledged by an invocation on +the VCPU object. VPPI interrupts that target a particular VCPU can only be generated while the VCPU thread is +executing.
    • +
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 11.0.0..12.0.0

+ +

More details

+

See the +12.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/12.1.0.html b/releases/sel4/12.1.0.html new file mode 100644 index 00000000000..5826cc2f71b --- /dev/null +++ b/releases/sel4/12.1.0.html @@ -0,0 +1,713 @@ + + + + + + + 12.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 12.1.0 Release

+

Announcing the release of seL4 12.1.0 with the following changes:

+ +

12.1.0 2021-06-10: SOURCE COMPATIBLE

+ +

Changes

+ +
    +
  • Moved kernel configuration header to libsel4.
    • +
  • Improved benchmarking: +
      +
    • Made the kernel log buffer to be derived from cmake config.
      • +
    • Added x86_64 kernel log buffer.
      • +
    • Implemented RISC-V benchmark timestamping.
      • +
    • Implemented benchmark log buffer for RISC-V.
      • +
    +
    • +
  • Moved cap functions out of inline to make changing cap bitfields less noisy.
    • +
  • Removed weak definition of the __sel4_ipc_buffer variable which was causing large thread local storages to be +required.
    • +
  • Prepared the bitfield generator for Isabelle 2021.
    • +
  • Made a number of improvements to the CMake build scripts.
    • +
  • Added pre-processor ‘include guards’ for auto-generated files.
    • +
  • Added missing CONFIG_PLAT_IMX7 pre-processor ‘#define’s.
    • +
  • Added #pragma once to the autoconf headers.
    • +
  • Removed HAVE_AUTOCONF guards in sel4/config.h.
    • +
  • Improved the manual: +
      +
    • Corrected descriptions of CNode addressing.
      • +
    • Documented initial thread’s SMMU caps.
      • +
    +
    • +
  • Improved libsel4: +
      +
    • Removed redundant HAVE_AUTOCONF header guards in libsel4.
      • +
    • Added missing macros.h #include in libsel4.
      • +
    • Cleaned-up macros.h in libsel4.
      • +
    • Added checks to use _Static_assert() in libsel4 if it is available.
      • +
    • Unified definitions in simple_types.h in libsel4.
      • +
    • Added printf format specifier PRI_sel4_word for printing word types.
      • +
    • Unified seL4 type definitions.
      • +
    +
    • +
  • Added specific printf formatting for seL4_Word.
    • +
  • Changed some variables to use BOOT_BSS instead of BOOT_DATA to save space in the ELF file.
    • +
  • Replaced the capDL() function with a generic debug_capDL function that is intended to be implemented by all +architectures.
    • +
  • Reduced printfs stack usage.
    • +
  • Fixed ksnprintf() corner case handling.
    • +
  • Fixed NULL printf output wrapper handling.
    • +
  • Cleaned up the printing API implementation.
    • +
  • Changed code to pass buffer to printf output channel.
    • +
  • Refactored the kernel console handling.
    • +
  • Added support for PRIu64 and SEL4_PRIu_word in the kernel.
    • +
  • Changed various printf conversion specifiers to use SEL4_PRIx_word specifiers.
    • +
+ +

MCS

+ +
    +
  • Fixed a physical counter access issue on MCS on EL2.
    • +
  • Added MCS support for the ZynqMP.
    • +
  • Changed invokeSchedControl_Configure to always produce a scheduling context that is active and has configured +refills.
    • +
  • Prevented the binding of scheduling contexts to blocked TCBs.
    • +
  • Fixed conversions of ticks to microseconds on aarch64.
    • +
  • Added an additional sporadic flag to seL4_SchedControl_Configure which allows the option to create a sporadic +scheduling context.
    • +
  • Added explicit checks to not unblock the current scheduling context.
    • +
  • Fixed MCS and aarch64 VCPU interrupt interaction.
    • +
  • Renamed MCS kernel configuration option KernelStaticMaxBudgetUs to KernelStaticMaxPeriodUs.
    • +
  • Added check to make sure that the current thread will not yield to multiple threads.
    • +
  • Added check to account for an inactive scheduling context at preemption.
    • +
  • Deferred charging time budget in a preempted invocation.
    • +
  • Added code to update ksDomainTime in updateTimestamp.
    • +
  • Added call to updateTimestamp in a preemption point.
    • +
  • Added code to clear ksConsume when charging time to a revoked scheduling context.
    • +
  • Added code to cancel IPC when finalising reply caps.
    • +
  • Fixed a dereference of a scheduling context after it’s removed from the associated TCB.
    • +
  • Added MCS to the preprocess check.
    • +
+ +

x86

+ +
    +
  • Removed a redundant de-reference for seL4_X86DangerousRDMSR in ia32.
    • +
  • Added a config option to set the frequency of the TSC.
    • +
  • Optimized the boot image size for x86_64.
    • +
  • Removed the PT_PHDR segment from the linker script to work around an issue in a variant of syslinux that treats a +PT_PHDR segment as distinct from a PT_LOAD segment.
    • +
+ +

Arm

+ +
    +
  • FPU ownership is now also given away on thread deletion instead of only on FPU exception.
    • +
  • Added basic build support for A35 core.
    • +
  • Fixed read/write of the VCPU CPACR register.
    • +
  • Fixed invalidation of the VIPI I-cache in hypervisor mode.
    • +
  • Removed duplicate interrupts for the zynqmp in its DTS.
    • +
  • Updated device definitions for the exynos5.
    • +
  • Added Raspberry Pi 4 support.
    • +
  • Updated Ethernet interrupts in the ZynqMP.
    • +
  • Added i.MX6 Nitrogen6_SoloX support.
    • +
  • Fixed CMake configurations for the ZynqMP and the Ultra96.
    • +
  • Fixed the platform #define for the i.MX6 Nitrogen6_SoloX.
    • +
  • Fixed I-cache invalidation on aarch64 SMP.
    • +
  • Fixed the usage of KernelPaddrUserTop on Arm platforms.
    • +
  • Added support for the i.MX low-power UART.
    • +
  • Added an option to ignore SErrors which is enabled on default for the TX2.
    • +
+ +

RISC-V

+ +
    +
  • Added PLIC driver and updated the DTS for the Ariane.
    • +
  • Merged the PLIC drivers for the Ariane and the Hifive.
    • +
  • Updated default timer frequency for the Ariane.
    • +
  • Map devices with large pages on 32 and 64-bit kernel.
    • +
  • Replaced mentions of BBL with OpenSBI.
    • +
  • Added definitions of the KernelOpenSBIPlatform variable for RISC-V platforms.
    • +
  • Removed instances of passing extra_caps_t by value for binary verification purposes.
    • +
  • Removed slot_range_t for binary verification purposes.
    • +
  • Removed DONT_TRANSLATE tag on ‘read_sip’ for binary verification purposes.
    • +
  • Added more efficient clz and ctz implementations to substitute the lack of machine instructions to count leading and +trailing zeroes.
    • +
  • Updated kernel bootstrap message to be the same as the one on Arm.
    • +
  • Added some fastpath improvements for RISC-V.
    • +
  • Added extra snippets of code to track kernel entries for RISC-V.
    • +
  • Added a configuration guard for fastpath on RISC-V.
    • +
  • Reorganised traps.S so that syscalls and fastpath checks were done after interrupts and exceptions checks to avoid +exceptions being interpreted as null-syscalls.
    • +
  • Added support for riscv64-elf- toolchain.
    • +
  • Fixed a register bug in the assembly entry point for SMP with regards to the elfloader passing HART and core IDs.
    • +
+ +

Upgrade Notes

+ +
    +
  • Scheduling contexts can now be configured as constant-bandwidth or sporadic server. +
      +
    • Constant bandwidth observes a continuous constant bandwidth of budget/period.
      • +
    • Sporadic server behaves as described by Sprunt et. al.
      • +
    • In an overcommitted system, sporadic preserves accumulated time.
      • +
    +
    • +
  • There are new PRIx and SEL4_PRIx printf conversion specifiers that can now be used inside the kernel.
    • +
  • x86_64 kernel binaries are now smaller and may be structured differently compared to previous kernel binaries.
    • +
  • Kernel entry benchmarking can now be done on RISC-V.
    • +
  • AUTOCONF_INCLUDED is no longer defined. The seL4 build system has stopped +using autoconf a long time ago and this define has been kept for compatibility +since then. It is no longer used anywhere by now, so it can be removed.
    • +
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 12.0.0..12.1.0

+ +

More details

+

See the +12.1.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/13.0.0.html b/releases/sel4/13.0.0.html new file mode 100644 index 00000000000..d8cdff0d602 --- /dev/null +++ b/releases/sel4/13.0.0.html @@ -0,0 +1,852 @@ + + + + + + + 13.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 13.0.0 Release

+ +

2024-07-01

+ +

Announcing the release of seL4 13.0.0. This release has security-relevant fixes that affect +configurations or areas of the kernel that have not been formally verified. It is recommended +to upgrade.

+ +

This is a breaking release.

+ +

Security-relevant Changes

+ +
    +
  • +

    Fixed a kernel-crashing NULL pointer dereference when injecting an IRQ for a non-associated VCPU on SMP +configurations. This can be triggered from user-level by any thread that has access to or can create non-associated +VCPU objects. While HYP+SMP is not a verified configuration and is not thoroughly tested, it is generally assumed to +be working. If you are using this configuration, it is strongly recommended to upgrade.

    + +
      +
    • Affected configurations: only unverified HYP+SMP configurations on Arm platforms are affected.
      • +
    • Affected versions: seL4 versions 12.0.0 and 12.1.0.
      • +
    • Exploitability: Any thread that can create or that has access to an unassociated VCPU can cause the crash. In static +systems, only the system initialiser thread can create VCPUs and the standard capDL system initialiser will not +trigger the issue. VMMs could have the authority to dissociate an existing VCPU from a TCB if they have both +capabilities. That is, a malicious VMM could cause a crash, but generally VMMs are trusted, albeit not verified +code. Guest VMs generally do not have sufficient authority to exploit this vulnerability.
      • +
    • Severity: Critical. This crashes the entire system.
      • +
    +
    • +
  • +

    Fixed a kernel-crashing cache maintenance operation on AArch64 (Armv8). On AArch64, when seL4 runs in EL1 the kernel +would fault with a data abort in seL4_ARM_Page_Invalidate_Data and seL4_ARM_VSpace_Invalidate_Data when the user +requested a dc ivac cache maintenance operation on a page that is not mapped writeable. If you are using seL4 in EL1 +on AArch64, it is strongly recommended to upgrade.

    + +
      +
    • Affected configurations: unverified AArch64 configurations of seL4 with hypervisor extensions off (kernel runs in +EL1). AArch32 configurations and configurations where seL4 runs in EL2 are not affected.
      • +
    • Affected versions: all previous versions since 5.0.0
      • +
    • Exploitability: Any thread that has a VSpace capability or page capability to a page that is not mapped writable can +cause the data abort. Most Microkit and CAmkES systems do not give their component access to these capabilities, but any component with Untyped capabilities could create threads with enough capabilities to trigger the issue.
      • +
    • Severity: Critical. This crashes the system.
      • +
    +
    • +
  • +

    Fixed a cache issue on Arm where cleared memory was not flushed to RAM, but only to the point of unification. This +means that uncached access was able to still see old memory content.

    + +
      +
    • Affected configurations: Arm platforms that distinguish flushing to PoU from flushing to RAM
      • +
    • Affected versions: all previous versions since 4.0.0
      • +
    • Exploitability: Low. The issue is trivially observable by mapping the same frame as cached and uncached. +However, it is unlikely to be exploitable in a real system, because re-using memory over security boundaries +is already excluded, so information leakage happens only within the same domain.
      • +
    • Severity: Medium. It breaks functional correctness in the sense that a cleared frame may not yet be cleared when +viewed as uncached. It does not break any functional kernel behaviour.
      • +
    +
    • +
+ +

Platforms

+ +
    +
  • Added support for the ARM Cortex A55
    • +
  • Added support for the imx8mp-evk platform
    • +
  • Added support for additional RPI4 variants
    • +
  • Added support for the Odroid C4
    • +
  • Added support for the Avnet MaaXBoard
    • +
  • Added support for arm_hyp on qemu-arm-virt platfrom with cortex-a15 CPU
    • +
  • Added support for qemu-riscv-virt
    • +
  • Added support for the Pine64 Star64
    • +
  • Added support for the TQMa8XQP 1GiB module
    • +
  • Remove imx31/kzm platform support. This platform is being removed as it is sufficiently old and unused.
    • +
  • Remove ARM1136JF_S and ARMv6 support. This architecture version is being removed as it is sufficiently old and +unused. See RFC-8.
    • +
  • Remove ARMv6 specific configs: KernelGlobalsFrame and KernelDangerousCodeInjectionOnUndefInstr. This removes the +constant seL4_GlobalsFrame from libsel4 as well as the IPC buffer in GlobalsFrame caveat from CAVEATS.md
    • +
  • rpi3+rpi4: Mark first memory page as reserved
    • +
+ +

Arm

+ +
    +
  • Enabled access to seL4_VCPUReg_VMPIDR and seL4_VCPUReg_VMPIDR_EL2 for all hypervisor configurations. Previously +this register was only accessible for SMP kernel configurations. Non-SMP configurations can still require access when +wanting to control the value of MPIDR that the guest reads. Note that the initial value for new seL4_ARM_VCPUs for +this register is 0 which isn’t a legal value for MPIDR_EL1 on AArch64. It may be necessary for the register to be +explicitly initialized by user level before launching a thread associated with the new seL4_ARM_VCPU.
    • +
  • Allow changing the VCPU of active thread: call vcpu_switch in associateVCPUTCB. This guarantees that the correct +VCPU will be activated when the kernel finishes execution. Previously, changing the VCPU of the current thread would +result in no VCPU being active.
    • +
  • benchmarking: use write-through kernel log buffer
    • +
  • arm_hyp: Access SPSR via non-banked instructions
    • +
  • generic_timer: force timer to de-assert IRQ.
    • +
  • No special handling for edge-triggered IRQs. +
      +
    • Clearing the pending state only has an effect if the IRQ state is active-and-pending, which happens for + edge-triggered interrupts if another edge happens on the IRQ line for the currently active interrupt. This window is + small enough to ignore, at worst user space will get another notification, which is harmless.
      • +
    + +

    If unnecessary notifications are unwanted, the pending state should be cleared during seL4_IRQHandler_Ack(), as + that covers a much bigger window. However, edge-triggered interrupts are not expected to happen often. Making all + interrupt handling slightly faster and the code simpler is the better trade-off.

    +
    • +
  • Make write-only mapping message consistent. There is a warning when creating a write-only mapping on AArch32/AArch64. +This message is now the same in all variants.
    • +
+ +
AArch32
+ +
    +
  • Implement KernelArmExportPTMRUser and KernelArmExportVTMRUser options for Arm generic timer use access on AArch32.
    • +
  • AArch32 VM fault messages now deliver original (untranslated) faulting IP in a hypervisor context, matching +AArch64 behaviour.
    • +
  • Fix single stepping on ARMv7
    • +
  • TLB: only perform TLB lockdown for Cortex A8. +
      +
    • The code previously used the same instructions for Cortex A8 and A9, but the Cortex A8 instructions are undocumented +for A9, and A9 provides a slightly different TLB interface. As far as we can tell, the instructions were simply +ignored by the supported A8 platforms, so there was no current correctness issue. Since the instructions had no +effect, we removed A9 TLB lockdown support. This potential issue was discovered and reported by the UK’s National +Cyber Security Centre (NCSC).
      • +
    +
    • +
  • TLB: guard TLB lockdown count. +
      +
    • lockTLBEntry uses the global tlbLockCount as input without checking bounds. This is fine, because the function +is called at most 2 times per core, but this is only apparent when checking the entire possible calling context. +Make this bound obvious locally by doing nothing if the function is called with values of tlbLockCount of 2 or +greater. This is safe, because TLB lockdown is a performance change only. Also add an assert for debug mode, because +we want to know if calling context ever changes. This potential issue was reported by The UK’s National Cyber +Security Centre (NCSC).
      • +
    +
    • +
+ +
AArch64
+ +
    +
  • Add AARCH64_verified.cmake config for functional correctness on AArch64
    • +
  • Rename libsel4 config option AARCH64_VSPACE_S2_START_L1 to CONFIG_AARCH64_VSPACE_S2_START_L1 to be namespace +compliant.
    • +
  • Added SMC Capability (smc_cap) and SMC forwarding for AArch64 platforms. See +RFC-9.
    • +
  • Remove VSpace object types in AArch64: seL4_ARM_PageDirectory and seL4_ARM_PageUpperDirectory. See also the +corresponding RFC. The functionality +previously provided by these types will be provided by the existing seL4_ARM_PageTable object type. This allows for +a simpler API and enables a smaller kernel implementation that will be easier to verify. libsel4 provides a source +compatibility translation that maps the old libsel4 names and constants the new ones in +<sel4/sel4_arch/deprecated.h>. There are some exceptional cases where kernel behavior has changed: +
      +
    • A Page directory and page table are now the same kind of object and can be mapped at any page table level. +If the lookup for the provided address stops at a slot that can map a page directory, it will map the object as a +page directory. If there already is a page directory mapped, the lookup will proceed to the next level and it will +map as a page table instead of returning an error.
      • +
    +
    • +
  • Removed user address space reserved slots restriction on 40bit PA platforms when KernelArmHypervisorSupport is set. +This change is reflected in the definition of the seL4_UserTop constant that holds the largest user virtual address.
    • +
  • Added support for GICv3 virtualization, tested on iMX8QXP
    • +
  • Implemented a signal fastpath on AArch64. Must be enabled explicitly with the KernelSignalFastpath config option.
    • +
  • Implemented a virtual memory fault fastpath on AArch64. Must be enabled explicitly with the KernelExceptionFastpath config option.
    • +
  • Add option KernelAArch64UserCacheEnable for user cache maintenance. +
      +
    • +

      Enables user level access to DC CVAU, DC CIVAC, DC CVAC, and IC IVAU which are cache maintenance operations +for the data caches and instruction caches underlying Normal memory and also access to the read-only cache-type +register CTR_EL0 that provides cache type information. The ArmV8-A architecture allows access from EL0 as fast +cache maintenance operations improves DMA performance in user-level device drivers.

      + +

      These instructions are a subset of the available cache maintenance instructions as they can only address lines by +virtual address (VA). They also require that the VA provided refers to a valid mapping with at least read +permissions. This corresponds to lines that the EL0 could already affect via regular operation and so it’s not +expected to break any cache-partitioning scheme.

      + +

      The config option allows this policy to be selected for a particular kernel configuration, but it is default enabled +as this has been the existing behavior for current aarch64,hyp configurations and have not been explicitly disabled +in non-hyp configurations.

      +
      • +
    +
    • +
  • make error reporting consistent: Report the VSpace cap (1) as invalid, instead of the frame cap (0) in +ARMFrameInvocation to stay consistent with the other architectures.
    • +
  • vcpu: only trap WFx instructions from VCPUs. When KernelArmDisableWFIWFETraps is disabled (trapping of WFI/WFE is +enabled), the kernel traps WFx instructions from both native and vCPU threads. This change brings the code in line +with the config description.
    • +
+ +

RISC-V

+ +
    +
  • Remove the ability for user-space on RISC-V platforms to access the core-local interrupt controller (CLINT). The +CLINT contains memory-mapped registers that the kernel depends on for timer interrupts and hence should not be +accessible by user-space.
    • +
  • Add configuration option KernelRiscvUseClintMtime for faster access of hardware timestamp on RISC-V platforms. +The configuration option is not enabled by default as it requires access to the CLINT which depends on the platform +and whether the M-mode firmware allows S-mode to access the CLINT. For example, newer versions of OpenSBI (1.0 and above) +do not allow direct access of the CLINT.
    • +
  • Rename object interface files include/interfaces/sel4.xml, arch_include/*/interfaces/sel4arch.xml, and +sel4_arch_include/*/interfaces/sel4arch.xml to include/interfaces/object-api.xml, +arch_include/*/interfaces/object-api-arch.xml, and sel4_arch_include/*/interfaces/object-api-sel4-arch.xml, +respectively.
    • +
  • Improve PLIC driver API and documentation
    • +
  • Fix getMaxUsToTicks function tor return time instead of ticks.
    • +
  • Improve RISC-V PTE compliance: keep D, A, and U bits cleared.
    • +
+ +

Intel

+ +
    +
  • libsel4: add enum for EPT attributes.
    • +
  • VTX: fix EPT cache attribute setting. Previously the only effectively possible value was EPTWriteBack.
    • +
  • Add kernel support for 64-bit VMs
    • +
  • Provide CONFIG_X86_64_VTX_64BIT_GUESTS for 64-bit VM support
    • +
  • Only access real IOAPIC registers. IOAPICS can have varying numbers of lines attached. The actual number can be +accessed in the top 16 bits of the version register. Rather than assuming fixed 24 lines per IRQ, read the actual +number and use that.
    • +
+ +

MCS

+ +
    +
  • Rename seL4_TimeoutMsg to seL4_Timeout_Msg to make it consistent with the naming of other messages.
    • +
  • Correct the minimum size of a scheduling context. This changes the value of seL4_MinSchedContextBits.
    • +
  • Correct check for message length in SchedControl_ConfigureFlags
    • +
  • Allow lazy SchedContext rebind. Before, binding a scheduling context to a TCB was not allowed if the SC was bound to a +notification object. Also, binding an SC to a notification was not allowed if that scheduling context was already +bound to a TCB. Without these restriction it is much easier to move scheduling contexts around: In effect having a SC +bound on both the TCB and a notification acts as if the thread is running on a donated SC which will be returned when +the tasks calls Recv/Wait, which is done by maybeReturnSchedContext().
    • +
  • Only charge budgets for non-idle thread SCs
    • +
  • ARM+MCS: Introduce TIMER_OVERHEAD_TICKS. For ARM currently TIMER_PRECISION exists, but that is in microseconds and +not fine-grained enough. TIMER_OVERHEAD_TICKS is needed to make periodic tasks synchronous with the system clock. If +this value is non-zero every period will be extended with the overhead of taking an interrupt and reading the system +clock. To avoid this drift, the configured value should be set to at least the average overhead.
    • +
  • SMP: Do not use cross-node ksCurTime assuming they are in sync (which they are not), instead use +NODE_STATE(ksCurTime).
    • +
  • SMP: Add clock synchronisation test on boot
    • +
  • SMP: Fix scheduling context use-after-free
    • +
+ +

Other Changes

+ +
    +
  • boot: Introduce seL4_BootInfoFrameSize and seL4_BootInfoFrameBits for user land so there is no longer a need to +hard-code a 4 KiByte assumption. Remove BI_FRAME_SIZE_BITS.
    • +
  • Fix: Don’t clobber msgInfo register in PageGetAddress, ASIDControlInvocation, ARMCBInvocation, +A32PageDirectoryGetStatusBits, X86PortIn, WriteVMCS, ReadVMCS, ConfigureSingleStepping, and GetBreakpoint.
    • +
  • libsel4: Make bootinfo consistent. Some slot positions in the rootnode would depend on configuration. However that +makes it difficult to add new root caps, especially if multiple caps only exist based on configuration. Make all caps +always there, but null if not configured.
    • +
  • libsel4: Eliminate unnamed enums
    • +
  • Improved consistency and completeness of user manual
    • +
  • Added manual for bitfield generator
    • +
  • bitfield_gen: allow non-contiguous tag fields. A tagged union can now optionally use multiple fields to indicate the +tag. These are called “sliced” tags in the code. The tag fields have to be at the same position and width in each +block of the tagged unions, and all tag fields have to be within the same word. See the manual for details.
    • +
  • Make CONFIG_PRINTING and CONFIG_DEBUG_BUILD usable independently from each other
    • +
  • Overall debug printing improvements
    • +
  • Fix invisible chars due to ANSI escape codes. On terminals with black background some debug output was invisible due +to black foreground colour. Use bold instead.
    • +
  • Rename libsel4 config option ENABLE_SMP_SUPPORT to CONFIG_ENABLE_SMP_SUPPORT to be namespace compliant.
    • +
  • Removed obsolete define HAVE_AUTOCONF
    • +
  • Remove userError from seL4_ReplyRecv path, because it too often incorrectly warns about legitimate operations
    • +
  • Update GDB macros
    • +
  • Add support for cmake --install <dir> for final build and config artefacts
    • +
  • cmake: support supplying custom device trees overrides
    • +
  • cmake: provide gen_config.json with kernel config settings
    • +
  • Provide platform_gen.json in addition to platform_gen.yaml
    • +
  • Allow build with GNU binutils >= 2.38
    • +
  • Allow compilation with clang 12
    • +
  • cmake: detect x86 cross-compiler for Arm host (e.g. on Apple M1)
    • +
  • Consistently use /usr/bin/env for bash/sh invocations
    • +
  • Require Python 3 consistently everywhere
    • +
  • Improved support for compiling on MacOS
    • +
  • General minor build system improvements and clean-up
    • +
  • Set up automated tests for CI and GitHub pull requests on seL4
    • +
  • Add vulnerability disclosure policy
    • +
+ +

Upgrade Notes

+ +
    +
  • The change in seL4_MinSchedContextBits can lead to failure where code previously created +scheduling contexts with size seL4_MinSchedContextBits and expected more than the 2 minimum +refills to be available for that size. Either use a larger size (the previous value 8 of +seL4_MinSchedContextBits) in retyping, or request fewer refills.
    • +
+ +

Full changelog

+ +

Refer to the git log in +https://github.com/seL4/seL4 using git log 12.1.0..13.0.0

+ +

More details

+ +

See the +13.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/14.0.0.html b/releases/sel4/14.0.0.html new file mode 100644 index 00000000000..3dd5ebe9697 --- /dev/null +++ b/releases/sel4/14.0.0.html @@ -0,0 +1,725 @@ + + + + + + + 14.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 14.0.0 Release

+ +

Announcing the release of seL4 14.0.0 with the following changes:

+ +

14.0.0 2025-11-25: BREAKING

+ +

Security-relevant Changes

+ +
    +
  • +

    Fixed a kernel-crashing defect on (unverified) x86 configurations with VT-x enabled where the kernel bookkeeping for +VCPU objects was incorrect. The kernel crash can be triggered by retyping multiple VCPU objects from the same Untyped +capability or by mixing the right deletion and retyping operations. Thanks to Mathieu Mirmont from Neutrality for +reporting and fixing this defect.

    + +
      +
    • Affected configurations: only unverified VT-x configurations on x86 platforms are affected.
      • +
    • Affected versions: seL4 versions 4.0.0 to 13.0.0.
      • +
    • Exploitability: Any thread on VT-x configurations with an untyped capability and a CNode capability can exploit +this bug. Static CAmKES and Microkit systems do not generally provide either of these to user-level components, but +in most dynamic systems, this combination of capabilities would be common for management components that provide +object allocation. The defect breaks the usual subsystem isolation properties that verified seL4 configurations +provide. In systems that follow the principle of least privilege this combination of capabilities should only be +available to trusted allocation components, which strongly reduces the scope of exploitability.
      • +
    • Severity: Critical. This crashes the entire system.
      • +
    +
    • +
+ +

Changes

+ +
    +
  • All Arm platforms supported by seL4 now have a verified configuration.
    • +
  • Added: build exports an invocations_all.json file with syscall invocation numbers.
    • +
  • Added option for suppressing generation of config output files in build process
    • +
  • Added --skip-unchanged option to build process to prevent time stamp update for config output files when these +files did not change.
    • +
  • Added recording of disabled options in build system config output files. Before, options that were hidden from the +CMake GUI due to unsatisfied config_choice conditions were not recorded. After this change, these hidden options are +recorded as disabled.
    • +
  • Added build system support for Qemu >= 10
    • +
  • Change fault based FPU context switching to a TCB flag based approach: +New system call seL4_TCB_SetFlags and new flag seL4_TCBFlag_fpuDisabled. +See RFC-18.
    • +
  • Multiple SMP related bugs fixed.
    • +
  • Change point of cache flush from untyped reset to retype. The kernel now flushes the cache only for those object types +where a flush is necessary, and only when the object is retyped, not when the untyped cap is reset. This reduces +overall need for flushing and delays it to the point of use. This speeds up boot time significantly.
    • +
  • Fixed kernel reply protocol for yieldTo (MCS). The kernel would previously for the yieldTo call: +
      +
    • return messages with length field set to 0, even though they had content;
      • +
    • generate a reply for send-only invocations of the system call;
      • +
    • incorrectly indicate success/failure in some circumstances. +While these were all incorrect, they would be unlikely to be observed through normal use of libsel4.
      • +
    +
    • +
  • Fixed TCB_SetSchedParams to match the API reference. TCB_SetSchedParams previously had more lenient checks. +Used new checks for simplifying the implementation.
    • +
  • Fixed error indication for SetTimeoutEndpoint and improve error message
    • +
  • Fixed: when the domain scheduler is used, avoid touching cross-domain state for VCPUs and FPU. Flush VCPU and FPU +state on domain switch.
    • +
  • Enable building with clang-18 and clang-20 (untested in CI).
    • +
  • Improve error message in build system for when invalid platform parameter is provided.
    • +
  • Improve boot printing: print half-open regions as [a..b)
    • +
+ +

Platforms

+ +
    +
  • Added support for the i.MX93 SoC
    • +
  • Added support for the Cheshire platform
    • +
  • Added support for the HiFive Premier P550 platform
    • +
  • Fixed imx8mq board timer frequency
    • +
  • Removed the default settings KernelArmVtimerUpdateVOffset and KernelArmDisableWFIWFETraps from the platform +tqma8xqp1gb, since they are project specific settings, not platform settings. Add +set(KernelArmVtimerUpdateVOffset OFF) and +set(KernelArmDisableWFIWFETraps ON) +to your project settings to get the same configuration as before if you are using tqma8xqp1gb.
    • +
+ +

Arm

+ +
    +
  • +

    Support SGIs (software generated interrupts) on platforms with GICv2 or GICv3 in non-SMP configurations. SGIs are +intended for signalling other cores when seL4 is used in a multi-kernel setup. On Arm, this is implemented with a new +capability SGISignal, which can be created from IRQControl capabilities with the new IRQ control invocation +ARMIRQIssueSGISignal for a specific IRQ and target core. The resulting SGISignal capability can be invoked like a +notification capability that supports only signal/send. SGIs can be received by IRQ notification objects on the target +core like other IRQs.

    + +

    See also RFC-17

    +
    • +
  • +

    Added config option for selecting which thread ID register is used for Kernel TLS syscalls and invocations. +KernelArmTLSReg can be used to select either tpidru or tpidruro as the TLS register used for seL4_TCB_SetTLSBase and seL4_SetTLSBase operations. +This config option’s default value is tpidru which is what the register that the kernel currently uses for the TLS register for aarch32 and aarch64 platforms.

    +
    • +
  • +

    Fixed: under some circumstances, writes by a VMM to VCPU timer registers could have been reverted by the kernel to +their previous state. This was triggered when:

    + +
      +
    • a VCPU thread was running,
      • +
    • the VCPU was then disabled but remained active by switching to a non-VCPU thread,
      • +
    • that VCPU thread had the VCPU cap and performed the timer register writes,
      • +
    • and execution then switched back to the VCPU thread.
      • +
    + +

    This was found by Alison Felizzi and independently by Ryan Barry during the integrity proofs for AArch64 hyp mode.

    +
    • +
  • +

    Fixed: under some circumstances, seL4_VCPUReg_CPACR is saved twice to the current VCPU. The value of this +register may change between saves, causing the latter save to unintentionally grant EL0/1 access to the FPU.

    + +
      +
    1. A thread with an active current VCPU switches to a thread without a VCPU. The current VCPU is disabled. + 1.1. seL4_VCPUReg_CPACR is saved to the current VCPU. + 1.2. enableFpuEL01 updates the register, enabling FPU access in EL0 and EL1.
      2. +
    2. The thread without a VCPU switches to a thread with a different VCPU to the first + 2.1. All registers from seL4_VCPUReg_TTBR0 to seL4_VCPUReg_SPSR_EL1 are saved. This range includes + seL4_VCPUReg_CPACR, which overwrites the previously saved value and grants FPU access at EL0 and EL1.
      3. +
    +
    • +
  • +

    Fixed: on aarch32 configurations with hypervisor support, CNTKCTL was not saved and restored alongside other virtual +timer registers. seL4_VCPUReg_CNTKCTL has been introduced to mirror seL4_VCPUReg_CNTKCTL_EL1 from aarch64.

    +
    • +
  • +

    Fixed VGIC and VPPI maintenance handling on MCS, which allowed a thread to simultaneously be blocked and in the +release queue.

    +
    • +
  • Added port of debug API to AArch64.
    • +
  • Added implementation of Split EOI mode for GICv3 for improved interrupt performance.
    • +
  • Added aarch64-elf- as valid AArch64 toolchain prefix.
    • +
+ +

X86

+ +
    +
  • Fixed XSAVES option for FPU. It is now possible to enable this for newer x86 CPUs.
    • +
  • Fixed: avoid use-after-free if a VCPU with active FPU state gets deleted.
    • +
+ +

RISC-V

+ +
    +
  • Fixed: TCB size on RISC-V 32-bit when FPU is enabled
    • +
  • Changed default cmake options KernelRiscvExtF and KernelRiscvExtD from OFF to ON. +Except for RISCV32 with LLVM clang enabled will default both to OFF.
    • +
  • Fixed: off-by-1 write for PLIC IRQ priorities. Effect so far only observed on Qemu.
    • +
  • Added: catch s-mode traps and halt in debug mode. For debugging only.
    • +
  • Added riscv-none-elf- as valid RISC-V toolchain prefix
    • +
  • Changed treatment of SBI memory: instead of special in-kernel treatment, SBI memory is now a +reserved region in the device tree and can therefore be adjusted per platform.
    • +
+ +

Upgrade Notes

+ +

Set seL4_TCBFlag_fpuDisabled (with the seL4_TCB_SetFlags invocation of TCB capabilities) for +tasks not using the FPU to retain the old context switch performance. The -mgeneral-regs-only +option may be needed to stop the compiler from issuing SIMD instructions to speed up integer +operations.

+ +

Full changelog

+ +

Refer to the git log in +https://github.com/seL4/seL4 using git log 13.0.0..14.0.0

+ +

More details

+ +

See the +14.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/2.0.0.html b/releases/sel4/2.0.0.html new file mode 100644 index 00000000000..b447dd18865 --- /dev/null +++ b/releases/sel4/2.0.0.html @@ -0,0 +1,708 @@ + + + + + + + 2.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Introducing seL4 2.0.0

+ +

Version 2.0.0 introduces more consistent terminology to manual and code, +as well as API and performance improvements, including to seL4’s +formally verified ARMv6 version.

+ +

We clarified the notion of signals and notifications vs IPC, and added a +new feature to the seL4 API that allows user programs to receive +notifications while waiting for IPC messages. You can now also poll +notification objects. Both of these changes are aimed at simplifying +user-level interaction with interrupts.

+ +

In addition to the new features, seL4 has become even faster than it was +before, esp. in scheduling threads.

+ +

The new features and performance improvements are available on all +supported platforms, and are formally verified to full sel4 standards. +We have also switched our release process to semantic versioning, so +it’s easy to tell which seL4 releases are binary-compatible, +source-compatible, or will require updates to user-level code.

+ +

Terminology Changes

+ +

IPC vs Notifications

+ +

The old terminology of “synchronous IPC” vs “asynchronous IPC” was +confusing and misleading. We changed this to reflect the fact that IPC +in seL4 is always synchronous and is simply referred to as “IPC”, which +is enabled by “endpoint” objects. The receive operation is now more +appropriately called “receive”.

+ +

What used to be called incorrectly “asynchronous IPC” is now called +Notifications, enabled by “notification” objects. Notifications are not +a form of message passing, but arrays of binary semaphores, and the new +terminology describes this better. The operations on them are +consequently called “signal” and “wait”

+ +

New Features

+ +

Notification binding

+ +

A notification can be bound to a thread and is referred to as the +thread’s bound notification object. This is a 1:1 relationship. Whenever +a thread waits for an IPC on an endpoint, it will receive any signals +sent to its bound notification object, with the signal flags converted +into a single-word message.

+ +

Threads can also explicitly wait for signals by waiting on the +notification object itself.

+ +

For more details, see the 2.0.0 manual

+ +

Implementation improvements

+ +
    +
  • introduces the bitfield scheduler: faster scheduler (Was linear in + the
    • +
+ +

number of runnable threads, now log n)

+ +
    +
  • improved benchmarking macros: can now specify multiple + benchmarking
    • +
+ +

tracepoints at once added +CONFIG_RELEASE_PRINTF in addition to CONFIG_DEBUG and CONFIG_RELEASE, which +enables printf in a release build

+ +

API Changes

+ +
    +
  • seL4_Recv replaces seL4_Wait on endpoints
    • +
  • seL4_Wait is now only used on notification objects
    • +
  • Async endpoint -> notification object
    • +
  • sync endpoint -> endpoint
    • +
  • seL4_Recv on an endpoint may now return signals sent to a + thread’s
    • +
+ +

bound notification object.

+ +

API Additions

+ +
    +
  • seL4_NotificationObject replaces deprecated + seL4_AsyncEndpointObject
    • +
  • seL4_NotificationBits size in bits of a notification object
    • +
  • seL4_IRQHandler_SetNotification replaces deprecated + seL4_IRQHandler_SetEndpoint
    • +
  • seL4_Recv replaces seL4_Wait for endpoints
    • +
  • seL4_Wait used on notifications
    • +
  • seL4_NBRecv non-blocking (polling) receive on an endpoint, + which fails
    • +
+ +

if there is no message waiting. Opposite of NBSend (which silently +fails if there is no receiver waiting)

+
    +
  • seL4_Poll collects any +signals from a notification objects, returns zero if there are none
    • +
  • seL4_Signal replaces deprecated seL4_Notify
    • +
  • seL4_TCB_BindNotification bind a notification to a tcb
    • +
  • seL4_TCB_UnbindNotification unbind a notification from a tcb
    • +
+ +

Deprecations

+ +
    +
  • seL4_AsyncEndpointObject
    • +
  • seL4_Notify
    • +
  • seL4_IRQHandler_SetEndpoint
    • +
+ +

Note on Syscall names

+ +

Logically there are only two operations on capabilities, send and +receive, which can take opcodes specifying sup-operations. For example, +the Notification operations Signal and Wait are mapped to Send and +Receive, respectively. For efficiency reasons, many kernel objects use +separate kernel entry points for their operations. You must not rely on +either, as this can change at any time. Instead, always use the +object-specific wrapper functions.

+ +

User-level repositories

+ +

To simply repository management we have merged many of our user level +library repositories. To see the changes please compare 1.0.4.xml and +2.0.x.xml in https://github.com/seL4/seL4test-manifest

+ +

Upgrade notes

+ +

Calls to seL4_Wait no longer return a seL4_MessageInfo_t +as seL4_Wait is intended to be used on notification objects. +Calls to the prior version of seL4_Wait need to be replaced with +seL4_Recv.

+ +

If you don’t want to upgrade yet - don’t worry. Both the +sel4test-manifest and verification manifest repositories have manifests +titled 1.0.4.xml which point to the tips of the previously released +repositories before today. All library repositories have a branch called +‘1.0.x-compatible’ which are compatible with the 1.0.4 kernel.

+ +

Note that to use the new merged repositories, you must upgrade to 2.0.0.

+ +

Full changelog

+ +

Use git log 1.0.4..2.0.0 in https://github.com/seL4/seL4

+ +

More details

+ +

See the 2.0.0 +manual +included in the release for detailed descriptions of the new features. +Or ask on this mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/2.1.0.html b/releases/sel4/2.1.0.html new file mode 100644 index 00000000000..4a59968f7fb --- /dev/null +++ b/releases/sel4/2.1.0.html @@ -0,0 +1,587 @@ + + + + + + + 2.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 2.1.0 Release Notes

+

New Features

+ +
    +
  • ability to generate libsel4 system calls without inlining them
    • +
  • new kernel debugging feature added, which allows developers to + call debug_printKernelEntryReason anywhere in the kernel which + will output the entry reason and relevant arguments.
    • +
+ +

Implementation improvements

+ +
    +
  • Some duplication between kernel and libsel4 removed.
    • +
  • Many changes refactoring the x86 code base in preparation for the + upcoming x86_64 platform port.
    • +
+ +

API Additions

+ +
    +
  • seL4_MappingFailedLookupLevel() - get the page table level a + frame mapping failed at. This will always return 2 (second level + page table) for currently supported 32 bit platforms.
    • +
  • seL4_NumInitialCaps constant added to bootinfo.h to track the + first free slot in the initial task’s cspace.
    • +
+ +

Upgrade notes

+ +

Source compatible, some API additions.

+ +

Full changelog

+ +

Use git log 2.0.0..2.1.0

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/3.0.0.html b/releases/sel4/3.0.0.html new file mode 100644 index 00000000000..ad847eb2d12 --- /dev/null +++ b/releases/sel4/3.0.0.html @@ -0,0 +1,671 @@ + + + + + + + 3.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 3.0.0 Release Notes

+

This release is a minor release that brings +structural improvements to the kernel in preparation for 64bit +architecture support. Although changes do break the API, the breakages +are small (see API Changes and API Removals below) and should not effect +most users.

+ +

Implementation improvements

+ +
    +
  • python3 compatability for our python scripts.
    • +
  • more source code restructuring in preparation for 64-bit ports + of seL4
    • +
  • idle thread is run in system mode for all ARM platforms except + for the KZM11.
    • +
  • more work to remove duplication between libsel4 and kernel.
    • +
+ +

API Additions

+ +
    +
  • seL4_IRQControl_GetIOAPIC for x86.
    • +
  • seL4_IRQControl_GetMSI for x86.
    • +
+ +

API Changes

+ +
    +
  • Total number of ASIDs for x86 reduced from 2\^16\^ to 2\^12\^ + (max ASID 2\^12\^).
    • +
  • seL4_BootInfo struct: userImagePDs and userImagePTs combined + into userImagePaging in preparation for multilevel paging + structures for 64 bit kernel support.
    • +
  • Diminish rights removed from IPC
    • +
+ +

API Removals

+ +
    +
  • seL4_IRQ_SetMode removed (This only effects users who use the + IOAPIC on x86, which is turned off by default).
    • +
+ +

API deprecations

+ +
    +
  • seL4_IA32_PageDirectory_Map deprecated for + seL4_X86_PageDirectory_Map
    • +
  • seL4_IA32_PageDirectory_Unmap deprecated for + seL4_X86_PageDirectory_Unmap
    • +
  • seL4_IA32_PageTable_Map deprecated for + seL4_X86_PageTable_Map
    • +
  • seL4_IA32_PageTable_Unmap deprecated for + seL4_X86_PageTable_Unmap
    • +
  • seL4_IA32_IOPageTable_Map deprecated for + seL4_X86_IOPageTable_Map
    • +
  • seL4_IA32_IOPageTable_Unmap deprecated for + seL4_X86_IOPageTable_Unmap
    • +
  • seL4_IA32_IOPageTable_Map deprecated for + seL4_X86_IOPageTable_Map
    • +
  • seL4_IA32_IOPageTable_Unmap deprecated for + seL4_X86_IOPageTable_Unmap
    • +
  • seL4_IA32_Page_Map deprecated for seL4_X86_Page_Map
    • +
  • seL4_IA32_Page_Unmap deprecated for seL4_X86_Page_Unmap
    • +
  • seL4_IA32_Page_Remap deprecated for seL4_X86_Page_Remap
    • +
  • seL4_IA32_Page_MapIO deprecated for seL4_X86_Page_MapIO
    • +
  • seL4_IA32_Page_GetAddress deprecated for + seL4_X86_Page_GetAddress
    • +
  • seL4_IA32_ASIDControl_MakePool deprecated for + seL4_X86_ASIDControl_MakePool
    • +
  • seL4_IA32_ASIDPool_Assign deprecated for + seL4_X86_ASIDPool_Assign
    • +
  • seL4_IA32_IOPort_In8 deprecated for seL4_X86_IOPort_In8
    • +
  • seL4_IA32_IOPort_In16 deprecated for seL4_X86_IOPort_In16
    • +
  • seL4_IA32_IOPort_In32 deprecated for seL4_X86_IOPort_In32
    • +
  • seL4_IA32_IOPort_Out8 deprecated for seL4_X86_IOPort_Out8
    • +
  • seL4_IA32_IOPort_Out16 deprecated for + seL4_X86_IOPort_Out16
    • +
  • seL4_IA32_IOPort_Out32 deprecated for + seL4_X86_IOPort_Out32
    • +
  • seL4_IA32_4K deprecated for seL4_X86_4K
    • +
  • seL4_IA32_LargePage deprecated for seL4_X86_LargePageObject
    • +
  • seL4_IA32_PageTableObject deprecated for + seL4_X86_PageTableObject
    • +
  • seL4_IA32_PageDirectoryObject deprecated for + seL4_X86_PageDirectoryObject
    • +
  • seL4_IA32_IOPageTableObject deprecated for + seL4_X86_IOPageTableObject
    • +
  • seL4_IA32_ASIDControl deprecated for seL4_X86_ASIDControl
    • +
  • seL4_IA32_ASIDPool deprecated for seL4_X86_ASIDPool
    • +
  • seL4_IA32_IOSpace deprecated for seL4_X86_IOSpace
    • +
  • seL4_IA32_IOPort deprecated for seL4_X86_IOPort
    • +
  • seL4_IA32_Page deprecated for seL4_X86_Page
    • +
  • seL4_IA32_PDPT deprecated for seL4_X86_PDPT
    • +
  • seL4_IA32_PageDirectory deprecated for + seL4_X86_PageDirectory
    • +
  • seL4_IA32_PageTable deprecated for seL4_X86_PageTable
    • +
  • seL4_IA32_IOPageTable deprecated for seL4_X86_IOPageTable
    • +
  • seL4_IA32_Default_VMAttributes deprecated for + seL4_X86_Default_VMAttributes
    • +
  • seL4_IA32_WriteBack deprecated for seL4_X86_WriteBack
    • +
  • seL4_IA32_WriteThrough deprecated for seL4_X86_WriteThrough
    • +
  • seL4_IA32_CacheDisabled deprecated for + seL4_X86_CacheDisabled
    • +
  • seL4_IA32_Uncacheable deprecated for + seL4_X86_Uncacheable
    • +
  • seL4_IA32_WriteCombining deprecated for + seL4_X86_WriteCombining
    • +
  • seL4_IA32_VMAttributes deprecated for seL4_X86_VMAttributes
    • +
+ +

Upgrade notes

+

This change is not source or binary compatible.

+ +

Users will need to remove calls to seL4_IRQ_SetMode, and upgrade any +manual parsing of seL4_BootInfo.

+ +

Full changelog

+

Use git log 2.1.0..3.0.0

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/3.0.1.html b/releases/sel4/3.0.1.html new file mode 100644 index 00000000000..33850c4b435 --- /dev/null +++ b/releases/sel4/3.0.1.html @@ -0,0 +1,574 @@ + + + + + + + 3.0.1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 3.0.1 Release Notes

+ +

This release adds support for the NVIDIA Tegra K1, along with other +minor improvements.

+ +

Implementation improvements

+ +
    +
  • Support for NVIDIA Nvidia Tegra K1 added.
    • +
  • more reduction of duplication between kernel and libsel4.
    • +
  • Beagle now uses GPT9 instead of GPT11 as the kernel timer, which + is much more accurate.
    • +
  • Fixes a bug where x86 would fault when built using -O0.
    • +
+ +

Upgrade notes

+ +

This change is source and binary compatible.

+ +

Full changelog

+ +

Use git log 3.0.0..3.0.1

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/3.1.0.html b/releases/sel4/3.1.0.html new file mode 100644 index 00000000000..ff40728795d --- /dev/null +++ b/releases/sel4/3.1.0.html @@ -0,0 +1,594 @@ + + + + + + + 3.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Introducing seL4 3.1.0

+ +
    +
  • Adds single-core support for HiKey cortex-a53 board, in 32 bit + mode (non-verified). This is the first armv8 platform + seL4 supports.
    • +
  • haskell kernel moved to verification repos (used to be in seL4 + repo, available here now: + https://github.com/seL4/l4v/tree/master/spec/haskell
    • +
+ +

Implementation improvements

+ +
    +
  • kernel now has debug feature which outputs part of the user stack + on a double fault
    • +
+ +

API Changes

+ +

API Additions

+ +
    +
  • X86PageDirectoryGetStatusBits allows users to get the status + bits of a virtual address mapping. This is not supported on PAE.
    • +
+ +

Upgrade notes

+ +
    +
  • This release is source compatible.
    • +
+ +

Full changelog

+ +

Use git log 3.0.1..3.1.0 in https://github.com/seL4/seL4

+ +

More details

+ +

See the +3.1.0 manual included in the release for detailed descriptions of the new +features. Or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/3.2.0.html b/releases/sel4/3.2.0.html new file mode 100644 index 00000000000..c556689ae72 --- /dev/null +++ b/releases/sel4/3.2.0.html @@ -0,0 +1,597 @@ + + + + + + + 3.2.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Introducing seL4 3.2.0

+ +
    +
  • ARM Hypervisor support.
    • +
  • ARM Jetson-TK1: Cleanup.
    • +
  • Benchmarking now supports tracking of syscalls.
    • +
  • Support for XSAVE feature set for x86 CPUs.
    • +
  • Simplified ARM platform selection during configuration.
    • +
+ +

Implementation improvements

+ +
    +
  • Several enhancements for both x86 and ARM have +been made. Please see the commit log for details.
    • +
+ +

API Changes

+ +
    +
  • No API changes in this release.
    • +
+ +

ABI Changes

+ +
    +
  • seL4_BootInfo has a new entry for IOSpace caps for + ARM SMMU.
    • +
+ +

Upgrade notes

+ +
    +
  • This release is source compatible.
    • +
+ +

Full changelog

+ +

Use git log 3.1.0..3.2.0 in https://github.com/seL4/seL4

+ +

More details

+ +

See the +3.2.0 manual included in the release for detailed descriptions of the new +features. Or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/4.0.0.html b/releases/sel4/4.0.0.html new file mode 100644 index 00000000000..c7177eac919 --- /dev/null +++ b/releases/sel4/4.0.0.html @@ -0,0 +1,646 @@ + + + + + + + 4.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Introducing seL4 4.0.0

+

Announcing the release of seL4 4.0.0 +with the following changes:

+ +

General:

+ +
    +
  • Reorder bootinfo structure.
    • +
  • Add missing seL4_AllRights macro in libsel4.
    • +
  • Disallow kernel from using a device frame as an IPC buffer.
    • +
  • Syscall docs in manual now generated by doxygen.
    • +
  • Changes to make verification easier.
    • +
  • Various documentation fixes.
    • +
  • Benchmarks refactoring.
    • +
  • Coding style fixes.
    • +
  • Support for TLB and Cache management.
    • +
  • Preemptible backwards memzero for Retype.
    • +
  • Support for TCB operations in X86 multicore.
    • +
  • Support for raspberry-pi 3.
    • +
  • Add seL4_BenchmarkFlushCaches() for arm and ia32.
    • +
+ +

ARM specific changes:

+
    +
  • ARM Hyp refactoring.
    • +
  • Update VCPU fault definitions.
    • +
  • Add userspace invocations for hardware debugging.
    • +
  • Enable PMU export for V8.
    • +
  • Support ARM MPCore registers.
    • +
  • Fix config dependency for ‘IPC Buffer location’.
    • +
  • Use new cap rights structures in iospace.
    • +
  • Move initial setting of TPIDRURW register.
    • +
  • Support for prefetcher on Cortex-A9.
    • +
  • Fix fastpath_restore on ARM Hyp and implement slowpath and restore in C.
    • +
  • am335x: Prevent out of bounds array access.
    • +
+ +

TK1

+ +
    +
  • Remove temporary SMMU memory mapping support.
    • +
  • Correct SMMU PD and PT indexing.
    • +
  • Split the mux controller from the misc region.
    • +
+ +

OMAP:

+
    +
  • Fix issues with OMAP IRQ Code.
    • +
+ +

X86 specific changes:

+
    +
  • Add userspace invocations for hardware debugging.
    • +
  • Avoid writing the fs/gs base unless necessary.
    • +
  • Explicitly declare address of .phys.bss.
    • +
  • Add BSS regions for BOOT and PHYS code.
    • +
  • Write FS and GS base when restoring user context.
    • +
  • Initialize store area when using XSAVE variant instructions.
    • +
  • Efficiently pack objects for fastpath.
    • +
  • Increase IPI words to 3.
    • +
  • Support for x2APIC.
    • +
  • Support larger XSAVE region sizes.
    • +
  • Change ia32 to use fs register for IPC buffer.
    • +
  • Update the bootinfo for number of cores.
    • +
  • Initial support for SMP vt-x.
    • +
  • Split CPU ID management into mode and general.
    • +
  • Fix cpuid family/model composition.
    • +
  • Add X86_64 support.
    • +
+ +

Implementation improvements

+ +
    +
  • Several enhancements for both x86 and ARM have +been made. Please see the commit log for details.
    • +
+ +

Upgrade notes

+ + + +

Full changelog

+ +

Use git log 3.2.0..4.0.0 in https://github.com/seL4/seL4

+ +

More details

+ +

See the +4.0.0 manual included in the release for detailed descriptions of the new +features. Or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/5.0.0.html b/releases/sel4/5.0.0.html new file mode 100644 index 00000000000..b4de7e86e67 --- /dev/null +++ b/releases/sel4/5.0.0.html @@ -0,0 +1,607 @@ + + + + + + + 5.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Introducing seL4 5.0.0

+

Announcing the release of seL4 5.0.0 +with the following changes:

+ +

Below are the changes to the seL4 ABI and API:

+ +

Generic changes:

+ +
    +
  • Add missing case to seL4_getFault (seL4_Fault_DebugException)
    • +
  • Explicitly pack bootinfo data structures
    • +
  • Modify FinalizeLog syscall - Now returns a number of entries in the log
    • +
  • Extend bootinfo to support potentially arbitrary additional structures
    • +
  • Deprecate bootinfo management in libsel4 - a replacement, platsupport_get_bootinfo can be found in libsel4platsupport
    • +
+ +

x86 specific changes:

+ +
    +
  • Pass VBE information from multiboot through bootinfo
    • +
  • Remove PAE support
    • +
+ +

x86-64 specific changes:

+ +
    +
  • VT-x related cap and object definitions added
    • +
  • seL4_VMEnter syscall added
    • +
+ +

ARM specific changes:

+ +
    +
  • ARM-HYP: VCPU interface for manipulating banked registers added
    • +
  • plat: added nvidia tx1 support
    • +
  • ARM-HYP: Add support for save/restore of debug registers
    • +
  • Add aarch64 implementation
    • +
+ +

Upgrade notes

+ +
    +
  • This release breaks both API and ABI and is not source compatible + with the earlier versions.
    • +
+ +

Full changelog

+ +

Use git log 4.0.0..5.0.0 in https://github.com/seL4/seL4

+ +

More details

+ +

See the +5.0.0 manual included in the release for detailed descriptions of the new +features. Or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/5.1.0.html b/releases/sel4/5.1.0.html new file mode 100644 index 00000000000..9eeaaccb828 --- /dev/null +++ b/releases/sel4/5.1.0.html @@ -0,0 +1,587 @@ + + + + + + + 5.1.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Introducing seL4 5.1.0

+

Announcing the release of seL4 5.1.0 +with the following changes:

+ +

Below are the changes to the seL4 ABI:

+ +

x86-64 specific changes:

+ +
    +
  • implement seL4_BenchmarkFlushCaches debug syscall.
    • +
+ +

Below are other changes that do not affect the seL4 ABI:

+ +

ARM specific changes:

+
    +
  • ARM-HYP: internal changes to support ARM-HYP verification work.
    • +
  • kzm: fix timer reload overflow calculations
    • +
+ +

Upgrade notes

+ +
    +
  • This release potentially breaks ABI with the earlier versions if + using benchmarking kernel configurations.
    • +
+ +

Full changelog

+ +

Use git log 5.0.0..5.1.0 in https://github.com/seL4/seL4

+ +

More details

+ +

See the +5.1.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/5.2.0-mcs.html b/releases/sel4/5.2.0-mcs.html new file mode 100644 index 00000000000..d414703d6b0 --- /dev/null +++ b/releases/sel4/5.2.0-mcs.html @@ -0,0 +1,787 @@ + + + + + + + 5.2.0 Mcs | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 MCS pre-release (5.2.0-mcs)

+ +

This is a pre-release of the seL4 mixed-criticality systems (RT) +extensions. This branch is not verified and is under active +verification. This is a subset of the previously released RT extensions, +which still exist and can be provided on request.

+ +

Highlights

+ +

The goals of the MCS kernel is to provide strong temporal isolation and +a basis for reasoning about time.

+ +

IPC & Signal ordering

+ +

Signal and IPC delivery is now priority ordered and FIFO within a +priority, rather than plain FIFO

+ +

Scheduling contexts

+ +

This branch adds scheduling contexts to seL4, which represent CPU time +(as budget/period). Scheduling contexts are separate from threads +(although threads require one to run) and can be passed around over IPC, +if the target of an IPC does not have its own scheduling context.

+ +

Scheduling contexts allow developers to create periodic threads, +temporally isolate threads and have variable timeslices for round robin +threads. If budget == period, the scheduling context acts as timeslice +and the thread it is bound to is treated as round-robin.

+ +

Periodic scheduling

+ +

Periodic threads can be created by binding them to scheduling contexts +with a budget < period. seL4_Yield for these threads will sacrifice +the remaining budget until the next period.

+ +

Isolation through sporadic servers

+ +

Temporal isolation is provided with scheduling context by an +implementation of +sporadic servers. Please see the manual or tutorial for further +explanation.

+ +

However, in seL4, threads without budget left in their sporadic server +are not runnable at all - this is used to provide an absolute cap on CPU +time executed by a scheduling context. More complex scheduling +algorithms can be implemented at user-level.

+ +

Scheduling contexts are of a variable size, allowing for a variable +maximum number of sporadic replenishment (termed refills in the API for +brevity) pre scheduling context object.

+ +

Passive Servers

+ +

Passive servers run on their clients scheduling context, as the do not +have one of their own. This allows for basic temporal isolation of +shared resources, however clients must provide enough budget for the +server to finish the request. Further extensions in future add timeout +exceptions, which allows a passive server to detect and recover from an +overrun, however they are not included in this release.

+ +

Threads can be converted to passive by removing their scheduling context +while they are waiting on an endpoint. Then, any calling threads will +automatically donate their scheduling context to this thread when they +send it an IPC.

+ +

Reply objects

+ +

Reply objects are a new object in the API which serve two purposes:

+ +
    +
  • They provide a container for the once-off reply capability + generated by a seL4_Call to be stored. This means that the reply + cap is always saved and cannot be overridden as it is no longer + stored in the internal CNode of a TCB, and seL4_CNode_SaveCaller + no longer needs to be used.
    • +
  • They track scheduling context donation over IPC to + passive servers.
    • +
+ +

MCS ABI and libsel4

+ +

This section documents kernel ABI and libsel4 changes as compared with +seL4 5.2.0.

+ +

Changes

+ +
    +
  • seL4_TCB_Configure arguments changed (scheduling context + cap added).
    • +
  • seL4_Recv, seL4_ReplyRecv, seL4_NBRecv now take a reply object + such that the caller can receive a call. The reply capability is + generated in the reply object, rather than being saved into the + TCB CNode internally. seL4_Call must be paired with seL4_Recv - + and seL4_CNode_SaveCaller is no longer required.
    • +
  • seL4_Wait, seL4_NBWait and variants do not require a reply + object and can be paired with seL4_Send on endpoints + and notifications. Instead of being an API wrapper, this is now a + real system call.
    • +
  • the x86 kernel ABI now only has 1 message register, due to the + need to store the reply object.
    • +
  • seL4_MsgLengthBits increased - this increases amount of caps can + be sent per message.
    • +
  • seL4_MsgMaxLength is now 115, as a result.
    • +
  • seL4_NotificationBits - increased.
    • +
+ +

API Additions

+ +

Constants

+ +
    +
  • seL4_SchedContextObject - new object for that allows threads + access to CPU time
    • +
  • seL4_MinSchedContextBits - minimum size n (2\^n) of a scheduling + context object
    • +
  • seL4_CoreSchedContextBytes - the amount of bytes required for the + fields in a scheduling context that are not sporadic refills.
    • +
  • seL4_RefillSizeBytes - the size of a single refill. Together with + the above, these can be used to determine the number of refills + that will fit in a scheduling context object of a certain size.
    • +
  • seL4_ReplyObject - new object to track scheduling context + donation over IPC and store reply capabilities.
    • +
  • seL4_ReplyObjectBits - size of a reply object (2\^n).
    • +
  • seL4_CapInitThreadSC - capability to the initial threads + scheduling context
    • +
+ +

System calls

+ +
    +
  • seL4_NBSendRecv - new system call which allows a single kernel + invocation to perform a non-blocking send on one capability, and + recieve on another.
    • +
  • seL4_NBSendRecvWithMRs - uses above new system call without + touching the IPC buffer, passing only data in registers
    • +
  • seL4_NBSendWait - new system call which allows a single kernel + invocation to perform a non-blocking send on one capability, and + wait on another (no reply object).
    • +
  • seL4_NBSendWaitWithMRs - uses above new system call without + touching the IPC buffer, passing only data in registers
    • +
  • seL4_SchedControl_Configure - invokes the scheduling control cap + to populate a scheduling context with parameters
    • +
  • seL4_SchedContext_Bind - bind a TCB to a scheduling context, if + the TCB is runnable and scheduling context has budget, this will + start the TCB running
    • +
  • seL4_SchedContext_Unbind - remove binding of a scheduling + context from a TCB, TCB will no longer run but state will be + preserved
    • +
  • seL4_SchedContext_Unbind Object - remove binding of a scheduling + context from a TCB, TCB will no longer run but state will be + preserved
    • +
  • seL4_Wait - block on an endpoint or notification without + providing a reply object. Can be paired with seL4_Send but + not seL4_Call.
    • +
  • seL4_NBWait - a non-blocking variant of the above.
    • +
  • seL4_WaitWithMRs - a variant of seL4_Wait that does not touch + the IPC buffer.
    • +
+ +

libsel4

+ +
    +
  • seL4_SetReserved, seL4_GetReserved: set a reserved word in + the IPC buffer that may be used by the kernel ABI for arguments + that do not fit into registers.
    • +
  • seL4_MaxExtraRefills is provided to allow users to calculate the + maximum number of extra refills for a specific scheduling + context size.
    • +
  • seL4_Time: type for specifying time arguments.
    • +
+ +

Structures

+ +
    +
  • A sched control capability is provided to the root task per node + via the seL4_BootInfo structure.
    • +
+ +

Deletions

+ +
    +
  • seL4_CNode_SaveCaller (deprecated by reply objects)
    • +
  • seL4_Reply (replaced by invoking a reply object)
    • +
  • seL4_ReplyWithMRs (as above)
    • +
+ +

Library & test compatability

+ +
    +
  • CAmkES and CapDL both support seL4 5.2.0-mcs on their + master branches.
    • +
  • seL4_libs and sel4test both have 5.2.0-mcs-compatible branches + that work with the forked API
    • +
  • You can obtain and run sel4test for seL4 5.2.0-mcs by doing the + following:
    • +
+ +
mkdir sel4test-mcs $ cd sel4test-mcs
+repo init -u <https://github.com/seL4/sel4test-manifest.git> -m 5.2.x-mcs.xml
+repo sync
+
+ + + +

Hardware support

+ +

The RT kernel currently supports:

+ + + +

Other hardware platforms will be added as required (the ports require +updated kernel and user-level timer drivers)

+ +

More details

+ +

See the 5.2.0-mcs manual included in the release.

+ +

We have developed a branch of the seL4 and CAmkES tutorials for the MCS +kernel.

+ +
    +
  • seL4 MCS tutorial a new tutorial which covers all of the + API changes and features is available here.
    • +
  • Tutorials Otherwise it’s worth going through all of the + tutorials, as all have been ported to the MCS kernel on the + ‘mcs’ branch.
    • +
+ + +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/5.2.0.html b/releases/sel4/5.2.0.html new file mode 100644 index 00000000000..eff3134174c --- /dev/null +++ b/releases/sel4/5.2.0.html @@ -0,0 +1,588 @@ + + + + + + + 5.2.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Introducing seL4 5.2.0

+

Announcing the release of seL4 5.2.0 +with the following changes:

+ +

Below are the changes to libsel4:

+ +
    +
  • Add seL4_FastMessageRegisters: Exposes number of registers used + in IPC for more optimised user-level IPC stubs.
    • +
  • Additional kernel entry types VMExit and VCPUFault added for + benchmarking kernel entries.
    • +
+ +

x86 specific changes:

+ +
    +
  • multiboot memory map information passed to user-level through + bootinfo extended regions
    • +
  • Expose more seL4 constants
    • +
+ +

Upgrade notes

+ +
    +
  • This release potentially breaks ABI with the earlier versions if + using benchmarking kernel configurations.
    • +
+ +

Full changelog

+ +

Use git log 5.1.0..5.2.0 in https://github.com/seL4/seL4

+ +

More details

+ +

See the +5.2.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/6.0.0.html b/releases/sel4/6.0.0.html new file mode 100644 index 00000000000..413cd627a43 --- /dev/null +++ b/releases/sel4/6.0.0.html @@ -0,0 +1,629 @@ + + + + + + + 6.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 6.0.0 Release

+

Announcing the release of seL4 6.0.0 with the following changes:

+ +

Highlights

+ +

ARM 32-bit SMP

+ +
    +
  • Works (and tested) only on Sabre/ARM with up to 4 cores.
    • +
  • Using the big kernel lock (same as x86 implementation).
    • +
  • Boot core is assumed to have an ID of 0.
    • +
  • Kernel bootstraps and initialises data structures only on the boot core.
    • +
  • Root task proceeds on the boot core.
    • +
  • Cores are assumed to have linear IDes.
    • +
+ +

ARM IPI caveats:

+ +
    +
  • Reserving the first two per-core SGIs for seL4’s IPI operations: 0 + to do a remote call, 1 to reschedule.
    • +
  • Relying on GIC.
    • +
  • Reschedule IPIs are sent when migrating a thread.
    • +
  • Remote call IPIs are sent if TLB and/or cache maintenance + operations are required.
    • +
  • Remote FPU operations (when migrating threads that use HW FPU).
    • +
+ +

ARM FPU

+

ARMv7 32-bit support is added to implement a lazy FP save/restore +mechanism, required for user threads when they use the FPU. The +following caveats exist:

+ +
    +
  • Only support synchronous exceptions. No support for asynchronous ones.
    • +
  • VFP opcodes are used instead of normal instructions to discard + compiler warnings/errors.
    • +
  • Support is limited to specific ARM subarchitectures we support and + tested this feature on.
    • +
  • Disable the FPU by default if users are not using it to + avoid channels.
    • +
  • FPU support is not verified yet.
    • +
  • Will not work properly if using a VM that’s running alongside + other VMs/threads that are using the FPU.
    • +
  • Any trapped FPU instruction (e.g. traps that need support code or + deprecated vectored VFP operations) are forwarded to the user as + a fault.
    • +
+ +

Changes

+ +
    +
  • aarch32 - Implement lazy FP save/restore
    • +
  • ARM SMP support
    • +
  • add seL4_DebugDumpScheduler debug syscall
    • +
  • x86: Split large structs into portions (See upgrade notes below)
    • +
  • License fixups
    • +
+ +

Upgrade notes

+ +
    +
  • This release is not source compatible with previous releases.
    • +
  • seL4_DebugDumpScheduler has had its only argument removed as it + was unused.
    • +
  • On x86 some structs in the Bootinfo have been rearranged. This + only affects seL4_VBEModeInfoBlock_t which is used if VESA + BIOS Extensions (VBE) information is being used.
    • +
+ +

Full changelog

+

Use git log 5.2.0..6.0.0 in +https://github.com/seL4/seL4

+ +

More details

+

See the +6.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/7.0.0.html b/releases/sel4/7.0.0.html new file mode 100644 index 00000000000..4bc6475b156 --- /dev/null +++ b/releases/sel4/7.0.0.html @@ -0,0 +1,619 @@ + + + + + + + 7.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 7.0.0 Release

+

Announcing the release of seL4 7.0.0 with the following changes:

+ +

Changes

+ +
    +
  • Support for building standalone ia32 kernel added in e7327fa6df3
    • +
  • ia32: Set sensible defaults for FS and GS selectors in + c2f6d48bcf2
    • +
  • aarch64: Use tpidrro_el0 for IPC buffer instead of tpidr_el0 + in ae9fe9b5d18
    • +
  • More seL4 manual documentation added for aarch64 object + invocations
    • +
  • Default NUM_DOMAINS set to 16 for x86-64 standalone builds in + baa9798f793
    • +
  • libsel4: Return seL4_Error in invocation stubs in 8fb06eecff9 + ** This is a source code level breaking change **
    • +
  • Add a CMake based build system in 0b73072016e
    • +
  • x86: Increase TCB size for debug builds in 4c8be8f4f91
    • +
  • libsel4: x86: Remove nested struct declarations in a8d6315eb16 + ** This is a source code level breaking change **
    • +
  • Bugfix: x86: Unmap pages when delete non final frame caps in + 08b9265563a
    • +
+ +

Notable changes

+ +
    +
  • CMake based build system added: Initial experimental support has + been added for using CMake for building the kernel and some user + level libraries. Currently the only project that takes advantage + of this is seL4test when using the cmake.xml manifest + in sel4test-manifest. Documentation can be found at: + https://github.com/seL4/seL4_tools/tree/master/cmake-tool
    • +
+ +

Upgrade notes

+ +
    +
  • This release is not source compatible with previous releases.
    • +
  • seL4 invocations that previously returned long now return + seL4_Error which is an enum. Our libraries have already been + updated to reflect this change, but in other places where seL4 + invocations are used directly, the return types will need to be + updated to reflect this change.
    • +
  • On x86 some structs in the Bootinfo have been rearranged. This + only affects seL4_VBEModeInfoBlock_t which is used if VESA + BIOS Extensions (VBE) information is being used.
    • +
+ +

Known issues

+ +
    +
  • One of our tests is non-deterministicly becoming unresponsive on + the SMP release build on the Sabre IMX.6 platform, which is a + non verified configuration of the kernel. We are working on + fixing this problem, and will likely do a point release once it + is fixed.
    • +
+ +

Full changelog

+

Use git log 6.0.0..7.0.0 in +https://github.com/seL4/seL4

+ +

More details

+

See the +7.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/8.0.0.html b/releases/sel4/8.0.0.html new file mode 100644 index 00000000000..5e08a65ef26 --- /dev/null +++ b/releases/sel4/8.0.0.html @@ -0,0 +1,597 @@ + + + + + + + 8.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 8.0.0 Release

+

Announcing the release of seL4 8.0.0 with the following changes:

+ +

Changes

+ +
    +
  • Support for additional zynq platform Zynq UltraScale+ MPSoC + (Xilinx ZCU102, ARMv8a, Cortex A53)
    • +
  • Support for multiboot2 bootloaders on x86 (contributed change + from Genode Labs)
    • +
  • Deprecate seL4_CapData_t type and functions related to it
    • +
  • A fastpath improvement means that when there are two runnable + threads and the target thread is the highest priority in the + scheduler, the fastpath will be hit. + Previously the fastpath would not be used on IPC from a + high priority thread to a low priority thread.
    • +
  • As a consequence of the above change, scheduling behaviour +has changed in the case where a non-blocking IPC is sent between two +same priority threads: the sender will be scheduled, rather than the +destination.
    • +
  • Benchmarking support for armv8/aarch64 is now available.
    • +
  • Additional x86 extra bootinfo type for retrieving frame buffer +information from multiboot 2
    • +
  • Debugging option to export x86 Performance-Monitoring Counters to user level
    • +
+ +

Upgrade notes

+ +
    +
  • seL4_CapData_t should be replaced with just seL4_Word. + Construction of badges should just be x instead + of seL4_CapData_Badge_new(x) and guards should + be seL4_CNode_CapData_new(x, y) instead + of seL4_CapData_Guard_new(x, y)
    • +
  • Code that relied on non-blocking IPC to switch between threads + of the same priority may break.
    • +
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 7.0.0..8.0.0

+ +

More details

+

See the +8.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/9.0.0-mcs.html b/releases/sel4/9.0.0-mcs.html new file mode 100644 index 00000000000..76e3a327010 --- /dev/null +++ b/releases/sel4/9.0.0-mcs.html @@ -0,0 +1,807 @@ + + + + + + + 9.0.0 Mcs | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 MCS pre-release (9.0.0-mcs)

+ +

This is a pre-release of the seL4 mixed-criticality systems (RT) +extensions. This branch is not verified and is under active +verification. This is a subset of the previously released RT extensions, +which still exist and can be provided on request.

+ +

Highlights

+ +

The goals of the MCS kernel is to provide strong temporal isolation and +a basis for reasoning about time.

+ +

IPC & Signal ordering

+ +

Signal and IPC delivery is now priority ordered and FIFO within a +priority, rather than plain FIFO

+ +

Scheduling contexts

+ +

This branch adds scheduling contexts to seL4, which represent CPU time +(as budget/period). Scheduling contexts are separate from threads +(although threads require one to run) and can be passed around over IPC, +if the target of an IPC does not have its own scheduling context.

+ +

Scheduling contexts allow developers to create periodic threads, +temporally isolate threads and have variable timeslices for round robin +threads. If budget == period, the scheduling context acts as timeslice +and the thread it is bound to is treated as round-robin.

+ +

Periodic scheduling

+ +

Periodic threads can be created by binding them to scheduling contexts +with a budget < period. seL4_Yield for these threads will sacrifice +the remaining budget until the next period.

+ +

Isolation through sporadic servers

+ +

Temporal isolation is provided with scheduling context by an +implementation of +sporadic servers. Please see the manual or tutorial for further +explanation.

+ +

However, in seL4, threads without budget left in their sporadic server +are not runnable at all - this is used to provide an absolute cap on CPU +time executed by a scheduling context. More complex scheduling +algorithms can be implemented at user-level.

+ +

Scheduling contexts are of a variable size, allowing for a variable +maximum number of sporadic replenishment (termed refills in the API for +brevity) pre scheduling context object.

+ +

Passive Servers

+ +

Passive servers run on their clients scheduling context, as the do not +have one of their own. This allows for basic temporal isolation of +shared resources, however clients must provide enough budget for the +server to finish the request. Further extensions in future add timeout +exceptions, which allows a passive server to detect and recover from an +overrun, however they are not included in this release.

+ +

Threads can be converted to passive by removing their scheduling context +while they are waiting on an endpoint. Then, any calling threads will +automatically donate their scheduling context to this thread when they +send it an IPC.

+ +

Reply objects

+ +

Reply objects are a new object in the API which serve two purposes:

+ +
    +
  • They provide a container for the once-off reply capability + generated by a seL4_Call to be stored. This means that the reply + cap is always saved and cannot be overridden as it is no longer + stored in the internal CNode of a TCB, and seL4_CNode_SaveCaller + no longer needs to be used.
    • +
  • They track scheduling context donation over IPC to + passive servers.
    • +
+ +

MCS ABI and libsel4

+ +

This section documents kernel ABI and libsel4 changes as compared with +seL4 9.0.0.

+ +

Changes

+ +
    +
  • seL4_TCB_Configure arguments changed (fault ep removed)
    • +
  • seL4_TCB_SetSchedParams also sets scheduling context, and fault endpoint. The fault endpoint is +a capability in the current thread’s cspace, unlike on the master kernel, where it is in the +target thread’s cspace.
    • +
  • seL4_Recv, seL4_ReplyRecv, seL4_NBRecv now take a reply object + such that the caller can receive a call. The reply capability is + generated in the reply object, rather than being saved into the + TCB CNode internally. seL4_Call must be paired with seL4_Recv - + and seL4_CNode_SaveCaller is no longer required.
    • +
  • seL4_Wait, seL4_NBWait and variants do not require a reply + object and can be paired with seL4_Send on endpoints + and notifications. Instead of being an API wrapper, this is now a + real system call.
    • +
  • the x86 kernel ABI now only has 1 message register, due to the + need to store the reply object.
    • +
  • seL4_MsgLengthBits increased - this increases amount of caps can + be sent per message.
    • +
  • seL4_MsgMaxLength is now 115, as a result.
    • +
  • seL4_NotificationBits - increased.
    • +
+ +

API Additions

+ +

Constants

+ +
    +
  • seL4_SchedContextObject - new object for that allows threads + access to CPU time
    • +
  • seL4_MinSchedContextBits - minimum size n (2\^n) of a scheduling + context object
    • +
  • seL4_CoreSchedContextBytes - the amount of bytes required for the + fields in a scheduling context that are not sporadic refills.
    • +
  • seL4_RefillSizeBytes - the size of a single refill. Together with + the above, these can be used to determine the number of refills + that will fit in a scheduling context object of a certain size.
    • +
  • seL4_ReplyObject - new object to track scheduling context + donation over IPC and store reply capabilities.
    • +
  • seL4_ReplyObjectBits - size of a reply object (2\^n).
    • +
  • seL4_CapInitThreadSC - capability to the initial threads + scheduling context
    • +
+ +

System calls

+ +
    +
  • seL4_NBSendRecv - new system call which allows a single kernel + invocation to perform a non-blocking send on one capability, and + recieve on another.
    • +
  • seL4_NBSendRecvWithMRs - uses above new system call without + touching the IPC buffer, passing only data in registers
    • +
  • seL4_NBSendWait - new system call which allows a single kernel + invocation to perform a non-blocking send on one capability, and + wait on another (no reply object).
    • +
  • seL4_NBSendWaitWithMRs - uses above new system call without + touching the IPC buffer, passing only data in registers
    • +
  • seL4_SchedControl_Configure - invokes the scheduling control cap + to populate a scheduling context with parameters
    • +
  • seL4_SchedContext_Bind - bind a TCB to a scheduling context, if + the TCB is runnable and scheduling context has budget, this will + start the TCB running
    • +
  • seL4_SchedContext_Unbind - remove binding of a scheduling + context from a TCB, TCB will no longer run but state will be + preserved
    • +
  • seL4_SchedContext_Unbind Object - remove binding of a scheduling + context from a TCB, TCB will no longer run but state will be + preserved
    • +
  • seL4_Wait - block on an endpoint or notification without + providing a reply object. Can be paired with seL4_Send but + not seL4_Call.
    • +
  • seL4_NBWait - a non-blocking variant of the above.
    • +
  • seL4_WaitWithMRs - a variant of seL4_Wait that does not touch + the IPC buffer.
    • +
+ +

Invocations

+ +
    +
  • seL4_TCBSetTimeoutEndpoint - new TCB invocation which allows a timeout endpoint to be set for a +TCB.
    • +
  • seL4_SchedControl_Configure - allows scheduling context parameters to be set.
    • +
  • seL4_SchedContext_Bind - Allows a notification or TCB object to be bound to a scheduling context +object.
    • +
  • seL4_SchedContext_Unbind - Unbind any object bound to a scheduling context.
    • +
  • seL4_SchedContext_UnbindObject - Unbind a specific object from a scheduling context.
    • +
  • seL4_SchedContext_Consumed - Read and reset the amount of time consumed from scheduling +context.
    • +
  • seL4_SchedContext_YieldTo - Place the active thread bound to this scheduling context at the head +of the scheduling queue for its priority. Read and reset the amount of time consumed.
    • +
+ +

libsel4

+ +
    +
  • seL4_SetReserved, seL4_GetReserved: set a reserved word in + the IPC buffer that may be used by the kernel ABI for arguments + that do not fit into registers.
    • +
  • seL4_MaxExtraRefills is provided to allow users to calculate the + maximum number of extra refills for a specific scheduling + context size.
    • +
  • seL4_Time: type for specifying time arguments.
    • +
  • seL4_isTimeoutFault_tag: detect a timeout fault message.
    • +
  • seL4_TimeoutReply_new: construct a reply to a timeout fault message.
    • +
+ +

Structures

+ +
    +
  • A sched control capability per core is provided to the root task per node + via the seL4_BootInfo structure.
    • +
+ +

Deletions

+ +
    +
  • seL4_CNode_SaveCaller (deprecated by reply objects)
    • +
  • seL4_Reply (replaced by invoking a reply object)
    • +
  • seL4_ReplyWithMRs (as above)
    • +
+ +

Library & test compatability

+ +
    +
  • CAmkES and CapDL both support seL4 9.0.0-mcs on their + master branches.
    • +
  • seL4_libs and sel4test both have 9.0.0-mcs-compatible branches + that work with the forked API
    • +
  • You can obtain and run sel4test for seL4 9.0.0-mcs by doing the + following:
    • +
+ +
mkdir sel4test-mcs $ cd sel4test-mcs
+repo init -u <https://github.com/seL4/sel4test-manifest.git> -m 9.0.x-mcs.xml
+repo sync
+
+ + + +

Hardware support

+ +

The RT kernel currently supports:

+ + + +

Other hardware platforms will be added as required (the ports require +updated kernel and user-level timer drivers)

+ +

More details

+ +

See the 9.0.0-mcs manual included in the release.

+ +

We have developed a branch of the seL4 and CAmkES tutorials for the MCS +kernel.

+ +
    +
  • seL4 MCS tutorial a new tutorial which covers all of the + API changes and features is available here.
    • +
  • Tutorials Otherwise it’s worth going through all of the + tutorials, as all have been ported to the MCS kernel on the + ‘mcs’ branch.
    • +
+ + +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/9.0.0.html b/releases/sel4/9.0.0.html new file mode 100644 index 00000000000..dd5befb8c4d --- /dev/null +++ b/releases/sel4/9.0.0.html @@ -0,0 +1,609 @@ + + + + + + + 9.0.0 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 9.0.0 Release

+

Announcing the release of seL4 9.0.0 with the following changes:

+ +

9.0.0 2018-04-11: BREAKING

+ +

Changes

+
    +
  • Debugging option on x86 for syscall interface to read/write MSRs (this is an, equally dangerous, alternative to +dangerous code injection)
    • +
  • Mitigation for Meltdown (https://meltdownattack.com) on x86-64 implemented. Mitigation is via a form of kernel +page table isolation through the use of a Static Kernel Image with Microstate (SKIM) window that is used for +trapping to and from the kernel address space. This can be enabled/disabled through the build configuration +depending on whether you are running on vulnerable hardware or not.
    • +
  • Mitigation for Spectre (https://spectreattack.com) on x86 against the kernel implemented. Default is software +mitigation and is the best performing so users need to do nothing. This does not prevent user processes from +exploiting each other.
    • +
  • x86 configuration option for performing branch prediction barrier on context switch to prevent Spectre style +attacks between user processes using the indirect branch predictor
    • +
  • x86 configuration option for flushing the RSB on context switch to prevent Spectre style attacks between user +processes using the RSB
    • +
  • Define extended bootinfo header for the x86 TSC frequency
    • +
  • x86 TSC frequency exported in extended bootinfo header
    • +
  • archInfo is no longer a member of the bootinfo struct. Its only use was for TSC frequency on x86, which +can now be retrieved through the extended bootinfo
    • +
  • Invocations to set thread priority and maximum control priority (MCP) have changed. +
      +
    • For both invocations, users must now provide a TCB capability auth
      • +
    • The requested MCP/priority is checked against the MCP of the auth capability.
      • +
    • Previous behavior checked against the invoked TCB, which could be subject to the confused deputy +problem.
      • +
    +
    • +
  • seL4_TCB_Configure no longer takes prio, mcp as an argument. Instead these fields must be set separately +with seL4_TCB_SetPriority and seL4_TCB_SetMCPriority.
    • +
  • seL4_TCB_SetPriority and seL4_TCB_SetMCPriority now take seL4_Word instead of seL4_Uint8. + - seL4_MaxPrio remains at 255.
    • +
  • seL4_TCB_SetSchedParams is a new method where MCP and priority can be set in the same sytsem call.
    • +
  • Size of the TCB object is increased for some build configurations
    • +
+ +

Upgrade notes

+
    +
  • seL4_TCB_Configure calls that set priority should be changed to explicitly call seL4_TCB_SetSchedParams +or SetPriority
    • +
  • seL4_TCB_Configure calls that set MCP should be changed to explicitly call seL4_TCB_SetSchedParams +or seL4_TCB_SetMCPriority
    • +
+ +
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 8.0.0..9.0.0

+ +

More details

+

See the +9.0.0 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/releases/sel4/9.0.1.html b/releases/sel4/9.0.1.html new file mode 100644 index 00000000000..d13ccbf2bfc --- /dev/null +++ b/releases/sel4/9.0.1.html @@ -0,0 +1,583 @@ + + + + + + + 9.0.1 | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

seL4 Version 9.0.1 Release

+

Announcing the release of seL4 9.0.1 with the following changes:

+ +

9.0.1 2018-04-18: BINARY COMPATIBLE

+ +

Changes

+
    +
  • On 64-bit architectures, the label field of seL4_MessageInfo is now 52 bits wide. User-level programs +which use any of the following functions may break, if the program relies on these functions to mask the +label field to the previous width of 20 bits. For more detail, see our +explanation on the seL4 mailing list. +
      +
    • seL4_MessageInfo_new
      • +
    • seL4_MessageInfo_get_label
      • +
    • seL4_MessageInfo_set_label
      • +
    +
    • +
  • Initial prototype RISC-V architecture port. This port currently only supports running in 64-bit mode without FPU or +or multicore support on the Spike simulation platform. There is no verification for this platform.
    • +
+ +

Upgrade Notes

+
+ +

Full changelog

+

Refer to the git log in +https://github.com/seL4/seL4 using git log 9.0.0..9.0.1

+ +

More details

+

See the +9.0.1 manual included in the release or ask on the mailing list!

+ +

Other releases

+

+ See the + full list of seL4 releases. +

+
+ +
+
+ + + +
+
+
+ + diff --git a/robots.txt b/robots.txt new file mode 100644 index 00000000000..7d1a5de3d32 --- /dev/null +++ b/robots.txt @@ -0,0 +1 @@ +Sitemap: https://docs.sel4.systems/sitemap.xml diff --git a/seL4DriverAPI/AddressingOtherDevices.html b/seL4DriverAPI/AddressingOtherDevices.html new file mode 100644 index 00000000000..74aa5779987 --- /dev/null +++ b/seL4DriverAPI/AddressingOtherDevices.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/seL4DriverAPI/ChildEnumeration.html b/seL4DriverAPI/ChildEnumeration.html new file mode 100644 index 00000000000..3c83cbe420b --- /dev/null +++ b/seL4DriverAPI/ChildEnumeration.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/seL4DriverAPI/DriverManagement.html b/seL4DriverAPI/DriverManagement.html new file mode 100644 index 00000000000..78a346f356f --- /dev/null +++ b/seL4DriverAPI/DriverManagement.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/seL4ManualAPIGeneration.html b/seL4ManualAPIGeneration.html new file mode 100644 index 00000000000..66c041292ee --- /dev/null +++ b/seL4ManualAPIGeneration.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/seL4SharedDataWithCaps.html b/seL4SharedDataWithCaps.html new file mode 100644 index 00000000000..1dadc82ff72 --- /dev/null +++ b/seL4SharedDataWithCaps.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/seL4Test.html b/seL4Test.html new file mode 100644 index 00000000000..b38d9f0fec8 --- /dev/null +++ b/seL4Test.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release.html b/sel4_release.html new file mode 100644 index 00000000000..a2ea1d67c38 --- /dev/null +++ b/sel4_release.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_0.0.1-rt-dev.html b/sel4_release/seL4_0.0.1-rt-dev.html new file mode 100644 index 00000000000..9913995ff7a --- /dev/null +++ b/sel4_release/seL4_0.0.1-rt-dev.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_0.0.1-rt-dev/index.html b/sel4_release/seL4_0.0.1-rt-dev/index.html new file mode 100644 index 00000000000..9913995ff7a --- /dev/null +++ b/sel4_release/seL4_0.0.1-rt-dev/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_1.0.0-rt-dev.html b/sel4_release/seL4_1.0.0-rt-dev.html new file mode 100644 index 00000000000..ec55a7b9a06 --- /dev/null +++ b/sel4_release/seL4_1.0.0-rt-dev.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_1.0.0-rt-dev/index.html b/sel4_release/seL4_1.0.0-rt-dev/index.html new file mode 100644 index 00000000000..ec55a7b9a06 --- /dev/null +++ b/sel4_release/seL4_1.0.0-rt-dev/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_10.0.0.html b/sel4_release/seL4_10.0.0.html new file mode 100644 index 00000000000..421cecaef28 --- /dev/null +++ b/sel4_release/seL4_10.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_10.0.0/index.html b/sel4_release/seL4_10.0.0/index.html new file mode 100644 index 00000000000..421cecaef28 --- /dev/null +++ b/sel4_release/seL4_10.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_10.1.0.html b/sel4_release/seL4_10.1.0.html new file mode 100644 index 00000000000..3168f4eab31 --- /dev/null +++ b/sel4_release/seL4_10.1.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_10.1.0/index.html b/sel4_release/seL4_10.1.0/index.html new file mode 100644 index 00000000000..3168f4eab31 --- /dev/null +++ b/sel4_release/seL4_10.1.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_10.1.1-mcs.html b/sel4_release/seL4_10.1.1-mcs.html new file mode 100644 index 00000000000..2eed7b260e6 --- /dev/null +++ b/sel4_release/seL4_10.1.1-mcs.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_10.1.1-mcs/index.html b/sel4_release/seL4_10.1.1-mcs/index.html new file mode 100644 index 00000000000..2eed7b260e6 --- /dev/null +++ b/sel4_release/seL4_10.1.1-mcs/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_10.1.1.html b/sel4_release/seL4_10.1.1.html new file mode 100644 index 00000000000..895fca984cc --- /dev/null +++ b/sel4_release/seL4_10.1.1.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_10.1.1/index.html b/sel4_release/seL4_10.1.1/index.html new file mode 100644 index 00000000000..895fca984cc --- /dev/null +++ b/sel4_release/seL4_10.1.1/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_2.0.0.html b/sel4_release/seL4_2.0.0.html new file mode 100644 index 00000000000..c234085ca02 --- /dev/null +++ b/sel4_release/seL4_2.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_2.0.0/index.html b/sel4_release/seL4_2.0.0/index.html new file mode 100644 index 00000000000..c234085ca02 --- /dev/null +++ b/sel4_release/seL4_2.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_2.1.0.html b/sel4_release/seL4_2.1.0.html new file mode 100644 index 00000000000..cbe8c080647 --- /dev/null +++ b/sel4_release/seL4_2.1.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_2.1.0/index.html b/sel4_release/seL4_2.1.0/index.html new file mode 100644 index 00000000000..cbe8c080647 --- /dev/null +++ b/sel4_release/seL4_2.1.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_3.0.0.html b/sel4_release/seL4_3.0.0.html new file mode 100644 index 00000000000..10bb4129339 --- /dev/null +++ b/sel4_release/seL4_3.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_3.0.0/index.html b/sel4_release/seL4_3.0.0/index.html new file mode 100644 index 00000000000..10bb4129339 --- /dev/null +++ b/sel4_release/seL4_3.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_3.0.1.html b/sel4_release/seL4_3.0.1.html new file mode 100644 index 00000000000..616b3d85533 --- /dev/null +++ b/sel4_release/seL4_3.0.1.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_3.0.1/index.html b/sel4_release/seL4_3.0.1/index.html new file mode 100644 index 00000000000..616b3d85533 --- /dev/null +++ b/sel4_release/seL4_3.0.1/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_3.1.0.html b/sel4_release/seL4_3.1.0.html new file mode 100644 index 00000000000..a336cf18279 --- /dev/null +++ b/sel4_release/seL4_3.1.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_3.1.0/index.html b/sel4_release/seL4_3.1.0/index.html new file mode 100644 index 00000000000..a336cf18279 --- /dev/null +++ b/sel4_release/seL4_3.1.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_3.2.0.html b/sel4_release/seL4_3.2.0.html new file mode 100644 index 00000000000..4c7ef4f76f0 --- /dev/null +++ b/sel4_release/seL4_3.2.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_3.2.0/index.html b/sel4_release/seL4_3.2.0/index.html new file mode 100644 index 00000000000..4c7ef4f76f0 --- /dev/null +++ b/sel4_release/seL4_3.2.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_4.0.0.html b/sel4_release/seL4_4.0.0.html new file mode 100644 index 00000000000..e84c0db4dff --- /dev/null +++ b/sel4_release/seL4_4.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_4.0.0/index.html b/sel4_release/seL4_4.0.0/index.html new file mode 100644 index 00000000000..e84c0db4dff --- /dev/null +++ b/sel4_release/seL4_4.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_5.0.0.html b/sel4_release/seL4_5.0.0.html new file mode 100644 index 00000000000..006c615096a --- /dev/null +++ b/sel4_release/seL4_5.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_5.0.0/index.html b/sel4_release/seL4_5.0.0/index.html new file mode 100644 index 00000000000..006c615096a --- /dev/null +++ b/sel4_release/seL4_5.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_5.1.0.html b/sel4_release/seL4_5.1.0.html new file mode 100644 index 00000000000..8a5ee0dcd42 --- /dev/null +++ b/sel4_release/seL4_5.1.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_5.1.0/index.html b/sel4_release/seL4_5.1.0/index.html new file mode 100644 index 00000000000..8a5ee0dcd42 --- /dev/null +++ b/sel4_release/seL4_5.1.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_5.2.0-mcs.html b/sel4_release/seL4_5.2.0-mcs.html new file mode 100644 index 00000000000..fdc50a5fbf3 --- /dev/null +++ b/sel4_release/seL4_5.2.0-mcs.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_5.2.0-mcs/index.html b/sel4_release/seL4_5.2.0-mcs/index.html new file mode 100644 index 00000000000..fdc50a5fbf3 --- /dev/null +++ b/sel4_release/seL4_5.2.0-mcs/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_5.2.0.html b/sel4_release/seL4_5.2.0.html new file mode 100644 index 00000000000..3b20aaefc20 --- /dev/null +++ b/sel4_release/seL4_5.2.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_5.2.0/index.html b/sel4_release/seL4_5.2.0/index.html new file mode 100644 index 00000000000..3b20aaefc20 --- /dev/null +++ b/sel4_release/seL4_5.2.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_6.0.0.html b/sel4_release/seL4_6.0.0.html new file mode 100644 index 00000000000..2de156f6e9a --- /dev/null +++ b/sel4_release/seL4_6.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_6.0.0/index.html b/sel4_release/seL4_6.0.0/index.html new file mode 100644 index 00000000000..2de156f6e9a --- /dev/null +++ b/sel4_release/seL4_6.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_7.0.0.html b/sel4_release/seL4_7.0.0.html new file mode 100644 index 00000000000..1c146d30104 --- /dev/null +++ b/sel4_release/seL4_7.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_7.0.0/index.html b/sel4_release/seL4_7.0.0/index.html new file mode 100644 index 00000000000..1c146d30104 --- /dev/null +++ b/sel4_release/seL4_7.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_8.0.0.html b/sel4_release/seL4_8.0.0.html new file mode 100644 index 00000000000..90f068baf15 --- /dev/null +++ b/sel4_release/seL4_8.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_8.0.0/index.html b/sel4_release/seL4_8.0.0/index.html new file mode 100644 index 00000000000..90f068baf15 --- /dev/null +++ b/sel4_release/seL4_8.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_9.0.0-mcs.html b/sel4_release/seL4_9.0.0-mcs.html new file mode 100644 index 00000000000..9db1e4fe3d3 --- /dev/null +++ b/sel4_release/seL4_9.0.0-mcs.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_9.0.0-mcs/index.html b/sel4_release/seL4_9.0.0-mcs/index.html new file mode 100644 index 00000000000..9db1e4fe3d3 --- /dev/null +++ b/sel4_release/seL4_9.0.0-mcs/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_9.0.0.html b/sel4_release/seL4_9.0.0.html new file mode 100644 index 00000000000..f160f46942e --- /dev/null +++ b/sel4_release/seL4_9.0.0.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_9.0.0/index.html b/sel4_release/seL4_9.0.0/index.html new file mode 100644 index 00000000000..f160f46942e --- /dev/null +++ b/sel4_release/seL4_9.0.0/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_9.0.1.html b/sel4_release/seL4_9.0.1.html new file mode 100644 index 00000000000..3e3df2c5fbc --- /dev/null +++ b/sel4_release/seL4_9.0.1.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sel4_release/seL4_9.0.1/index.html b/sel4_release/seL4_9.0.1/index.html new file mode 100644 index 00000000000..3e3df2c5fbc --- /dev/null +++ b/sel4_release/seL4_9.0.1/index.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/sitemap.html b/sitemap.html new file mode 100644 index 00000000000..7f722a12092 --- /dev/null +++ b/sitemap.html @@ -0,0 +1,821 @@ + + + + + + + Sitemap | seL4 docs + + + + + + + + + + + + +
+ +
+
+
+ +
+
+ + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
+
+ +
+
+
+
+ +
+

Sitemap

+ +

Pages

+ + + +

Archived Pages

+ + +
+ +
+
+ + + +
+
+
+ + diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 00000000000..8577058eefb --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,891 @@ + + + +https://docs.sel4.systems/releases/camkes/camkes-2.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-2.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-2.2.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-2.3.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-2.3.1.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.10.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.11.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.11.1.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.2.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.3.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.4.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.5.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.6.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.7.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.8.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/camkes/camkes-3.9.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/capdl/0.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/capdl/0.2.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/capdl/0.2.1.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/capdl/0.3.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/capdl/0.4.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/microkit/1.3.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/microkit/1.4.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/microkit/1.4.1.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/microkit/2.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/microkit/2.0.1.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/microkit/2.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/0.0.1-rt-dev.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/1.0.0-rt-dev.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/10.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/10.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/10.1.1-mcs.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/10.1.1.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/11.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/12.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/12.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/13.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/14.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/2.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/2.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/3.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/3.0.1.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/3.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/3.2.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/4.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/5.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/5.1.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/5.2.0-mcs.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/5.2.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/6.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/7.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/8.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/9.0.0-mcs.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/9.0.0.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/releases/sel4/9.0.1.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/buildsystem/11.0.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/camkes-vm/camkes-3.8.x-arm-old.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/camkes-vm/camkes-3.8.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/elfloader/11.0.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/sel4-tutorials/camkes-3.8.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/sel4bench/11.0.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/sel4runtime/11.0.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/sel4test/11.0.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/sel4webserver/camkes-3.8.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/updates/user_libs/11.0.x.html +2026-03-16T04:11:22+00:00 + + +https://docs.sel4.systems/projects/driver_framework/AddressingOtherDevices.html + + +https://docs.sel4.systems/Hardware/BeagleBoard.html + + +https://docs.sel4.systems/Hardware/Beaglebone.html + + +https://docs.sel4.systems/projects/driver_framework/ChildEnumeration.html + + +https://docs.sel4.systems/projects/driver_framework/DriverManagement.html + + +https://docs.sel4.systems/Hardware/GeneralARM.html + + +https://docs.sel4.systems/Hardware/IA32.html + + +https://docs.sel4.systems/Hardware/IF6410.html + + +https://docs.sel4.systems/Hardware/JetsonTX2.html + + +https://docs.sel4.systems/Hardware/Kzm.html + + +https://docs.sel4.systems/Hardware/MaaXBoard.html + + +https://docs.sel4.systems/Hardware/OdroidC2.html + + +https://docs.sel4.systems/Hardware/OdroidC4.html + + +https://docs.sel4.systems/Hardware/OdroidXU.html + + +https://docs.sel4.systems/Hardware/OdroidXU4.html + + +https://docs.sel4.systems/Hardware/Rpi3.html + + +https://docs.sel4.systems/Hardware/Rpi4.html + + +https://docs.sel4.systems/Hardware/X64.html + + +https://docs.sel4.systems/Hardware/ZC706.html + + +https://docs.sel4.systems/Hardware/ZCU102.html + + +https://docs.sel4.systems/Hardware/ZCU106.html + + +https://docs.sel4.systems/projects/sel4/api-doc.html + + +https://docs.sel4.systems/Hardware/ariane.html + + +https://docs.sel4.systems/Hardware/arndale.html + + +https://docs.sel4.systems/Hardware/bananapi-f3.html + + +https://docs.sel4.systems/projects/sel4-tutorials/benchmarking-guide.html + + +https://docs.sel4.systems/projects/sel4/bfgen.html + + +https://docs.sel4.systems/projects/capdl/c-loader-app.html + + +https://docs.sel4.systems/Tutorials/camkes-vm-crossvm.html + + +https://docs.sel4.systems/Tutorials/camkes-vm-linux.html + + +https://docs.sel4.systems/Tutorials/capabilities.html + + +https://docs.sel4.systems/projects/capdl/cdl-utils.html + + +https://docs.sel4.systems/projects/camkes-vm/centos.html + + +https://docs.sel4.systems/Hardware/cheshire.html + + +https://docs.sel4.systems/projects/camkes/cli.html + + +https://docs.sel4.systems/projects/camkes/components.html + + +https://docs.sel4.systems/projects/sel4/configurations.html + + +https://docs.sel4.systems/projects/sel4-tutorials/debugging-guide.html + + +https://docs.sel4.systems/projects/sel4-tutorials/debugging-userspace.html + + +https://docs.sel4.systems/projects/camkes/differences.html + + +https://docs.sel4.systems/processes/docs-contributing.html + + +https://docs.sel4.systems/projects/microkit/tutorial/end.html + + +https://docs.sel4.systems/examples.html + + +https://docs.sel4.systems/Tutorials/fault-handlers.html + + +https://docs.sel4.systems/projects/camkes/features.html + + +https://docs.sel4.systems/Tutorials/get-the-tutorials.html + + +https://docs.sel4.systems/getting-started.html + + +https://docs.sel4.systems/projects/camkes/hardware.html + + +https://docs.sel4.systems/Tutorials/hello-camkes-0.html + + +https://docs.sel4.systems/Tutorials/hello-camkes-1.html + + +https://docs.sel4.systems/Tutorials/hello-camkes-2.html + + +https://docs.sel4.systems/Tutorials/hello-camkes-timer.html + + +https://docs.sel4.systems/Tutorials/hello-world.html + + +https://docs.sel4.systems/Hardware/hifive-p550.html + + +https://docs.sel4.systems/Hardware/hifive.html + + +https://docs.sel4.systems/projects/buildsystem/host-dependencies.html + + +https://docs.sel4.systems/Tutorials/how-to-CAmkES.html + + +https://docs.sel4.systems/Tutorials/how-to-libs.html + + +https://docs.sel4.systems/Tutorials/how-to-seL4.html + + +https://docs.sel4.systems/projects/rust/how-to-use.html + + +https://docs.sel4.systems/Hardware/imx8mm.html + + +https://docs.sel4.systems/Hardware/imx8mp.html + + +https://docs.sel4.systems/Hardware/imx8mq.html + + +https://docs.sel4.systems/Hardware/imx93.html + + +https://docs.sel4.systems/projects/buildsystem/incorporating.html + + +https://docs.sel4.systems/ + + +https://docs.sel4.systems/projects/camkes/visual-camkes/ + + +https://docs.sel4.systems/projects/camkes/ + + +https://docs.sel4.systems/projects/user_libs/ + + +https://docs.sel4.systems/projects/dockerfiles/ + + +https://docs.sel4.systems/projects/sel4bench/ + + +https://docs.sel4.systems/projects/sel4/ + + +https://docs.sel4.systems/projects/sel4test/ + + +https://docs.sel4.systems/projects/hardware_hacks/level-converter/ + + +https://docs.sel4.systems/projects/hardware_hacks/ + + +https://docs.sel4.systems/projects/sel4runtime/ + + +https://docs.sel4.systems/projects/camkes-vm/ + + +https://docs.sel4.systems/projects/elfloader/ + + +https://docs.sel4.systems/projects/rust/ + + +https://docs.sel4.systems/projects/capdl/ + + +https://docs.sel4.systems/projects/microkit/manual/2.1.0/ + + +https://docs.sel4.systems/projects/microkit/manual/latest/ + + +https://docs.sel4.systems/projects/microkit/manual/2.0.1/ + + +https://docs.sel4.systems/projects/microkit/ + + +https://docs.sel4.systems/projects/buildsystem/old/ + + +https://docs.sel4.systems/projects/buildsystem/ + + +https://docs.sel4.systems/CMA34DBMC/ + + +https://docs.sel4.systems/Tutorials/ + + +https://docs.sel4.systems/Hardware/CEI_TK1_SOM/LogicPro8/ + + +https://docs.sel4.systems/Hardware/CEI_TK1_SOM/Tk1SomMods/ + + +https://docs.sel4.systems/Hardware/CEI_TK1_SOM/L4TCan/ + + +https://docs.sel4.systems/Hardware/CEI_TK1_SOM/DaughterBoard/ + + +https://docs.sel4.systems/Hardware/CEI_TK1_SOM/CANBoard/ + + +https://docs.sel4.systems/Hardware/CEI_TK1_SOM/ + + +https://docs.sel4.systems/Hardware/VMware/ + + +https://docs.sel4.systems/Hardware/HiKey/ + + +https://docs.sel4.systems/Hardware/Star64/ + + +https://docs.sel4.systems/Hardware/ + + +https://docs.sel4.systems/projects/camkes/internals.html + + +https://docs.sel4.systems/Tutorials/interrupts.html + + +https://docs.sel4.systems/Tutorials/ipc.html + + +https://docs.sel4.systems/Hardware/jetsontk1.html + + +https://docs.sel4.systems/Hardware/jetsontx1.html + + +https://docs.sel4.systems/projects/sel4/kernel-contribution.html + + +https://docs.sel4.systems/projects/capdl/lang-spec.html + + +https://docs.sel4.systems/Tutorials/libraries-1.html + + +https://docs.sel4.systems/Tutorials/libraries-2.html + + +https://docs.sel4.systems/Tutorials/libraries-3.html + + +https://docs.sel4.systems/Tutorials/libraries-4.html + + +https://docs.sel4.systems/projects/virtualization/docs/libsel4vm.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_arm_guest_vm.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_boot.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_arm_context.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_iospace.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_irq_controller.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_memory.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_memory_helpers.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_ram.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_vcpu_fault.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_vm.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_vm_util.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_guest_x86_context.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_x86_guest_vm.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_x86_ioports.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vm_x86_vmcall.html + + +https://docs.sel4.systems/projects/virtualization/docs/libsel4vmm.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_ac_device.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_generic_forward_device.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_boot_init.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_reboot.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_vcpu_fault.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_guest_vcpu_util.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_vpci.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_arm_vusb.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_cross_vm_connection.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_device.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_device_utils.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_image.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_memory_util.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_guest_vcpu_util.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_ioports.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_pci.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_pci_helper.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_virtio_con.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_virtio_net.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_acpi.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_guest_boot_init.html + + +https://docs.sel4.systems/projects/virtualization/docs/api/libsel4vmmplatsupport_x86_vmm_pci_helper.html + + +https://docs.sel4.systems/projects/camkes/manual.html + + +https://docs.sel4.systems/projects/sel4/manual.html + + +https://docs.sel4.systems/Tutorials/mapping.html + + +https://docs.sel4.systems/Tutorials/mcs.html + + +https://docs.sel4.systems/projects/camkes/next.html + + +https://docs.sel4.systems/Tutorials/notifications.html + + +https://docs.sel4.systems/Hardware/odroidx.html + + +https://docs.sel4.systems/projects/microkit/tutorial/part0.html + + +https://docs.sel4.systems/projects/microkit/tutorial/part1.html + + +https://docs.sel4.systems/projects/microkit/tutorial/part2.html + + +https://docs.sel4.systems/projects/microkit/tutorial/part3.html + + +https://docs.sel4.systems/projects/microkit/tutorial/part4.html + + +https://docs.sel4.systems/projects/microkit/platforms.html + + +https://docs.sel4.systems/Hardware/polarfire.html + + +https://docs.sel4.systems/projects/sel4/porting.html + + +https://docs.sel4.systems/Hardware/qemu-arm-virt.html + + +https://docs.sel4.systems/Hardware/qemu-riscv-virt.html + + +https://docs.sel4.systems/releases/camkes.html + + +https://docs.sel4.systems/releases/seL4.html + + +https://docs.sel4.systems/projects/rust/releases.html + + +https://docs.sel4.systems/releases/capDL.html + + +https://docs.sel4.systems/releases/microkit.html + + +https://docs.sel4.systems/releases.html + + +https://docs.sel4.systems/projects/buildsystem/repo-cheatsheet.html + + +https://docs.sel4.systems/projects/microkit/roadmap.html + + +https://docs.sel4.systems/Hardware/rock3b.html + + +https://docs.sel4.systems/Hardware/rocketchip-zcu102.html + + +https://docs.sel4.systems/Hardware/rocketchip.html + + +https://docs.sel4.systems/Hardware/rockpro64.html + + +https://docs.sel4.systems/Hardware/sabreLite.html + + +https://docs.sel4.systems/Tutorials/seL4-end.html + + +https://docs.sel4.systems/projects/camkes/seL4SharedDataWithCaps.html + + +https://docs.sel4.systems/projects/camkes/setting-up.html + + +https://docs.sel4.systems/projects/microkit/setting-up.html + + +https://docs.sel4.systems/Tutorials/setting-up.html + + +https://docs.sel4.systems/sitemap.html + + +https://docs.sel4.systems/Hardware/spike.html + + +https://docs.sel4.systems/projects/buildsystem/standalone.html + + +https://docs.sel4.systems/projects/rust/supported-configurations.html + + +https://docs.sel4.systems/processes/test-status.html + + +https://docs.sel4.systems/Tutorials/threads.html + + +https://docs.sel4.systems/Hardware/tqma8xqp1gb.html + + +https://docs.sel4.systems/Hardware/ultra96v2.html + + +https://docs.sel4.systems/Tutorials/untyped.html + + +https://docs.sel4.systems/projects/buildsystem/using.html + + +https://docs.sel4.systems/projects/sel4/verified-configurations.html + + +https://docs.sel4.systems/projects/microkit/tutorial/welcome.html + + +https://docs.sel4.systems/projects/camkes-vm/zmq-samples.html + + +https://docs.sel4.systems/Hardware/CEI_TK1_SOM/CANBoard/canboard_v3.pdf +2026-03-16T04:08:54+00:00 + + +https://docs.sel4.systems/Hardware/CEI_TK1_SOM/DaughterBoard/daughterboard_r3a_schematic.pdf +2026-03-16T04:08:54+00:00 + + +https://docs.sel4.systems/projects/microkit/manual/2.0.1/assets/microkit_flow.pdf +2026-03-16T04:08:54+00:00 + + +https://docs.sel4.systems/projects/microkit/manual/2.0.1/microkit_user_manual.pdf +2026-03-16T04:08:54+00:00 + + +https://docs.sel4.systems/projects/microkit/manual/2.1.0/assets/microkit_flow.pdf +2026-03-16T04:08:54+00:00 + + +https://docs.sel4.systems/projects/microkit/manual/2.1.0/microkit_user_manual.pdf +2026-03-16T04:08:54+00:00 + + +https://docs.sel4.systems/projects/microkit/manual/latest/assets/microkit_flow.pdf +2026-03-16T04:08:54+00:00 + + +https://docs.sel4.systems/projects/microkit/manual/latest/microkit_user_manual.pdf +2026-03-16T04:08:54+00:00 + + diff --git a/status/camkes.html b/status/camkes.html new file mode 100644 index 00000000000..bdbe87d44c6 --- /dev/null +++ b/status/camkes.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/status/sel4.html b/status/sel4.html new file mode 100644 index 00000000000..8af3d6ef9c8 --- /dev/null +++ b/status/sel4.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/status/sel4bench.html b/status/sel4bench.html new file mode 100644 index 00000000000..6019cbde303 --- /dev/null +++ b/status/sel4bench.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/status/sel4test.html b/status/sel4test.html new file mode 100644 index 00000000000..8e99b30d39e --- /dev/null +++ b/status/sel4test.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/status/user_libs.html b/status/user_libs.html new file mode 100644 index 00000000000..002f1519fe3 --- /dev/null +++ b/status/user_libs.html @@ -0,0 +1,11 @@ + + + + Redirecting… + + + + +

Redirecting…

+ Click here if you are not redirected. + diff --git a/tools/Dockerfile b/tools/Dockerfile deleted file mode 100644 index 5f8091c23ab..00000000000 --- a/tools/Dockerfile +++ /dev/null @@ -1,38 +0,0 @@ -# Copyright 2020 Data61, CSIRO -# SPDX-License-Identifier: BSD-2-Clause - -FROM ruby:2 - -RUN apt-get update -q \ - && apt-get install -y --no-install-recommends \ - doxygen \ - python3-dev \ - python3-bs4 \ - python3-lxml \ - python3-six \ - python3-jinja2 \ - python3-sh \ - python3-pip \ - python3-pyelftools \ - rsync \ - && apt-get clean autoclean \ - && apt-get autoremove --yes \ - && pip3 install setuptools camkes-deps \ - && rm -rf /var/lib/{apt,dpkg,cache,log}/ - -# Init bundle dependencies -RUN git clone https://github.com/seL4/docs.git \ - && cd docs \ - && bundle install \ - && cd / \ - && rm -rf docs - -RUN curl -sSf https://sh.rustup.rs \ - | bash -s -- -y --no-modify-path - -ENV PATH=/root/.cargo/bin:$PATH - -RUN git config --global --add safe.directory '/docs' - -# Jekyll will be serving on 127.0.0.1:4000 -EXPOSE 4000 diff --git a/tools/gen_markdown_api_doc.py b/tools/gen_markdown_api_doc.py deleted file mode 100755 index d9e812bfcf8..00000000000 --- a/tools/gen_markdown_api_doc.py +++ /dev/null @@ -1,35 +0,0 @@ -#! /usr/bin/env python3 - -# Copyright 2020 Data61, CSIRO -# SPDX-License-Identifier: BSD-2-Clause - -import os -import argparse - -parser = argparse.ArgumentParser() -parser.add_argument("-f", "--file", dest="file", type=str, - help="Markdown location (within repository)") -parser.add_argument("-o", "--output", dest="output", type=str, - help="Output docsite file") -parser.add_argument("-p", "--parent", dest="parent", type=str, - help="Parent file on docsite") -args = parser.parse_args() - -base = os.path.basename(args.file) -title = os.path.splitext(base)[0] -output = '''--- -title: {0} -layout: "api" -toc: true -parent: "/projects/virtualization/docs/{1}" ---- - -{{% capture file %}} -{{% include_absolute {2} %}} -{{% endcapture %}} -{{% assign file = file | replace: '[top](#)', '[top](#page-top)' %}} - -{{{{ file }}}} -'''.format(title, args.parent, args.file) -with open(args.output, "w") as output_file: - output_file.write(output) diff --git a/tools/get_repos.py b/tools/get_repos.py deleted file mode 100755 index 914382077fb..00000000000 --- a/tools/get_repos.py +++ /dev/null @@ -1,23 +0,0 @@ -#! /usr/bin/env python3 - -# Copyright 2020 Data61, CSIRO -# SPDX-License-Identifier: BSD-2-Clause - -import sys -from yaml import load, dump - -# Try use libyaml C bindings first for parsing. Fall back to python implementations -# otherwise. -try: - from yaml import CLoader as Loader -except ImportError: - from yaml import Loader - -# Parse yaml file from stdin and output a newline separated list of repositories -data = load(sys.stdin, Loader=Loader) -try: - if "repositories" in data: - for repo in data["repositories"]: - print(("%s/%s" % (repo["org"], repo["repo"])).lower()) -except: - pass diff --git a/tools/inject_backlink.sh b/tools/inject_backlink.sh deleted file mode 100755 index 182a889978a..00000000000 --- a/tools/inject_backlink.sh +++ /dev/null @@ -1,22 +0,0 @@ -#!/bin/sh - -# Copyright 2025 Proofcraft Pty Ltd -# SPDX-License-Identifier: BSD-2-Clause -# -# Insert a back link to the seL4 docsite into the Rust tutorial. - -if [ $# -ne 1 ]; then - echo "Usage: $0 " - exit 1 -fi - -if [ ! -d "$1" ]; then - echo "'$1' not a directory." - exit 1 -fi - -TOC="$1/toc.js" - -LINK='
  • Back to seL4 docsite' - -sed -i.bak "s|
    • |${LINK}|" "$TOC" diff --git a/tools/mk_tutorial_vars.sh b/tools/mk_tutorial_vars.sh deleted file mode 100755 index 20f2a6f7ae0..00000000000 --- a/tools/mk_tutorial_vars.sh +++ /dev/null @@ -1,28 +0,0 @@ -#!/bin/sh -# -# Copyright 2025 Proofcraft Pty Ltd -# SPDX-License-Identifier: BSD-2-Clause - -# Generate _data/microkit_tutorial.yml from microkit_tutorial repo -# -# Usage: ./mk_tutorial_vars.sh - -if [ $# -ne 2 ]; then - echo "Usage: $0 " - exit 1 -fi - -INPUT_FILE="$1" -DATA_FILE="$2" - -if [ ! -r "$INPUT_FILE" ]; then - echo "Error: $INPUT_FILE is not readable." - exit 1 -fi - -# Conver export VAR="value" to VAR: value -cat $INPUT_FILE | \ - grep -E '^export ' | \ - sed -E 's/^export ([^=]+)=(.*)$/\1: \2/' > $DATA_FILE - -echo "$INPUT_FILE ==> $DATA_FILE" diff --git a/tools/process-mdbook.py b/tools/process-mdbook.py deleted file mode 100755 index e5b151a7bfc..00000000000 --- a/tools/process-mdbook.py +++ /dev/null @@ -1,80 +0,0 @@ -#! /usr/bin/env python3 - -# Copyright 2025 Proofcraft Pty Ltd -# SPDX-License-Identifier: BSD-2-Clause - -# Process mdbook .md files to -# - execute `{{#include "path/to/file.md"}}` directives -# - convert tab directives Jekyll includes used in the docsite -# - convert
    to
    -# - convert {{variable}} to {{site.data.microkit_tutorial.variable}} - -import os -import re -import argparse - - -def inclusion_content(input_path, match): - include_path = match.group(1) - start_line = match.group(2) - end_line = match.group(3) - - full_path = os.path.join(input_path, include_path) - if os.path.exists(full_path): - with open(full_path, 'r', encoding='utf-8') as inc_file: - lines = inc_file.read().splitlines() - if start_line is None: - start_line = 1 - if end_line is None: - end_line = len(lines) - else: - end_line = int(end_line) - # Return the specified lines as a string - return '\n'.join(lines[int(start_line)-1:end_line]) - else: - print(f'Include file {include_path} not found in {input_path}') - return f'' - - -def process_mdbook(input_file, output_dir): - if not os.path.exists(output_dir): - os.makedirs(output_dir) - - # Read entire input file - with open(input_file, 'r', encoding='utf-8') as f: - content = f.read() - - # Process include directives with line numbers - include_pattern = re.compile(r'{{#include[ ]*([^ :]+)(?::(\d+):(\d+))?[ ]*}}') - input_path = os.path.dirname(input_file) - content = re.sub(include_pattern, lambda match: inclusion_content(input_path, match), content) - - # Convert tab directives to Jekyll includes - # {{#tabs }}, {{#endtabs }}, {{#endtab }} - pat = re.compile(r'{{#([a-z]*tabs?)[ ]*}}') - content = re.sub(pat, r'{% include \1.html %}', content) - - # "{{#tab name="Linux" }}" - pat = re.compile(r'{{#tab name="([^"]+)"[ ]*}}') - content = re.sub(pat, r'{% include tab.html title="\1" %}', content) - - # Convert
    to
    - content = re.sub(r'
    ', r'
    ', content) - - # Convert {{variable}} to {{site.data.microkit_tutorial.variable}} - pat = re.compile(r'{{([a-zA-Z0-9_]+)}}') - content = re.sub(pat, r'{{site.data.microkit_tutorial.\1}}', content) - - # Write processed content - output_file = os.path.join(output_dir, os.path.basename(input_file)) - with open(output_file, 'w', encoding='utf-8') as f: - f.write(content) - - -if __name__ == "__main__": - parser = argparse.ArgumentParser(description='Process mdbook .md files for includes and tabs.') - parser.add_argument('input_file', help='Path to the input .md file') - parser.add_argument('output_dir', help='Directory to save the processed output') - - args = parser.parse_args() - process_mdbook(args.input_file, args.output_dir) diff --git a/tools/testWCAG.py b/tools/testWCAG.py deleted file mode 100644 index f2e2fe7c44e..00000000000 --- a/tools/testWCAG.py +++ /dev/null @@ -1,84 +0,0 @@ -#! /usr/bin/env python - -# Copyright 2020 Data61, CSIRO -# SPDX-License-Identifier: BSD-2-Clause - -import sys -from sys import stdin -import requests -import json -from multiprocessing import Pool - -from HTMLParser import HTMLParser -from junit_xml import TestSuite, TestCase - -AATT_SITE_ENDPOINT = "http://localhost:3000/sniffURL" -JEKYLL_SITE_URL = "http://localhost:4000" - - -def run_test(page): - - class SimpleHTMLParser(HTMLParser): - ''' - This pulls out the number of errors which is the data in the span - with class `result-count-errors`. - ''' - get_error = False - num_errors = 0 - - def handle_starttag(self, tag, attrs): - if tag == "span": - for (key, val) in attrs: - if key == "class" and "result-count-errors" in val: - self.get_error = True - - def handle_data(self, data): - if self.get_error: - self.num_errors = data - self.get_error = False - - def get_result(self): - return self.num_errors - - # POST request with url to AATT endpoint - url = AATT_SITE_ENDPOINT - headers = {'content-type': 'application/x-www-form-urlencoded'} - r = requests.post(url, data='engine=htmlcs&msgErr=true&textURL=%s/%s' % - (JEKYLL_SITE_URL, page), headers=headers) - output = json.loads(r.text) - - # Parse result using simple parser to get number of errors. - parser = SimpleHTMLParser() - parser.feed(output['data']) - result = parser.get_result() - - # Put error number into junit TestCase and return to caller. - tc = TestCase(page, 'some.class.name', 1, output['data']) - if (parser.get_result() != "0"): - tc.add_failure_info("Detected %s error(s)." % (parser.get_result())) - return tc - - -def main(): - # Read list of html files in from stdin line by line. - # This is to enable piping result from `find` - # Use a multiprocessing pool to get some parallelism - pool = Pool() - - queries = [] - test_cases = [] - - for line in sys.stdin: - queries.append(pool.apply_async(run_test, [line.strip()])) - - for query in queries: - test_cases.append(query.get(timeout=10)) - - # Dump test results to stdout - ts = [TestSuite("my test suite", test_cases)] - print(TestSuite.to_xml_string(ts)) - return 0 - - -if __name__ == "__main__": - main() diff --git a/updates/buildsystem/11.0.x.html b/updates/buildsystem/11.0.x.html new file mode 100644 index 00000000000..dc352b4f848 --- /dev/null +++ b/updates/buildsystem/11.0.x.html @@ -0,0 +1,650 @@ + + + + + + + seL4 11.0.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to the Build system from seL4 10.1.x to 11.0.x

    + +

    seL4_tools/cmake-tool

    +
      +
    • dts.cmake: Suppress output from dtc unless it doesn’t produce an output file.
      • +
    • application_settings.cmake: Disable kernel printing in release builds.
      • +
    • dts.cmake: Use dts files from the kernel repository.
      • +
    • rootserver.cmake: Support building RISC-V with gcc-8.
      • +
    • Split common.cmake into simulation.cmake, cpio.cmake and rootserver.cmake.
      • +
    • Remove AddLegacyLibrary function. This was used to wrap old build system libraries and is no longer used.
      • +
    • cpio.cmake: Support constructing multiple CPIO archives within the same build directory.
      • +
    • Style all CMake files and python scripts.
      • +
    • Add make.cpio module with MakefileDepsToList, create_depfile_by_find and execute_process_with_stale_check helpers. +These helpers add mechanisms for not re-running expensive execute_process commands during build +configurations if inputs to the command are not stale.
      • +
    • Add cmakerepl script for inline debugging of CMake scripts.
      • +
    • Add debug.cmake that adds set_break() CMake function for limited CMake variable inspection.
      • +
    • Add griddle tool to enable easy build scenarios: +
        +
      • Automatically add additional CMake initialization flags on first init.
        • +
      • Present project build configuration options based on an easy-settings.cmake file.
        • +
      • Detect when CMakeCache.txt file is unstable and re-run cmake until it stabalizes.
        • +
      • Inform user about config stability.
        • +
      • Provide a --platform-hel option for listing all kernel supported platforms.
        • +
      • Handle platform toolchain configuration requirements.
        • +
      +
      • +
    • init-build.sh: tidy script and remove bash-isms to make POSIX-compliant.
      • +
    • rootserver.cmake: Support uimage format for ArmV7 platforms.
      • +
    • Add scripts in helpers/ to CMAKE_MODULE_PATH and support importing on demand.
      • +
    • cakeml.cmake: Add support for multiple CakeML libraries within a project. +Holmake doesn’t support concurrent builds of different projects, so multiple builds need to be serialized.
      • +
    • Add platform_sift.py script for extracting platform memory region descriptions from a YAML file outputted by kernel build.
      • +
    • init-build.sh: Remove multiple CMake invocations and only call CMake once.
      • +
    • application_settings.cmake: Add correct_platform_strings for converting conventional -DPLATFORM values to +valid KernelPlatform and KernelSel4Arch settings.
      • +
    • flags.cmake: Use the runtime objects from sel4runtime rather than musl.
      • +
    • flags.cmake: Always use __aeabi_read_tp for aarch32 by setting -mtp=soft.
      • +
    • Require -C settings.cmake for initializing CMake projects. +This supports the new build structure where instead of blindly including +every settings.cmake file in every projects/ folder, we instead require a single settings.cmake file to be passed in.
      • +
    • Add check_arch_compiler.cmake. This triggers errors if the incorrect compiler is selected.
      • +
    • Add nanopb.cmake for nanopb support.
      • +
    • rust_targets: Update x86_64-target.json to new format.
      • +
    • application_settings.cmake: ApplyData61ElfLoaderSettings RISCV support.
      • +
    • Add elf_sift.py script for computing ELF image loadable segment sizes.
      • +
    • Add shoehorn.py script for computing load addresses of Elfloader, Kernel and User images in memory.
      • +
    • Add make-uimage script to extract the entry point (start symbol) of an ELF executable and wrap the object in a + chain-loadable payload for use by the U-Boot boot loader.
      • +
    • Holmakefile.in, buildScript.sml.in, cakeml.cmake: Update CakeML build scripts for newer CakeML version.
      • +
    • simulate.py: Add tput reset to end of Qemu command for when Qemu leaves the terminal in an inconsistent state.
      • +
    • Remove global Configuration CMake library. Each build artifact should instead control its own configuration dependencies.
      • +
    • Add environment_flags.cmake module for use in modules that are used for defining system environment build flags.
      • +
    • Move musllibc rules from flags.cmake to Findmusllibc.cmake CMake module and merge remainder of flags.cmake with base.cmake.
      • +
    • Mark CMake cache variables advanced by default and allow final project configuration to explicitly show options in the ccmake GUI.
      • +
    • init-build.sh: Support alternative build structure where the top-level CMakeLists.txt project file is not located in the top level directory.
      • +
    • Move ccache settings to compiler toolchain files.
      • +
    • cpio.cmake: Change strategy for constructing cpio archive object file to use linker instead of objcopy.
      • +
    • simulation.cmake: Add new qemu-arm-virt platform simulator options with hyp support.
      • +
    • rust_targets: add aarch64-sel4-none.json target file for Aarch64 rust targets.
      • +
    + +

    kernel

    + +
      +
    • Add functions for querying all kernel platform names and architectures.
      • +
    • Add check_outfile_stale macro. + This checks if a file is older than other files during CMake configure + phase. This is to prevent unnecessary long running execute_process + calls.
      • +
    • Style all CMake and python files.
      • +
    • Add FORCE to all INTERNAL sets. + INTERNAL implies FORCE but in some versions of CMake if a config option + has been passed in via a -D option the INTERNAL set doesn’t override the + value when it should. + See: https://gitlab.kitware.com/cmake/cmake/issues/19015 - + INTERNAL does not imply FORCE for CACHE.
      • +
    • Update python2 –> python3 in build scripts.
      • +
    • Invoke verified configuration files to build kernel with verified configurations.
      • +
    • Add SEL4_CONFIG_DEFAULT_ADVANCED CMake variable. If set then all cache variable +declarations get marked as advanced by default.
      • +
    • Add device trees for every Arm and RISC-V platform. +
        +
      • Use per-config device tree overlays to customize platform layouts for different build configurations.
        • +
      +
      • +
    • Auto-generate hardware headers describing Arm and RISC-V platforms. Use these headers +for creating Untyped objects and Kernel device binding and export YAML memory region +file for use by other projects in build system.
      • +
    • sel4_deps: Add pyfdt, cmake-format, guardonce, pyelftools, autopep8, jsonschema and libarchive-c to seL4 python package. Change pyaml to pyyaml.
      • +
    • Automatically select serial and timer drivers based on device trees.
      • +
    • Remove kernel_astyle.sh in favour of using style scripts in sel4_tools.
      • +
    • Use device tree chosen node to specify kernel devices with seL4,kernel-devices property.
      • +
    • Add reciprocal.py for calculating constants for reciprocal division used in MCS kernel.
      • +
    • Add seL4Config.cmake module to kernel configurations folder for use in CMake -C configuration scripts. +This enables picking kernel platform settings before any projects are configured and also allows +automatically picking the right toolchain files.
      • +
    + + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/camkes-vm/camkes-3.8.x-arm-old.html b/updates/camkes-vm/camkes-3.8.x-arm-old.html new file mode 100644 index 00000000000..3fc5f408b47 --- /dev/null +++ b/updates/camkes-vm/camkes-3.8.x-arm-old.html @@ -0,0 +1,659 @@ + + + + + + + camkes-3.8.x-compatible-arm-old | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to camkes-arm-vm from camkes-3.7.x to camkes-3.8.0

    + +
      +
    • VM: Load kernel and dtb images using FileServer. +This now uses the same mechanism as the x86 Init VM component.
      • +
    • VM: Add basic module abstraction. This allows compilation units +to declare modules that the vmm will +initialise without having to directly call the init function. This +should reduce the amount of #ifdefs throughout the code.
      • +
    • VM: Create map_frame_hack module. +This is a hack that was used in the SMACCM demo for giving the VM direct +memory access to a crypto component.
      • +
    • VM: Create device_fwd module for tk1.
      • +
    • VM: Create vchan module. This moves the vchan source into its own module.
      • +
    • VM: Move remaining vmlinux.c code to per-platform init modules.
      • +
    • Add initial aarch64 support.
      • +
    • Add initial TX1 support.
      • +
    • Rename tk1_vm to vm_minimal as this app supports more than one platform.
      • +
    • vm_minimal: Added Exynos5422 support.
      • +
    • VM: Perform map_unity_ram on Exynos5422. This allows for +a one-to-one PA<->IPA mapping of the guest RAM device on the exynos5422.
      • +
    • Remove duplicate frames from vm_odroid.camkes. +The new CapDL allocator will not permit separate objects with the same +physical address. This change makes the vm_odroid share its hardware MMIO objects +without duplicating them.
      • +
    • VM: Install vpci device. Added call to the sel4arm-vmm in order to install the virtual +pci device in the guest VM.
      • +
    • VM: Added virtio_net module. +This introduces the virtio_net module. This initializes and +manages the virtio net driver in the guest VM. The module +is a basic demonstration that responds to ARP request packets. +This is refactored out of the x86 VMM (camkes-vm).
      • +
    • VM: Support for loading initrd vm module. +Attempts to load an initrd module if provided in the CPIO archive. +This is loaded in the kernel lowmem alongside the dtb.
      • +
    • vm_minimal: Added rootfs to archive for exynos5422. +Updated the vm_minimal CMakeLists.txt to pass the linux-initrd file +to the file server. This change pertains to the exynos5422 +platform.
      • +
    • vm_virtio_net: New virtio_net application. +Added vm_viritio_net application. This is currently target to +the exynos5422 platform. The application demonstrates the use +user level linux overlays, adding an arping test and network +interface file to test virtio net functionality in the vm.
      • +
    • Add griddle support: +
        +
      • Migrate RELEASE and CAMKES_VM_APP to easy-settings.cmake.
        • +
      • Give CAMKES_VM_APP a default of vm_minimal.
        • +
      • Add PLATFORM to easy-settings.cmake as well; default tx1.
        • +
      +
      • +
    • VM: Added TX2 Support.
      • +
    • VM: Added GlobalAsynch notification to the VM. +Added support for a global async notification within the VM +component. This supports additional components in the system to +send notifications to the VM.
      • +
    • VM: Added Virtio Net virtqueue module. +Added a new VM module that forwards and recieves packets through +virtqueues. This allows packets to be forwarded to another +component in the system and in addition for the connected component +to send messages to the VM.
      • +
    • vm_virtio_net: Added ping echo response client. +Added an example camkes application that uses the VM’s virtio +net support to recieve and reply to arping and [icmp] ping +packets sent by the connect guest VM. This is performed over +virtqueues.
      • +
    • serial-server-app: added console support libvirtio. +Added console support to libvirtio library. +This copys the same setup as net where we install +a vpci device. Uses linux hvc0 device to communicate with +the camkes serial server through the vm.
      • +
    • virtio-con: Add module for virtual console.
      • +
    • VM: Added CPP Macro configuration helpers. +Added a set of CPP macro helpers that can be used to configure +a camkes arm vm application. These can be used in substitute of +the vm_common.camkes file.
      • +
    • VM: Memory and image settings as camkes attributes. +Refactored the definitions of the linux guest attributes (e.g. ram +base, size, image names) into camkes attributes. This makes the +VM component more configurable, removing the need to have to hard +code values into the source. Updated the vm apps and component +source to reflect these changes.
      • +
    • VM: Update common sources for new IRQ server changes in libsel4utils.
      • +
    • Remove Configuration library and append #include <<lib_name>/gen_config.h> after each + #include <autoconf.h> since autoconf.h is only for the kernel and libsel4 config now.
      • +
    • templates: Added new template seL4VMDTBPassthrough. +Added a new template/interface that can be used in a camkes +arm vm app. seL4VMDTBPassthrough allows users to define a series +of dtb nodes that will in turn be converted into a series of +untyped memory and irq objects. This can then be used for passing +the devices through to the guest vm. This is an alternative +interface that can be used as opposed to specifying two +independent lists of untypes and irqs.
      • +
    • VM: Component support for the seL4VMDTBPassthrough. +Added support for the seL4VMDTBPassthrough template in the VM +component. This in particular will add the untypes presented by +the passthrough template and updating the camkes simple interface +to account for the dtb irq caps.
      • +
    • vm_minimal, vm_serial, vm_virtio_net, odroid_vm: Updated to use seL4VMDTBPassthrough. +Updated the device configurations to the use seL4VMDTBPassthrough. +This converts the untyped and irq arrays into a single dtb query +array.
      • +
    • Update ping_client to use the new virtqueue lib. +Introduces the necessary changes for the ping client to use the new +libvirtqueue with multi-entry rings and scatter buffer logic.
      • +
    • Added support for the QEMU virt platform, starting a linux VM with buildroot.
      • +
    + + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/camkes-vm/camkes-3.8.x.html b/updates/camkes-vm/camkes-3.8.x.html new file mode 100644 index 00000000000..9452d85aac1 --- /dev/null +++ b/updates/camkes-vm/camkes-3.8.x.html @@ -0,0 +1,589 @@ + + + + + + + camkes-3.8.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to camkes-vm from camkes-3.7.x to camkes-3.8.0

    + +

    camkes-vm

    + +
      +
    • FileServer: Move fsclient to libFileServer-client. +libFileServer-client is now a library bundled with the FileServer +component. Components that are clients of the RPC interface provided by +the FileServer can now link this client library and initialise it with +the name of the local-client interface binding (fs for Init) to set up +the muslc syscall bindings.
      • +
    • Update RPC templates with new grantreply right (rather than grant).
      • +
    • Ethdriver: Fix DMA physical and virtual DMA address assumption. +Previously, the component assumed that the physical and virtual DMA +addresses are the same. This is supposedly the case on x86 platforms but +not on ARM platforms. This commit fixes this assumption and correctly +passes the physical DMA addresses down to the Ethernet device driver.
      • +
    • Ethdriver: Add ARM Ethdriver component and platform specific definitions
      • +
    • Add PicoServer component for providing a UDP/TCP socket client interface and +consuming a seL4Ethernet interface.
      • +
    • Ethdriver: Use new seL4DTBHardware connector. +This commit updates the ARM versions of the Ethdriver component to use +the new seL4DTBHardware connector. This is done to remove the additional +boilerplate code needed to initialise hardware resources.
      • +
    • Move Ethdriver and PicoServer components, templates and interfaces to global-components repository.
      • +
    • remove global Configuration library.
      • +
    • Update virtio_net_switch to new libvirtqueue. +Introduces the necessary changes for the virtio_net_switch to work with +the new multi buffer virtqueue.
      • +
    • CMake: Add Findcamkes-vm.cmake module
      • +
    + +

    camkes-vm-examples

    + +
      +
    • Add griddle support for easy project configuration and building.
      • +
    • CMake: Update project to use CMake modules
      • +
    + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/elfloader/11.0.x.html b/updates/elfloader/11.0.x.html new file mode 100644 index 00000000000..5c3a3bf581c --- /dev/null +++ b/updates/elfloader/11.0.x.html @@ -0,0 +1,646 @@ + + + + + + + seL4 11.0.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to Elfloader from seL4 10.1.x to 11.0.x

    + +

    Externally visible changes

    + +
      +
    • Add Arm Fixed Virtual Platform(FVP) support. This also includes multicore
      • +
    • Add support for the 64-bit i.MX8M Quad evaluation kit. Currently only AArch64 EL1 is supported. +This also includes multicore.
      • +
    • Add support for the 64-bit i.MX8M Mini Quad evaluation kit. Currently only AArch64 EL1 is supported.
      • +
    • Add support for rockpro64 Soc
      • +
    • Add qemu-arm-virt platform support
      • +
    • Remove ancient platforms: nslu2 and realview have never been supported by any (public) + release of the kernel.
      • +
    • Add TX2 multicore support. Brings up as many cores as configured by CONFIG_MAX_NUM_NODES.
      • +
    • Add multicore support for zynqmp
      • +
    • Add multicore support for RISCV
      • +
    • Fix ARM CPUID message on EFI: + At O2 and higher, the switch gets optimised into a table of strings. + Unfortunately, the compiler doesn’t properly handle this when building + position-independent code with -fpic
      • +
    • Enable ElfloaderMonitorHook config option for imx6
      • +
    • fvp: Save MPIDR_EL1 in TPIDR_EL0. On FVP, The MPIDR_EL1 changes to 0x80000000 after +MMU is enabled for unknown reason. We save the +MPIDR_EL1 in TPIDR_EL0 before switching the MMU, and +the correct MPIDR_EL1 can be picked up by the kernel +from TPIDR_EL0.
      • +
    • Pass DTB from bootloader to seL4 on ARM. On ARM, we expect the physical address of the dtb to be passed in r2 on +aarch32 or x0 on aarch64. The elfloader then moves the dtb to immediately after where the +kernel is loaded in memory, and passes that address on to the kernel.
      • +
    • Add aarch32 EFI support. This makes the ELF loader relocatable on aarch32, +and generates the appropriate EFI header for aarch32 boards.
      • +
    • Support using DTB provided by EFI. This adds support for loading a DTB provided by an EFI implementation +in the EFI system tables, identified by a GUID.
      • +
    • Support loading DTB from CPIO archive. + On platforms where the bootloader does not provide a DTB, + we may still want to provide userspace with a DTB - allow including + it in the CPIO archive, named “kernel.dtb”.
      • +
    • Prefer DTB passed from CPIO archive when multiple DTBs are available
      • +
    • Enable nvidia-specific TX2 SERR extensions.
      • +
    • Add option to place the user image at the end of physical memory
      • +
    • Support leaving aarch64 EL2 to aarch32. This allows aarch32 seL4 kernel configurations to be loaded from a + 64bit entry point.
      • +
    • Dynamically compute image start address. Stop hard-coding an address at which the ELF-loader will + be loaded into physical memory. Instead, dynamically compute where it + should go based on the size and locations of the payloads (kernel plus + rootserver) it will extract, and place the image just above their end. + Futhermore, for U-Boot images, pass the computed load address through to + the mkimage command instead of using a hard-coded one (for this format + the load address and entry address are identical).
      • +
    • Still allow statically configuring image start address via -DIMAGE_START_ADDR=0xaddress
      • +
    • Support aarch64 2MiB kernel load addresses + Previously the input kernel vaddr had to be 1GiB aligned. Now it can be + only 2MiB aligned. The paddr previously required 2MiB alignment and this + is still the case.
      • +
    • CMake: Add Findelfloader-tool.cmake module + This adds support for importing this project via + find_package(elfloader-tool) if the project exists in the + CMAKE_MODULE_PATH.
      • +
    • output: use CR LF as line break and not LF CR for all console output.
      • +
    + +

    Implementation changes

    +
      +
    • Switch to new libcpio API: This newer API requires passing in the length of the archive +to prevent buffer overflows.
      • +
    • Style CMake files consistently
      • +
    • Provide weak default for platform_init. This removes the need for empty duplicates per platform.
      • +
    • Style source files
      • +
    • RISCV: Map the elfloader to a separate address space on 64-bit machine.
      • +
    • Add basic memmove implementation
      • +
    • support relocating on ARM. + Under EFI, we can’t control where the ELF loader is loaded - + and so it might be loaded above the kernel’s first vaddr. + If this is the case, once we turn the MMU on the ELF loader + will no longer be accessible and the system will not boot. + When this occurs, workaround it by relocating the ELF loader + below the kernel.
      • +
    • Improve diagnostic error and warning messages.
      • +
    • Explicitly link sel4_autoconf and elfloader_Config + since the global config lib is removed
      • +
    • Fix hashing implementation. Fixes a bug in the parameters being given to the hash functions.
      • +
    • RISC-V: Add fence.i before kernel start. This fence operation ensures that writes to memory that will be executed + are visible to the instruction stream.
      • +
    • Support 40-bit PA. Configure the EL2_TCR register with the correct PS value.
      • +
    • output: introduce plat_console_putchar(). drop __fputc() and provide plat_console_putchar() instead. Duplicated + CR LF handling is removed from the platform code and happens centralized + in arch_write_char()
      • +
    • Support multiple RISC-V hart entries. + On multi-hart platforms, the bbl will call the payload’s entrypoint on + each hart and it is up to the payload to synchronise them for a + deterministic start order. Harts that aren’t required by the kernel get placed into + a wfi loop.
      • +
    • Follow Arm calling conventions in monitor mode SMC handlers for TK1 and imx6.
      • +
    + + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/sel4-tutorials/camkes-3.8.x.html b/updates/sel4-tutorials/camkes-3.8.x.html new file mode 100644 index 00000000000..32b497ba349 --- /dev/null +++ b/updates/sel4-tutorials/camkes-3.8.x.html @@ -0,0 +1,593 @@ + + + + + + + camkes-3.8.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to sel4-tutorials from camkes-3.7.x to camkes-3.8.0

    + +

    External

    + +
      +
    • Add fault-handlers tutorial for learning about fault handlers.
      • +
    • mcs: Add section describing difference between mainline and mcs kernel APIs +for registering fault handlers.
      • +
    • hello-camkes-timer tutorial: Fix init script to pick the correct tutorial.
      • +
    • hello-camkes-[1-2]: Hide tutorial files from instructions
      • +
    • interrupts: Remove sample output that doesn’t appear in practice.
      • +
    • hello-camkes-2: Update exit text test to match actual output.
      • +
    • mcs: reduce spinner budget for final task to ensure timeout behavior happens correctly.
      • +
    • libraries-4: Correctly initalize a stack variable.
      • +
    • hello-camkes-timer: Use device tree for binding timer component to device and update tutorial.
      • +
    • hello-camkes-timer: Add part-2 to tutorial for describing how to use new seL4DTBHardware camkes connector.
      • +
    • camkes-vm-crossvm: Add error message if build configuration is incorrect.
      • +
    • dynamic-4: Remove duplicate vspace init function.
      • +
    • hello-camkes-2: Fix error in hint in task 8.
      • +
    • Refactor tutorial build system to better match typical usage in other project. Previously the tutorials indicated +that their build scripts shouldn’t be used outside of the tutorial project, but this is no longer the case.
      • +
    • libraries-4: Update platform timer API’s to use ltimer interface.
      • +
    • mcs: Support running tutorial on kernel master branch since mcs branch was merged.
      • +
    • mapping: Remove seL4_X86_Page_Remap invocation from tutorial as kernel function had been removed.
      • +
    • libraries-1: fix completion text for task-3.
      • +
    • hello-camkes-1: Update instructions to match source code layout.
      • +
    • untyped: Make sure that untyped being used in tutorial doesn’t correspond to a device.
      • +
    + +

    Internal

    +
      +
    • Update usage of capdl_linker tool to newer API.
      • +
    • Specify TCB CapDL attributes at allocation point.
      • +
    • capdl-ld: Add newly required --keys argument.
      • +
    • add .stylefilter for style tooling.
      • +
    • Style scripts.
      • +
    • Update scripts from python2 to python3.
      • +
    • hello-camkes-timer: Correctly configure device tree tooling.
      • +
    • Port tutorials to use new sel4runtime.
      • +
    • Add support for custom build configuration settings.cmake files for each tutorial.
      • +
    • Remove dependence on global Configuration library.
      • +
    + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/sel4bench/11.0.x.html b/updates/sel4bench/11.0.x.html new file mode 100644 index 00000000000..595eb4aa8ab --- /dev/null +++ b/updates/sel4bench/11.0.x.html @@ -0,0 +1,599 @@ + + + + + + + seL4 11.0.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to seL4Bench from seL4 10.1.x to 11.0.x

    + +

    External

    + +
      +
    • Add new VCPU benchmarks. This new benchmark app benchmarks the following overheads: +
        +
      • The overhead of a HVC privilege escalation from EL1 to EL2.
        • +
      • The overhead of an ERET privilege de-escalation from EL2 to EL1.
        • +
      • The overhead of a NULL hypercall into the seL4 EL2 kernel.
        • +
      • The overhead of an seL4_Call syscall.
        • +
      • The overhead of an seL4_Reply syscall.
        • +
      +
      • +
    • Add griddle support with easy-settings.cmake file.
      • +
    • Force FPU state to only be restored when used. + This ensures that during benchmarks where the FPU state isn’t being used + that the FPU state does not get restored. This ensures that context + switches in benchmarks accurately show the case where FPU restore is not + performed.
      • +
    • Allow for platform counters to be enabled in IPC benchmark.
      • +
    • Update page_mapping benchmark to remap pages using the changed kernel API.
      • +
    + +

    Internal

    + +
      +
    • sel4bench: make plat_setup a weak symbol and remove stub functions for each platform
      • +
    • sel4bench: Add newlines to printf calls. + printf buffering the output makes debugging harder as output becomes + ordered differently.
      • +
    • Update usages of libcpio to match new api.
      • +
    • Style files.
      • +
    • smp: use SEL4BENCH_RESET_CCNT. This is a generic function for achieving what the code was hardcoded to + armv7 for.
      • +
    • sel4bench: start looking for untyped at seL4_MaxUntypedBits.
      • +
    • Use sel4runtime.
      • +
    • libsel4benchsupport: fix child process stack init by ensuring benchmark_spawn_process leaves the stack top + intact.
      • +
    • sel4bench: remove autoconf.h and global Configuration library and link configuration libraries explicitly.
      • +
    • Rename configuration libraries to follow a consistent naming convention.
      • +
    • Use sel4rpc library for allocating untypeds.
      • +
    • Remove sel4platsupport_timer usages and replace with ltimer and new ps_io_irq_t interfaces.
      • +
    • Rename CONFIG_KERNEL_RT to CONFIG_KERNEL_MCS.
      • +
    • Fix SMP thread checkpointing. This fixes breakage in SMP x86_64 benchmark.
      • +
    • Refactor buildsystem to keep up with underlying changes. Try to also make configuration scripts easier to follow.
      • +
    • Use device tree for binding drivers to devices on Arm.
      • +
    + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/sel4runtime/11.0.x.html b/updates/sel4runtime/11.0.x.html new file mode 100644 index 00000000000..5287a0d4103 --- /dev/null +++ b/updates/sel4runtime/11.0.x.html @@ -0,0 +1,593 @@ + + + + + + + seL4 11.0.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to sel4runtime from seL4 10.1.x to 11.0.x

    + +
      +
    • Created sel4runtime project to be a runtime for running a C or C-compatible process, i.e. one with a C-like main, in a minimal seL4 environment. +
        +
      • Added seL4 roottask runtime entry points for: AARCH32, AARCH64, IA32, x86_64, RISC-V 32-bit and RISC-V 64-bit with supporting documentation for calling conventions.
        • +
      • Added regular runtime entry points for non-roottask new processes for the above architectures.
        • +
      • Added CMake rules for replacing musllibc’s CRT files with a CMake object library.
        • +
      • Added CMake configuration option, Sel4RuntimeRootStack, for setting Roottask’s initial stack size.
        • +
      • Create runtime datastructure containing: +
          +
        • process name likely read from argv[0].
          • +
        • AUX vector with additional seL4 specific AUX values: +
            +
          • AT_SEL4_BOOT_INFO: seL4_BootInfo pointer in current vspace.
            • +
          • AT_SEL4_IPC_BUFFER_PTR: IPC buffer pointer in current vspace of initial thread.
            • +
          • AT_SEL4_TCB: TCP capability seL4_CPtr to initial thread’s TCB object.
            • +
          +
          • +
        • Environment vector.
          • +
        • Bootinfo pointer to be initialized with bootinfo address from AUX vector.
          • +
        • ELF headers to be initialized with info from AUX vectors.
          • +
        • Initial thread information: +
            +
          • Thread local storage image information.
            • +
          • Cap to TCB if given in AUX vectors.
            • +
          • IPC buffer: if given in AUX vectors.
            • +
          +
          • +
        +
        • +
      • Add support for calling constructors and destructors.
        • +
      • Add support for managing threads’ static TLS regions.
        • +
      • set a global __sysinfo pointer if AT_SYSINFO is set in AUX vector.
        • +
      • Call main() with required argc and argv arguments.
        • +
      • Support for setting TLS variables of threads remotely.
        • +
      • Call seL4_DebugNameThread if the runtime has a process name and the initial thread has a TCB cap +and IPC buffer set.
        • +
      • Add Findsel4runtime.cmake module for importing as CMake module.
        • +
      +
      • +
    + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/sel4test/11.0.x.html b/updates/sel4test/11.0.x.html new file mode 100644 index 00000000000..9d409535a64 --- /dev/null +++ b/updates/sel4test/11.0.x.html @@ -0,0 +1,634 @@ + + + + + + + seL4 11.0.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to seL4Test from seL4 10.1.x to 11.0.x

    + +

    External

    + +
      +
    • List valid platforms if invalid platform is provided in build configuration.
      • +
    • Add IPCRIGHTS tests for master and mcs to test new grantreply access right: +
        +
      • IPCRIGHTS0001, “seL4_Send needs write”
        • +
      • IPCRIGHTS0002, “seL4_Recv needs read”
        • +
      • IPCRIGHTS0003, “seL4_Send with caps needs grant”
        • +
      • IPCRIGHTS0004, “seL4_Call needs grant or grant-reply”
        • +
      • IPCRIGHTS0005, “seL4_Reply grant depends of the grant of previous seL4_Recv”
        • +
      +
      • +
    • add test UNKNOWN_SYSCALL_001, “Test seL4_VMEnter in a non-vm thread” to check cannot enter VM in no-vm thread on x86.
      • +
    • Added tests for maximum ASID pools usage: +
        +
      • VSPACE0003, “Test create multiple ASID pools”
        • +
      • VSPACE0004, “Test running out of ASID pools”
        • +
      • VSPACE0005, “Test overassigning ASID pool”
        • +
      • VSPACE0006, “Test touching all available ASID pools”
        • +
      +
      • +
    • Add griddle support to sel4test via easy-settings.cmake file.
      • +
    • Re-enable serial_server tests on RISC-V with addition of userlevel serial driver.
      • +
    • Change timeout time for PREEMPT_REVOKE to make test more robust.
      • +
    • Added tests to check IRQ routing: +
        +
      • SMPIRQ0001, “Test multicore irqs”
        • +
      +
      • +
    • Enable TLS tests for RISC-V as they are now supported.
      • +
    • Change RISC-V bad instruction value to 0xffffffff in fault tests. This change was motivated by some simulators not + trapping 0x00000000 or 0x0000 as invalid instructions.
      • +
    • Enable timer tests on RISC-V.
      • +
    • Disable flaky SCHED0000 on RISCV.
      • +
    • Update vspace test to support 40 bit PAs
      • +
    • add NUM_NODES to override KernelMaxNumNodes. + This allows users to pass NUM_NODES on the command line to an init-build + invocation and override the default of 4 cores when SMP=ON. Example: + ../init-build.sh -DPLATFORM=imx8mq-evk -DAARCH32=1 -DSMP=1 -DNUM_NODES=2
      • +
    • Disable device mem tests for spike.
      • +
    • Change frame tests to not try and steal timer device frame from runtime and instead request device frames +more reliably.
      • +
    • set Sel4testHaveTimer and Sel4testHaveCache options to advanced if Sel4testAllowSettingsOverride is not set. +Otherwise any changes to these settings will get overridden.
      • +
    • Set SEL4_CONFIG_DEFAULT_ADVANCED=On. This will cause most CMake config options to be hidden apart from ones +expected to be changed.
      • +
    • Add MCS option for configuring KernelIsMCS. -DMCS=ON will enable MCS configurations and -DMCS=OFF will use mainline + configurations.
      • +
    • Remove Remap and use Map instead in mapping tests due to kernel API change.
      • +
    • RISCV: Disable huge page test for Ariane
      • +
    • MULTICORE0003: Extend to test different VSpaces. + On x86 the kernel was only performing TLB cross-core invalidation if the + VSpace that was being unmapped was running on the current core. This + means that if a core unmaps a page from a different VSpace running on a + different core then the cross-core invalidation wouldn’t happen. + We extend MULTICORE0003 to test unmapping from different VSpaces as well + as the same VSpace. We also now repeat the test a few times for if a + kernel timer IRQ is received during any of them leading to a false + success.
      • +
    + +

    Internal

    + +
      +
    • Correctly initialize clocks for exynos5422 serial driver
      • +
    • Improve test SCHED0011: compare timestamps in nanoseconds not microseconds to improve accuracy. +Use period value instead as wait time instead of assuming 1s.
      • +
    • Switch to new libelf and libcpio API
      • +
    • Style source files.
      • +
    • Use seL4runtime.
      • +
    • Refactor build scripts to keep up to date with build system changes.
      • +
    • Refactor object allocation to use libsel4rpc to dynamically allocate additional resources +instead of trying to preallocate everything.
      • +
    • Remove autoconf.h and global Configuration library usage.
      • +
    • Add memory barriers in SCHED0004 to prevent spurious failures.
      • +
    • Use custom IRQ handler allocation function in IRQ allocation so that some tests may borrow the +caps.
      • +
    • Rename CONFIG_KERNEL_RT to CONFIG_KERNEL_MCS
      • +
    • MULTICORE0003: Reduce wait time to limit timer IRQ. This makes the test more reliable.
      • +
    + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/sel4webserver/camkes-3.8.x.html b/updates/sel4webserver/camkes-3.8.x.html new file mode 100644 index 00000000000..eaba4cf6003 --- /dev/null +++ b/updates/sel4webserver/camkes-3.8.x.html @@ -0,0 +1,566 @@ + + + + + + + camkes-3.8.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to sel4webserver from camkes-3.7.x to camkes-3.8.0

    + +
      +
    • Created sel4webserver project containing an seL4 webserver application. Its purpose is to be a reference for implementing applications on seL4. +
        +
      • This project currently builds an odroid-xu4 VM that runs linux and gets some devices passed through to it.
        • +
      +
      • +
    • Add lighttpd module. This module will build and install a static binary of the lighttpd +webserver into a VM overlay. It is currently configured to serve a +static site on port 3000 out of /run/site in the VM.
      • +
    • Add docsite package that downloads, builds and packages a +docs.sel4.systems static website. It is intended for being served by the +lighttpd webserver added previously.
      • +
    + +
    + +
    +
    + + + +
    +
    +
    + + diff --git a/updates/user_libs/11.0.x.html b/updates/user_libs/11.0.x.html new file mode 100644 index 00000000000..b3de1f23f3e --- /dev/null +++ b/updates/user_libs/11.0.x.html @@ -0,0 +1,902 @@ + + + + + + + seL4 11.0.x-compatible | seL4 docs + + + + + + + + + + + + +
    + +
    +
    +
    + +
    +
    + + Releases + + + Contribute + + + Contact + + + Support + + + Main Site + + + + + seL4 on GitHub + + +
    +
    + +
    +
    +
    +
    +
    +

    This page is archived and is no longer receiving updates.

    +

    It remains here because some of the content may still be useful.

    +
    + +
    +

    Updates to user_libs from seL4 10.1.x to 11.0.x

    + +

    util_libs

    + +
      +
    • libplatsupport: Refactor TX2 timers to use multiple 4k mappings instead of a single large mapping.
      • +
    • libplatsupport: Updated clock driver for exynos5422 that has different clocks layout compared to previous exynos54XX platforms.
      • +
    • libplatsupport: exynos/serial: Attempt TX IRQ handle on uart write.
      • +
    • libethdrivers: 64-bit compatibility fixes
      • +
    • libpci: Only print verbose log messages when logging verbosely
      • +
    • libplatsupport: Add BCM2837 system timer driver.
      • +
    • libplatsupport: Update BCM2837 ltimer to use system timer for absolute time.
      • +
    • libplatsupport: remove static init in ltimers. The regular init functions can be used with an implementation of + ps_io_ops_t that is a static implementation.
      • +
    • libplatsupport: Add Arm Fixed virtual platform(FVP) driver support: serial, SP804 timer, ltimer.
      • +
    • libelf: remove debug functions. These functions have not been maintained and are out of date.
      • +
    • libelf: delete unnecessary functions. +
        +
      • elf_getProgramHeaderInfo: This is an awkward convenience function that +appears to be unused.
        • +
      • elfxx_getProgramSegmentTable, + elfxx_getSegmentType: Functions with different names but the same + functionality already exist.
        • +
      • elfxx_getSegmentInfo: Both of the above.
        • +
      +
      • +
    • libelf: make elf32.h, elf64.h internal header files.
      • +
    • libelf: introduce memory safety: +
        +
      • The size of the buffer containing the ELF file needs to be known to + access it safely.
        • +
      • Change all public void * references to elf_t *, which requires a size + parameter.
        • +
      +
      • +
    • libelf: delete struct definitions that are also provided by musllibc or newlib.
      • +
    • libelf: normalise types. +
        +
      • Use size_t and uintptr_t where appropriate.
        • +
      • Add enum elf_addr_type for physical/virtual memory.
        • +
      +
      • +
    • libelf: remove duplicate and add missing functions. + By normalising return types, most functions in elfxx.c can be merged and + moved into elf.c. + Also add missing prototypes and functions for accessing ELF fields. +
        +
      • getSectionStringTableIndex
        • +
      • getSectionNameOffset
        • +
      • getSectionOffset
        • +
      • getSectionLink
        • +
      • getSectionInfo
        • +
      • getSectionAddrAlign
        • +
      • getSectionEntrySize
        • +
      +
      • +
    • libelf: const-qualify strings. Strings returned by this library should be considered read-only. + If string tables are to be modified, elf_getSection should be used.
      • +
    • libelf: add elf_check_magic function to check if a pointer to a file contains the ELF magic number.
      • +
    • libcpio: avoid side effects when failing in cpio_parse_header by waiting until success before setting return values.
      • +
    • libcpio: introduce memory safety by requiring file_length argument to all CPIO functions.
      • +
    • libplatsupport: Cap the imx timer counter values if it cannot fit in 32 bits.
      • +
    • libplatsupport: Fix ZYNQ ltimer handle_irq() to return EINVAL correctly
      • +
    • libplatsupport: Change NVIDIA plat default timers. + We use TMR1 instead of TMR0 due to the fact that + the IRQ for TMR1 is missing from the DTS file for + TX1. It exists for TX2, but for the sake of + compatibility, we use TMR1 for both.
      • +
    • libplatsupport: Add IRQ type with trigger (PS_TRIGGER). Allows using IRQControl_GetTrigger in libsel4simple.
      • +
    • libplatsupport: Add timer and serial drivers for the Odroid-C2.
      • +
    • libcpio: make position-independent
      • +
    • Import libfdt library from linux kernel sourced from linux kernel version : 5.0.6.
      • +
    • libplatsupport: added ps_io_fdt in interface to return a pointer to an FDT blob.
      • +
    • libplatsupport: Add ‘other’ IRQ type (PS_OTHER) to ps_irq_t interface.
      • +
    • libplatsupport: Add ps_irq_ops_t interface for registering interrupt callbacks.
      • +
    • libutils: Add an unsigned long version of the POPCOUNT macro.
      • +
    • libplatsupport: Added initial i.MX8M Quad EVK Platform support.
      • +
    • libplatsupport: Add ps_irq_ops_t to ps_io_ops structure
      • +
    • libplatsupport: Add RISC-V HiFive serial and pwm drivers.
      • +
    • libplatsupport: zynqmp: Don’t set baud in serial driver init. + The driver doesn’t seem to have the correct clk frequency that it uses + to program the baud and this leads to incorrect baud settings. We assume + that the baud is already configured by the loaders that came before for + now.
      • +
    • libplatsupport: extend generic timer implementation. +
        +
      • update generic timer implementation to work on aarch64 in addition to aarch32.
        • +
      • add more manipulation functions for using the generic timer when it is exported to user level. +Note that exporting the generic timer to user level exposes a timing +channel. This should only be done for testing and benchmarking and never +in a verified configuration of the kernel.
        • +
      +
      • +
    • libplatsupport: Add an ltimer backed by the arm generic timer. For use for + debugging/testing/benchmarking when CONFIG_EXPORT_PCNT_USER is set.
      • +
    • Remove Configuration library from util_libs and append #include <<lib_name>/gen_config.h> after each + #include <autoconf.h> since autoconf.h is only for the kernel and libsel4 config now.
      • +
    • libethdrivers: include config of lwip and picotcp + since global autoconf is removed, we need to explicitly + include the config of lwip and picotcp which will further + indicate the existance of corresponding lib.
      • +
    • libplatsupport: Added initial i.MX8M Mini EVK Platform support
      • +
    • libplatsupport: Added rockpro64 Platform support: Serial and timer drivers.
      • +
    • libplatsupport: Add IRQ register logic to ltimer driver level. + Instead of treating interrupt allocation being a OS/environment specific + thing, this commit now uses the OS/environment agnostic IRQ interface to + register these interrupts. Also fix bugs/clean-up the logic of the init + and destroy functions.
      • +
    • libplatsupport: Allow user callbacks for ltimer + With the IRQ changes to the ltimer, IRQs are now managed internally. + This poses a problem with the management of the time manager and other + services which rely on having known that an interrupt arrived for the + timers. This also isn’t a good idea as it presents a leaky abstraction + in that the services infers events based on interrupts received. + This adds the ability to allow users to supply a callback + that’ll be called when certain events occur for the timer, e.g. timeouts + and etc.
      • +
    • libplatsupport: Remove handle_irq from ltimers. + The ‘handle_irq’ function is no longer necessary and shouldn’t be called + externally as the IRQs will be managed by the IRQ handling functions of + the IRQ interface.
      • +
    • libplatsupport: mcs: Rename CONFIG_KERNEL_RT to CONFIG_KERNEL_MCS
      • +
    • zynqmp: Allow 32-bit free-running clock. + The current zynq machine code assumes a 16-bit counter, which is only + true for the zynq7000. The zynqmp has a 32-bit counter. The timestamp + timer would stop functioning on the zynqmp after it overflowed. This + commit handles the overflow properly on the zynqmp.
      • +
    • zynq: implement serial interrupt handler
      • +
    • pc99: Ack interrupts before handling timer when interrupts are edge triggered.
      • +
    • CMake: Add Findutil_libs.cmake module. + This adds support for importing this project via + find_package(util_libs) if the project exists in the + CMAKE_MODULE_PATH.
      • +
    • libplatsupport: Add FDT parsing library + This FDT parsing library is a collection of utility functions which + parses the FDT with the help of libfdt to simplify the common use cases + of the FDT.
      • +
    • liplatsupport: Add IRQ controller parsing library. + This is a private library that the FDT parsing library uses to parse the + interrupt properties of devices that use a specific IRQ controller. +
        +
      • GICv2
        • +
      • Tegra IRQ controller parser
        • +
      +
      • +
    • libutils: add uthash, a well documented, easy-to-use hash table header.
      • +
    • libplatsupport: add new PER_CPU irq type to ps_irq_t.
      • +
    • libplatsupport: nvidia,tx2: Remove hard-coded addr and IRQ numbers +as these can be retrieved from the DTB and are no longer necessary.
      • +
    • libplatsupport: Add design docs for FDT parsing library
      • +
    • libplatsupport: Added the new qemu-arm-virt platform drivers: serial and timer.
      • +
    • libplatsupport: bbone-timer: update timer for mcs. +
        +
      • remove tick calculations and use frequency lib
        • +
      • fix bug checking wrong irq bit
        • +
      • update get time to use 64bit counter
        • +
      • fix race in ltimer
        • +
      • return correct error
        • +
      • use UINT32_MAX
        • +
      +
      • +
    • libplatsupport: Add placeholder support for Ariane. + Added placeholders in libplatsupport for Ariane to pass the compilation. + The actual driver is yet to be implemented.
      • +
    • libplatsupport: am335x/ltimer: return ETIME when timeout in past.
      • +
    • libethdrivers: The imx8mq-evk reuses the imx6 Ethernet drivers as the devices and setup + are very similar. This is a bit of a hack at the moment and will + eventually be cleaned up.
      • +
    • libutils: Add next-power-of-2 macro which calculates the next power of 2 for a + 32 bit integer.
      • +
    + +

    seL4_libs

    + +
      +
    • libsel4simple: Fix translation of cap numbers to CPtrs + seL4_CapIOPortControl only exists on x86, while seL4_CapIOSpace only + exists on x86 with an IOMMU. + Simple does not address these on other configurations. + Ensure that this is correctly accounted for on all configurations and + architectures.
      • +
    • libsel4simple-default: Don’t assert return pointers in simple_default_nth_untyped.
      • +
    • libsel4utils: updates the address that seL4utils thinks is the maximum usable +userspace vaddr for aarch64-hyp where the kernel provides a 44-bit userspace vaddrspace range.
      • +
    • libsel4vka: Lift the Arm VCPU object to arch level. This makes it available to aarch64.
      • +
    • libsel4utils, elf: Handle new GrantReply right in ELF loading code.
      • +
    • libsel4vka: add function for setting the receive cap slot with a path. (This is the receive slot +for receiving caps over IPC)
      • +
    • libsel4utils: use seL4_UserTop and remove hard coded KERNEL_RESERVED_START values (which is + mean to represent the last page mappable by user-level) and calculates + the value from seL4_UserTop instead, such that if seL4_UserTop changes + at any point the vspace code will still work.
      • +
    • libsel4utils: new new function: sel4_strfault() which returns a string for an seL4 fault type
      • +
    • libsel4vka: Validate object type first in vka_alloc_object_at_maybe_dev and return if invalid. +As a follow up, invalid object type argument error handling becomes non-fatal.
      • +
    • libsel4vka: “implement” utspace_paddr in nullvka and also ensure the struct is zeroed, just in case.
      • +
    • libsel4allocman: Fix bug in internal _destroy_second_level function where 32 was used instead of seL4_WordBits.
      • +
    • libsel4utils: transition to new libelf API. This newer API requires tighter buffer bounds checking on input ELF file.
      • +
    • libsel4vmm: update to use new libelf API
      • +
    • libsel4utils: transition to new libcpio API. This newer API requires tighter buffer bounds checking on input CPIO archive.
      • +
    • libsel4utils: Return NULL if sel4utils_elf_get_vsyscall cannot find __vsyscall symbol instead of memory faulting.
      • +
    • libsel4debug: add prefix for register dump to allow register dumps to identify the source of the dump.
      • +
    • libsel4platsupport,riscv: Fix stack overflow in crt0. A stack frame of 10 words is created, but we were accidentally + overwriting the end due to a fence-post error.
      • +
    • libsel4vspace: Add seL4_ARCH_Page_GetAddress, ARCHPageGetAddress and seL4_ARCH_Page_GetAddress_t definitions for RISC-V.
      • +
    • libsel4simple: Add IRQControl_GetTrigger interface to specify edge or level trigger on + ARM platforms.
      • +
    • libsel4bench: add SEL4BENCH_RESET_CCNT macro definition for arm. + This is not possible on x86, but required on arm if a benchmark is + relying on the 32bit cycle count not overflowing.
      • +
    • libsel4vspace: Implemented a ‘vspace_access_page_with_callback’ function. This + performs a mapping of a page from a source to destination vspace. + The mapping is subsequently passed to a user defined callback + before being unmapped out of the destination vspace.
      • +
    • libsel4vspace: Enable sharing of mem range 0x0-0x1000
      • +
    • libsel4utils: avoid binding null sched contexts (mcs) when configuring passive threads.
      • +
    • libsel4vspace: add vspace_map_page_fn_t type and vspace_iospace_map_page iospace wrapper. +This allows all page mapping functions we currently use to have the + same type signature.
      • +
    • libsel4vspace: extend map object to io and ept structures. This allows code implementing vspace management +to abstract over different page table structures such as IOMMU page tables.
      • +
    • libsel4utils: allow 0 to be mapped by map_page. + 0 is a valid address to map in many scenarios (eg virtualisation).
      • +
    • libsel4allocman: fix use of ALLOCMAN_NO_PADDR. + Throughout allocman, various parts of the code for allocating a + specific paddr would check that the paddr fell within the bounds of a + given untyped node. Unfortunately, in some cases ALLOCMAN_NO_PADDR + + node->size would overlap with the paddr and cause a false positive - + allocman would think that a given node contains the request paddr, + when in fact it didn’t. + Eventually, everything would fall apart: ALLOCMAN_NO_PADDR+node->size + would not be large enough to reach the paddr, and allocman would end + up with a NULL node where it wasn’t expecting one. + Fix this issue by avoiding nodes with paddr == ALLOCMAN_NO_PADDR + whenever we’re searching through node lists, thus preventing + such ‘false positive’ situations from occurring.
      • +
    • libsel4platsupport: Remove CRT runtime files in favor of sel4runtime. Sel4runtime now provides the CRT.
      • +
    • libsel4platsupport: Remove TLS primitives and ELF segment definitions in favour of the ones provided by sel4runtime.
      • +
    • libsel4debug: Update register layout descriptions due to recent seL4 TLS ABI changes.
      • +
    • libsel4platsupport: platsupport_get_bootinfo now locates bootinfo by calling sel4runtime_bootinfo() instead of looking +for an environment variable.
      • +
    • libsel4utils: Use aux vectors to pass context to new processes + Instead of encoding values in strings and storing them in environment + variables, store raw pointers in auxiliary vectors so that the runtime + can parse them without depending on <stdio.h>.
      • +
    • libsel4utils: Use sel4runtime to initialise TLS for newly created threads so that they get their own TLS regions.
      • +
    • libsel4platsupport: Add implementation of ps_irq_ops_t interrupt registration interface from libplatsupport. This +implementation dynamically allocates interrupt handlers from a simple_t and vka_t interface, and also provides entry +points for interrupts to be handled via blocking or polling.
      • +
    • libsel4test: add RPC support for allocating test resources over RPC.
      • +
    • libsel4serialserver: Create separate lib for tests so that they don’t need to get built in projects that don’t need them.
      • +
    • libserialserver: Remove sel4test library dependency.
      • +
    • libsel4platsupport: Remove serial_objects_t interface. +This interface won’t scale to more complicated serial devices. +Instead drivers describe their requirements via calls to ps_io_ops and +the implementations of these interfaces can handle access and allocation policies.
      • +
    • libsel4utils, irqserver: Refactor IRQ server sources to use new libsel4platsupport ps_irq_ops_t interface. +This changes the API, but the general design of the server is the same: the server provides an option of using several threads +for forwarding IRQs to a single notification object such that more IRQs can be handled than what can fit on a single notification object.
      • +
    • Remove Configuration library from seL4_libs and append #include <<lib_name>/gen_config.h> after each + #include <autoconf.h> since autoconf.h is only for the kernel and libsel4 config now.
      • +
    • libsel4platsupport: Add IO FDT ops implementation by returning fdt from seL4_BootInfo.
      • +
    • libsel4utils, elf, riscv: Add FENCE.I instruction in ELF loading code. + Writes to executable memory may not become visible to execution until + after FENCE.I instruction. This prevents programs loaded by this + function crashing due to invalid program instructions.
      • +
    • utils/vka/vspace: update for aarch64 api change. Use seL4_ARM_VSpace* rather than seL4_ARM_PageGlobalDirectory*
      • +
    • libsel4vspace: Add definitions for 40-bit PA on aarch64-hyp.
      • +
    • libsel4vspace: Add deferred rights reservation mapping functions. vspace_reserve_deferred_rights_range_at +and vspace_deferred_rights_map_pages_at_vaddr can be used to allocate reservations where the mapping +rights will be supplied at time of mapping.
      • +
    • libsel4utils: Add implementations for mapping deferred rights reservations
      • +
    • libsel4platsupport: Refactor IO-related interfaces. This refactoring is intended to bring these interface initialisation +functions more in line with the style of similar functions. Instead of +accepting an rvalue (or an expression) of the interfaces, we accept a +pointer to the interfaces themselves. Also add a warning regarding +lifetimes and concurrency.
      • +
    • libsel4platsupport: Add mini IRQ interface. +The new mini IRQ interface covers the common use case where there’s only +a few interrupts to manage and these can fit into a single +notification’s badge space. This also avoids the unneeded complexity +that the standard IRQ interface offers.
      • +
    • mcs: Rename CONFIG_KERNEL_RT to CONFIG_KERNEL_MCS across all libraries
      • +
    • CMake: Add FindseL4_libs.cmake module. This adds support for importing this project via +find_package(seL4_libs) if the project exists in the CMAKE_MODULE_PATH.
      • +
    • libsel4platsupport/libsel4simple: add per cpu irq support on arm +
        +
      • support PER_CPU interrupt type to specify a core
        • +
      • use GetTriggerCore on SMP (GetTrigger fails)
        • +
      +
      • +
    • libsel4muslcsys: Set -u __vsyscall_ptr on link args. +Projects that use this library expect __vsyscall_ptr to be present in +the final binary, but require forcing the symbol because it is often not +used by the final binary but by the loader when setting up the AUX +vectors.
      • +
    • libsel4vspace: Remove Remap operation macro definitions as seL4 Remap operation +was removed.
      • +
    • libsel4utils: mcs: add api method for SC consumed
      • +
    • libsel4muslcsys: Implement sys_write wrapper. +This wraps sys_writev the same way that sys_read is implemented.
      • +
    • libsel4bench: sel4bench.h: update documentation and style
      • +
    • libsel4bench: remove libsel4bench/include/sel4bench/flog.h as file was unused.
      • +
    + +

    projects_libs

    + +
      +
    • Remove Configuration library from projects_libs and append #include <<lib_name>/gen_config.h> after each + #include <autoconf.h> since autoconf.h is only for the kernel and libsel4 config now.
      • +
    • libvirtqueue: Updated to a new multi-buffer, scatter-gather libvirtqueue, closer to + compliance with the virtio standard.
      • +
    • CMake: Add Findprojects_libs.cmake module. This adds support for importing this project via +find_package(projects_libs) if the project exists in the CMAKE_MODULE_PATH.
      • +
    • Add libfdtgen, a library for generating device trees for virtual machines.
      • +
    + +

    seL4_projects_libs

    + +
      +
    • libsel4arm-vmm: add initial support for aarch64 virtualization
      • +
    • libsel4arm-vmm: Add tx1 platform virtualization library support.
      • +
    • libsel4arm-vmm: exynos5: Increase MAX_VIRQS to 200 to support odroid-xu4
      • +
    • libsel4arm-vmm: use new libelf API. This newer API requires tighter buffer bounds checking on input ELF file.
      • +
    • Added a new library, libsel4pci to provide virtual pci emulation. +As a base, the pci driver code from the x86 vmm (libsel4vmm) has +been copied to this library.
      • +
    • libsel4pci: Add support for using PCI emulation in Arm VMs.
      • +
    • Added libsel4vmmcore to be a collection of shared vmm drivers +and utilities that can be used between the x86 and arm vmms.
      • +
    • libsel4vmmcore: Port PCI IOPort emulation from x86 to Arm.
      • +
    • libsel4vmmcore: Port virtio-net driver from x86 VMM and add support for Arm VMs.
      • +
    • libsel4arm-vmm: Add functions for installing virtual PCI device to guest VMs.
      • +
    • libsel4arm-vmm: Support for gzipped initrd image being passed outside of guest kernel image.
      • +
    • libsel4arm-vmm: Add tx2 platform support
      • +
    • Added functionality with in the libsel4pci and libsel4vmmcore libs for vuart devices over vpci.
      • +
    • Add libsel4rpc: a basic library for managing allocating resources over process boundaries.
      • +
    • Add libsel4nanopb: An interface between sel4 IPC buffers and nanopb.
      • +
    • Remove Configuration library from seL4_projects_libs and append #include <<lib_name>/gen_config.h> after each + #include <autoconf.h> since autoconf.h is only for the kernel and libsel4 config now.
      • +
    • CMake: Add Findsel4_projects_libs.cmake module
      • +
    • libsel4arm-vmm: Added support for virtualization on qemu-arm-virt
      • +
    + +

    musllibc

    + +
      +
    • Remove musl runtime objects. These are now supplied by sel4runtime.
      • +
    • Remove __aeabi_read_tp symbol from sel4_arm. This is supplied by sel4runtime.
      • +
    • CMake: Add Findmusllibc.cmake module.
      • +
    + +
    + +
    +
    + + + +
    +
    +
    + +