github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-18 11:47:30 +00:00
Code Issues Projects Releases Wiki Activity

doc: copy edits in the developer reference

Browse Source 
Signed-off-by: Benjamin Fitch <benjamin.fitch@intel.com>
This commit is contained in:
Benjamin Fitch 2021-04-01 16:28:25 -07:00 committed by fitchbe
parent 86176a30a0
commit 8c8df1afb9
12 changed files with 848 additions and 847 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
doc/developer-guides/GVT-g-porting.rst
View File

@ -6,36 +6,36 @@ GVT-g Enabling and Porting Guide
Introduction
************
GVT-g is Intel's Open Source GPU virtualization solution, up-streamed to
GVT-g is Intel's open-source GPU virtualization solution, up-streamed to
the Linux kernel. Its implementation over KVM is named KVMGT, over Xen
is named XenGT, and over ACRN is named AcrnGT. GVT-g can export
multiple virtual-GPU (vGPU) instances for virtual machine (VM) system. A
VM can be assigned one instance of a vGPU. The guest OS graphic driver
needs only minor modifications to drive the vGPU adapter in a VM. Every
vGPU instance adopts the full HW GPU's acceleration capability for
media, 3D rendering, and display.
is named XenGT, and over ACRN is named AcrnGT. GVT-g can export multiple
virtual-GPU (vGPU) instances for a virtual machine (VM) system. A VM can be
assigned one instance of a vGPU. The guest OS graphic driver needs only
minor modifications to drive the vGPU adapter in a VM. Every vGPU instance
adopts the full HW GPU's acceleration capability for media, 3D rendering,
and display.
AcrnGT refers to the glue layer between the ACRN hypervisor and GVT-g
core device model. It works as the agent of hypervisor-related services.
It is the only layer that needs to be rewritten when porting GVT-g to
other specific hypervisors.
It is the only layer that must be rewritten when porting GVT-g to other
specific hypervisors.
For simplicity, in the rest of this document, the term GVT is used to
refer to the core device model component of GVT-g, specifically
corresponding to ``gvt.ko`` when build as a module.
For simplicity, in the rest of this document, the term GVT is used to refer
to the core device model component of GVT-g, specifically corresponding to
``gvt.ko`` when built as a module.
Purpose of This Document
************************
This document explains the relationship between components of GVT-g in
the ACRN hypervisor, shows how to enable GVT-g on ACRN, and guides
developers porting GVT-g to work on other hypervisors.
This document explains the relationship between components of GVT-g in the
ACRN hypervisor, shows how to enable GVT-g on ACRN, and guides developers
porting GVT-g to work on other hypervisors.
This document describes:
- the overall components of GVT-g
- interaction interface of each component
- core interaction scenarios
- the interaction interface of each component
- the core interaction scenarios
APIs of each component interface can be found in the :ref:`GVT-g_api`
documentation.
@ -44,47 +44,46 @@ documentation.
Overall Components
******************
For the GVT-g solution for the ACRN hypervisor, there are two
key modules: AcrnGT and GVT:
For the GVT-g solution for the ACRN hypervisor, there are two key modules:
AcrnGT and GVT.
AcrnGT module
Compiled from ``drivers/gpu/drm/i915/gvt/acrn_gvt.c``, the AcrnGT
module acts as a glue layer between the ACRN hypervisor and the
interface to the ACRN-DM in user space.
AcrnGT is the agent of hypervisor related services, including I/O trap
AcrnGT is the agent of hypervisor-related services, including I/O trap
request, IRQ injection, address translation, VM controls, etc. It also
listens to ACRN hypervisor in ``acrngt_emulation_thread``, and informs GVT
module of I/O traps.
listens to ACRN hypervisor in ``acrngt_emulation_thread``, and informs the
GVT module of I/O traps.
It calls into the GVT module's :ref:`intel_gvt_ops_interface` to invoke
Device Model's routines, and receives request from GVT module through
Device Model's routines, and receives requests from the GVT module through
the :ref:`MPT_interface`.
User space programs, such as ACRN-DM, communicate with AcrnGT through
User-space programs, such as ACRN-DM, communicate with AcrnGT through
the :ref:`sysfs_interface` by writing to sysfs node
``/sys/kernel/gvt/control/create_gvt_instance``.
This is the only module that needs to be rewritten when porting to
another embedded device hypervisor.
This is the only module that must be rewritten when porting to another
embedded device hypervisor.
GVT module
This Device Model service is the central part of all
GVT-g components. It receives workloads from each vGPU, shadows the
workloads, and dispatches the workloads to Dom0's i915 module to deliver
workloads to real hardware. It also emulates the virtual display to each
VM.
This Device Model service is the central part of all the GVT-g components.
It receives workloads from each vGPU, shadows the workloads, and
dispatches the workloads to the Service VM's i915 module to deliver
workloads to real hardware. It also emulates the virtual display to each VM.
VHM module
This is a kernel module that requires an interrupt (vIRQ) number,
and exposes APIs to external kernel modules such as GVT-g, and the
This is a kernel module that requires an interrupt (vIRQ) number and
exposes APIs to external kernel modules such as GVT-g and the
virtIO BE service running in kernel space. It exposes a char device node
in user space, and only interacts with the DM. The DM routes I/O
requests and responses between other modules to and from the VHM module
via the char device. DM may use the VHM for hypervisor service
(including remote memory map), and VHM may directly service the request
such as for the remote memory map, or invoking hypercall. It also sends
I/O responses to user space modules, notified by vIRQ injections.
in user space, and interacts only with the DM. The DM routes I/O requests
and responses between other modules to and from the VHM module via the
char device. DM may use the VHM for hypervisor service (including remote
memory map), and VHM may directly service the request such as for the
remote memory map or invoking hypercall. It also sends I/O responses to
user-space modules, notified by vIRQ injections.
.. figure:: images/GVT-g-porting-image1.png
@ -101,21 +100,21 @@ Core Scenario Interaction Sequences
vGPU Creation Scenario
======================
In this scenario, AcrnGT receives a create request from ACRN-DM. It
calls GVT's :ref:`intel_gvt_ops_interface` to inform GVT of vGPU
creation. This interface sets up all vGPU resources such as MMIO, GMA,
PVINFO, GTT, DISPLAY, and Execlists, and calls back to the AcrnGT
module through the :ref:`MPT_interface` ``attach_vgpu``. Then, the
AcrnGT module sets up an I/O request server and asks to trap the PCI
configure space of the vGPU (virtual device 0:2:0) via VHM's APIs.
Finally, the AcrnGT module launches an AcrnGT emulation thread to
listen to I/O trap notifications from HVM and ACRN hypervisor.
In this scenario, AcrnGT receives a create request from ACRN-DM. It calls
GVT's :ref:`intel_gvt_ops_interface` to inform GVT of vGPU creation. This
interface sets up all vGPU resources such as MMIO, GMA, PVINFO, GTT,
DISPLAY, and Execlists, and calls back to the AcrnGT module through the
:ref:`MPT_interface` ``attach_vgpu``. Then, the AcrnGT module sets up an
I/O request server and asks to trap the PCI configure space of the vGPU
(virtual device 0:2:0) via VHM's APIs. Finally, the AcrnGT module launches
an AcrnGT emulation thread to listen to I/O trap notifications from HVM and
ACRN hypervisor.
vGPU Destroy Scenario
=====================
In this scenario, AcrnGT receives a destroy request from ACRN-DM. It
calls GVT's :ref:`intel_gvt_ops_interface` to inform GVT of the vGPU destroy
In this scenario, AcrnGT receives a destroy request from ACRN-DM. It calls
GVT's :ref:`intel_gvt_ops_interface` to inform GVT of the vGPU destroy
request, and cleans up all vGPU resources.
vGPU PCI Configure Space Write Scenario
@ -136,28 +135,26 @@ config space write:
PCI Configure Space Read Scenario
=================================
Call sequence is almost the same as the write scenario above,
but instead it calls the GVT's :ref:`intel_gvt_ops_interface`
The call sequence is almost the same as in the write scenario above, but
instead it calls the GVT's :ref:`intel_gvt_ops_interface`
``emulate_cfg_read`` to emulate the vGPU PCI config space read.
GGTT Read/Write Scenario
========================
GGTT's trap is set up in the PCI configure space write
scenario above.
GGTT's trap is set up in the PCI configure space write scenario above.
MMIO Read/Write Scenario
========================
MMIO's trap is set up in the PCI configure space write
scenario above.
MMIO's trap is set up in the PCI configure space write scenario above.
PPGTT Write-Protection Page Set/Unset Scenario
==============================================
PPGTT write-protection page is set by calling ``acrn_ioreq_add_iorange``
with range type as ``REQ_WP``, and trap its write to device model while
allowing read without trap.
The PPGTT write-protection page is set by calling ``acrn_ioreq_add_iorange``
with range type as ``REQ_WP`` and trapping its write to the device model
while allowing read without trap.
PPGTT write-protection page is unset by calling ``acrn_ioreq_del_range``.

89
doc/developer-guides/VBSK-analysis.rst
View File

@ -6,29 +6,27 @@ VBS-K Framework Virtualization Overhead Analysis
Introduction
************
The ACRN Hypervisor follows the Virtual I/O Device (virtio)
specification to realize I/O virtualization for many
performance-critical devices supported in the ACRN project. The
hypervisor provides the virtio backend service (VBS) APIs, that make it
very straightforward to implement a virtio device in the hypervisor. We
can evaluate the virtio backend service in kernel-land (VBS-K) framework
overhead through a test virtual device called virtio-echo. The total
overhead of a frontend-backend application based on VBS-K consists
of VBS-K framework overhead and application-specific overhead. The
application-specific overhead depends on the specific frontend-backend
design, from microseconds to seconds. In our HW case, the overall VBS-K
framework overhead is on the microsecond level, sufficient to meet the
needs of most applications.
The ACRN Hypervisor follows the Virtual I/O Device (virtio) specification to
realize I/O virtualization for many performance-critical devices supported in
the ACRN project. The hypervisor provides the virtio backend service (VBS)
APIs, which make it very straightforward to implement a virtio device in the
hypervisor. We can evaluate the virtio backend service in kernel-land (VBS-K)
framework overhead through a test virtual device called virtio-echo. The
total overhead of a frontend-backend application based on VBS-K consists of
VBS-K framework overhead and application-specific overhead. The
application-specific overhead depends on the specific frontend-backend design,
from microseconds to seconds. In our hardware case, the overall VBS-K
framework overhead is on the microsecond level, sufficient to meet the needs
of most applications.
Architecture of VIRTIO-ECHO
***************************
virtio-echo is a virtual device based on virtio, and designed for
testing ACRN virtio backend services in the kernel (VBS-K) framework. It
includes a virtio-echo frontend driver, a virtio-echo driver in ACRN
device model (DM) for initialization, and a virtio-echo driver based on
VBS-K for data reception and transmission. For more virtualization
background introduction, please refer to:
virtio-echo is a virtual device based on virtio, and designed for testing
ACRN virtio backend services in the kernel (VBS-K) framework. It includes a
virtio-echo frontend driver, a virtio-echo driver in ACRN device model (DM)
for initialization, and a virtio-echo driver based on VBS-K for data reception
and transmission. For more virtualization background introduction, refer to:
* :ref:`introduction`
* :ref:`virtio-hld`
@ -37,9 +35,9 @@ virtio-echo is implemented as a virtio legacy device in the ACRN device
model (DM), and is registered as a PCI virtio device to the guest OS
(User VM). The virtio-echo software has three parts:
- **virtio-echo Frontend Driver**: This driver runs in the User VM. It prepares
the RXQ and notifies the backend for receiving incoming data when the
User VM starts. Second, it copies the received data from the RXQ to TXQ
- **virtio-echo Frontend Driver**: This driver runs in the User VM. It
prepares the RXQ and notifies the backend for receiving incoming data when
the User VM starts. Second, it copies the received data from the RXQ to TXQ
and sends them to the backend. After receiving the message that the
transmission is completed, it starts again another round of reception
and transmission, and keeps running until a specified number of cycles
@ -54,9 +52,9 @@ model (DM), and is registered as a PCI virtio device to the guest OS
be a specific value and sends the data to the frontend driver. After
receiving the data in RXQ, the fronted driver copies the data to the
TXQ, and then sends them back to the backend. The backend driver then
notifies the frontend driver that the data in the TXQ has
been successfully received. In virtio-echo, the backend driver
doesn't process or use the received data.
notifies the frontend driver that the data in the TXQ has been successfully
received. In virtio-echo, the backend driver doesn't process or use the
received data.
:numref:`vbsk-virtio-echo-arch` shows the whole architecture of virtio-echo.
@ -70,14 +68,14 @@ model (DM), and is registered as a PCI virtio device to the guest OS
Virtualization Overhead Analysis
********************************
Let's analyze the overhead of the VBS-K framework. As we know, the VBS-K
handles notifications in the Service VM kernel instead of in the Service VM user space
DM. This can avoid overhead from switching between kernel space and user
space. Virtqueues are allocated by User VM, and virtqueue information is
configured to VBS-K backend by the virtio-echo driver in DM, thus
virtqueues can be shared between User VM and Service VM. There is no copy overhead
in this sense. The overhead of VBS-K framework mainly contains two
parts: kick overhead and notify overhead.
Let's analyze the overhead of the VBS-K framework. As we know, the VBS-K
handles notifications in the Service VM kernel instead of in the Service VM
user space DM. This can avoid overhead from switching between kernel space
and user space. Virtqueues are allocated by User VM, and virtqueue
information is configured to VBS-K backend by the virtio-echo driver in DM;
thus virtqueues can be shared between User VM and Service VM. There is no
copy overhead in this sense. The overhead of VBS-K framework mainly contains
two parts: kick overhead and notify overhead.
- **Kick Overhead**: The User VM gets trapped when it executes sensitive
instructions that notify the hypervisor first. The notification is
@ -96,8 +94,8 @@ parts: kick overhead and notify overhead.
defined as the interval from the beginning of the interrupt injection
to when the User VM starts interrupt processing.
The overhead of a specific application based on VBS-K includes two
parts: VBS-K framework overhead and application-specific overhead.
The overhead of a specific application based on VBS-K includes two parts:
VBS-K framework overhead and application-specific overhead.
- **VBS-K Framework Overhead**: As defined above, VBS-K framework overhead
refers to kick overhead and notify overhead.
@ -111,10 +109,9 @@ the virtualization scheme based on VBS-K framework. Costs of one "kick"
operation and one "notify" operation are both on a microsecond level.
Overhead of steps marked as blue depend on specific frontend and backend
virtual device drivers. For virtio-echo, the whole end-to-end process
(from step1 to step 9) costs about 4 dozens of microsecond. That's
because virtio-echo does little things in its frontend and backend
driver that is just for testing and there is very little process
overhead.
(from step1 to step 9) costs about four dozen microseconds. That's
because virtio-echo performs small operations in its frontend and backend
driver that are just for testing, and there is very little process overhead.
.. figure:: images/vbsk-image1.png
:width: 600px
@ -126,7 +123,7 @@ overhead.
:numref:`vbsk-virtio-echo-path` details the path of kick and notify
operation shown in :numref:`vbsk-virtio-echo-e2e`. The VBS-K framework
overhead is caused by operations through these paths. As we can see, all
these operations are processed in kernel mode and avoids extra
these operations are processed in kernel mode, which avoids the extra
overhead of passing IOREQ to userspace processing.
.. figure:: images/vbsk-image3.png
@ -139,9 +136,9 @@ overhead of passing IOREQ to userspace processing.
Conclusion
**********
Unlike VBS-U processing in user mode, VBS-K moves things into the kernel
mode and can be used to accelerate processing. A virtual device
virtio-echo based on VBS-K framework is used to evaluate the VBS-K
framework overhead. In our test, the VBS-K framework overhead (one kick
operation and one notify operation) is on the microsecond level, which
can meet the needs of most applications.
Unlike VBS-U processing in user mode, VBS-K moves processing into the kernel
mode and can be used to accelerate processing. A virtual device virtio-echo
based on the VBS-K framework is used to evaluate the VBS-K framework overhead.
In our test, the VBS-K framework overhead (one kick operation and one
notify operation) is on the microsecond level, which can meet the needs of
most applications.

38
doc/developer-guides/asm_coding_guidelines.rst
View File

@ -139,10 +139,9 @@ Compliant example::
ASM-GN-06: .end directive statement shall be the last statement in an Assembly file
===================================================================================
This rule only applies to the Assembly file that uses ``.end``
directive. ``.end`` directive shall be the last statement in this case.
All the statements past ``.end`` directive will not be processed by the
assembler.
This rule applies only to the Assembly file that uses the ``.end`` directive.
The ``.end`` directive shall be the last statement in this case. All
statements past the ``.end`` directive will not be processed by the assembler.
Compliant example::
@ -226,8 +225,8 @@ Compliant example::
ASM-GN-09: Far jump shall be used with restrictions
===================================================
Jumping to an instruction located in a different segment shall only be used for
the following two cases:
Jumping to an instruction located in a different segment shall be used only
for the following two cases:
a) Code bit changes, such as change from 32-bit mode to 64-bit mode.
b) System resumes from S3. In this case, Global Descriptor Table (GDT) is set by
@ -268,8 +267,8 @@ Compliant example::
ASM-GN-10: Assembler directives shall be used with restrictions
===============================================================
Usage of the assembler directive refers to GNU assembler 'as' user manual. Only
the following assembler directives may be used:
Usage of the assembler directive refers to the GNU assembler ``as`` user
manual. Only the following assembler directives may be used:
1) ``.align``
2) ``.end``
@ -315,12 +314,12 @@ Compliant example::
call asm_func_showcase
ASM-FN-02: A function shall only have one entry point
ASM-FN-02: A function shall have only one entry point
=====================================================
The label in a function shall only be used inside. Jumping into the function
The label in a function shall be used only inside. Jumping into the function
from outside via this label shall not be allowed. This rule applies to both
conditional jump and unconditional jump.
conditional jumps and unconditional jumps.
Compliant example::
@ -352,7 +351,7 @@ Compliant example::
jmp tmp
ASM-FN-03: A function shall only have one return statement
ASM-FN-03: A function shall have only one return statement
==========================================================
Compliant example::
@ -381,10 +380,10 @@ Compliant example::
ret
ASM-FN-04: Function shall only be entered by explicit call
ASM-FN-04: Function shall be entered only by explicit call
==========================================================
Falling through from prior instruction shall not be allowed.
Falling through from a prior instruction shall not be allowed.
Compliant example::
@ -411,7 +410,7 @@ Compliant example::
ASM-FN-05: A jump instruction shall not be used to jump out of a function
=========================================================================
This rule applies to both conditional jump and unconditional jump.
This rule applies to both conditional jumps and unconditional jumps.
Compliant example::
@ -786,10 +785,11 @@ Compliant example::
ASM-NC-03: Label name shall be unique
=====================================
Label name shall be unique with the following exception. Usage of local labels
is allowed. Local label is defined with the format ``N:``, where N represents any
non-negative integer. Using ``Nb`` to refer to the most recent previous definition
of that label. Using ``Nf`` to refer to the next definition of a local label.
Label name shall be unique with the following exception: Use of local labels
is allowed. A local label is defined with the format ``N:``, where N
represents any non-negative integer. Use ``Nb`` to refer to the most recent
previous definition of that label. Use ``Nf`` to refer to the next definition
of a local label.
Compliant example::

398
doc/developer-guides/c_coding_guidelines.rst
View File

@ -13,12 +13,12 @@ Preprocessor
C-PP-01: ## or # operators shall be used with restrictions
==========================================================
``##`` or ``#`` operators shall only be used alone. The following cases shall not be
allowed:
``##`` or ``#`` operators shall only be used alone. The following cases shall
not be allowed:
a) The result getting from ``##`` or ``#`` operation shall not be used as the operands
of another ``##`` or ``#`` operation;
b) Mixed-use of ``##`` or ``#`` operators shall not be allowed.
a) The result from the ``##`` or ``#`` operation shall not be used as the
operands of another ``##`` or ``#`` operation.
b) Mixed use of ``##`` or ``#`` operators shall not be allowed.
Compliant example::
@ -322,8 +322,8 @@ Compliant example::
showcase += 10U;
C-DI-04: The initialization of struct shall be enclosed with brackets
=====================================================================
C-DI-04: The initialization of a struct shall be enclosed with brackets
=======================================================================
Compliant example::
@ -374,13 +374,13 @@ Compliant example::
uint32_t showcase[] = {0U, 1U};
C-DI-06: Global variables shall only be declared once
C-DI-06: Global variables shall be declared only once
=====================================================
Global variables shall only be declared once with the following exception.
A global variable may be declared twice, if one declaration is in a header file
with extern specifier, and the other one is in a source file without extern
specifier.
Global variables shall be declared only once with the following exception:
A global variable may be declared twice if one declaration is in a header file
with the ``extern`` specifier and the other one is in a source file *without*
the ``extern`` specifier.
Compliant example::
@ -444,8 +444,8 @@ Compliant example::
Functions
*********
C-FN-01: A non-void function shall have return statement
========================================================
C-FN-01: A non-void function shall have a return statement
==========================================================
Compliant example::
@ -465,8 +465,8 @@ Compliant example::
}
C-FN-02: A non-void function shall have return value rather than empty return
=============================================================================
C-FN-02: A non-void function shall have a return value rather than empty return
===============================================================================
Compliant example::
@ -487,8 +487,8 @@ Compliant example::
}
C-FN-03: A non-void function shall return value on all paths
============================================================
C-FN-03: A non-void function shall return a value on all paths
==============================================================
Compliant example::
@ -550,8 +550,8 @@ Compliant example::
}
C-FN-05: Parameter passed by pointer to a function shall not be reassigned
==========================================================================
C-FN-05: A parameter passed by pointer to a function shall not be reassigned
============================================================================
Compliant example::
@ -574,8 +574,8 @@ Compliant example::
}
C-FN-06: Parameter passed by value to a function shall not be modified directly
===============================================================================
C-FN-06: A parameter passed by value to a function shall not be modified directly
=================================================================================
Compliant example::
@ -598,8 +598,8 @@ Compliant example::
}
C-FN-07: Non-static function shall be declared in header file
=============================================================
C-FN-07: A non-static function shall be declared in a header file
=================================================================
Compliant example::
@ -627,8 +627,8 @@ Compliant example::
}
C-FN-08: All static functions shall be used within the file they are declared
=============================================================================
C-FN-08: All static functions shall be used within the file in which they are declared
======================================================================================
Unlike global functions in C, access to a static function is restricted to the
file where it is declared. Therefore, a static function shall be used in the
@ -662,7 +662,7 @@ C-FN-09: The formal parameter name of a function shall be consistent
====================================================================
The formal parameter name of a function shall be the same between its
declaration and definition.
declaration and its definition.
Compliant example::
@ -697,7 +697,7 @@ C-FN-10: The formal parameter type of a function shall be consistent
====================================================================
The formal parameter type of a function shall be the same between its
declaration and definition.
declaration and its definition.
Compliant example::
@ -731,7 +731,7 @@ Compliant example::
C-FN-11: The return type of a function shall be consistent
==========================================================
The return type of a function shall be the same between its declaration and
The return type of a function shall be the same between its declaration and its
definition.
Compliant example::
@ -771,9 +771,9 @@ The following cases shall be covered:
a) These dynamic memory allocation functions shall not be used: ``calloc``,
``malloc``, ``realloc``, and ``free``. Dynamic memory allocation shall be
replaced with static memory allocation.
b) The functions ``va_arg``, ``va_start``, and ``va_end`` shall only be used
within variadic functions (functions taking a variable number of parameters)
such as ``printf``.
b) The functions ``va_arg``, ``va_start``, and ``va_end`` shall be used only
within variadic functions (functions taking a variable number of
parameters) such as ``printf``.
Compliant example::
@ -812,18 +812,18 @@ Compliant example::
/* declaration */
uint32_t func_showcase(uint32_t param);
/* There is no definition of `func_showcase` anywhere in all source files */
/* There is no definition of `func_showcase` anywhere in the source files */
C-FN-14: All defined functions shall be used
============================================
All defined functions shall be used, either called explicitly or indirectly via
its address. Otherwise, the function shall be removed. The following case is an
exception. Some extra functions may be kept in order to provide a more complete
library of APIs. These functions may have been implemented but not used
currently. These functions will come in handy in the future. In this case, these
functions may remain.
All defined functions shall be used, either called explicitly or indirectly
via the address. Otherwise, the function shall be removed. The following case
is an exception: Some extra functions may be kept in order to provide a more
complete library of APIs. These functions may be implemented but not used
currently. These functions will come in handy in the future. In this case,
these functions may remain.
Compliant example::
@ -951,12 +951,12 @@ Compliant example::
}
C-FN-17: The return value of a non-void function shall either be used or discarded
C-FN-17: The return value of a non-void function shall be either used or discarded
==================================================================================
The return value of a non-void function shall either be used or discarded
explicitly via (void). If the return value contains the error code, this return
value shall be checked in all possible paths.
The return value of a non-void function shall be either used or discarded
explicitly via ``(void)``. If the return value contains the error code, this
return value shall be checked in all possible paths.
Compliant example::
@ -1021,11 +1021,11 @@ Compliant example::
}
C-FN-18: The array size shall be valid if the array is function input parameter
===============================================================================
C-FN-18: The array size shall be valid if the array is a function input parameter
=================================================================================
This is to guarantee that the destination array has sufficient space for the
operation, such as copy, move, compare and concatenate.
operation, such as copy, move, compare, and concatenate.
Compliant example::
@ -1107,8 +1107,8 @@ C-ST-01: The condition of a selection or iteration statement shall not be consta
==================================================================================
The condition of a selection or iteration statement shall not be constant with
the following exception, `do { ... } while (0)` shall be allowed if it is used
in a MACRO.
the following exception: ``do { ... } while (0)`` shall be allowed if it is
used in a MACRO.
Compliant example::
@ -1189,7 +1189,7 @@ Compliant example::
C-ST-04: The else statement shall not be empty if it is following an else if
============================================================================
Either a non-null statement or a comment shall be included in the else
Either a non-null statement or a comment shall be included in the ``else``
statement. This is to guarantee that the developers have considered all of the
possible cases.
@ -1366,8 +1366,8 @@ Expressions
C-EP-01: The initialization expression of a for loop shall be simple
====================================================================
The initialization expression of a for loop shall only be used to initialize the
loop counter. All other operations shall not be allowed.
The initialization expression of a for loop shall be used only to initialize
the loop counter. All other operations shall not be allowed.
Compliant example::
@ -1417,8 +1417,8 @@ Compliant example::
C-EP-03: The third expression of a for loop shall be simple
===========================================================
The third expression of a for loop shall only be used to increase or decrease
the loop counter with the following operators, ++, --, +=, or -=. All other
The third expression of a for loop shall be used only to increase or decrease
the loop counter with the following operators: ++, --, +=, or -=. All other
operations shall not be allowed.
Compliant example::
@ -1498,8 +1498,8 @@ Compliant example::
uint8_t showcase = 255U + 1U;
C-EP-07: Negation shall not be performed on unsigned expression
===============================================================
C-EP-07: Negation shall not be performed on an unsigned expression
==================================================================
Compliant example::
@ -1512,8 +1512,8 @@ Compliant example::
int32_t showcase = -10U;
C-EP-08: The address of an object shall not be assigned to another object whose lifetime is longer
==================================================================================================
C-EP-08: The address of an object shall not be assigned to a different object with a longer lifetime
====================================================================================================
Compliant example::
@ -1548,10 +1548,10 @@ Compliant example::
}
C-EP-09: sizeof operator shall not be performed on an array function parameter
==============================================================================
C-EP-09: The sizeof operator shall not be used on an array function parameter
=============================================================================
When an array is used as the function parameter, the array address is passed.
When an array is used as a function parameter, the array address is passed.
Thus, the return value of the sizeof operation is the pointer size rather than
the array size.
@ -1675,8 +1675,8 @@ Compliant example::
C-EP-14: The destination object shall have sufficient space for operation
=========================================================================
The destination object shall have sufficient space for operation, such as copy,
move, compare and concatenate. Otherwise, data corruption may occur.
The destination object shall have sufficient space for operation, such as
copy, move, compare, and concatenate. Otherwise, data corruption may occur.
Compliant example::
@ -1790,9 +1790,9 @@ C-EP-19: ++ or -- operation shall be used with restrictions
Only the following cases shall be allowed:
a) ++ or -- operation shall be allowed if it is used alone in the expression;
b) ++ or -- operation shall be allowed if it is used as the third expression of
a for loop.
a) ++ or -- operation shall be allowed if it is used alone in the expression.
b) ++ or -- operation shall be allowed if it is used as the third expression
of a for loop.
Compliant example::
@ -1813,9 +1813,9 @@ Compliant example::
C-EP-20: Array indexing shall be in-bounds
==========================================
An array index value shall be between zero (for the first element) and the array
size minus one (for the last element). Out-of-bound array references are an
undefined behavior and shall be avoided.
An array index value shall be between zero (for the first element) and the
array size minus one (for the last element). Out-of-bounds array references
are an undefined behavior and shall be avoided.
Compliant example::
@ -1860,8 +1860,8 @@ Only the following cases shall be allowed:
a) The magic number is defined as a MACRO with a name clearly indicating its
meaning.
b) The meaning of the magic number is clearly documented in the comments before
its usage.
b) The meaning of the magic number is clearly documented in the comments
before its usage.
c) The meaning of the magic number is straightforward in the specific context.
Compliant example::
@ -1880,9 +1880,10 @@ Compliant example::
C-EP-23: Pointer arithmetic shall be used with restrictions
===========================================================
Pointer arithmetic shall be performed on an array if it is possible. If not, the
data type and the value range of this pointer shall be checked before access to
ensure that the pointer reference is within the correct address space.
Pointer arithmetic shall be performed on an array if it is possible. If not,
the data type and the value range of this pointer shall be checked before
access to ensure that the pointer reference is within the correct
address space.
Compliant example::
@ -1962,15 +1963,15 @@ Compliant example::
showcase = showcase & mask;
C-TY-03: Mixed-use between Boolean values and integers shall not be allowed
===========================================================================
C-TY-03: Mixed-use of Boolean values and integers shall not be allowed
======================================================================
Some detailed rules are listed below:
a) The operands of the arithmetic operation shall be integers;
b) The operands of the logical operation shall be Boolean values;
a) The operands of the arithmetic operation shall be integers.
b) The operands of the logical operation shall be Boolean values.
c) The controlling expression of a selection or iteration statement shall be
Boolean;
Boolean.
d) A Boolean type expression shall be used where Boolean is expected.
Compliant example::
@ -1997,8 +1998,8 @@ C-TY-04: The enum shall not be used for arithmetic operations
Only the following operations on enum shall be allowed:
a) enum assignment shall be allowed if the operands of = operation have the same
enum type;
a) enum assignment shall be allowed if the operands of = operation have the
same enum type.
b) enum comparison shall be allowed, including the operators ==, !=, >, <, >=,
and <=.
@ -2045,8 +2046,8 @@ Compliant example::
chr = showcase[static 1];
C-TY-06: A pointer shall point to const object if the object is not modified
============================================================================
C-TY-06: A pointer shall point to a const object if the object is not modified
==============================================================================
Compliant example::
@ -2065,8 +2066,8 @@ Compliant example::
}
C-TY-07: The expressions type of ternary operation shall be consistent
======================================================================
C-TY-07: The expressions type in a ternary operation shall be consistent
========================================================================
Compliant example::
@ -2116,8 +2117,8 @@ Compliant example::
struct struct_showcase showcase = {32U, -1};
C-TY-09: The type used in switch statement shall be consistent
==============================================================
C-TY-09: The type used in a switch statement shall be consistent
================================================================
The type shall be consistent between the case expression and the controlling
expression of switch statement.
@ -2169,8 +2170,8 @@ Compliant example::
}
C-TY-10: const qualifier shall not be discarded in cast operation
=================================================================
C-TY-10: const qualifier shall not be discarded in a cast operation
===================================================================
Compliant example::
@ -2185,7 +2186,7 @@ Compliant example::
uint32_t *showcase = (uint32_t *)showcase_const;
C-TY-11: A variable shall be declared as static if it is only used in the file where it is declared
C-TY-11: A variable shall be declared as static if it is used only in the file where it is declared
===================================================================================================
Compliant example::
@ -2331,9 +2332,9 @@ C-TY-17: A pointer shall not be cast from any other types
Only the following pointer assignment shall be allowed:
a) Assignment shall be allowed via the address operator &;
b) Assignment shall be allowed if the objects pointed to by the two pointers are
of the same type.
a) Assignment shall be allowed via the address operator ``&``.
b) Assignment shall be allowed if the objects pointed to by the two pointers
are of the same type.
Compliant example::
@ -2372,7 +2373,7 @@ Compliant example::
uint32_t showcase;
C-TY-19: Array indexing shall only be performed on array type
C-TY-19: Array indexing shall be performed only on array type
=============================================================
Compliant example::
@ -2450,8 +2451,8 @@ Compliant example::
};
C-TY-22: Cast shall not be performed on pointers with different object type
===========================================================================
C-TY-22: Cast shall not be performed on pointers with different object types
============================================================================
Compliant example::
@ -2482,8 +2483,8 @@ Compliant example::
showcase_ptr_u32 = (uint32_t *)showcase_ptr_struct;
C-TY-23: Assignment on function pointers shall be performed with same type
==========================================================================
C-TY-23: Assignment on function pointers shall be performed with the same type
==============================================================================
Compliant example::
@ -2507,8 +2508,8 @@ Compliant example::
func_ptr_a = func_ptr_b;
C-TY-24: Cast shall not be performed on function pointer
========================================================
C-TY-24: Cast shall not be performed on a function pointer
==========================================================
Compliant example::
@ -2537,17 +2538,17 @@ Compliant example::
func_ptr_showcase = (func_ptr_t)func_showcase;
C-TY-25: A string literal shall only be used as const object
============================================================
C-TY-25: A string literal shall be used only as a const object
==============================================================
The following operations shall be covered:
a) If a string literal is assigned to a variable, this variable shall be
declared with const qualifier;
declared with const qualifier.
b) If a string literal is passed as a function parameter, this function
parameter shall be declared with const qualifier;
c) If a string literal is used as the return value of a function, this function
return type shall be declared with const qualifier.
parameter shall be declared with the ``const`` qualifier.
c) If a string literal is used as the return value of a function, this
function return type shall be declared with the ``const`` qualifier.
Compliant example::
@ -2563,8 +2564,9 @@ Compliant example::
C-TY-26: The basic numerical types shall not be used other than in typedefs
===========================================================================
Typedef-name shall be used to replace the usage of basic numerical types. This
is to guarantee the code portability between different compilers and platforms.
The typedef name shall be used to replace the usage of basic numerical types.
This is to guarantee the code portability between different compilers and
platforms.
Compliant example::
@ -2615,11 +2617,11 @@ Compliant example::
uint32_t test = showcase_u16 + showcase_u32 + showcase_u64;
C-TY-29: "U" suffix shall be used for unsigned integer constants
================================================================
C-TY-29: The "U" suffix shall be used for unsigned integer constants
====================================================================
For 8-bit, 16-bit, and 32-bit unsigned integer constants, "U" suffix shall be
used. For 64-bit unsigned integer constants, "UL" suffix shall be used.
For 8-bit, 16-bit, and 32-bit unsigned integer constants, the "U" suffix shall
be used. For 64-bit unsigned integer constants, the "UL" suffix shall be used.
Compliant example::
@ -2713,9 +2715,9 @@ Compliant example::
C-ID-03: A global variable name shall be unique
===============================================
A global variable name shall not be the same as the name of struct, union, enum,
typedef, function, function parameter, macro, member, enum constant, local
variable, or other global variables.
A global variable name shall not be the same as the name of struct, union,
enum, typedef, function, function parameter, macro, member, enum constant,
local variable, or other global variables.
Compliant example::
@ -2832,8 +2834,8 @@ Compliant example::
uint32_t uint32_t;
C-ID-07: Name defined by developers shall not start with underscore
===================================================================
C-ID-07: Names defined by developers shall not start with underscore
====================================================================
All names starting with one or two underscores are reserved for use by the
compiler and standard libraries to eliminate potential conflicts with
@ -2850,8 +2852,8 @@ Compliant example::
uint32_t __showcase;
C-ID-08: A variable name shall not be the same as struct, union or enum
=======================================================================
C-ID-08: A variable name shall not be the same as a struct, union, or enum
==========================================================================
Compliant example::
@ -2929,7 +2931,7 @@ Compliant example::
cpuid(CPUID_EXTEND_FEATURE, &unused, &boot_cpu_data.cpuid_leaves[FEAT_7_0_EBX], &boot_cpu_data.cpuid_leaves[FEAT_7_0_ECX], &boot_cpu_data.cpuid_leaves[FEAT_7_0_EDX]);
C-CS-02: Each line shall only contain one statement
C-CS-02: Each line shall contain only one statement
===================================================
Compliant example::
@ -2950,8 +2952,8 @@ Compliant example::
C-CS-03: Tabs shall be used for code indentation
================================================
Spaces are allowed only for indenting comments or aligning statements that span
multiple lines.
Spaces are allowed only for indenting comments or aligning statements that
span multiple lines.
Compliant example::
@ -3007,8 +3009,9 @@ C-CS-06: A single space shall exist between non-function-like keywords and openi
===========================================================================================
A single space shall exist between a non-function-like keyword and the opening
bracket (either a brace or a parenthesis) that follows. This rule applies to the
keywords ``if``, ``else``, ``for``, ``do``, ``while``, ``switch`` and ``return``.
bracket (either a brace or a parenthesis) that follows. This rule applies to
the keywords ``if``, ``else``, ``for``, ``do``, ``while``, ``switch``, and
``return``.
Compliant example::
@ -3029,8 +3032,8 @@ Compliant example::
}
C-CS-07: Space shall not exist between the function identifier and the following open-parenthesis
=================================================================================================
C-CS-07: A space shall not exist between the function identifier and the following open-parenthesis
===================================================================================================
Compliant example::
@ -3043,10 +3046,10 @@ Compliant example::
size_t entry_size = sizeof (struct vcpuid_entry);
C-CS-08: Space shall not exist right after opening brackets and right before closing ones
=========================================================================================
C-CS-08: A space shall not exist right after opening brackets and right before closing ones
===========================================================================================
Brackets in this rule refer to parenthesis, braces and squared brackets.
Brackets in this rule refer to parenthesis, braces, and square brackets.
Compliant example::
@ -3064,11 +3067,11 @@ C-CS-09: The ``*`` characters used for pointers shall be right before the functi
The following cases shall be covered:
a) For declaration of variables of a pointer type, the ``*`` character shall be
right before the variable identifier with no space in between.
a) For declaration of variables of a pointer type, the ``*`` character shall
be right before the variable identifier with no space in between.
b) For functions whose return value is of a pointer type, the ``*`` character
shall be right before the function identifier with no spaces in between in the
function prototype.
shall be right before the function identifier with no spaces in between in
the function prototype.
Compliant example::
@ -3087,7 +3090,8 @@ C-CS-10: A single space shall exist around binary and ternary operators
=======================================================================
This rule applies to all binary arithmetic, bit-wise, logical, relational,
equality and assignment operators, as well as the ternary conditional operator.
equality, and assignment operators, as well as the ternary conditional
operator.
Compliant example::
@ -3108,8 +3112,8 @@ C-CS-11: Space shall not exist after unary operator
===================================================
There shall be no space between a unary operator and its operand. This rule
applies to member accesses, prefix or postfix increments and decrements, address
and indirection operators.
applies to member accesses, prefix or postfix increments and decrements,
address and indirection operators.
Compliant example::
@ -3151,11 +3155,11 @@ Compliant example::
}
C-CS-13: Braces after if/switch/for/do/while shall be in the same line
C-CS-13: Braces after if/switch/for/do/while shall be on the same line
======================================================================
The statement after if/switch/for/do/while shall always be a compound statement
with its opening brace in the same line as the keyword.
The statement after if/switch/for/do/while shall always be a compound
statement with its opening brace on the same line as the keyword.
Compliant example::
@ -3274,46 +3278,47 @@ Compliant example::
C-CS-18: Function information shall be documented with doxygen-style comments
=============================================================================
Some detailed rules are listed below to illustrate the comments format for each
function:
Some detailed rules are listed below to illustrate the comments format for
each function:
1) The comments block shall start with ``/**`` (slash-asterisk-asterisk) in a
single line.
2) The comments block shall end with :literal:`\ */` (space-asterisk-slash) in a single
line.
2) The comments block shall end with :literal:`\ */` (space-asterisk-slash) in
a single line.
3) Other than the first line and the last line, every line inside the comments
block shall start with :literal:`\ *` (space-asterisk). It also applies to the line which
is used to separate different paragraphs. We'll call it a blank line for
simplicity.
block shall start with :literal:`\ *` (space-asterisk). It also applies to
the line which is used to separate different paragraphs. We'll call it a
blank line for simplicity.
4) For each function, following information shall be documented:
brief description, detailed description, parameters description,
pre-conditions, post-conditions, return value description, and comments
explaining the actual return values. We'll call each block of information a
paragraph for simplicity. A paragraph may be removed from the list if it is not
applicable for that function.
explaining the actual return values. We'll call each block of information
a paragraph for simplicity. A paragraph may be removed from the list if it
is not applicable for that function.
5) Each line shall only contain the description for one parameter, or one
pre-condition, or one post-condition, or one actual return value. We'll call
each of these an element for simplicity.
pre-condition, or one post-condition, or one actual return value. We'll
call each of these an element for simplicity.
6) A blank line shall separate different paragraphs. Inside each paragraph, a
blank line is not required to separate each element.
7) The brief description of the function shall be documented with the format
``@brief <brief description>``.
8) No specific format is required for the detailed description of the function.
9) The description of the function parameter shall be documented with the format
``@param <parameter name> <parameter description>``.
8) No specific format is required for the detailed description of the
function.
9) The description of the function parameter shall be documented with the
format ``@param <parameter name> <parameter description>``.
10) The pre-condition of the function shall be documented with the format
``@pre <pre-condition description>``.
11) The post-condition of the function shall be documented with the format
``@post <post-condition description>``.
12) The brief description of the function return value shall be documented with
the format ``@return <brief description of return value>``.
12) The brief description of the function return value shall be documented
with the format ``@return <brief description of return value>``.
13) A void-returning function shall be documented with the format
``@return None``.
14) The comments explaining the actual return values shall be documented with
the format ``@retval <return value> <return value explanation>``.
15) If the description of one element needs to span multiple lines, each line
shall be aligned to the start of the description in the first line for that
element.
shall be aligned to the start of the description in the first line for
that element.
16) The comments block shall appear immediately before the function
definition/declaration in the C source file or header file.
@ -3370,8 +3375,7 @@ C-CS-19: Legal entity shall be documented in every file
=======================================================
Legal entity shall be documented in a separate comments block at the start of
every file.
The following information shall be included:
every file. The following information shall be included:
a) Copyright
b) License (using an `SPDX-License-Identifier <https://spdx.org/licenses/>`_)
@ -3439,12 +3443,12 @@ Compliant example::
C-NC-03: Data structures exposed to external components shall be named with prefix ``acrn_``
============================================================================================
The data structure types include struct, union, and enum.
This rule applies to the data structure with all the following properties:
The data structure types include struct, union, and enum. This rule applies to
the data structure with all the following properties:
a) The data structure is used by multiple modules;
a) The data structure is used by multiple modules.
b) The corresponding resource is exposed to external components, such as the
Service VM or a User VM;
Service VM or a User VM.
c) The name meaning is simplistic or common, such as vcpu or vm.
Compliant example::
@ -3465,11 +3469,11 @@ Compliant example::
C-NC-04: Data structures only used by hypervisor shall be named with prefix ``hv_``
===================================================================================
The data structure types include struct, union, and enum.
This rule applies to the data structure with all the following properties:
The data structure types include struct, union, and enum. This rule applies to
the data structure with all the following properties:
a) The data structure is used by multiple modules;
b) The corresponding resource is only used by hypervisor;
a) The data structure is used by multiple modules.
b) The corresponding resource is only used by hypervisor.
c) The name meaning is simplistic or common, such as timer.
Compliant example::
@ -3490,10 +3494,10 @@ Compliant example::
C-NC-05: Data structures only used by one module shall be named with the module name as prefix
==============================================================================================
The data structure types include struct, union, and enum.
This rule applies to the data structure with all the following properties:
The data structure types include struct, union, and enum. This rule applies to
the data structure with all the following properties:
a) The data structure is only used by one module;
a) The data structure is only used by one module.
b) The name meaning is simplistic or common, such as context.
Compliant example::
@ -3514,10 +3518,9 @@ Compliant example::
C-NC-06: Data structures related to hardware resource shall be named with the resource name as suffix
=====================================================================================================
The data structure types include struct, union, and enum.
For example:
The data structure types include struct, union, and enum. For example:
a) The data structure related to register shall be named with suffix ``reg``;
a) The data structure related to register shall be named with suffix ``reg``.
b) The data structure related to segment selector shall be named with suffix
``sel``.
@ -3562,13 +3565,13 @@ C-NC-08: Function name shall be descriptive
Function name shall be descriptive and clearly indicate the purpose of the
function. Some detailed rules are listed below:
1) If the function is doing actions, it shall be named with one of the following
formats:
1) If the function is performing actions, it shall be named with one of the
following formats:
a) ``<verb>_<nouns>``, such as ``init_vmcs``.
b) ``<verb>_<adjective>_<nouns>``, such as ``init_primary_pcpu``.
2) If the function is doing checks, it shall be named with one of the following
formats:
2) If the function is doing checks, it shall be named with one of the
following formats:
a) ``is_<nouns>``, such as ``is_space``.
b) ``is_<nouns>_<adjective>``, such as ``is_pcpu_active``.
@ -3578,18 +3581,18 @@ function. Some detailed rules are listed below:
a) ``<nouns>_to_<nouns>``, such as ``irq_to_vector``.
b) ``<nouns>2<nouns>``, such as ``gva2gpa``.
4) If the function is specific for one module and the name is not descriptive
enough with prior rules, it shall be named with the module name as prefix, such
as ``vie_read_mmio``.
5) If the function is a wrapper of inline Assembly codes, it shall be named with
one of the following formats:
enough with prior rules, it shall be named with the module name as prefix,
such as ``vie_read_mmio``.
5) If the function is a wrapper of inline Assembly codes, it shall be named
with one of the following formats:
a) ``asm_<Assembly instruction mnemonic>``, such as ``asm_pause``.
b) If the Assembly instruction mnemonic does not clearly indicate the
purpose of the function or the function includes multiple Assembly
instruction statements, the function shall be named with ``asm_`` as
prefix and apply the other non-assembly function naming rules.
6) ``<nouns>`` mentioned in prior rules may either be one noun or multiple nouns, as
long as it could clearly illustrate the object.
6) ``<nouns>`` mentioned in prior rules may either be one noun or multiple
nouns, as long as it could clearly illustrate the object.
Compliant example::
@ -3630,7 +3633,7 @@ Compliant example::
uint32_t pause(uint32_t param);
Implementation-specific Behaviors
Implementation-Specific Behaviors
*********************************
@ -3644,8 +3647,8 @@ all characters in an identifier are significant initial characters.
C-IB-02: The number of bits in a byte is 8
==========================================
The number of bits in a byte is implementation-defined, according to J.3.4 item
1 in C99. For ACRN hypervisor, the number of bits in a byte is 8.
The number of bits in a byte is implementation-defined, according to J.3.4
item 1 in C99. For ACRN hypervisor, the number of bits in a byte is 8.
C-IB-03: The values of the members of the execution character set depends on ASCII Table
========================================================================================
@ -3653,8 +3656,8 @@ C-IB-03: The values of the members of the execution character set depends on ASC
The values of the members of the execution character set is
implementation-defined, according to J.3.4 item 2 in C99. For ACRN hypervisor,
characters are encoded in ASCII. This rule applies to the source code that is
being compiled. Non-ASCII characters are allowed in comments, such as the author
name.
being compiled. Non-ASCII characters are allowed in comments, such as the
author name.
C-IB-04: ``plain char`` is equivalent to ``signed char``
========================================================
@ -3674,16 +3677,17 @@ complement.
C-IB-06: The integer type compatible with each enumerated type is case by case
==============================================================================
The integer type compatible with each enumerated type is implementation-defined,
according to J.3.9 item 6 in C99. For ACRN hypervisor, if the enum has no
negative underlying values, unsigned int is used; otherwise, int is used.
The integer type compatible with each enumerated type is
implementation-defined, according to J.3.9 item 6 in C99. For ACRN hypervisor,
if the enum has no negative underlying values, unsigned int is used;
otherwise, int is used.
C-IB-07: The number of bytes in an object is specified
======================================================
The number of bytes in an object is implementation-defined, according to J.3.13
item 2 in C99. For ACRN hypervisor, char is 1 byte, short is 2 bytes, int is 4
bytes, long is 8 bytes, and long long is not used.
The number of bytes in an object is implementation-defined, according to
J.3.13 item 2 in C99. For ACRN hypervisor, char is 1 byte, short is 2 bytes,
int is 4 bytes, long is 8 bytes, and long long is not used.
Language Extensions
*******************
@ -3691,7 +3695,7 @@ Language Extensions
Refer to the `GCC 8.3 Manual, Section 6 Extensions to the C Language Family <https://gcc.gnu.org/onlinedocs/gcc-8.3.0/gcc/C-Extensions.html#C-Extensions/>`_.
C-LE-01: Use of inline Assembly language in C Code is allowed
C-LE-01: Use of inline Assembly language in C code is allowed
=============================================================
This feature refers to section 6.45 in GCC 8.3 Manual.
@ -3701,8 +3705,8 @@ C-LE-02: Use of builtin-type ``__builtin_va_list`` is allowed
This feature refers to section 6.20 in GCC 8.3 Manual.
C-LE-03: Use of extended type attribute is allowed
==================================================
C-LE-03: Use of extended type attributes is allowed
===================================================
This rule applies to the following type attributes:

11
doc/developer-guides/coding_guidelines.rst
View File

@ -3,12 +3,11 @@
Coding Guidelines
#################
ACRN Project coding guidelines establish a common set of standards
and practices that improve readability and maintainability
of the code. These guidelines also help ensure the code is safe,
secure, and reliable by reducing undefined or unspecified
behavior by restricting use of problematic areas of the programming
language.
ACRN Project coding guidelines establish a common set of standards and
practices that improve the readability and maintainability of the code.
These guidelines also help ensure that the code is safe, secure, and reliable
by reducing undefined or unspecified behavior through restrictions on the use
of problematic areas of the programming language.
The following sections document the project's language-specific guidelines:

253
doc/developer-guides/contribute_guidelines.rst
View File

@ -3,25 +3,23 @@
Contribution Guidelines
#######################
As an open-source project, we welcome and encourage the community to
submit patches directly to project ACRN. In our collaborative open
source environment, standards and methods for submitting changes help
reduce the chaos that can result from an active development community.
As an open-source project, we welcome and encourage the community to submit
patches directly to project ACRN. In our collaborative open-source
environment, standards and methods for submitting changes help reduce the
chaos that can result from an active development community.
This document explains how to participate in project conversations, log
and track bugs and enhancement requests, and submit patches to the
project so your patch will be accepted quickly in the codebase.
project so that your patch will be accepted quickly into the codebase.
Licensing
*********
Licensing is very important to open source projects. It helps ensure the
software continues to be available under the terms that the author
desired.
Licensing is very important to open-source projects. It helps ensure that the
software continues to be available under the terms that the author desired.
Project ACRN uses a BSD-3-Clause license, as found in the
:acrn_file:`LICENSE <LICENSE>`
in the project's GitHub repo.
:acrn_file:`LICENSE <LICENSE>` in the project's GitHub repo.
A license tells you what rights you have as a developer, as provided by
the copyright holder. It is important that the contributor fully
@ -34,18 +32,18 @@ doing work on behalf of a company.
Developer Certification of Origin (DCO)
***************************************
To make a good faith effort to ensure licensing criteria are met,
To make a good faith effort to ensure that licensing criteria are met,
project ACRN requires the Developer Certificate of Origin (DCO) process
to be followed.
The DCO is an attestation attached to every contribution made by every
developer. In the commit message of the contribution, (described more
fully later in this document), the developer simply adds a
``Signed-off-by`` statement and thereby agrees to the DCO.
fully later in this document), the developer simply adds a ``Signed-off-by``
statement and thereby agrees to the DCO.
When a developer submits a patch, it is a commitment that the
contributor has the right to submit the patch per the license. The DCO
agreement is shown below and at http://developercertificate.org/.
When a developer submits a patch, it is a commitment that the contributor has
the right to submit the patch per the license. The DCO agreement is shown
below and at http://developercertificate.org/.
.. code-block:: none
@ -79,21 +77,22 @@ agreement is shown below and at http://developercertificate.org/.
DCO Sign-Off Methods
====================
The DCO requires that a sign-off message, in the following format,
appears on each commit in the pull request::
The DCO requires that a sign-off message, in the following format, appears on
each commit in the pull request::
Signed-off-by: Acrnus Jones <acrnusj@gmail.com>
The DCO text can either be manually added to your commit body, or you can add
either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget
to add the sign-off you can also amend a previous commit with the sign-off by
You can either manually add the DCO text to your commit body or you can add
``-s`` or ``--signoff`` to your usual Git commit commands. If you forget to
add the sign-off, you can also amend a previous commit with the sign-off by
running ``git commit --amend -s``. If you've pushed your changes to GitHub
already you'll need to force push your branch after this with ``git push -f``.
already, you'll need to force push your branch after this with
``git push -f``.
.. note::
The name and email address of the account you use to submit your PR must
match the name and email address on the ``Signed-off-by`` line in
your commit message.
match the name and email address on the ``Signed-off-by`` line in your
commit message.
Prerequisites
*************
@ -108,8 +107,8 @@ as introduced in the project ACRN `Getting Started Guide`_.
.. _Getting Started Guide:
https://projectacrn.github.io/latest/try.html
You should be familiar with common developer tools such as Git and
platforms such as GitHub.
You should be familiar with common developer tools and platforms such as Git
and GitHub.
If you haven't already done so, you'll need to create a (free) GitHub account
on https://github.com and have Git tools available on your development system.
@ -118,14 +117,14 @@ Repository Layout
*****************
To clone the ACRN hypervisor repository (including the ``hypervisor``,
``devicemodel``, and ``doc`` folders) use::
``devicemodel``, and ``doc`` folders), use::
$ git clone https://github.com/projectacrn/acrn-hypervisor
In addition to the ACRN hypervisor and device model itself,
you'll also find the sources for technical documentation available from
the `ACRN documentation site`_. All of these are available for
developers to contribute to and enhance.
In addition to the ACRN hypervisor and device model itself, you'll also find
the sources for technical documentation available from the
`ACRN documentation site`_. All of these are available for developers to
contribute to and enhance.
.. _ACRN documentation site:
https://projectacrn.github.io/
@ -150,13 +149,13 @@ have encountered the issue you're finding, or that have similar ideas
for changes or additions.
If you don't find an existing issue listed in the `ACRN hypervisor issues`_
list, then click on the "New Issue" button and provide a summary title
and more detailed description of your bug or enhancement request.
list, then click the "New Issue" button and provide a summary title and a
more-detailed description of your bug or enhancement request.
When you submit an issue (bug or feature request), the triage team will
review and comment on the submission, typically within a few business
days. Use the `ACRN hypervisor issues`_ list to track the status of
your submitted issues as well, or to add additional comments.
days. Use the `ACRN hypervisor issues`_ list to track the status of your
submitted issues as well, or to add additional comments.
.. _Contribution Tools:
@ -169,21 +168,20 @@ Contribution Tools and Git Setup
Git-Send-Email
==============
If you'll be submitting code patches, you may need to install
the git-email package for easier patch submission. On Ubuntu,
for example use::
If you'll be submitting code patches, you may need to install the git-email
package for easier patch submission. On Ubuntu, for example, use::
$ sudo apt install git-email
and then configure Git` with your SMTP server information as
described in the `Git send-email documentation`_.
and then configure Git with your SMTP server information as described in the
`Git send-email documentation`_.
Signed-Off-By
=============
The name in the commit message ``Signed-off-by:`` line and your email must
match the change authorship information. Make sure your :file:`.gitconfig`
is set up correctly by using:
The name in the commit message ``Signed-off-by:`` line and your email address
must match the change authorship information. Make sure that your
:file:`.gitconfig` is set up correctly by using:
.. code-block:: none
@ -195,7 +193,7 @@ Tracked-On
All commits must be mapped to a GitHub issue for a feature or bug. Add a
Tracked-On: #issue-number line to your commit message together with the
issue number, for example::
issue number. For example::
Tracked-On: #1420
@ -203,7 +201,7 @@ Coding Style
************
Use these coding guidelines to ensure that your development complies with the
project's style and naming conventions.
project's style and naming conventions:
.. _Linux kernel coding style:
https://kernel.org/doc/html/latest/process/coding-style.html
@ -214,42 +212,42 @@ following exceptions:
* Add braces to every ``if`` and ``else`` body, even for single-line code
blocks.
* Use spaces instead of tabs to align comments after declarations, as needed.
* Use C89-style single line comments, ``/* */``. The C99-style single line
* Use C89-style single-line comments, ``/* */``. The C99-style single-line
comment, ``//``, is not allowed.
* Use ``/** */`` for doxygen comments that need to appear in the documentation.
* Use ``/** */`` for doxygen comments that need to appear in the
documentation.
* The line limit is 120 columns instead of 80 columns. Note that tabs are
8-column wide.
You can use *checkpatch* from Linux kernel to check the compliance. ACRN
maintains a :acrn_file:`.checkpatch.conf <.checkpatch.conf>` file
that customizes the script to stop warnings on
the exceptions above. Invoke *checkpatch* with the root of ``acrn-hypervisor``
repository as the current working directory to make the configurations
effective.
You can use *checkpatch* from the Linux kernel to check the compliance. ACRN
maintains a :acrn_file:`.checkpatch.conf <.checkpatch.conf>` file that
customizes the script to stop warnings on the exceptions above. Invoke
*checkpatch* with the root of the ``acrn-hypervisor`` repository as the
current working directory to make the configurations effective.
.. _Contribution workflow:
Contribution Workflow
*********************
One general practice we encourage, is to make small,
controlled changes. This practice simplifies review, makes merging and
rebasing easier, and keeps the change history clear and clean.
One general practice we encourage, is to make small, controlled changes. This
practice simplifies review, makes merging and rebasing easier, and keeps the
change history clear and clean.
When contributing to project ACRN, it is also important you provide as much
information as you can about your change, update appropriate documentation,
and test your changes thoroughly before submitting.
When contributing to project ACRN, it is also important that you provide as
much information as you can about your change, update appropriate
documentation, and test your changes thoroughly before submitting.
Documentation changes should also be checked for technical accuracy,
spelling, grammar, and clarity and that the :ref:`doc_guidelines` are
being followed. It's also good practice to do a local documentation build to
verify the changes don't cause the build to fail. See :ref:`acrn_doc`
verify that the changes don't cause the build to fail. See :ref:`acrn_doc`
for details.
The general GitHub workflow used by project ACRN developers uses a combination of
command line Git commands and browser interaction with GitHub. As it is with
Git, there are multiple ways of getting a task done. We'll describe a typical
workflow here for the acrn-hypervisor repo, which includes the
The general GitHub workflow used by project ACRN developers uses a combination
of command-line Git commands and browser interaction with GitHub. As it is
with Git, there are multiple ways of getting a task done. We'll describe a
typical workflow here for the acrn-hypervisor repo, which includes the
source files for the hypervisor, devicemodel, and documentation.
.. important:: Both code and documentation changes follow the same steps
@ -283,8 +281,9 @@ source files for the hypervisor, devicemodel, and documentation.
$ git remote -v
#. Create a topic branch (off of the main branch) for your work (if you're addressing
an issue, we suggest including the issue number in the branch name)::
#. Create a topic branch (off of the main branch) for your work (if you're
addressing an issue, we suggest including the issue number in the
branch name)::
$ git checkout master
$ git checkout -b fix_comment_typo
@ -315,34 +314,34 @@ source files for the hypervisor, devicemodel, and documentation.
$ git commit -s
The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
message. Your commit will be rejected without this line that indicates your
agreement with the `DCO`_. See the `Commit Guidelines`_ section
message. Your commit will be rejected without this line that indicates
your agreement with the `DCO`_. See the `Commit Guidelines`_ section
below for specific guidelines for writing your commit messages.
All commits must be mapped to a GitHub issue for a feature or bug. Add a
``Tracked-On: #issue-number`` line to your commit message together
with the issue number, for example::
``Tracked-On: #issue-number`` line to your commit message together with the
issue number. For example::
Tracked-On: #1420
If only **documentation changes** are made, your PR can be submitted
without review on the ACRN developer mailing list, so you can skip
If only **documentation changes** are made, you can submit your PR
without a review on the ACRN developer mailing list, so you can skip
directly to step 9.
8. As mentioned earlier, all **code changes** must first be reviewed and
approved via the developer mailing list. This review process is
started by sending a patch file for each commit, as created by the ``git
format-patch`` command. For example if your change is contained in one
commit, create a patch file (in ``/tmp``, or some other location) with
approved via the developer mailing list. You start this review process by
sending a patch file for each commit, as created by the
``git format-patch`` command. For example, if your change is contained in
one commit, create a patch file (in ``/tmp``, or some other location) with
the command::
$ git format-patch -o /tmp/ -1
Then email the generated ``.patch`` file(s) to the ACRN developer
mailing list, acrn-dev@lists.projectacrn.org using the ``git
send-email`` command. (See the `Git send-email documentation`_
for details. For example::
mailing list, acrn-dev@lists.projectacrn.org using the ``git send-email``
command. (See the `Git send-email documentation`_ for details.
For example::
$ git send-email /tmp/000*.patch --to acrn-dev@lists.projectacrn.org
@ -350,9 +349,9 @@ source files for the hypervisor, devicemodel, and documentation.
`ACRN developer mailing list archive <https://lists.projectacrn.org/g/acrn-dev>`_.
After all review issues have been resolved, amend your commit with
necessary changes and also update the commit message with approvals
given in the mailing list discussion by adding
**Reviewed-by:** and **Acked-by:** tags.
necessary changes, and also update the commit message with approvals given
in the mailing list discussion by adding **Reviewed-by:** and **Acked-by:**
tags.
You can then proceed to the next step and submit a Git pull request
to the repo.
@ -362,48 +361,49 @@ source files for the hypervisor, devicemodel, and documentation.
$ git push origin fix_comment_typo
#. In your web browser, go to your personal forked repo and click on the Compare & pull
request button for the branch you just worked on and you want to
#. In your web browser, go to your personal forked repo and click the
Compare & pull request button for the branch you just worked on and want to
submit to the upstream ACRN repo.
#. Review the pull request changes, and verify that you are opening a pull request
for the appropriate branch. The title and message from your commit message should
appear as well.
#. Review the pull request changes, and verify that you are opening a pull
request for the appropriate branch. The title and message from your commit
message should appear as well.
#. GitHub will assign one or more suggested reviewers (based on the CODEOWNERS file
in the repo). If you are a project member, you can select additional reviewers
now too. If no reviewers are selected, the ACRN triage team will
#. GitHub will assign one or more suggested reviewers (based on the CODEOWNERS
file in the repo). If you are a project member, you can select additional
reviewers now too. If no reviewers are selected, the ACRN triage team will
assign reviewers as appropriate.
#. Click on the submit button and your pull request is sent and awaits review.
#. Click the submit button. Your pull request is sent and awaits review.
For code changes, this review should be cursory since any issues were
handled via the mailing list review.
Email will be sent as review comments are made, or you can check on your
pull request at https://github.com/projectacrn/acrn-hypervisor/pulls.
handled via the mailing list review. Email will be sent as review comments
are made, or you can check on your pull request at
https://github.com/projectacrn/acrn-hypervisor/pulls.
#. While you're waiting for your pull request to be accepted and merged, you can
create another branch to work on another issue. (Be sure to make your new branch
off of the main branch and not the previous branch.)::
#. While you're waiting for your pull request to be accepted and merged, you
can create another branch to work on another issue. (Be sure to make your
new branch off of the main branch and not the previous branch)::
$ git checkout master
$ git checkout -b fix_another_issue
and use the same process described above to work on this new topic branch.
Use the same process described above to work on this new topic branch.
#. If reviewers request changes to your patch, you can interactively rebase
commit(s) to fix review issues. In your development repo, make the
needed changes on the branch you made the initial submission::
one or more commits to fix review issues. In your development repo, make
the needed changes on the branch that you initially submitted::
$ git checkout fix-comment-typo
make the requested changes, and then::
Make the requested changes, and then::
$ git fetch --all
$ git rebase --ignore-whitespace upstream/master
This is an important step to make sure your changes are properly
merged with changes from other developers that may have happened while you
This is an important step to make sure that your changes are properly
merged with changes from other developers that may have occurred while you
were working on your changes.
The ``--ignore-whitespace`` option stops ``git apply`` (called by
rebase) from changing any whitespace characters (such as spaces, tabs, and
newlines). If any merging issues are detected you can address them
@ -411,9 +411,10 @@ source files for the hypervisor, devicemodel, and documentation.
$ git rebase -i <offending-commit-id>
In the interactive rebase editor, replace pick with edit to select a specific
commit (if there's more than one in your pull request), or remove the line to
delete a commit entirely. Then edit files to fix the issues in the review.
In the interactive rebase editor, replace pick with edit to select a
specific commit (if there's more than one in your pull request), or remove
the line to delete a commit entirely. Then edit files to fix the issues in
the review.
As before, inspect and test your changes. When ready, continue the
patch submission::
@ -421,14 +422,15 @@ source files for the hypervisor, devicemodel, and documentation.
$ git add [file(s)]
$ git rebase --continue
Update commit comment if needed, and continue::
Update commit comment if needed, and then continue::
$ git push --force origin fix_comment_typo
By force pushing your update, your original pull request will be updated with
your changes so you won't need to resubmit the pull request.
By force pushing your update, you ensure that your original pull request
will be updated with your changes, so you won't need to resubmit the
pull request.
You can follow the same workflow for contributing to acrn-devicemodel
You can follow the same workflow for contributing to the acrn-devicemodel
or acrn-documentation repos.
@ -437,10 +439,10 @@ Commit Guidelines
Changes are submitted as Git commits. Each commit message must contain:
* A short and descriptive subject line that is less than 72 characters,
* A short and descriptive subject line that is fewer than 72 characters,
followed by a blank line. The subject line must include a prefix that
identifies the subsystem being changed, followed by a colon, and a short
title, for example: ``doc: update commit guidelines instructions``.
title. For example: ``doc: update commit guidelines instructions``.
(If you're updating an existing file, you can use
``git log <filename>`` to see what developers used as the prefix for
previous patches of this file.)
@ -456,18 +458,18 @@ Changes are submitted as Git commits. Each commit message must contain:
Tracked-On: #issue-number
All changes and topics sent to GitHub must be well-formed, as described above.
Commit Message Body
===================
When editing the commit message, please briefly explain what your change
does and why it's needed. A change summary of ``"Fixes stuff"`` will be rejected.
does and why it's needed. A change summary of ``"Fixes stuff"`` will be
rejected.
.. warning::
An empty change summary body is not permitted. Even for trivial changes, please
include a summary body in the commit message.
An empty change summary body is not permitted. Even for trivial changes,
please include a summary body in the commit message.
The description body of the commit message must include:
@ -476,7 +478,8 @@ The description body of the commit message must include:
* **what** assumptions were made, and
* **how** you know it works -- for example, which tests you ran.
For examples of accepted commit messages, you can refer to the acrn-hypervisor GitHub
For examples of accepted commit messages, you can refer to the acrn-hypervisor
GitHub
`changelog <https://github.com/projectacrn/acrn-hypervisor/commits/master>`__.
Other Commit Expectations
@ -489,8 +492,8 @@ Other Commit Expectations
logically self-contained. Unrelated changes should be submitted as
separate commits.
* You may submit pull request RFCs (requests for comments) to send work
proposals, progress snapshots of your work, or to get early feedback on
* You may submit pull-request RFCs (requests for comments) to send work
proposals or progress snapshots of your work, or to get early feedback on
features or changes that will affect multiple areas in the code base.
Identifying Contribution Origin
@ -498,18 +501,18 @@ Identifying Contribution Origin
When adding a new file to the tree, it is important to detail the source of
origin on the file, provide attributions, and detail the intended usage. In
cases where the file is an original to acrn-hypervisor, the commit message should
include the following ("Original" is the assumption if no Origin tag is
cases where the file is an original to acrn-hypervisor, the commit message
should include the following ("Original" is the assumption if no Origin tag is
present)::
Origin: Original
In cases where the file is imported from an external project, the commit
message shall contain details regarding the original project, the location of
message must contain details regarding the original project, the location of
the project, the SHA-id of the origin commit for the file, the intended
purpose, and if the file will be maintained by the acrn-hypervisor project,
(whether or not project ACRN will contain a localized branch or if
it is a downstream copy).
purpose, and whether the file will be maintained by the acrn-hypervisor
project (whether project ACRN will contain a localized branch or whether it is
a downstream copy).
For example, a copy of a locally maintained import::

257
doc/developer-guides/doc_guidelines.rst
View File

@ -8,13 +8,12 @@ language (``.rst`` file extension) with Sphinx extensions, and processed
using Sphinx to create a formatted stand-alone website. Developers can
view this content either in its raw form as ``.rst`` markup files, or (with
Sphinx installed) they can build the documentation using the Makefile
(on Linux systems) to
generate the HTML content. The HTML content can then be viewed using a
web browser. This same ``.rst`` content is also fed into the
(on Linux systems) to generate the HTML content. The HTML content can then be
viewed using a web browser. This same ``.rst`` content is also fed into the
`Project ACRN documentation`_ website.
You can read details about `reStructuredText`_
and about `Sphinx extensions`_ from their respective websites.
You can read details about `reStructuredText`_ and about `Sphinx extensions`_
from their respective websites.
.. _Sphinx extensions: https://www.sphinx-doc.org/en/stable/contents.html
.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
@ -28,19 +27,19 @@ you're reading.
Headings
********
Document sections are identified through their heading titles,
indicated with an underline below the title text. (While reST allows
use of both and overline and matching underline to indicate a heading,
we only use an underline indicator for headings.) For consistency in
our documentation, we define the order of characters used to indicate
the nested table of contents levels:
Document sections are identified through their heading titles, indicated with
an underline below the title text. (While reST allows use of both and
overline and matching underline to indicate a heading, we use only an
underline indicator for headings.) For consistency in our documentation, we
define the order of characters used to indicate the nested levels in the
table of contents:
* Use ``#`` for the Document title underline character
* Use ``*`` for the First sub-section heading level
* Use ``=`` for the Second sub-section heading level
* Use ``-`` for the Third sub-section heading level
Additional heading level depth is discouraged.
Additional heading-level depth is discouraged.
The heading underline must be at least as long as the title it's under.
@ -89,20 +88,19 @@ the beginning and ending characters must not start or end with a space,
so ``*this is italics*`` ( *this is italics*) while ``* this isn't*``
(* this isn't*).
If asterisks or back quotes appear in running text and could be confused with
inline markup delimiters, you can eliminate the confusion by adding a
If an asterisk or back quote appears in running text and could be confused
with inline markup delimiters, you can eliminate the confusion by adding a
backslash (``\``) before it.
Lists
*****
For bullet lists, place an asterisk (``*``) or hyphen (``-``) at
the start of a paragraph and indent continuation lines with two
spaces.
For bullet lists, place an asterisk (``*``) or hyphen (``-``) at the start of
a paragraph and indent continuation lines with two spaces.
The first item in a list (or sublist) must have a blank line before it
and should be indented at the same level as the preceding paragraph
(and not indented itself).
The first item in a list (or sublist) must have a blank line before it and
should be indented at the same level as the preceding paragraph (and not
indented itself).
For numbered lists
start with a ``1.`` or ``a)`` for example, and continue with autonumbering by
@ -136,9 +134,9 @@ list item:
#. And a second item back in the containing list. No blank line
needed, but it wouldn't hurt for readability.
Definition lists (with a term and its definition) are a convenient way
to document a word or phrase with an explanation. For example, this reST
content:
Definition lists (with one or more terms and their definition) are a
convenient way to document a word or phrase with an explanation. For example,
this reST content:
.. code-block:: rest
@ -165,11 +163,11 @@ Would be rendered as:
Multi-Column Lists
******************
If you have a long bullet list of items, where each item is short, you
can indicate the list items should be rendered in multiple columns with
a special ``.. rst-class:: rst-columns`` directive. The directive will
apply to the next non-comment element (e.g., paragraph), or to content
indented under the directive. For example, this unordered list::
If you have a long bullet list of items, where each item is short, you can
indicate that the list items should be rendered in multiple columns with a
special ``.. rst-class:: rst-columns`` directive. The directive will apply to
the next non-comment element (e.g., paragraph) or to content indented under
the directive. For example, this unordered list::
.. rst-class:: rst-columns
@ -199,16 +197,17 @@ would be rendered as:
A maximum of three columns will be displayed if you use ``rst-columns``
(or ``rst-columns3``), and two columns for ``rst-columns2``. The number
of columns displayed can be reduced
based on the available width of the display window, reducing to one
column on narrow (phone) screens if necessary. We've deprecated use of
the ``hlist`` directive because it misbehaves on smaller screens.
of columns displayed can be reduced based on the available width of the
display window, reducing to one column on narrow (phone) screens if necessary.
.. note:: We've deprecated use of the ``hlist`` directive because it
misbehaves on smaller screens.
Tables
******
There are a few ways to create tables, each with their limitations or
quirks. `Grid tables
There are a few ways to create tables, each with their limitations or quirks.
`Grid tables
<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables>`_
offer the most capability for defining merged rows and columns, but are
hard to maintain::
@ -286,9 +285,9 @@ File Names and Commands
***********************
Sphinx extends reST by supporting additional inline markup elements (called
"roles") used to tag text with special
meanings and allow style output formatting. (You can refer to the `Sphinx Inline Markup`_
documentation for the full list).
"roles") used to tag text with special meanings and enable output formatting.
(You can refer to the `Sphinx Inline Markup`_ documentation for the full
list).
For example, there are roles for marking :file:`filenames`
(``:file:`name```) and command names such as :command:`make`
@ -297,23 +296,23 @@ markup (double backticks) to indicate a ``filename``.
Don't use items within a single backtick, for example ```word```.
For references to files that are in the ACRN Hypervisor GitHub tree, a special
role can be used that creates a hyperlink to that file. For example a
For references to files that are in the ACRN Hypervisor GitHub tree, you can
use a special role that creates a hyperlink to that file. For example, a
GitHub link to the reST file used to create this document can be generated
using ``:acrn_file:`doc/developer-guides/doc_guidelines.rst``` that will show
up as :acrn_file:`doc/developer-guides/doc_guidelines.rst`, a link to
using ``:acrn_file:`doc/developer-guides/doc_guidelines.rst```, which will
appear as :acrn_file:`doc/developer-guides/doc_guidelines.rst`, a link to
the “blob” file in the GitHub repo as displayed by GitHub. There’s also an
``:acrn_raw:`doc/developer-guides/doc_guidelines.rst``` role that will link
to the “raw” uninterpreted file,
:acrn_raw:`doc/developer-guides/doc_guidelines.rst` file. (Click
on these links to see the difference.)
:acrn_raw:`doc/developer-guides/doc_guidelines.rst` file. (Click these links
to see the difference.)
.. _internal-linking:
Internal Cross-Reference Linking
********************************
Traditional ReST links are only supported within the current file using the
Traditional ReST links are supported only within the current file using the
notation:
.. code-block:: rest
@ -324,13 +323,12 @@ which renders as,
refer to the `internal-linking`_ page
Note the use of a trailing
underscore to indicate an outbound link. In this example, the label was
added immediately before a heading, so the text that's displayed is the
heading text itself.
Note the use of a trailing underscore to indicate an outbound link. In this
example, the label was added immediately before a heading, so the text that's
displayed is the heading text itself.
With Sphinx however, we can create
link-references to any tagged text within the project documentation.
With Sphinx however, we can create link-references to any tagged text within
the project documentation.
Target locations within documents are defined with a label directive:
@ -338,28 +336,24 @@ Target locations within documents are defined with a label directive:
.. _my label name:
Note the leading underscore indicating an inbound link.
The content immediately following
this label is the target for a ``:ref:`my label name```
reference from anywhere within the documentation set.
The label **must** be added immediately before a heading so there's a
natural phrase to show when referencing this label (e.g., the heading
text).
Note the leading underscore indicating an inbound link. The content
immediately following this label is the target for a ``:ref:`my label name```
reference from anywhere within the documentation set. The label **must** be
added immediately before a heading so that there's a natural phrase to show
when referencing this label (e.g., the heading text).
This is the same directive used to
define a label that's a reference to a URL:
This is the same directive used to define a label that's a reference to a URL:
.. code-block:: rest
.. _Hypervisor Wikipedia Page:
https://en.wikipedia.org/wiki/Hypervisor
To enable easy cross-page linking within the site, each file should have
a reference label before its title so it can
be referenced from another file. These reference labels must be unique
across the whole site, so generic names such as "samples" should be
avoided. For example the top of this document's ``.rst`` file is:
To enable easy cross-page linking within the site, each file should have a
reference label before its title so that it can be referenced from another
file. These reference labels must be unique across the whole site, so generic
names such as "samples" should be avoided. For example, the top of this
document's ``.rst`` file is:
.. code-block:: rst
@ -368,33 +362,34 @@ avoided. For example the top of this document's ``.rst`` file is:
Documentation Guidelines
########################
Other ``.rst`` documents can link to this document using the ``:ref:`doc_guidelines``` tag and
it will show up as :ref:`doc_guidelines`. This type of internal cross reference works across
multiple files, and the link text is obtained from the document source so if the title changes,
the link text will update as well.
Other ``.rst`` documents can link to this document using the
``:ref:`doc_guidelines``` tag, and it will appear as :ref:`doc_guidelines`.
This type of internal cross-reference works across multiple files. The link
text is obtained from the document source, so if the title changes, the link
text will automatically update as well.
There may be times when you'd like to change the link text that's shown
in the generated document. In this case, you can specify alternate
text using ``:ref:`alternate text <doc_guidelines>``` (renders as
There may be times when you'd like to change the link text that's shown in the
generated document. In this case, you can specify alternate text using
``:ref:`alternate text <doc_guidelines>``` (renders as
:ref:`alternate text <doc_guidelines>`).
Non-ASCII Characters
********************
You can insert non-ASCII characters such as a Trademark symbol (|trade|),
by using the notation ``|trade|``. (It's also allowed to use the UTF-8
characters directly.)
Available replacement names are defined in an include file used during the Sphinx processing
of the reST files. The names of these replacement characters are the same as used in HTML
entities used to insert characters in HTML, e.g., \&trade; and are defined in the
file ``sphinx_build/substitutions.txt`` as listed here:
You can insert non-ASCII characters such as a Trademark symbol (|trade|) by
using the notation ``|trade|``. (It's also allowed to use the UTF-8
characters directly.) Available replacement names are defined in an include
file used during the Sphinx processing of the reST files. The names of these
replacement characters are the same as those used in HTML entities to insert
special characters such as \&trade; and are defined in the file
``sphinx_build/substitutions.txt`` as listed here:
.. literalinclude:: ../substitutions.txt
:language: rst
We've kept the substitutions list small but others can be added as
needed by submitting a change to the ``substitutions.txt`` file.
We've kept the substitutions list small but you can add others as needed by
submitting a change to the ``substitutions.txt`` file.
Code and Command Examples
*************************
@ -417,8 +412,8 @@ For example:
u32_t data;
} __packed;
Note the blank line between the ``code-block`` directive and the first
line of the code-block body, and the body content is indented three
Note that there is a blank line between the ``code-block`` directive and the
first line of the code-block body, and the body content is indented three
spaces (to the first non-blank space of the directive name).
This would be rendered as:
@ -434,10 +429,9 @@ This would be rendered as:
} __packed;
You can specify other languages for the ``code-block`` directive,
including ``c``, ``python``, and ``rst``, and also ``console``,
``bash``, or ``shell``. If you want no syntax highlighting, use the
language ``none``, for example:
You can specify other languages for the ``code-block`` directive, including
``c``, ``python``, and ``rst``, and also ``console``, ``bash``, or ``shell``.
If you want no syntax highlighting, specify ``none``. For example:
.. code-block:: rest
@ -453,12 +447,13 @@ Would display as:
This would be a block of text styled with a background
and box, but with no syntax highlighting.
There's a shorthand for writing code blocks too: end the introductory
There's a shorthand for writing code blocks, too: end the introductory
paragraph with a double colon (``::``) and indent the code block content
by three spaces. On output, only one colon will be shown. The
highlighting package makes a best guess at the type of content in the
block and highlighting purposes. This can lead to some odd
highlighting in the generated output.
by three spaces. On output, only one colon will appear.
.. note:: The highlighting package makes a best guess at the type of content
in the block for highlighting purposes. This can lead to some odd
highlighting in the generated output.
Images
******
@ -476,21 +471,20 @@ or if you'd like to add an image caption, use::
Caption for the figure
The file name specified is relative to the document source file,
and we recommend putting images into an ``images`` folder where the document
source is found. The usual image formats handled by a web browser are
supported: JPEG, PNG, GIF, and SVG. Keep the image size only as large
as needed, generally at least 500 px wide but no more than 1000 px, and
no more than 250 KB unless a particularly large image is needed for
clarity.
The file name specified is relative to the document source file, and we
recommend putting images into an ``images`` folder where the document source
is found. The usual image formats handled by a web browser are supported:
JPEG, PNG, GIF, and SVG. Keep the image size only as large as needed,
generally at least 500 px wide but no more than 1000 px, and no more than
250 KB unless a particularly large image is needed for clarity.
Tabs, Spaces, and Indenting
***************************
Indenting is significant in reST file content, and using spaces is
preferred. Extra indenting can (unintentionally) change the way content
is rendered too. For lists and directives, indent the content text to
the first non-blank space in the preceding line. For example:
Indenting is significant in reST file content, and using spaces is preferred.
Extra indenting can (unintentionally) change the way content is rendered, too.
For lists and directives, indent the content text to the first non-blank space
in the preceding line. For example:
.. code-block:: rest
@ -505,14 +499,14 @@ the first non-blank space in the preceding line. For example:
The text within a directive block should align with the
first character of the directive name.
Keep the line length for documentation less than 80 characters to make
it easier for reviewing in GitHub. Long lines because of URL references
are an allowed exception.
Keep the line length for documentation less than 80 characters to make it
easier for reviewing in GitHub. Long lines due to URL references are an
allowed exception.
Drawings
********
You can include a picture (.jpg, .png, .svg for example) by using the
You can include a picture (.jpg, .png, or .svg for example) by using the
``.. image`` directive::
.. image:: ../images/ACRNlogo.png
@ -524,10 +518,9 @@ This results in the image being placed in the document:
:align: center
Alternatively, use the ``.. figure`` directive to include a picture with
a caption and automatic figure numbering for
your image, (so you can say see :numref:`acrn-logo-figure`, by using the
notation ``:numref:`acrn-logo-figure``` and specifying the name of
figure)::
a caption and automatic figure numbering for your image, (so that you can say
see :numref:`acrn-logo-figure`, by using the notation
``:numref:`acrn-logo-figure``` and specifying the name of figure)::
.. figure:: ../images/ACRNlogo.png
:align: center
@ -542,17 +535,17 @@ figure)::
Caption for the figure
We've also included the ``graphviz`` Sphinx extension to let you use a text
description language to render drawings. See :ref:`graphviz-examples` for more
information.
We've also included the ``graphviz`` Sphinx extension to enable you to use a
text description language to render drawings. For more information, see
:ref:`graphviz-examples`.
Alternative Tabbed Content
**************************
Instead of creating multiple documents with common material except for
some specific sections, you can write one document and provide alternative
content to the reader via a tabbed interface. When the reader clicks on
a tab, the content for that tab is displayed, for example::
Instead of creating multiple documents with common material except for some
specific sections, you can write one document and provide alternative content
to the reader via a tabbed interface. When the reader clicks on a tab, the
content for that tab is displayed. For example::
.. tabs::
@ -584,7 +577,7 @@ will display as:
Oranges are orange.
Tabs can also be grouped, so that changing the current tab in one area
Tabs can also be grouped so that changing the current tab in one area
changes all tabs with the same name throughout the page. For example:
.. tabs::
@ -620,19 +613,19 @@ a ``.. tab::`` directive. Under the hood, we're using the `sphinx-tabs
<https://github.com/djungelorm/sphinx-tabs>`_ extension that's included
in the ACRN (requirements.txt) setup. Within a tab, you can have most
any content *other than a heading* (code-blocks, ordered and unordered
lists, pictures, paragraphs, and such). You can read more about
sphinx-tabs from the link above.
lists, pictures, paragraphs, and such). You can read more about sphinx-tabs
from the link above.
Instruction Steps
*****************
A numbered instruction steps style makes it
easy to create tutorial guides with clearly identified steps. Add
the ``.. rst-class:: numbered-step`` directive immediately before a
second-level heading (by project convention, a heading underlined with
asterisks ``******``, and it will be displayed as a numbered step,
sequentially numbered within the document. (Second-level headings
without this ``rst-class`` directive will not be numbered.) For example::
A numbered instruction steps style makes it easy to create tutorial guides
with clearly identified steps. Add the ``.. rst-class:: numbered-step``
directive immediately before a second-level heading (by project convention, a
heading underlined with asterisks ``******``, and it will be displayed as a
numbered step, sequentially numbered within the document. (Second-level
headings without this ``rst-class`` directive will not be numbered.)
For example::
.. rst-class:: numbered-step
@ -644,10 +637,10 @@ without this ``rst-class`` directive will not be numbered.) For example::
First Instruction Step
**********************
This is the first instruction step material. You can do the usual paragraphs and
pictures as you'd use in normal document writing. Write the heading to
be a summary of what the step is (the step numbering is automated so you
can move steps around easily if needed).
This is the first instruction step material. You can do the usual paragraph
and pictures as you'd use in normal document writing. Write the heading to be
a summary of what the step is (the step numbering is automated so you can move
steps around easily if needed).
.. rst-class:: numbered-step

33
doc/developer-guides/graphviz.rst
View File

@ -5,13 +5,13 @@ Drawings Using Graphviz
We support using the Sphinx `graphviz extension`_ for creating simple
graphs and line drawings using the dot language. The advantage of using
graphviz for drawings is that source for a drawing is a text file that
graphviz for drawings is that the source for a drawing is a text file that
can be edited and maintained in the repo along with the documentation.
.. _graphviz extension: http://graphviz.gitlab.io
These source ``.dot`` files are generally kept separate from the document itself,
and included by using a graphviz directive:
These source ``.dot`` files are generally kept separate from the document
itself, and included by using a graphviz directive:
.. code-block:: none
@ -20,7 +20,7 @@ and included by using a graphviz directive:
:align: center
:caption: ACRN Hypervisor Boot Flow
Where the boot-flow.dot file contains the drawing commands:
where the boot-flow.dot file contains the drawing commands:
.. literalinclude:: images/boot-flow.dot
@ -32,16 +32,15 @@ and the generated output would appear as this:
:caption: ACRN Hypervisor Boot Flow
Let's look at some more examples and then we'll get into more details
about the dot language and drawing options.
Let's look at some more examples and then we'll get into more details about
the dot language and drawing options.
Simple Directed Graph
*********************
For simple drawings with shapes and lines, you can put the graphviz
commands in the content block for the directive. For example, for a
simple directed graph (digraph) with two nodes connected by an arrow,
you can write:
For simple drawings with shapes and lines, you can put the graphviz commands
in the content block for the directive. For example, for a simple directed
graph (digraph) with two nodes connected by an arrow, you can write:
.. code-block:: none
@ -71,8 +70,8 @@ image placement on the page (centered):
.. graphviz:: images/circle-square.dot
:align: center
You can use the `standard HTML color names`_ or use RGB values for
colors, as shown.
You can use the `standard HTML color names`_ or use RGB values for colors,
as shown.
.. _standard HTML color names:
https://www.w3schools.com/colors/colors_hex.asp
@ -80,9 +79,9 @@ colors, as shown.
Adding Edge Labels
******************
Here's an example of a drawing with labels on the edges (arrows)
between nodes. We also show how to change the default attributes for all
nodes and edges within this graph:
Here's an example of a drawing with labels on the edges (arrows) between
nodes. We also show how to change the default attributes for all nodes and
edges within this graph:
.. literalinclude:: images/node-shape-edges.dot
@ -103,8 +102,8 @@ column) or a new column (if you're in a row). For example:
:align: center
Note that you can also specify the horizontal alignment of text using escape
sequences ``\n``, ``\l`` and ``\r`` that divide the label into lines, centered,
left-justified, and right-justified, respectively.
sequences ``\n``, ``\l``, and ``\r``, which divide the label into lines that
are centered, left-justified, and right-justified, respectively.
Finite-State Machine
********************

199
doc/developer-guides/l1tf.rst
View File

@ -70,51 +70,51 @@ There is no additional action in ACRN hypervisor.
Guest -> Hypervisor Attack
==========================
ACRN always enables EPT for all guests (Service VM and User VM), thus a malicious
guest can directly control guest PTEs to construct L1TF-based attack
to hypervisor. Alternatively if ACRN EPT is not sanitized with some
PTEs (with present bit cleared, or reserved bit set) pointing to valid
host PFNs, a malicious guest may use those EPT PTEs to construct an attack.
ACRN always enables EPT for all guests (Service VM and User VM); thus a
malicious guest can directly control guest PTEs to construct an L1TF-based
attack to the hypervisor. Alternatively, if ACRN EPT is not sanitized with
some PTEs (with present bit cleared, or reserved bit set) pointing to valid
host PFNs, a malicious guest can use those EPT PTEs to construct an attack.
A special aspect of L1TF in the context of virtualization is symmetric
multithreading (SMT), e.g. Intel |reg| Hyper-threading Technology.
Logical processors on the affected physical cores share the L1 Data Cache
(L1D). This fact could make more variants of L1TF-based attack, e.g.
a malicious guest running on one logical processor can attack the data which
is brought into L1D by the context which runs on the sibling thread of
the same physical core. This context can be any code in hypervisor.
(L1D). This fact could produce more variants of L1TF-based attack; e.g.,
a malicious guest running on one logical processor can attack the data
brought into L1D by the context that runs on the sibling thread of the same
physical core. This context can be any code in the hypervisor.
Guest -> Guest Attack
=====================
The possibility of guest -> guest attack varies on specific configuration,
The possibility of guest -> guest attack varies by specific configuration,
e.g. whether CPU partitioning is used, whether Hyper-threading is on, etc.
If CPU partitioning is enabled (default policy in ACRN), there is
1:1 mapping between vCPUs and pCPUs i.e. no sharing of pCPU. There
may be an attack possibility when Hyper-threading is on, where
logical processors of the same physical core may be allocated to two
different guests. Then one guest may be able to attack the other guest
on sibling thread due to shared L1D.
If CPU partitioning is enabled (the default policy in ACRN), there is a 1:1
mapping between vCPUs and pCPUs; that is, there is no pCPU sharing. There
may be an attack possibility when Hyper-threading is on, where logical
processors of the same physical core may be allocated to two different
guests. Then one guest may be able to attack the other guest on a sibling
thread due to shared L1D.
If CPU sharing is enabled (not supported now), two VMs may share
same pCPU thus next VM may steal information in L1D which comes
from activity of previous VM on the same pCPU.
If CPU sharing is enabled (not supported now), two VMs may share the same
pCPU; thus the next VM may steal information in L1D that comes from activity
of the previous VM on the same pCPU.
Normal_world -> Secure_world Attack
===================================
ACRN supports Android guest, which requires two running worlds
(normal world and secure world). Two worlds run on the same CPU,
and world switch is conducted on demand. It could be possible for
normal world to construct an L1TF-based stack to secure world,
breaking the security model as expected by Android guest.
ACRN supports Android guest, which requires two running worlds (normal world
and secure world). Two worlds run on the same CPU, and world switch is
conducted on demand. It could be possible for normal world to construct an
L1TF-based stack to secure world, breaking the security model as expected by
the Android guest.
Affected Processors
===================
L1TF affects a range of Intel processors, but Intel Atom |reg| processors
(including Apollo Lake) are immune to it. Currently ACRN hypervisor
(including Apollo Lake) are immune to it. Currently, ACRN hypervisor
supports only Apollo Lake. Support for other core-based platforms is
planned, so we still need a mitigation plan in ACRN.
@ -122,56 +122,54 @@ Processors that have the RDCL_NO bit set to one (1) in the
IA32_ARCH_CAPABILITIES MSR are not susceptible to the L1TF
speculative execution side channel.
Please refer to `Intel Analysis of L1TF`_ for more details.
For more details, refer to `Intel Analysis of L1TF`_.
L1TF Mitigation in ACRN
***********************
Use the latest microcode, which mitigates SMM and Intel SGX cases
while also providing necessary capability for VMM to use for further
mitigation.
Use the latest microcode, which mitigates SMM and Intel SGX cases while also
providing necessary capability for VMM to use for further mitigation.
ACRN will check the platform capability based on `CPUID enumeration
and architectural MSR`_. For L1TF affected platform (CPUID.07H.EDX.29
and architectural MSR`_. For an L1TF affected platform (CPUID.07H.EDX.29
with MSR_IA32_ARCH_CAPABILITIES), L1D_FLUSH capability(CPUID.07H.EDX.28)
must be supported.
.. _CPUID enumeration and architectural MSR:
https://software.intel.com/security-software-guidance/insights/deep-dive-cpuid-enumeration-and-architectural-msrs
Not all of mitigations below will be implemented in ACRN, and
not all of them apply to a specific ACRN deployment. Check the
'Mitigation Status'_ and 'Mitigation Recommendations'_ sections
for guidance.
Not all the mitigations below will be implemented in ACRN, and not all of
them apply to a specific ACRN deployment. Check the 'Mitigation Status'_ and
'Mitigation Recommendations'_ sections for guidance.
L1D Flush on VMENTRY
====================
ACRN may optionally flush L1D at VMENTRY, which ensures no
sensitive information from hypervisor or previous VM revealed
to current VM (in case of CPU sharing).
ACRN may optionally flush L1D at VMENTRY, which ensures that no sensitive
information from the hypervisor or previous VM is revealed to the current VM
(in case of CPU sharing).
Flushing the L1D evicts not only the data which should not be
accessed by a potentially malicious guest, it also flushes the
guest data. Flushing the L1D has a performance impact as the
processor has to bring the flushed guest data back into the L1D,
and actual overhead is proportional to the frequency of vmentry.
Flushing the L1D evicts not only the data that should not be accessed by a
potentially malicious guest, it also flushes the guest data. Flushing the
L1D has a performance impact as the processor has to bring the flushed guest
data back into the L1D, and the actual overhead is proportional to the
frequency of vmentry.
Due to such performance reason, ACRN provides a config option
(L1D_FLUSH_VMENTRY) to enable/disable L1D flush during
VMENTRY. By default this option is disabled.
Due to such performance reasons, ACRN provides a config option
(L1D_FLUSH_VMENTRY) to enable/disable L1D flush during VMENTRY. By default,
this option is disabled.
EPT Sanitization
================
EPT is sanitized to avoid pointing to valid host memory in PTEs
which has present bit cleared or reserved bits set.
EPT is sanitized to avoid pointing to valid host memory in PTEs that have
the present bit cleared or reserved bits set.
For non-present PTEs, ACRN currently set PFN bits to ZERO, which
means page ZERO might fall into risk if containing security info.
ACRN reserves page ZERO (0~4K) from page allocator thus page ZERO
won't be used by anybody for valid usage. This sanitization logic
is always enabled on all platforms.
For non-present PTEs, ACRN currently sets PFN bits to ZERO, which means
that page ZERO might fall into risk if it contains security information.
ACRN reserves page ZERO (0~4K) from page allocator; thus page ZERO won't
be used by anybody for a valid purpose. This sanitization logic is always
enabled on all platforms.
ACRN hypervisor doesn't set reserved bits in any EPT entry.
@ -183,81 +181,78 @@ data. The amount of valuable data from ACRN contexts cannot be declared as
non-interesting for an attacker without deep inspection of the code.
But obviously, the most import secret data in ACRN is the physical platform
seed generated from CSME and virtual seeds which are derived from that
platform seed. They are critical secrets to serve for guest keystore or
other security usage, e.g. disk encryption, secure storage.
seed generated from CSME and virtual seeds derived from that platform seed.
They are critical secrets to serve for a guest keystore or other security
usage, e.g. disk encryption, secure storage.
If the critical secret data in ACRN is identified, then such
data can be put into un-cached memory. As the content will
never go to L1D, it is immune to L1TF attack.
If the critical secret data in ACRN is identified, then such data can be put
into un-cached memory. As the content will never go to L1D, it is immune to
L1TF attack.
For example, after getting the physical seed from CSME, before any guest
starts, ACRN can pre-derive all the virtual seeds for all the
guests and then put these virtual seeds into uncached memory,
at the same time flush & erase physical seed.
starts, ACRN can pre-derive all the virtual seeds for all the guests and
then put these virtual seeds into uncached memory, and at the same time
flush and erase the physical seed.
If all security data are identified and put in uncached
memory in a specific deployment, then it is not necessary to
prevent guest -> hypervisor attack, since there is nothing
useful to be attacked.
If all security data are identified and put in uncached memory in a specific
deployment, it is not necessary to prevent guest -> hypervisor attack,
because there is nothing useful to be attacked.
However if such 100% identification is not possible, user should
consider other mitigation options to protect hypervisor.
However, if such 100% identification is not possible, the user should
consider other mitigation options to protect the hypervisor.
L1D Flush on World Switch
=========================
For L1D-affected platforms, ACRN writes to aforementioned MSR
to flush L1D when switching from secure world to normal world.
Doing so guarantees no sensitive information from secure world
leaked in L1D. Performance impact is expected to small since world
switch frequency is not expected high.
For L1D-affected platforms, ACRN writes to aforementioned MSR to flush L1D
when switching from secure world to normal world. Doing so guarantees that
no sensitive information from secure world leaked into L1D. The performance
impact is expected to be small since world switch frequency is not expected
to be high.
It's not necessary to flush L1D in the other direction, since
normal world is less privileged entity to secure world.
It's not necessary to flush L1D in the other direction, because normal world
is a less privileged entity than secure world.
This mitigation is always enabled.
Core-Based Scheduling
=====================
If Hyper-threading is enabled, it's important to avoid running
sensitive context (if containing security data which a given VM
has no permission to access) on the same physical core that runs
said VM. It requires scheduler enhancement to enable core-based
scheduling policy, so all threads on the same core are always
scheduled to the same VM. Also there are some further actions
required to protect hypervisor and secure world from sibling
attacks in core-based scheduler.
If Hyper-threading is enabled, it's important to avoid running a sensitive
context (if it contains security data that a given VM has no permission to
access) on the same physical core that runs that VM. It requires a scheduler
enhancement to enable a core-based scheduling policy, so all threads on the
same core are always scheduled to the same VM. Also there are some further
actions required to protect the hypervisor and secure the world from sibling
attacks in the core-based scheduler.
.. note:: There is no current plan to implement this scheduling
policy. The ACRN community will evaluate the need for this based
on usage requirements and hardware platform status.
.. note:: There is no current plan to implement this scheduling policy. The
ACRN community will evaluate the need for this based on usage
requirements and hardware platform status.
Mitigation Recommendations
**************************
There is no mitigation required on Apollo Lake based platforms.
The majority use case for ACRN is in pre-configured environment,
where the whole software stack (from ACRN hypervisor to guest
kernel to Service VM root) is tightly controlled by solution provider
and not allowed for run time change after sale (guest kernel is
trusted). In that case solution provider will make sure that guest
kernel is up-to-date including necessary page table sanitization,
thus there is no attack interface exposed within guest. Then a
minimal mitigation configuration is sufficient with negligible
performance impact, as explained below:
The majority use case for ACRN is in a pre-configured environment, where the
whole software stack (from ACRN hypervisor to guest kernel to Service VM
root) is tightly controlled by the solution provider and not enabled for
runtime change after sale (that is, the guest kernel is trusted). In that
case, the solution provider will make sure that the guest kernel is
up-to-date including necessary page table sanitization; thus there is no
attack interface exposed within the guest. Then a minimal mitigation
configuration is sufficient with negligible performance impact, as
explained below:
1) Use latest microcode
2) Guest kernel is up-to-date with page table sanitization
3) EPT sanitization (always enabled)
4) Flush L1D at world switch (Android specific, always enabled)
In case that someone wants to deploy ACRN into an open environment
where guest kernel is considered untrusted, there are more
mitigation options required according to the specific usage
requirements:
In case someone wants to deploy ACRN into an open environment where the
guest kernel is considered untrusted, there are additional mitigation
options required according to the specific usage requirements:
5) Put hypervisor security data in UC memory if possible
6) Enable L1D_FLUSH_VMENTRY option, if
@ -265,10 +260,10 @@ requirements:
- Doing 5) is not feasible, or
- CPU sharing is enabled (in the future)
If Hyper-threading is enabled, there is no available mitigation
option before core scheduling is planned. User should understand
the security implication and only turn on Hyper-threading
when the potential risk is acceptable to their usage.
If Hyper-threading is enabled, there is no available mitigation option
before core scheduling is planned. The user should understand the security
implication and only turn on Hyper-threading when the potential risk is
acceptable for their usage.
Mitigation Status
*****************

111
doc/developer-guides/modularity.rst
View File

@ -6,9 +6,9 @@ ACRN Hypervisor: Modular Design
Overview
********
ACRN highly emphasizes modular design, i.e. the separation of functionality info
modules that define a concise set of interfaces. The goals of modular design
include:
ACRN highly emphasizes modular design, which is the separation of
functionality into modules that define a concise set of interfaces. The goals
of modular design include:
* **Understandability** A modular design is easier to understand due to
encapsulation.
@ -17,55 +17,57 @@ include:
of tests and identify corner cases that are hard to trigger when testing the
hypervisor as a whole.
* **Configurability** Modular design makes it easy to configure certain
functionalities in or out. This is crucial in safety-critical scenarios
because absence of irrelevant code is required in both MISRA-C and functional
safety standards.
* **Meet functional safety requirements** Functional safety standards explicitly
require a hierarchical structure of modules in software architectural
design. This applies to any safety integrity level defined in
functionalities in or out. This is crucial in safety-critical scenarios,
because absence of irrelevant code is required in both MISRA-C and
functional safety standards.
* **Meet functional safety requirements** Functional safety standards
explicitly require a hierarchical structure of modules in software
architectural design. This applies to any safety integrity level defined in
[IEC_61508-3]_ and [ISO_26262-6]_.
Principles
**********
* Each source file shall belong to one module only. One module may consist of
one or multiple source files, though. A source file can be a C source, a C
header or an assembly file.
* Each module shall have well-defined interfaces, including the exported
functions and global variables. Functions and variables that are not
interfaces shall be static and used inside the module only.
* Each source file belongs to one module only. One module may consist of one
or multiple source files, though. A source file can be a C source, a C
header, or an assembly file.
* Each module has well-defined interfaces, including the exported functions
and global variables. Functions and variables that are not interfaces are
static and used inside the module only.
* Dependencies among the modules should be acyclic. Any cyclic dependency must
be deviated explicitly.
* The complexity of a module shall be limited.
* The complexity of a module should be limited.
Minimizing Cyclic Dependencies
==============================
Cyclic dependencies can be mostly avoided by carefully defining the boundary of
modules. The following methods can be used when certain cyclic dependency cannot
be resolved by design.
Cyclic dependencies are mostly avoided through careful definition of module
boundaries. The following methods can be used when a cyclic dependency cannot
be resolved by design:
* **Use callbacks** Callback registration and invocation help reverse dependencies
between two modules and break cyclic dependencies. However callbacks shall be
used with care due to its dynamic behavior. Send proposals or patches to the
* **Use callbacks** Callback registration and invocation help to reverse
dependencies between modules and break cyclic dependencies. However,
callbacks must be used with care due to their dynamic behavior. Send
proposals or patches to the
`acrn-dev mailing list <https://lists.projectacrn.org/g/acrn-dev>`_ for
discussing if specific callbacks are appropriate.
* **Making the cyclic dependency an exception** A specific cyclic dependency can
be regarded as an exception if it is well justified and a workaround is
discussing whether specific callbacks are appropriate.
* **Making the cyclic dependency an exception** A specific cyclic dependency
can be regarded as an exception if it is well justified and a workaround is
available to break the cyclic dependency for integration testing.
Measuring Complexity
====================
ACRN uses the number of functions and the cyclomatic complexity [CC]_ of each
function to measure the complexity of a module. Concrete criteria on complexity
will be determined while enhancing the modularity of the hypervisor. The current
recommendation is to limit the cyclomatic complexity of a function under 20.
function to measure the complexity of a module. Concrete criteria on
complexity will be determined during the process of enhancing the modularity
of the hypervisor. The current recommendation is to limit the cyclomatic
complexity of a function to under 20.
Architecture
************
The following figure shows the high-level components of ACRN hypervisor.
The following figure shows the high-level components of ACRN hypervisor:
.. figure:: images/modularity-architecture.png
:align: center
@ -75,34 +77,33 @@ The following figure shows the high-level components of ACRN hypervisor.
The components are listed as follows.
* **Boot** This component carries out the most basic hardware initialization to
enable the execution of C code.
* **Boot** This component carries out the most basic hardware initialization
to enable the execution of C code.
* **Library** This component consists of subroutines that require no explicit
initialization. Examples include standard memory and string manipulation
functions like strncpy, atomic operations and bitmap operations. This
functions like strncpy, atomic operations, and bitmap operations. This
component is independent from and widely used in the other components.
* **Hardware Management and Utilities** This component abstracts hardware
resources and provide services such as timers and physical interrupt handler
registration to the upper layers.
* **Virtual CPU** This component implements CPU, memory and interrupt
virtualization. The vCPU loop module in this component handles VM exit events
by calling the proper handler in the other components. Hypercalls are
implemented as a special type of VM exit event. This component is also able to
inject upcall interrupts to the Service VM.
* **Virtual CPU** This component implements CPU, memory, and interrupt
virtualization. The vCPU loop module in this component handles VM exit
events by calling the proper handler in the other components. Hypercalls are
implemented as a special type of VM exit event. This component is also able
to inject upcall interrupts to the Service VM.
* **Device Emulation** This component implements devices that are emulated in
the hypervisor itself, such as the virtual programmable interrupt controllers
including vPIC, vLAPIC and vIOAPIC.
* **Passthrough Management** This component manages devices that are passed-through
to specific VMs.
the hypervisor itself, such as the virtual programmable interrupt
controllers including vPIC, vLAPIC, and vIOAPIC.
* **Passthrough Management** This component manages devices that are passed
through to specific VMs.
* **Extended Device Emulation** This component implements an I/O request
mechanism that allows the hypervisor to forward I/O accesses from a User
VM to the Service VM.
for emulation.
* **VM Management** This component manages the creation, deletion and other
mechanism that enables the hypervisor to forward I/O accesses from a User
VM to the Service VM for emulation.
* **VM Management** This component manages the creation, deletion, and other
lifecycle operations of VMs.
* **Hypervisor Initialization** This component invokes the initialization
subroutines in the other components to bring up the hypervisor and
start the Service VM in sharing mode or all the VMs in partitioning mode.
subroutines in the other components to bring up the hypervisor and start
the Service VM in sharing mode or all the VMs in partitioning mode.
ACRN hypervisor adopts a layered design where higher layers can invoke the
interfaces of lower layers but not vice versa. The only exception is the
@ -113,16 +114,16 @@ reasons.
* **Boot** enables the execution of C code and thus has to be the lowest layer
in the architecture.
* **Hypervisor Initialization** contains the hypervisor initialization function
that calls the initialization functions of each layer. Thus this component is
the highest layer to minimize reverse dependencies.
* **Boot** shall invoke the hypervisor initialization routine after bringing up
the hardware. This inevitably causes a reverse dependency from **Boot** to
**Hypervisor Initialization**.
* **Hypervisor Initialization** contains the hypervisor initialization
function that calls the initialization functions of each layer. Thus this
component is the highest layer to minimize reverse dependencies.
* **Boot** shall invoke the hypervisor initialization routine after bringing
up the hardware. This inevitably causes a reverse dependency from **Boot**
to **Hypervisor Initialization**.
To enable integration testing of a layer in the middle (e.g. **Virtual CPU**),
**Boot** will invoke a customized function that only invokes the initialization
functions of that layer as well as the layers below.
**Boot** will invoke a customized function that invokes only the
initialization functions of that layer as well as the layers below.
References
**********

123
doc/developer-guides/sw_design_guidelines.rst
View File

@ -46,38 +46,38 @@ below:
function should trust these post-conditions are met.
Error checking of the post-conditions is not needed in release version of
each caller. Developers could use ASSERT to catch design errors in a debug
version for some cases. Verification of the hypervisor shall check whether the
function guarantees all post-conditions (or not).
version for some cases. Verification of the hypervisor shall check whether
the function guarantees all post-conditions (or not).
This design assumption applies to the following case:
- Return value of the function
It is used to guarantee that the return value is valid, such as the return
pointer is not NULL, the return value is within a valid range, or the
members of the return structure are valid.
It is used to guarantee that the return value is valid; for example, the
return pointer is not NULL, the return value is within a valid range, or
the members of the return structure are valid.
**Application Constraints**
Application constraints of the hypervisor shall be defined in design document
and safety manual.
All application constraints shall be guaranteed by external safety
applications, such as Board Support Package, firmware, safety VM, or Hardware.
The verification of application integration shall check whether the safety
application meets all application constraints. These constraints must be verified
during hypervisor validation test. It is optional to do error checking for
application constraints at hypervisor boot time.
Application constraints of the hypervisor shall be defined in design
document and safety manual. All application constraints shall be guaranteed
by external safety applications, such as Board Support Package, firmware,
safety VM, and Hardware. The verification of application integration shall
check whether the safety application meets all application constraints.
These constraints must be verified during hypervisor validation test. It is
optional to do error checking for application constraints at hypervisor
boot time.
This design assumption applies to the following cases:
- Configuration data defined by external safety application, such as physical
PCI device information specific for each board design.
- Configuration data defined by external safety application, such as
physical PCI device information specific for each board design.
- Input data that is only specified by external safety application.
- Input data that is specified only by external safety application.
.. note:: If input data can be specified by both a non-safety VM and a safety VM,
the application constraint isn't applicable to these data. Related error checking
and handling shall be done during hypervisor design.
.. note:: If input data can be specified by both a non-safety VM and a
safety VM, the application constraint isn't applicable to these data.
Related error checking and handling shall be done during hypervisor design.
Refer to the :ref:`C Programming Language Coding Guidelines <c_coding_guidelines>`
to document these design assumptions with doxygen-style comments.
@ -94,15 +94,15 @@ according to Table A.2 of FuSA Standards [IEC_61508-3_2010]_.
Error Handling Methods
----------------------
The error handling methods used in the ACRN hypervisor on an architecture level
are shown below.
The error handling methods used in the ACRN hypervisor on an architecture
level are shown below.
**Invoke default fatal error handler**
The hypervisor shall invoke the default fatal error handler when the below
cases occur. Customers can define platform-specific handlers, allowing them to
implement additional error reporting (mostly to hardware) if required. The
default fatal error handler will invoke platform-specific handlers defined by
users at first, then it will panic the system.
cases occur. Customers can define platform-specific handlers, allowing them
to implement additional error reporting (mostly to hardware) if required.
The default fatal error handler will invoke platform-specific handlers
defined by users at first, then it will panic the system.
This method applies to the following cases:
@ -122,9 +122,9 @@ are shown below.
**Inform the safety VM through specific register or memory area**
The hypervisor shall inform the safety VM through a specific register or
memory area when the below cases occur. The VM will decide how to handle the
related error. This shall only be done after the VM (Safety OS or Service OS)
dedicated to error handling has started.
memory area when the below cases occur. The VM will decide how to handle
the related error. This shall be done only after the VM (Safety OS or
Service OS) dedicated to error handling has started.
This method applies to the following cases:
@ -207,8 +207,8 @@ it's the caller's responsibility to guarantee these pre-conditions.
}
``vcpu_from_vid`` is called by ``hcall_set_vcpu_regs``, which is a hypercall.
``hcall_set_vcpu_regs`` is an external interface and ``vcpu_id`` is provided by
VM. In this case, we shall add the error checking codes before calling
``hcall_set_vcpu_regs`` is an external interface and ``vcpu_id`` is provided
by the VM. In this case, we shall add the error checking codes before calling
``vcpu_from_vid`` to make sure that the passed parameters are valid and the
pre-conditions are guaranteed.
@ -238,9 +238,9 @@ Module Level
Functional Safety Consideration
-------------------------------
Data verification, and explicit specification of pre-conditions and post-conditions
are applied for internal functions of the hypervisor according to Table A.4 of
FuSA Standards [IEC_61508-3_2010]_ .
Data verification, and explicit specification of pre-conditions and
post-conditions are applied for internal functions of the hypervisor
according to Table A.4 of FuSA Standards [IEC_61508-3_2010]_ .
Error Handling Methods
----------------------
@ -385,28 +385,29 @@ post-condition of ``get_vm_config`` guarantees that the return value is not NULL
No. Here are the reasons:
a) The pre-condition of ``partition_mode_vpci_init`` guarantees that ``vm`` is not
NULL. It indicates that ``vpci`` is not NULL. Since ``vdev`` is getting data from
the array ``pci_vdevs[]`` via indexing, ``vdev`` is not NULL as long as the index
is valid.
a) The pre-condition of ``partition_mode_vpci_init`` guarantees that ``vm``
is not NULL. It indicates that ``vpci`` is not NULL. Since ``vdev`` is
getting data from the array ``pci_vdevs[]`` via indexing, ``vdev`` is not
NULL as long as the index is valid.
b) The post-condition of ``get_vm_config`` guarantees that ``vpci->pci_vdev_cnt``
is less than or equal to ``CONFIG_MAX_PCI_DEV_NUM``, which is the array size of
``pci_vdevs[]``. It indicates that the index used to get ``vdev`` is always
valid.
b) The post-condition of ``get_vm_config`` guarantees that
``vpci->pci_vdev_cnt`` is less than or equal to ``CONFIG_MAX_PCI_DEV_NUM``,
which is the array size of ``pci_vdevs[]``. It indicates that the index
used to get ``vdev`` is always valid.
Given the two reasons above, ``vdev`` is always not NULL. So, the error checking
codes are not required for ``vdev``.
Given the two reasons above, ``vdev`` is always not NULL. So, the error
checking codes are not required for ``vdev``.
**Question_3: Is error checking required for ``pci_dev_config``?**
No. ``pci_dev_config`` is getting data from the array ``pci_vdevs[]``, which is the
physical PCI device information coming from Board Support Package and firmware.
For physical PCI device information, the related application constraints
shall be defined in the design document or safety manual. For debug purpose,
developers could use ASSERT here to catch the Board Support Package or firmware
failures, which do not guarantee these application constraints.
No. ``pci_dev_config`` is getting data from the array ``pci_vdevs[]``, which
is the physical PCI device information coming from Board Support Package and
firmware. For physical PCI device information, the related application
constraints shall be defined in the design document or safety manual. For
debug purposes, developers could use ASSERT here to catch the Board Support
Package or firmware failures, which do not guarantee these application
constraints.
**Question_4: Is error checking required for ``vdev->ops->init``?**
@ -417,8 +418,8 @@ a) Question_2 proves that ``vdev`` is always not NULL.
b) ``vdev->ops`` is fully initialized before ``vdev->ops->init`` is called.
Given the two reasons above, ``vdev->ops->init`` is always not NULL. So, the error
checking codes are not required for ``vdev->ops->init``.
Given the two reasons above, ``vdev->ops->init`` is always not NULL. So, the
error checking codes are not required for ``vdev->ops->init``.
**Question_5: How to handle the case when ``vdev->ops->init(vdev)`` returns non-zero?**
@ -457,7 +458,8 @@ boot information.
**Question_6: Is error checking required for ``vdev->ops`` and ``vdev->ops->init``?**
Yes. Because ``vdev->ops`` and ``vdev->ops->init`` cannot be guaranteed to be
not NULL. If the VM called ``partition_mode_vpci_deinit`` twice, it may be NULL.
not NULL. If the VM called ``partition_mode_vpci_deinit`` twice, it may be
NULL.
Module Level Configuration Design Guidelines
@ -527,18 +529,19 @@ Design Rules
The module level configuration design rules are shown below:
1. The platform configurations shall be detectable by hypervisor in DETECT mode;
1. The platform configurations shall be detectable by the hypervisor in
DETECT mode;
2. Configurable module APIs shall be abstracted as operations that are
implemented through a set of function pointers in the operations data
structure;
3. Every function pointer in the operations data structure shall be instantiated
as one module API in DETECT mode and the API is allowed to be implemented as
empty function for some specific configurations;
3. Every function pointer in the operations data structure shall be
instantiated as one module API in DETECT mode and the API is allowed to be
implemented as empty function for some specific configurations;
4. The operations data structure shall be read-only in STARTUP mode, OPERATIONAL
mode, and TERMINATION mode;
4. The operations data structure shall be read-only in STARTUP mode,
OPERATIONAL mode, and TERMINATION mode;
5. The configurable module shall only be accessed via APIs in the operations
data structure in STARTUP mode or OPERATIONAL mode;
@ -567,8 +570,8 @@ The following table shows some use cases of module level configuration design:
- This module is used to virtualize part of LAPIC functionalities.
It can be done via APICv or software emulation depending on CPU
capabilities.
For example, KBL Intel NUC doesn't support virtual-interrupt delivery, while
other platforms support it.
For example, KBL Intel NUC doesn't support virtual-interrupt delivery,
while other platforms support it.
- If a function pointer is used, the prerequisite is
"hv_operation_mode == OPERATIONAL".

68
doc/developer-guides/trusty.rst
View File

@ -6,21 +6,25 @@ Trusty TEE
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 wiki page <https://en.wikipedia.org/wiki/Trusted_execution_environment>`_.
`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 wiki page <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
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.
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
*******************
@ -47,21 +51,24 @@ There are a few :ref:`hypercall_apis` that are related to Trusty.
Trusty Boot Flow
****************
By design, the User OS bootloader (``UOS_Loader``) will trigger the Trusty boot process. The complete boot flow is illustrated below.
By design, the User OS bootloader (``UOS_Loader``) will trigger the Trusty
boot process. The complete boot flow is illustrated below.
.. graphviz:: images/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:
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
#. Call ``hcall_initialize_trusty`` with trusty memory base and
entry address
#. ACRN (``hcall_initialize_trusty``)
a. Save World context for Normal World
@ -70,10 +77,12 @@ As shown in the above figure, here are some details about the Trusty boot flow p
#. Trusty
a. Booting
#. Call ``hcall_world_switch`` to switch back to Normal World if boot completed
#. Call ``hcall_world_switch`` to switch back to Normal World if
boot completed
#. ACRN (``hcall_world_switch``)
a. Save World context for the World that caused this ``vmexit`` (Secure World)
a. Save World context for the World that caused this ``vmexit``
(Secure World)
#. Restore World context for next World (Normal World (UOS_Loader))
#. Resume to next World (UOS_Loader)
#. UOS_Loader
@ -83,26 +92,27 @@ As shown in the above figure, here are some details about the Trusty boot flow p
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.
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.
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.
This design will benefit the EPT changes of Normal World. There are
requirements 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.
.. figure:: images/ept-hierarchy.png
:align: center