github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-20 12:42:54 +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 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 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 is named XenGT, and over ACRN is named AcrnGT. GVT-g can export multiple
multiple virtual-GPU (vGPU) instances for virtual machine (VM) system. A virtual-GPU (vGPU) instances for a virtual machine (VM) system. A VM can be
VM can be assigned one instance of a vGPU. The guest OS graphic driver assigned one instance of a vGPU. The guest OS graphic driver needs only
needs only minor modifications to drive the vGPU adapter in a VM. Every minor modifications to drive the vGPU adapter in a VM. Every vGPU instance
vGPU instance adopts the full HW GPU's acceleration capability for adopts the full HW GPU's acceleration capability for media, 3D rendering,
media, 3D rendering, and display. and display.
AcrnGT refers to the glue layer between the ACRN hypervisor and GVT-g 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. 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 It is the only layer that must be rewritten when porting GVT-g to other
other specific hypervisors. specific hypervisors.
For simplicity, in the rest of this document, the term GVT is used to For simplicity, in the rest of this document, the term GVT is used to refer
refer to the core device model component of GVT-g, specifically to the core device model component of GVT-g, specifically corresponding to
corresponding to ``gvt.ko`` when build as a module. ``gvt.ko`` when built as a module.
Purpose of This Document Purpose of This Document
************************ ************************
This document explains the relationship between components of GVT-g in This document explains the relationship between components of GVT-g in the
the ACRN hypervisor, shows how to enable GVT-g on ACRN, and guides ACRN hypervisor, shows how to enable GVT-g on ACRN, and guides developers
developers porting GVT-g to work on other hypervisors. porting GVT-g to work on other hypervisors.
This document describes: This document describes:
- the overall components of GVT-g - the overall components of GVT-g
- interaction interface of each component - the interaction interface of each component
- core interaction scenarios - the core interaction scenarios
APIs of each component interface can be found in the :ref:`GVT-g_api` APIs of each component interface can be found in the :ref:`GVT-g_api`
documentation. documentation.
@ -44,47 +44,46 @@ documentation.
Overall Components Overall Components
****************** ******************
For the GVT-g solution for the ACRN hypervisor, there are two For the GVT-g solution for the ACRN hypervisor, there are two key modules:
key modules: AcrnGT and GVT: AcrnGT and GVT.
AcrnGT module AcrnGT module
Compiled from ``drivers/gpu/drm/i915/gvt/acrn_gvt.c``, the AcrnGT Compiled from ``drivers/gpu/drm/i915/gvt/acrn_gvt.c``, the AcrnGT
module acts as a glue layer between the ACRN hypervisor and the module acts as a glue layer between the ACRN hypervisor and the
interface to the ACRN-DM in user space. 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 request, IRQ injection, address translation, VM controls, etc. It also
listens to ACRN hypervisor in ``acrngt_emulation_thread``, and informs GVT listens to ACRN hypervisor in ``acrngt_emulation_thread``, and informs the
module of I/O traps. GVT module of I/O traps.
It calls into the GVT module's :ref:`intel_gvt_ops_interface` to invoke 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`. 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 the :ref:`sysfs_interface` by writing to sysfs node
``/sys/kernel/gvt/control/create_gvt_instance``. ``/sys/kernel/gvt/control/create_gvt_instance``.
This is the only module that needs to be rewritten when porting to This is the only module that must be rewritten when porting to another
another embedded device hypervisor. embedded device hypervisor.
GVT module GVT module
This Device Model service is the central part of all This Device Model service is the central part of all the GVT-g components.
GVT-g components. It receives workloads from each vGPU, shadows the It receives workloads from each vGPU, shadows the workloads, and
workloads, and dispatches the workloads to Dom0's i915 module to deliver dispatches the workloads to the Service VM's i915 module to deliver
workloads to real hardware. It also emulates the virtual display to each workloads to real hardware. It also emulates the virtual display to each VM.
VM.
VHM module VHM module
This is a kernel module that requires an interrupt (vIRQ) number, This is a kernel module that requires an interrupt (vIRQ) number and
and exposes APIs to external kernel modules such as GVT-g, and the 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 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 in user space, and interacts only with the DM. The DM routes I/O requests
requests and responses between other modules to and from the VHM module and responses between other modules to and from the VHM module via the
via the char device. DM may use the VHM for hypervisor service char device. DM may use the VHM for hypervisor service (including remote
(including remote memory map), and VHM may directly service the request memory map), and VHM may directly service the request such as for the
such as for the remote memory map, or invoking hypercall. It also sends remote memory map or invoking hypercall. It also sends I/O responses to
I/O responses to user space modules, notified by vIRQ injections. user-space modules, notified by vIRQ injections.
.. figure:: images/GVT-g-porting-image1.png .. figure:: images/GVT-g-porting-image1.png
@ -101,21 +100,21 @@ Core Scenario Interaction Sequences
vGPU Creation Scenario vGPU Creation Scenario
====================== ======================
In this scenario, AcrnGT receives a create request from ACRN-DM. It In this scenario, AcrnGT receives a create request from ACRN-DM. It calls
calls GVT's :ref:`intel_gvt_ops_interface` to inform GVT of vGPU GVT's :ref:`intel_gvt_ops_interface` to inform GVT of vGPU creation. This
creation. This interface sets up all vGPU resources such as MMIO, GMA, interface sets up all vGPU resources such as MMIO, GMA, PVINFO, GTT,
PVINFO, GTT, DISPLAY, and Execlists, and calls back to the AcrnGT DISPLAY, and Execlists, and calls back to the AcrnGT module through the
module through the :ref:`MPT_interface` ``attach_vgpu``. Then, the :ref:`MPT_interface` ``attach_vgpu``. Then, the AcrnGT module sets up an
AcrnGT module sets up an I/O request server and asks to trap the PCI I/O request server and asks to trap the PCI configure space of the vGPU
configure space of the vGPU (virtual device 0:2:0) via VHM's APIs. (virtual device 0:2:0) via VHM's APIs. Finally, the AcrnGT module launches
Finally, the AcrnGT module launches an AcrnGT emulation thread to an AcrnGT emulation thread to listen to I/O trap notifications from HVM and
listen to I/O trap notifications from HVM and ACRN hypervisor. ACRN hypervisor.
vGPU Destroy Scenario vGPU Destroy Scenario
===================== =====================
In this scenario, AcrnGT receives a destroy request from ACRN-DM. It In this scenario, AcrnGT receives a destroy request from ACRN-DM. It calls
calls GVT's :ref:`intel_gvt_ops_interface` to inform GVT of the vGPU destroy GVT's :ref:`intel_gvt_ops_interface` to inform GVT of the vGPU destroy
request, and cleans up all vGPU resources. request, and cleans up all vGPU resources.
vGPU PCI Configure Space Write Scenario vGPU PCI Configure Space Write Scenario
@ -136,28 +135,26 @@ config space write:
PCI Configure Space Read Scenario PCI Configure Space Read Scenario
================================= =================================
Call sequence is almost the same as the write scenario above, The call sequence is almost the same as in the write scenario above, but
but instead it calls the GVT's :ref:`intel_gvt_ops_interface` instead it calls the GVT's :ref:`intel_gvt_ops_interface`
``emulate_cfg_read`` to emulate the vGPU PCI config space read. ``emulate_cfg_read`` to emulate the vGPU PCI config space read.
GGTT Read/Write Scenario GGTT Read/Write Scenario
======================== ========================
GGTT's trap is set up in the PCI configure space write GGTT's trap is set up in the PCI configure space write scenario above.
scenario above.
MMIO Read/Write Scenario MMIO Read/Write Scenario
======================== ========================
MMIO's trap is set up in the PCI configure space write MMIO's trap is set up in the PCI configure space write scenario above.
scenario above.
PPGTT Write-Protection Page Set/Unset Scenario PPGTT Write-Protection Page Set/Unset Scenario
============================================== ==============================================
PPGTT write-protection page is set by calling ``acrn_ioreq_add_iorange`` The 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 with range type as ``REQ_WP`` and trapping its write to the device model
allowing read without trap. while allowing read without trap.
PPGTT write-protection page is unset by calling ``acrn_ioreq_del_range``. 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 Introduction
************ ************
The ACRN Hypervisor follows the Virtual I/O Device (virtio) The ACRN Hypervisor follows the Virtual I/O Device (virtio) specification to
specification to realize I/O virtualization for many realize I/O virtualization for many performance-critical devices supported in
performance-critical devices supported in the ACRN project. The the ACRN project. The hypervisor provides the virtio backend service (VBS)
hypervisor provides the virtio backend service (VBS) APIs, that make it APIs, which make it very straightforward to implement a virtio device in the
very straightforward to implement a virtio device in the hypervisor. We hypervisor. We can evaluate the virtio backend service in kernel-land (VBS-K)
can evaluate the virtio backend service in kernel-land (VBS-K) framework framework overhead through a test virtual device called virtio-echo. The
overhead through a test virtual device called virtio-echo. The total total overhead of a frontend-backend application based on VBS-K consists of
overhead of a frontend-backend application based on VBS-K consists VBS-K framework overhead and application-specific overhead. The
of VBS-K framework overhead and application-specific overhead. The application-specific overhead depends on the specific frontend-backend design,
application-specific overhead depends on the specific frontend-backend from microseconds to seconds. In our hardware case, the overall VBS-K
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
framework overhead is on the microsecond level, sufficient to meet the of most applications.
needs of most applications.
Architecture of VIRTIO-ECHO Architecture of VIRTIO-ECHO
*************************** ***************************
virtio-echo is a virtual device based on virtio, and designed for virtio-echo is a virtual device based on virtio, and designed for testing
testing ACRN virtio backend services in the kernel (VBS-K) framework. It ACRN virtio backend services in the kernel (VBS-K) framework. It includes a
includes a virtio-echo frontend driver, a virtio-echo driver in ACRN virtio-echo frontend driver, a virtio-echo driver in ACRN device model (DM)
device model (DM) for initialization, and a virtio-echo driver based on for initialization, and a virtio-echo driver based on VBS-K for data reception
VBS-K for data reception and transmission. For more virtualization and transmission. For more virtualization background introduction, refer to:
background introduction, please refer to:
* :ref:`introduction` * :ref:`introduction`
* :ref:`virtio-hld` * :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 model (DM), and is registered as a PCI virtio device to the guest OS
(User VM). The virtio-echo software has three parts: (User VM). The virtio-echo software has three parts:
- **virtio-echo Frontend Driver**: This driver runs in the User VM. It prepares - **virtio-echo Frontend Driver**: This driver runs in the User VM. It
the RXQ and notifies the backend for receiving incoming data when the prepares the RXQ and notifies the backend for receiving incoming data when
User VM starts. Second, it copies the received data from the RXQ to TXQ 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 and sends them to the backend. After receiving the message that the
transmission is completed, it starts again another round of reception transmission is completed, it starts again another round of reception
and transmission, and keeps running until a specified number of cycles 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 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 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 TXQ, and then sends them back to the backend. The backend driver then
notifies the frontend driver that the data in the TXQ has notifies the frontend driver that the data in the TXQ has been successfully
been successfully received. In virtio-echo, the backend driver received. In virtio-echo, the backend driver doesn't process or use the
doesn't process or use the received data. received data.
:numref:`vbsk-virtio-echo-arch` shows the whole architecture of virtio-echo. :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 Virtualization Overhead Analysis
******************************** ********************************
Let's analyze the overhead of the VBS-K framework. As we know, the VBS-K 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 handles notifications in the Service VM kernel instead of in the Service VM
DM. This can avoid overhead from switching between kernel space and user user space DM. This can avoid overhead from switching between kernel space
space. Virtqueues are allocated by User VM, and virtqueue information is and user space. Virtqueues are allocated by User VM, and virtqueue
configured to VBS-K backend by the virtio-echo driver in DM, thus information is configured to VBS-K backend by the virtio-echo driver in DM;
virtqueues can be shared between User VM and Service VM. There is no copy overhead thus virtqueues can be shared between User VM and Service VM. There is no
in this sense. The overhead of VBS-K framework mainly contains two copy overhead in this sense. The overhead of VBS-K framework mainly contains
parts: kick overhead and notify overhead. two parts: kick overhead and notify overhead.
- **Kick Overhead**: The User VM gets trapped when it executes sensitive - **Kick Overhead**: The User VM gets trapped when it executes sensitive
instructions that notify the hypervisor first. The notification is 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 defined as the interval from the beginning of the interrupt injection
to when the User VM starts interrupt processing. to when the User VM starts interrupt processing.
The overhead of a specific application based on VBS-K includes two The overhead of a specific application based on VBS-K includes two parts:
parts: VBS-K framework overhead and application-specific overhead. VBS-K framework overhead and application-specific overhead.
- **VBS-K Framework Overhead**: As defined above, VBS-K framework overhead - **VBS-K Framework Overhead**: As defined above, VBS-K framework overhead
refers to kick overhead and notify 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. operation and one "notify" operation are both on a microsecond level.
Overhead of steps marked as blue depend on specific frontend and backend Overhead of steps marked as blue depend on specific frontend and backend
virtual device drivers. For virtio-echo, the whole end-to-end process 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 (from step1 to step 9) costs about four dozen microseconds. That's
because virtio-echo does little things in its frontend and backend because virtio-echo performs small operations in its frontend and backend
driver that is just for testing and there is very little process driver that are just for testing, and there is very little process overhead.
overhead.
.. figure:: images/vbsk-image1.png .. figure:: images/vbsk-image1.png
:width: 600px :width: 600px
@ -126,7 +123,7 @@ overhead.
:numref:`vbsk-virtio-echo-path` details the path of kick and notify :numref:`vbsk-virtio-echo-path` details the path of kick and notify
operation shown in :numref:`vbsk-virtio-echo-e2e`. The VBS-K framework 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 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. overhead of passing IOREQ to userspace processing.
.. figure:: images/vbsk-image3.png .. figure:: images/vbsk-image3.png
@ -139,9 +136,9 @@ overhead of passing IOREQ to userspace processing.
Conclusion Conclusion
********** **********
Unlike VBS-U processing in user mode, VBS-K moves things into the kernel 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 mode and can be used to accelerate processing. A virtual device virtio-echo
virtio-echo based on VBS-K framework is used to evaluate the VBS-K based on the VBS-K framework is used to evaluate the VBS-K framework overhead.
framework overhead. In our test, the VBS-K framework overhead (one kick In our test, the VBS-K framework overhead (one kick operation and one
operation and one notify operation) is on the microsecond level, which notify operation) is on the microsecond level, which can meet the needs of
can meet the needs of most applications. 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 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`` This rule applies only to the Assembly file that uses the ``.end`` directive.
directive. ``.end`` directive shall be the last statement in this case. The ``.end`` directive shall be the last statement in this case. All
All the statements past ``.end`` directive will not be processed by the statements past the ``.end`` directive will not be processed by the assembler.
assembler.
Compliant example:: Compliant example::
@ -226,8 +225,8 @@ Compliant example::
ASM-GN-09: Far jump shall be used with restrictions ASM-GN-09: Far jump shall be used with restrictions
=================================================== ===================================================
Jumping to an instruction located in a different segment shall only be used for Jumping to an instruction located in a different segment shall be used only
the following two cases: for the following two cases:
a) Code bit changes, such as change from 32-bit mode to 64-bit mode. 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 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 ASM-GN-10: Assembler directives shall be used with restrictions
=============================================================== ===============================================================
Usage of the assembler directive refers to GNU assembler 'as' user manual. Only Usage of the assembler directive refers to the GNU assembler ``as`` user
the following assembler directives may be used: manual. Only the following assembler directives may be used:
1) ``.align`` 1) ``.align``
2) ``.end`` 2) ``.end``
@ -315,12 +314,12 @@ Compliant example::
call asm_func_showcase 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 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:: Compliant example::
@ -352,7 +351,7 @@ Compliant example::
jmp tmp 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:: Compliant example::
@ -381,10 +380,10 @@ Compliant example::
ret 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:: Compliant example::
@ -411,7 +410,7 @@ Compliant example::
ASM-FN-05: A jump instruction shall not be used to jump out of a function 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:: Compliant example::
@ -786,10 +785,11 @@ Compliant example::
ASM-NC-03: Label name shall be unique ASM-NC-03: Label name shall be unique
===================================== =====================================
Label name shall be unique with the following exception. Usage of local labels Label name shall be unique with the following exception: Use of local labels
is allowed. Local label is defined with the format ``N:``, where N represents any is allowed. A local label is defined with the format ``N:``, where N
non-negative integer. Using ``Nb`` to refer to the most recent previous definition represents any non-negative integer. Use ``Nb`` to refer to the most recent
of that label. Using ``Nf`` to refer to the next definition of a local label. previous definition of that label. Use ``Nf`` to refer to the next definition
of a local label.
Compliant example:: 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 C-PP-01: ## or # operators shall be used with restrictions
========================================================== ==========================================================
``##`` or ``#`` operators shall only be used alone. The following cases shall not be ``##`` or ``#`` operators shall only be used alone. The following cases shall
allowed: not be allowed:
a) The result getting from ``##`` or ``#`` operation shall not be used as the operands a) The result from the ``##`` or ``#`` operation shall not be used as the
of another ``##`` or ``#`` operation; operands of another ``##`` or ``#`` operation.
b) Mixed-use of ``##`` or ``#`` operators shall not be allowed. b) Mixed use of ``##`` or ``#`` operators shall not be allowed.
Compliant example:: Compliant example::
@ -322,8 +322,8 @@ Compliant example::
showcase += 10U; 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:: Compliant example::
@ -374,13 +374,13 @@ Compliant example::
uint32_t showcase[] = {0U, 1U}; 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. 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 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 with the ``extern`` specifier and the other one is in a source file *without*
specifier. the ``extern`` specifier.
Compliant example:: Compliant example::
@ -444,8 +444,8 @@ Compliant example::
Functions 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:: 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:: 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:: 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:: 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:: 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:: 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 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 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 The formal parameter name of a function shall be the same between its
declaration and definition. declaration and its definition.
Compliant example:: 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 The formal parameter type of a function shall be the same between its
declaration and definition. declaration and its definition.
Compliant example:: Compliant example::
@ -731,7 +731,7 @@ Compliant example::
C-FN-11: The return type of a function shall be consistent 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. definition.
Compliant example:: Compliant example::
@ -771,9 +771,9 @@ The following cases shall be covered:
a) These dynamic memory allocation functions shall not be used: ``calloc``, a) These dynamic memory allocation functions shall not be used: ``calloc``,
``malloc``, ``realloc``, and ``free``. Dynamic memory allocation shall be ``malloc``, ``realloc``, and ``free``. Dynamic memory allocation shall be
replaced with static memory allocation. replaced with static memory allocation.
b) The functions ``va_arg``, ``va_start``, and ``va_end`` shall only be used b) The functions ``va_arg``, ``va_start``, and ``va_end`` shall be used only
within variadic functions (functions taking a variable number of parameters) within variadic functions (functions taking a variable number of
such as ``printf``. parameters) such as ``printf``.
Compliant example:: Compliant example::
@ -812,18 +812,18 @@ Compliant example::
/* declaration */ /* declaration */
uint32_t func_showcase(uint32_t param); 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 C-FN-14: All defined functions shall be used
============================================ ============================================
All defined functions shall be used, either called explicitly or indirectly via All defined functions shall be used, either called explicitly or indirectly
its address. Otherwise, the function shall be removed. The following case is an via the address. Otherwise, the function shall be removed. The following case
exception. Some extra functions may be kept in order to provide a more complete is an exception: Some extra functions may be kept in order to provide a more
library of APIs. These functions may have been implemented but not used 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 currently. These functions will come in handy in the future. In this case,
functions may remain. these functions may remain.
Compliant example:: 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 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 explicitly via ``(void)``. If the return value contains the error code, this
value shall be checked in all possible paths. return value shall be checked in all possible paths.
Compliant example:: 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 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:: 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 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 the following exception: ``do { ... } while (0)`` shall be allowed if it is
in a MACRO. used in a MACRO.
Compliant example:: 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 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 statement. This is to guarantee that the developers have considered all of the
possible cases. possible cases.
@ -1366,8 +1366,8 @@ Expressions
C-EP-01: The initialization expression of a for loop shall be simple 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 The initialization expression of a for loop shall be used only to initialize
loop counter. All other operations shall not be allowed. the loop counter. All other operations shall not be allowed.
Compliant example:: Compliant example::
@ -1417,8 +1417,8 @@ Compliant example::
C-EP-03: The third expression of a for loop shall be simple 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 third expression of a for loop shall be used only to increase or decrease
the loop counter with the following operators, ++, --, +=, or -=. All other the loop counter with the following operators: ++, --, +=, or -=. All other
operations shall not be allowed. operations shall not be allowed.
Compliant example:: Compliant example::
@ -1498,8 +1498,8 @@ Compliant example::
uint8_t showcase = 255U + 1U; 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:: Compliant example::
@ -1512,8 +1512,8 @@ Compliant example::
int32_t showcase = -10U; 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:: 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 Thus, the return value of the sizeof operation is the pointer size rather than
the array size. the array size.
@ -1675,8 +1675,8 @@ Compliant example::
C-EP-14: The destination object shall have sufficient space for operation C-EP-14: The destination object shall have sufficient space for operation
========================================================================= =========================================================================
The destination object shall have sufficient space for operation, such as copy, The destination object shall have sufficient space for operation, such as
move, compare and concatenate. Otherwise, data corruption may occur. copy, move, compare, and concatenate. Otherwise, data corruption may occur.
Compliant example:: Compliant example::
@ -1790,9 +1790,9 @@ C-EP-19: ++ or -- operation shall be used with restrictions
Only the following cases shall be allowed: Only the following cases shall be allowed:
a) ++ or -- operation shall be allowed if it is used alone in the expression; 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 b) ++ or -- operation shall be allowed if it is used as the third expression
a for loop. of a for loop.
Compliant example:: Compliant example::
@ -1813,9 +1813,9 @@ Compliant example::
C-EP-20: Array indexing shall be in-bounds C-EP-20: Array indexing shall be in-bounds
========================================== ==========================================
An array index value shall be between zero (for the first element) and the array An array index value shall be between zero (for the first element) and the
size minus one (for the last element). Out-of-bound array references are an array size minus one (for the last element). Out-of-bounds array references
undefined behavior and shall be avoided. are an undefined behavior and shall be avoided.
Compliant example:: 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 a) The magic number is defined as a MACRO with a name clearly indicating its
meaning. meaning.
b) The meaning of the magic number is clearly documented in the comments before b) The meaning of the magic number is clearly documented in the comments
its usage. before its usage.
c) The meaning of the magic number is straightforward in the specific context. c) The meaning of the magic number is straightforward in the specific context.
Compliant example:: Compliant example::
@ -1880,9 +1880,10 @@ Compliant example::
C-EP-23: Pointer arithmetic shall be used with restrictions 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 Pointer arithmetic shall be performed on an array if it is possible. If not,
data type and the value range of this pointer shall be checked before access to the data type and the value range of this pointer shall be checked before
ensure that the pointer reference is within the correct address space. access to ensure that the pointer reference is within the correct
address space.
Compliant example:: Compliant example::
@ -1962,15 +1963,15 @@ Compliant example::
showcase = showcase & mask; 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: Some detailed rules are listed below:
a) The operands of the arithmetic operation shall be integers; a) The operands of the arithmetic operation shall be integers.
b) The operands of the logical operation shall be Boolean values; b) The operands of the logical operation shall be Boolean values.
c) The controlling expression of a selection or iteration statement shall be 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. d) A Boolean type expression shall be used where Boolean is expected.
Compliant example:: 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: Only the following operations on enum shall be allowed:
a) enum assignment shall be allowed if the operands of = operation have the same a) enum assignment shall be allowed if the operands of = operation have the
enum type; same enum type.
b) enum comparison shall be allowed, including the operators ==, !=, >, <, >=, b) enum comparison shall be allowed, including the operators ==, !=, >, <, >=,
and <=. and <=.
@ -2045,8 +2046,8 @@ Compliant example::
chr = showcase[static 1]; 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:: 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:: Compliant example::
@ -2116,8 +2117,8 @@ Compliant example::
struct struct_showcase showcase = {32U, -1}; 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 The type shall be consistent between the case expression and the controlling
expression of switch statement. 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:: Compliant example::
@ -2185,7 +2186,7 @@ Compliant example::
uint32_t *showcase = (uint32_t *)showcase_const; 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:: 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: Only the following pointer assignment shall be allowed:
a) Assignment shall be allowed via the address operator &; a) Assignment shall be allowed via the address operator ``&``.
b) Assignment shall be allowed if the objects pointed to by the two pointers are b) Assignment shall be allowed if the objects pointed to by the two pointers
of the same type. are of the same type.
Compliant example:: Compliant example::
@ -2372,7 +2373,7 @@ Compliant example::
uint32_t showcase; 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:: 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:: Compliant example::
@ -2482,8 +2483,8 @@ Compliant example::
showcase_ptr_u32 = (uint32_t *)showcase_ptr_struct; 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:: Compliant example::
@ -2507,8 +2508,8 @@ Compliant example::
func_ptr_a = func_ptr_b; 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:: Compliant example::
@ -2537,17 +2538,17 @@ Compliant example::
func_ptr_showcase = (func_ptr_t)func_showcase; 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: The following operations shall be covered:
a) If a string literal is assigned to a variable, this variable shall be 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 b) If a string literal is passed as a function parameter, this function
parameter 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 c) If a string literal is used as the return value of a function, this
return type shall be declared with const qualifier. function return type shall be declared with the ``const`` qualifier.
Compliant example:: Compliant example::
@ -2563,8 +2564,9 @@ Compliant example::
C-TY-26: The basic numerical types shall not be used other than in typedefs 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 The typedef name shall be used to replace the usage of basic numerical types.
is to guarantee the code portability between different compilers and platforms. This is to guarantee the code portability between different compilers and
platforms.
Compliant example:: Compliant example::
@ -2615,11 +2617,11 @@ Compliant example::
uint32_t test = showcase_u16 + showcase_u32 + showcase_u64; 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 For 8-bit, 16-bit, and 32-bit unsigned integer constants, the "U" suffix shall
used. For 64-bit unsigned integer constants, "UL" suffix shall be used. be used. For 64-bit unsigned integer constants, the "UL" suffix shall be used.
Compliant example:: Compliant example::
@ -2713,9 +2715,9 @@ Compliant example::
C-ID-03: A global variable name shall be unique 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, A global variable name shall not be the same as the name of struct, union,
typedef, function, function parameter, macro, member, enum constant, local enum, typedef, function, function parameter, macro, member, enum constant,
variable, or other global variables. local variable, or other global variables.
Compliant example:: Compliant example::
@ -2832,8 +2834,8 @@ Compliant example::
uint32_t uint32_t; 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 All names starting with one or two underscores are reserved for use by the
compiler and standard libraries to eliminate potential conflicts with compiler and standard libraries to eliminate potential conflicts with
@ -2850,8 +2852,8 @@ Compliant example::
uint32_t __showcase; 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:: 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]); 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:: Compliant example::
@ -2950,8 +2952,8 @@ Compliant example::
C-CS-03: Tabs shall be used for code indentation C-CS-03: Tabs shall be used for code indentation
================================================ ================================================
Spaces are allowed only for indenting comments or aligning statements that span Spaces are allowed only for indenting comments or aligning statements that
multiple lines. span multiple lines.
Compliant example:: 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 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 bracket (either a brace or a parenthesis) that follows. This rule applies to
keywords ``if``, ``else``, ``for``, ``do``, ``while``, ``switch`` and ``return``. the keywords ``if``, ``else``, ``for``, ``do``, ``while``, ``switch``, and
``return``.
Compliant example:: 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:: Compliant example::
@ -3043,10 +3046,10 @@ Compliant example::
size_t entry_size = sizeof (struct vcpuid_entry); 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:: 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: The following cases shall be covered:
a) For declaration of variables of a pointer type, the ``*`` character shall be a) For declaration of variables of a pointer type, the ``*`` character shall
right before the variable identifier with no space in between. be right before the variable identifier with no space in between.
b) For functions whose return value is of a pointer type, the ``*`` character 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 shall be right before the function identifier with no spaces in between in
function prototype. the function prototype.
Compliant example:: 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, 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:: 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 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 applies to member accesses, prefix or postfix increments and decrements,
and indirection operators. address and indirection operators.
Compliant example:: 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 The statement after if/switch/for/do/while shall always be a compound
with its opening brace in the same line as the keyword. statement with its opening brace on the same line as the keyword.
Compliant example:: Compliant example::
@ -3274,46 +3278,47 @@ Compliant example::
C-CS-18: Function information shall be documented with doxygen-style comments 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 Some detailed rules are listed below to illustrate the comments format for
function: each function:
1) The comments block shall start with ``/**`` (slash-asterisk-asterisk) in a 1) The comments block shall start with ``/**`` (slash-asterisk-asterisk) in a
single line. single line.
2) The comments block shall end with :literal:`\ */` (space-asterisk-slash) in a single 2) The comments block shall end with :literal:`\ */` (space-asterisk-slash) in
line. a single line.
3) Other than the first line and the last line, every line inside the comments 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 block shall start with :literal:`\ *` (space-asterisk). It also applies to
is used to separate different paragraphs. We'll call it a blank line for the line which is used to separate different paragraphs. We'll call it a
simplicity. blank line for simplicity.
4) For each function, following information shall be documented: 4) For each function, following information shall be documented:
brief description, detailed description, parameters description, brief description, detailed description, parameters description,
pre-conditions, post-conditions, return value description, and comments pre-conditions, post-conditions, return value description, and comments
explaining the actual return values. We'll call each block of information a explaining the actual return values. We'll call each block of information
paragraph for simplicity. A paragraph may be removed from the list if it is not a paragraph for simplicity. A paragraph may be removed from the list if it
applicable for that function. is not applicable for that function.
5) Each line shall only contain the description for one parameter, or one 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 pre-condition, or one post-condition, or one actual return value. We'll
each of these an element for simplicity. call each of these an element for simplicity.
6) A blank line shall separate different paragraphs. Inside each paragraph, a 6) A blank line shall separate different paragraphs. Inside each paragraph, a
blank line is not required to separate each element. blank line is not required to separate each element.
7) The brief description of the function shall be documented with the format 7) The brief description of the function shall be documented with the format
``@brief <brief description>``. ``@brief <brief description>``.
8) No specific format is required for the detailed description of the function. 8) No specific format is required for the detailed description of the
9) The description of the function parameter shall be documented with the format function.
``@param <parameter name> <parameter description>``. 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 10) The pre-condition of the function shall be documented with the format
``@pre <pre-condition description>``. ``@pre <pre-condition description>``.
11) The post-condition of the function shall be documented with the format 11) The post-condition of the function shall be documented with the format
``@post <post-condition description>``. ``@post <post-condition description>``.
12) The brief description of the function return value shall be documented with 12) The brief description of the function return value shall be documented
the format ``@return <brief description of return value>``. with the format ``@return <brief description of return value>``.
13) A void-returning function shall be documented with the format 13) A void-returning function shall be documented with the format
``@return None``. ``@return None``.
14) The comments explaining the actual return values shall be documented with 14) The comments explaining the actual return values shall be documented with
the format ``@retval <return value> <return value explanation>``. the format ``@retval <return value> <return value explanation>``.
15) If the description of one element needs to span multiple lines, each line 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 shall be aligned to the start of the description in the first line for
element. that element.
16) The comments block shall appear immediately before the function 16) The comments block shall appear immediately before the function
definition/declaration in the C source file or header file. 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 Legal entity shall be documented in a separate comments block at the start of
every file. every file. The following information shall be included:
The following information shall be included:
a) Copyright a) Copyright
b) License (using an `SPDX-License-Identifier <https://spdx.org/licenses/>`_) 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_`` C-NC-03: Data structures exposed to external components shall be named with prefix ``acrn_``
============================================================================================ ============================================================================================
The data structure types include struct, union, and enum. The data structure types include struct, union, and enum. This rule applies to
This rule applies to the data structure with all the following properties: 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 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. c) The name meaning is simplistic or common, such as vcpu or vm.
Compliant example:: Compliant example::
@ -3465,11 +3469,11 @@ Compliant example::
C-NC-04: Data structures only used by hypervisor shall be named with prefix ``hv_`` C-NC-04: Data structures only used by hypervisor shall be named with prefix ``hv_``
=================================================================================== ===================================================================================
The data structure types include struct, union, and enum. The data structure types include struct, union, and enum. This rule applies to
This rule applies to the data structure with all the following properties: 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 only used by hypervisor; b) The corresponding resource is only used by hypervisor.
c) The name meaning is simplistic or common, such as timer. c) The name meaning is simplistic or common, such as timer.
Compliant example:: 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 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. The data structure types include struct, union, and enum. This rule applies to
This rule applies to the data structure with all the following properties: 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. b) The name meaning is simplistic or common, such as context.
Compliant example:: 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 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. The data structure types include struct, union, and enum. For example:
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 b) The data structure related to segment selector shall be named with suffix
``sel``. ``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 name shall be descriptive and clearly indicate the purpose of the
function. Some detailed rules are listed below: function. Some detailed rules are listed below:
1) If the function is doing actions, it shall be named with one of the following 1) If the function is performing actions, it shall be named with one of the
formats: following formats:
a) ``<verb>_<nouns>``, such as ``init_vmcs``. a) ``<verb>_<nouns>``, such as ``init_vmcs``.
b) ``<verb>_<adjective>_<nouns>``, such as ``init_primary_pcpu``. 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 2) If the function is doing checks, it shall be named with one of the
formats: following formats:
a) ``is_<nouns>``, such as ``is_space``. a) ``is_<nouns>``, such as ``is_space``.
b) ``is_<nouns>_<adjective>``, such as ``is_pcpu_active``. 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``. a) ``<nouns>_to_<nouns>``, such as ``irq_to_vector``.
b) ``<nouns>2<nouns>``, such as ``gva2gpa``. b) ``<nouns>2<nouns>``, such as ``gva2gpa``.
4) If the function is specific for one module and the name is not descriptive 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 enough with prior rules, it shall be named with the module name as prefix,
as ``vie_read_mmio``. such as ``vie_read_mmio``.
5) If the function is a wrapper of inline Assembly codes, it shall be named with 5) If the function is a wrapper of inline Assembly codes, it shall be named
one of the following formats: with one of the following formats:
a) ``asm_<Assembly instruction mnemonic>``, such as ``asm_pause``. a) ``asm_<Assembly instruction mnemonic>``, such as ``asm_pause``.
b) If the Assembly instruction mnemonic does not clearly indicate the b) If the Assembly instruction mnemonic does not clearly indicate the
purpose of the function or the function includes multiple Assembly purpose of the function or the function includes multiple Assembly
instruction statements, the function shall be named with ``asm_`` as instruction statements, the function shall be named with ``asm_`` as
prefix and apply the other non-assembly function naming rules. 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 6) ``<nouns>`` mentioned in prior rules may either be one noun or multiple
long as it could clearly illustrate the object. nouns, as long as it could clearly illustrate the object.
Compliant example:: Compliant example::
@ -3630,7 +3633,7 @@ Compliant example::
uint32_t pause(uint32_t param); 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 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 The number of bits in a byte is implementation-defined, according to J.3.4
1 in C99. For ACRN hypervisor, the number of bits in a byte is 8. 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 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 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, 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 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 being compiled. Non-ASCII characters are allowed in comments, such as the
name. author name.
C-IB-04: ``plain char`` is equivalent to ``signed char`` 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 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, The integer type compatible with each enumerated type is
according to J.3.9 item 6 in C99. For ACRN hypervisor, if the enum has no implementation-defined, according to J.3.9 item 6 in C99. For ACRN hypervisor,
negative underlying values, unsigned int is used; otherwise, int is used. 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 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 The number of bytes in an object is implementation-defined, according to
item 2 in C99. For ACRN hypervisor, char is 1 byte, short is 2 bytes, int is 4 J.3.13 item 2 in C99. For ACRN hypervisor, char is 1 byte, short is 2 bytes,
bytes, long is 8 bytes, and long long is not used. int is 4 bytes, long is 8 bytes, and long long is not used.
Language Extensions 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/>`_. 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. 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. 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: This rule applies to the following type attributes:

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

@ -3,12 +3,11 @@
Coding Guidelines Coding Guidelines
################# #################
ACRN Project coding guidelines establish a common set of standards ACRN Project coding guidelines establish a common set of standards and
and practices that improve readability and maintainability practices that improve the readability and maintainability of the code.
of the code. These guidelines also help ensure the code is safe, These guidelines also help ensure that the code is safe, secure, and reliable
secure, and reliable by reducing undefined or unspecified by reducing undefined or unspecified behavior through restrictions on the use
behavior by restricting use of problematic areas of the programming of problematic areas of the programming language.
language.
The following sections document the project's language-specific guidelines: 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 Contribution Guidelines
####################### #######################
As an open-source project, we welcome and encourage the community to As an open-source project, we welcome and encourage the community to submit
submit patches directly to project ACRN. In our collaborative open patches directly to project ACRN. In our collaborative open-source
source environment, standards and methods for submitting changes help environment, standards and methods for submitting changes help reduce the
reduce the chaos that can result from an active development community. chaos that can result from an active development community.
This document explains how to participate in project conversations, log This document explains how to participate in project conversations, log
and track bugs and enhancement requests, and submit patches to the 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
********* *********
Licensing is very important to open source projects. It helps ensure the Licensing is very important to open-source projects. It helps ensure that the
software continues to be available under the terms that the author software continues to be available under the terms that the author desired.
desired.
Project ACRN uses a BSD-3-Clause license, as found in the Project ACRN uses a BSD-3-Clause license, as found in the
:acrn_file:`LICENSE <LICENSE>` :acrn_file:`LICENSE <LICENSE>` in the project's GitHub repo.
in the project's GitHub repo.
A license tells you what rights you have as a developer, as provided by A license tells you what rights you have as a developer, as provided by
the copyright holder. It is important that the contributor fully 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) 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 project ACRN requires the Developer Certificate of Origin (DCO) process
to be followed. to be followed.
The DCO is an attestation attached to every contribution made by every The DCO is an attestation attached to every contribution made by every
developer. In the commit message of the contribution, (described more developer. In the commit message of the contribution, (described more
fully later in this document), the developer simply adds a fully later in this document), the developer simply adds a ``Signed-off-by``
``Signed-off-by`` statement and thereby agrees to the DCO. statement and thereby agrees to the DCO.
When a developer submits a patch, it is a commitment that the When a developer submits a patch, it is a commitment that the contributor has
contributor has the right to submit the patch per the license. The DCO the right to submit the patch per the license. The DCO agreement is shown
agreement is shown below and at http://developercertificate.org/. below and at http://developercertificate.org/.
.. code-block:: none .. code-block:: none
@ -79,21 +77,22 @@ agreement is shown below and at http://developercertificate.org/.
DCO Sign-Off Methods DCO Sign-Off Methods
==================== ====================
The DCO requires that a sign-off message, in the following format, The DCO requires that a sign-off message, in the following format, appears on
appears on each commit in the pull request:: each commit in the pull request::
Signed-off-by: Acrnus Jones <acrnusj@gmail.com> Signed-off-by: Acrnus Jones <acrnusj@gmail.com>
The DCO text can either be manually added to your commit body, or you can add You can either manually add the DCO text to your commit body or you can add
either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget to
to add the sign-off you can also amend a previous commit with the sign-off by 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 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:: .. note::
The name and email address of the account you use to submit your PR must 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 match the name and email address on the ``Signed-off-by`` line in your
your commit message. commit message.
Prerequisites Prerequisites
************* *************
@ -108,8 +107,8 @@ as introduced in the project ACRN `Getting Started Guide`_.
.. _Getting Started Guide: .. _Getting Started Guide:
https://projectacrn.github.io/latest/try.html https://projectacrn.github.io/latest/try.html
You should be familiar with common developer tools such as Git and You should be familiar with common developer tools and platforms such as Git
platforms such as GitHub. and GitHub.
If you haven't already done so, you'll need to create a (free) GitHub account 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. 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``, 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 $ git clone https://github.com/projectacrn/acrn-hypervisor
In addition to the ACRN hypervisor and device model itself, In addition to the ACRN hypervisor and device model itself, you'll also find
you'll also find the sources for technical documentation available from the sources for technical documentation available from the
the `ACRN documentation site`_. All of these are available for `ACRN documentation site`_. All of these are available for developers to
developers to contribute to and enhance. contribute to and enhance.
.. _ACRN documentation site: .. _ACRN documentation site:
https://projectacrn.github.io/ https://projectacrn.github.io/
@ -150,13 +149,13 @@ have encountered the issue you're finding, or that have similar ideas
for changes or additions. for changes or additions.
If you don't find an existing issue listed in the `ACRN hypervisor issues`_ 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 list, then click the "New Issue" button and provide a summary title and a
and more detailed description of your bug or enhancement request. more-detailed description of your bug or enhancement request.
When you submit an issue (bug or feature request), the triage team will When you submit an issue (bug or feature request), the triage team will
review and comment on the submission, typically within a few business review and comment on the submission, typically within a few business
days. Use the `ACRN hypervisor issues`_ list to track the status of days. Use the `ACRN hypervisor issues`_ list to track the status of your
your submitted issues as well, or to add additional comments. submitted issues as well, or to add additional comments.
.. _Contribution Tools: .. _Contribution Tools:
@ -169,21 +168,20 @@ Contribution Tools and Git Setup
Git-Send-Email Git-Send-Email
============== ==============
If you'll be submitting code patches, you may need to install If you'll be submitting code patches, you may need to install the git-email
the git-email package for easier patch submission. On Ubuntu, package for easier patch submission. On Ubuntu, for example, use::
for example use::
$ sudo apt install git-email $ sudo apt install git-email
and then configure Git` with your SMTP server information as and then configure Git with your SMTP server information as described in the
described in the `Git send-email documentation`_. `Git send-email documentation`_.
Signed-Off-By Signed-Off-By
============= =============
The name in the commit message ``Signed-off-by:`` line and your email must The name in the commit message ``Signed-off-by:`` line and your email address
match the change authorship information. Make sure your :file:`.gitconfig` must match the change authorship information. Make sure that your
is set up correctly by using: :file:`.gitconfig` is set up correctly by using:
.. code-block:: none .. 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 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 Tracked-On: #issue-number line to your commit message together with the
issue number, for example:: issue number. For example::
Tracked-On: #1420 Tracked-On: #1420
@ -203,7 +201,7 @@ Coding Style
************ ************
Use these coding guidelines to ensure that your development complies with the 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: .. _Linux kernel coding style:
https://kernel.org/doc/html/latest/process/coding-style.html 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 * Add braces to every ``if`` and ``else`` body, even for single-line code
blocks. blocks.
* Use spaces instead of tabs to align comments after declarations, as needed. * 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. 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 * The line limit is 120 columns instead of 80 columns. Note that tabs are
8-column wide. 8-column wide.
You can use *checkpatch* from Linux kernel to check the compliance. ACRN You can use *checkpatch* from the Linux kernel to check the compliance. ACRN
maintains a :acrn_file:`.checkpatch.conf <.checkpatch.conf>` file maintains a :acrn_file:`.checkpatch.conf <.checkpatch.conf>` file that
that customizes the script to stop warnings on customizes the script to stop warnings on the exceptions above. Invoke
the exceptions above. Invoke *checkpatch* with the root of ``acrn-hypervisor`` *checkpatch* with the root of the ``acrn-hypervisor`` repository as the
repository as the current working directory to make the configurations current working directory to make the configurations effective.
effective.
.. _Contribution workflow: .. _Contribution workflow:
Contribution Workflow Contribution Workflow
********************* *********************
One general practice we encourage, is to make small, One general practice we encourage, is to make small, controlled changes. This
controlled changes. This practice simplifies review, makes merging and practice simplifies review, makes merging and rebasing easier, and keeps the
rebasing easier, and keeps the change history clear and clean. change history clear and clean.
When contributing to project ACRN, it is also important you provide as much When contributing to project ACRN, it is also important that you provide as
information as you can about your change, update appropriate documentation, much information as you can about your change, update appropriate
and test your changes thoroughly before submitting. documentation, and test your changes thoroughly before submitting.
Documentation changes should also be checked for technical accuracy, Documentation changes should also be checked for technical accuracy,
spelling, grammar, and clarity and that the :ref:`doc_guidelines` are 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 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. for details.
The general GitHub workflow used by project ACRN developers uses a combination of The general GitHub workflow used by project ACRN developers uses a combination
command line Git commands and browser interaction with GitHub. As it is with of command-line Git commands and browser interaction with GitHub. As it is
Git, there are multiple ways of getting a task done. We'll describe a typical with Git, there are multiple ways of getting a task done. We'll describe a
workflow here for the acrn-hypervisor repo, which includes the typical workflow here for the acrn-hypervisor repo, which includes the
source files for the hypervisor, devicemodel, and documentation. source files for the hypervisor, devicemodel, and documentation.
.. important:: Both code and documentation changes follow the same steps .. 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 $ git remote -v
#. Create a topic branch (off of the main branch) for your work (if you're addressing #. Create a topic branch (off of the main branch) for your work (if you're
an issue, we suggest including the issue number in the branch name):: addressing an issue, we suggest including the issue number in the
branch name)::
$ git checkout master $ git checkout master
$ git checkout -b fix_comment_typo $ git checkout -b fix_comment_typo
@ -315,34 +314,34 @@ source files for the hypervisor, devicemodel, and documentation.
$ git commit -s $ git commit -s
The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
message. Your commit will be rejected without this line that indicates your message. Your commit will be rejected without this line that indicates
agreement with the `DCO`_. See the `Commit Guidelines`_ section your agreement with the `DCO`_. See the `Commit Guidelines`_ section
below for specific guidelines for writing your commit messages. 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 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 ``Tracked-On: #issue-number`` line to your commit message together with the
with the issue number, for example:: issue number. For example::
Tracked-On: #1420 Tracked-On: #1420
If only **documentation changes** are made, your PR can be submitted If only **documentation changes** are made, you can submit your PR
without review on the ACRN developer mailing list, so you can skip without a review on the ACRN developer mailing list, so you can skip
directly to step 9. directly to step 9.
8. As mentioned earlier, all **code changes** must first be reviewed and 8. As mentioned earlier, all **code changes** must first be reviewed and
approved via the developer mailing list. This review process is approved via the developer mailing list. You start this review process by
started by sending a patch file for each commit, as created by the ``git sending a patch file for each commit, as created by the
format-patch`` command. For example if your change is contained in one ``git format-patch`` command. For example, if your change is contained in
commit, create a patch file (in ``/tmp``, or some other location) with one commit, create a patch file (in ``/tmp``, or some other location) with
the command:: the command::
$ git format-patch -o /tmp/ -1 $ git format-patch -o /tmp/ -1
Then email the generated ``.patch`` file(s) to the ACRN developer Then email the generated ``.patch`` file(s) to the ACRN developer
mailing list, acrn-dev@lists.projectacrn.org using the ``git mailing list, acrn-dev@lists.projectacrn.org using the ``git send-email``
send-email`` command. (See the `Git send-email documentation`_ command. (See the `Git send-email documentation`_ for details.
for details. For example:: For example::
$ git send-email /tmp/000*.patch --to acrn-dev@lists.projectacrn.org $ 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>`_. `ACRN developer mailing list archive <https://lists.projectacrn.org/g/acrn-dev>`_.
After all review issues have been resolved, amend your commit with After all review issues have been resolved, amend your commit with
necessary changes and also update the commit message with approvals necessary changes, and also update the commit message with approvals given
given in the mailing list discussion by adding in the mailing list discussion by adding **Reviewed-by:** and **Acked-by:**
**Reviewed-by:** and **Acked-by:** tags. tags.
You can then proceed to the next step and submit a Git pull request You can then proceed to the next step and submit a Git pull request
to the repo. to the repo.
@ -362,48 +361,49 @@ source files for the hypervisor, devicemodel, and documentation.
$ git push origin fix_comment_typo $ git push origin fix_comment_typo
#. In your web browser, go to your personal forked repo and click on the Compare & pull #. In your web browser, go to your personal forked repo and click the
request button for the branch you just worked on and you want to Compare & pull request button for the branch you just worked on and want to
submit to the upstream ACRN repo. submit to the upstream ACRN repo.
#. Review the pull request changes, and verify that you are opening a pull request #. Review the pull request changes, and verify that you are opening a pull
for the appropriate branch. The title and message from your commit message should request for the appropriate branch. The title and message from your commit
appear as well. message should appear as well.
#. GitHub will assign one or more suggested reviewers (based on the CODEOWNERS file #. GitHub will assign one or more suggested reviewers (based on the CODEOWNERS
in the repo). If you are a project member, you can select additional reviewers file in the repo). If you are a project member, you can select additional
now too. If no reviewers are selected, the ACRN triage team will reviewers now too. If no reviewers are selected, the ACRN triage team will
assign reviewers as appropriate. 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 For code changes, this review should be cursory since any issues were
handled via the mailing list review. handled via the mailing list review. Email will be sent as review comments
Email will be sent as review comments are made, or you can check on your are made, or you can check on your pull request at
pull request at https://github.com/projectacrn/acrn-hypervisor/pulls. https://github.com/projectacrn/acrn-hypervisor/pulls.
#. While you're waiting for your pull request to be accepted and merged, you can #. While you're waiting for your pull request to be accepted and merged, you
create another branch to work on another issue. (Be sure to make your new branch can create another branch to work on another issue. (Be sure to make your
off of the main branch and not the previous branch.):: new branch off of the main branch and not the previous branch)::
$ git checkout master $ git checkout master
$ git checkout -b fix_another_issue $ 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 #. If reviewers request changes to your patch, you can interactively rebase
commit(s) to fix review issues. In your development repo, make the one or more commits to fix review issues. In your development repo, make
needed changes on the branch you made the initial submission:: the needed changes on the branch that you initially submitted::
$ git checkout fix-comment-typo $ git checkout fix-comment-typo
make the requested changes, and then:: Make the requested changes, and then::
$ git fetch --all $ git fetch --all
$ git rebase --ignore-whitespace upstream/master $ git rebase --ignore-whitespace upstream/master
This is an important step to make sure your changes are properly This is an important step to make sure that your changes are properly
merged with changes from other developers that may have happened while you merged with changes from other developers that may have occurred while you
were working on your changes. were working on your changes.
The ``--ignore-whitespace`` option stops ``git apply`` (called by The ``--ignore-whitespace`` option stops ``git apply`` (called by
rebase) from changing any whitespace characters (such as spaces, tabs, and rebase) from changing any whitespace characters (such as spaces, tabs, and
newlines). If any merging issues are detected you can address them 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> $ git rebase -i <offending-commit-id>
In the interactive rebase editor, replace pick with edit to select a specific In the interactive rebase editor, replace pick with edit to select a
commit (if there's more than one in your pull request), or remove the line to specific commit (if there's more than one in your pull request), or remove
delete a commit entirely. Then edit files to fix the issues in the review. 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 As before, inspect and test your changes. When ready, continue the
patch submission:: patch submission::
@ -421,14 +422,15 @@ source files for the hypervisor, devicemodel, and documentation.
$ git add [file(s)] $ git add [file(s)]
$ git rebase --continue $ 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 $ git push --force origin fix_comment_typo
By force pushing your update, your original pull request will be updated with By force pushing your update, you ensure that your original pull request
your changes so you won't need to resubmit the 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. or acrn-documentation repos.
@ -437,10 +439,10 @@ Commit Guidelines
Changes are submitted as Git commits. Each commit message must contain: 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 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 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 (If you're updating an existing file, you can use
``git log <filename>`` to see what developers used as the prefix for ``git log <filename>`` to see what developers used as the prefix for
previous patches of this file.) previous patches of this file.)
@ -456,18 +458,18 @@ Changes are submitted as Git commits. Each commit message must contain:
Tracked-On: #issue-number Tracked-On: #issue-number
All changes and topics sent to GitHub must be well-formed, as described above. All changes and topics sent to GitHub must be well-formed, as described above.
Commit Message Body Commit Message Body
=================== ===================
When editing the commit message, please briefly explain what your change 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:: .. warning::
An empty change summary body is not permitted. Even for trivial changes, please An empty change summary body is not permitted. Even for trivial changes,
include a summary body in the commit message. please include a summary body in the commit message.
The description body of the commit message must include: 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 * **what** assumptions were made, and
* **how** you know it works -- for example, which tests you ran. * **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>`__. `changelog <https://github.com/projectacrn/acrn-hypervisor/commits/master>`__.
Other Commit Expectations Other Commit Expectations
@ -489,8 +492,8 @@ Other Commit Expectations
logically self-contained. Unrelated changes should be submitted as logically self-contained. Unrelated changes should be submitted as
separate commits. separate commits.
* You may submit pull request RFCs (requests for comments) to send work * You may submit pull-request RFCs (requests for comments) to send work
proposals, progress snapshots of your work, or to get early feedback on 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. features or changes that will affect multiple areas in the code base.
Identifying Contribution Origin 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 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 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 cases where the file is an original to acrn-hypervisor, the commit message
include the following ("Original" is the assumption if no Origin tag is should include the following ("Original" is the assumption if no Origin tag is
present):: present)::
Origin: Original Origin: Original
In cases where the file is imported from an external project, the commit 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 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, purpose, and whether the file will be maintained by the acrn-hypervisor
(whether or not project ACRN will contain a localized branch or if project (whether project ACRN will contain a localized branch or whether it is
it is a downstream copy). a downstream copy).
For example, a copy of a locally maintained import:: 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 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 view this content either in its raw form as ``.rst`` markup files, or (with
Sphinx installed) they can build the documentation using the Makefile Sphinx installed) they can build the documentation using the Makefile
(on Linux systems) to (on Linux systems) to generate the HTML content. The HTML content can then be
generate the HTML content. The HTML content can then be viewed using a viewed using a web browser. This same ``.rst`` content is also fed into the
web browser. This same ``.rst`` content is also fed into the
`Project ACRN documentation`_ website. `Project ACRN documentation`_ website.
You can read details about `reStructuredText`_ You can read details about `reStructuredText`_ and about `Sphinx extensions`_
and about `Sphinx extensions`_ from their respective websites. from their respective websites.
.. _Sphinx extensions: https://www.sphinx-doc.org/en/stable/contents.html .. _Sphinx extensions: https://www.sphinx-doc.org/en/stable/contents.html
.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html .. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
@ -28,19 +27,19 @@ you're reading.
Headings Headings
******** ********
Document sections are identified through their heading titles, Document sections are identified through their heading titles, indicated with
indicated with an underline below the title text. (While reST allows an underline below the title text. (While reST allows use of both and
use of both and overline and matching underline to indicate a heading, overline and matching underline to indicate a heading, we use only an
we only use an underline indicator for headings.) For consistency in underline indicator for headings.) For consistency in our documentation, we
our documentation, we define the order of characters used to indicate define the order of characters used to indicate the nested levels in the
the nested table of contents levels: table of contents:
* Use ``#`` for the Document title underline character * Use ``#`` for the Document title underline character
* Use ``*`` for the First sub-section heading level * Use ``*`` for the First sub-section heading level
* Use ``=`` for the Second sub-section heading level * Use ``=`` for the Second sub-section heading level
* Use ``-`` for the Third 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. 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*`` so ``*this is italics*`` ( *this is italics*) while ``* this isn't*``
(* this isn't*). (* this isn't*).
If asterisks or back quotes appear in running text and could be confused with If an asterisk or back quote appears in running text and could be confused
inline markup delimiters, you can eliminate the confusion by adding a with inline markup delimiters, you can eliminate the confusion by adding a
backslash (``\``) before it. backslash (``\``) before it.
Lists Lists
***** *****
For bullet lists, place an asterisk (``*``) or hyphen (``-``) at For bullet lists, place an asterisk (``*``) or hyphen (``-``) at the start of
the start of a paragraph and indent continuation lines with two a paragraph and indent continuation lines with two spaces.
spaces.
The first item in a list (or sublist) must have a blank line before it The first item in a list (or sublist) must have a blank line before it and
and should be indented at the same level as the preceding paragraph should be indented at the same level as the preceding paragraph (and not
(and not indented itself). indented itself).
For numbered lists For numbered lists
start with a ``1.`` or ``a)`` for example, and continue with autonumbering by 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 #. And a second item back in the containing list. No blank line
needed, but it wouldn't hurt for readability. needed, but it wouldn't hurt for readability.
Definition lists (with a term and its definition) are a convenient way Definition lists (with one or more terms and their definition) are a
to document a word or phrase with an explanation. For example, this reST convenient way to document a word or phrase with an explanation. For example,
content: this reST content:
.. code-block:: rest .. code-block:: rest
@ -165,11 +163,11 @@ Would be rendered as:
Multi-Column Lists Multi-Column Lists
****************** ******************
If you have a long bullet list of items, where each item is short, you If you have a long bullet list of items, where each item is short, you can
can indicate the list items should be rendered in multiple columns with indicate that the list items should be rendered in multiple columns with a
a special ``.. rst-class:: rst-columns`` directive. The directive will special ``.. rst-class:: rst-columns`` directive. The directive will apply to
apply to the next non-comment element (e.g., paragraph), or to content the next non-comment element (e.g., paragraph) or to content indented under
indented under the directive. For example, this unordered list:: the directive. For example, this unordered list::
.. rst-class:: rst-columns .. 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`` A maximum of three columns will be displayed if you use ``rst-columns``
(or ``rst-columns3``), and two columns for ``rst-columns2``. The number (or ``rst-columns3``), and two columns for ``rst-columns2``. The number
of columns displayed can be reduced of columns displayed can be reduced based on the available width of the
based on the available width of the display window, reducing to one display window, reducing to one column on narrow (phone) screens if necessary.
column on narrow (phone) screens if necessary. We've deprecated use of
the ``hlist`` directive because it misbehaves on smaller screens. .. note:: We've deprecated use of the ``hlist`` directive because it
misbehaves on smaller screens.
Tables Tables
****** ******
There are a few ways to create tables, each with their limitations or There are a few ways to create tables, each with their limitations or quirks.
quirks. `Grid tables `Grid tables
<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#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 offer the most capability for defining merged rows and columns, but are
hard to maintain:: hard to maintain::
@ -286,9 +285,9 @@ File Names and Commands
*********************** ***********************
Sphinx extends reST by supporting additional inline markup elements (called Sphinx extends reST by supporting additional inline markup elements (called
"roles") used to tag text with special "roles") used to tag text with special meanings and enable output formatting.
meanings and allow style output formatting. (You can refer to the `Sphinx Inline Markup`_ (You can refer to the `Sphinx Inline Markup`_ documentation for the full
documentation for the full list). list).
For example, there are roles for marking :file:`filenames` For example, there are roles for marking :file:`filenames`
(``:file:`name```) and command names such as :command:`make` (``: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```. 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 For references to files that are in the ACRN Hypervisor GitHub tree, you can
role can be used that creates a hyperlink to that file. For example a 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 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 using ``:acrn_file:`doc/developer-guides/doc_guidelines.rst```, which will
up as :acrn_file:`doc/developer-guides/doc_guidelines.rst`, a link to 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 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 ``:acrn_raw:`doc/developer-guides/doc_guidelines.rst``` role that will link
to the “raw” uninterpreted file, to the “raw” uninterpreted file,
:acrn_raw:`doc/developer-guides/doc_guidelines.rst` file. (Click :acrn_raw:`doc/developer-guides/doc_guidelines.rst` file. (Click these links
on these links to see the difference.) to see the difference.)
.. _internal-linking: .. _internal-linking:
Internal Cross-Reference 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: notation:
.. code-block:: rest .. code-block:: rest
@ -324,13 +323,12 @@ which renders as,
refer to the `internal-linking`_ page refer to the `internal-linking`_ page
Note the use of a trailing Note the use of a trailing underscore to indicate an outbound link. In this
underscore to indicate an outbound link. In this example, the label was example, the label was added immediately before a heading, so the text that's
added immediately before a heading, so the text that's displayed is the displayed is the heading text itself.
heading text itself.
With Sphinx however, we can create With Sphinx however, we can create link-references to any tagged text within
link-references to any tagged text within the project documentation. the project documentation.
Target locations within documents are defined with a label directive: 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: .. _my label name:
Note the leading underscore indicating an inbound link. Note the leading underscore indicating an inbound link. The content
The content immediately following immediately following this label is the target for a ``:ref:`my label name```
this label is the target for a ``:ref:`my label name``` reference from anywhere within the documentation set. The label **must** be
reference from anywhere within the documentation set. added immediately before a heading so that there's a natural phrase to show
The label **must** be added immediately before a heading so there's a when referencing this label (e.g., the heading text).
natural phrase to show when referencing this label (e.g., the heading
text).
This is the same directive used to This is the same directive used to define a label that's a reference to a URL:
define a label that's a reference to a URL:
.. code-block:: rest .. code-block:: rest
.. _Hypervisor Wikipedia Page: .. _Hypervisor Wikipedia Page:
https://en.wikipedia.org/wiki/Hypervisor https://en.wikipedia.org/wiki/Hypervisor
To enable easy cross-page linking within the site, each file should have To enable easy cross-page linking within the site, each file should have a
a reference label before its title so it can reference label before its title so that it can be referenced from another
be referenced from another file. These reference labels must be unique file. These reference labels must be unique across the whole site, so generic
across the whole site, so generic names such as "samples" should be names such as "samples" should be avoided. For example, the top of this
avoided. For example the top of this document's ``.rst`` file is: document's ``.rst`` file is:
.. code-block:: rst .. code-block:: rst
@ -368,33 +362,34 @@ avoided. For example the top of this document's ``.rst`` file is:
Documentation Guidelines Documentation Guidelines
######################## ########################
Other ``.rst`` documents can link to this document using the ``:ref:`doc_guidelines``` tag and Other ``.rst`` documents can link to this document using the
it will show up as :ref:`doc_guidelines`. This type of internal cross reference works across ``:ref:`doc_guidelines``` tag, and it will appear as :ref:`doc_guidelines`.
multiple files, and the link text is obtained from the document source so if the title changes, This type of internal cross-reference works across multiple files. The link
the link text will update as well. 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 There may be times when you'd like to change the link text that's shown in the
in the generated document. In this case, you can specify alternate generated document. In this case, you can specify alternate text using
text using ``:ref:`alternate text <doc_guidelines>``` (renders as ``:ref:`alternate text <doc_guidelines>``` (renders as
:ref:`alternate text <doc_guidelines>`). :ref:`alternate text <doc_guidelines>`).
Non-ASCII Characters Non-ASCII Characters
******************** ********************
You can insert non-ASCII characters such as a Trademark symbol (|trade|), You can insert non-ASCII characters such as a Trademark symbol (|trade|) by
by using the notation ``|trade|``. (It's also allowed to use the UTF-8 using the notation ``|trade|``. (It's also allowed to use the UTF-8
characters directly.) characters directly.) Available replacement names are defined in an include
Available replacement names are defined in an include file used during the Sphinx processing file used during the Sphinx processing of the reST files. The names of these
of the reST files. The names of these replacement characters are the same as used in HTML replacement characters are the same as those used in HTML entities to insert
entities used to insert characters in HTML, e.g., \&trade; and are defined in the special characters such as \&trade; and are defined in the file
file ``sphinx_build/substitutions.txt`` as listed here: ``sphinx_build/substitutions.txt`` as listed here:
.. literalinclude:: ../substitutions.txt .. literalinclude:: ../substitutions.txt
:language: rst :language: rst
We've kept the substitutions list small but others can be added as We've kept the substitutions list small but you can add others as needed by
needed by submitting a change to the ``substitutions.txt`` file. submitting a change to the ``substitutions.txt`` file.
Code and Command Examples Code and Command Examples
************************* *************************
@ -417,8 +412,8 @@ For example:
u32_t data; u32_t data;
} __packed; } __packed;
Note the blank line between the ``code-block`` directive and the first Note that there is a blank line between the ``code-block`` directive and the
line of the code-block body, and the body content is indented three 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). spaces (to the first non-blank space of the directive name).
This would be rendered as: This would be rendered as:
@ -434,10 +429,9 @@ This would be rendered as:
} __packed; } __packed;
You can specify other languages for the ``code-block`` directive, You can specify other languages for the ``code-block`` directive, including
including ``c``, ``python``, and ``rst``, and also ``console``, ``c``, ``python``, and ``rst``, and also ``console``, ``bash``, or ``shell``.
``bash``, or ``shell``. If you want no syntax highlighting, use the If you want no syntax highlighting, specify ``none``. For example:
language ``none``, for example:
.. code-block:: rest .. code-block:: rest
@ -453,12 +447,13 @@ Would display as:
This would be a block of text styled with a background This would be a block of text styled with a background
and box, but with no syntax highlighting. 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 paragraph with a double colon (``::``) and indent the code block content
by three spaces. On output, only one colon will be shown. The by three spaces. On output, only one colon will appear.
highlighting package makes a best guess at the type of content in the
block and highlighting purposes. This can lead to some odd .. note:: The highlighting package makes a best guess at the type of content
highlighting in the generated output. in the block for highlighting purposes. This can lead to some odd
highlighting in the generated output.
Images Images
****** ******
@ -476,21 +471,20 @@ or if you'd like to add an image caption, use::
Caption for the figure Caption for the figure
The file name specified is relative to the document source file, The file name specified is relative to the document source file, and we
and we recommend putting images into an ``images`` folder where the document recommend putting images into an ``images`` folder where the document source
source is found. The usual image formats handled by a web browser are is found. The usual image formats handled by a web browser are supported:
supported: JPEG, PNG, GIF, and SVG. Keep the image size only as large JPEG, PNG, GIF, and SVG. Keep the image size only as large as needed,
as needed, generally at least 500 px wide but no more than 1000 px, and generally at least 500 px wide but no more than 1000 px, and no more than
no more than 250 KB unless a particularly large image is needed for 250 KB unless a particularly large image is needed for clarity.
clarity.
Tabs, Spaces, and Indenting Tabs, Spaces, and Indenting
*************************** ***************************
Indenting is significant in reST file content, and using spaces is Indenting is significant in reST file content, and using spaces is preferred.
preferred. Extra indenting can (unintentionally) change the way content Extra indenting can (unintentionally) change the way content is rendered, too.
is rendered too. For lists and directives, indent the content text to For lists and directives, indent the content text to the first non-blank space
the first non-blank space in the preceding line. For example: in the preceding line. For example:
.. code-block:: rest .. 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 The text within a directive block should align with the
first character of the directive name. first character of the directive name.
Keep the line length for documentation less than 80 characters to make Keep the line length for documentation less than 80 characters to make it
it easier for reviewing in GitHub. Long lines because of URL references easier for reviewing in GitHub. Long lines due to URL references are an
are an allowed exception. allowed exception.
Drawings 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`` directive::
.. image:: ../images/ACRNlogo.png .. image:: ../images/ACRNlogo.png
@ -524,10 +518,9 @@ This results in the image being placed in the document:
:align: center :align: center
Alternatively, use the ``.. figure`` directive to include a picture with Alternatively, use the ``.. figure`` directive to include a picture with
a caption and automatic figure numbering for a caption and automatic figure numbering for your image, (so that you can say
your image, (so you can say see :numref:`acrn-logo-figure`, by using the see :numref:`acrn-logo-figure`, by using the notation
notation ``:numref:`acrn-logo-figure``` and specifying the name of ``:numref:`acrn-logo-figure``` and specifying the name of figure)::
figure)::
.. figure:: ../images/ACRNlogo.png .. figure:: ../images/ACRNlogo.png
:align: center :align: center
@ -542,17 +535,17 @@ figure)::
Caption for the figure Caption for the figure
We've also included the ``graphviz`` Sphinx extension to let you use a text We've also included the ``graphviz`` Sphinx extension to enable you to use a
description language to render drawings. See :ref:`graphviz-examples` for more text description language to render drawings. For more information, see
information. :ref:`graphviz-examples`.
Alternative Tabbed Content Alternative Tabbed Content
************************** **************************
Instead of creating multiple documents with common material except for Instead of creating multiple documents with common material except for some
some specific sections, you can write one document and provide alternative specific sections, you can write one document and provide alternative content
content to the reader via a tabbed interface. When the reader clicks on to the reader via a tabbed interface. When the reader clicks on a tab, the
a tab, the content for that tab is displayed, for example:: content for that tab is displayed. For example::
.. tabs:: .. tabs::
@ -584,7 +577,7 @@ will display as:
Oranges are orange. 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: changes all tabs with the same name throughout the page. For example:
.. tabs:: .. 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 <https://github.com/djungelorm/sphinx-tabs>`_ extension that's included
in the ACRN (requirements.txt) setup. Within a tab, you can have most in the ACRN (requirements.txt) setup. Within a tab, you can have most
any content *other than a heading* (code-blocks, ordered and unordered any content *other than a heading* (code-blocks, ordered and unordered
lists, pictures, paragraphs, and such). You can read more about lists, pictures, paragraphs, and such). You can read more about sphinx-tabs
sphinx-tabs from the link above. from the link above.
Instruction Steps Instruction Steps
***************** *****************
A numbered instruction steps style makes it A numbered instruction steps style makes it easy to create tutorial guides
easy to create tutorial guides with clearly identified steps. Add with clearly identified steps. Add the ``.. rst-class:: numbered-step``
the ``.. rst-class:: numbered-step`` directive immediately before a directive immediately before a second-level heading (by project convention, a
second-level heading (by project convention, a heading underlined with heading underlined with asterisks ``******``, and it will be displayed as a
asterisks ``******``, and it will be displayed as a numbered step, numbered step, sequentially numbered within the document. (Second-level
sequentially numbered within the document. (Second-level headings headings without this ``rst-class`` directive will not be numbered.)
without this ``rst-class`` directive will not be numbered.) For example:: For example::
.. rst-class:: numbered-step .. rst-class:: numbered-step
@ -644,10 +637,10 @@ without this ``rst-class`` directive will not be numbered.) For example::
First Instruction Step First Instruction Step
********************** **********************
This is the first instruction step material. You can do the usual paragraphs and This is the first instruction step material. You can do the usual paragraph
pictures as you'd use in normal document writing. Write the heading to and pictures as you'd use in normal document writing. Write the heading to be
be a summary of what the step is (the step numbering is automated so you a summary of what the step is (the step numbering is automated so you can move
can move steps around easily if needed). steps around easily if needed).
.. rst-class:: numbered-step .. 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 We support using the Sphinx `graphviz extension`_ for creating simple
graphs and line drawings using the dot language. The advantage of using 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. can be edited and maintained in the repo along with the documentation.
.. _graphviz extension: http://graphviz.gitlab.io .. _graphviz extension: http://graphviz.gitlab.io
These source ``.dot`` files are generally kept separate from the document itself, These source ``.dot`` files are generally kept separate from the document
and included by using a graphviz directive: itself, and included by using a graphviz directive:
.. code-block:: none .. code-block:: none
@ -20,7 +20,7 @@ and included by using a graphviz directive:
:align: center :align: center
:caption: ACRN Hypervisor Boot Flow :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 .. literalinclude:: images/boot-flow.dot
@ -32,16 +32,15 @@ and the generated output would appear as this:
:caption: ACRN Hypervisor Boot Flow :caption: ACRN Hypervisor Boot Flow
Let's look at some more examples and then we'll get into more details Let's look at some more examples and then we'll get into more details about
about the dot language and drawing options. the dot language and drawing options.
Simple Directed Graph Simple Directed Graph
********************* *********************
For simple drawings with shapes and lines, you can put the graphviz For simple drawings with shapes and lines, you can put the graphviz commands
commands in the content block for the directive. For example, for a in the content block for the directive. For example, for a simple directed
simple directed graph (digraph) with two nodes connected by an arrow, graph (digraph) with two nodes connected by an arrow, you can write:
you can write:
.. code-block:: none .. code-block:: none
@ -71,8 +70,8 @@ image placement on the page (centered):
.. graphviz:: images/circle-square.dot .. graphviz:: images/circle-square.dot
:align: center :align: center
You can use the `standard HTML color names`_ or use RGB values for You can use the `standard HTML color names`_ or use RGB values for colors,
colors, as shown. as shown.
.. _standard HTML color names: .. _standard HTML color names:
https://www.w3schools.com/colors/colors_hex.asp https://www.w3schools.com/colors/colors_hex.asp
@ -80,9 +79,9 @@ colors, as shown.
Adding Edge Labels Adding Edge Labels
****************** ******************
Here's an example of a drawing with labels on the edges (arrows) Here's an example of a drawing with labels on the edges (arrows) between
between nodes. We also show how to change the default attributes for all nodes. We also show how to change the default attributes for all nodes and
nodes and edges within this graph: edges within this graph:
.. literalinclude:: images/node-shape-edges.dot .. 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 :align: center
Note that you can also specify the horizontal alignment of text using escape 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, sequences ``\n``, ``\l``, and ``\r``, which divide the label into lines that
left-justified, and right-justified, respectively. are centered, left-justified, and right-justified, respectively.
Finite-State Machine 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 Guest -> Hypervisor Attack
========================== ==========================
ACRN always enables EPT for all guests (Service VM and User VM), thus a malicious ACRN always enables EPT for all guests (Service VM and User VM); thus a
guest can directly control guest PTEs to construct L1TF-based attack malicious guest can directly control guest PTEs to construct an L1TF-based
to hypervisor. Alternatively if ACRN EPT is not sanitized with some attack to the hypervisor. Alternatively, if ACRN EPT is not sanitized with
PTEs (with present bit cleared, or reserved bit set) pointing to valid 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. 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 A special aspect of L1TF in the context of virtualization is symmetric
multithreading (SMT), e.g. Intel |reg| Hyper-threading Technology. multithreading (SMT), e.g. Intel |reg| Hyper-threading Technology.
Logical processors on the affected physical cores share the L1 Data Cache 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. (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 which a malicious guest running on one logical processor can attack the data
is brought into L1D by the context which runs on the sibling thread of brought into L1D by the context that runs on the sibling thread of the same
the same physical core. This context can be any code in hypervisor. physical core. This context can be any code in the hypervisor.
Guest -> Guest Attack 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. e.g. whether CPU partitioning is used, whether Hyper-threading is on, etc.
If CPU partitioning is enabled (default policy in ACRN), there is If CPU partitioning is enabled (the default policy in ACRN), there is a 1:1
1:1 mapping between vCPUs and pCPUs i.e. no sharing of pCPU. There mapping between vCPUs and pCPUs; that is, there is no pCPU sharing. There
may be an attack possibility when Hyper-threading is on, where may be an attack possibility when Hyper-threading is on, where logical
logical processors of the same physical core may be allocated to two processors of the same physical core may be allocated to two different
different guests. Then one guest may be able to attack the other guest guests. Then one guest may be able to attack the other guest on a sibling
on sibling thread due to shared L1D. thread due to shared L1D.
If CPU sharing is enabled (not supported now), two VMs may share If CPU sharing is enabled (not supported now), two VMs may share the same
same pCPU thus next VM may steal information in L1D which comes pCPU; thus the next VM may steal information in L1D that comes from activity
from activity of previous VM on the same pCPU. of the previous VM on the same pCPU.
Normal_world -> Secure_world Attack Normal_world -> Secure_world Attack
=================================== ===================================
ACRN supports Android guest, which requires two running worlds ACRN supports Android guest, which requires two running worlds (normal world
(normal world and secure world). Two worlds run on the same CPU, and secure world). Two worlds run on the same CPU, and world switch is
and world switch is conducted on demand. It could be possible for conducted on demand. It could be possible for normal world to construct an
normal world to construct an L1TF-based stack to secure world, L1TF-based stack to secure world, breaking the security model as expected by
breaking the security model as expected by Android guest. the Android guest.
Affected Processors Affected Processors
=================== ===================
L1TF affects a range of Intel processors, but Intel Atom |reg| 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 supports only Apollo Lake. Support for other core-based platforms is
planned, so we still need a mitigation plan in ACRN. 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 IA32_ARCH_CAPABILITIES MSR are not susceptible to the L1TF
speculative execution side channel. 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 L1TF Mitigation in ACRN
*********************** ***********************
Use the latest microcode, which mitigates SMM and Intel SGX cases Use the latest microcode, which mitigates SMM and Intel SGX cases while also
while also providing necessary capability for VMM to use for further providing necessary capability for VMM to use for further mitigation.
mitigation.
ACRN will check the platform capability based on `CPUID enumeration 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) with MSR_IA32_ARCH_CAPABILITIES), L1D_FLUSH capability(CPUID.07H.EDX.28)
must be supported. must be supported.
.. _CPUID enumeration and architectural MSR: .. _CPUID enumeration and architectural MSR:
https://software.intel.com/security-software-guidance/insights/deep-dive-cpuid-enumeration-and-architectural-msrs 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 the mitigations below will be implemented in ACRN, and not all of
not all of them apply to a specific ACRN deployment. Check the them apply to a specific ACRN deployment. Check the 'Mitigation Status'_ and
'Mitigation Status'_ and 'Mitigation Recommendations'_ sections 'Mitigation Recommendations'_ sections for guidance.
for guidance.
L1D Flush on VMENTRY L1D Flush on VMENTRY
==================== ====================
ACRN may optionally flush L1D at VMENTRY, which ensures no ACRN may optionally flush L1D at VMENTRY, which ensures that no sensitive
sensitive information from hypervisor or previous VM revealed information from the hypervisor or previous VM is revealed to the current VM
to current VM (in case of CPU sharing). (in case of CPU sharing).
Flushing the L1D evicts not only the data which should not be Flushing the L1D evicts not only the data that should not be accessed by a
accessed by a potentially malicious guest, it also flushes the potentially malicious guest, it also flushes the guest data. Flushing the
guest data. Flushing the L1D has a performance impact as the L1D has a performance impact as the processor has to bring the flushed guest
processor has to bring the flushed guest data back into the L1D, data back into the L1D, and the actual overhead is proportional to the
and actual overhead is proportional to the frequency of vmentry. frequency of vmentry.
Due to such performance reason, ACRN provides a config option Due to such performance reasons, ACRN provides a config option
(L1D_FLUSH_VMENTRY) to enable/disable L1D flush during (L1D_FLUSH_VMENTRY) to enable/disable L1D flush during VMENTRY. By default,
VMENTRY. By default this option is disabled. this option is disabled.
EPT Sanitization EPT Sanitization
================ ================
EPT is sanitized to avoid pointing to valid host memory in PTEs EPT is sanitized to avoid pointing to valid host memory in PTEs that have
which has present bit cleared or reserved bits set. the present bit cleared or reserved bits set.
For non-present PTEs, ACRN currently set PFN bits to ZERO, which For non-present PTEs, ACRN currently sets PFN bits to ZERO, which means
means page ZERO might fall into risk if containing security info. that page ZERO might fall into risk if it contains security information.
ACRN reserves page ZERO (0~4K) from page allocator thus page ZERO ACRN reserves page ZERO (0~4K) from page allocator; thus page ZERO won't
won't be used by anybody for valid usage. This sanitization logic be used by anybody for a valid purpose. This sanitization logic is always
is always enabled on all platforms. enabled on all platforms.
ACRN hypervisor doesn't set reserved bits in any EPT entry. 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. non-interesting for an attacker without deep inspection of the code.
But obviously, the most import secret data in ACRN is the physical platform 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 seed generated from CSME and virtual seeds derived from that platform seed.
platform seed. They are critical secrets to serve for guest keystore or They are critical secrets to serve for a guest keystore or other security
other security usage, e.g. disk encryption, secure storage. usage, e.g. disk encryption, secure storage.
If the critical secret data in ACRN is identified, then such If the critical secret data in ACRN is identified, then such data can be put
data can be put into un-cached memory. As the content will into un-cached memory. As the content will never go to L1D, it is immune to
never go to L1D, it is immune to L1TF attack. L1TF attack.
For example, after getting the physical seed from CSME, before any guest For example, after getting the physical seed from CSME, before any guest
starts, ACRN can pre-derive all the virtual seeds for all the starts, ACRN can pre-derive all the virtual seeds for all the guests and
guests and then put these virtual seeds into uncached memory, then put these virtual seeds into uncached memory, and at the same time
at the same time flush & erase physical seed. flush and erase the physical seed.
If all security data are identified and put in uncached If all security data are identified and put in uncached memory in a specific
memory in a specific deployment, then it is not necessary to deployment, it is not necessary to prevent guest -> hypervisor attack,
prevent guest -> hypervisor attack, since there is nothing because there is nothing useful to be attacked.
useful to be attacked.
However if such 100% identification is not possible, user should However, if such 100% identification is not possible, the user should
consider other mitigation options to protect hypervisor. consider other mitigation options to protect the hypervisor.
L1D Flush on World Switch L1D Flush on World Switch
========================= =========================
For L1D-affected platforms, ACRN writes to aforementioned MSR For L1D-affected platforms, ACRN writes to aforementioned MSR to flush L1D
to flush L1D when switching from secure world to normal world. when switching from secure world to normal world. Doing so guarantees that
Doing so guarantees no sensitive information from secure world no sensitive information from secure world leaked into L1D. The performance
leaked in L1D. Performance impact is expected to small since world impact is expected to be small since world switch frequency is not expected
switch frequency is not expected high. to be high.
It's not necessary to flush L1D in the other direction, since It's not necessary to flush L1D in the other direction, because normal world
normal world is less privileged entity to secure world. is a less privileged entity than secure world.
This mitigation is always enabled. This mitigation is always enabled.
Core-Based Scheduling Core-Based Scheduling
===================== =====================
If Hyper-threading is enabled, it's important to avoid running If Hyper-threading is enabled, it's important to avoid running a sensitive
sensitive context (if containing security data which a given VM context (if it contains security data that a given VM has no permission to
has no permission to access) on the same physical core that runs access) on the same physical core that runs that VM. It requires a scheduler
said VM. It requires scheduler enhancement to enable core-based enhancement to enable a core-based scheduling policy, so all threads on the
scheduling policy, so all threads on the same core are always same core are always scheduled to the same VM. Also there are some further
scheduled to the same VM. Also there are some further actions actions required to protect the hypervisor and secure the world from sibling
required to protect hypervisor and secure world from sibling attacks in the core-based scheduler.
attacks in core-based scheduler.
.. note:: There is no current plan to implement this scheduling .. note:: There is no current plan to implement this scheduling policy. The
policy. The ACRN community will evaluate the need for this based ACRN community will evaluate the need for this based on usage
on usage requirements and hardware platform status. requirements and hardware platform status.
Mitigation Recommendations Mitigation Recommendations
************************** **************************
There is no mitigation required on Apollo Lake based platforms. There is no mitigation required on Apollo Lake based platforms.
The majority use case for ACRN is in pre-configured environment, The majority use case for ACRN is in a pre-configured environment, where the
where the whole software stack (from ACRN hypervisor to guest whole software stack (from ACRN hypervisor to guest kernel to Service VM
kernel to Service VM root) is tightly controlled by solution provider root) is tightly controlled by the solution provider and not enabled for
and not allowed for run time change after sale (guest kernel is runtime change after sale (that is, the guest kernel is trusted). In that
trusted). In that case solution provider will make sure that guest case, the solution provider will make sure that the guest kernel is
kernel is up-to-date including necessary page table sanitization, up-to-date including necessary page table sanitization; thus there is no
thus there is no attack interface exposed within guest. Then a attack interface exposed within the guest. Then a minimal mitigation
minimal mitigation configuration is sufficient with negligible configuration is sufficient with negligible performance impact, as
performance impact, as explained below: explained below:
1) Use latest microcode 1) Use latest microcode
2) Guest kernel is up-to-date with page table sanitization 2) Guest kernel is up-to-date with page table sanitization
3) EPT sanitization (always enabled) 3) EPT sanitization (always enabled)
4) Flush L1D at world switch (Android specific, always enabled) 4) Flush L1D at world switch (Android specific, always enabled)
In case that someone wants to deploy ACRN into an open environment In case someone wants to deploy ACRN into an open environment where the
where guest kernel is considered untrusted, there are more guest kernel is considered untrusted, there are additional mitigation
mitigation options required according to the specific usage options required according to the specific usage requirements:
requirements:
5) Put hypervisor security data in UC memory if possible 5) Put hypervisor security data in UC memory if possible
6) Enable L1D_FLUSH_VMENTRY option, if 6) Enable L1D_FLUSH_VMENTRY option, if
@ -265,10 +260,10 @@ requirements:
- Doing 5) is not feasible, or - Doing 5) is not feasible, or
- CPU sharing is enabled (in the future) - CPU sharing is enabled (in the future)
If Hyper-threading is enabled, there is no available mitigation If Hyper-threading is enabled, there is no available mitigation option
option before core scheduling is planned. User should understand before core scheduling is planned. The user should understand the security
the security implication and only turn on Hyper-threading implication and only turn on Hyper-threading when the potential risk is
when the potential risk is acceptable to their usage. acceptable for their usage.
Mitigation Status Mitigation Status
***************** *****************

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

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

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

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

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

@ -6,21 +6,25 @@ Trusty TEE
Introduction Introduction
************ ************
`Trusty`_ is a set of software components supporting a Trusted Execution Environment (TEE). `Trusty`_ is a set of software components supporting a Trusted Execution
TEE is commonly known as an isolated processing environment in which applications can be Environment (TEE). TEE is commonly known as an isolated processing environment
securely executed irrespective of the rest of the system. For more information about TEE, in which applications can be securely executed irrespective of the rest of the
please visit the `Trusted Execution Environment wiki page <https://en.wikipedia.org/wiki/Trusted_execution_environment>`_. 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: Trusty consists of:
1. An operating system (the Trusty OS) that runs on a processor intended to provide a TEE 1. An operating system (the Trusty OS) that runs on a processor intended to
#. Drivers for the Android kernel (Linux) to facilitate communication with applications provide a TEE
running under the Trusty OS #. Drivers for the Android kernel (Linux) to facilitate communication with
#. A set of libraries for Android/Linux systems software to facilitate communication with applications running under the Trusty OS
trusted applications executed within the Trusty OS using the kernel drivers #. 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, LK (`Little Kernel`_) is a tiny operating system suited for small embedded
and other environments where OS primitives such as threads, mutexes, and timers are needed, but devices, bootloaders, and other environments where OS primitives such as
there's a desire to keep things small and lightweight. LK has been chosen as the Trusty OS kernel. threads, mutexes, and timers are needed, but there's a desire to keep things
small and lightweight. LK has been chosen as the Trusty OS kernel.
Trusty Architecture Trusty Architecture
******************* *******************
@ -47,21 +51,24 @@ There are a few :ref:`hypercall_apis` that are related to Trusty.
Trusty Boot Flow 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 .. graphviz:: images/trusty-boot-flow.dot
:name: trusty-boot-flow :name: trusty-boot-flow
:align: center :align: center
:caption: Trusty Boot Flow :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 1. UOS_Loader
a. Load and verify Trusty image from virtual disk a. Load and verify Trusty image from virtual disk
#. Allocate runtime memory for trusty #. Allocate runtime memory for trusty
#. Do ELF relocation of trusty image and get entry address #. 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``) #. ACRN (``hcall_initialize_trusty``)
a. Save World context for Normal World 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 #. Trusty
a. Booting 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``) #. 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)) #. Restore World context for next World (Normal World (UOS_Loader))
#. Resume to next World (UOS_Loader) #. Resume to next World (UOS_Loader)
#. 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 EPT Hierarchy
************* *************
As per the Trusty design, Trusty can access Normal World's memory, but Normal World cannot As per the Trusty design, Trusty can access Normal World's memory, but Normal
access Secure World's memory. Hence it means Secure World EPTP page table hierarchy World cannot access Secure World's memory. Hence it means Secure World EPTP
must contain normal world GPA address space, while Trusty world's GPA address space page table hierarchy must contain normal world GPA address space, while Trusty
must be removed from the Normal world EPTP page table hierarchy. world's GPA address space must be removed from the Normal world EPTP page
table hierarchy.
Design Design
====== ======
Put Secure World's GPA to very high position: 511 GB - 512 GB. The PML4/PDPT for Trusty Put Secure World's GPA to very high position: 511 GB - 512 GB. The PML4/PDPT
World are separated from Normal World. PD/PT for low memory (< 511 GB) are shared in for Trusty World are separated from Normal World. PD/PT for low memory
both Trusty World's EPT and Normal World's EPT. PD/PT for high memory (>= 511 GB) are (< 511 GB) are shared in both Trusty World's EPT and Normal World's EPT.
valid for Trusty World's EPT only. PD/PT for high memory (>= 511 GB) are valid for Trusty World's EPT only.
Benefit Benefit
======= =======
This design will benefit the EPT changes of Normal World. There are requirement to This design will benefit the EPT changes of Normal World. There are
modify Normal World's EPT during runtime such as increasing memory, changing attributes, requirements to modify Normal World's EPT during runtime such as increasing
etc. If such behavior happened, only PD and PT for Normal World need to memory, changing attributes, etc. If such behavior happened, only PD and PT
be updated. for Normal World need to be updated.
.. figure:: images/ept-hierarchy.png .. figure:: images/ept-hierarchy.png
:align: center :align: center