mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-09-05 19:00:16 +00:00
Documentation: move Trusty documentation to doc/
Move the existing Trusty document to the doc/ folder (where it belongs) and convert the text to ReST. The Documentation/ folder under hypervisor/ is removed as all documents should be put under doc/. All technical information has been preserved or was already available in other documents. Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This commit is contained in:
Geoffroy Van Cutsem
committed by
David Kinder
David Kinder
parent
666430a3d4
commit
d24179550e
@@ -794,6 +794,7 @@ INPUT = custom-doxygen/mainpage.md \
|
||||
../hypervisor/include/common/hypercall.h \
|
||||
../hypervisor/include/public/acrn_common.h \
|
||||
../hypervisor/include/public/acrn_hv_defs.h \
|
||||
../hypervisor/arch/x86/trusty.c \
|
||||
../devicemodel/include/virtio.h
|
||||
|
||||
|
||||
|
||||
@@ -9,6 +9,7 @@ Developer Guides
|
||||
primer.rst
|
||||
../api/index.rst
|
||||
../reference/kconfig/index.rst
|
||||
trusty.rst
|
||||
|
||||
|
||||
Contributing to the project
|
||||
|
||||
163
doc/developer-guides/trusty.rst
Normal file
163
doc/developer-guides/trusty.rst
Normal file
@@ -0,0 +1,163 @@
|
||||
.. _trusty_tee:
|
||||
|
||||
Trusty TEE on ACRN
|
||||
##################
|
||||
|
||||
Introduction
|
||||
************
|
||||
|
||||
`Trusty`_ is a set of software components supporting a Trusted Execution Environment (TEE).
|
||||
TEE is commonly known as an isolated processing environment in which applications can be
|
||||
securely executed irrespective of the rest of the system. For more information about TEE,
|
||||
please visit the `Trusted Execution Environment wikipage <https://en.wikipedia.org/wiki/Trusted_execution_environment>`_.
|
||||
Trusty consists of:
|
||||
|
||||
1. An operating system (the Trusty OS) that runs on a processor intended to provide a TEE
|
||||
#. Drivers for the Android kernel (Linux) to facilitate communication with applications
|
||||
running under the Trusty OS
|
||||
#. A set of libraries for Android/Linux systems software to facilitate communication with
|
||||
trusted applications executed within the Trusty OS using the kernel drivers
|
||||
|
||||
LK (`Little Kernel`_) is a tiny operating system suited for small embedded devices, bootloaders,
|
||||
and other environments where OS primitives such as threads, mutexes, and timers are needed, but
|
||||
there's a desire to keep things small and lightweight. LK has been chosen as the Trusty OS kernel.
|
||||
|
||||
Trusty Architecture
|
||||
*******************
|
||||
|
||||
Trusty Architectural diagram::
|
||||
|
||||
+---------------------------+
|
||||
|VMn |
|
||||
| ...... |
|
||||
+------------+ +---------------------------+ |
|
||||
|VM0 | |VM1 | |
|
||||
| | | +--------+ +--------+ | |
|
||||
| | | | | | | | |
|
||||
| SOS | | | Normal | | Secure | | |
|
||||
| | | | World | | World | |-+
|
||||
| | | | | | | |
|
||||
| | | +--------+ +--------+ |
|
||||
+------------+ +---------------------------+
|
||||
+-------------------------------------------+
|
||||
| ACRN Hypervisor |
|
||||
+-------------------------------------------+
|
||||
+-------------------------------------------+
|
||||
| HW |
|
||||
+-------------------------------------------+
|
||||
|
||||
.. note::
|
||||
Trusty OS is running in Secure World in the architecture drawing above.
|
||||
|
||||
Trusty specific Hypercalls
|
||||
**************************
|
||||
|
||||
There are a few :ref:`hypercall_apis` that are related to Trusty.
|
||||
|
||||
.. doxygengroup:: trusty_hypercall
|
||||
:project: Project ACRN
|
||||
:content-only:
|
||||
|
||||
Trusty Boot flow
|
||||
****************
|
||||
|
||||
By design, the User OS bootloader (``UOS_Loader``) will trigger the Trusty boot process. The complete bootflow is illustrated below.
|
||||
|
||||
.. graphviz:: trusty/boot-flow.dot
|
||||
:name: trusty-boot-flow
|
||||
:align: center
|
||||
:caption: Trusty Boot Flow
|
||||
|
||||
As shown in the above figure, here are some details about the Trusty boot flow processing:
|
||||
|
||||
1. UOS_Loader
|
||||
|
||||
a. Load and verify Trusty image from virtual disk
|
||||
#. Allocate runtime memory for trusty
|
||||
#. Do ELF relocation of trusty image and get entry address
|
||||
#. Call ``hcall_initialize_trusty`` with trusty memory base and entry address
|
||||
#. ACRN (``hcall_initialize_trusty``)
|
||||
|
||||
a. Save World context for Normal World
|
||||
#. Init World context for Secure World (RIP, RSP, EPT, etc.)
|
||||
#. Resume to Secure World
|
||||
#. Trusty
|
||||
|
||||
a. Booting up
|
||||
#. Call ``hcall_world_switch`` to switch back to Normal World if boot completed
|
||||
#. ACRN (``hcall_world_switch``)
|
||||
|
||||
a. Save World context for the World which caused this ``vmexit`` (Secure World)
|
||||
#. Restore World context for next World (Normal World (UOS_Loader))
|
||||
#. Resume to next World (UOS_Loader)
|
||||
#. UOS_Loader
|
||||
|
||||
a. Continue to boot
|
||||
|
||||
EPT Hierarchy
|
||||
*************
|
||||
|
||||
As per the Trusty design, Trusty can access Normal World's memory, but Normal World cannot
|
||||
access Secure World's memory. Hence it means Secure World EPTP page table hierarchy
|
||||
must contain normal world GPA address space, while Trusty world's GPA address space
|
||||
must be removed from the Normal world EPTP page table hierarchy.
|
||||
|
||||
Design
|
||||
======
|
||||
|
||||
Put Secure World's GPA to very high position: 511 GB - 512 GB. The PML4/PDPT for Trusty
|
||||
World are separated from Normal World. PD/PT for low memory (< 511 GB) are shared in
|
||||
both Trusty World's EPT and Normal World's EPT. PD/PT for high memory (>= 511 GB) are
|
||||
valid for Trusty World's EPT only.
|
||||
|
||||
Benefit
|
||||
=======
|
||||
|
||||
This design will benefit the EPT changes of Normal World. There are requirement to
|
||||
modify Normal World's EPT during runtime such as increasing memory, changing attributes,
|
||||
etc. If such behavior happened, only PD and PT for Normal World need to
|
||||
be updated.
|
||||
|
||||
::
|
||||
|
||||
ABSTRACT EPT hierarchy for 2 Worlds:
|
||||
==================================================================== ==================================================
|
||||
: Normal World : : Secure World :
|
||||
: PML4 : : PML4 :
|
||||
: +--------+ : : +--------+ :
|
||||
: | | : : | | :
|
||||
: | | : : PD | | :
|
||||
: | | : : +-------+ | | :
|
||||
: | | : : | | | | :
|
||||
: | 0-512G |--+ : : | | +--| 0-512G | :
|
||||
:EPTP -->+--------+ | : : | | | +--------+<-- EPTP :
|
||||
: | PDPT : : | | PDPT | :
|
||||
: | +--------+ : : | | +--------+ | :
|
||||
: | | >=511G |---> Not present : : +-------+<--| >=511G | | :
|
||||
: | |________| : : |________| | :
|
||||
: | | | : : | | | :
|
||||
: | | <511G |->+<----------------------------:--------:--------------| <511G | | :
|
||||
: | | | | : : | | | :
|
||||
: +-->+--------+ | PD PT : : +--------+<-+ :
|
||||
: | ... ... : ==================================================
|
||||
: | +-------+ +-------+ :
|
||||
: | +-------+| +-------+| :
|
||||
: | | || | || :
|
||||
: | | || | || :
|
||||
: | | PDE |--+ | || :
|
||||
: | | || | | || :
|
||||
: | | |+ | | |+ :
|
||||
: +-->+-------+ +-->+-------+ :
|
||||
: :
|
||||
====================================================================
|
||||
|
||||
|
||||
API
|
||||
===
|
||||
|
||||
.. doxygengroup:: trusty_apis
|
||||
:project: Project ACRN
|
||||
:content-only:
|
||||
|
||||
.. _Trusty: https://source.android.com/security/trusty/
|
||||
.. _Little Kernel: https://github.com/littlekernel/lk
|
||||
10
doc/developer-guides/trusty/boot-flow.dot
Normal file
10
doc/developer-guides/trusty/boot-flow.dot
Normal file
@@ -0,0 +1,10 @@
|
||||
digraph G {
|
||||
rankdir=LR;
|
||||
rank=same;
|
||||
bgcolor="transparent";
|
||||
uosl1 [label="UOS_Loader"]
|
||||
acrn_init [shape=box style="rounded,filled" label="ACRN"]
|
||||
acrn_switch [shape=box style="rounded,filled" label="ACRN"]
|
||||
uosl2 [label="UOS_Loader"]
|
||||
uosl1 -> acrn_init -> "Trusty" -> acrn_switch -> uosl2;
|
||||
}
|
||||
Reference in New Issue
Block a user