diff --git a/source/bao_hyp/getting_started.rst b/source/bao_hyp/getting_started.rst index 3ce1d78a..070484a6 100644 --- a/source/bao_hyp/getting_started.rst +++ b/source/bao_hyp/getting_started.rst @@ -1,2 +1,39 @@ Getting Started =============== + +For getting started with the `Bao Hypervisor `_ we recommend +following the "Hello World" interactive tutorial. + +The `bao-helloworld `_ repository provides a minimal +tutorial designed to guide beginners through the process of setting up and running the Bao +Hypervisor on QEMU platforms. It serves as a practical starting point for new users to understand +Bao’s workflow and development, including the configuration and deployment of different :term:`VM` +(i.e., Linux OS, FreeRTOS, and baremetal applications). + +This guide walks through the steps required to reproduce the "Hello World" demo. It begins with +setting up a development environment, including the installation of all necessary dependencies and +cross-compile toolchain. The tutorial then covers building Bao and necessary platform-specific +firmware, i.e., Arm’s Trusted Firmware-A (TF-A) for ``aarch64`` targets and RISC-V’s OpenSBI for +``riscv64`` targets. Finally, you will configure and run different setups, such as single-guest and +dual-guest configurations, on QEMU platforms for both architectures. + +Whether you are evaluating Bao for the first time or seeking a minimal, reproducible reference +environment for further development, this example offers a solid foundation. + +You can find the complete tutorial and source code in the official repository at `bao-helloworld +`_. We also recommend watching the following video, +which provides a step-by-step walk-through of the tutorial: + +.. raw:: html + +
+ +
diff --git a/source/bao_hyp/index.rst b/source/bao_hyp/index.rst index 86b6086c..44882a78 100644 --- a/source/bao_hyp/index.rst +++ b/source/bao_hyp/index.rst @@ -1,12 +1,36 @@ -Bao Hypervisor -============== +The Bao Hypervisor +================== + +.. raw:: html + +

A Lightweight Static Partitioning Hypervisor

+ +Bao (from Mandarin Chinese “bǎohù”, meaning “to protect”) is a lightweight, open-source embedded +hypervisor which aims at providing strong isolation and real-time guarantees. Bao provides a +minimal, from-scratch implementation of the partitioning hypervisor architecture. + +Designed mainly for targeting mixed-criticality systems, Bao strongly focuses on isolation for +fault-containment and real-time behavior. Its implementation comprises only a minimal, thin-layer +of privileged software leveraging ISA virtualization support to implement the static partitioning +hypervisor architecture: resources are statically partitioned and assigned at VM instantiation +time; memory is statically assigned using 2-stage translation; IO is pass-through only; virtual +interrupts are directly mapped to physical ones; and it implements a 1-1 mapping of virtual to +physical CPUs, with no need for a scheduler. + +Bao has no external dependencies, such as on privileged VMs running untrustable, large monolithic +general-purpose operating systems (e.g., Linux), and, as such, encompasses a much smaller TCB. + +**Main Features** + +* Static partitioning consolidation +* Minimalist design +* Strong isolation +* Heterogeneous platforms +* Freedom-from-interference .. toctree:: - :maxdepth: 2 - :caption: Contents: + :maxdepth: 3 + :caption: Documentation and Guides: - overview getting_started - config user_manual/index - internals/index diff --git a/source/bao_hyp/overview.rst b/source/bao_hyp/overview.rst deleted file mode 100644 index 802d3414..00000000 --- a/source/bao_hyp/overview.rst +++ /dev/null @@ -1,2 +0,0 @@ -Overview -======== diff --git a/source/bao_hyp/config.rst b/source/bao_hyp/user_manual/config.rst similarity index 99% rename from source/bao_hyp/config.rst rename to source/bao_hyp/user_manual/config.rst index 873e05e9..c62c5b4f 100644 --- a/source/bao_hyp/config.rst +++ b/source/bao_hyp/user_manual/config.rst @@ -63,7 +63,7 @@ single VM and cannot be shared. In contrast, certain hardware devices and commun (such as shared memory or dedicated IPCs) can be assigned to more than one VM, enabling controlled sharing and inter-VM communication. -.. figure:: img/guest-config.svg +.. figure:: ../img/guest-config.svg :align: center :name: guest-config-fig @@ -196,7 +196,7 @@ hypervisor itself was loaded. However, if the ``separately_loaded`` parameter is ``true``, the VM image is not embedded in the hypervisor image; instead, it is loaded independently. For more details, refer to the figure below. -.. figure:: img/guest-image.svg +.. figure:: ../img/guest-image.svg :align: center :width: 100% :name: vm-image-fig @@ -317,7 +317,7 @@ physical mappings. This feature provides a means to define the physical memory r Inter-Partition Communication (IPC) enables communication between distinct partitions in a computing system, facilitating data exchange, synchronization, and coordination between partitions. -.. figure:: img/ipc.svg +.. figure:: ../img/ipc.svg :align: center :width: 100% :name: ipc-fig @@ -548,7 +548,7 @@ CPU Affinity The configuration file of the Bao hypervisor also enables the definition of core affinity, which involves selecting the physical core where the guest should run. -.. figure:: img/cpu-affinity.svg +.. figure:: ../img/cpu-affinity.svg :align: center :width: 100% :name: cpu-affinity-fig @@ -576,7 +576,7 @@ Bao supports cache coloring which can be configured using the ``colors`` field w platform-dependent. By default, the coloring mechanism is not active. For instance, the following picture depicts a hypothetical setup with a 50/50 coloring scheme; -.. figure:: img/llc-colors.svg +.. figure:: ../img/llc-colors.svg :align: center :width: 100% :name: llc-colors-fig @@ -596,7 +596,7 @@ In Bao's configuration, you can set multiple shared memory regions (e.g., ``shme ...) or none at all. An ID is assigned to each shared memory object. Later, this ID can be linked to an IPC in the multi-guest configuration. -.. figure:: img/shmem.svg +.. figure:: ../img/shmem.svg :align: center :name: shmem-fig diff --git a/source/bao_hyp/user_manual/index.rst b/source/bao_hyp/user_manual/index.rst index de05006b..1491e7aa 100644 --- a/source/bao_hyp/user_manual/index.rst +++ b/source/bao_hyp/user_manual/index.rst @@ -1,2 +1,8 @@ User Manual =========== + + +.. toctree:: + :maxdepth: 2 + + config diff --git a/source/conf.py b/source/conf.py index 456d5d74..0b33ba7d 100644 --- a/source/conf.py +++ b/source/conf.py @@ -44,7 +44,12 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] +exclude_patterns = [ + 'introduction/*', + 'development/testing.rst', + 'development/coding_style.rst', + 'bao_hyp/internals/index.rst', + 'development/ci_pipeline.rst',] # -- Options for HTML output ------------------------------------------------- @@ -70,7 +75,7 @@ 'style_nav_header_background': '#156577', } -html_logo = "introduction/img/bao-logo-200x.png" +html_logo = "img/bao-logo-200x.png" # These folders are copied to the documentation's HTML output html_static_path = ['_static'] diff --git a/source/development/contributing.rst b/source/development/contributing.rst index dca259a0..04dd5b7d 100644 --- a/source/development/contributing.rst +++ b/source/development/contributing.rst @@ -199,15 +199,15 @@ Review Guide ************ As much as possible, code quality and enforced standards/guidelines will be automatically checked -in the :ref:`CI pipeline `. **Reviewers** must be particularly attentive to the ones that are +in the CI pipeline. **Reviewers** must be particularly attentive to the ones that are not addressed by these automated tools. The following are some tips all **reviewers** should take into account: * Make sure the code is readable, well commented (includes doxygen comments), and the :term:`PR` provide the appropriate/necessary documentation; -* The code follows the project's :ref:`coding guidelines` as much as possible, - especially those not automatically checked such as: +* The code follows the project's coding guidelines as much as possible, especially those not + automatically checked such as: * code organization, that is, are the files placed correctly? (e.g., architecture specific files in the *arch* directory); @@ -251,7 +251,7 @@ enforced by GitHub: * was reviewed by at least by two **reviewers**; * all review comments, suggestions or modification requests have been addressed; -* passes all :ref:`CI pipeline ` checks; +* passes all CI pipeline checks; * can be rebased on ``main`` without any conflict; The **maintainer** shall have as the main objective when integrating the :term:`PR` to maintain a @@ -282,10 +282,10 @@ history within the :term:`PR`: ``branch/pull-request``); * follow a logical order. That is, a commit that has a dependence on the modifications by a different commit of the same :term:`PR`, is after the former. -* adhere to the project's :ref:`coding guidelines` for the targeted languages; +* adhere to the project's coding guidelines for the targeted languages; * tag the necessary requirements; * introduce code that is readable and sufficiently commented/documented; -* pass all :ref:`base CI pipeline` checks, by running them locally; +* pass all base CI pipeline checks, by running them locally; * make sure your code works: test your code in as many targets as possible and write the needed automated tests; * introduces or updates the necessary documentation; @@ -371,7 +371,7 @@ Message Format ############## The format of the message, especially the header, is checked using the `gitlint -`_ tool referenced in :ref:`CI pipeline`. For detailed +`_ tool referenced in the CI pipeline. For detailed information on the commit format check the ``.gitlint`` file in the `CI repository `_, which defines a certain set of rules that comply with the following list: @@ -551,10 +551,10 @@ Other topic branches might also be subject to protection rules at the will of th CI/GitHub Actions ***************** -Every repository must have an automated :ref:`CI pipeline ` setup using GitHub Actions. -Specifically, by adding workflow yaml files to the ``.github/workflows`` directory. The `CI -repository `_ contains a number of templates as well as -further instructions on how to set it up. +Every repository must have an automated CI pipeline setup using GitHub Actions. Specifically, by +adding workflow yaml files to the ``.github/workflows`` directory. The `CI repository +`_ contains a number of templates as well as further +instructions on how to set it up. Here are a few workflows a **maintainer** should add to the repository's :term:`CI`: @@ -562,10 +562,10 @@ Here are a few workflows a **maintainer** should add to the repository's :term:` conventional commit style; * copyright and license check: making sure all files have the necessary license and copyright information; -* language format/linting: apply the language format checkers defined in the :ref:`CI repository - ` for the repo's used languages (e.g. clang-format for C or pylint for python); -* static analysis: apply static analyses defined in :ref:`CI repository ` for the - repo's used language (e.g. misra-check for C language); +* language format/linting: apply the language format checkers defined in the CI repository for the + repo's used languages (e.g. clang-format for C or pylint for python); +* static analysis: apply static analyses defined in the CI repository for the repo's used language + (e.g. misra-check for C language); * build: build the repository for a representative set of targets and configurations (using GitHub Actions' strategy matrix); @@ -659,3 +659,5 @@ Final layout of the ``.gitmodules`` configuration file: .. ---------- .. add ref to "requirements and traceability" mentions throughout the document + +..Reference to coding guidelines needs to be added diff --git a/source/development/doc_guidelines.rst b/source/development/doc_guidelines.rst index d713c561..3bb9574d 100644 --- a/source/development/doc_guidelines.rst +++ b/source/development/doc_guidelines.rst @@ -447,9 +447,9 @@ updated. Spelling and Format Checkers ---------------------------- -To keep the consistency of the documentation, the :ref:`CI pipeline ` runs two checkers to find -misspelled words and invalid reST format styles. The checkers can be run locally by just running -the following Make rules: +To keep the consistency of the documentation, the CI pipeline runs two checkers to find misspelled +words and invalid reST format styles. The checkers can be run locally by just running the following +Make rules: To run the `sphinxcontrib.spelling `_ spell checker: @@ -528,5 +528,5 @@ To link terms with the glossary, the keyword ``:term:`term1``` must be used, whi reference in all other documents and mark it with the ``:term:`` keyword to created a link to the glossary entry. However, this should be avoided if the term has a dedicated file documenting it (e.g., - :ref:`CI `, :ref:`MISRA `). Use explicit referencing - instead. Notwithstanding, add the term to the glossary. + CI, :ref:`MISRA `). Use explicit referencing instead. Notwithstanding, add the term to + the glossary. diff --git a/source/development/index.rst b/source/development/index.rst index 91158501..aef7d0c8 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -1,16 +1,11 @@ -Development -=========== +Development Guidelines +====================== .. toctree:: - :maxdepth: 2 - :caption: Contents: + :maxdepth: 3 - coding_style code_documentation doc_guidelines - testing - ci_pipeline - licensing contributing misra versioning diff --git a/source/development/misra.rst b/source/development/misra.rst index 962f9757..90d66632 100644 --- a/source/development/misra.rst +++ b/source/development/misra.rst @@ -6,12 +6,12 @@ MISRA Compliance The project aims to comply with the :term:`MISRA` C:2012 coding guidelines in all C code across all repositories. All submitted code will be checked for :term:`MISRA` violations following the :ref:`Guideline Enforcement Plan ` and the :ref:`Guideline Requalification Plan -` using automated checker tools in the :ref:`CI pipeline `. Developers should -continuously check for :term:`MISRA` violations by :ref:`running the checker tools -locally` at each commit. Any violation identified in the submitted code must -be justifiable and duly :ref:`deviated`. These processes must be properly documented, -peer-reviewed, and authorized according to the project's :ref:`contribution process ` -and the guidance provided by the official `MISRA Compliance:2020 document +` using automated checker tools in the CI pipeline. Developers should continuously check +for :term:`MISRA` violations by :ref:`running the checker tools locally` at +each commit. Any violation identified in the submitted code must be justifiable and duly +:ref:`deviated`. These processes must be properly documented, peer-reviewed, and +authorized according to the project's :ref:`contribution process ` and the guidance +provided by the official `MISRA Compliance:2020 document `_. Every :term:`developer`, reviewer, or :term:`maintainer` should familiarize themselves with, first @@ -101,7 +101,7 @@ A project's GRP must start with the original category for every rule. Every reca reconfigure the tools accordingly. As described in :ref:`Repository MISRA Artefacts`, each repository must provide a -GEP in a CSV format, for which a baseline is provided in the :ref:`CI repository `. +GEP in a CSV format, for which a baseline is provided in the CI repository. .. _deviations: @@ -109,16 +109,16 @@ Deviations ---------- All new :ref:`code submissions via a GitHub pull-requests `, will be subject to the -automatic checking of :term:`MISRA` compliance by the :ref:`CI pipeline `. Ideally, the -pull-request should not introduce any new :term:`MISRA` violations. Developers should always strive -to follow the :term:`MISRA` coding guidelines. However, they may conclude that a violation is -unavoidable and justifiable according to at least one of the :ref:`deviation reasons -`. If so, developers must document and request the introduction of the violation -in the code base, which will be subject to the approval of a code reviewer. These approved -violations are called deviations. To introduce a deviation, a :term:`developer` must follow the -:ref:`deviation procedure ` which include providing a :ref:`deviation record -`, :ref:`annotate` all violations, and being explicitly -approved by :ref:`MISRA managers`. +automatic checking of :term:`MISRA` compliance by the CI pipeline. Ideally, the pull-request should +not introduce any new :term:`MISRA` violations. Developers should always strive to follow the +:term:`MISRA` coding guidelines. However, they may conclude that a violation is unavoidable and +justifiable according to at least one of the :ref:`deviation reasons `. If so, +developers must document and request the introduction of the violation in the code base, which will +be subject to the approval of a code reviewer. These approved violations are called deviations. To +introduce a deviation, a :term:`developer` must follow the :ref:`deviation procedure +` which include providing a :ref:`deviation record `, +:ref:`annotate` all violations, and being explicitly approved by :ref:`MISRA +managers`. .. _deviation_reasons: @@ -425,7 +425,7 @@ Templates for all these documents are provided in the ``misra`` directory of the MISRA managers -------------- -On top of the roles described in :ref:`ci`, every repository shall be assigned at least one +On top of the roles described in the CI, every repository shall be assigned at least one :term:`MISRA` manager responsible for enforcing the processes described in this document and guaranteeing the `MISRA compliance best practices `_ are being followed as @@ -450,13 +450,13 @@ guidelines. Their responsibilities include, but are not limited to: Running the MISRA Checker Locally --------------------------------- -Every project shall instantiate the :ref:`CI` :code:`misra-check` Make rule that takes care of -running all the necessary :term:`MISRA` checks. For example, for checking compliance for the +Every project shall instantiate the CI :code:`misra-check` Make rule that takes care of running all +the necessary :term:`MISRA` checks. For example, for checking compliance for the *qemu-aarch64-virt* platform: .. code-block:: shell make PLATFORM=qemu-aarch64-virt misra-check -It is suggested to use the provided :ref:`Docker container image ` for running the checks; -otherwise, you will first have to :ref:`setup all the necessary tools locally`. +It is suggested to use the provided Docker container image for running the checks; otherwise, you +will first have to setup all the necessary tools locally. diff --git a/source/glossary.rst b/source/glossary.rst index 0dd13a05..cf90d2a3 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -12,7 +12,7 @@ Glossary CI Continuous Integration: process that automates the integration of new changes to the - repositories. More information :ref:`here `. + repositories. More information here. MISRA Set of software development guidelines for the C programming language developed by The @@ -51,3 +51,9 @@ Glossary A subject is an entity that can access or interact with a system, its resources and its assets. This can include individuals, other systems (e.g., through a remote connection), and specific system components such as VMs and VMMs. + + VM + A Virtual Machine (VM) is a software-emulated environment that runs programs, including + operating systems, as if they were executing directly on physical hardware. VMs are created + and managed by a hypervisor, which enables the consolidation of multiple VM-based isolated + systems on a single platform. diff --git a/source/introduction/img/bao-logo-200x.png b/source/img/bao-logo-200x.png similarity index 100% rename from source/introduction/img/bao-logo-200x.png rename to source/img/bao-logo-200x.png diff --git a/source/index.rst b/source/index.rst index 64cee26c..239cd8cd 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,14 +3,49 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Bao Project Documentation -========================= +Bao Project +=========== + +The Bao Project is a community-driven initiative with the mission of disrupting virtualization at +the edge by embracing the core principles of open-source software: openness, collaboration, and the +freedom to use, modify, and distribute code. + +We believe that open-source collaboration is essential for driving innovation and improving the +security and reliability of software technologies, especially in domains traditionally governed by +proprietary virtualization solutions. To this end, we are committed to building a community that +welcomes virtualization enthusiasts and encourages contributions from developers, industry +partners, researchers, and end users alike. + +.. raw:: html + + +

The Bao Hypervisor

+ +

Overview, getting started, user manual, and advanced guides regarding the Bao Hypervisor

+ + +

Development Guidelines

+ +

Guidelines for contributing to the Bao Project (coding style, CI workflow, MISRA guides, + contributing guidelines)

+ + +

Licensing

+ +

Licensing summary and author's DCO

+ + +

Glossary

+ +

Definitions of terms and concepts used in the Bao Project

.. toctree:: + :hidden: :maxdepth: 2 :caption: Contents: - introduction/index bao_hyp/index development/index + licensing glossary + diff --git a/source/introduction/index.rst b/source/introduction/index.rst index 89cb173c..4849a9fd 100644 --- a/source/introduction/index.rst +++ b/source/introduction/index.rst @@ -1,7 +1,6 @@ About ======================= - .. toctree:: :maxdepth: 2 diff --git a/source/development/licensing.rst b/source/licensing.rst similarity index 100% rename from source/development/licensing.rst rename to source/licensing.rst diff --git a/source/spelling_wordlist.txt b/source/spelling_wordlist.txt index 07635cb1..ea414c47 100644 --- a/source/spelling_wordlist.txt +++ b/source/spelling_wordlist.txt @@ -83,3 +83,8 @@ aarch64 aarch linearized VM +baremetal +toolchain +bǎohù +instantiation +untrustable