readme.rst
1.. SPDX-License-Identifier: BSD-3-Clause
2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
3
4.. image:: https://scan.coverity.com/projects/28411/badge.svg
5 :target: https://scan.coverity.com/projects/tf-rmm-tf-rmm
6
7.. image:: https://readthedocs.org/projects/tf-rmm/badge/?version=latest
8 :target: https://tf-rmm.readthedocs.io/en/latest/?badge=latest
9 :alt: Documentation Status
10
11#################
12Readme for TF-RMM
13#################
14
15`TF-RMM`_ (or simply RMM) is the `Trusted Firmware`_ Implementation of the
16`Realm Management Monitor (RMM) Specification`_. The RMM
17is a software component that runs at Realm EL2 and forms part of a system
18which implements the Arm Confidential Compute Architecture (Arm CCA).
19`Arm CCA`_ is an architecture which provides Protected Execution Environments
20called Realms.
21
22Prior to Arm CCA, virtual machines have to trust hypervisors that manage them
23and a resource that is managed by the hypervisor is also accessible by it.
24Exploits against the hypervisors can leak confidential data held in the virtual
25machines. `Arm CCA`_ introduces a new confidential compute environment called
26a `Realm`. Any code or data belonging to a `Realm`, whether in memory or in
27registers, cannot be accessed or modified by the hypervisor. This means that
28the Realm owner does not need to trust the hypervisor that manages the
29resources used by the Realm.
30
31The Realm VM is initiated and controlled by the Normal world Hypervisor.
32To allow the isolated execution of the Realm VM, a new component called the
33Realm Management Monitor (RMM) is introduced, executing at R_EL2. The
34hypervisor interacts with the RMM via Realm Management Interface (RMI) to
35manage the Realm VM. Policy decisions, such as which Realm to run or what
36memory to be delegated to the Realm are made by the hypervisor and communicated
37via the RMI. The RMM also provides services to the Realm via the Realm Service
38Interface (RSI). These services include cryptographic services and
39attestation. The Realm initial state can be measured and an attestation
40report, which also includes platform attestation, can be requested via RSI.
41The RSI is also the channel for memory management requests from the
42Realm VM to the RMM.
43
44The following diagram shows the complete Arm CCA software stack running a
45confidential Realm VM :
46
47|Realm VM|
48
49Figure 1. Realm VM execution
50
51The `TF-RMM`_ interacts with the Root EL3 Firmware via the
52`RMM-EL3 Communication Interface`_ and this is implemented by the reference
53EL3 Firmware implementation `TF-A`_.
54
55More details about the RMM and how it fits in the Software Stack can be
56found in `Arm CCA Software Stack Guide`_.
57
58The `Change-log and Release notes`_ has the details of features implemented
59by this version of `TF-RMM`_ and lists any known issues.
60
61*******
62License
63*******
64
65Unless specifically indicated otherwise in a file, `TF-RMM`_ files are provided
66under the `BSD-3-Clause License`_. For contributions, please
67see `License and Copyright for Contributions`_.
68
69Third Party Projects
70====================
71
72The `TF-RMM`_ project requires to be linked with certain other 3rd party
73projects and they are to be cloned from their repositories into ``ext`` folder
74before building. The projects are `MbedTLS`_, `t_cose`_, `QCBOR`_,
75`CppUTest`_ and `libspdm`_. `libspdm`_ repository is fetched during config phase
76when RMM_V1_1 build option is enabled.
77
78The project also contains files which are imported from other projects
79into the source tree and may have a different license. Such files with
80different licenses are listed in the table below. This table is used by the
81``checkspdx`` tool in the project to verify license headers.
82
83.. list-table:: **List of files with different license**
84
85 * - File
86 - License
87 * - lib/libc/src/printf.c
88 - MIT
89 * - lib/libc/include/stdio.h
90 - MIT
91 * - lib/libc/src/strlcpy.c
92 - ISC
93 * - lib/libc/src/strnlen.c
94 - BSD-2-Clause
95 * - lib/allocator/src/memory_alloc.c
96 - Apache-2.0
97
98
99************
100Contributing
101************
102
103We gratefully accept bug reports and contributions from the community.
104Please see the `Contributor's Guide`_ for details on how to do this.
105
106********************
107Feedback and support
108********************
109
110Feedback is requested via email to:
111`tf-rmm@lists.trustedfirmware.org <tf-rmm@lists.trustedfirmware.org>`__.
112
113To report a bug, please file an `issue on Github`_
114
115-----------------
116
117.. |Realm VM| image:: ./about/diagrams/cca_software_arch.png
118.. _Realm Management Monitor (RMM) Specification: https://developer.arm.com/documentation/den0137/1-0eac5/?lang=en
119.. _Arm CCA: https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture
120.. _Arm CCA Software Stack Guide: https://developer.arm.com/documentation/den0127/0100/Overview
121.. _TF-A: https://www.trustedfirmware.org/projects/tf-a/
122.. _RMM-EL3 Communication Interface: https://trustedfirmware-a.readthedocs.io/en/latest/components/rmm-el3-comms-spec.html
123.. _issue on Github: https://github.com/TF-RMM/tf-rmm/issues
124.. _MbedTLS: https://github.com/ARMmbed/mbedtls.git
125.. _t_cose: https://github.com/laurencelundblade/t_cose
126.. _QCBOR: https://github.com/laurencelundblade/QCBOR.git
127.. _Change-log and Release notes: https://tf-rmm.readthedocs.io/en/latest/about/change-log.html
128.. _BSD-3-Clause License: https://tf-rmm.readthedocs.io/en/latest/about/license.html
129.. _License and Copyright for Contributions: https://tf-rmm.readthedocs.io/en/latest/process/contributing.html#license-and-copyright-for-contributions
130.. _Contributor's Guide: https://tf-rmm.readthedocs.io/en/latest/process/contributing.html
131.. _CppUTest: https://github.com/cpputest/cpputest.git
132.. _libspdm: https://github.com/DMTF/libspdm.git
133.. _Trusted Firmware: https://www.trustedfirmware.org/
134.. _TF-RMM: https://www.trustedfirmware.org/projects/tf-rmm/
135
