From 33a7b843939ec17a39752019f79327ca821ab49e Mon Sep 17 00:00:00 2001 From: David Martins Cerdeira Date: Wed, 12 Oct 2022 13:58:26 +0100 Subject: [PATCH] doc: Add requirement framework description (#20) Present the requirement framework followed in the Bao-Project, introducing key requirement concepts and their definitions. Signed-off-by: David Cerdeira --- source/index.rst | 1 + source/requirements/img/BaoReq.png | Bin 0 -> 43320 bytes source/requirements/index.rst | 11 + source/requirements/requirements.rst | 138 +++++++++ source/requirements/writing_requirements.rst | 287 +++++++++++++++++++ 5 files changed, 437 insertions(+) create mode 100644 source/requirements/img/BaoReq.png create mode 100644 source/requirements/index.rst create mode 100644 source/requirements/requirements.rst create mode 100644 source/requirements/writing_requirements.rst diff --git a/source/index.rst b/source/index.rst index 7f23a9a..ee55ac8 100644 --- a/source/index.rst +++ b/source/index.rst @@ -14,6 +14,7 @@ Bao Documentation user_manual/index development/index internals/index + requirements/index glossary diff --git a/source/requirements/img/BaoReq.png b/source/requirements/img/BaoReq.png new file mode 100644 index 0000000000000000000000000000000000000000..7b68e5da1af0a88e35a2ea0bbf0b38dae672c951 GIT binary patch literal 43320 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%0A< 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 literal 0 HcmV?d00001 diff --git a/source/requirements/index.rst b/source/requirements/index.rst new file mode 100644 index 0000000..2d73fa1 --- /dev/null +++ b/source/requirements/index.rst @@ -0,0 +1,11 @@ + +Requirements +============ + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + requirements + writing_requirements diff --git a/source/requirements/requirements.rst b/source/requirements/requirements.rst new file mode 100644 index 0000000..6f738d5 --- /dev/null +++ b/source/requirements/requirements.rst @@ -0,0 +1,138 @@ +.. _requirement_framework: + +Bao Requirements Framework +========================== + +.. _Bao Design: https://www.github.com/bao-project + +Introduction +------------ + +This document specifies the strategy of requirement specification followed in +by the Bao project. Requirements are specified at various abstraction levels +and follow a hierarchical structure. The starting point is the overall design +and definition of Bao. Bao's definition will directly inform the specification +of Bao's :ref:`Utilitarian Objectives`. Additionally, Bao's design +will inform the security threat model and the safety and security assumptions. +Because it is impossible to predict every single environment Bao will be +deployed in, a set of assumptions are made regarding the security and safety +environment. Additionally a Security Threat model is established that outlines +the expected security threats Bao might face. The Security Assumptions and +Security Threat Model are used to derive :ref:`Security +Objectives`. The Safety Assumptions, in their turn, are used to +derive :ref:`Safety Objectives`. The objectives give rise to +:ref:`HLR`, which are used to derive :ref:`DLR`. The :ref:`DLRs` are the +basis to define :ref:`DELR` and :ref:`ILR`. + + +The following diagram depicts how the concepts explained in this document +relate to each other: + + .. figure:: ./img/BaoReq.png + :width: 340px + :align: center + :name: bao-req-fig + + Bao Requirement Concepts and their relation to each other. + + + +.. _T_A: + +Threats and Assumptions +----------------------- + +Threats and assumptions define the expected security and safety problems. +These include security and safety threats to be mitigated by the either the +system or the operating environment. + +The system's overall design is the leading input in creating the security and +safety threat models. An overall description of the system can be found in `Bao +Design`_. With this high-level view of the system, it's possible to create +security and safety threat models and establish security and safety assumptions +regarding the environment in which the system will operate. Assumptions +describe aspects of the system's operations that are assumed to be true or are +imposed by external factors. If assumptions are not met by the environment, the +system will not provide the necessary security and safety functionality. The +threat models specify the countered security and safety threats. Some threats +are addressed directly by meeting the security and safety Objectives_. Others +are expected to taken care of by the environment in which the system is +deployed. + +.. _objectives: + +Objectives +---------- + +Our framework establishes three categories of objectives: utilitarian, +security, and safety. Utilitarian objectives establish what is the +functionality of Bao that is not directly related to security or safety. They +establish the high-level features that Bao must meet in order to provide +desirable functionality not related to security or safety. Security objectives +address security concerns brought to light by the threat model and assumptions. +The same is true for safety objectives, regarding safety threats. + + +Requirements +------------ + +.. _HLR: + +High-Level Requirements (HLR) +***************************** + +High-Level Requirements (HLR) establish a more detailed description of the +functionality and restrictions first established in the objectives. These +descriptions are written from the system's point of view without relating to +the actual architectural components that implement them. As such, these +requirements specify the system's behavior as a whole. These requirements are +not very detailed, as they still serve as an overall guideline for a feature, +not the exact details of what must be accomplished. HLRs are not +platform-specific, so they use generic terms applicable across the various +supported platforms + + +.. Note:: + One way to make sense of HLRs is to take the point of view of a system + integrator which is consolidating multiple software stacks in system + partitions, and making certain assumptions about its execution environment. + +.. _DLR: + +Design-Level Requirements (DLR) +******************************* + +Design-Level Requirements (DLR) map the high-level functionality established in +HLR_ to the actual architectural components of the system (e.g., Tool, VMM, +Partitioner). They detail even further the functionality and restrictions that +may apply. For example, by detailing that access control must be performed +using certain mechanisms without explicitly describing how they are +implemented. DLRs may also enumerate requirements obtained from expanding the +ideas in a single HLR. Another aspect of DLRs is that they are still +platform-agnostic, and their specifications refer to multiple platforms. + + +.. TODO: add example of requirement mapping between HLR and DLR + +.. _DELR: + +Design-Level Error Requirements (DELR) +************************************** + +Design-Level Error Requirements (DELR) map to some DLR_ with the goal of +detailing the expected error conditions during the operation of Bao. DELR +should establish the error conditions that must be detected by the system and +the correct way to handle the detected errors depending on the current context. + +.. _ILR: + +Implementation-Level Requirements (ILR) +*************************************** + +Implementation-Level Requirements (ILR) map to DLR_ to further refine the +requirements. At this level, platform aspects are taken into account. For +example, specific interrupt control (e.g., GIC 400), or IOMMU (e.g., SMMU 400) +support. Additionally, ILR also specifies which data formats are to be used at +an interface level. For example, a device tree format for configuration of the +system partitions. + diff --git a/source/requirements/writing_requirements.rst b/source/requirements/writing_requirements.rst new file mode 100644 index 0000000..c611f2b --- /dev/null +++ b/source/requirements/writing_requirements.rst @@ -0,0 +1,287 @@ +Writing Requirements +==================== + + +The Bao Project uses the `doorstop `_ +tool to help manage, track and maintain requirements in a consistent format. +Doorstop is a command line tool to manage requirements written in plain text, +which can then be managed by using VCS, such as git, and written using a text +editor. + +Bao's requirements are maintained in their own repository `bao-project/bao-reqs +`_. + +Bao Requirement Hierarchy +------------------------- + +The `bao-reqs `_ repository stores all +requirements starting from :ref:`Objectives`. The following diagram illustrates +the portion of the requirement hierarchy managed through doorstop. + + +.. code-block:: None + + OBJ + │ + └── HLR + │ + └── DLR + │ + ├── ILR + │ + └── DLER + + +For an overview of each hierarchy level please refer to the +:ref:`requirement_framework`. + +Doorstop terms and definitions +------------------------------ + +Item An item is a single requirement. Each item is stored in a single YAML file +following a well-defined schema. + +Document A document is a directory containing a collection of items. + +Standard Item Properties Doorstop Items have multiple properties. For a +description of these properties see `Doorstop Items +`_. + +Custom Item Properties Doorstop allows the creation of custom Item properties, +which we leverage to add meaningful attributes to requirements in the context +of Bao. Here we list them. + + type + Can be either ``Functional`` or ``Non-Functional`` + + priority + Priority of this requirement in relation to other requirements. Can + be ``High``, ``Medium``, ``Low``. + + observation + A property to store additional information about the requirement + that complements the description in the text. + +Adding Requirements +--------------------- + +To add new requirements to a document you can run, for example: + +.. code-block:: shell + + doorstop add HLR + +This command will add a new requirement (Item) to the HLR document. However, +given that we use custom properties it is cumbersome to retrieve them every +time a new requirement is added. To help with this, there's a default item with +the custom attributes filled with blanks. This item is ``default.yml`` in +`bao-project/bao-reqs `_. To leverage +it, run, for example: + +.. code-block:: shell + + doorstop add -d default.yml HLR + +This way the ``default.yml`` parameters will be used as a template for a new +item in HLR. + +To streamline things even further there's a ``env_setup.sh`` file that creates +an alias for this command. To include the alias in your environment run the +following command: + +.. code-block:: shell + + . env_setup.sh + +The following alias is now available: + +.. code-block:: shell + + alias dsadd="doorstop add -d default.yml" + +Example usage: + +.. code-block:: shell + + dsadd HLR + +Finally you can either navigate to the created item, or you can edit your item +in the list of HLR by running the following command: + +.. code-block:: shell + + doorstop edit HLR + +The commands presented so far are appropriate for handling adding a small +number of requirements. However if adding large amounts of requirements an +alternative approach is to export a document to a ``.csv`` file. This can be +done by running, for example: + +.. code-block:: shell + + doorstop export DLR DLR.csv + +This command will take all requirements in the DLR document and write them unto +single lines in a ``.csv`` file that can be edited using a Spreadsheet editor. +When using this method you should be careful as to not replace the Items' UID +as it will break any links established between levels of the requirement +hierarchy. + + +.. Note:: + The CI workflows will automatically fail if there are any issues with the + requirement documents including the issue of broken requirement links due to + unreviews changes. + + +Adding Objectives +----------------- + +With the goal of making requirement UIDs more meaningful, we write the +:ref:`Objectives` UIDs in the form of: OBJ__XXX. OBJ signifies that the +item pertains Objectives. is either UTIL for utilitarian objectives, +SAF for safety objectives, or SEC for security objectives. XXX is a number +starting from 000. The disadvantage of modifying the UID is that it must be +managed manually. + +In this document we make use of the header property, see `Items +`_ , to give a name +to each Objective. + + + +Adding HLR +----------------- + +In :ref:`HLR` we make use of linear UIDs, resulting in UIDs in the form of: +HLR_XXX. XXX is a number starting from 000. + + +Adding DLR +----------------- + +In :ref:`DLR` we again use a modified UID. In DLR the UIDs take the form of: +DLR__XXX. Where DLR identifies the DLR document. +identifies the system component which the requirement targets. Currently Bao +has DLR for the following components (componente → Abreviation used in UID): +Tool→ TOOL, Partitioner→ PART, VMM Static→ VMMSTATIC. + + +Managing Requirements +--------------------- + +There are two main activities apart from purely establishing requirements. +Linking requirements to the above hierarchical requirement layer, and reviewing +requirements. + + +Linking Requirements +******************** + +Linking requirements can be done through the command-line tool: + +.. code-block:: shell + + doorstop link HLR_001 DLR_TOOL_020 + +By adding the following field to the Item in a text editor: + +.. code-block:: shell + + links: + - HLR_001: + +Or by specifying the link in the export file (e.g., ``.csv``) the using the UID +column in the appropriate requirement row. + +.. Note:: + Only after the requirements are reviewed will links be presented when + published. This is because the link between requirements is tied not only to + the item UID, but also to all its property values. This means that any + change to a linked requirement will result in the link breaking. To fix the + link the changed requirement should be marked as reviewed. + +Reviewing Requirements +********************** + +Once you have made the intended modifications to the requirements, run the +following command to mark all requirements as reviewed: + +.. code-block:: shell + + doorstop review + +To mark only a single requirement as reviewed run: + +.. code-block:: shell + + doorstop review + +Generating the Requirements +--------------------------- + +To generate an HTML page which presents the requirements run: + +.. code-block:: shell + + doorstop publish all ./publish + +To make things easier, the ``Makefile`` creates a rule called ``dspub``. + +.. code-block:: shell + + dspub: + doorstop publish all ./publish + +Simply run the following command to generate the HTML page: + +.. code-block:: shell + + make dspub + +Finally to take a look at the requirements in an HTML format open the +``index.html`` file in the publish folder by running, for example: + +.. code-block:: shell + + sensible-browser ./publish/index.html + +To make it simpler the ``Makefile`` provides the ``dsshow`` rule: + + +.. code-block:: shell + + dsshow: + sensible-browser ./publish/index.html + +Thus, to open the requirements HTML page simply run: + +.. code-block:: shell + + make dsshow + +Traceability +------------ + +The ``index.html`` in the output folder will show the Item traceability. +Additionally requirements can also be traceable to code. + +Traceability to Code +******************** + +Doorstop provides the mechanisms to trace requirements to code by using the +``references`` property, see `here +`_. + +Checking for errors +------------------- + +To make sure the current modifications to the requirements do not cause errors +run the Makefile rule ``ci``: + +.. code-block:: shell + + make ci + + +