TF-RMM Release v0.1.0
This is the first external release of TF-RMM and provides a reference
implementation of Realm Management Monitor (RMM) as specified by the
RMM Beta0 specification[1].
The `docs/readme.rst` has more details about the project and
`docs/getting_started/getting-started.rst` has details on how to get
started with TF-RMM.
[1] https://developer.arm.com/documentation/den0137/1-0bet0/?lang=en
Signed-off-by: Soby Mathew <soby.mathew@arm.com>
Change-Id: I205ef14c015e4a37ae9ae1a64e4cd22eb8da746e
diff --git a/docs/readme.rst b/docs/readme.rst
new file mode 100644
index 0000000..8af1396
--- /dev/null
+++ b/docs/readme.rst
@@ -0,0 +1,117 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+
+######
+TF-RMM
+######
+
+TF-RMM (or simply RMM) is the Trusted Firmware Implementation of the `Realm
+Management Monitor (RMM) Specification`_. The RMM
+is a software component that runs at Realm EL2 and forms part of a system
+which implements the Arm Confidential Compute Architecture (Arm CCA).
+`Arm CCA`_ is an architecture which provides Protected Execution Environments
+called Realms.
+
+Prior to Arm CCA, virtual machines have to trust hypervisors that manage them
+and a resource that is managed by the hypervisor is also accessible by it.
+Exploits against the hypervisors can leak confidential data held in the virtual
+machines. `Arm CCA`_ introduces a new confidential compute environment called
+a `Realm`. Any code or data belonging to a `Realm`, whether in memory or in
+registers, cannot be accessed or modified by the hypervisor. This means that
+the Realm owner does not need to trust the hypervisor that manages the
+resources used by the Realm.
+
+The Realm VM is initiated and controlled by the Normal world Hypervisor.
+To allow the isolated execution of the Realm VM, a new component called the
+Realm Management Monitor (RMM) is introduced, executing at R_EL2. The
+hypervisor interacts with the RMM via Realm Management Interface (RMI) to
+manage the Realm VM. Policy decisions, such as which Realm to run or what
+memory to be delegated to the Realm are made by the hypervisor and communicated
+via the RMI. The RMM also provides services to the Realm via the Realm Service
+Interface (RSI). These services include cryptographic services and
+attestation. The Realm initial state can be measured and an attestation
+report, which also includes platform attestation, can be requested via RSI.
+The RSI is also the channel for memory management requests from the
+Realm VM to the RMM.
+
+The following diagram shows the complete Arm CCA software stack running a
+confidential Realm VM :
+
+|Realm VM|
+
+Figure 1. Realm VM execution
+
+The TF-RMM interacts with the Root EL3 Firmware via the
+`RMM-EL3 Communication Interface`_ and this is implemented by the reference
+EL3 Firmware implementation `TF-A`_.
+
+More details about the RMM and how it fits in the Software Stack can be
+found in `Arm CCA Software Stack Guide`_.
+
+The :ref:`Change-log and Release notes` has the details of features implemented
+by this version of TF-RMM and lists any known issues.
+
+*******
+License
+*******
+
+Unless specifically indicated otherwise in a file, TF-RMM files are provided
+under the :ref:`BSD-3-Clause License <License>`. For contributions, please
+see :ref:`License and Copyright for Contributions <copyright-license-guidance>`.
+
+Third Party Projects
+====================
+
+The TF-RMM project requires to be linked with certain other 3rd party projects
+and they are to be cloned from their repositories into ``ext`` folder before
+building. The projects are `MbedTLS`_, `t_cose`_, and `QCBOR`_.
+
+The project also contains files which are imported from other projects
+into the source tree and may have a different license. Such files with
+different licenses are listed in the table below. This table is used by the
+``checkspdx`` tool in the project to verify license headers.
+
+.. list-table:: **List of files with different license**
+
+ * - File
+ - License
+ * - lib/libc/src/printf.c
+ - MIT
+ * - lib/libc/include/stdio.h
+ - MIT
+ * - lib/libc/src/strlcpy.c
+ - ISC
+ * - lib/libc/src/strnlen.c
+ - BSD-2-Clause
+ * - lib/allocator/src/memory_alloc.c
+ - Apache-2.0
+
+
+************
+Contributing
+************
+
+We gratefully accept bug reports and contributions from the community.
+Please see the :ref:`Contributor's Guide` for details on how to do this.
+
+********************
+Feedback and support
+********************
+
+Feedback is requested via email to:
+`tf-rmm@lists.trustedfirmware.org <tf-rmm@lists.trustedfirmware.org>`__.
+
+To report a bug, please file an `issue on Github`_
+
+-----------------
+
+.. |Realm VM| image:: ./about/diagrams/cca_software_arch.png
+.. _Realm Management Monitor (RMM) Specification: https://developer.arm.com/documentation/den0137/1-0bet0/?lang=en
+.. _Arm CCA: https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture
+.. _Arm CCA Software Stack Guide: https://developer.arm.com/documentation/den0127/0100/Overview
+.. _TF-A: https://www.trustedfirmware.org/projects/tf-a/
+.. _RMM-EL3 Communication Interface: https://trustedfirmware-a.readthedocs.io/en/latest/components/rmm-el3-comms-spec.html
+.. _issue on Github: https://github.com/TF-RMM/tf-rmm/issues
+.. _MbedTLS: https://github.com/ARMmbed/mbedtls.git
+.. _t_cose: https://github.com/laurencelundblade/t_cose
+.. _QCBOR: https://github.com/laurencelundblade/QCBOR.git