Docs: Restructuring and new layout
This patch implements a set of user-experiences aimed
changes.It modifies the documentation structure and
switches to a more reactive design for the rtd theme.
* The documentation layout has been redesigned to be more
intuitive,easier to maintain and and scale.
* The landing page introduces a new dashboard.
* Introduced dedicated space for release documents, and
changelog has been modified to directly source content
from referenced documents.
* Added quick-link navigation for items that need emphasis.
* Relevant design documents can now be grouped in suf-folders.
* There is dedicated space for custom platform, and third
party tools documents.
* Wildcard and regex matching has been introduced to indexes.
Change-Id: Ib02d17d5d26187d397ba17317788cf2a01401b07
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
diff --git a/docs/contributing/coding_guide.rst b/docs/contributing/coding_guide.rst
new file mode 100644
index 0000000..099d3b3
--- /dev/null
+++ b/docs/contributing/coding_guide.rst
@@ -0,0 +1,79 @@
+##############################
+Yet another coding standard :)
+##############################
+
+.. Warning::
+
+ Every rule has an exception so if you disagree or dislike then reach out!
+
+The coding style of TF-M project is based on
+`Linux coding style <https://www.kernel.org/doc/html/v4.10/process/coding-style.html>`__
+but there are updates for domain specific conventions as listed below.
+
+TF-M also reuses code from other SW projects, e.g. ``CMSIS_5``, which
+means some areas of code may have different styles. We use common sense approach
+and new code may inherit coding style from external projects but it needs to
+remain within clear scope.
+
+The guidance below is provided as a help. It isn't meant to be a definitive
+list.
+
+As implied in the :doc:`contributing guide </docs/contributing/contributing>`
+maintainers have the right to decide on what's acceptable in case of any
+divergence.
+
+.. Warning::
+
+ Text files do not fall within these rules as they may require different formatting.``
+
+****************
+Consistent style
+****************
+The code needs to be consistent with itself, so if existing code in the file
+violates listed coding style rules then it is better to follow existing style
+in the file and not break consistency by following the rules listed here.
+
+You may need to add a comment in the commit description to clarify this.
+
+List of rules
+=============
+
+- Use 4 spaces indentation. No tabs.
+- Use ``lower_case_with_underscore`` for filenames, variable and function names.
+- Use standard types e.g. ``uint32_t``, ``uint16_t``, ``uint8_t``, ``int32_t``
+ etc.
+- Use ``uintptr_t`` type when representing addresses as numbers.
+- Use static for all private functions and variables.
+- Use void argument if your function doesn't contain any argument.
+- Use C90 ``/* */`` for comments rather than C99 ``//``
+- No trailing spaces in code.
+- Max 80 characters length. Text files are exception as stated above.
+- Open curly brace ``{`` at the same if/else/while/for/switch statement line.
+- Use curly braces ``{ }`` for one line statement bodies also.
+- Put open curly brace in the line below the function header.
+- Order function parameters so that input params are before output params.
+- Declare local variables at the beginning of the function.
+- Define macros in all caps i.e. ``CAPITAL_WITH_UNDERSCORE``.
+- Use typedefs **ONLY** for function prototype declarations.
+- Type definitions in ``lower_case_with_underscore`` ended by ``_t``.
+- Do not use typedef for other constructs as it obfuscates code.
+- Do not use bitfields.
+- Use static for all global variables to reduce the variable scope.
+- Use enumeration for error codes to keep the code readable.
+- Use descriptive variable and functions names.
+- Put the correct license header at the beginning of the file.
+- Keep the files (.h/.c) self-contained, i.e. put include dependencies in the
+ file.
+- Put appropriate header define guard in .h files: ``__HEADER_NAME__``.
+ Any divergence from this rules should be clearly documented.
+- In a .c file, #include it's own header file first.
+- Document all the public functions in the header file only.
+- Document all the private functions in the source file only.
+- Add "extern C " definition for C++ support in the header files.
+- In the switch statement, aligned cases with the switch keyword.
+- For enums, use upper case letters with digits and underscore only.
+- Do not code while eating.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/contributing.rst b/docs/contributing/contributing.rst
new file mode 100644
index 0000000..761f52f
--- /dev/null
+++ b/docs/contributing/contributing.rst
@@ -0,0 +1,69 @@
+Contributing
+============
+
+Contributions to the TF-M project need to follow the process below.
+
+.. Note::
+
+ Please contact :doc:`maintainers </docs/contributing/maintainers>` for any
+ questions.
+
+- Subscribe to `TF-M development
+ <https://lists.trustedfirmware.org/mailman/listinfo/tf-m>`_ if not subscribed
+ already.
+- Refer to the `Roadmap
+ <https://developer.trustedfirmware.org/w/tf_m/planning>`_ or send a mail to
+ the tf-m@lists.trustedfirmware.org to check if this work is already
+ planned/progresses elsewhere.
+- Create a task in `Phabricator
+ <https://developer.trustedfirmware.org/maniphest>`_, put as many details as
+ possible in the description. Add 'Trusted Firmware M' in the 'Tags' field.
+- For non-trivial changes, need to follow the design proposal process
+ :doc:`Design Proposal Process </docs/contributing/tfm_design_proposal_process>`
+ for the TF-M project.
+- After the design has been accepted by the maintainer(s), a corresponding
+ patch should be posted; follow guidelines below:
+
+ - Clone the TF-M code on your own machine from `TF-M git repository
+ <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git>`_.
+ - Follow the :doc:`SW Requirements </docs/getting_started/tfm_sw_requirement>`,
+ :doc:`Build Instructions </docs/getting_started/tfm_build_instruction>` and
+ :doc:`Coding Guide </docs/contributing/coding_guide>` for the TF-M project.
+ - Make your changes in logical chunks to help reviewers. Each commit should
+ be a separate review and either work properly or be squashed after the
+ review and before merging.
+ - Update documentation in docs/ folder if needed.
+ - Test your changes and add details to the commit description.
+ - The code is accepted under :doc:`DCO </docs/contributing/dco>`, Developer
+ Certificate of Origin, so you must add following fields to your
+ commit description:
+
+ .. code-block:: text
+
+ Author: Full Name <email address>
+ Signed-off-by: Full Name <email address>
+
+ .. Note::
+
+ Sign off authority needs to adhere to the [DCO](./dco.txt) rules.
+
+ - You may add other fields in the commit message. Need to add the Task ID link
+ in the comment for the commit.
+ - Submit your patch for review.
+
+ .. code-block:: shell
+
+ git push ssh://review.trustedfirmware.org:29418/TF-M/trusted-firmware-m.git HEAD:refs/for/master
+
+- Add relevant :doc:`maintainers </docs/contributing/maintainers>` for reviewing
+ the patch.
+- You may be asked to provide further details or make additional changes.
+- You can discuss further with maintainer(s) by directly over email if
+ necessary.
+- Once the change is approved by maintainers, the patch will be merged by the
+ maintainer.
+- Mark the task as 'resolved' after patch is merged.
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/dco.rst b/docs/contributing/dco.rst
new file mode 100644
index 0000000..7a5a4c3
--- /dev/null
+++ b/docs/contributing/dco.rst
@@ -0,0 +1,12 @@
+
+###############################
+Developer Certificate of Origin
+###############################
+
+.. include:: /dco.txt
+ :literal:
+
+
+-----------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
new file mode 100644
index 0000000..f21a1c7
--- /dev/null
+++ b/docs/contributing/index.rst
@@ -0,0 +1,14 @@
+Contributing
+============
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :glob:
+ :numbered:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/lic.rst b/docs/contributing/lic.rst
new file mode 100644
index 0000000..b8d4ce5
--- /dev/null
+++ b/docs/contributing/lic.rst
@@ -0,0 +1,10 @@
+
+#######
+License
+#######
+
+.. include:: /license.rst
+
+-----------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/maintainers.rst b/docs/contributing/maintainers.rst
new file mode 100644
index 0000000..811035f
--- /dev/null
+++ b/docs/contributing/maintainers.rst
@@ -0,0 +1,77 @@
+Maintainers
+===========
+
+Trusted Firmware M is a community maintained project. Contributions can only
+be approved and merged by the maintainers listed below.
+Sub-maintainers' approval is required for their specific areas of ownership.
+
+Contributions must follow the instructions in
+:doc:`Contributing Guidelines </docs/contributing/contributing>`.
+
+Main maintainers
+----------------
+
+Abhishek Pandit
+ :email: `abhishek.pandit@arm.com <abhishek.pandit@arm.com>`__
+ :github: `abhishek-pandit <https://github.com/abhishek-pandit>`__
+
+Ashutosh Singh
+ :email: `ashutosh.singh@arm.com <ashutosh.singh@arm.com>`__
+ :github: `ashutoshksingh <https://github.com/ashutoshksingh>`__
+
+Miklos Balint
+ :email: `miklos.balint@arm.com <miklos.balint@arm.com>`__
+ :github: `wmnt <https://github.com/wmnt>`__
+
+Sub-maintainers
+---------------
+
+Bootloader
+~~~~~~~~~~
+
+Tamas Ban
+ :email: `Tamas.Ban@arm.com <Tamas.Ban@arm.com>`__
+ :github: `tamban01 <https://github.com/tamban01>`__
+
+Secure Storage (ITS & PS)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Jamie Fox
+ :email: `jamie.fox@arm.com <jamie.fox@arm.com>`__
+ :github: `jf549 <https://github.com/jf549>`__
+
+Crypto
+~~~~~~
+
+Soby Mathew
+ :email: `Soby.Mathew@arm.com <Soby.Mathew@arm.com>`__
+ :github: `soby-mathew <https://github.com/soby-mathew>`__
+
+SPM & IPC
+~~~~~~~~~
+
+Ken Liu
+ :email: `Ken.Liu@arm.com <Ken.Liu@arm.com>`__
+ :github: `KenLSoft <https://github.com/KenLSoft>`__)
+
+Mate Toth-Pal
+ :email: `Mate.Toth-Pal@arm.com <Mate.Toth-Pal@arm.com>`__
+ :github: `matetothpal <https://github.com/matetothpal>`__)
+
+Audit Log
+~~~~~~~~~
+
+Anton Komlev
+ :email: `Anton.Komlev <Anton.Komlev@arm.com>`__
+ :github: `Anton-TF <https://github.com/Anton-TF>`__
+
+Attestation
+~~~~~~~~~~~
+
+Tamas Ban
+ :email: `Tamas.Ban@arm.com <Tamas.Ban@arm.com>`__
+ :github: `tamban01 <https://github.com/tamban01>`__
+
+--------------
+
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*
diff --git a/docs/contributing/tfm_design_proposal_process.rst b/docs/contributing/tfm_design_proposal_process.rst
new file mode 100644
index 0000000..0be4d04
--- /dev/null
+++ b/docs/contributing/tfm_design_proposal_process.rst
@@ -0,0 +1,156 @@
+Design proposal process
+=======================
+
+:Author: Gyorgy Szing
+:Organisation: Arm Limited
+:Contact: Gyorgy Szing <gyorgy.szing@arm.com>
+
+Purpose and Content
+-------------------
+This document describes the steps of adding/changing Trusted Firmware design. It
+specifies:
+
+ - The documentation format to be used.
+ - The information which shall be captured.
+ - The steps of the process.
+ - The location where the information shall be captured during the process.
+
+General
+-------
+The Trusted Firmware project uses the
+`reStructuredText <http://docutils.sourceforge.net/rst.html>`_ format with
+`Sphinx <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+extensions for documentation. Design documents shall be captured in this format.
+
+Design documents are kept under version control at the project's
+`Gerrit server <https://review.trustedfirmware.org>`_. All decisions made and
+important information gathered during the design discussion, which is not part
+of the design document shall be captured as Gerrit comments or notes for
+archiving purposes. To meet this requirement this process encourages the use of
+the Gerrit web UI for communication.
+
+
+Status of a document
+---------------------
+The status of the document is captured in a *reST filed* called *Status*.
+Bibliographic fields like the *Status* shall be kept near to the top of the
+document after the document title.
+
+Example document fragment::
+
+ TF-M Crypto Service design
+ --------------------------
+
+ :Author: Antonio de Angelis
+ :Organization: Arm Limited
+ :Contact: Antonio de Angelis <antonio.deangelis@arm.com>
+ :Status: Draft
+
+Design documents are kept in three different sections of the documentation
+reflecting the status of the document. The status of the document determines
+the section it is in. Open (*Draft* and *Detailed* status) and accepted design
+documents shall be put to the ``docs/design_documents`` directory.
+
+.. important::
+ - 'Author' and 'Organization' can be *OPTIONAL* but at least one of them is
+ *MANDATORY*.
+ - 'Contact' is *MANDATORY* and must be valid for contacting with 'Author'
+ or 'Organization'.
+ - 'Status' is *OPTIONAL* if the design document is managed under a version
+ control tool. In this 'Status' field not available case, a guideline can be:
+
+ - No review comments given design is a *Draft* design.
+ - Positive review comments given design is a *Detailed* design.
+ - Merged design is an *Accepted* design.
+
+Preparation
+-------------
+In order to work on TF-M documentation the TF-M git repository has to be
+available locally. Setting up the documentation tools will allow pre-viewing the
+documentation file in preparation.
+For information on what tools are needed please refer to
+:doc:`sw requirements </docs/getting_started/tfm_sw_requirement>`. To see how to get
+a local copy of the TF-M repository please see
+:doc:`build instructions </docs/getting_started/tfm_build_instruction>`
+
+Process steps
+-------------
+
+- Write the design proposal in the format that is described in this document
+ with the *Status* set to *Draft* if *Status* field is provided. Put it to the
+ ``docs/design_documents`` directory and create a pull request.
+- Start an e-mail thread on the
+ `TF-M mailing list <mailto:tf-m@lists.trustedfirmware.org>`_ for discussing
+ the proposal.
+- Build initial consensus within the community about the proposed design
+ change, rework it according to the feedbacks and identify members who would
+ like to participate in the detailed review.
+- When the "short list" of members who are willing to participate in the
+ detailed review is established, set the *Status* field to *Detailed* if
+ *Status* field is provided and push the change to Gerrit.
+- Add the members of the "short list" to the Gerrit review as reviewers.
+- The detailed discussion then takes place in the Gerrit review and gets
+ recorded there.
+ Additional changes are submitted as new commits to the review.
+- When the proposal is accepted and *Status* field is provided, the *Status*
+ field is set to *Accepted* and update the change then get merged.
+
+.. uml::
+
+ @startuml
+ !define DRAFT_DIR **docs/design_documents/**
+ !define REJECTED_DIR **docs/design_documents/rejected/**
+ !define GERRIT_URL https://review.trustedfirmware.org
+ !define GERRIT_LINK [[GERRIT_URL trustedfirmware.org]]
+ !define MAINTAINER_RST_URL https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/docs/maintainers.rst
+ !define TFM_MAILING_LIST mailto:tf-m@lists.trustedfirmware.org
+ !define NO_DECISION **no**
+ !define YES_DECISION **yes**
+ !define STATUS_DRAFT **Draft**
+ !define STATUS_DETAILED **Detailed**
+ !define STATUS_REJECTED **Rejected**
+ !define STATUS_ACCEPTED **Accepted**
+
+ title Design Proposal Process
+
+ start
+ :Create first draft.in [[http://docutils.sourceforge.net/rst.html ReST format]];
+ :Set it's available 'Status' field to STATUS_DRAFT.;
+
+ :Add your document under DRAFT_DIR.;
+ :Create pull-request at GERRIT_LINK.;
+ partition "Initial review." {
+ :Start an e-mail thread at [[TFM_MAILING_LIST tf-m mailing list]].;
+ repeat
+ :Build initial consensus within the
+ community about the proposed design change.;
+ :Gather developers interested in detailed review.;
+ repeat while (Ready for detailed review?)
+ }
+
+ partition "Detailed review." {
+ :Set available 'Status' field to STATUS_DETAILED.;
+ :Add reviewers to pull request.;
+
+ repeat
+ :Discuss design in Gerrit comments/notes.;
+ :Log the result of discussions over
+ other communication channels
+ as Gerrit comments/notes.;
+ :Push new document version if needed.;
+ repeat while (Consensus reached?)
+ }
+
+ if (Design is accepted?) then (STATUS_ACCEPTED)
+ :Sets available 'Status' field to STATUS_ACCEPTED.;
+ ://Submit// the pull-request.;
+ else (STATUS_REJECTED)
+ endif
+
+ stop
+
+ @enduml
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*