From 79582b996f1d5e4d496a2e7de30017fcae9c97c0 Mon Sep 17 00:00:00 2001 From: Shiqing Gao Date: Tue, 19 Mar 2019 08:44:47 +0800 Subject: [PATCH] doc: update software design guidelines This patch adds the guidelines for 'Module Level Configuration Design'. Signed-off-by: Shiqing Gao --- .../boot_information_parsing_module.png | Bin 0 -> 28189 bytes doc/developer-guides/sw_design_guidelines.rst | 230 ++++++++++++++++++ 2 files changed, 230 insertions(+) create mode 100644 doc/developer-guides/images/boot_information_parsing_module.png diff --git a/doc/developer-guides/images/boot_information_parsing_module.png b/doc/developer-guides/images/boot_information_parsing_module.png new file mode 100644 index 0000000000000000000000000000000000000000..91588ce7680088b942dd04d765a02e4025bf17e6 GIT binary patch literal 28189 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

;elSyEcH<;)+z31u)DknHL*F8XtN{cfVt==Ght zA684|CTI=8IhrkE;x;zbCd#lMiq>;KF`at{g3%xg)dGMI`F$Y&?X+0#>QRj8%0LYh zTqZuGf``!eRd9|ILw8*%>PuSj5t%g!f$lC$-d|5apwd2N*MIe8MRc=uK2hE|mFzsI zo+)`2!+9iX@SptKbG(XPn+BKFu9Pt%DT4BJbkk@4l)u0WfVLEWS>?3|5vk|COkXUe zM=vxVTM{S#_&-~MBFfu3o2m)MCtu#)Vo(0zmpi!A{brxv+};xRp3u-a$UB%_RinK2 zdtKImOL_YD6Ctg^Vf$Oee{BoG`1kK}J3H{F@=*4-t}a9SLC3X{&Md-0Mfwo(#l8x- z)cdK-!Fgx+o^|aZz)h5al@k=0+a9(2QCbc?u|^w-MffQFFxJ@ifGVb zYj#)H;_JS`VHh4A9rawBBXodZ{~=g;6WZEtb+t|sgaE_owa)|UhyVUr9Rq6+weG{M z5C(BiE4H5j-A7Cn9>mZ|S6EQcaG3P;DY0BAs!+vOxwf;>$K<>lw~JbFLTr4yxUY`N zqdtaY3~ti-kcXq!X49V)QhA6qnGyx^cABe`#j=1e>43|l@788G`BJ#c1V{i=w|IUF zsFV2##O}uM{7&vr>MtS2m@K(04$=G+A{a%d1;J;?;a3AU#P*=eM2kKC@{vgzusqQ- zad|zv)2hGZoHh%6vg1HA((LZI8ItS^m&zQZ!TAD(OCqzUB;^G`9-Men2KZQsnsXu3 zc1?D)&=SXl`O7gx(ZYL~P|} z6Vk405lsbUR*;Q=p*uw}1;a&9R5^ zi3@&G^Nr3EeS*PjAF$=&Rd;jr2kgS5j)iMlwQr>@6r%5J8)=Rx>NL}veQ~hOeIMYL zY4F$3esJ0qAAWOfGc1o`y#d|R<^1NMne4|lBYE40}|Kcl3$22ZO>O5$3X)lJNH!&Bap=rNU1Ih`H>=dbCKqbg@K zKDaOT2DY6?G6)o?{v|?ZtZnQYEk|Dxnb!V=d<%~kax&Mt1oQD%8>J$cBUHTl!Map6 z`?ad~gf27De)pS-%b1#Vc$-OBvF_C$shq1mtpqO9LJC*vCC9|Vh;QSxxK+HCTp6R6 zUuMDYfkTQcv+aMVDYx+R&nD_u2FYVj?eB1LP~5s_N)YCHRS;maR|NmESNzrng?7tu z`kX?dfMYX%ZOVUVbhTvn>Ql`FwOU(XH&VxRbr*MFvkU-2>ZJLdR;Ele*HhzzMpj!^ zgf-k&?`|(hx7cqePys%|)Q2Fy8f9OO~wmr5>nRQAz W^Z7&t_<9=*hP)?xH|w^x>wf{{o@fRD literal 0 HcmV?d00001 diff --git a/doc/developer-guides/sw_design_guidelines.rst b/doc/developer-guides/sw_design_guidelines.rst index d3cf35cd8..a15867634 100644 --- a/doc/developer-guides/sw_design_guidelines.rst +++ b/doc/developer-guides/sw_design_guidelines.rst @@ -450,6 +450,236 @@ boot information. Yes. Because 'vdev->ops' and 'vdev->ops->init' can not be guaranteed to be not NULL. If the VM called ``partition_mode_vpci_deinit`` twice, it may be NULL. + +Module Level Configuration Design Guidelines +******************************************** + +Design Goals +============ + +There are two goals for module level configuration design, as shown below: + +a) In order to make the hypervisor more flexible, one source code and binary + is preferred for different platforms with different configurations; + +b) If one module is not used by a specific project, the module source code is + treated as dead code. The effort to configure it in/out shall be minimized. + + +Hypervisor Operation Modes +========================== + +The hypervisor operation modes are shown in +:numref:`hypervisor_operation_modes` below. + +.. table:: Hypervisor Operation Modes + :align: center + :widths: 10 10 50 + :name: hypervisor_operation_modes + + +-------------+-----------+------------------------------------------------------------------------------+ + | Operation | Sub-modes | Description | + | Modes | | | + +=============+===========+==============================================================================+ + | INIT mode | DETECT | The hypervisor detects firmware, detects hardware resource, and reads | + | | mode | configuration data. | + | +-----------+------------------------------------------------------------------------------+ + | | STARTUP | The hypervisor initializes hardware resources, creates virtual resources like| + | | mode | VCPU and VM, and executes VMLAUNCH instruction(the very first VM entry). | + +-------------+-----------+------------------------------------------------------------------------------+ + | OPERATIONAL | N/A | After the first VM entry, the hypervisor runs in VMX root mode and guest OS | + | mode | | runs in VMX non-root mode. | + +-------------+-----------+------------------------------------------------------------------------------+ + | TERMINATION | N/A | If any fatal error is detected, the hypervisor will enter TERMINATION mode. | + | mode | | In this mode, a default fatal error handler will be invoked to handle the | + | | | fatal error. | + +-------------+-----------+------------------------------------------------------------------------------+ + + +Configurable Module Properties +============================== + +The properties of configurable modules are shown below: + +- The functionality of the module depends on platform configurations; +- Corresponding platform configurations can be detected in DETECT mode; +- The module APIs shall be configured in DETECT mode; +- The module APIs shall be used in modes other than DETECT mode. + +Platform configurations include: + +- Features depending on hardware or firmware +- Configuration data provided by firmware +- Configuration data provided by BSP + + +Design Rules +============ + +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 + implemented through a set of function pointers in the operations data + structure; + +3. Every function pointer in the operations data structure shall be instantiated + as one module API in DETECT mode and the API is allowed to be implemented as + empty function for some specific configurations; + +4. The operations data structure shall be read-only in STARTUP mode, OPERATIONAL + mode, and TERMINATION mode; + +5. The configurable module shall only be accessed via APIs in the operations + data structure in STARTUP mode or OPERATIONAL mode; + +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 deferences the function pointer, + instead of checking the pointer for NULL. + +.. note:: The third rule shall be double checked during code review. + +Use Cases +========= + +The following table shows some use cases of module level configuration design: + +.. list-table:: Module Level Configuration Design Use Cases + :widths: 10 25 20 + :header-rows: 1 + + * - **Platform Configuration** + - **Configurable Module** + - **Prerequisite** + + * - Features depending on hardware or firmware + - This module is used to virtualize part of LAPIC functionalities. + It can be done via APICv or software emulation depending on CPU + capabilities. + For example, KBL NUC doesn't support virtual-interrupt delivery, while + other platforms support it. + - If a function pointer is used, the prerequisite is + "hv_operation_mode == OPERATIONAL". + + * - Configuration data provided by firmware + - This module is used to interact with firmware (UEFI or SBL), and the + configuration data is provided by firmware. + For example, UP2 uses SBL and KBL NUC uses UEFI. + - If a function pointer is used, the prerequisite is + "hv_operation_mode != DETECT". + + * - Configuration data provided by BSP + - This module is used to virtualize LAPIC, and the configuration data is + provided by BSP. + For example, some VMs use LAPIC pass-through and the other VMs use + vLAPIC. + - If a function pointer is used, the prerequisite is + "hv_operation_mode == OPERATIONAL". + +.. note:: Prerequisite is used to guarantee that the function pointer used for + configuration is dereferenced after it has been instantiated. + + +Examples +======== + +Take the module for parsing boot information as an example to illustrate the +idea of module level configuration design. + +.. figure:: images/boot_information_parsing_module.png + :align: center + :scale: 70 % + :name: boot_information_parsing_module + + Boot Information Parsing Module + + +As shown in the source code below, 'struct firmware_operations' is an operations +data structure that contains a set of function pointers. +Different firmware may have different implementations: + +- 'firmware_uefi_ops' is for UEFI platform; +- 'firmware_sbl_ops' is for SBL platform. + + +.. code-block:: c + + struct firmware_operations { + void (*init)(void); + uint64_t (*get_ap_trampoline)(void); + void *(*get_rsdp)(void); + void (*init_irq)(void); + int32_t (*init_vm_boot_info)(struct acrn_vm *vm); + }; + + static struct firmware_operations firmware_uefi_ops = { + .init = uefi_init, + .get_ap_trampoline = uefi_get_ap_trampoline, + .get_rsdp = uefi_get_rsdp, + .init_irq = uefi_init_irq, + .init_vm_boot_info = uefi_init_vm_boot_info, + }; + + static struct firmware_operations firmware_sbl_ops = { + .init = sbl_init, + .get_ap_trampoline = sbl_get_ap_trampoline, + .get_rsdp = sbl_get_rsdp, + .init_irq = sbl_init_irq, + .init_vm_boot_info = sbl_init_vm_boot_info, + }; + + +'firmware_ops' is the operations set that is dereferenced and takes effect. + +'init_firmware_operations' is called when the hypervisor is in DETECT mode and +'firmware_ops' is instantiated here to either 'firmware_uefi_ops' or +'firmware_sbl_ops' depending on the platform. + +.. note:: All the other exported interfaces using 'firmware_ops' shall be called + after the instantiation. + + +.. code-block:: c + + static struct firmware_operations *firmware_ops; + + struct firmware_operations* uefi_get_firmware_operations(void) + { + return &firmware_uefi_ops; + } + + struct firmware_operations* sbl_get_firmware_operations(void) + { + return &firmware_sbl_ops; + } + + void init_firmware_operations(void) + { + if (is_firmware_sbl()) { + firmware_ops = sbl_get_firmware_operations(); + } else { + firmware_ops = uefi_get_firmware_operations(); + } + } + + +For example, when the hypervisor needs to initialize the VM boot information, +it calls 'firmware_init_vm_boot_info' and 'firmware_ops->init_vm_boot_info' is +dereferenced here with correct API being called. + +.. code-block:: c + + /** + * @pre firmware_ops->init_vm_boot_info != NULL + */ + int32_t firmware_init_vm_boot_info(struct acrn_vm *vm) + { + return firmware_ops->init_vm_boot_info(vm); + } + + References **********