github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-07-20 18:31:20 +00:00
Code Issues Projects Releases Wiki Activity

doc: more spelling and grammar fixes

Browse Source 
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2020-10-02 15:24:32 -07:00 committed by David Kinder
parent 576a3b5947
commit 5289a3eb97
18 changed files with 607 additions and 603 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -34,7 +34,7 @@ developers 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 components - interaction interface of each component
- core interaction scenarios - 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`
@ -118,7 +118,7 @@ In this scenario, AcrnGT receives a destroy request from ACRN-DM. It
calls GVT's :ref:`intel_gvt_ops_interface` to inform GVT of the vGPU destroy calls 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
======================================= =======================================
ACRN traps the vGPU's PCI config space write, notifies AcrnGT's ACRN traps the vGPU's PCI config space write, notifies AcrnGT's
@ -127,13 +127,13 @@ handle all I/O trap notifications. This routine calls the GVT's
:ref:`intel_gvt_ops_interface` ``emulate_cfg_write`` to emulate the vGPU PCI :ref:`intel_gvt_ops_interface` ``emulate_cfg_write`` to emulate the vGPU PCI
config space write: config space write:
#. If it's BAR0 (GTTMMIO) write, turn on/off GTTMMIO trap, according to #. If it is BAR0 (GTTMMIO) write, turn on/off GTTMMIO trap, according to
the write value. the write value.
#. If it's BAR1 (Aperture) write, maps/unmaps vGPU's aperture to its #. If it is BAR1 (Aperture) write, maps/unmaps vGPU's aperture to its
corresponding part in the host's aperture. corresponding part in the host's aperture.
#. Otherwise, write to the virtual PCI configuration space of the vGPU. #. Otherwise, write to the virtual PCI configuration space of the vGPU.
pci configure space read scenario PCI configure space read scenario
================================= =================================
Call sequence is almost the same as the write scenario above, Call sequence is almost the same as the write scenario above,
@ -143,25 +143,25 @@ but instead it calls the GVT's :ref:`intel_gvt_ops_interface`
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`` 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 trap its write to device model while
allowing read without trap. 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``.
PPGTT write protection page write PPGTT write-protection page write
================================= =================================
In the VHM module, ioreq for PPGTT WP and MMIO trap is the same. It will In the VHM module, ioreq for PPGTT WP and MMIO trap is the same. It will

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

@ -42,13 +42,13 @@ model (DM), and is registered as a PCI virtio device to the guest OS
User VM starts. Second, it copies the received data from the RXQ to TXQ 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 cycle and transmission, and keeps running until a specified number of cycles
is reached. is reached.
- **virtio-echo Driver in DM**: This driver is used for initialization - **virtio-echo Driver in DM**: This driver is used for initialization
configuration. It simulates a virtual PCI device for the frontend configuration. It simulates a virtual PCI device for the frontend
driver use, and sets necessary information such as the device driver use, and sets necessary information such as the device
configuration and virtqueue information to the VBS-K. After configuration and virtqueue information to the VBS-K. After
initialization, all data exchange are taken over by the VBS-K initialization, all data exchange is taken over by the VBS-K
vbs-echo driver. vbs-echo driver.
- **vbs-echo Backend Driver**: This driver sets all frontend RX buffers to - **vbs-echo Backend Driver**: This driver sets all frontend RX buffers to
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
@ -85,7 +85,7 @@ parts: kick overhead and notify overhead.
forwarded to the VHM module by the hypervisor. The VHM notifies its forwarded to the VHM module by the hypervisor. The VHM notifies its
client for this IOREQ, in this case, the client is the vbs-echo client for this IOREQ, in this case, the client is the vbs-echo
backend driver. Kick overhead is defined as the interval from the backend driver. Kick overhead is defined as the interval from the
beginning of User VM trap to a specific VBS-K driver e.g. when beginning of User VM trap to a specific VBS-K driver, e.g. when
virtio-echo gets notified. virtio-echo gets notified.
- **Notify Overhead**: After the data in virtqueue being processed by the - **Notify Overhead**: After the data in virtqueue being processed by the
backend driver, vbs-echo calls the VHM module to inject an interrupt backend driver, vbs-echo calls the VHM module to inject an interrupt
@ -113,7 +113,7 @@ 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 4 dozens of microsecond. That's
because virtio-echo does little things in its frontend and backend because virtio-echo does little things in its frontend and backend
driver which is just for testing and there is very little process driver that is just for testing and there is very little process
overhead. overhead.
.. figure:: images/vbsk-image1.png .. figure:: images/vbsk-image1.png
@ -126,7 +126,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 which avoids extra these operations are processed in kernel mode and avoids 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
@ -143,5 +143,5 @@ Unlike VBS-U processing in user mode, VBS-K moves things into the kernel
mode and can be used to accelerate processing. A virtual device mode and can be used to accelerate processing. A virtual device
virtio-echo based on VBS-K framework is used to evaluate the VBS-K virtio-echo based on VBS-K framework is used to evaluate the VBS-K
framework overhead. In our test, the VBS-K framework overhead (one kick framework overhead. In our test, the VBS-K framework overhead (one kick
operation and one notify operation) is on the microsecond level which operation and one notify operation) is on the microsecond level, which
can meet the needs of most applications. can meet the needs of most applications.

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

@ -139,9 +139,10 @@ 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 which uses .end directive. .end This rule only applies to the Assembly file that uses ``.end``
directive shall be the last statement in this case. All the statements past .end directive. ``.end`` directive shall be the last statement in this case.
directive will not be processed by the assembler. All the statements past ``.end`` directive will not be processed by the
assembler.
Compliant example:: Compliant example::
@ -270,17 +271,17 @@ 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 GNU assembler 'as' user manual. Only
the following assembler directives may be used: the following assembler directives may be used:
1) .align 1) ``.align``
2) .end 2) ``.end``
3) .extern 3) ``.extern``
4) repeat related directives, including .rept and .endr 4) repeat related directives, including ``.rept`` and ``.endr``
5) global related directives, including .global and .globl 5) global related directives, including ``.global`` and ``.globl``
6) macro related directives, including .altmacro, .macro, and .endm 6) macro related directives, including ``.altmacro``, ``.macro``, and ``.endm``
7) code bit related directives, including .code16, .code32, and .code64 7) code bit related directives, including ``.code16``, ``.code32``, and ``.code64``
8) section related directives, including .section, .data, and .text 8) section related directives, including ``.section``, ``.data``, and ``.text``
9) number emission related directives, including .byte, .word, .short, .long, 9) number emission related directives, including ``.byte``, ``.word``,
and .quad ``.short``, ``.long``, and ``.quad``
10) .org, which shall be used with restrictions. It shall only be used to 10) ``.org`` shall be used with restrictions. It shall only be used to
advance the location counter due to code bit changes, such as change from 32-bit advance the location counter due to code bit changes, such as change from 32-bit
mode to 64-bit mode. mode to 64-bit mode.
@ -786,9 +787,9 @@ 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. Usage of local labels
is allowed. Local label is defined with the format 'N:', where N represents any is allowed. Local label is defined with the format ``N:``, where N represents any
non-negative integer. Using 'Nb' to refer to the most recent previous definition non-negative integer. Using ``Nb`` to refer to the most recent previous definition
of that label. Using 'Nf' to refer to the next definition of a local label. of that label. Using ``Nf`` to refer to the next definition of a local label.
Compliant example:: Compliant example::
@ -809,8 +810,8 @@ Compliant example::
movl $0x2, %eax movl $0x2, %eax
ASM-NC-04: Names defined by developers shall be less than 31 characters ASM-NC-04: Names defined by developers shall be fewer than 31 characters
======================================================================= ========================================================================
Compliant example:: Compliant example::

133
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 not be
allowed: allowed:
a) The result getting from ## or # operation shall not be used as the operands a) The result getting from ``##`` or ``#`` operation shall not be used as the operands
of another ## or # operation; 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::
@ -59,7 +59,8 @@ Compliant example::
C-PP-03: Header file shall not be included multiple times C-PP-03: Header file shall not be included multiple times
========================================================= =========================================================
The content inside shall be protected with #ifndef, #if !defined, or #ifdef. The content inside shall be protected with ``#ifndef``, ``#if
!defined``, or ``#ifdef``.
Compliant example:: Compliant example::
@ -1297,8 +1298,8 @@ Compliant example::
} }
C-ST-08: 'goto' statement shall not be used C-ST-08: ``goto`` statement shall not be used
============================================ ==============================================
Compliant example:: Compliant example::
@ -2962,7 +2963,7 @@ 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 the
keywords 'if', 'else', 'for', 'do', 'while', 'switch' and 'return'. keywords ``if``, ``else``, ``for``, ``do``, ``while``, ``switch`` and ``return``.
Compliant example:: Compliant example::
@ -3013,14 +3014,14 @@ Compliant example::
size_t entry_size = sizeof( struct vcpuid_entry ); size_t entry_size = sizeof( struct vcpuid_entry );
C-CS-09: The '*' characters used for pointers shall be right before the function or variable identifiers C-CS-09: The ``*`` characters used for pointers shall be right before the function or variable identifiers
======================================================================================================== ==========================================================================================================
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 be
right before the variable identifier with no space in between. 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 the
function prototype. function prototype.
@ -3154,8 +3155,8 @@ Compliant example::
} }
C-CS-15: A 'switch' statement and its subordinate 'case' shall be aligned C-CS-15: A ``switch`` statement and its subordinate ``case`` shall be aligned
========================================================================= =============================================================================
Compliant example:: Compliant example::
@ -3209,10 +3210,10 @@ Compliant example::
param_3); param_3);
C-CS-17: '//' shall not be used for single-line comments C-CS-17: ``//`` shall not be used for single-line comments
========================================================= ===========================================================
'/\* \*/' shall be used to replace '//' for single-line comments. ``/* */`` shall be used to replace ``//`` for single-line comments.
Compliant example:: Compliant example::
@ -3231,12 +3232,12 @@ 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 each
function: 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 ' \*/' (space-asterisk-slash) in a single 2) The comments block shall end with :literal:`\ */` (space-asterisk-slash) in a single
line. 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 ' \*' (space-asterisk). It also applies to the line which block shall start with :literal:`\ *` (space-asterisk). It also applies to the line which
is used to separate different paragraphs. We'll call it a blank line for is used to separate different paragraphs. We'll call it a blank line for
simplicity. simplicity.
4) For each function, the information shall be documented with the following 4) For each function, the information shall be documented with the following
@ -3251,20 +3252,20 @@ function:
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 function.
9) The description of the function parameter shall be documented with the format 9) The description of the function parameter shall be documented with the format
'\@param <parameter name> <parameter description>'. ``@param <parameter name> <parameter description>``.
10) The pre-condition of the function shall be documented with the format '\@pre 10) The pre-condition of the function shall be documented with the format
<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 with
the format '\@return <brief description of return value>'. the format ``@return <brief description of return value>``.
13) A void-returning function shall be documented with the format '\@return 13) A void-returning function shall be documented with the format
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 that
element. element.
@ -3390,8 +3391,8 @@ Compliant example::
#define Max(x, y) ((x) < (y)) ? (y) : (x) #define Max(x, y) ((x) < (y)) ? (y) : (x)
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 the data structure with all the following properties: This rule applies to the data structure with all the following properties:
@ -3416,8 +3417,8 @@ 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 the data structure with all the following properties: This rule applies to the data structure with all the following properties:
@ -3471,9 +3472,9 @@ C-NC-06: Data structures related to hardware resource shall be named with the re
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``.
Compliant example:: Compliant example::
@ -3490,8 +3491,8 @@ Compliant example::
}; };
C-NC-07: Function pointer shall be named with suffix 'fn' C-NC-07: Function pointer shall be named with suffix ``fn``
========================================================= ===========================================================
Compliant example:: Compliant example::
@ -3519,30 +3520,30 @@ 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 doing actions, it shall be named with one of the following
formats: 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 following
formats: 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``.
3) If the function is doing conversions, it shall be named with one of the 3) If the function is doing conversions, it shall be named with one of the
following formats: following formats:
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, such
as 'vie_read_mmio'. 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 with
one of the following formats: 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 nouns, as
long as it could clearly illustrate the object. long as it could clearly illustrate the object.
Compliant example:: Compliant example::
@ -3610,12 +3611,12 @@ 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 author
name. name.
C-IB-04: 'plain' char is equivalent to signed char C-IB-04: ``plain char`` is equivalent to ``signed char``
=================================================== ========================================================
The underlying type of 'plain' char is implementation-defined, according to The underlying type of ``plain char`` is implementation-defined, according to
J.3.4 item 5 in C99. For ACRN hypervisor, 'plain' char is equivalent to signed J.3.4 item 5 in C99. For ACRN hypervisor, ``plain char`` is equivalent to
char. ``signed char``.
C-IB-05: Signed integers are represented in two's complement C-IB-05: Signed integers are represented in two's complement
============================================================ ============================================================
@ -3650,8 +3651,8 @@ 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.
C-LE-02: Use of builtin-type '__builtin_va_list' is allowed 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.
@ -3660,26 +3661,24 @@ C-LE-03: Use of extended type attribute is allowed
This rule applies to the following type attributes: This rule applies to the following type attributes:
a) 'aligned', refers to section 6.33.1 in GCC 8.3 Manual. a) ``aligned``, refers to section 6.33.1 in GCC 8.3 Manual.
b) 'packed', refers to section 6.33.1 in GCC 8.3 Manual. b) ``packed``, refers to section 6.33.1 in GCC 8.3 Manual.
c) 'unused', refers to section 6.33.1 in GCC 8.3 Manual. c) ``unused``, refers to section 6.33.1 in GCC 8.3 Manual.
d) 'section', refers to section 6.32.1 in GCC 8.3 Manual. d) ``section``, refers to section 6.32.1 in GCC 8.3 Manual.
C-LE-04: Use of extended builtin-function is allowed C-LE-04: Use of extended builtin-function is allowed
==================================================== ====================================================
This rule applies to the following builtin-functions: This rule applies to the following builtin-functions:
a) '__builtin_va_arg', refers to section 6.20 in GCC 8.3 Manual. a) ``__builtin_va_arg``, refers to section 6.20 in GCC 8.3 Manual.
b) '__builtin_va_start', refers to section 6.20 in GCC 8.3 Manual. b) ``__builtin_va_start``, refers to section 6.20 in GCC 8.3 Manual.
c) '__builtin_va_end', refers to section 6.20 in GCC 8.3 Manual. c) ``__builtin_va_end``, refers to section 6.20 in GCC 8.3 Manual.
d) '__builtin_offsetof', refers to section 6.51 in GCC 8.3 Manual. d) ``__builtin_offsetof``, refers to section 6.51 in GCC 8.3 Manual.
C-LE-05: Use of extended designated initializers is allowed C-LE-05: Use of extended designated initializers is allowed
=========================================================== ===========================================================
This rule applies to the following designated initializer: writing '[first ... This rule applies to the following designated initializer: writing
last] = value' to initialize a range of elements to the same value, refers to ``[first ... last] = value`` to initialize a range of elements
section 6.27 in GCC 8.3 Manual. to the same value, refers to section 6.27 in GCC 8.3 Manual.

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

@ -117,8 +117,8 @@ on https://github.com and have Git tools available on your development system.
Repository layout 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

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

@ -5,7 +5,7 @@ Documentation Guidelines
Project ACRN content is written using the `reStructuredText`_ markup Project ACRN content is written using the `reStructuredText`_ markup
language (``.rst`` file extension) with Sphinx extensions, and processed language (``.rst`` file extension) with Sphinx extensions, and processed
using Sphinx to create a formatted standalone 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
@ -32,7 +32,7 @@ Document sections are identified through their heading titles,
indicated with an underline below the title text. (While reST allows indicated with an underline below the title text. (While reST allows
use of both and overline and matching underline to indicate a heading, use of both and overline and matching underline to indicate a heading,
we only use an underline indicator for headings.) For consistency in we only use an underline indicator for headings.) For consistency in
our documentation, we define the order of characters used to indicated our documentation, we define the order of characters used to indicate
the nested table of contents levels: the nested table of contents levels:
* Use ``#`` for the Document title underline character * Use ``#`` for the Document title underline character
@ -52,11 +52,11 @@ underlines to use:
Document Title heading Document Title heading
###################### ######################
Section 1.0 heading Section 1 heading
******************* *****************
Section 2.0 heading Section 2 heading
******************* *****************
Section 2.1 heading Section 2.1 heading
=================== ===================
@ -67,8 +67,8 @@ underlines to use:
Section 2.2 heading Section 2.2 heading
=================== ===================
Section 3.0 heading Section 3 heading
******************* *****************
@ -79,17 +79,17 @@ Some common reST inline markup samples:
* one asterisk: ``*text*`` for emphasis (*italics*), * one asterisk: ``*text*`` for emphasis (*italics*),
* two asterisks: ``**text**`` for strong emphasis (**boldface**), and * two asterisks: ``**text**`` for strong emphasis (**boldface**), and
* two backquotes: ````text```` for ``inline code`` samples. * two back quotes: ````text```` for ``inline code`` samples.
ReST rules for inline markup try to be forgiving to account for common ReST rules for inline markup try to be forgiving to account for common
cases of using these marks. For example using an asterisk to indicate cases of using these marks. For example, using an asterisk to indicate
multiplication, such as ``2 * (x + y)`` will not be interpreted as an multiplication, such as ``2 * (x + y)`` will not be interpreted as an
unterminated italics section. For inline markup, the characters between unterminated italics section. For inline markup, the characters between
the beginning and ending characters must not start or end with a space, 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 backquotes appear in running text and could be confused with If asterisks or back quotes appear in running text and could be confused with
inline markup delimiters, you can eliminate the confusion by adding a inline markup delimiters, you can eliminate the confusion by adding a
backslash (``\``) before it. backslash (``\``) before it.
@ -137,17 +137,17 @@ list item:
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 a term and its definition) are a convenient way
to document a word or phrase with an explanation. For example this reST to document a word or phrase with an explanation. For example, this reST
content: content:
.. code-block:: rest .. code-block:: rest
The Makefile has targets that include: The Makefile has targets that include:
html ``html``
Build the HTML output for the project Build the HTML output for the project
clean ``clean``
Remove all generated output, restoring the folders to a Remove all generated output, restoring the folders to a
clean state. clean state.
@ -198,7 +198,8 @@ would be rendered as:
* the page * the page
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``), and change (or ``rst-columns3``), and two columns for ``rst-columns2``. The number
of columns displayed can be reduced
based on the available width of the display window, reducing to one based on the available width of the display window, reducing to one
column on narrow (phone) screens if necessary. We've deprecated use of column on narrow (phone) screens if necessary. We've deprecated use of
the ``hlist`` directive because it misbehaves on smaller screens. the ``hlist`` directive because it misbehaves on smaller screens.
@ -361,8 +362,8 @@ it will show up as :ref:`doc_guidelines`. This type of internal cross reference
multiple files, and the link text is obtained from the document source so if the title changes, multiple files, and the link text is obtained from the document source so if the title changes,
the link text will update as well. the link text will update as well.
There may be times where 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 generated document. In this case, you can add specify alternate in the generated document. In this case, you can specify alternate
text using ``:ref:`alternate text <doc_guidelines>``` (renders as text using ``:ref:`alternate text <doc_guidelines>``` (renders as
:ref:`alternate text <doc_guidelines>`). :ref:`alternate text <doc_guidelines>`).
@ -614,7 +615,7 @@ sphinx-tabs from the link above.
Instruction Steps Instruction Steps
***************** *****************
Numbered instruction steps is a style that makes it A numbered instruction steps style makes it
easy to create tutorial guides with clearly identified steps. Add easy to create tutorial guides with clearly identified steps. Add
the ``.. rst-class:: numbered-step`` directive immediately before a the ``.. rst-class:: numbered-step`` directive immediately before a
second-level heading (by project convention, a heading underlined with second-level heading (by project convention, a heading underlined with

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

@ -39,7 +39,7 @@ 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 in the content block for the directive. For example for a commands in the content block for the directive. For example, for a
simple directed graph (digraph) with two nodes connected by an arrow, simple directed graph (digraph) with two nodes connected by an arrow,
you can write: you can write:

50
doc/developer-guides/hld/hld-devicemodel.rst
View File

@ -28,7 +28,7 @@ framework. There are 3 major subsystems in Service VM:
- HV initializes an I/O request and notifies VHM driver in Service VM - HV initializes an I/O request and notifies VHM driver in Service VM
through upcall. through upcall.
- VHM driver dispatches I/O requests to I/O clients and notifies the - VHM driver dispatches I/O requests to I/O clients and notifies the
clients (in this case the client is the DM which is notified clients (in this case the client is the DM, which is notified
through char device) through char device)
- DM I/O dispatcher calls corresponding I/O handlers - DM I/O dispatcher calls corresponding I/O handlers
- I/O dispatcher notifies VHM driver the I/O request is completed - I/O dispatcher notifies VHM driver the I/O request is completed
@ -160,8 +160,8 @@ DM Initialization
mapping, and maps the memory segments into user space. mapping, and maps the memory segments into user space.
- **PIO/MMIO Handler Init**: PIO/MMIO handlers provide callbacks for - **PIO/MMIO Handler Init**: PIO/MMIO handlers provide callbacks for
trapped PIO/MMIO request which are triggered from I/O request trapped PIO/MMIO requests that are triggered from I/O request
server in HV for DM owned device emulation. This is the endpoint server in HV for DM-owned device emulation. This is the endpoint
of I/O path in DM. After this initialization, device emulation of I/O path in DM. After this initialization, device emulation
driver in DM could register its MMIO handler by *register_mem()* driver in DM could register its MMIO handler by *register_mem()*
API and PIO handler by *register_inout()* API or INOUT_PORT() API and PIO handler by *register_inout()* API or INOUT_PORT()
@ -283,7 +283,7 @@ VHM overview
============ ============
Device Model manages User VM by accessing interfaces exported from VHM Device Model manages User VM by accessing interfaces exported from VHM
module. VHM module is an Service VM kernel driver. The ``/dev/acrn_vhm`` node is module. VHM module is a Service VM kernel driver. The ``/dev/acrn_vhm`` node is
created when VHM module is initialized. Device Model follows the standard created when VHM module is initialized. Device Model follows the standard
Linux char device API (ioctl) to access the functionality of VHM. Linux char device API (ioctl) to access the functionality of VHM.
@ -305,7 +305,7 @@ hypercall to the hypervisor. There are two exceptions:
VHM ioctl interfaces VHM ioctl interfaces
==================== ====================
.. note:: Reference API docs for General interface, VM Management, .. note:: Reference API documents for General interface, VM Management,
IRQ and Interrupts, Device Model management, Guest Memory management, IRQ and Interrupts, Device Model management, Guest Memory management,
PCI assignment, and Power management PCI assignment, and Power management
@ -338,10 +338,10 @@ I/O Clients
An I/O client is either a Service VM userland application or a Service VM kernel space An I/O client is either a Service VM userland application or a Service VM kernel space
module responsible for handling I/O access whose address module responsible for handling I/O access whose address
falls in a certain range. Each VM has an array of registered I/O falls in a certain range. Each VM has an array of registered I/O
clients which are initialized with a fixed I/O address range, plus a PCI clients that are initialized with a fixed I/O address range, plus a PCI
BDF on VM creation. There is a special client in each VM, called the BDF on VM creation. There is a special client in each VM, called the
fallback client, that handles all I/O requests that do not fit into fallback client, that handles all I/O requests that do not fit into
the range of any other client. In the current design the device model the range of any other client. In the current design, the device model
acts as the fallback client for any VM. acts as the fallback client for any VM.
Each I/O client can be configured to handle the I/O requests in the Each I/O client can be configured to handle the I/O requests in the
@ -358,8 +358,8 @@ specifically created for this purpose.
- On registration, the client requests a fresh ID, registers a - On registration, the client requests a fresh ID, registers a
handler, adds the I/O range (or PCI BDF) to be emulated by this handler, adds the I/O range (or PCI BDF) to be emulated by this
client, and finally attaches it to VHM which creates the kicks off client, and finally attaches it to VHM that kicks off
for a new kernel thread. a new kernel thread.
- The kernel thread waits for any I/O request to be handled. When a - The kernel thread waits for any I/O request to be handled. When a
pending I/O request is assigned to the client by VHM, the kernel pending I/O request is assigned to the client by VHM, the kernel
@ -414,9 +414,9 @@ are as follows:
all clients that have I/O requests to be processed. The flow is all clients that have I/O requests to be processed. The flow is
illustrated in more detail in :numref:`io-dispatcher-flow`. illustrated in more detail in :numref:`io-dispatcher-flow`.
4. The waked client (the DM in :numref:`io-sequence-sos` above) handles the 4. The woken client (the DM in :numref:`io-sequence-sos` above) handles the
assigned I/O requests, updates their state to COMPLETE, and notifies assigned I/O requests, updates their state to COMPLETE, and notifies
the VHM of the completion via ioctl. :numref:`dm-io-flow` show this the VHM of the completion via ioctl. :numref:`dm-io-flow` shows this
flow. flow.
5. The VHM device notifies the hypervisor of the completion via 5. The VHM device notifies the hypervisor of the completion via
@ -499,10 +499,10 @@ from different devices including PIO, MMIO, and PCI CFG
SPACE access. For example, a CMOS RTC device may access 0x70/0x71 PIO to SPACE access. For example, a CMOS RTC device may access 0x70/0x71 PIO to
get CMOS time, a GPU PCI device may access its MMIO or PIO bar space to get CMOS time, a GPU PCI device may access its MMIO or PIO bar space to
complete its framebuffer rendering, or the bootloader may access a PCI complete its framebuffer rendering, or the bootloader may access a PCI
devices' CFG SPACE for BAR reprogramming. device's CFG SPACE for BAR reprogramming.
The DM needs to inject interrupts/MSIs to its frontend devices whenever The DM needs to inject interrupts/MSIs to its frontend devices whenever
necessary. For example, a RTC device needs get its ALARM interrupt, or a necessary. For example, an RTC device needs get its ALARM interrupt, or a
PCI device with MSI capability needs to get its MSI. PCI device with MSI capability needs to get its MSI.
DM also provides a PIRQ routing mechanism for platform devices. DM also provides a PIRQ routing mechanism for platform devices.
@ -543,7 +543,7 @@ A PIO emulation handler is defined as:
The DM pre-registers the PIO emulation handlers through MACRO The DM pre-registers the PIO emulation handlers through MACRO
INOUT_PORT, or registers the PIO emulation handers through INOUT_PORT, or registers the PIO emulation handlers through
register_inout() function after init_inout(): register_inout() function after init_inout():
.. code-block:: c .. code-block:: c
@ -565,7 +565,7 @@ register_inout() function after init_inout():
MMIO Handler Register MMIO Handler Register
--------------------- ---------------------
A MMIO range structure is defined below. As with PIO, it's the An MMIO range structure is defined below. As with PIO, it's the
parameter needed to register MMIO handler for special MMIO range: parameter needed to register MMIO handler for special MMIO range:
.. code-block:: c .. code-block:: c
@ -580,7 +580,7 @@ parameter needed to register MMIO handler for special MMIO range:
uint64_t size; uint64_t size;
}; };
A MMIO emulation handler is defined as: An MMIO emulation handler is defined as:
.. code-block:: c .. code-block:: c
@ -694,17 +694,17 @@ DM calls pci_lintr_route() to emulate this PIRQ routing:
The PIRQ routing for IOAPIC and PIC is dealt with differently. The PIRQ routing for IOAPIC and PIC is dealt with differently.
* For IOAPIC, the irq pin is allocated in a round-robin fashion within the * For IOAPIC, the IRQ pin is allocated in a round-robin fashion within the
pins permitted for PCI devices. The irq information will be built pins permitted for PCI devices. The IRQ information will be built
into ACPI DSDT table then passed to guest VM. into ACPI DSDT table then passed to guest VM.
* For PIC, the pin2irq information is maintained in a pirqs[] array (the array size is 8 * For PIC, the pin2irq information is maintained in a pirqs[] array (the array size is 8
representing 8 shared PIRQs). When a PCI device tries to allocate a representing 8 shared PIRQs). When a PCI device tries to allocate a
pirq pin, it will do a balancing calculation to figure out a best pin pirq pin, it will do a balancing calculation to figure out a best pin
vs. irq pair. The irq# will be programed into PCI INTLINE config space vs. IRQ pair. The irq# will be programed into PCI INTLINE config space
and the pin# will be built into ACPI DSDT table then passed to guest VM. and the pin# will be built into ACPI DSDT table then passed to guest VM.
.. note:: "irq" here is also called as "gsi" in ACPI terminology . .. note:: "IRQ" here is also called as "GSI" in ACPI terminology.
Regarding to INT A/B/C/D for PCI devices, DM just allocates them evenly Regarding to INT A/B/C/D for PCI devices, DM just allocates them evenly
prior to PIRQ routing and then programs into PCI INTPIN config space. prior to PIRQ routing and then programs into PCI INTPIN config space.
@ -742,9 +742,9 @@ During PCI initialization, ACRN DM will scan each PCI bus, slot and
function and identify the PCI devices configured by acrn-dm command function and identify the PCI devices configured by acrn-dm command
line. The corresponding PCI device's initialization function will line. The corresponding PCI device's initialization function will
be called to initialize its config space, allocate its BAR resource, its be called to initialize its config space, allocate its BAR resource, its
irq, and do its irq routing. irq, and do its IRQ routing.
.. note:: reference API doc for pci_vdev, pci_vdef_ops .. note:: reference API documentation for pci_vdev, pci_vdef_ops
The pci_vdev_ops of the pci_vdev structure could be installed by The pci_vdev_ops of the pci_vdev structure could be installed by
customized handlers for cfgwrite/cfgread and barwrite/barread. customized handlers for cfgwrite/cfgread and barwrite/barread.
@ -797,7 +797,7 @@ Introduction
Advanced Configuration and Power Interface (ACPI) provides an open Advanced Configuration and Power Interface (ACPI) provides an open
standard that operating systems can use to discover and configure standard that operating systems can use to discover and configure
computer hardware components to perform power management for example, by computer hardware components to perform power management, for example, by
monitoring status and putting unused components to sleep. monitoring status and putting unused components to sleep.
Functions implemented by ACPI include: Functions implemented by ACPI include:
@ -1176,7 +1176,7 @@ Bluetooth UART enumeration.
PM in Device Model PM in Device Model
****************** ******************
PM module in Device Model emulate the User VM low power state transition. PM module in Device Model emulates the User VM low power state transition.
Each time User VM writes an ACPI control register to initialize low power Each time User VM writes an ACPI control register to initialize low power
state transition, the writing operation is trapped to DM as an I/O state transition, the writing operation is trapped to DM as an I/O
@ -1196,4 +1196,4 @@ Passthrough in Device Model
You may refer to :ref:`hv-device-passthrough` for passthrough realization You may refer to :ref:`hv-device-passthrough` for passthrough realization
in device model and :ref:`mmio-device-passthrough` for MMIO passthrough realization in device model and :ref:`mmio-device-passthrough` for MMIO passthrough realization
in device model and ACRN Hypervisor.. in device model and ACRN Hypervisor.

50
doc/developer-guides/hld/hld-overview.rst
View File

@ -3,11 +3,13 @@
ACRN high-level design overview ACRN high-level design overview
############################### ###############################
ACRN is an open source reference hypervisor (HV) that runs on top of Intel ACRN is an open source reference hypervisor (HV) that runs on top of
platforms (APL, KBL, etc) for heterogeneous scenarios such as the Software Defined Intel platforms (APL, KBL, etc.) for heterogeneous scenarios such as the
Cockpit (SDC), or the In-Vehicle Experience (IVE) for automotive, or HMI & real-time OS for industry. ACRN provides embedded hypervisor vendors with a reference Software-defined Cockpit (SDC), or the In-vehicle Experience (IVE) for
I/O mediation solution with a permissive license and provides auto makers and automotive, or HMI & real-time OS for industry. ACRN provides embedded
industry users a reference software stack for corresponding use. hypervisor vendors with a reference I/O mediation solution with a
permissive license and provides auto makers and industry users a
reference software stack for corresponding use.
ACRN Supported Use Cases ACRN Supported Use Cases
************************ ************************
@ -20,16 +22,16 @@ system, the In-vehicle Infotainment (IVI) system, and one or more rear
seat entertainment (RSE) systems. Each system runs as a VM for better seat entertainment (RSE) systems. Each system runs as a VM for better
isolation. isolation.
The Instrument Control (IC) system manages graphic displays of The Instrument Control (IC) system manages graphic displays of:
- driving speed, engine RPM, temperature, fuel level, odometer, trip mile, etc. - driving speed, engine RPM, temperature, fuel level, odometer, trip mile, etc.
- alerts of low fuel or tire pressure - alerts of low fuel or tire pressure
- rear-view camera (RVC) and surround-camera view for driving assistance - rear-view camera (RVC) and surround-camera view for driving assistance
In-Vehicle Infotainment In-vehicle Infotainment
======================= =======================
A typical In-Vehicle Infotainment (IVI) system supports: A typical In-vehicle Infotainment (IVI) system supports:
- Navigation systems - Navigation systems
- Radios, audio and video playback - Radios, audio and video playback
@ -49,11 +51,11 @@ VMs for a customized IC/IVI/RSE.
Industry Usage Industry Usage
============== ==============
A typical industry usage would include one windows HMI + one RT VM: A typical industry usage would include one Windows HMI + one RT VM:
- windows HMI as a guest OS with display to provide Human Machine Interface - Windows HMI as a guest OS with display to provide Human Machine Interface
- RT VM which running specific RTOS on it to provide capability of handling - RT VM that runs a specific RTOS on it to handle
real-time workloads like PLC control real-time workloads such as PLC control
ACRN supports guest OS of Windows; ACRN has also added/is adding a ACRN supports guest OS of Windows; ACRN has also added/is adding a
series features to enhance its real-time performance then meet hard-RT KPI series features to enhance its real-time performance then meet hard-RT KPI
@ -76,7 +78,7 @@ Mandatory IA CPU features are support for:
- MTRR - MTRR
- TSC deadline timer - TSC deadline timer
- NX, SMAP, SMEP - NX, SMAP, SMEP
- Intel-VT including VMX, EPT, VT-d, APICv, VPID, invept and invvpid - Intel-VT including VMX, EPT, VT-d, APICv, VPID, INVEPT and INVVPID
Recommended Memory: 4GB, 8GB preferred. Recommended Memory: 4GB, 8GB preferred.
@ -102,7 +104,7 @@ in the future. Running the IC system in a separate VM can isolate it from
other VMs and their applications, thereby reducing the attack surface other VMs and their applications, thereby reducing the attack surface
and minimizing potential interference. However, running the IC system in and minimizing potential interference. However, running the IC system in
a separate VM introduces additional latency for the IC applications. a separate VM introduces additional latency for the IC applications.
Some country regulations requires an IVE system to show a rear-view Some country regulations require an IVE system to show a rear-view
camera (RVC) within 2 seconds, which is difficult to achieve if a camera (RVC) within 2 seconds, which is difficult to achieve if a
separate instrument cluster VM is started after the User VM is booted. separate instrument cluster VM is started after the User VM is booted.
@ -111,7 +113,7 @@ the IC VM and Service VM. As shown, the Service VM owns most of platform devices
provides I/O mediation to VMs. Some of the PCIe devices function as a provides I/O mediation to VMs. Some of the PCIe devices function as a
passthrough mode to User VMs according to VM configuration. In addition, passthrough mode to User VMs according to VM configuration. In addition,
the Service VM could run the IC applications and HV helper applications such the Service VM could run the IC applications and HV helper applications such
as the Device Model, VM manager, etc. where the VM manager is responsible as the Device Model, VM manager, etc., where the VM manager is responsible
for VM start/stop/pause, virtual CPU pause/resume, etc. for VM start/stop/pause, virtual CPU pause/resume, etc.
.. figure:: images/over-image34.png .. figure:: images/over-image34.png
@ -130,7 +132,7 @@ and real-time (RT) VM.
compared to ACRN 1.0 is that: compared to ACRN 1.0 is that:
- a pre-launched VM is supported in ACRN 2.0, with isolated resources, including - a pre-launched VM is supported in ACRN 2.0, with isolated resources, including
CPU, memory, and HW devices, etc CPU, memory, and HW devices, etc.
- ACRN 2.0 adds a few necessary device emulations in hypervisor like vPCI and vUART to avoid - ACRN 2.0 adds a few necessary device emulations in hypervisor like vPCI and vUART to avoid
interference between different VMs interference between different VMs
@ -190,7 +192,7 @@ I/O read from the User VM.
I/O (PIO/MMIO) Emulation Path I/O (PIO/MMIO) Emulation Path
:numref:`overview-io-emu-path` shows an example I/O emulation flow path. :numref:`overview-io-emu-path` shows an example I/O emulation flow path.
When a guest executes an I/O instruction (port I/O or MMIO), an VM exit When a guest executes an I/O instruction (port I/O or MMIO), a VM exit
happens. The HV takes control and executes the request based on the VM exit happens. The HV takes control and executes the request based on the VM exit
reason ``VMX_EXIT_REASON_IO_INSTRUCTION`` for port I/O access, for reason ``VMX_EXIT_REASON_IO_INSTRUCTION`` for port I/O access, for
example. The HV will then fetch the additional guest instructions, if any, example. The HV will then fetch the additional guest instructions, if any,
@ -349,7 +351,7 @@ Kernel Mediators
================ ================
Kernel mediators are kernel modules providing a para-virtualization method Kernel mediators are kernel modules providing a para-virtualization method
for the User VMs, for example, an i915 gvt driver. for the User VMs, for example, an i915 GVT driver.
Log/Trace Tools Log/Trace Tools
=============== ===============
@ -478,7 +480,7 @@ the following mechanisms:
scheduling latency and vCPU priority, exposing more opportunities scheduling latency and vCPU priority, exposing more opportunities
for one VM to interfere another. for one VM to interfere another.
To prevent such interference, ACRN hypervisor could adopts static To prevent such interference, ACRN hypervisor could adopt static
core partitioning by dedicating each physical CPU to one vCPU. The core partitioning by dedicating each physical CPU to one vCPU. The
physical CPU loops in idle when the vCPU is paused by I/O physical CPU loops in idle when the vCPU is paused by I/O
emulation. This makes the vCPU scheduling deterministic and physical emulation. This makes the vCPU scheduling deterministic and physical
@ -497,7 +499,7 @@ the following mechanisms:
3. The hypervisor does not unintendedly access the memory of the Service or User VM. 3. The hypervisor does not unintendedly access the memory of the Service or User VM.
- Destination of external interrupts are set to be the physical core - The destination of external interrupts is set to be the physical core
where the VM that handles them is running. where the VM that handles them is running.
External interrupts are always handled by the hypervisor in ACRN. External interrupts are always handled by the hypervisor in ACRN.
@ -564,7 +566,7 @@ System power state
================== ==================
ACRN supports ACPI standard defined power state: S3 and S5 in system ACRN supports ACPI standard defined power state: S3 and S5 in system
level. For each guest, ACRN assume guest implements OSPM and controls its level. For each guest, ACRN assumes guest implements OSPM and controls its
own power state accordingly. ACRN doesn't involve guest OSPM. Instead, own power state accordingly. ACRN doesn't involve guest OSPM. Instead,
it traps the power state transition request from guest and emulates it. it traps the power state transition request from guest and emulates it.
@ -582,8 +584,8 @@ transition of the User VM (Linux VM or Android VM in
notifies the OSPM of the Service VM (Service OS in :numref:`overview-pm-block`) once notifies the OSPM of the Service VM (Service OS in :numref:`overview-pm-block`) once
active the User VM is in the required power state. active the User VM is in the required power state.
Then the OSPM of the Service VM starts the power state transition of the Service VM which is Then the OSPM of the Service VM starts the power state transition of the Service VM
trapped to "Sx Agency" in ACRN, and it will start the power state trapped to "Sx Agency" in ACRN, and it starts the power state
transition. transition.
Some details about the ACPI table for the User and Service VMs: Some details about the ACPI table for the User and Service VMs:
@ -594,4 +596,4 @@ Some details about the ACPI table for the User and Service VMs:
- The ACPI table in the Service VM is passthrough. There is no ACPI parser - The ACPI table in the Service VM is passthrough. There is no ACPI parser
in ACRN HV. The power management related ACPI table is in ACRN HV. The power management related ACPI table is
generated offline and hardcoded in ACRN HV. generated offline and hard-coded in ACRN HV.

22
doc/developer-guides/hld/hld-power-management.rst
View File

@ -74,7 +74,7 @@ The build flow is:
1) Use an offline tool (e.g. **iasl**) to parse the Px/Cx data and hard-code to 1) Use an offline tool (e.g. **iasl**) to parse the Px/Cx data and hard-code to
a CPU state table in the Hypervisor. The Hypervisor loads the data after a CPU state table in the Hypervisor. The Hypervisor loads the data after
system boots up. the system boots.
2) Before User VM launching, the Device mode queries the Px/Cx data from the Service 2) Before User VM launching, the Device mode queries the Px/Cx data from the Service
VM VHM via ioctl interface. VM VHM via ioctl interface.
3) VHM transmits the query request to the Hypervisor by hypercall. 3) VHM transmits the query request to the Hypervisor by hypercall.
@ -94,10 +94,10 @@ table) should be rejected.
It is better not to intercept C-state request because the trap would It is better not to intercept C-state request because the trap would
impact both power and performance. impact both power and performance.
.. note:: For P-state control you should pay attention to SoC core .. note:: For P-state control, you should pay attention to SoC core
voltage domain design when doing P-state measurement. The highest voltage domain design when doing P-state measurement. The highest
P-state would win if different P-state requests on the cores shared P-state would win if different P-state requests on the cores shared
same voltage domain. In this case APERF/MPERF must be used to see same voltage domain. In this case, APERF/MPERF must be used to see
what P-state was granted on that core. what P-state was granted on that core.
S3/S5 S3/S5
@ -111,14 +111,14 @@ assumptions:
4) Highest severity guest's power state is promoted to system power state. 4) Highest severity guest's power state is promoted to system power state.
5) Guest has lifecycle manager running to handle power state transaction 5) Guest has lifecycle manager running to handle power state transaction
requirement and initialize guest power state transaction. requirement and initialize guest power state transaction.
6) S3 is only available on configurations which has no DM launched RTVM. 6) S3 is only available on configurations that have no DM launched RTVM.
7) S3 is only supported at platform level - not VM level. 7) S3 is only supported at platform level - not VM level.
ACRN has a common implementation for notification between lifecycle manager ACRN has a common implementation for notification between lifecycle manager
in different guest. Which is vUART based cross-vm notification. But user in different guest. Which is vUART based cross-vm notification. But user
could customize it according to their hardware/software requirements. could customize it according to their hardware/software requirements.
:numref:`systempmdiag` shows the basic system level S3/S5 diagram :numref:`systempmdiag` shows the basic system level S3/S5 diagram.
.. figure:: images/hld-pm-image62.png .. figure:: images/hld-pm-image62.png
:align: center :align: center
@ -127,7 +127,7 @@ could customize it according to their hardware/software requirements.
ACRN System S3/S5 diagram ACRN System S3/S5 diagram
System low power state enter process System low power state entry process
==================================== ====================================
Each time, when lifecycle manager of User VM starts power state transition, Each time, when lifecycle manager of User VM starts power state transition,
@ -156,19 +156,19 @@ with typical ISD configuration(S3 follows very similar process)
:align: center :align: center
:name: pmworkflow :name: pmworkflow
ACRN system S5 enter workflow ACRN system S5 entry workflow
For system power state entry: For system power state entry:
1. Service VM received S5 request. 1. Service VM received S5 request.
2. Lifecycle manager in Service VM notify User VM1 and RTVM through 2. Lifecycle manager in Service VM notifies User VM1 and RTVM through
vUART for S5 request. vUART for S5 request.
3. Guest lifecycle manager initialize S5 action. And guest enter S5. 3. Guest lifecycle manager initializes S5 action and guest enters S5.
4. RTOS cleanup rt task, send response of S5 request back to Service 4. RTOS cleanup RT task, send response of S5 request back to Service
VM and RTVM enter S5. VM and RTVM enter S5.
5. After get response from RTVM and all User VM are shutdown, Service VM 5. After get response from RTVM and all User VM are shutdown, Service VM
enter S5. enter S5.
6. OSPM in ACRN hypervisor check all guest in S5 state and shutdown 6. OSPM in ACRN hypervisor checks all guests are in S5 state and shuts down
whole system. whole system.
System low power state exit process System low power state exit process

66
doc/developer-guides/hld/hld-security.rst
View File

@ -94,7 +94,7 @@ call these two OS systems "secure world" and
"non-secure world", and they are isolated from each other by the "non-secure world", and they are isolated from each other by the
hypervisor. Secure world has a higher "privilege level" than non-secure hypervisor. Secure world has a higher "privilege level" than non-secure
world; for example, the secure world can access the non-secure world's world; for example, the secure world can access the non-secure world's
physical memory but not vice-versa. This document discusses how this physical memory but not vice versa. This document discusses how this
security works and why it is required. security works and why it is required.
Careful consideration should be made when evaluating using the Service Careful consideration should be made when evaluating using the Service
@ -150,7 +150,7 @@ before launching.
2) Verified Boot Sequence with UEFI 2) Verified Boot Sequence with UEFI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As shown in :numref:`security-bootflow-uefi`, in this boot sequence,UEFI As shown in :numref:`security-bootflow-uefi`, in this boot sequence, UEFI
authenticates and starts the ACRN hypervisor firstly,and hypervisor will return authenticates and starts the ACRN hypervisor firstly,and hypervisor will return
to UEFI environment to authenticate and load Service VM kernel bootloader. to UEFI environment to authenticate and load Service VM kernel bootloader.
@ -184,7 +184,7 @@ The 2018 minimal requirements for cryptographic strength currently are:
#. RSA2048 for cryptographic digital signature signing and verification. #. RSA2048 for cryptographic digital signature signing and verification.
We strongly recommend that SHA512 and RSA3072+ be used for a product shipped We strongly recommend that SHA512 and RSA3072+ be used for a product shipped
in 2018, especially for a product which has a long production life such as in 2018, especially for a product that has a long production life such as
an automotive vehicle. an automotive vehicle.
The CSE FW image is signed with an Intel RSA private key. All other The CSE FW image is signed with an Intel RSA private key. All other
@ -216,9 +216,9 @@ UEFI Secure Boot is already supported by OVMF.
UEFI Secure Boot Overview UEFI Secure Boot Overview
UEFI Secure Boot is controlled by a set of UEFI Authenticated Variables which specify UEFI Secure Boot is controlled by a set of UEFI Authenticated Variables that specify
the UEFI Secure Boot Policy; the platform manufacturer or the platform owner enroll the the UEFI Secure Boot Policy; the platform manufacturer or the platform owner enrolls the
policy objects, which includes the n-tuple of keys {PK, KEK, db,dbx} as step 1. policy objects, which include the n-tuple of keys {PK, KEK, db,dbx} as step 1.
During each successive boot, the UEFI secure boot implementation will assess the During each successive boot, the UEFI secure boot implementation will assess the
policy in order to verify the signed images that are discovered in a host-bus adapter policy in order to verify the signed images that are discovered in a host-bus adapter
or on a disk. If the images pass policy, then they are invoked. or on a disk. If the images pass policy, then they are invoked.
@ -230,7 +230,7 @@ UEFI Secure Boot implementations use these keys:
#. Key Exchange Key (KEK) is used to sign Signature and Forbidden Signature Database updates. #. Key Exchange Key (KEK) is used to sign Signature and Forbidden Signature Database updates.
#. Signature Database (db) contains keys and/or hashes of allowed EFI binaries. #. Signature Database (db) contains keys and/or hashes of allowed EFI binaries.
And keys and certificates are in multiple format: And keys and certificates are in multiple formats:
#. `.key` PEM format private keys for EFI binary and EFI signature list signing. #. `.key` PEM format private keys for EFI binary and EFI signature list signing.
#. `.crt` PEM format certificates for sbsign. #. `.crt` PEM format certificates for sbsign.
@ -272,7 +272,7 @@ In practice, the Service VM designer and implementer should obey at least the
following rules: following rules:
#. Verify that the Service VM is a closed system and doesn't allow the user to #. Verify that the Service VM is a closed system and doesn't allow the user to
install any unauthorized 3rd-party software or components. install any unauthorized third-party software or components.
#. Verify that external peripherals are constrained. #. Verify that external peripherals are constrained.
#. Enable kernel-based hardening techniques, for example dm-verity (to #. Enable kernel-based hardening techniques, for example dm-verity (to
ensure integrity of the DM and vBIOS/vOSloaders), and kernel module ensure integrity of the DM and vBIOS/vOSloaders), and kernel module
@ -283,7 +283,7 @@ Detailed configurations and policies are out of scope for this document.
For good references on OS system security hardening and enhancement, For good references on OS system security hardening and enhancement,
see `AGL security see `AGL security
<https://docs.automotivelinux.org/docs/en/master/architecture/reference/security/part-2/0_Abstract.html>`_ <https://docs.automotivelinux.org/docs/en/master/architecture/reference/security/part-2/0_Abstract.html>`_
and `Android security <https://source.android.com/security/>`_ and `Android security <https://source.android.com/security/>`_.
Hypervisor Security Enhancement Hypervisor Security Enhancement
=============================== ===============================
@ -355,7 +355,7 @@ CR3 MMU paging tables, such as splitting hypervisor code and data
(stack/heap) sections, and then applying W |oplus| X policy, which means if memory (stack/heap) sections, and then applying W |oplus| X policy, which means if memory
is Writable, then the hypervisor must make it non-eXecutable. The is Writable, then the hypervisor must make it non-eXecutable. The
hypervisor must configure its code as read-only and executable, and hypervisor must configure its code as read-only and executable, and
configure its data as read-write. Optionally, if there are read-only configure its data as read/write. Optionally, if there are read-only
data sections, it would be best if the hypervisor configures them as data sections, it would be best if the hypervisor configures them as
read-only. read-only.
@ -421,7 +421,7 @@ three typical solutions exist:
behavior can be thwarted with a page fault (#PF) by the processor in the behavior can be thwarted with a page fault (#PF) by the processor in the
hypervisor. Whenever the hypervisor has a valid reason to have a write hypervisor. Whenever the hypervisor has a valid reason to have a write
access to user-accessible read-only memory (guest memory), it can access to user-accessible read-only memory (guest memory), it can
disable CR0.WP (clear CR0.WP) before writing, and afterwards set CR0.WP disable CR0.WP (clear CR0.WP) before writing, and then set CR0.WP
back to 1. back to 1.
This solution is better than the 1st solution above because it doesn't This solution is better than the 1st solution above because it doesn't
@ -451,7 +451,7 @@ mitigate many vulnerability exploits.
Guest Memory Execution Prevention Guest Memory Execution Prevention
+++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++
SMEP is designed to prevent user memory malicious code (typically SMEP is designed to prevent user memory malware (typically
attacker-supplied) from being executed in the kernel (Ring 0) privilege attacker-supplied) from being executed in the kernel (Ring 0) privilege
level. As long as the CR4.SMEP = 1, software operating in supervisor level. As long as the CR4.SMEP = 1, software operating in supervisor
mode cannot fetch instructions from linear addresses that are accessible mode cannot fetch instructions from linear addresses that are accessible
@ -466,7 +466,7 @@ In order to activate SMEP protection, the ACRN hypervisor must:
#. Configure all the guest memory as user-accessible memory (U/S = 1). #. Configure all the guest memory as user-accessible memory (U/S = 1).
No matter what settings for NX bit and R/W bit in corresponding host No matter what settings for NX bit and R/W bit in corresponding host
CR3 paging tables. CR3 paging tables.
#. Set CR4.SMEP bit. In the entire lifecycle of the hypervisor, this bit #. Set CR4.SMEP bit. In the entire life cycle of the hypervisor, this bit
value always remains one. value always remains one.
As an alternative, NX feature is used for this purpose by setting the As an alternative, NX feature is used for this purpose by setting the
@ -481,7 +481,7 @@ Guest Memory Access Prevention
++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++
Supervisor Mode Access Prevention (SMAP) is yet another powerful Supervisor Mode Access Prevention (SMAP) is yet another powerful
processor feature which makes it harder for malicious programs to processor feature that makes it harder for malware to
"trick" the kernel into using instructions or data from a user-space "trick" the kernel into using instructions or data from a user-space
application program. application program.
@ -505,7 +505,7 @@ To activate SMAP protection in the ACRN hypervisor:
#. Configure all the guest memory as user-writable memory (U/S bit = 1, #. Configure all the guest memory as user-writable memory (U/S bit = 1,
and R/W bit = 1) in corresponding host CR3 paging table entries, as and R/W bit = 1) in corresponding host CR3 paging table entries, as
shown in :numref:`security-smap` below. shown in :numref:`security-smap` below.
#. Set CR4.SMAP bit. In the entire lifecycle of the hypervisor, this bit #. Set CR4.SMAP bit. In the entire life cycle of the hypervisor, this bit
value always remains one. value always remains one.
#. When needed, use STAC instruction to suppress SMAP protection, and #. When needed, use STAC instruction to suppress SMAP protection, and
use CLAC instruction to restore SMAP protection. use CLAC instruction to restore SMAP protection.
@ -548,8 +548,8 @@ an arbitrary amount of data to or from VM memory area.
Whenever the hypervisor needs to perform legitimate read/write access to Whenever the hypervisor needs to perform legitimate read/write access to
guest memory pages, one of functions above must be used. Otherwise, the guest memory pages, one of functions above must be used. Otherwise, the
#PF will be triggered by the processor to prevent malicious or #PF will be triggered by the processor to prevent malware or
unintended access from/to the guest memory pages. unintended access from or to the guest memory pages.
These functions must also internally check the address availabilities, These functions must also internally check the address availabilities,
for example, ensuring the input address accessed by the hypervisor must have for example, ensuring the input address accessed by the hypervisor must have
@ -574,7 +574,7 @@ Memory content from one guest VM might be leaked to another guest VM. So
in ACRN and Device Model design, when one guest VM is destroyed or in ACRN and Device Model design, when one guest VM is destroyed or
crashes, its memory content should be scrubbed either by the hypervisor crashes, its memory content should be scrubbed either by the hypervisor
or the Service VM device model process, in case its memory content is or the Service VM device model process, in case its memory content is
re-allocated to another guest VM which could otherwise leave the re-allocated to another guest VM that could otherwise leave the
previous guest VM secrets in memory. previous guest VM secrets in memory.
.. _secure-hypervisor-interface: .. _secure-hypervisor-interface:
@ -639,12 +639,12 @@ guest VM. The hypervisor then emulates the MMIO instructions with design
behaviors. behaviors.
As done for I/O emulation, this interface could also be manipulated by As done for I/O emulation, this interface could also be manipulated by
malicious software in guest VM to compromise system security. malware in guest VM to compromise system security.
Other VMEXIT Handlers Other VMEXIT Handlers
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
There are some other VMEXIT handlers in the hypervisor which might take There are some other VMEXIT handlers in the hypervisor that might take
untrusted parameters and registers from guest VM, for example, MSR write untrusted parameters and registers from guest VM, for example, MSR write
VMEXIT, APIC VMEXIT. VMEXIT, APIC VMEXIT.
@ -682,7 +682,7 @@ User VM Power On and Shutdown
The memory of the User VM is allocated dynamically by the DM The memory of the User VM is allocated dynamically by the DM
process in the Service VM before the User VM is launched. When the User VM process in the Service VM before the User VM is launched. When the User VM
is shutdown (or crashed), its memory will be freed to Service VM memory space. is shut down (or crashed), its memory will be freed to Service VM memory space.
Later on, if there is a new User VM launch event occurring, DM may potentially allocate Later on, if there is a new User VM launch event occurring, DM may potentially allocate
the same memory content (or some overlaps) for this new User VM. the same memory content (or some overlaps) for this new User VM.
@ -696,12 +696,12 @@ access the previous User VM's secrets by scanning the memory regions
allocated for the new User VM. allocated for the new User VM.
In ACRN, the memory content is scrubbed in Device Model after the guest In ACRN, the memory content is scrubbed in Device Model after the guest
VM is shutdown. VM is shut down.
User VM Reboot User VM Reboot
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
The behaviors of **cold** boot of virtual User VM reboot is the same as that of The behaviors of **cold** boot of virtual User VM reboot are the same as that of
previous virtual power-on and shutdown events. There is a special case: previous virtual power-on and shutdown events. There is a special case:
virtual **warm** reboot. virtual **warm** reboot.
@ -730,7 +730,7 @@ enabling the configuration.
User VM Suspend/Resume User VM Suspend/Resume
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
There is no special design considerations for normal User VM without secure There are no special design considerations for normal User VM without secure
world supported, as long as the EPT/VT-d memory protection/isolation is world supported, as long as the EPT/VT-d memory protection/isolation is
active during the entire suspended time. active during the entire suspended time.
@ -740,7 +740,7 @@ Service VM, the memory content of secure world of User VM must not be visible to
Service VM. This is designed for security with defense in depth. Service VM. This is designed for security with defense in depth.
During the entire process of User VM sleep/suspend, the memory protection During the entire process of User VM sleep/suspend, the memory protection
for secure-world is preserved too.The physical memory region of for secure-world is preserved too. The physical memory region of
secure world is removed from EPT paging tables of any guest VM, secure world is removed from EPT paging tables of any guest VM,
even including the Service VM. even including the Service VM.
@ -791,9 +791,9 @@ The parameters of HDKF derivation in the hypervisor are:
#. OutSeedLen = 64 in bytes #. OutSeedLen = 64 in bytes
#. Guest Dev and User SEED (dvSEED/uvSEED) #. Guest Dev and User SEED (dvSEED/uvSEED)
dvSEED = HKDF(theHash, nil, dSEEd, VMInfo\|"devseed", OutSeedLen) ``dvSEED = HKDF(theHash, nil, dSEEd, VMInfo\|"devseed", OutSeedLen)``
uvSEED = HKDF(theHash, nil, uSEEd, VMInfo\|"userseed", OutSeedLen ``uvSEED = HKDF(theHash, nil, uSEEd, VMInfo\|"userseed", OutSeedLen)``
.. _secure_trusty: .. _secure_trusty:
@ -805,7 +805,7 @@ guest VM such as the Android User VM. (See :ref:`trusty_tee` for more
information.) information.)
On the APL platform, the secure world is used to run a On the APL platform, the secure world is used to run a
virtualization-based Trusty TEE in an isolated world which serves virtualization-based Trusty TEE in an isolated world that serves
Android as a guest (AaaG,) to get Google's Android relevant certificates Android as a guest (AaaG,) to get Google's Android relevant certificates
by fulfilling Android CDD requirements. Also as a plan, Trusty will be by fulfilling Android CDD requirements. Also as a plan, Trusty will be
supported to provide security services for LaaG User VM as well. supported to provide security services for LaaG User VM as well.
@ -868,7 +868,7 @@ configuration.
To save page tables and share the mappings for non-secure world address To save page tables and share the mappings for non-secure world address
space, the hypervisor relocates the Secure World's GPA to a very high space, the hypervisor relocates the Secure World's GPA to a very high
position: 511G-512G. Hence, the PML4 for Trusty World are separated from position: 511G-512G. Hence, the PML4 for Trusty World is separated from
non-secure World. PDPT/PD/PT for low memory (<511G) are shared in both non-secure World. PDPT/PD/PT for low memory (<511G) are shared in both
Trusty World's EPT and non-secure World's EPT. PDPT/PD/PT for high Trusty World's EPT and non-secure World's EPT. PDPT/PD/PT for high
memory (>=511G) are valid for Trusty World's EPT only. memory (>=511G) are valid for Trusty World's EPT only.
@ -892,7 +892,7 @@ Hypercall - Trusty Initialization
When a User VM is created by the DM in the Service VM, if this User VM When a User VM is created by the DM in the Service VM, if this User VM
supports a secure isolated world, then this hypercall will be invoked supports a secure isolated world, then this hypercall will be invoked
by OSLoader(it could be Android OS loader in :numref:`security-bootflow-sbl` and by OSLoader(it could be Android OS loader in :numref:`security-bootflow-sbl` and
:numref:`security-bootflow-uefi` above) to create / initialize the :numref:`security-bootflow-uefi` above) to create or initialize the
secure world (Trusty/TEE). secure world (Trusty/TEE).
.. figure:: images/security-image9.png .. figure:: images/security-image9.png
@ -905,18 +905,18 @@ secure world (Trusty/TEE).
In :numref:`security-start-flow` above, the OSLoader is responsible for In :numref:`security-start-flow` above, the OSLoader is responsible for
loading TEE/Trusty image to a dedicated and reserved memory region, and loading TEE/Trusty image to a dedicated and reserved memory region, and
locating its entry point of TEE/Trusty executable, then executes a locating its entry point of TEE/Trusty executable, then executes a
hypercall which exits to the hypervisor handler. hypercall that exits to the hypervisor handler.
In the hypervisor, from a security perspective, it removes GPA->HPA In the hypervisor, from a security perspective, it removes GPA->HPA
mapping of secure world from EPT paging tables of both User VM non-secure mapping of secure world from EPT paging tables of both User VM non-secure
world and even Service VM. This is intended to disallow non-secure world and world and even Service VM. This is intended to disallow non-secure world and
Service VM to access the memory region of secure world for security reasons as Service VM to access the memory region of secure world for security reasons as
previously mentioned previously mentioned.
After all is set up by the hypervisor, including vCPU context After all is set up by the hypervisor, including vCPU context
initialization, the hypervisor eventually does vmresume (step 4 in initialization, the hypervisor eventually does vmresume (step 4 in
:numref:`security-start-flow` above) to the entry point of secure world :numref:`security-start-flow` above) to the entry point of secure world
TEE/Trusty, then Trusty OS gets started in vmx non-root mode to TEE/Trusty, then Trusty OS gets started in VMX non-root mode to
initialize itself, and loads its TAs (Trusted Applications) so that the initialize itself, and loads its TAs (Trusted Applications) so that the
security services can be ready right before non-secure OS gets started. security services can be ready right before non-secure OS gets started.

18
doc/developer-guides/hld/hld-trace-log.rst
View File

@ -22,10 +22,10 @@ are two use scenarios of Sbuf:
Both ACRNTrace and ACRNLog use sbuf as a lockless ring buffer. The Sbuf Both ACRNTrace and ACRNLog use sbuf as a lockless ring buffer. The Sbuf
is allocated by Service VM and assigned to HV via a hypercall. To hold pointers is allocated by Service VM and assigned to HV via a hypercall. To hold pointers
to sbuf passed down via hypercall, an array ``sbuf[ACRN_SBUF_ID_MAX]`` to sbuf passed down via hypercall, an array ``sbuf[ACRN_SBUF_ID_MAX]``
is defined in per_cpu region of HV, with predefined sbuf id to identify is defined in per_cpu region of HV, with predefined sbuf ID to identify
the usage, such as ACRNTrace, ACRNLog, etc. the usage, such as ACRNTrace, ACRNLog, etc.
For each physical CPU there is a dedicated Sbuf. Only a single producer For each physical CPU, there is a dedicated Sbuf. Only a single producer
is allowed to put data into that Sbuf in HV, and a single consumer is is allowed to put data into that Sbuf in HV, and a single consumer is
allowed to get data from Sbuf in Service VM. Therefore, no lock is required to allowed to get data from Sbuf in Service VM. Therefore, no lock is required to
synchronize access by the producer and consumer. synchronize access by the producer and consumer.
@ -33,7 +33,7 @@ synchronize access by the producer and consumer.
sbuf APIs sbuf APIs
========= =========
The sbuf APIs are defined in ``hypervisor/include/debug/sbuf.h`` The sbuf APIs are defined in ``hypervisor/include/debug/sbuf.h``.
ACRN Trace ACRN Trace
@ -77,7 +77,7 @@ Service VM Trace Module
The Service VM trace module is responsible for: The Service VM trace module is responsible for:
- allocating sbuf in Service VM memory range for each physical CPU, and assign - allocating sbuf in Service VM memory range for each physical CPU, and assign
the gpa of Sbuf to ``per_cpu sbuf[ACRN_TRACE]`` the GPA of Sbuf to ``per_cpu sbuf[ACRN_TRACE]``
- create a misc device for each physical CPU - create a misc device for each physical CPU
- provide mmap operation to map entire Sbuf to userspace for high - provide mmap operation to map entire Sbuf to userspace for high
flexible and efficient access. flexible and efficient access.
@ -104,7 +104,7 @@ Once ACRNTrace is launched, for each physical CPU a consumer thread is
created to periodically read RAW trace data from sbuf and write to a created to periodically read RAW trace data from sbuf and write to a
file. file.
.. note:: figure is missing .. note:: TODO figure is missing
Figure 2.2 Sequence of trace init and trace data collection Figure 2.2 Sequence of trace init and trace data collection
These are the Python scripts provided: These are the Python scripts provided:
@ -113,7 +113,7 @@ These are the Python scripts provided:
text offline according to given format; text offline according to given format;
- **acrnalyze.py** analyzes trace data (as output by acrntrace) - **acrnalyze.py** analyzes trace data (as output by acrntrace)
based on given analyzer filters, such as vm_exit or irq, and generates a based on given analyzer filters, such as vm_exit or IRQ, and generates a
report. report.
See :ref:`acrntrace` for details and usage. See :ref:`acrntrace` for details and usage.
@ -122,7 +122,7 @@ ACRN Log
******** ********
acrnlog is a tool used to capture ACRN hypervisor log to files on acrnlog is a tool used to capture ACRN hypervisor log to files on
Service VM filesystem. It can run as an Service VM service at boot, capturing two Service VM filesystem. It can run as a Service VM service at boot, capturing two
kinds of logs: kinds of logs:
- Current runtime logs; - Current runtime logs;
@ -179,7 +179,7 @@ at runtime via hypervisor shell command "loglevel".
The element size of sbuf for logs is fixed at 80 bytes, and the max size The element size of sbuf for logs is fixed at 80 bytes, and the max size
of a single log message is 320 bytes. Log messages with a length between of a single log message is 320 bytes. Log messages with a length between
80 and 320 bytes will be separated into multiple sbuf elements. Log 80 and 320 bytes will be separated into multiple sbuf elements. Log
messages with length larger then 320 will be truncated. messages with length larger than 320 will be truncated.
For security, Service VM allocates sbuf in its memory range and assigns it to For security, Service VM allocates sbuf in its memory range and assigns it to
the hypervisor. the hypervisor.
@ -200,7 +200,7 @@ On Service VM boot, Service VM acrnlog module is responsible to:
these last logs these last logs
- construct sbuf in the usable buf range for each physical CPU, - construct sbuf in the usable buf range for each physical CPU,
assign the gpa of Sbuf to ``per_cpu sbuf[ACRN_LOG]`` and create a misc assign the GPA of Sbuf to ``per_cpu sbuf[ACRN_LOG]`` and create a misc
device for each physical CPU device for each physical CPU
- the misc devices implement read() file operation to allow - the misc devices implement read() file operation to allow

34
doc/developer-guides/hld/hld-virtio-devices.rst
View File

@ -55,7 +55,7 @@ hypervisor. Virtio was developed by Rusty Russell when he worked at IBM
research to support his lguest hypervisor in 2007, and it quickly became research to support his lguest hypervisor in 2007, and it quickly became
the de facto standard for KVM's para-virtualized I/O devices. the de facto standard for KVM's para-virtualized I/O devices.
Virtio is very popular for virtual I/O devices because is provides a Virtio is very popular for virtual I/O devices because it provides a
straightforward, efficient, standard, and extensible mechanism, and straightforward, efficient, standard, and extensible mechanism, and
eliminates the need for boutique, per-environment, or per-OS mechanisms. eliminates the need for boutique, per-environment, or per-OS mechanisms.
For example, rather than having a variety of device emulation For example, rather than having a variety of device emulation
@ -126,9 +126,9 @@ Standard: virtqueue
The virtqueues are created in guest physical memory by the FE drivers. The virtqueues are created in guest physical memory by the FE drivers.
BE drivers only need to parse the virtqueue structures to obtain BE drivers only need to parse the virtqueue structures to obtain
the requests and process them. How a virtqueue is organized is the requests and process them. The virtqueue organization is
specific to the Guest OS. In the Linux implementation of virtio, the specific to the Guest OS. In the Linux implementation of virtio, the
virtqueue is implemented as a ring buffer structure called vring. virtqueue is implemented as a ring buffer structure called `vring``.
In ACRN, the virtqueue APIs can be leveraged directly so that users In ACRN, the virtqueue APIs can be leveraged directly so that users
don't need to worry about the details of the virtqueue. (Refer to guest don't need to worry about the details of the virtqueue. (Refer to guest
@ -178,8 +178,8 @@ Virtio Device Discovery
Virtio Frameworks Virtio Frameworks
***************** *****************
This section describes the overall architecture of virtio, and then This section describes the overall architecture of virtio, and
introduce ACRN specific implementations of the virtio framework. introduces the ACRN-specific implementations of the virtio framework.
Architecture Architecture
============ ============
@ -223,7 +223,7 @@ can be classified into two types, virtio backend service in user-land
where the virtio backend service (VBS) is located. Although different in BE where the virtio backend service (VBS) is located. Although different in BE
drivers, both VBS-U and VBS-K share the same FE drivers. The reason drivers, both VBS-U and VBS-K share the same FE drivers. The reason
behind the two virtio implementations is to meet the requirement of behind the two virtio implementations is to meet the requirement of
supporting a large amount of diverse I/O devices in ACRN project. supporting a large number of diverse I/O devices in ACRN project.
When developing a virtio BE device driver, the device owner should choose When developing a virtio BE device driver, the device owner should choose
carefully between the VBS-U and VBS-K. Generally VBS-U targets carefully between the VBS-U and VBS-K. Generally VBS-U targets
@ -288,7 +288,7 @@ for feature negotiations between FE and BE drivers. This means the
"control plane" of the virtio device still remains in VBS-U. When "control plane" of the virtio device still remains in VBS-U. When
feature negotiation is done, which is determined by FE driver setting up feature negotiation is done, which is determined by FE driver setting up
an indicative flag, VBS-K module will be initialized by VBS-U. an indicative flag, VBS-K module will be initialized by VBS-U.
Afterwards, all request handling will be offloaded to the VBS-K in Afterward, all request handling will be offloaded to the VBS-K in
kernel. kernel.
Finally the FE driver is not aware of how the BE driver is implemented, Finally the FE driver is not aware of how the BE driver is implemented,
@ -336,8 +336,8 @@ can be described as:
device: device:
a) Ioevenftd is bound with a PIO/MMIO range. If it is a PIO, it is a) Ioevenftd is bound with a PIO/MMIO range. If it is a PIO, it is
registered with (fd, port, len, value). If it is a MMIO, it is registered with ``(fd, port, len, value)``. If it is an MMIO, it is
registered with (fd, addr, len). registered with ``(fd, addr, len)``.
b) Irqfd is registered with MSI vector. b) Irqfd is registered with MSI vector.
3. vhost proxy sets the two fds to vhost kernel through ioctl of vhost 3. vhost proxy sets the two fds to vhost kernel through ioctl of vhost
@ -362,20 +362,20 @@ general workflow of ioeventfd.
The workflow can be summarized as: The workflow can be summarized as:
1. vhost device init. Vhost proxy create two eventfd for ioeventfd and 1. vhost device init. Vhost proxy creates two eventfd for ioeventfd and
irqfd. irqfd.
2. pass ioeventfd to vhost kernel driver. 2. pass ioeventfd to vhost kernel driver.
3. pass ioevent fd to vhm driver 3. pass ioevent fd to vhm driver
4. User VM FE driver triggers ioreq and forwarded to Service VM by hypervisor 4. User VM FE driver triggers ioreq and forwarded to Service VM by hypervisor
5. ioreq is dispatched by vhm driver to related vhm client. 5. ioreq is dispatched by vhm driver to related vhm client.
6. ioeventfd vhm client traverse the io_range list and find 6. ioeventfd vhm client traverses the io_range list and find
corresponding eventfd. corresponding eventfd.
7. trigger the signal to related eventfd. 7. trigger the signal to related eventfd.
Irqfd implementation Irqfd implementation
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
The irqfd module is implemented in VHM, and can enhance an registered The irqfd module is implemented in VHM, and can enhance a registered
eventfd to inject an interrupt to a guest OS when the eventfd gets eventfd to inject an interrupt to a guest OS when the eventfd gets
signaled. :numref:`irqfd-workflow` shows the general flow for irqfd. signaled. :numref:`irqfd-workflow` shows the general flow for irqfd.
@ -387,7 +387,7 @@ signaled. :numref:`irqfd-workflow` shows the general flow for irqfd.
The workflow can be summarized as: The workflow can be summarized as:
1. vhost device init. Vhost proxy create two eventfd for ioeventfd and 1. vhost device init. Vhost proxy creates two eventfd for ioeventfd and
irqfd. irqfd.
2. pass irqfd to vhost kernel driver. 2. pass irqfd to vhost kernel driver.
3. pass irq fd to vhm driver 3. pass irq fd to vhm driver
@ -395,8 +395,8 @@ The workflow can be summarized as:
transfer is completed. transfer is completed.
5. irqfd related logic traverses the irqfd list to retrieve related irq 5. irqfd related logic traverses the irqfd list to retrieve related irq
information. information.
6. irqfd related logic inject an interrupt through vhm interrupt API. 6. irqfd related logic injects an interrupt through vhm interrupt API.
7. interrupt is delivered to User VM FE driver through hypervisor. 7. Interrupt is delivered to User VM FE driver through hypervisor.
.. _virtio-APIs: .. _virtio-APIs:
@ -464,7 +464,7 @@ relationships are shown in :numref:`VBS-K-data`.
A single virtqueue information to be A single virtqueue information to be
synchronized from VBS-U to VBS-K kernel module. synchronized from VBS-U to VBS-K kernel module.
``struct vbs_k_vqs_info`` ``struct vbs_k_vqs_info``
Virtqueue(s) information, of a virtio device, Virtqueue information, of a virtio device,
to be synchronized from VBS-U to VBS-K kernel module. to be synchronized from VBS-U to VBS-K kernel module.
.. figure:: images/virtio-hld-image8.png .. figure:: images/virtio-hld-image8.png
@ -480,7 +480,7 @@ to open and register device status after feature negotiation with the FE
driver. driver.
The device status includes negotiated features, number of virtqueues, The device status includes negotiated features, number of virtqueues,
interrupt information, and more. All these status will be synchronized interrupt information, and more. All these statuses will be synchronized
from VBS-U to VBS-K. In VBS-U, the ``struct vbs_k_dev_info`` and ``struct from VBS-U to VBS-K. In VBS-U, the ``struct vbs_k_dev_info`` and ``struct
vbs_k_vqs_info`` will collect all the information and notify VBS-K through vbs_k_vqs_info`` will collect all the information and notify VBS-K through
ioctls. In VBS-K, the ``struct vbs_k_dev`` and ``struct vbs_k_vq``, which are ioctls. In VBS-K, the ``struct vbs_k_dev`` and ``struct vbs_k_vq``, which are

6
doc/developer-guides/hld/index.rst
View File

@ -3,10 +3,10 @@
High-Level Design Guides High-Level Design Guides
######################## ########################
The ACRN Hypervisor acts as a host with full control of the processor(s) The ACRN Hypervisor acts as a host with full control of the processors
and the hardware (physical memory, interrupt management and I/O). It and the hardware (physical memory, interrupt management, and I/O). It
provides the User OS with an abstraction of a virtual platform, allowing provides the User OS with an abstraction of a virtual platform, allowing
the guest to behave as if were executing directly on a logical the guest to behave as if it were executing directly on a physical
processor. processor.
These chapters describe the ACRN architecture, high-level design, These chapters describe the ACRN architecture, high-level design,

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

@ -14,10 +14,10 @@ Refer to `Intel Analysis of L1TF`_ and `Linux L1TF document`_ for details.
.. _Linux L1TF document: .. _Linux L1TF document:
https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/l1tf.html https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/l1tf.html
L1 Terminal Fault is a speculative side channel which allows unprivileged L1 Terminal Fault is a speculative side channel that allows unprivileged
speculative access to data which is available in the Level 1 Data Cache speculative access to data that is available in the Level 1 Data Cache
when the page table entry controlling the virtual address, which is used when the page table entry controlling the virtual address, used
for the access, has the Present bit cleared or reserved bits set. for the access, has the present bit cleared or reserved bits set.
When the processor accesses a linear address, it first looks for a When the processor accesses a linear address, it first looks for a
translation to a physical address in the translation lookaside buffer (TLB). translation to a physical address in the translation lookaside buffer (TLB).
@ -77,7 +77,7 @@ 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 may 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
multi threading (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 make 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 which
@ -93,7 +93,7 @@ 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 (default policy in ACRN), there is
1:1 mapping between vCPUs and pCPUs i.e. no sharing of pCPU. There 1:1 mapping between vCPUs and pCPUs i.e. no sharing of pCPU. There
may be an attack possibility when Hyper-threading is on, where may be an attack possibility when Hyper-threading is on, where
logical processors of same physical core may be allocated to two logical processors of the same physical core may be allocated to two
different guests. Then one guest may be able to attack the other guest different guests. Then one guest may be able to attack the other guest
on sibling thread due to shared L1D. on sibling thread due to shared L1D.
@ -167,7 +167,7 @@ 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
which has present bit cleared or reserved bits set. which has 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 set PFN bits to ZERO, which
means page ZERO might fall into risk if containing security info. means page ZERO might fall into risk if containing security info.
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 be used by anybody for valid usage. This sanitization logic won't be used by anybody for valid usage. This sanitization logic
@ -189,7 +189,7 @@ other security 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 into un-cached memory. As the content will data can be put into un-cached memory. As the content will
never go to L1D, it is immune to L1TF attack never go to L1D, it is immune to 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
@ -242,7 +242,7 @@ 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 pre-configured environment,
where the whole software stack (from ACRN hypervisor to guest where the whole software stack (from ACRN hypervisor to guest
kernel to Service VM root) is tightly controlled by solution provider kernel to Service VM root) is tightly controlled by solution provider
and not allowed for run-time change after sale (guest kernel is and not allowed for run time change after sale (guest kernel is
trusted). In that case solution provider will make sure that guest trusted). In that case solution provider will make sure that guest
kernel is up-to-date including necessary page table sanitization, kernel is up-to-date including necessary page table sanitization,
thus there is no attack interface exposed within guest. Then a thus there is no attack interface exposed within guest. Then a

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

@ -51,7 +51,7 @@ be resolved by design.
`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 if 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 can
be regarded as an exception if it is well justified and a work around is 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
@ -81,8 +81,8 @@ The components are listed as follows.
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 abstract hardware * **Hardware Management and Utilities** This component abstracts hardware
resources and provide services like 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 events
@ -95,14 +95,14 @@ The components are listed as follows.
* **Passthrough Management** This component manages devices that are passed-through * **Passthrough Management** This component manages devices that are passed-through
to specific VMs. 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 allow the hypervisor to forward I/O accesses from a User mechanism that allows 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 start up subroutines in the other components to bring up the hypervisor and
Service VM in sharing mode or all the VMs in partitioning mode. start the Service VM in sharing mode or all the VMs in partitioning mode.
ACRN hypervisor adopts a layered design where higher layers can invoke the 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

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

@ -29,7 +29,7 @@ below:
Pre-conditions shall be defined right before the definition/declaration of Pre-conditions shall be defined right before the definition/declaration of
the corresponding function in the C source file or header file. the corresponding function in the C source file or header file.
All pre-conditions shall be guaranteed by the caller of the function. All pre-conditions shall be guaranteed by the caller of the function.
Error checking of the pre-conditions are not needed in release version of the Error checking of the pre-conditions is not needed in release version of the
function. Developers could use ASSERT to catch design errors in a debug function. Developers could use ASSERT to catch design errors in a debug
version for some cases. Verification of the hypervisor shall check whether version for some cases. Verification of the hypervisor shall check whether
each caller guarantees all pre-conditions of the callee (or not). each caller guarantees all pre-conditions of the callee (or not).
@ -44,7 +44,7 @@ below:
the corresponding function in the C source file or header file. the corresponding function in the C source file or header file.
All post-conditions shall be guaranteed by the function. All callers of the All post-conditions shall be guaranteed by the function. All callers of the
function should trust these post-conditions are met. function should trust these post-conditions are met.
Error checking of the post-conditions are 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 the
function guarantees all post-conditions (or not). function guarantees all post-conditions (or not).
@ -73,7 +73,7 @@ below:
- Configuration data defined by external safety application, such as physical - Configuration data defined by external safety application, such as physical
PCI device information specific for each board design. PCI device information specific for each board design.
- Input data which is only specified by external safety application. - Input data that is only specified 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 safety VM,
the application constraint isn't applicable to these data. Related error checking the application constraint isn't applicable to these data. Related error checking
@ -89,7 +89,7 @@ Functional Safety Consideration
------------------------------- -------------------------------
The hypervisor will do range check in hypercalls and HW capability checks The hypervisor will do range check in hypercalls and HW capability checks
according to Table A.2 of FuSa Standards [IEC_61508-3_2010]_ . according to Table A.2 of FuSA Standards [IEC_61508-3_2010]_.
Error Handling Methods Error Handling Methods
---------------------- ----------------------
@ -162,7 +162,7 @@ shown in :numref:`rules_arch_level` below.
+====================+=========================+==============+===========================+=========================+ +====================+=========================+==============+===========================+=========================+
| External resource | Invalid register/memory | Yes | Follow SDM strictly, or | Unsupported MSR | | External resource | Invalid register/memory | Yes | Follow SDM strictly, or | Unsupported MSR |
| provided by VM | state on VM exit | | state any deviation to the| or invalid CPU ID | | provided by VM | state on VM exit | | state any deviation to the| or invalid CPU ID |
| | | | document explicitly | | | | | | document explicitly. | |
| +-------------------------+--------------+---------------------------+-------------------------+ | +-------------------------+--------------+---------------------------+-------------------------+
| | Invalid hypercall | Yes | The hypervisor shall | Invalid hypercall | | | Invalid hypercall | Yes | The hypervisor shall | Invalid hypercall |
| | parameter | | return related error code | parameter provided by | | | parameter | | return related error code | parameter provided by |
@ -176,12 +176,12 @@ shown in :numref:`rules_arch_level` below.
+--------------------+-------------------------+--------------+---------------------------+-------------------------+ +--------------------+-------------------------+--------------+---------------------------+-------------------------+
| External resource | Invalid E820 table or | Yes | The hypervisor shall | Invalid E820 table or | | External resource | Invalid E820 table or | Yes | The hypervisor shall | Invalid E820 table or |
| provided by | invalid boot information| | panic during platform | invalid boot information| | provided by | invalid boot information| | panic during platform | invalid boot information|
| bootloader | | | initialization | | | bootloader | | | initialization. | |
| (GRUB or SBL) | | | | | | (GRUB or SBL) | | | | |
+--------------------+-------------------------+--------------+---------------------------+-------------------------+ +--------------------+-------------------------+--------------+---------------------------+-------------------------+
| Physical resource | 1GB page is not | Yes | The hypervisor shall | 1GB page is not | | Physical resource | 1GB page is not | Yes | The hypervisor shall | 1GB page is not |
| used by the | available on the | | panic during platform | available on the | | used by the | available on the | | panic during platform | available on the |
| hypervisor | platform or invalid | | initialization | platform or invalid | | hypervisor | platform or invalid | | initialization. | platform or invalid |
| | physical CPU ID | | | physical CPU ID | | | physical CPU ID | | | physical CPU ID |
+--------------------+-------------------------+--------------+---------------------------+-------------------------+ +--------------------+-------------------------+--------------+---------------------------+-------------------------+
@ -212,7 +212,7 @@ 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.
Here is the sample codes for error checking before calling ``vcpu_from_vid``: Here is the sample code for error checking before calling ``vcpu_from_vid``:
.. code-block:: c .. code-block:: c
@ -240,7 +240,7 @@ Functional Safety Consideration
Data verification, and explicit specification of pre-conditions and post-conditions Data verification, and explicit specification of pre-conditions and post-conditions
are applied for internal functions of the hypervisor according to Table A.4 of are applied for internal functions of the hypervisor according to Table A.4 of
FuSa Standards [IEC_61508-3_2010]_ . FuSA Standards [IEC_61508-3_2010]_ .
Error Handling Methods Error Handling Methods
---------------------- ----------------------
@ -275,12 +275,13 @@ The rules of error detection and error handling on a module level are shown in
+====================+===========+============================+===========================+=========================+ +====================+===========+============================+===========================+=========================+
| Internal data of | N/A | Partial. | The hypervisor shall use | virtual PCI device | | Internal data of | N/A | Partial. | The hypervisor shall use | virtual PCI device |
| the hypervisor | | The related pre-conditions | the internal resource/data| information, defined | | the hypervisor | | The related pre-conditions | the internal resource/data| information, defined |
| | | are required. | directly. | with array 'pci_vdevs[]'| | | | are required. | directly. | with array |
| | | | | ``pci_vdevs[]`` |
| | | The design will guarantee | | through static | | | | The design will guarantee | | through static |
| | | the correctness and the | | allocation. | | | | the correctness and the | | allocation. |
| | | test cases will verify the | | | | | | test cases will verify the | | |
| | | related pre-conditions. | | | | | | related pre-conditions. | | |
| | | If the design can not | | | | | | If the design cannot | | |
| | | guarantee the correctness, | | | | | | guarantee the correctness, | | |
| | | the related error handling | | | | | | the related error handling | | |
| | | codes need to be added. | | | | | | codes need to be added. | | |
@ -290,7 +291,7 @@ The rules of error detection and error handling on a module level are shown in
| | | array size and non-null | | | | | | array size and non-null | | |
| | | pointer. | | | | | | pointer. | | |
+--------------------+-----------+----------------------------+---------------------------+-------------------------+ +--------------------+-----------+----------------------------+---------------------------+-------------------------+
| Configuration data | Corrupted | No. | The bootloader initializes| 'vm_config->pci_devs' | | Configuration data | Corrupted | No. | The bootloader initializes| ``vm_config->pci_devs`` |
| of the VM | VM config | The related pre-conditions | hypervisor (including | is configured | | of the VM | VM config | The related pre-conditions | hypervisor (including | is configured |
| | | are required. | code, data, and bss) and | statically. | | | | are required. | code, data, and bss) and | statically. |
| | | Note: VM configuration data| verifies the integrity of | | | | | Note: VM configuration data| verifies the integrity of | |
@ -315,7 +316,7 @@ Examples
Here are some examples to illustrate when error handling codes are required on Here are some examples to illustrate when error handling codes are required on
a module level. a module level.
**Example_1: Analyze the function 'partition_mode_vpci_init'** **Example_1: Analyze the function ``partition_mode_vpci_init``**
.. code-block:: c .. code-block:: c
@ -374,53 +375,53 @@ pre-conditions and ``get_vm_config`` itself shall guarantee the post-condition.
return &vm_configs[vm_id]; return &vm_configs[vm_id];
} }
**Question_1: Is error checking required for 'vm_config'?** **Question_1: Is error checking required for ``vm_config``?**
No. Because 'vm_config' is getting data from ``get_vm_config`` and the No. Because ``vm_config`` is getting data from ``get_vm_config`` and the
post-condition of ``get_vm_config`` guarantees that the return value is not NULL. post-condition of ``get_vm_config`` guarantees that the return value is not NULL.
**Question_2: Is error checking required for 'vdev'?** **Question_2: Is error checking required for ``vdev``?**
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`` is not
NULL. It indicates that 'vpci' is not NULL. Since 'vdev' is getting data from NULL. It indicates that ``vpci`` is not NULL. Since ``vdev`` is getting data from
the array 'pci_vdevs[]' via indexing, 'vdev' is not NULL as long as the index the array ``pci_vdevs[]`` via indexing, ``vdev`` is not NULL as long as the index
is valid. 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 ``vpci->pci_vdev_cnt``
is less than or equal to 'CONFIG_MAX_PCI_DEV_NUM', which is the array size of is less than or equal to ``CONFIG_MAX_PCI_DEV_NUM``, which is the array size of
'pci_vdevs[]'. It indicates that the index used to get 'vdev' is always ``pci_vdevs[]``. It indicates that the index used to get ``vdev`` is always
valid. 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 checking
codes are not required for 'vdev'. 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 is the
physical PCI device information coming from Board Support Package and firmware. physical PCI device information coming from Board Support Package and firmware.
For physical PCI device information, the related application constraints For physical PCI device information, the related application constraints
shall be defined in the design document or safety manual. For debug purpose, shall be defined in the design document or safety manual. For debug purpose,
developers could use ASSERT here to catch the Board Support Package or firmware developers could use ASSERT here to catch the Board Support Package or firmware
failures, which does not guarantee these application constraints. 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``?**
No. Here are the reasons: No. Here are the reasons:
a) Question_2 proves that 'vdev' is always not NULL. 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 error
checking codes are not required for 'vdev->ops->init'. 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?**
This case indicates that the initialization of specific virtual device fails. This case indicates that the initialization of specific virtual device fails.
Investigation has to be done to figure out the root-cause. Default fatal error Investigation has to be done to figure out the root-cause. Default fatal error
@ -428,7 +429,7 @@ handler shall be invoked here if it is caused by a hardware failure or invalid
boot information. boot information.
**Example_2: Analyze the function 'partition_mode_vpci_deinit'** **Example_2: Analyze the function ``partition_mode_vpci_deinit``**
.. code-block:: c .. code-block:: c
@ -453,9 +454,9 @@ 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' can not 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.
@ -528,7 +529,7 @@ 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 hypervisor in DETECT mode;
2. Configurable module APIs shall be abstracted as operations which 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;
@ -544,7 +545,7 @@ The module level configuration design rules are shown below:
6. In order to guarantee that the function pointer in the operations data 6. In order to guarantee that the function pointer in the operations data
structure is dereferenced after it has been instantiated, the pre-condition structure is dereferenced after it has been instantiated, the pre-condition
shall be added for the function which dereferences the function pointer, shall be added for the function that dereferences the function pointer,
instead of checking the pointer for NULL. instead of checking the pointer for NULL.
.. note:: The third rule shall be double checked during code review. .. note:: The third rule shall be double checked during code review.

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

@ -73,7 +73,7 @@ As shown in the above figure, here are some details about the Trusty boot flow p
#. 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 which 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