DOC: update documentation.
Add documentation covering:
- developer information about architecture
- project structure and building
- project overview and service descriptions
- the portability model for supporting hardware
Signed-off-by: Julian Hall <julian.hall@arm.com>
Co-Authored-By: Gyorgy Szing <gyorgy.szing@gmail.com>
Change-Id: I8bf9c01a66350719d82a7ca2bc1c78a8ab17978d
diff --git a/docs/project/change-log.rst b/docs/project/change-log.rst
new file mode 100644
index 0000000..fbabfa4
--- /dev/null
+++ b/docs/project/change-log.rst
@@ -0,0 +1,30 @@
+Change Log & Release Notes
+==========================
+
+This document contains a summary of the new features, changes, fixes and known
+issues in each release of Trusted Services.
+
+Version 0.1.0
+-------------
+
+New Features
+^^^^^^^^^^^^
+First release.
+
+Changes
+^^^^^^^
+None.
+
+Resolved Issues
+^^^^^^^^^^^^^^^
+None.
+
+Deprecations
+^^^^^^^^^^^^
+None.
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/coding-guidelines.rst b/docs/project/coding-guidelines.rst
new file mode 100644
index 0000000..3090aa4
--- /dev/null
+++ b/docs/project/coding-guidelines.rst
@@ -0,0 +1,73 @@
+Coding Style & Guidelines
+=========================
+
+The following sections contain |TS| coding guidelines. They are continually evolving and should not be considered "set
+in stone". Feel free to question them and provide feedback.
+
+The |TS| project uses multiple "domains" (textual content types, like programming languages) and each defines its own
+rules.
+
+To help configuring text editors the project comes with "`EditorConfig`_" file(s). (:download:`../../.editorconfig`).
+
+Shared rules
+------------
+
+The following rules are common for all domains, except where noted otherwise:
+
+#. Files shall be **UTF-8** encoded.
+#. Use **Unix** style line endings (``LF`` character)
+#. The primary language of the project is English. All comments and documentation must be in this language.
+#. Trailing whitespace is not welcome, please trim these.
+
+C Domain
+--------
+
+C source code rules are base on the *Linux Coding Style* (See: |LCS|). The following deviations apply:
+
+5. |TS| follows *ISO/IEC 9899:1999* standard with |ACLE| version *Q3 2020* extensions.
+#. Line length shall not exceed 100 characters.
+#. Use `snake_case`_ for function, variable and file names.
+#. Each file shall be "self contained" and include header files with external dependencies. No file shall depend on
+ headers included by other files.
+#. Include ordering: please include project specific headers first and then system includes. Please order the files
+ alphabetically in the above two groups.
+#. All variables must be initialized.
+
+Boring stuff is not for smart people and the project uses the `Uncrustify`_ code beautifier to easy formatting the
+source. (See :download:`../../.uncrustify.cfg`)
+
+CMake domain
+------------
+
+11. CMake file names use `CamelCase`_ style.
+#. Indent with tabs and otherwise use spaces. Use 4 spaces for tab size.
+#. Use LF as line end in CMake files.
+#. Remove trailing whitespace.
+#. Maximum line length is 128 characters.
+#. When complicated functionality is needed prefer CMake scripting over other languages.
+#. Prefix local variables with `_`.
+#. Use functions to prevent global name-space pollution.
+#. Use `snake_case`_ for function and variable names.
+#. Use the ``include_guard()`` CMake function when creating new modules, to prevent multiple inclusion.
+#. Use self contained modules, i.e. include direct dependencies of the module.
+#. Use the Sphinx CMake domain for in-line documentation of CMake scripts. For details please refer to the
+ `CMake Documentation`_.
+
+.. todo:: Explain CMake return values and parent scope concept in more detail.
+
+Restructured Text Domain
+------------------------
+
+Please refer to :doc:`/developer/writing-documentation`.
+
+--------------
+
+.. _`CamelCase`: https://hu.wikipedia.org/wiki/CamelCase
+.. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case
+.. _`CMake Documentation`: https://github.com/Kitware/CMake/blob/master/Help/dev/documentation.rst
+.. _`EditorConfig`: https://editorconfig.org/
+.. _`Uncrustify`: https://github.com/uncrustify/uncrustify
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/contributing.rst b/docs/project/contributing.rst
new file mode 100644
index 0000000..d9760d9
--- /dev/null
+++ b/docs/project/contributing.rst
@@ -0,0 +1,88 @@
+Contributing
+============
+
+
+Getting Started
+---------------
+
+- Make sure you have a GitHub account and you are logged on `developer.trustedfirmware.org`_.
+- Send an email to the |TS_MAIL_LIST| about your work. This gives everyone
+ visibility of whether others are working on something similar.
+- Clone the |TS_REPO| on your own machine.
+- Create a local topic branch based on ``main`` branch of the |TS_REPO|.
+
+Making Changes
+--------------
+
+- Make commits of logical units. See these general `Git guidelines`_ for contributing to a project.
+- Follow the :ref:`Coding Style & Guidelines`.
+- Keep the commits on topic. If you need to fix another bug or make another enhancement, please create a separate
+ change.
+- Avoid long commit series. If you do have a long series, consider whether some
+ commits should be squashed together or addressed in a separate topic.
+- Make sure your commit messages are in the proper format. Please keel the 50/72 rule (for details see `Tim Popes blog entry`_.)
+- Where appropriate, please update the documentation.
+
+ - Consider whether the this document or other in-source documentation
+ needs updating.
+ - Ensure that each changed file has the correct copyright and license information. Files that entirely consist of
+ contributions to this project should have a copyright notice and BSD-3-Clause SPDX license identifier of the form
+ as shown in :ref:`license`. Files that contain changes to imported Third Party IP files should retain their
+ original copyright and license notices. For significant contributions you may add your own copyright notice in
+ following format::
+
+ Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved.
+
+ where XXXX is the year of first contribution (if different to YYYY) and YYYY is the year of most recent
+ contribution. *<OWNER>* is your name or your company name.
+ - If you are submitting new files that you intend to be the technical sub-maintainer for (for example, a new platform
+ port), then also update the :ref:`maintainers` file.
+ - For topics with multiple commits, you should make all documentation changes (and nothing else) in the last commit
+ of the series. Otherwise, include the documentation changes within the single commit.
+
+- Please test your changes.
+
+Submitting Changes
+------------------
+
+- Ensure that each commit in the series has at least one ``Signed-off-by:`` line, using your real name and email
+ address. The names in the ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else contributes to the
+ commit, they must also add their own ``Signed-off-by:`` line. By adding this line the contributor certifies the
+ contribution is made under the terms of the :download:`Developer Certificate of Origin <../../dco.txt>`.
+
+ More details may be found in the `Gerrit Signed-off-by Lines guidelines`_.
+
+- Ensure that each commit also has a unique ``Change-Id:`` line. If you have cloned the repository with the "`Clone with
+ commit-msg hook`" clone method, this should already be the case.
+
+ More details may be found in the `Gerrit Change-Ids documentation`_.
+
+- Submit your changes for review at https://review.trustedfirmware.org targeting the ``integration`` branch.
+
+ - The changes will then undergo further review and testing by the :ref:`maintainers`. Any review comments will be made
+ directly on your patch. This may require you to do some rework.
+
+ Refer to the `Gerrit Uploading Changes documentation`_ for more details.
+
+- When the changes are accepted, the :ref:`maintainers` will integrate them.
+
+ - Typically, the :ref:`maintainers` will merge the changes into the ``integration`` branch.
+ - If the changes are not based on a sufficiently-recent commit, or if they cannot be automatically rebased, then the
+ :ref:`maintainers` may rebase it on the ``main`` branch or ask you to do so.
+ - After final integration testing, the changes will make their way into the ``main`` branch. If a problem is found
+ during integration, the merge commit will be removed from the ``integration`` branch and the :ref:`maintainers` will
+ ask you to create a new patch set to resolve the problem.
+
+--------------
+
+.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
+.. _Git guidelines: http://git-scm.com/book/ch5-2.html
+.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
+.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html
+.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html
+.. _`Tim Popes blog entry`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/glossary.rst b/docs/project/glossary.rst
new file mode 100644
index 0000000..da907b4
--- /dev/null
+++ b/docs/project/glossary.rst
@@ -0,0 +1,35 @@
+Glossary
+========
+
+This glossary provides definitions for terms and abbreviations used in the Trusted Services documentation.
+
+You can find additional definitions in the `Arm Glossary`_.
+
+.. glossary::
+ :sorted:
+
+ TF-A
+ Trusted Firmware-A
+
+ TS
+ Trusted Services
+
+ C identifier like string
+ A name which uses only alphanumeric characters and underscores and the first character is not a digit.
+
+ LCS
+ `Linux Coding Style`_
+
+ ACLE
+ `Arm C language extensions`_
+
+
+--------------
+
+.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary
+.. _`Linux Coding Style`: https://www.kernel.org/doc/html/v4.10/process/coding-style.html
+.. _`Arm C language extensions`: https://developer.arm.com/documentation/101028/0012/?lang=en
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/index.rst b/docs/project/index.rst
new file mode 100644
index 0000000..21f1d0f
--- /dev/null
+++ b/docs/project/index.rst
@@ -0,0 +1,21 @@
+About the project
+=================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ change-log
+ coding-guidelines
+ contributing
+ glossary
+ license
+ maintainers
+ versioning_policy
+ todo
+
+--------------
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/license.rst b/docs/project/license.rst
index 472bc6a..fb63be6 100644
--- a/docs/project/license.rst
+++ b/docs/project/license.rst
@@ -1,7 +1,7 @@
License
=======
-Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.
+Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
@@ -11,7 +11,7 @@
- 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.
-- Neither the name of ARM nor the names of its contributors may be used to
+- Neither the name of Arm nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior
written permission.
diff --git a/docs/project/maintainers.rst b/docs/project/maintainers.rst
index 61d13c5..992d926 100644
--- a/docs/project/maintainers.rst
+++ b/docs/project/maintainers.rst
@@ -1,9 +1,9 @@
Maintainers
===========
-|TS| is a Trusted Firmware maintained project. All contributions are ultimately
+|TS| is a trustedfirmware.org maintained project. All contributions are ultimately
merged by the maintainers listed below. Technical ownership of some parts of the
-codebase is delegated to the code owners listed below. An acknowledgement from
+code-base is delegated to the code owners listed below. An acknowledgment from
these code maintainers may be required before the maintainers merge a
contribution.
@@ -45,6 +45,6 @@
.. _`Linux Maintainers file`: https://github.com/torvalds/linux/blob/master/MAINTAINERS#L80
.. _Project Maintenance Process: https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/
-*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/todo.rst b/docs/project/todo.rst
new file mode 100644
index 0000000..1739eab
--- /dev/null
+++ b/docs/project/todo.rst
@@ -0,0 +1,22 @@
+TODO list
+=========
+
+This file collects information on planned future changes and issues to be
+addressed. For managing the TODO list below, the `Sphinx TODO extension`_ is
+used.
+
+.. todo:: Find a solution to make the rendering of TODO entries less intrusive
+ at their original location.
+
+List of TODO entries in the project
+-----------------------------------
+
+.. todolist::
+
+--------------
+
+.. _`Sphinx TODO extension`: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
\ No newline at end of file
diff --git a/docs/project/versioning_policy.rst b/docs/project/versioning_policy.rst
new file mode 100644
index 0000000..d57057f
--- /dev/null
+++ b/docs/project/versioning_policy.rst
@@ -0,0 +1,47 @@
+Versioning policy
+==================
+
+This document captures information about the version identifier used by the
+project. It tells the meaning of each part, where the version information is
+captured and how it is managed.
+
+Summary
+-------
+
+The version identifier identifies the feature set supported by a specific
+release, and captures compatibility information to other releases.
+
+This project uses "Semantic Versioning", for details please refer to |SEMVER|.
+
+In general the version number is constructed from three numbers. The `MAJOR`
+number is changed when incompatible API changes are introduced, the `MINOR`
+version when you functionality is added in a backward compatible manner, and
+the `PATCH` version when backwards compatible bug fixes are added.
+
+Each release will get a unique release id assigned. When a release is made, the
+version number will get incremented in accordance with the compatibility rules
+mentioned above.
+
+This project is only using the core version and will not use pre-release or
+build specific metadata extension.
+
+Storage and format
+------------------
+
+The version number of each release will be stored at two locations:
+ #. In a tag of the version control system in the form of "vX.Y.Z" where X Y
+ and Z are the major, minor and patch version numbers.
+ #. In a file called version.txt. This file uses ASCII encoding and will
+ contain the version number as "X.Y.Z" where X Y and Z are the major,
+ minor and patch version numbers.
+
+.. note:: The version id is independent from version identifiers of the
+ versioning system used to store the |TS| (i.e. git).
+
+--------------
+
+.. _`Semantic Versioning`: https://semver.org/spec/v2.0.0.html
+
+*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause