1.. _trusty_tee:
2
3Trusty TEE
4##########
5
6Introduction
7************
8
9`Trusty`_ is a set of software components supporting a Trusted Execution
10Environment (TEE). TEE is commonly known as an isolated processing environment
11in which applications can be securely executed irrespective of the rest of the
12system. For more information about TEE, visit the
13`Trusted Execution Environment wiki page <https://en.wikipedia.org/wiki/Trusted_execution_environment>`_.
14Trusty consists of:
15
161. An operating system (the Trusty OS) that runs on a processor intended to
17   provide a TEE
18#. Drivers for the Android kernel (Linux) to facilitate communication with
19   applications running under the Trusty OS
20#. A set of libraries for Android/Linux systems software to facilitate
21   communication with trusted applications executed within the Trusty OS using
22   the kernel drivers
23
24LK (`Little Kernel`_) is a tiny operating system for small embedded
25devices, bootloaders, and other environments that need OS primitives such as
26threads, mutexes, and timers.  LK has been chosen as the Trusty OS kernel.
27
28Trusty Architecture
29*******************
30
31.. figure:: images/trusty-arch.png
32   :align: center
33   :width: 800px
34   :name: trusty-architectural-diagram
35
36   Trusty Architectural Diagram
37
38.. note::
39   The Trusty OS is running in the Secure World in the architecture drawing
40   above.
41
42.. _trusty-hypercalls:
43
44Trusty Specific Hypercalls
45**************************
46
47The following :ref:`hypercall_apis` are related to Trusty.
48
49.. doxygengroup:: trusty_hypercall
50   :project: Project ACRN
51   :content-only:
52
53Trusty Boot Flow
54****************
55
56By design, the User VM OS bootloader will trigger the Trusty
57boot process. The complete boot flow is illustrated below.
58
59.. graphviz:: images/trusty-boot-flow.dot
60   :name: trusty-boot-flow
61   :align: center
62   :caption: Trusty Boot Flow
63
64As shown in the above figure, here are some details about the Trusty
65boot flow processing:
66
671. User VM OS bootloader
68
69   a. Load and verify Trusty image from virtual disk
70   #. Allocate runtime memory for Trusty
71   #. Do ELF relocation of Trusty image and get entry address
72   #. Call ``hcall_initialize_trusty`` with Trusty memory base and
73      entry address
74#. ACRN (``hcall_initialize_trusty``)
75
76   a. Save World context for Normal World
77   #. Init World context for Secure World (RIP, RSP, EPT, etc.)
78   #. Resume to Secure World
79#. Trusty
80
81   a. Booting
82   #. Call ``hcall_world_switch`` to switch back to Normal World if
83      boot completed
84#. ACRN (``hcall_world_switch``)
85
86   a. Save World context for the World that caused this ``vmexit``
87      (Secure World)
88   #. Restore World context for next World (Normal World: User VM OS bootloader)
89   #. Resume to next World (User VM OS bootloader)
90#. User VM OS bootloader
91
92   a. Continue to boot
93
94EPT Hierarchy
95*************
96
97As per the Trusty design, Trusty can access the Normal World's memory, but the
98Normal World cannot access the Secure World's memory.  The Secure
99World EPTP page table hierarchy must contain the Normal World GPA address space,
100while the Trusty world's GPA address space must be removed from the Normal World
101EPTP page table hierarchy.
102
103Design
104======
105
106Put the Secure World's GPA to a very high position:  511 GB - 512 GB.  The
107PML4/PDPT for the Trusty World are separated from the Normal World.  PD and PT
108for low memory
109(< 511 GB) are shared in both the Trusty World's EPT and the Normal World's EPT.
110PD and PT for high memory (>= 511 GB) are valid for the Trusty World's EPT only.
111
112Benefit
113=======
114
115The Normal World's EPT can be modified during runtime. Examples include
116increasing memory and changing attributes. If such behavior happens, only PD and
117PT for the Normal World need to be updated.
118
119.. figure:: images/ept-hierarchy.png
120   :align: center
121   :width: 800px
122   :name: ept-hierarchy
123
124   EPT Hierarchy
125
126API
127===
128
129.. doxygengroup:: trusty_apis
130   :project: Project ACRN
131   :content-only:
132
133.. _Trusty: https://source.android.com/security/trusty/
134.. _Little Kernel: https://github.com/littlekernel/lk
135