From 5289a3eb97fed9dc5726cc683ab5263725c0c136 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Fri, 2 Oct 2020 15:24:32 -0700 Subject: [PATCH] doc: more spelling and grammar fixes Signed-off-by: David B. Kinder --- doc/developer-guides/GVT-g-porting.rst | 22 +- doc/developer-guides/VBSK-analysis.rst | 12 +- .../asm_coding_guidelines.rst | 125 ++-- doc/developer-guides/c_coding_guidelines.rst | 653 +++++++++--------- .../contribute_guidelines.rst | 4 +- doc/developer-guides/doc_guidelines.rst | 37 +- doc/developer-guides/graphviz.rst | 2 +- doc/developer-guides/hld/hld-devicemodel.rst | 50 +- doc/developer-guides/hld/hld-overview.rst | 50 +- .../hld/hld-power-management.rst | 22 +- doc/developer-guides/hld/hld-security.rst | 66 +- doc/developer-guides/hld/hld-trace-log.rst | 18 +- .../hld/hld-virtio-devices.rst | 34 +- doc/developer-guides/hld/index.rst | 6 +- doc/developer-guides/l1tf.rst | 18 +- doc/developer-guides/modularity.rst | 12 +- doc/developer-guides/sw_design_guidelines.rst | 77 ++- doc/developer-guides/trusty.rst | 2 +- 18 files changed, 607 insertions(+), 603 deletions(-) diff --git a/doc/developer-guides/GVT-g-porting.rst b/doc/developer-guides/GVT-g-porting.rst index 6087a15a0..e55eecbf1 100644 --- a/doc/developer-guides/GVT-g-porting.rst +++ b/doc/developer-guides/GVT-g-porting.rst @@ -34,7 +34,7 @@ developers porting GVT-g to work on other hypervisors. This document describes: - the overall components of GVT-g -- interaction interface of each components +- interaction interface of each component - core interaction scenarios 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 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 @@ -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 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. -#. 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. #. 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, @@ -143,25 +143,25 @@ but instead it calls the GVT's :ref:`intel_gvt_ops_interface` 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. 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. -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 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 diff --git a/doc/developer-guides/VBSK-analysis.rst b/doc/developer-guides/VBSK-analysis.rst index c950c9c82..a93454bf5 100644 --- a/doc/developer-guides/VBSK-analysis.rst +++ b/doc/developer-guides/VBSK-analysis.rst @@ -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 and sends them to the backend. After receiving the message that the transmission is completed, it starts again another round of reception - and transmission, and keeps running until a specified number of cycle + and transmission, and keeps running until a specified number of cycles is reached. - **virtio-echo Driver in DM**: This driver is used for initialization configuration. It simulates a virtual PCI device for the frontend driver use, and sets necessary information such as the device 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 Backend Driver**: This driver sets all frontend RX buffers to 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 client for this IOREQ, in this case, the client is the vbs-echo 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. - **Notify Overhead**: After the data in virtqueue being processed by the 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 (from step1 to step 9) costs about 4 dozens of microsecond. That's because virtio-echo does little things in its frontend and backend -driver which is just for testing and there is very little process +driver that is just for testing and there is very little process overhead. .. figure:: images/vbsk-image1.png @@ -126,7 +126,7 @@ overhead. :numref:`vbsk-virtio-echo-path` details the path of kick and notify operation shown in :numref:`vbsk-virtio-echo-e2e`. The VBS-K framework overhead is caused by operations through these paths. As we can see, all -these operations are processed in kernel mode which avoids extra +these operations are processed in kernel mode and avoids extra overhead of passing IOREQ to userspace processing. .. 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 virtio-echo based on VBS-K framework is used to evaluate the VBS-K framework overhead. In our test, the VBS-K framework overhead (one kick -operation and one notify operation) is on the microsecond level which +operation and one notify operation) is on the microsecond level, which can meet the needs of most applications. diff --git a/doc/developer-guides/asm_coding_guidelines.rst b/doc/developer-guides/asm_coding_guidelines.rst index 11b3c5a96..a5fe4a94c 100644 --- a/doc/developer-guides/asm_coding_guidelines.rst +++ b/doc/developer-guides/asm_coding_guidelines.rst @@ -37,10 +37,10 @@ Compliant example:: asm_showcase_1: movl $0x1, %eax - + asm_showcase_2: movl $0x2, %eax - + asm_showcase_3: movl $0x3, %eax @@ -50,10 +50,10 @@ Compliant example:: text: movl $0x1, %eax - + mov: movl $0x2, %eax - + eax: movl $0x3, %eax @@ -68,9 +68,9 @@ Compliant example:: asm_showcase_1: movl $0x1, %eax jmp asm_showcase_2 - + /* do something */ - + asm_showcase_2: movl $0x2, %eax @@ -80,7 +80,7 @@ Compliant example:: asm_showcase_1: movl $0x1, %eax - + /* * 'asm_showcase_2' is not used anywhere, including * all C source/header files and Assembly files. @@ -139,19 +139,20 @@ Compliant example:: ASM-GN-06: .end directive statement shall be the last statement in an Assembly file =================================================================================== -This rule only applies to the Assembly file which uses .end directive. .end -directive shall be the last statement in this case. All the statements past .end -directive will not be processed by the assembler. +This rule only applies to the Assembly file that uses ``.end`` +directive. ``.end`` directive shall be the last statement in this case. +All the statements past ``.end`` directive will not be processed by the +assembler. Compliant example:: #include #include - + .macro asm_showcase_mov movl $0x1, %eax .endm - + .end .. rst-class:: non-compliant-code @@ -159,11 +160,11 @@ Compliant example:: Non-compliant example:: #include - + .end - + #include - + .macro asm_showcase_mov movl $0x1, %eax .endm @@ -177,9 +178,9 @@ Compliant example:: asm_showcase_1: movl $0x1, %eax jmp asm_showcase_2 - + /* do something */ - + asm_showcase_2: movl $0x2, %eax @@ -203,7 +204,7 @@ Compliant example:: jne asm_test movl $0x2, %eax movl $0x3, %eax - + asm_test: movl $0x6, %eax @@ -217,7 +218,7 @@ Compliant example:: /* the following two lines have no chance to be executed */ movl $0x2, %eax movl $0x3, %eax - + asm_test: movl $0x6, %eax @@ -242,11 +243,11 @@ Compliant example:: * perform a far jump to start executing in 64-bit mode */ ljmp $0x0008, $execution_64_2 - + .code64 execution_64_1: /* do something in 64-bit mode */ - + execution_64_2: /* do something in 64-bit mode */ @@ -257,7 +258,7 @@ Compliant example:: .data asm_showcase_data: .word 0x0008 - + .code32 execution_32: /* do something in 32-bit mode */ @@ -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 the following assembler directives may be used: -1) .align -2) .end -3) .extern -4) repeat related directives, including .rept and .endr -5) global related directives, including .global and .globl -6) macro related directives, including .altmacro, .macro, and .endm -7) code bit related directives, including .code16, .code32, and .code64 -8) section related directives, including .section, .data, and .text -9) number emission related directives, including .byte, .word, .short, .long, - and .quad -10) .org, which shall be used with restrictions. It shall only be used to +1) ``.align`` +2) ``.end`` +3) ``.extern`` +4) repeat related directives, including ``.rept`` and ``.endr`` +5) global related directives, including ``.global`` and ``.globl`` +6) macro related directives, including ``.altmacro``, ``.macro``, and ``.endm`` +7) code bit related directives, including ``.code16``, ``.code32``, and ``.code64`` +8) section related directives, including ``.section``, ``.data``, and ``.text`` +9) number emission related directives, including ``.byte``, ``.word``, + ``.short``, ``.long``, and ``.quad`` +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 mode to 64-bit mode. @@ -297,7 +298,7 @@ Compliant example:: asm_func_showcase: movl $0x2, %eax ret - + asm_showcase: movl $0x1, %eax call asm_func_showcase @@ -308,7 +309,7 @@ Compliant example:: asm_func_showcase: movl $0x2, %eax - + asm_showcase: movl $0x1, %eax call asm_func_showcase @@ -330,7 +331,7 @@ Compliant example:: tmp: movl $0x2, %eax ret - + asm_showcase: movl $0x1, %eax call asm_func_showcase @@ -344,7 +345,7 @@ Compliant example:: tmp: movl $0x2, %eax ret - + asm_showcase: movl $0x1, %eax call asm_func_showcase @@ -390,7 +391,7 @@ Compliant example:: asm_func_showcase: movl $0x2, %eax ret - + asm_showcase: movl $0x1, %eax call asm_func_showcase @@ -401,7 +402,7 @@ Compliant example:: asm_showcase: movl $0x1, %eax - + asm_func_showcase: movl $0x2, %eax ret @@ -417,7 +418,7 @@ Compliant example:: asm_func_showcase: movl $0x2, %eax ret - + asm_showcase: movl $0x1, %eax call asm_func_showcase @@ -430,11 +431,11 @@ Compliant example:: movl $0x2, %eax jmp asm_test ret - + asm_showcase: movl $0x1, %ebx call asm_func_showcase - + asm_test: cli @@ -447,7 +448,7 @@ Compliant example:: asm_func_showcase: movl $0x2, %eax ret - + asm_showcase: movl $0x1, %eax call asm_func_showcase @@ -460,7 +461,7 @@ Compliant example:: movl $0x2, %eax call asm_func_showcase ret - + asm_showcase: movl $0x1, %eax call asm_func_showcase @@ -568,12 +569,12 @@ Compliant example:: .extern cpu_primary_save32 .extern cpu_primary_save64 - + .section multiboot_header, "a" .align 4 .long 0x0008 .long 0x0018 - + .section entry, "ax" .align 8 .code32 @@ -584,12 +585,12 @@ Compliant example:: .extern cpu_primary_save32 .extern cpu_primary_save64 - + .section multiboot_header, "a" .align 4 .long 0x0008 .long 0x0018 - + .section entry, "ax" .align 8 .code32 @@ -602,7 +603,7 @@ Compliant example:: asm_showcase_1: movl $0x1, %eax - + asm_showcase_2: movl $0x2, %eax @@ -612,7 +613,7 @@ Compliant example:: asm_showcase_1: movl $0x1, %eax - + asm_showcase_2: movl $0x2, %eax @@ -643,7 +644,7 @@ Compliant example:: asm_showcase_1: movl $0x1, %eax lock and %rcx, (%rdx) - + asm_showcase_2: movl $0x3, %eax @@ -654,7 +655,7 @@ Compliant example:: asm_showcase_1: movl $0x1, %eax lock and %rcx, (%rdx) - + asm_showcase_2: movl $0x2, %eax @@ -718,13 +719,13 @@ Compliant example:: /* Legal entity shall be placed at the start of the file. */ -------------File Contents Start After This Line------------ - + /* * Copyright (C) 2019 Intel Corporation. * * SPDX-License-Identifier: BSD-3-Clause */ - + /* Coding or implementation related comments start after the legal entity. */ .code64 @@ -734,7 +735,7 @@ Compliant example:: /* Neither copyright nor license information is included in the file. */ -------------------File Contents Start After This Line------------------ - + /* Coding or implementation related comments start directly. */ .code64 @@ -786,15 +787,15 @@ ASM-NC-03: Label name shall be unique ===================================== Label name shall be unique with the following exception. Usage of local labels -is allowed. Local label is defined with the format 'N:', where N represents any -non-negative integer. Using 'Nb' to refer to the most recent previous definition -of that label. Using 'Nf' to refer to the next definition of a local label. +is allowed. Local label is defined with the format ``N:``, where N represents any +non-negative integer. Using ``Nb`` to refer to the most recent previous definition +of that label. Using ``Nf`` to refer to the next definition of a local label. Compliant example:: asm_showcase_1: movl $0x1, %eax - + asm_showcase_2: movl $0x2, %eax @@ -804,13 +805,13 @@ Compliant example:: asm_showcase: movl $0x1, %eax - + asm_showcase: 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:: diff --git a/doc/developer-guides/c_coding_guidelines.rst b/doc/developer-guides/c_coding_guidelines.rst index 08d012925..3612d6719 100644 --- a/doc/developer-guides/c_coding_guidelines.rst +++ b/doc/developer-guides/c_coding_guidelines.rst @@ -13,17 +13,17 @@ Preprocessor 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: -a) The result getting from ## or # operation shall not be used as the operands - of another ## or # operation; -b) Mixed-use of ## or # operators shall not be allowed. +a) The result getting from ``##`` or ``#`` operation shall not be used as the operands + of another ``##`` or ``#`` operation; +b) Mixed-use of ``##`` or ``#`` operators shall not be allowed. Compliant example:: #define CONCAT(x, y) x ## y - + uint32_t ab = 32U; printf("%d \n", CONCAT(a, b)); @@ -32,7 +32,7 @@ Compliant example:: Non-compliant example:: #define CONCAT(x, y, z) x ## y ## z - + uint32_t abc = 32U; printf("%d \n", CONCAT(a, b, c)); @@ -59,17 +59,18 @@ Compliant example:: 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:: /* In `showcase.h`: */ #ifndef SHOWCASE_H #define SHOWCASE_H - + /* header contents */ uint32_t func_showcase(uint32_t param); - + #endif /* SHOWCASE_H */ .. rst-class:: non-compliant-code @@ -77,7 +78,7 @@ Compliant example:: Non-compliant example:: /* In `showcase.h`: */ - + /* header contents without any protection */ uint32_t func_showcase(uint32_t param); @@ -128,14 +129,14 @@ Compliant example:: int32_t foo(char *ptr) { int32_t ret; - + if (ptr == NULL) { ret = -1; } else { ... ret = 0; } - + return ret; } @@ -160,7 +161,7 @@ Compliant example:: uint32_t func_showcase(void) { uint32_t showcase = 32U; - + printf("showcase: %d \n", showcase); return showcase; } @@ -172,7 +173,7 @@ Compliant example:: uint32_t func_showcase(void) { uint32_t showcase = 32U; - + return showcase; printf("showcase: %d \n", showcase); } @@ -189,18 +190,18 @@ Compliant example:: bool is_even_number(uint32_t param) { bool even = false; - + if ((param & 0x1U) == 0U) { even = true; } - + return even; } - + uint32_t func_showcase(uint32_t param) { uint32_t ret; - + if (param >= 20U) { ret = 20U; } else if (is_even_number(param)) { @@ -208,7 +209,7 @@ Compliant example:: } else { ret = 0U; } - + return ret; } @@ -219,23 +220,23 @@ Compliant example:: uint32_t func_showcase(uint32_t param) { uint32_t ret; - + if (param >= 20U) { ret = 20U; } - + if ((param == 0U) || (param == 2U) || (param == 4U) || (param == 6U) || (param == 8U) || (param == 10U) || (param == 12U) || (param == 14U) || (param == 16U) || (param == 18U)) { ret = 10U; } - + if ((param == 1U) || (param == 3U) || (param == 5U) || (param == 7U) || (param == 9U) || (param == 11U) || (param == 13U) || (param == 15U) || (param == 17U) || (param == 19U)) { ret = 0U; } - + return ret; } @@ -250,7 +251,7 @@ C-DI-01: Variable shall be used after its initialization Compliant example:: uint32_t a, b; - + a = 0U; b = a; @@ -259,7 +260,7 @@ Compliant example:: Non-compliant example:: uint32_t a, b; - + b = a; @@ -272,7 +273,7 @@ Compliant example:: { /* main body */ } - + static void showcase_1(void) { showcase_2(void); @@ -286,7 +287,7 @@ Compliant example:: { showcase_2(void); } - + static void showcase_2(void) { /* main body */ @@ -299,11 +300,11 @@ C-DI-03: The initialization statement shall not be skipped Compliant example:: uint32_t showcase; - + showcase = 0U; goto increment_ten; showcase += 20U; - + increment_ten: showcase += 10U; @@ -312,11 +313,11 @@ Compliant example:: Non-compliant example:: uint32_t showcase; - + goto increment_ten; showcase = 0U; showcase += 20U; - + increment_ten: showcase += 10U; @@ -331,13 +332,13 @@ Compliant example:: uint32_t temp_1; uint32_t temp_2; }; - + struct struct_showcase { uint32_t temp_3; struct struct_showcase_sub temp_struct; }; - + struct struct_showcase showcase = {32U, {32U, 32U}}; .. rst-class:: non-compliant-code @@ -349,13 +350,13 @@ Compliant example:: uint32_t temp_1; uint32_t temp_2; }; - + struct struct_showcase { uint32_t temp_3; struct struct_showcase_sub temp_struct; }; - + struct struct_showcase showcase = {32U, 32U, 32U}; @@ -385,11 +386,11 @@ Compliant example:: /* In `showcase.h` */ extern uint32_t showcase; - + /* In `showcase.c`: */ /* global variable */ uint32_t showcase = 32U; - + void func_showcase(void) { showcase++; @@ -403,7 +404,7 @@ Compliant example:: /* global variable */ uint32_t showcase; uint32_t showcase = 32U; - + void func_showcase(void) { showcase++; @@ -523,11 +524,11 @@ Compliant example:: { printf("param: %d\n", param); } - + void showcase_2(void) { uint32_t a; - + showcase_1(0U); a = 0U; } @@ -540,11 +541,11 @@ Compliant example:: { printf("param: %d\n", param); } - + void showcase_2(void) { uint32_t a; - + a = showcase_1(0U); } @@ -557,7 +558,7 @@ Compliant example:: void func_showcase(uint32_t *param_ptr) { uint32_t *local_ptr = param_ptr; - + local_ptr++; printf("%d \n", *local_ptr); } @@ -581,7 +582,7 @@ Compliant example:: void func_showcase(uint32_t param) { uint32_t local = param; - + local++; printf("%d \n", local); } @@ -604,10 +605,10 @@ Compliant example:: /* In `showcase.h`: */ uint32_t func_showcase(uint32_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + uint32_t func_showcase(uint32_t param) { return param; @@ -618,7 +619,7 @@ Compliant example:: Non-compliant example:: /* There is no `showcase.h`. */ - + /* In `showcase.c`: */ uint32_t func_showcase(uint32_t param) { @@ -640,7 +641,7 @@ Compliant example:: { printf("param %d \n", param); } - + void main(void) { func_showcase(10U); @@ -667,10 +668,10 @@ Compliant example:: /* In `showcase.h`: */ uint32_t func_showcase(uint32_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + uint32_t func_showcase(uint32_t param) { return param; @@ -682,10 +683,10 @@ Compliant example:: /* In `showcase.h`: */ uint32_t func_showcase(uint32_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + uint32_t func_showcase(uint32_t param_1) { return param_1; @@ -702,10 +703,10 @@ Compliant example:: /* In `showcase.h`: */ uint32_t func_showcase(uint32_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + uint32_t func_showcase(uint32_t param) { return param; @@ -717,10 +718,10 @@ Compliant example:: /* In `showcase.h`: */ uint32_t func_showcase(uint64_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + uint32_t func_showcase(uint32_t param) { return param; @@ -737,10 +738,10 @@ Compliant example:: /* In `showcase.h`: */ uint32_t func_showcase(uint32_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + uint32_t func_showcase(uint32_t param) { return param; @@ -752,10 +753,10 @@ Compliant example:: /* In `showcase.h`: */ uint64_t func_showcase(uint64_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + uint32_t func_showcase(uint32_t param) { return param; @@ -793,10 +794,10 @@ Compliant example:: /* In `showcase.h`: */ /* declaration */ uint32_t func_showcase(uint32_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + /* definition */ uint32_t func_showcase(uint32_t param) { @@ -810,7 +811,7 @@ Compliant example:: /* In `showcase.h`: */ /* declaration */ uint32_t func_showcase(uint32_t param); - + /* There is no definition of `func_showcase` anywhere in all source files */ @@ -828,22 +829,22 @@ Compliant example:: /* In `showcase.h`: */ uint32_t func_showcase(uint32_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + uint32_t func_showcase(uint32_t param) { return param; } - + /* In `main.c`: */ #include "showcase.h" - + void main(void) { uint32_t showcase; - + showcase = func_showcase(32U); } @@ -853,10 +854,10 @@ Compliant example:: /* In `showcase.h`: */ uint32_t func_showcase(uint32_t param); - + /* In `showcase.c`: */ #include "showcase.h" - + /* There is no usage of `func_showcase` anywhere in all source files */ uint32_t func_showcase(uint32_t param) { @@ -877,16 +878,16 @@ Compliant example:: uint32_t temp_32; uint64_t temp_64; }; - + struct struct_showcase func_showcase(void) { struct struct_showcase showcase; uint32_t showcase_u32 = 32U; uint64_t showcase_u64 = 64UL; - + showcase.temp_32 = showcase_u32; showcase.temp_64 = showcase_u64; - + return showcase; } @@ -899,19 +900,19 @@ Compliant example:: uint32_t *temp_32; uint64_t *temp_64; }; - + struct struct_showcase func_showcase(void) { struct struct_showcase showcase; uint32_t showcase_u32 = 32U; uint64_t showcase_u64 = 64UL; - + showcase.temp_32 = &showcase_u32; showcase.temp_64 = &showcase_u64; - + return showcase; } - + C-FN-16: Mixed-use of C code and assembly code in a single function shall not be allowed @@ -926,11 +927,11 @@ Compliant example:: { asm volatile ("hlt"); } - + void func_showcase(void) { bool showcase_flag = true; - + if (showcase_flag) { asm_hlt(); } @@ -943,7 +944,7 @@ Compliant example:: void func_showcase(void) { bool showcase_flag = true; - + if (showcase_flag) { asm volatile ("hlt"); } @@ -961,28 +962,28 @@ Compliant example:: /** Indicates that argument is not valid. */ #define EINVAL 22 - + int32_t func_showcase(uint32_t param) { int32_t error; - + if (param < 32U) { error = 0; } else { error = -EINVAL; } - + return error; } - + void main(uint32_t index) { int32_t error; uint32_t test; uint32_t array_showcase[32]; - + error = func_showcase(index); - + if (error == 0) { test = array_showcase[index]; } @@ -994,28 +995,28 @@ Compliant example:: /** Indicates that argument is not valid. */ #define EINVAL 22 - + int32_t func_showcase(uint32_t param) { int32_t error; - + if (param < 32U) { error = 0; } else { error = -EINVAL; } - + return error; } - + void main(uint32_t index) { int32_t error; uint32_t test; uint32_t array_showcase[32]; - + error = func_showcase(index); - + test = array_showcase[index]; } @@ -1031,7 +1032,7 @@ Compliant example:: void showcase(uint32_t array_source[16]) { uint32_t array_destination[16]; - + (void)memcpy(array_destination, array_source, 16U); } @@ -1042,7 +1043,7 @@ Compliant example:: void showcase(uint32_t array_source[32]) { uint32_t array_destination[16]; - + (void)memcpy(array_destination, array_source, 32U); } @@ -1055,11 +1056,11 @@ Compliant example:: uint32_t func_showcase(uint32_t param) { uint32_t mult = 1; uint32_t i; - + for (i = param; i > 0U; i--) { mult = mult * i; } - + return mult; } @@ -1069,11 +1070,11 @@ Compliant example:: uint32_t func_showcase(uint32_t param) { uint32_t mult = 1; - + if (param > 0U) { mult = param * func_showcase(param - 1); } - + return mult; } @@ -1116,7 +1117,7 @@ C-ST-02: The loop body shall be enclosed with brackets Compliant example:: uint32_t i; - + for (i = 0U; i < 5U; i++) { printf("count: %d \n", i); } @@ -1126,7 +1127,7 @@ Compliant example:: Non-compliant example:: uint32_t i; - + for (i = 0U; i < 5U; i++) printf("count: %d \n", i); @@ -1140,7 +1141,7 @@ Compliant example:: uint32_t count = 10U; bool showcase_flag = false; - + while (count > 5U) { if (showcase_flag) { @@ -1156,7 +1157,7 @@ Compliant example:: uint32_t count = 10U; bool showcase_flag = false; - + while (count > 5U) { if (showcase_flag) { @@ -1175,7 +1176,7 @@ possible cases. Compliant example:: uint32_t param, showcase; - + if (param < 10U) { showcase = 10U; } else if (param < 20U) { @@ -1189,7 +1190,7 @@ Compliant example:: Non-compliant example:: uint32_t param, showcase; - + if (param < 10U) { showcase = 10U; } else if (param < 20U) { @@ -1207,7 +1208,7 @@ cases. Compliant example:: char showcase; - + switch (showcase) { case 'a': /* do something */ @@ -1225,7 +1226,7 @@ Compliant example:: Non-compliant example:: char showcase; - + switch (showcase) { case 'a': /* do something */ @@ -1244,7 +1245,7 @@ Falling through a case shall not be allowed. Compliant example:: char showcase; - + switch (showcase) { case 'a': /* do something */ @@ -1262,7 +1263,7 @@ Compliant example:: Non-compliant example:: char showcase; - + switch (showcase) { case 'a': /* do something */ @@ -1280,7 +1281,7 @@ C-ST-07: The for loop counter shall not be changed inside the loop body Compliant example:: uint32_t i; - + for (i = 0U; i < 5U; i++) { printf("count: %d \n", i); } @@ -1290,29 +1291,29 @@ Compliant example:: Non-compliant example:: uint32_t i; - + for (i = 0U; i < 5U; i++) { printf("count: %d \n", i); i++; } -C-ST-08: 'goto' statement shall not be used -============================================ +C-ST-08: ``goto`` statement shall not be used +============================================== Compliant example:: uint32_t showcase(uint32_t param) { uint32_t ret; - + if (param < 10U) { ret = 10U; } else { ret = param; /* do something */ } - + return ret; } @@ -1323,16 +1324,16 @@ Compliant example:: uint32_t showcase(uint32_t param) { uint32_t ret; - + if (param < 10U) { ret = 10U; goto done; } else { ret = param; } - + /* do something */ - + done: return ret; } @@ -1351,7 +1352,7 @@ loop counter. All other operations shall not be allowed. Compliant example:: uint32_t i; - + for (i = 0U; i < 5U; i++) { printf("count: %d \n", i); } @@ -1362,7 +1363,7 @@ Compliant example:: uint32_t i; uint32_t showcase = 0U; - + for (i = 0U, showcase = 10U; i < 5U; i++) { printf("count: %d \n", i); } @@ -1374,7 +1375,7 @@ C-EP-02: The controlling expression of a for loop shall not be empty Compliant example:: uint32_t i; - + for (i = 0U; i < 5U; i++) { printf("count: %d \n", i); } @@ -1384,7 +1385,7 @@ Compliant example:: Non-compliant example:: uint32_t i; - + for (i = 0U; ; i++) { printf("count: %d \n", i); if (i > 4U) { @@ -1403,7 +1404,7 @@ operations shall not be allowed. Compliant example:: uint32_t i; - + for (i = 0U; i < 5U; i++) { printf("count: %d \n", i); } @@ -1414,7 +1415,7 @@ Compliant example:: uint32_t i; uint32_t showcase = 0U; - + for (i = 0U; i < 5U; i++, showcase++) { printf("count: %d \n", i); } @@ -1427,7 +1428,7 @@ Compliant example:: uint32_t showcase = 0U; uint32_t showcase_test = 10U; - + showcase++; showcase_test = showcase_test + showcase; @@ -1437,7 +1438,7 @@ Compliant example:: uint32_t showcase = 0U; uint32_t showcase_test = 10U; - + showcase_test = showcase_test + ++showcase; @@ -1449,7 +1450,7 @@ Compliant example:: uint32_t showcase_u32_1 = 0U; uint32_t showcase_u32_2 = 0xFFU; uint32_t showcase_u32_3; - + showcase_u32_3 = showcase_u32_1 * (showcase_u32_2 >> 4U); .. rst-class:: non-compliant-code @@ -1459,7 +1460,7 @@ Compliant example:: uint32_t showcase_u32_1 = 0U; uint32_t showcase_u32_2 = 0xFU; uint32_t showcase_u32_3; - + showcase_u32_3 = showcase_u32_1 * showcase_u32_2 >> 4U; @@ -1500,7 +1501,7 @@ Compliant example:: { uint32_t showcase_local = 32U; uint32_t *showcase_ptr_local; - + showcase_ptr_local = &showcase_local; printf("*showcase_ptr_local %d \n", *showcase_ptr_local); } @@ -1510,16 +1511,16 @@ Compliant example:: Non-compliant example:: uint32_t *showcase_ptr_global; - + void func_showcase(void) { uint32_t showcase_local = 32U; uint32_t *showcase_ptr_local; - + showcase_ptr_local = &showcase_local; showcase_ptr_global = showcase_ptr_local; } - + void main(void) { func_showcase(); @@ -1537,11 +1538,11 @@ the array size. Compliant example:: #define SHOWCASE_SIZE 32U - + void showcase(uint32_t array_source[SHOWCASE_SIZE]) { uint32_t num_bytes = SHOWCASE_SIZE * sizeof(uint32_t); - + printf("num_bytes %d \n", num_bytes); } @@ -1550,11 +1551,11 @@ Compliant example:: Non-compliant example:: #define SHOWCASE_SIZE 32U - + void showcase(uint32_t array_source[SHOWCASE_SIZE]) { uint32_t num_bytes = sizeof(array_source); - + printf("num_bytes %d \n", num_bytes); } @@ -1566,7 +1567,7 @@ Compliant example:: uint32_t size; char showcase[3] = {'0', '1', '\0'}; - + size = strlen(showcase); .. rst-class:: non-compliant-code @@ -1575,7 +1576,7 @@ Compliant example:: uint32_t size; char showcase[2] = {'0', '1'}; - + size = strlen(showcase); @@ -1586,7 +1587,7 @@ Compliant example:: char *str_source = "showcase"; char str_destination[32]; - + (void)strncpy(str_destination, str_source, 8U); .. rst-class:: non-compliant-code @@ -1595,7 +1596,7 @@ Compliant example:: char *str_source = "showcase"; char *str_destination = &str_source[1]; - + (void)strncpy(str_destination, str_source, 8U); @@ -1606,7 +1607,7 @@ Compliant example:: char *str_source = "showcase"; char str_destination[32]; - + (void)memcpy(str_destination, str_source, 8U); .. rst-class:: non-compliant-code @@ -1615,7 +1616,7 @@ Compliant example:: char str_source[32]; char *str_destination = &str_source[1]; - + (void)memcpy(str_destination, str_source, 8U); @@ -1629,9 +1630,9 @@ Compliant example:: uint8_t data_8[4]; uint16_t data_16[2]; }; - + union union_showcase showcase; - + showcase.data_16[0] = 0U; showcase.data_8[3] = (uint8_t)showcase.data_16[0]; @@ -1644,9 +1645,9 @@ Compliant example:: uint8_t data_8[4]; uint16_t data_16[2]; }; - + union union_showcase showcase; - + showcase.data_16[0] = 0U; showcase.data_8[0] = (uint8_t)showcase.data_16[0]; @@ -1661,7 +1662,7 @@ Compliant example:: uint32_t array_source[32]; uint32_t array_destination[32]; - + (void)memcpy(array_destination, array_source, 32U); .. rst-class:: non-compliant-code @@ -1670,7 +1671,7 @@ Compliant example:: uint32_t array_source[32]; uint32_t array_destination[16]; - + (void)memcpy(array_destination, array_source, 32U); @@ -1683,9 +1684,9 @@ size. Otherwise, data corruption may occur. Compliant example:: #define SHOWCASE_BYTES (32U * sizeof(uint32_t)) - + uint32_t array_source[32]; - + (void)memset(array_source, 0U, SHOWCASE_BYTES); .. rst-class:: non-compliant-code @@ -1693,9 +1694,9 @@ Compliant example:: Non-compliant example:: #define SHOWCASE_BYTES (32U * sizeof(uint32_t)) - + uint32_t array_source[32]; - + (void)memset(array_source, 0U, 2U * SHOWCASE_BYTES); @@ -1708,7 +1709,7 @@ Compliant example:: uint32_t numerator = 32U; uint32_t denominator = 0U; - + if (denominator != 0U) { uint32_t quotient = numerator / denominator; } @@ -1719,7 +1720,7 @@ Compliant example:: uint32_t numerator = 32U; uint32_t denominator = 0U; - + uint32_t quotient = numerator / denominator; @@ -1731,7 +1732,7 @@ A pointer shall be checked before use. Compliant example:: uint32_t *showcase_ptr = NULL; - + if (showcase_ptr != NULL) { uint32_t showcase = *showcase_ptr; } @@ -1741,7 +1742,7 @@ Compliant example:: Non-compliant example:: uint32_t *showcase_ptr = NULL; - + uint32_t showcase = *showcase_ptr; @@ -1751,7 +1752,7 @@ C-EP-18: A string literal shall not be modified Compliant example:: const char *showcase = "showcase"; - + printf("%s \n", showcase); .. rst-class:: non-compliant-code @@ -1759,7 +1760,7 @@ Compliant example:: Non-compliant example:: char *showcase = "showcase"; - + showcase[0] = 'S'; printf("%s \n", showcase); @@ -1776,7 +1777,7 @@ b) ++ or -- operation shall be allowed if it is used as the third expression of Compliant example:: uint32_t showcase = 0U; - + showcase++; .. rst-class:: non-compliant-code @@ -1785,7 +1786,7 @@ Compliant example:: uint32_t showcase = 0U; uint32_t showcase_test; - + showcase_test = showcase++; @@ -1799,7 +1800,7 @@ undefined behavior and shall be avoided. Compliant example:: char showcase_array[4] = {'s', 'h', 'o', 'w'}; - + char showcase = showcase_array[0]; .. rst-class:: non-compliant-code @@ -1807,7 +1808,7 @@ Compliant example:: Non-compliant example:: char showcase_array[4] = {'s', 'h', 'o', 'w'}; - + char showcase = showcase_array[10]; @@ -1818,7 +1819,7 @@ Compliant example:: uint32_t showcase_a = 10U; uint32_t showcase_b = 20U; - + showcase_a++; showcase_b++; @@ -1828,7 +1829,7 @@ Compliant example:: uint32_t showcase_a = 10U; uint32_t showcase_b = 20U; - + showcase_a++, showcase_b++; @@ -1846,7 +1847,7 @@ c) The meaning of the magic number is straightforward in the specific context. Compliant example:: #define APIC_ID_MASK 0xff000000U - + uint32_t showcase = APIC_ID_MASK; .. rst-class:: non-compliant-code @@ -1866,10 +1867,10 @@ ensure that the pointer reference is within the correct address space. Compliant example:: #define SHOWCASE_SIZE 32U - + uint32_t showcase_arr[SHOWCASE_SIZE]; uint32_t i; - + for (i = 0U; i < SHOWCASE_SIZE; i++) { showcase_arr[i] = i; } @@ -1879,10 +1880,10 @@ Compliant example:: Non-compliant example:: #define SHOWCASE_SIZE 32U - + uint32_t *showcase_ptr; uint32_t i; - + for (i = 0U; i < SHOWCASE_SIZE; i++) { *showcase_ptr = i; showcase_ptr = showcase_ptr + 1U; @@ -1928,7 +1929,7 @@ Compliant example:: uint32_t showcase = 32U; uint32_t mask = 0xFU; - + showcase = showcase & mask; .. rst-class:: non-compliant-code @@ -1937,7 +1938,7 @@ Compliant example:: uint32_t showcase = 32U; int32_t mask = -1; - + showcase = showcase & mask; @@ -1957,7 +1958,7 @@ Compliant example:: bool showcase_flag = true; uint32_t exp = 32U; uint32_t cond_exp = 64U; - + uint32_t showcase = showcase_flag ? exp : cond_exp; .. rst-class:: non-compliant-code @@ -1967,7 +1968,7 @@ Compliant example:: uint32_t showcase_flag = 1U; uint32_t exp = 32U; uint32_t cond_exp = 64U; - + uint32_t showcase = showcase_flag ? exp : cond_exp; @@ -1987,7 +1988,7 @@ Compliant example:: ENUM_SHOWCASE_0, ENUM_SHOWCASE_1 }; - + enum enum_showcase showcase_0 = ENUM_SHOWCASE_0; enum enum_showcase showcase_1 = showcase_0; @@ -1999,7 +2000,7 @@ Compliant example:: ENUM_SHOWCASE_0, ENUM_SHOWCASE_1 }; - + enum enum_showcase showcase_0 = ENUM_SHOWCASE_0; enum enum_showcase showcase_1 = showcase_0 + 1U; @@ -2011,7 +2012,7 @@ Compliant example:: char showcase[2] = {'0', '1'}; char chr; - + chr = showcase[1]; .. rst-class:: non-compliant-code @@ -2020,7 +2021,7 @@ Compliant example:: char showcase[2] = {'0', '1'}; char chr; - + chr = showcase[static 1]; @@ -2052,7 +2053,7 @@ Compliant example:: bool showcase_flag = true; uint32_t exp = 32U; uint32_t cond_exp = 64U; - + uint32_t showcase = showcase_flag ? exp : cond_exp; .. rst-class:: non-compliant-code @@ -2062,7 +2063,7 @@ Compliant example:: bool showcase_flag = true; int32_t exp = -1; uint32_t cond_exp = 64U; - + uint32_t showcase = showcase_flag ? exp : cond_exp; @@ -2079,7 +2080,7 @@ Compliant example:: uint32_t temp_32; uint64_t temp_64; }; - + struct struct_showcase showcase = {32U, 64UL}; .. rst-class:: non-compliant-code @@ -2091,7 +2092,7 @@ Compliant example:: uint32_t temp_32; uint64_t temp_64; }; - + struct struct_showcase showcase = {32U, -1}; @@ -2108,9 +2109,9 @@ Compliant example:: ENUM_SHOWCASE_1, ENUM_SHOWCASE_2 }; - + enum enum_showcase showcase; - + switch (showcase) { case ENUM_SHOWCASE_0: /* showcase */ @@ -2132,9 +2133,9 @@ Compliant example:: ENUM_SHOWCASE_1, ENUM_SHOWCASE_2 }; - + enum enum_showcase showcase; - + switch (showcase) { case ENUM_SHOWCASE_0: /* showcase */ @@ -2191,7 +2192,7 @@ Compliant example:: uint32_t showcase_u32; uint64_t showcase_u64 = 64UL; - + showcase_u32 = (uint32_t)showcase_u64; .. rst-class:: non-compliant-code @@ -2200,7 +2201,7 @@ Compliant example:: uint32_t showcase_u32; uint64_t showcase_u64 = 64UL; - + showcase_u32 = showcase_u64; @@ -2212,7 +2213,7 @@ Compliant example:: uint32_t showcase_u32_1 = 10U; uint32_t showcase_u32_2 = 10U; uint64_t showcase_u64; - + showcase_u64 = (uint64_t)showcase_u32_1 + (uint64_t)showcase_u32_2; .. rst-class:: non-compliant-code @@ -2222,7 +2223,7 @@ Compliant example:: uint32_t showcase_u32_1 = 10U; uint32_t showcase_u32_2 = 10U; uint64_t showcase_u64; - + showcase_u64 = (uint64_t)(showcase_u32_1 + showcase_u32_2); @@ -2234,7 +2235,7 @@ Compliant example:: /* 0x61 is 'a' in ASCII Table */ uint32_t showcase_u32; char showcase_char; - + showcase_u32 = 0x61U + 1U; showcase_char = (char)showcase_u32; @@ -2245,7 +2246,7 @@ Compliant example:: /* 0x61 is 'a' in ASCII Table */ uint32_t showcase_u32; char showcase_char; - + showcase_u32 = 0x61U; showcase_char = (char)(showcase_u32 + 1U); @@ -2256,7 +2257,7 @@ C-TY-15: Integer shall not be used when a character is expected Compliant example:: char showcase; - + switch (showcase) { case 'a': /* do something */ @@ -2273,7 +2274,7 @@ Compliant example:: Non-compliant example:: char showcase; - + switch (showcase) { /* 0x61 is 'a' in ASCII Table */ case 0x61: @@ -2293,7 +2294,7 @@ C-TY-16: A pointer shall not be cast to any other types Compliant example:: uint64_t *showcase_ptr; - + uint64_t showcase = *showcase_ptr; .. rst-class:: non-compliant-code @@ -2301,7 +2302,7 @@ Compliant example:: Non-compliant example:: uint64_t *showcase_ptr; - + uint64_t showcase = (uint64_t)showcase_ptr; @@ -2317,7 +2318,7 @@ b) Assignment shall be allowed if the objects pointed to by the two pointers are Compliant example:: uint64_t showcase = 10UL; - + uint64_t *showcase_ptr = &showcase; .. rst-class:: non-compliant-code @@ -2325,7 +2326,7 @@ Compliant example:: Non-compliant example:: uint64_t showcase = 10UL; - + uint64_t *showcase_ptr = (uint64_t *)showcase; @@ -2337,7 +2338,7 @@ Typedefs that are not used shall be deleted. Compliant example:: typedef unsigned int uint32_t; - + uint32_t showcase; .. rst-class:: non-compliant-code @@ -2347,7 +2348,7 @@ Compliant example:: typedef unsigned int uint32_t; /* uint32_t_backup is not being used anywhere */ typedef unsigned int uint32_t_backup; - + uint32_t showcase; @@ -2357,7 +2358,7 @@ C-TY-19: Array indexing shall only be performed on array type Compliant example:: char showcase[4] = {'s', 'h', 'o', 'w'}; - + char chr = showcase[1]; .. rst-class:: non-compliant-code @@ -2365,7 +2366,7 @@ Compliant example:: Non-compliant example:: char *showcase = "show"; - + char chr = showcase[1]; @@ -2378,11 +2379,11 @@ Compliant example:: { printf("formal_param: %d \n", formal_param); } - + void main(void) { uint32_t actual_param = 32U; - + func_showcase(actual_param); } @@ -2394,11 +2395,11 @@ Compliant example:: { printf("formal_param: %d \n", formal_param); } - + void main(void) { uint64_t actual_param = 32UL; - + func_showcase(actual_param); } @@ -2439,10 +2440,10 @@ Compliant example:: uint32_t *temp_32; uint64_t *temp_64; }; - + uint32_t *showcase_ptr_u32; struct struct_showcase *showcase_ptr_struct; - + showcase_ptr_u32 = showcase_ptr_struct->temp_32; .. rst-class:: non-compliant-code @@ -2454,10 +2455,10 @@ Compliant example:: uint32_t *temp_32; uint64_t *temp_64; }; - + uint32_t *showcase_ptr_u32; struct struct_showcase *showcase_ptr_struct; - + showcase_ptr_u32 = (uint32_t *)showcase_ptr_struct; @@ -2467,10 +2468,10 @@ C-TY-23: Assignment on function pointers shall be performed with same type Compliant example:: typedef void (*func_ptr_t)(void); - + func_ptr_t func_ptr_a; func_ptr_t func_ptr_b; - + func_ptr_a = func_ptr_b; .. rst-class:: non-compliant-code @@ -2479,10 +2480,10 @@ Compliant example:: typedef void (*func_ptr_a_t)(void); typedef uint32_t (*func_ptr_b_t)(uint32_t param); - + func_ptr_a_t func_ptr_a; func_ptr_b_t func_ptr_b; - + func_ptr_a = func_ptr_b; @@ -2492,12 +2493,12 @@ C-TY-24: Cast shall not be performed on function pointer Compliant example:: typedef uint32_t (*func_ptr_t)(uint32_t param); - + uint32_t func_showcase(uint32_t param) { return param; } - + func_ptr_t func_ptr_showcase; func_ptr_showcase = func_showcase; @@ -2506,12 +2507,12 @@ Compliant example:: Non-compliant example:: typedef uint32_t (*func_ptr_t)(uint32_t param); - + void func_showcase(uint32_t param) { printf("param: %d \n", param); } - + func_ptr_t func_ptr_showcase; func_ptr_showcase = (func_ptr_t)func_showcase; @@ -2548,7 +2549,7 @@ is to guarantee the code portability between different compilers and platforms. Compliant example:: typedef unsigned int uint32_t; - + uint32_t showcase = 32U; .. rst-class:: non-compliant-code @@ -2580,7 +2581,7 @@ Compliant example:: uint16_t showcase_u16 = 16U; uint32_t showcase_u32 = 32U; uint64_t showcase_u64 = 64UL; - + uint32_t test = (uint32_t)showcase_u16 + showcase_u32 + (uint32_t)showcase_u64; .. rst-class:: non-compliant-code @@ -2590,7 +2591,7 @@ Compliant example:: uint16_t showcase_u16 = 16U; uint32_t showcase_u32 = 32U; uint64_t showcase_u64 = 64UL; - + uint32_t test = showcase_u16 + showcase_u32 + showcase_u64; @@ -2608,7 +2609,7 @@ Compliant example:: char *str_source; char *str_destination; }; - + void func_showcase(uint32_t showcase) { /* main body */ @@ -2623,7 +2624,7 @@ Compliant example:: char *str_source; char *str_destination; }; - + void func_showcase(uint32_t showcase) { /* main body */ @@ -2640,7 +2641,7 @@ Compliant example:: char *str_source; char *str_destination; }; - + struct struct_showcase_2 { uint32_t showcase_1; @@ -2656,7 +2657,7 @@ Compliant example:: char *str_source; char *str_destination; }; - + struct showcase_2 { uint32_t showcase_1; @@ -2678,10 +2679,10 @@ Compliant example:: char *str_source; char *str_destination; }; - + /* global variable */ uint32_t showcase; - + void func_showcase(void) { showcase++; @@ -2696,10 +2697,10 @@ Compliant example:: char *str_source; char *str_destination; }; - + /* global variable */ uint32_t showcase; - + void func_showcase(void) { showcase++; @@ -2713,11 +2714,11 @@ Compliant example:: /* global variable */ uint32_t showcase; - + void func_showcase(void) { uint32_t showcase_local; - + showcase_local = 32U; } @@ -2727,11 +2728,11 @@ Compliant example:: /* global variable */ uint32_t showcase; - + void func_showcase(void) { uint32_t showcase; - + showcase = 32U; } @@ -2747,7 +2748,7 @@ Compliant example:: /* global variable */ uint32_t showcase; - + void func_showcase(void) { /* main body */ @@ -2759,7 +2760,7 @@ Compliant example:: /* global variable */ uint32_t showcase; - + void showcase(void) { /* main body */ @@ -2774,7 +2775,7 @@ The typedef name shall be unique and not be used for any other purpose. Compliant example:: typedef unsigned int uint32_t; - + uint32_t showcase; .. rst-class:: non-compliant-code @@ -2782,7 +2783,7 @@ Compliant example:: Non-compliant example:: typedef unsigned int uint32_t; - + uint32_t uint32_t; @@ -2814,7 +2815,7 @@ Compliant example:: char *str_source; char *str_destination; }; - + uint32_t showcase; .. rst-class:: non-compliant-code @@ -2826,7 +2827,7 @@ Compliant example:: char *str_source; char *str_destination; }; - + uint32_t showcase; @@ -2962,12 +2963,12 @@ C-CS-06: A single space shall exist between non-function-like keywords and openi A single space shall exist between a non-function-like keyword and the opening bracket (either a brace or a parenthesis) that follows. This rule applies to the -keywords 'if', 'else', 'for', 'do', 'while', 'switch' and 'return'. +keywords ``if``, ``else``, ``for``, ``do``, ``while``, ``switch`` and ``return``. Compliant example:: uint32_t showcase; - + if (showcase == 0U) { showcase = 32U; } @@ -2977,7 +2978,7 @@ Compliant example:: Non-compliant example:: uint32_t showcase; - + if(showcase == 0U){ showcase = 32U; } @@ -3013,14 +3014,14 @@ Compliant example:: 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: -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. -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 function prototype. @@ -3046,7 +3047,7 @@ equality and assignment operators, as well as the ternary conditional operator. Compliant example:: uint32_t showcase = 32U; - + showcase = showcase * 2U; .. rst-class:: non-compliant-code @@ -3054,7 +3055,7 @@ Compliant example:: Non-compliant example:: uint32_t showcase=32U; - + showcase=showcase*2U; @@ -3089,7 +3090,7 @@ expressions in for-loop headers. Compliant example:: uint32_t i; - + for (i = 0U; i < 5U; i++) { printf("count: %d \n", i); } @@ -3099,7 +3100,7 @@ Compliant example:: Non-compliant example:: uint32_t i; - + for (i = 0U;i < 5U;i++) { printf("count: %d \n", i); } @@ -3116,7 +3117,7 @@ Compliant example:: uint32_t numerator = 32U; uint32_t denominator = 0U; uint32_t quotient; - + if (denominator != 0U) { quotient = numerator / denominator; } @@ -3128,7 +3129,7 @@ Compliant example:: uint32_t numerator = 32U; uint32_t denominator = 0U; uint32_t quotient; - + if (denominator != 0U) { quotient = numerator / denominator; @@ -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:: @@ -3193,7 +3194,7 @@ shall be the same for one case. Compliant example:: uint32_t showcase; - + showcase = func(param_1, param_2, param_3); @@ -3203,16 +3204,16 @@ Compliant example:: Non-compliant example:: uint32_t showcase; - + showcase = func(param_1, param_2, 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:: @@ -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 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. -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. 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 simplicity. 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 blank line is not required to separate each element. 7) The brief description of the function shall be documented with the format - '\@brief '. + ``@brief ``. 8) No specific format is required for the detailed description of the function. 9) The description of the function parameter shall be documented with the format - '\@param '. -10) The pre-condition of the function shall be documented with the format '\@pre - '. + ``@param ``. +10) The pre-condition of the function shall be documented with the format + ``@pre ``. 11) The post-condition of the function shall be documented with the format - '\@post '. + ``@post ``. 12) The brief description of the function return value shall be documented with - the format '\@return '. -13) A void-returning function shall be documented with the format '\@return - None'. + the format ``@return ``. +13) A void-returning function shall be documented with the format + ``@return None``. 14) The comments explaining the actual return values shall be documented with - the format '\@retval '. + the format ``@retval ``. 15) If the description of one element needs to span multiple lines, each line shall be aligned to the start of the description in the first line for that element. @@ -3307,15 +3308,15 @@ Compliant example:: /* Brief description of the function. Detailed description of the function. Detailed description of the function. Detailed description of the function. Detailed description of the function. - + @param param_1 Parameter description for param_1. @param param_2 Parameter description for param_2. @param param_3 Parameter description for param_3. Parameter description for param_3. Parameter description for param_3. Parameter description for param_3. Parameter description for param_3. Parameter description for param_3. - + pre-conditions: param_1 != NULL, param_2 <= 255U post-conditions: retval <= 0 - + Brief description of the return value. */ int32_t func_showcase(uint32_t *param_1, uint32_t param_2, uint32_t param_3); @@ -3334,13 +3335,13 @@ Compliant example:: /* Legal entity shall be placed at the start of the file. */ -------------File Contents Start After This Line------------ - + /* * Copyright (C) 2019 Intel Corporation. * * SPDX-License-Identifier: BSD-3-Clause */ - + /* Coding or implementation related comments start after the legal entity. */ #include @@ -3350,7 +3351,7 @@ Compliant example:: /* Neither copyright nor license information is included in the file. */ -------------------File Contents Start After This Line------------------ - + /* Coding or implementation related comments start directly. */ #include @@ -3390,8 +3391,8 @@ Compliant example:: #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. 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. 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. For example: -a) The data structure related to register shall be named with suffix 'reg'; +a) The data structure related to register shall be named with suffix ``reg``; b) The data structure related to segment selector shall be named with suffix - 'sel'. + ``sel``. 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:: @@ -3519,48 +3520,48 @@ function. Some detailed rules are listed below: 1) If the function is doing actions, it shall be named with one of the following formats: - a) _, such as 'init_vmcs'. - b) __, such as 'init_primary_pcpu'. + a) ``_``, such as ``init_vmcs``. + b) ``__``, such as ``init_primary_pcpu``. 2) If the function is doing checks, it shall be named with one of the following formats: - a) is_, such as 'is_space'. - b) is__, such as 'is_pcpu_active'. + a) ``is_``, such as ``is_space``. + b) ``is__``, such as ``is_pcpu_active``. 3) If the function is doing conversions, it shall be named with one of the following formats: - a) _to_, such as 'irq_to_vector'. - b) 2, such as 'gva2gpa'. + a) ``_to_``, such as ``irq_to_vector``. + b) ``2``, such as ``gva2gpa``. 4) If the function is specific for one module and the name is not descriptive enough with prior rules, it shall be named with the module name as prefix, such - as 'vie_read_mmio'. + as ``vie_read_mmio``. 5) If the function is a wrapper of inline Assembly codes, it shall be named with one of the following formats: - a) asm_, such as 'asm_pause'. + a) ``asm_``, such as ``asm_pause``. b) If the Assembly instruction mnemonic does not clearly indicate the purpose of the function or the function includes multiple Assembly - instruction statements, the function shall be named with 'asm\_' as + instruction statements, the function shall be named with ``asm_`` as prefix and apply the other non-assembly function naming rules. -6) mentioned in prior rules may either be one noun or multiple nouns, as +6) ```` mentioned in prior rules may either be one noun or multiple nouns, as long as it could clearly illustrate the object. Compliant example:: uint32_t init_vmcs(uint32_t param); - + uint32_t init_primary_pcpu(uint32_t param); - + bool is_space(uint32_t param); - + bool is_pcpu_active(uint32_t param); - + uint32_t vie_read_mmio(uint32_t param); - + uint32_t irq_to_vector(uint32_t param); - + uint32_t gva2gpa(uint32_t param); - + uint32_t asm_pause(uint32_t param); .. rst-class:: non-compliant-code @@ -3568,19 +3569,19 @@ Compliant example:: Non-compliant example:: uint32_t vmcs_init(uint32_t param); - + uint32_t primary_pcpu_init(uint32_t param); - + bool space(uint32_t param); - + bool pcpu_active(uint32_t param); - + uint32_t vie_mmio_read(uint32_t param); - + uint32_t from_irq_to_vector(uint32_t param); - + uint32_t get_gpa_based_on_gva(uint32_t param); - + uint32_t pause(uint32_t param); @@ -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 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 -J.3.4 item 5 in C99. For ACRN hypervisor, 'plain' char is equivalent to signed -char. +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 char``. 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. -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. @@ -3660,26 +3661,24 @@ C-LE-03: Use of extended type attribute is allowed This rule applies to the following type attributes: -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. -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. +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. +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. C-LE-04: Use of extended builtin-function is allowed ==================================================== This rule applies to the following builtin-functions: -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. -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. +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. +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. C-LE-05: Use of extended designated initializers is allowed =========================================================== -This rule applies to the following designated initializer: writing '[first ... -last] = value' to initialize a range of elements to the same value, refers to -section 6.27 in GCC 8.3 Manual. - - +This rule applies to the following designated initializer: writing +``[first ... last] = value`` to initialize a range of elements +to the same value, refers to section 6.27 in GCC 8.3 Manual. diff --git a/doc/developer-guides/contribute_guidelines.rst b/doc/developer-guides/contribute_guidelines.rst index d44985cdc..7088f3bc7 100644 --- a/doc/developer-guides/contribute_guidelines.rst +++ b/doc/developer-guides/contribute_guidelines.rst @@ -117,8 +117,8 @@ on https://github.com and have Git tools available on your development system. Repository layout ***************** -To clone the ACRN hypervisor repository (including the hypervisor, -devicemodel, and doc folders) use:: +To clone the ACRN hypervisor repository (including the ``hypervisor``, +``devicemodel``, and ``doc`` folders) use:: $ git clone https://github.com/projectacrn/acrn-hypervisor diff --git a/doc/developer-guides/doc_guidelines.rst b/doc/developer-guides/doc_guidelines.rst index b7f099604..275c6fcd5 100644 --- a/doc/developer-guides/doc_guidelines.rst +++ b/doc/developer-guides/doc_guidelines.rst @@ -5,7 +5,7 @@ Documentation Guidelines Project ACRN content is written using the `reStructuredText`_ markup 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 Sphinx installed) they can build the documentation using the Makefile (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 use of both and overline and matching underline to indicate a heading, we only use an underline indicator for headings.) For consistency in -our documentation, we define the order of characters used to indicated +our documentation, we define the order of characters used to indicate the nested table of contents levels: * Use ``#`` for the Document title underline character @@ -52,11 +52,11 @@ underlines to use: Document Title heading ###################### - Section 1.0 heading - ******************* + Section 1 heading + ***************** - Section 2.0 heading - ******************* + Section 2 heading + ***************** Section 2.1 heading =================== @@ -67,8 +67,8 @@ underlines to use: 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*), * 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 -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 unterminated italics section. For inline markup, the characters between the beginning and ending characters must not start or end with a space, so ``*this is italics*`` ( *this is italics*) while ``* this isn't*`` (* this isn't*). -If asterisks or 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 backslash (``\``) before it. @@ -137,17 +137,17 @@ list item: needed, but it wouldn't hurt for readability. Definition lists (with a term and its definition) are a convenient way -to document a word or phrase with an explanation. For example this reST +to document a word or phrase with an explanation. For example, this reST content: .. code-block:: rest The Makefile has targets that include: - html + ``html`` Build the HTML output for the project - clean + ``clean`` Remove all generated output, restoring the folders to a clean state. @@ -198,7 +198,8 @@ would be rendered as: * the page 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 column on narrow (phone) screens if necessary. We've deprecated use of 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, the link text will update as well. -There may be times where you'd like to change the link text that's shown -in the generated document. In this case, you can add specify alternate +There may be times when you'd like to change the link text that's shown +in the generated document. In this case, you can specify alternate text using ``:ref:`alternate text ``` (renders as :ref:`alternate text `). @@ -614,7 +615,7 @@ sphinx-tabs from the link above. 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 the ``.. rst-class:: numbered-step`` directive immediately before a second-level heading (by project convention, a heading underlined with diff --git a/doc/developer-guides/graphviz.rst b/doc/developer-guides/graphviz.rst index 509d4ff30..243c75cd4 100644 --- a/doc/developer-guides/graphviz.rst +++ b/doc/developer-guides/graphviz.rst @@ -39,7 +39,7 @@ Simple directed graph ********************* For simple drawings with shapes and lines, you can put the graphviz -commands in the content block for the directive. For example for a +commands in the content block for the directive. For example, for a simple directed graph (digraph) with two nodes connected by an arrow, you can write: diff --git a/doc/developer-guides/hld/hld-devicemodel.rst b/doc/developer-guides/hld/hld-devicemodel.rst index 65c9414e9..f7bd0c5cd 100644 --- a/doc/developer-guides/hld/hld-devicemodel.rst +++ b/doc/developer-guides/hld/hld-devicemodel.rst @@ -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 through upcall. - 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) - DM I/O dispatcher calls corresponding I/O handlers - 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. - **PIO/MMIO Handler Init**: PIO/MMIO handlers provide callbacks for - trapped PIO/MMIO request which are triggered from I/O request - server in HV for DM owned device emulation. This is the endpoint + trapped PIO/MMIO requests that are triggered from I/O request + server in HV for DM-owned device emulation. This is the endpoint of I/O path in DM. After this initialization, device emulation driver in DM could register its MMIO handler by *register_mem()* 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 -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 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 ==================== -.. 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, 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 module responsible for handling I/O access whose address 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 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. 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 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 - for a new kernel thread. + client, and finally attaches it to VHM that kicks off + a new kernel thread. - 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 @@ -414,9 +414,9 @@ are as follows: all clients that have I/O requests to be processed. The flow is 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 - 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. 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 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 -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 -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. 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 -INOUT_PORT, or registers the PIO emulation handers through +INOUT_PORT, or registers the PIO emulation handlers through register_inout() function after init_inout(): .. code-block:: c @@ -565,7 +565,7 @@ register_inout() function after init_inout(): 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: .. code-block:: c @@ -580,7 +580,7 @@ parameter needed to register MMIO handler for special MMIO range: uint64_t size; }; -A MMIO emulation handler is defined as: +An MMIO emulation handler is defined as: .. 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. -* 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 +* 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 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 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 - 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. -.. 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 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 line. The corresponding PCI device's initialization function will 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 customized handlers for cfgwrite/cfgread and barwrite/barread. @@ -797,7 +797,7 @@ Introduction Advanced Configuration and Power Interface (ACPI) provides an open 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. Functions implemented by ACPI include: @@ -1176,7 +1176,7 @@ Bluetooth UART enumeration. 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 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 in device model and :ref:`mmio-device-passthrough` for MMIO passthrough realization -in device model and ACRN Hypervisor.. +in device model and ACRN Hypervisor. diff --git a/doc/developer-guides/hld/hld-overview.rst b/doc/developer-guides/hld/hld-overview.rst index 2f4210ac2..7f875cfd3 100644 --- a/doc/developer-guides/hld/hld-overview.rst +++ b/doc/developer-guides/hld/hld-overview.rst @@ -3,11 +3,13 @@ ACRN high-level design overview ############################### -ACRN is an open source reference hypervisor (HV) that runs on top of Intel -platforms (APL, KBL, etc) for heterogeneous scenarios such as the Software Defined -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 -I/O mediation solution with a permissive license and provides auto makers and -industry users a reference software stack for corresponding use. +ACRN is an open source reference hypervisor (HV) that runs on top of +Intel platforms (APL, KBL, etc.) for heterogeneous scenarios such as the +Software-defined 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 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 ************************ @@ -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 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. - alerts of low fuel or tire pressure - 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 - Radios, audio and video playback @@ -49,11 +51,11 @@ VMs for a customized IC/IVI/RSE. 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 -- RT VM which running specific RTOS on it to provide capability of handling - real-time workloads like PLC control +- Windows HMI as a guest OS with display to provide Human Machine Interface +- RT VM that runs a specific RTOS on it to handle + real-time workloads such as PLC control 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 @@ -76,7 +78,7 @@ Mandatory IA CPU features are support for: - MTRR - TSC deadline timer - 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. @@ -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 and minimizing potential interference. However, running the IC system in 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 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 passthrough mode to User VMs according to VM configuration. In addition, 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. .. figure:: images/over-image34.png @@ -130,7 +132,7 @@ and real-time (RT) VM. compared to ACRN 1.0 is that: - 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 interference between different VMs @@ -190,7 +192,7 @@ I/O read from the User VM. I/O (PIO/MMIO) Emulation 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 reason ``VMX_EXIT_REASON_IO_INSTRUCTION`` for port I/O access, for 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 -for the User VMs, for example, an i915 gvt driver. +for the User VMs, for example, an i915 GVT driver. Log/Trace Tools =============== @@ -478,7 +480,7 @@ the following mechanisms: scheduling latency and vCPU priority, exposing more opportunities 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 physical CPU loops in idle when the vCPU is paused by I/O 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. -- 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. 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 -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, 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 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 -trapped to "Sx Agency" in ACRN, and it will start the power state +Then the OSPM of the Service VM starts the power state transition of the Service VM +trapped to "Sx Agency" in ACRN, and it starts the power state transition. 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 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. diff --git a/doc/developer-guides/hld/hld-power-management.rst b/doc/developer-guides/hld/hld-power-management.rst index 2f79f5db7..ca87e0e2d 100644 --- a/doc/developer-guides/hld/hld-power-management.rst +++ b/doc/developer-guides/hld/hld-power-management.rst @@ -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 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 VM VHM via ioctl interface. 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 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 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. S3/S5 @@ -111,14 +111,14 @@ assumptions: 4) Highest severity guest's power state is promoted to system power state. 5) Guest has lifecycle manager running to handle 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. ACRN has a common implementation for notification between lifecycle manager in different guest. Which is vUART based cross-vm notification. But user 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 :align: center @@ -127,7 +127,7 @@ could customize it according to their hardware/software requirements. 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, @@ -156,19 +156,19 @@ with typical ISD configuration(S3 follows very similar process) :align: center :name: pmworkflow - ACRN system S5 enter workflow + ACRN system S5 entry workflow For system power state entry: 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. -3. Guest lifecycle manager initialize S5 action. And guest enter S5. -4. RTOS cleanup rt task, send response of S5 request back to Service +3. Guest lifecycle manager initializes S5 action and guest enters S5. +4. RTOS cleanup RT task, send response of S5 request back to Service VM and RTVM enter S5. 5. After get response from RTVM and all User VM are shutdown, Service VM 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. System low power state exit process diff --git a/doc/developer-guides/hld/hld-security.rst b/doc/developer-guides/hld/hld-security.rst index 85d3a4625..98f648988 100644 --- a/doc/developer-guides/hld/hld-security.rst +++ b/doc/developer-guides/hld/hld-security.rst @@ -94,7 +94,7 @@ call these two OS systems "secure world" and "non-secure world", and they are isolated from each other by the hypervisor. Secure world has a higher "privilege level" than non-secure 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. Careful consideration should be made when evaluating using the Service @@ -150,7 +150,7 @@ before launching. 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 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. 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. 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 is controlled by a set of UEFI Authenticated Variables which specify -the UEFI Secure Boot Policy; the platform manufacturer or the platform owner enroll the -policy objects, which includes the n-tuple of keys {PK, KEK, db,dbx} as step 1. +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 enrolls the +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 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. @@ -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. #. 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. #. `.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: #. 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. #. Enable kernel-based hardening techniques, for example dm-verity (to 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, see `AGL security `_ -and `Android security `_ +and `Android security `_. 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 is Writable, then the hypervisor must make it non-eXecutable. The 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 read-only. @@ -421,7 +421,7 @@ three typical solutions exist: 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 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. 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 +++++++++++++++++++++++++++++++++ -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 level. As long as the CR4.SMEP = 1, software operating in supervisor 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). No matter what settings for NX bit and R/W bit in corresponding host 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. 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 -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 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, and R/W bit = 1) in corresponding host CR3 paging table entries, as 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. #. When needed, use STAC instruction to suppress SMAP protection, and 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 guest memory pages, one of functions above must be used. Otherwise, the -#PF will be triggered by the processor to prevent malicious or -unintended access from/to the guest memory pages. +#PF will be triggered by the processor to prevent malware or +unintended access from or to the guest memory pages. These functions must also internally check the address availabilities, 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 crashes, its memory content should be scrubbed either by the hypervisor 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. .. _secure-hypervisor-interface: @@ -639,12 +639,12 @@ guest VM. The hypervisor then emulates the MMIO instructions with design behaviors. 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 ~~~~~~~~~~~~~~~~~~~~~ -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 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 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 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. In ACRN, the memory content is scrubbed in Device Model after the guest -VM is shutdown. +VM is shut down. 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: virtual **warm** reboot. @@ -730,7 +730,7 @@ enabling the configuration. 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 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. 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, even including the Service VM. @@ -791,9 +791,9 @@ The parameters of HDKF derivation in the hypervisor are: #. OutSeedLen = 64 in bytes #. 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: @@ -805,7 +805,7 @@ guest VM such as the Android User VM. (See :ref:`trusty_tee` for more information.) 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 by fulfilling Android CDD requirements. Also as a plan, Trusty will be 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 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 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. @@ -892,7 +892,7 @@ Hypercall - Trusty Initialization 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 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). .. figure:: images/security-image9.png @@ -905,18 +905,18 @@ secure world (Trusty/TEE). In :numref:`security-start-flow` above, the OSLoader is responsible for loading TEE/Trusty image to a dedicated and reserved memory region, and 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 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 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 initialization, the hypervisor eventually does vmresume (step 4 in :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 security services can be ready right before non-secure OS gets started. diff --git a/doc/developer-guides/hld/hld-trace-log.rst b/doc/developer-guides/hld/hld-trace-log.rst index 7110ceb75..2678d23af 100644 --- a/doc/developer-guides/hld/hld-trace-log.rst +++ b/doc/developer-guides/hld/hld-trace-log.rst @@ -22,10 +22,10 @@ are two use scenarios of 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 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. -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 allowed to get data from Sbuf in Service VM. Therefore, no lock is required to synchronize access by the producer and consumer. @@ -33,7 +33,7 @@ synchronize access by the producer and consumer. 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 @@ -77,7 +77,7 @@ Service VM Trace Module The Service VM trace module is responsible for: - 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 - provide mmap operation to map entire Sbuf to userspace for high 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 file. -.. note:: figure is missing +.. note:: TODO figure is missing Figure 2.2 Sequence of trace init and trace data collection These are the Python scripts provided: @@ -113,7 +113,7 @@ These are the Python scripts provided: text offline according to given format; - **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. 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 -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: - 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 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 -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 the hypervisor. @@ -200,7 +200,7 @@ On Service VM boot, Service VM acrnlog module is responsible to: these last logs - 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 - the misc devices implement read() file operation to allow diff --git a/doc/developer-guides/hld/hld-virtio-devices.rst b/doc/developer-guides/hld/hld-virtio-devices.rst index f571e63e4..ebf6b565c 100644 --- a/doc/developer-guides/hld/hld-virtio-devices.rst +++ b/doc/developer-guides/hld/hld-virtio-devices.rst @@ -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 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 eliminates the need for boutique, per-environment, or per-OS mechanisms. 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. 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 - 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 don't need to worry about the details of the virtqueue. (Refer to guest @@ -178,8 +178,8 @@ Virtio Device Discovery Virtio Frameworks ***************** -This section describes the overall architecture of virtio, and then -introduce ACRN specific implementations of the virtio framework. +This section describes the overall architecture of virtio, and +introduces the ACRN-specific implementations of the virtio framework. 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 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 -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 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 feature negotiation is done, which is determined by FE driver setting up 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. Finally the FE driver is not aware of how the BE driver is implemented, @@ -336,8 +336,8 @@ can be described as: device: 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, addr, len). + registered with ``(fd, port, len, value)``. If it is an MMIO, it is + registered with ``(fd, addr, len)``. b) Irqfd is registered with MSI vector. 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: -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. 2. pass ioeventfd to vhost kernel driver. 3. pass ioevent fd to vhm driver 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. -6. ioeventfd vhm client traverse the io_range list and find +6. ioeventfd vhm client traverses the io_range list and find corresponding eventfd. 7. trigger the signal to related eventfd. 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 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: -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. 2. pass irqfd to vhost kernel driver. 3. pass irq fd to vhm driver @@ -395,8 +395,8 @@ The workflow can be summarized as: transfer is completed. 5. irqfd related logic traverses the irqfd list to retrieve related irq information. -6. irqfd related logic inject an interrupt through vhm interrupt API. -7. interrupt is delivered to User VM FE driver through hypervisor. +6. irqfd related logic injects an interrupt through vhm interrupt API. +7. Interrupt is delivered to User VM FE driver through hypervisor. .. _virtio-APIs: @@ -464,7 +464,7 @@ relationships are shown in :numref:`VBS-K-data`. A single virtqueue information to be synchronized from VBS-U to VBS-K kernel module. ``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. .. figure:: images/virtio-hld-image8.png @@ -480,7 +480,7 @@ to open and register device status after feature negotiation with the FE driver. 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 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 diff --git a/doc/developer-guides/hld/index.rst b/doc/developer-guides/hld/index.rst index 1efffb931..95549c92f 100644 --- a/doc/developer-guides/hld/index.rst +++ b/doc/developer-guides/hld/index.rst @@ -3,10 +3,10 @@ High-Level Design Guides ######################## -The ACRN Hypervisor acts as a host with full control of the processor(s) -and the hardware (physical memory, interrupt management and I/O). It +The ACRN Hypervisor acts as a host with full control of the processors +and the hardware (physical memory, interrupt management, and I/O). It 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. These chapters describe the ACRN architecture, high-level design, diff --git a/doc/developer-guides/l1tf.rst b/doc/developer-guides/l1tf.rst index 4e4772951..d52803c1b 100644 --- a/doc/developer-guides/l1tf.rst +++ b/doc/developer-guides/l1tf.rst @@ -14,10 +14,10 @@ Refer to `Intel Analysis of L1TF`_ and `Linux L1TF document`_ for details. .. _Linux L1TF document: https://www.kernel.org/doc/html/latest/admin-guide/hw-vuln/l1tf.html -L1 Terminal Fault is a speculative side channel which allows unprivileged -speculative access to data which is available in the Level 1 Data Cache -when the page table entry controlling the virtual address, which is used -for the access, has the Present bit cleared or reserved bits set. +L1 Terminal Fault is a speculative side channel that allows unprivileged +speculative access to data that is available in the Level 1 Data Cache +when the page table entry controlling the virtual address, used +for the access, has the present bit cleared or reserved bits set. When the processor accesses a linear address, it first looks for a 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. 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 (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 @@ -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 1:1 mapping between vCPUs and pCPUs i.e. no sharing of pCPU. There may be an attack possibility when Hyper-threading is on, where -logical processors of 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 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 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. ACRN reserves page ZERO (0~4K) from page allocator thus page ZERO 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 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 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, where the whole software stack (from ACRN hypervisor to guest kernel to Service VM root) is tightly controlled by solution provider -and not allowed for run-time change after sale (guest kernel is +and not allowed for run time change after sale (guest kernel is trusted). In that case solution provider will make sure that guest kernel is up-to-date including necessary page table sanitization, thus there is no attack interface exposed within guest. Then a diff --git a/doc/developer-guides/modularity.rst b/doc/developer-guides/modularity.rst index dbb131ddd..701a3865c 100644 --- a/doc/developer-guides/modularity.rst +++ b/doc/developer-guides/modularity.rst @@ -51,7 +51,7 @@ be resolved by design. `acrn-dev mailing list `_ for discussing if specific callbacks are appropriate. * **Making the cyclic dependency an exception** A specific cyclic dependency can - be regarded as an exception if it is well justified and a 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. Measuring Complexity @@ -81,8 +81,8 @@ The components are listed as follows. initialization. Examples include standard memory and string manipulation functions like strncpy, atomic operations and bitmap operations. This component is independent from and widely used in the other components. -* **Hardware Management and Utilities** This component abstract hardware - resources and provide services like timers and physical interrupt handler +* **Hardware Management and Utilities** This component abstracts hardware + resources and provide services such as timers and physical interrupt handler registration to the upper layers. * **Virtual CPU** This component implements CPU, memory and interrupt virtualization. The vCPU loop module in this component handles VM exit events @@ -95,14 +95,14 @@ The components are listed as follows. * **Passthrough Management** This component manages devices that are passed-through to specific VMs. * **Extended Device Emulation** This component implements an I/O request - mechanism that 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. for emulation. * **VM Management** This component manages the creation, deletion and other lifecycle operations of VMs. * **Hypervisor Initialization** This component invokes the initialization - subroutines in the other components to bring up the hypervisor and start up - Service VM in sharing mode or all the VMs in partitioning mode. + subroutines in the other components to bring up the hypervisor and + start the Service VM in sharing mode or all the VMs in partitioning mode. ACRN hypervisor adopts a layered design where higher layers can invoke the interfaces of lower layers but not vice versa. The only exception is the diff --git a/doc/developer-guides/sw_design_guidelines.rst b/doc/developer-guides/sw_design_guidelines.rst index 7f4aa72d7..40804ad79 100644 --- a/doc/developer-guides/sw_design_guidelines.rst +++ b/doc/developer-guides/sw_design_guidelines.rst @@ -29,7 +29,7 @@ below: Pre-conditions shall be defined right before the definition/declaration of the corresponding function in the C source file or header file. 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 version for some cases. Verification of the hypervisor shall check whether 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. All post-conditions shall be guaranteed by the function. All callers of the 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 version for some cases. Verification of the hypervisor shall check whether the function guarantees all post-conditions (or not). @@ -73,7 +73,7 @@ below: - Configuration data defined by external safety application, such as physical 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, 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 -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 ---------------------- @@ -162,7 +162,7 @@ shown in :numref:`rules_arch_level` below. +====================+=========================+==============+===========================+=========================+ | 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 | - | | | | document explicitly | | + | | | | document explicitly. | | | +-------------------------+--------------+---------------------------+-------------------------+ | | Invalid hypercall | Yes | The hypervisor shall | Invalid hypercall | | | 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 | | provided by | invalid boot information| | panic during platform | invalid boot information| - | bootloader | | | initialization | | + | bootloader | | | initialization. | | | (GRUB or SBL) | | | | | +--------------------+-------------------------+--------------+---------------------------+-------------------------+ | 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 | - | hypervisor | platform or invalid | | initialization | platform or invalid | + | hypervisor | platform or invalid | | initialization. | platform or invalid | | | 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 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 @@ -240,7 +240,7 @@ Functional Safety Consideration Data verification, and explicit specification of pre-conditions and post-conditions are applied for internal functions of the hypervisor according to Table A.4 of -FuSa Standards [IEC_61508-3_2010]_ . +FuSA Standards [IEC_61508-3_2010]_ . 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 | | 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 correctness and the | | allocation. | | | | test cases will verify the | | | | | | related pre-conditions. | | | - | | | If the design can not | | | + | | | If the design cannot | | | | | | guarantee the correctness, | | | | | | the related error handling | | | | | | 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 | | | | | | 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 | | | | are required. | code, data, and bss) and | statically. | | | | 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 a module level. -**Example_1: Analyze the function 'partition_mode_vpci_init'** +**Example_1: Analyze the function ``partition_mode_vpci_init``** .. code-block:: c @@ -374,53 +375,53 @@ pre-conditions and ``get_vm_config`` itself shall guarantee the post-condition. 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. -**Question_2: Is error checking required for 'vdev'?** +**Question_2: Is error checking required for ``vdev``?** No. Here are the reasons: -a) The pre-condition of ``partition_mode_vpci_init`` guarantees that 'vm' is not - NULL. It indicates that 'vpci' is not NULL. Since 'vdev' is getting data from - the array 'pci_vdevs[]' via indexing, 'vdev' is not NULL as long as the index +a) The pre-condition of ``partition_mode_vpci_init`` guarantees that ``vm`` is not + NULL. It indicates that ``vpci`` is not NULL. Since ``vdev`` is getting data from + the array ``pci_vdevs[]`` via indexing, ``vdev`` is not NULL as long as the index is valid. -b) The post-condition of ``get_vm_config`` guarantees that 'vpci->pci_vdev_cnt' - is less than or equal to 'CONFIG_MAX_PCI_DEV_NUM', which is the array size of - 'pci_vdevs[]'. It indicates that the index used to get 'vdev' is always +b) The post-condition of ``get_vm_config`` guarantees that ``vpci->pci_vdev_cnt`` + is less than or equal to ``CONFIG_MAX_PCI_DEV_NUM``, which is the array size of + ``pci_vdevs[]``. It indicates that the index used to get ``vdev`` is always valid. -Given the two reasons above, 'vdev' is always not NULL. So, the error checking -codes are not required for 'vdev'. +Given the two reasons above, ``vdev`` is always not NULL. So, the error checking +codes are not required for ``vdev``. -**Question_3: Is error checking required for 'pci_dev_config'?** +**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. For physical PCI device information, the related application constraints shall be defined in the design document or safety manual. For debug purpose, developers could use ASSERT here to catch the Board Support Package or firmware -failures, which 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: -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 -checking codes are not required for 'vdev->ops->init'. +Given the two reasons above, ``vdev->ops->init`` is always not NULL. So, the error +checking codes are not required for ``vdev->ops->init``. -**Question_5: How to handle the case when 'vdev->ops->init(vdev)' returns non-zero?** +**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. 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. -**Example_2: Analyze the function 'partition_mode_vpci_deinit'** +**Example_2: Analyze the function ``partition_mode_vpci_deinit``** .. 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. @@ -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; -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 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 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. .. note:: The third rule shall be double checked during code review. diff --git a/doc/developer-guides/trusty.rst b/doc/developer-guides/trusty.rst index 1bc2cd54d..acf66996e 100644 --- a/doc/developer-guides/trusty.rst +++ b/doc/developer-guides/trusty.rst @@ -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 #. 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)) #. Resume to next World (UOS_Loader) #. UOS_Loader