Ref/structure: change documentation skeleton

source/bao_hyp/getting_started.rst

@@ -1,2 +1,39 @@
 Getting Started
 ===============
+
+For getting started with the `Bao Hypervisor <https://github.com/bao-project>`_ we recommend
+following the "Hello World" interactive tutorial.
+
+The `bao-helloworld <https://github.com/bao-project/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
+<https://github.com/bao-project/bao-helloworld>`_. We also recommend watching the following video,
+which provides a step-by-step walk-through of the tutorial:
+
+.. raw:: html
+
+    <div style="position: relative; width: 100%; height: 0; padding-bottom: 56.25%; margin: 20px 0;">
+        <iframe
+            style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
+            src="https://www.youtube.com/embed/6c8_MG-OHYo?si=-jT3a9-2NkxxdnIT"
+            title="YouTube video player"
+            frameborder="0"
+            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+            referrerpolicy="strict-origin-when-cross-origin"
+            allowfullscreen>
+        </iframe>
+    </div>

source/bao_hyp/index.rst

@@ -1,12 +1,36 @@
-Bao Hypervisor
-==============
+The Bao Hypervisor
+==================
+
+.. raw:: html
+
+   <h2>A Lightweight Static Partitioning Hypervisor</h2>
+
+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

source/bao_hyp/config.rst → 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
 

source/bao_hyp/user_manual/index.rst

@@ -1,2 +1,8 @@
 User Manual
 ===========
+
+
+.. toctree::
+   :maxdepth: 2
+
+   config

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']

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 <ci>`. **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<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 <ci>` 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<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<ci>` 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
-<https://jorisroovers.com/gitlint/>`_ tool referenced in :ref:`CI pipeline<ci>`. For detailed
+<https://jorisroovers.com/gitlint/>`_ tool referenced in the CI pipeline. For detailed
 information on the commit format check the ``.gitlint`` file in the `CI repository
 <https://github.com/bao-project/bao-ci>`_, which defines a certain set of rules that comply with
 the following list:
@@ -551,21 +551,21 @@ 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 <ci>` setup using GitHub Actions.
-Specifically, by adding workflow yaml files to the ``.github/workflows`` directory. The `CI
-repository <https://github.com/bao-project/bao-ci>`_ 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
+<https://github.com/bao-project/bao-ci>`_ 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`:
 
 * commit message linting: apply gitlint to verify all the PRs' commit messages follow the
   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
-  <gitact_checkers>` 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 <gitact_checkers>` 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

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 <ci>` 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 <https://sphinxcontrib-spelling.readthedocs.io/en/latest/>`_
 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 <ci>`, :ref:`MISRA <misra>`). Use explicit referencing
-      instead. Notwithstanding, add the term to the glossary.
+      CI, :ref:`MISRA <misra>`). Use explicit referencing instead. Notwithstanding, add the term to
+      the glossary.

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

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 <misra_gep>` and the :ref:`Guideline Requalification Plan
-<misra_grp>` using automated checker tools in the :ref:`CI pipeline <ci>`. Developers should
-continuously check for :term:`MISRA` violations by :ref:`running the checker tools
-locally<misra_check_locally>` at each commit. Any violation identified in the submitted code must
-be justifiable and duly :ref:`deviated<deviations>`. These processes must be properly documented,
-peer-reviewed, and authorized according to the project's :ref:`contribution process <contributing>`
-and the guidance provided by the official `MISRA Compliance:2020 document
+<misra_grp>` using automated checker tools in the CI pipeline. Developers should continuously check
+for :term:`MISRA` violations by :ref:`running the checker tools locally<misra_check_locally>` at
+each commit. Any violation identified in the submitted code must be justifiable and duly
+:ref:`deviated<deviations>`. These processes must be properly documented, peer-reviewed, and
+authorized according to the project's :ref:`contribution process <contributing>` and the guidance
+provided by the official `MISRA Compliance:2020 document
 <https://www.misra.org.uk/app/uploads/2021/06/MISRA-Compliance-2020.pdf>`_.
 
 Every :term:`developer`, reviewer, or :term:`maintainer` should familiarize themselves with, first
@@ -101,24 +101,24 @@ 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<misra_artifacts>`, each repository must provide a
-GEP in a CSV format, for which a baseline is provided in the :ref:`CI repository <ci>`.
+GEP in a CSV format, for which a baseline is provided in the CI repository.
 
 .. _deviations:
 
 Deviations
 ----------
 
 All new :ref:`code submissions via a GitHub pull-requests <contributing>`, will be subject to the
-automatic checking of :term:`MISRA` compliance by the :ref:`CI pipeline <ci>`. 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
-<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 <deviation_procedure>` which include providing a :ref:`deviation record
-<deviation_records>`, :ref:`annotate<deviation_annotations>` all violations, and being explicitly
-approved by :ref:`MISRA managers<misra_manager>`.
+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 <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
+<deviation_procedure>` which include providing a :ref:`deviation record <deviation_records>`,
+:ref:`annotate<deviation_annotations>` all violations, and being explicitly approved by :ref:`MISRA
+managers<misra_manager>`.
 
 .. _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
 <https://www.misra.org.uk/app/uploads/2021/06/MISRA-Compliance-2020.pdf>`_ 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<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 <docker>` for running the checks;
-otherwise, you will first have to :ref:`setup all the necessary tools locally<gitact_local_env>`.
+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.