Add first version of CMake framework code
This commit adds the core elements of the framework and documentation:
- Map utility: store key-value pairs.
- Group utility: store build configuration options.
- STGT API: describe the targets.
- Compiler abstraction functions for GCC.
- Other helper functions.
- New CMake system type called "Embedded", using correct output file
prefixes and extensions.
- Sphinx based documentation which includes:
- licensing information
- version numbering policy
- documentation on how-to build the documentation
In addition the following utility files are added:
- .editorconfig
- .gitignore
Change-Id: If19a171ef066775d3544fba82f1cc70a5fb0e7d7
Signed-off-by: Balint Dobszay <balint.dobszay@arm.com>
Co-authored-by: Gyorgy Szing <gyorgy.szing@arm.com>
Co-authored-by: Bence Szépkúti <bence.szepkuti@arm.com>
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..f23d058
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,25 @@
+#
+# Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/change-log.rst b/doc/change-log.rst
new file mode 100644
index 0000000..76c979a
--- /dev/null
+++ b/doc/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 Firmware-A CMake Framework.
+
+Version 0.1.0
+-------------
+
+New Features
+^^^^^^^^^^^^
+First release.
+
+Changes
+^^^^^^^
+None.
+
+Resolved Issues
+^^^^^^^^^^^^^^^
+None.
+
+Deprecations
+^^^^^^^^^^^^
+None.
+
+--------------
+
+*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/coding-guidelines.rst b/doc/coding-guidelines.rst
new file mode 100644
index 0000000..cda68bc
--- /dev/null
+++ b/doc/coding-guidelines.rst
@@ -0,0 +1,36 @@
+Coding Style & Guidelines
+=========================
+
+The following sections contain |TFACMF| coding guidelines. They are continually
+evolving and should not be considered "set in stone". Feel free to question them
+and provide feedback.
+
+Rules
+-----
+
+#. CMake file names use `CamelCase`_ formating.
+#. Indent with tabs and otherwise use spaces. Use 4 spaces for tab size.
+#. Use LF as line end in CMake files.
+#. Remove trailing whitespace.
+#. 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.
+
+--------------
+
+.. _`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
+
+*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..31885eb
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+
+# -- Metadata about this file ------------------------------------------------
+__copyright__ = "Copyright (c) 2019-2020 Arm Limited"
+__license__ = "SPDX-License-Identifier: BSD-3-Clause"
+
+# Configuration file for the Sphinx documentation builder.
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+project = 'CMake Framework'
+
+# The full version, including alpha/beta/rc tags
+with open('../version.txt', 'r') as f:
+ release = f.read()
+ f.close()
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.plantuml',
+ 'sphinxcontrib.moderncmakedomain', 'sphinx.ext.todo']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# 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 = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# Load the contents of the global substitutions file into the 'rst_prolog'
+# variable. This ensures that the substitutions are all inserted into each page.
+with open('global_substitutions.txt', 'r') as subs:
+ rst_prolog = subs.read()
+# Minimum version of sphinx required
+needs_sphinx = '2.0'
+
+# -- Options for HTML output -------------------------------------------------
+
+# Don't show the "Built with Sphinx" footer
+html_show_sphinx = False
+
+# Don't show copyright info in the footer (we have this content in the page)
+html_show_copyright = False
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = "sphinx_rtd_theme"
+
+# The logo to display in the sidebar
+# html_logo = ''
+
+# Options for the "sphinx-rtd-theme" theme
+html_theme_options = {
+ 'collapse_navigation': False, # Can expand and collapse sidebar entries
+ 'prev_next_buttons_location': 'both', # Top and bottom of the page
+ 'style_external_links': True # Display an icon next to external links
+}
+
+# -- Options for autosectionlabel --------------------------------------------
+
+# Only generate automatic section labels for document titles
+autosectionlabel_maxdepth = 1
+
+# -- Options for plantuml ----------------------------------------------------
+
+plantuml_output_format = 'svg_img'
+
+# -- Options for todo extension ----------------------------------------------
+
+# Display todos
+todo_include_todos = True
diff --git a/doc/contributing.rst b/doc/contributing.rst
new file mode 100644
index 0000000..a2d3398
--- /dev/null
+++ b/doc/contributing.rst
@@ -0,0 +1,107 @@
+Contributing
+============
+
+
+Getting Started
+---------------
+
+- Make sure you have a Github account and you are logged on
+ `developer.trustedfirmware.org`_.
+- Send an email to the |TFACMF-MAIL-LIST| about your work. This gives
+ everyone visibility of whether others are working on something similar.
+- Clone the `TFACMF repository`_ on your own machine as suggested in the
+ :ref:`User Guide`.
+- Create a local topic branch based on the `TFACMF repository`_ ``master``
+ branch.
+
+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.
+- Where appropriate, please update the documentation.
+
+ - Consider whether the :ref:`User Guide` 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
+ (as advised on the :ref:`User Guide`), 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 ``master`` branch or ask you to do so.
+ - After final integration testing, the changes will make their way into the
+ ``master`` 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
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/docs-build.rst b/doc/docs-build.rst
new file mode 100644
index 0000000..7ef059e
--- /dev/null
+++ b/doc/docs-build.rst
@@ -0,0 +1,77 @@
+Building Documentation
+======================
+
+To create a rendered copy of this documentation locally you can use the
+`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
+pages.
+
+If you are building the documentation for the first time then you will need to
+check that you have the required software packages, as described in the
+*Prerequisites* section that follows.
+
+Prerequisites
+-------------
+
+For building a local copy of the |TFACMF| documentation you will need, at minimum:
+
+- GNUMake
+- Python 3 (3.5 or later)
+- PlantUML (1.2017.15 or later)
+
+You must also install the Python modules that are specified in the
+``requirements.txt`` file in the root of the ``docs`` directory. These modules
+can be installed using ``pip3`` (the Python Package Installer). Passing this
+requirements file as an argument to ``pip3`` automatically installs the specific
+module versions required.
+
+Example environment
+-------------------
+
+An example set of installation commands for Linux with the following assumptions:
+ #. OS and version: Ubuntu 18.04 LTS
+ #. `virtualenv` is used to separate the python dependencies
+ #. pip is used for python dependency management
+ #. `bash` is used as the shell.
+
+.. code:: shell
+
+ sudo apt install make python3 python3-pip virtualenv python3-virtualenv plantuml
+ virtualenv -p python3 ~/tfacmf-venv
+ . ~/tfacmf-venv/bin/activate
+ pip3 install -r requirements.txt
+ deactivate
+
+.. note::
+ More advanced usage instructions for *pip* are beyond the scope of this
+ document but you can refer to the `pip homepage`_ for detailed guides.
+
+.. note::
+ For more information on Virtualenv please refer to the `Virtualenv documentation`_
+
+Building rendered documentation
+-------------------------------
+
+From the ``docs`` directory of the project, run the following commands.
+
+.. code:: shell
+
+ . ~/tfacmf-venv/bin/activate
+ make clean
+ make SPHINXOPTS=-W html
+ deactivate
+
+Output from the build process will be placed in:
+
+::
+
+ <tf-a CMF root>/docs/_build/html/
+
+--------------
+
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _pip homepage: https://pip.pypa.io/en/stable/
+.. _`Virtualenv documentation`: https://virtualenv.pypa.io/en/latest/
+
+*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/gcc.rst b/doc/gcc.rst
new file mode 100644
index 0000000..58d9ba3
--- /dev/null
+++ b/doc/gcc.rst
@@ -0,0 +1,7 @@
+.. cmake-module:: ../Compiler/GCC.cmake
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/global_substitutions.txt b/doc/global_substitutions.txt
new file mode 100644
index 0000000..0d00064
--- /dev/null
+++ b/doc/global_substitutions.txt
@@ -0,0 +1,17 @@
+.. |TF-A| replace:: :term:`TF-A`
+.. |TFACMF| replace:: :term:`TFACMF`
+
+.. |C identifier like string| replace:: :term:`C identifier like string`
+
+.. |TFACMF-MAIL-LIST| replace:: `TF-A Mailing List`_
+.. |TFACMF_REPO| replace:: `TFACMF repository`_
+
+.. _`TF-A Mailing List`: https://lists.trustedfirmware.org/mailman/listinfo/tf-a
+.. _`TFACMF repository`: https://review.trustedfirmware.org/TF-A/cmake-framework.git
+
+..
+ --------------
+
+ *Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+
+ SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/glossary.rst b/doc/glossary.rst
new file mode 100644
index 0000000..78e8723
--- /dev/null
+++ b/doc/glossary.rst
@@ -0,0 +1,28 @@
+Glossary
+========
+
+This glossary provides definitions for terms and abbreviations used in the TF-A
+documentation.
+
+You can find additional definitions in the `Arm Glossary`_.
+
+.. glossary::
+ :sorted:
+
+ TF-A
+ Trusted Firmware-A
+
+ TFACMF
+ Trusted Firmware-A CMake Framework
+
+ C identifier like string
+ A name which uses only alphanumeric characters and underscores and the
+ first character is not a digit.
+
+--------------
+
+.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary
+
+*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/group.rst b/doc/group.rst
new file mode 100644
index 0000000..7c6543c
--- /dev/null
+++ b/doc/group.rst
@@ -0,0 +1,7 @@
+.. cmake-module:: ../Common/Group.cmake
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..d57d815
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,43 @@
+Welcome to TF-A CMake Framework's documentation!
+================================================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents:
+
+ Home<self>
+ license
+ change-log
+ contributing
+ coding-guidelines
+ maintainers
+ user_guide
+ map
+ group
+ stgt
+ gcc
+ utils
+ docs-build
+ software_requirements
+ versioning_policy
+ glossary
+ todo
+
+The CMake Framework is a set of CMake functions organised into logical modules,
+adding missing features to CMake and standardizing the usage of existing ones.
+The framework's primary purpose is to simplify creating cross-compiled, embedded
+projects.
+
+The current version of the framework is version |release|. For details about
+changes between versions please refer to the :ref:`Change Log & Release Notes`.
+
+For information on planned changes and issues to be addressed please refer to
+:ref:`TODO list`.
+
+.. todo:: Expand general description of the framework.
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/license.rst b/doc/license.rst
new file mode 100644
index 0000000..2c44ee2
--- /dev/null
+++ b/doc/license.rst
@@ -0,0 +1,37 @@
+License
+=======
+
+Copyright (c) 2019, 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:
+
+- Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+- 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
+ endorse or promote products derived from this software without specific prior
+ written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+--------------
+
+*Note*:
+Individual files contain the following tag instead of the full license text.
+
+ SPDX-License-Identifier: BSD-3-Clause
+
+This enables machine processing of license information based on the SPDX
+License Identifiers that are here available: http://spdx.org/licenses/
\ No newline at end of file
diff --git a/doc/maintainers.rst b/doc/maintainers.rst
new file mode 100644
index 0000000..b87f4a0
--- /dev/null
+++ b/doc/maintainers.rst
@@ -0,0 +1,38 @@
+Maintainers
+===========
+
+|TFACMF| is an Arm maintained project. All contributions are ultimately merged
+by the maintainers listed below. Technical ownership of some parts of the
+codebase is delegated to the sub-maintainers listed below. An acknowledgement
+from these sub-maintainers may be required before the maintainers merge
+a contribution.
+
+This file follows the format of the Linux Maintainers file. For details on the
+meaning of tags below please refer to the `Linux Maintainers file`_.
+
+Main maintainers
+----------------
+:M: Dan Handley <dan.handley@arm.com>
+:G: `danh-arm`_
+:M: Bálint Dobszay <balint.dobszay@arm.com>
+:G: `balintdobszay`_
+:M: György Szing <gyorgy.szing@arm.com>
+:G: `gyuri-szing`_
+:L: |TFACMF-MAIL-LIST|
+
+Sub-maintainers
+--------------------
+
+Currently none.
+
+--------------
+
+.. _danh-arm: https://github.com/danh-arm
+.. _gyuri-szing: https://github.com/gyuri-szing
+.. _balintdobszay: https://github.com/balintdobszay
+
+.. _`Linux Maintainers file`: https://github.com/torvalds/linux/blob/master/MAINTAINERS#L80
+
+*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/map.rst b/doc/map.rst
new file mode 100644
index 0000000..a737b2e
--- /dev/null
+++ b/doc/map.rst
@@ -0,0 +1,7 @@
+.. cmake-module:: ../Common/Map.cmake
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000..ff3a3f6
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,11 @@
+#
+# Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Python dependencies for building the documentation.
+
+Sphinx==2.3.1
+sphinx-rtd-theme==0.4.3
+sphinxcontrib-moderncmakedomain==3.13
+sphinxcontrib-plantuml==0.18
diff --git a/doc/software_requirements.rst b/doc/software_requirements.rst
new file mode 100644
index 0000000..6d36e67
--- /dev/null
+++ b/doc/software_requirements.rst
@@ -0,0 +1,17 @@
+Software Requirements
+=====================
+
+The following applications and modules are required to use the framework:
+
+ * CMake, version 3.13 or newer
+ * GNU Make, version 4.2 or newer
+
+To build the documentation, please refer to :ref:`Building Documentation`.
+
+.. todo:: Describe cross-compiler requirements.
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/stgt.rst b/doc/stgt.rst
new file mode 100644
index 0000000..0858e4c
--- /dev/null
+++ b/doc/stgt.rst
@@ -0,0 +1,7 @@
+.. cmake-module:: ../Common/STGT.cmake
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/todo.rst b/doc/todo.rst
new file mode 100644
index 0000000..06e3666
--- /dev/null
+++ b/doc/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, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
\ No newline at end of file
diff --git a/doc/user_guide.rst b/doc/user_guide.rst
new file mode 100644
index 0000000..d4e87e4
--- /dev/null
+++ b/doc/user_guide.rst
@@ -0,0 +1,180 @@
+User Guide
+==========
+
+This guide describes how the framework features are supposed to be used, through
+an example implementation for the |TF-A| project. Please refer to the `TF-A
+repository`_ for the code.
+
+Root CMakeLists file
+--------------------
+
+The root CMakeLists file contains the following sections:
+
+#. Set required CMake version
+
+ This is mandatory at the start of every CMake project. The framework
+ requires version 3.13 or newer.
+
+#. Set default build type
+
+ Set the default value for ``CMAKE_BUILD_TYPE`` as a cache entry. This
+ ensures that the variable will have a value when it is not specified as a
+ command line argument.
+
+#. Set project root dir
+
+ This is not strictly necessary, but makes referring to project relative
+ paths easier. Using ``CMAKE_CURRENT_LIST_DIR`` is recommended, it contains
+ the absolute path to the directory containing the currently processed file.
+
+#. Find the framework
+
+ The framework is written as a CMake module, which can be used by
+ :cmake:command:`find_package`. This will take care of the version matching
+ and adding the framework dir to the module path.
+
+ In the example, we try to find the framework at the parent directory of the
+ TF-A project dir and inside the TF-A project. If the framework is not
+ found, we clone the git repository using :cmake:module:`FetchContent`. The
+ path to the framework can also be provided as a command line option to
+ CMake, using ``-DTFACMF_DIR=<path to framework>``.
+
+#. Add project specific paths
+
+ There are some CMake modules which are specific to the project, so cannot
+ be part of the generic framework (e.g. find fiptool). These should also be
+ added to the module path.
+
+#. Set CMake system parameters
+
+ The framework provides a new platform called ``Embedded``. The project
+ should set :cmake:variable:`CMAKE_SYSTEM_NAME` to ``Embedded`` in order to
+ use the platform. This is an important step as this method is the only way
+ in CMake to ensure the correct output extension, library name
+ prefix/suffix, etc.
+
+ :cmake:variable:`CMAKE_SYSTEM_PROCESSOR` should be set to ``arm``. This has
+ no particular effect, but it indicates that the project is cross-compiled.
+
+#. Include framework files
+
+ It is more convenient to include the framework files here. The config and
+ target files included later will inherit the environment.
+
+#. Start CMake project
+
+ The start of a CMake project, ``C`` and ``ASM`` languages should be
+ selected.
+
+#. Find platform module
+
+ Currently for finding platform related config a minimal
+ :cmake:command:`find_package` module is implemented. These module files
+ describing the platform are located in the ``<TF-A root>/cmake/HwPlat``
+ directory, which is added to :cmake:variable:`CMAKE_MODULE_PATH` in the
+ project specific paths section.
+
+ A platform description file contains more :cmake:command:`find_package`
+ calls to find other external tools which are needed by the platform, and
+ sets the following global variables:
+
+ * :cmake:variable:`HW_PLAT_CONFIG`: path to config file which contains
+ the :cmake:module:`group` for the platform options,
+ * :cmake:variable:`HW_PLAT_TARGET`: path to target file which contains
+ target creation, adding source files, etc. for the platform,
+ * :cmake:variable:`HW_PLAT_IMAGE`: path to file which describes the steps
+ of packaging the compiled binaries into an image (e.g. fiptool usage).
+
+ The files indicated by these variables should be included in the relevant
+ sections of the root CMakeLists file, as described below.
+
+#. Include config files
+
+ All the config files containing the settings groups have to be included.
+ These create and fill the groups with content, so in the target files we
+ can select which group to apply on which target. This means including the
+ :cmake:variable:`HW_PLAT_CONFIG` too.
+
+#. Include target files
+
+ The target files selected for the current build have to be included. These
+ create the target and add source files, includes, etc. to the target.
+ Include :cmake:variable:`HW_PLAT_TARGET` in this section.
+
+ Currently there is no solution provided to select which targets are
+ necessary, except adding/removing the include command in this section. A
+ better solution would be to decide based on the current build configuration
+ (from Kconfig?) so targets can be selected without modifying the CMakeLists
+ file.
+
+#. Include image files
+
+ The files describing how to package the output binaries into an image can
+ be included here. Since this is platform specific, only
+ :cmake:variable:`HW_PLAT_IMAGE` should be used.
+
+Config file
+-----------
+
+The config files are located in the ``<TF-A root>/configs`` directory. Each
+config file creates a :cmake:module:`group` using :cmake:command:`group_new` and
+fills the group with content using :cmake:command:`group_add`.
+
+An important topic in the example is the difference between the ``CONFIG`` and
+``DEFINE`` types in a group. The idea is, that ``CONFIG`` is a parameter that
+affects the build, i.e. what sources are necessary for a given target, etc.
+while ``DEFINE`` is a simple C language define. Often a build option falls into
+both categories, but not necessarily. For example,
+
+* ``ENABLE_AMU`` is a config, because it affects the build, it determines
+ whether ``amu.c`` is added to ``BL31`` or not. It is a define too, because
+ there is ``#if ENABLE_AMU`` conditional compilation in the C source,
+
+* ``FVP_MAX_PE_PER_CPU`` is a define only, because it does not affect the list
+ of files necessary for the build,
+
+* ``ENABLE_STACK_PROTECTOR`` is a config only, because it is never used in the
+ source code.
+
+Target file
+-----------
+
+A target file can be one of two types, ``CMakeLists.txt`` or ``<module
+name>.cmake``. The former is for a module which is likely to be reused in other
+projects and can be built stand-alone, the latter is a module which only has
+meaning as part of the project. A ``CMakeLists.txt`` must contain a
+:cmake:command:`project` command and has to be included using
+:cmake:command:`add_subdirectory`, while a ``<module name>.cmake`` cannot start
+a new project and the file is simply included with the :cmake:command:`include`
+command.
+
+A target file uses the :cmake:module:`STGT` functions to create a target, add
+groups to the target, add source files, etc. Please check the example code in
+TF-A, e.g.:
+
+* ``bl*/bl*.cmake``
+* ``plat/arm/board/fvp/platform.cmake``
+* ``plat/arm/common/arm_common.cmake``
+* ``lib/libc/CMakeLists.txt``
+* etc.
+
+Image file
+----------
+
+The purpose of this file is to package the output binaries into an image, using
+the platform specific tools. The recommendation is to use
+:cmake:command:`add_custom_target` which depends on the targets/files packaged
+into the image. It is likely that ``ALL`` should be added to the command
+options, since usually this image is the final output of the build, so no other
+targets will depend on this therefore it would not be built without ``ALL``.
+Please check the example in ``plat/arm/board/fvp/image.cmake``.
+
+.. todo:: Add support for ``install`` feature of CMake.
+
+--------------
+
+.. _`TF-A repository`: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/utils.rst b/doc/utils.rst
new file mode 100644
index 0000000..f0eee13
--- /dev/null
+++ b/doc/utils.rst
@@ -0,0 +1,7 @@
+.. cmake-module:: ../Common/Utils.cmake
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/doc/versioning_policy.rst b/doc/versioning_policy.rst
new file mode 100644
index 0000000..83f45c7
--- /dev/null
+++ b/doc/versioning_policy.rst
@@ -0,0 +1,50 @@
+Versioning policy
+==================
+
+This document captures information about how the version identifier of the
+|TFACMF| is built up, what is 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 of the |TFACMF|, and captures compatibility information to other
+releases.
+
+This project uses "Semantic Versioning v2.0". For details please refer to
+|SMVC| v2.0.
+
+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 |TFACMF| (i.e. git).
+
+--------------
+
+.. |SMVC| replace:: `Semantic Versioning`_
+.. _`Semantic Versioning`: https://semver.org/spec/v2.0.0.html
+
+*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause