1.. _modularity: 2 3ACRN Hypervisor: Modular Design 4############################### 5 6Overview 7******** 8 9ACRN highly emphasizes modular design, which is the separation of 10functionality into modules that define a concise set of interfaces. The goals 11of modular design include: 12 13* **Understandability** A modular design is easier to understand due to 14 encapsulation. 15* **Testability** Modules can be integrated and tested in the reverse order of 16 dependencies among them. Modular integration tests help improve the coverage 17 of tests and identify corner cases that are hard to trigger when testing the 18 hypervisor as a whole. 19* **Configurability** Modular design makes it easy to configure certain 20 functionalities in or out. This is crucial in safety-critical scenarios, 21 because absence of irrelevant code is required in both MISRA-C and 22 functional safety standards. 23* **Meet functional safety requirements** Functional safety standards 24 explicitly require a hierarchical structure of modules in software 25 architectural design. This applies to any safety integrity level defined in 26 [IEC_61508-3]_ and [ISO_26262-6]_. 27 28Principles 29********** 30 31* Each source file belongs to one module only. One module may consist of one 32 or multiple source files, though. A source file can be a C source, a C 33 header, or an assembly file. 34* Each module has well-defined interfaces, including the exported functions 35 and global variables. Functions and variables that are not interfaces are 36 static and used inside the module only. 37* Dependencies among the modules should be acyclic. Any cyclic dependency must 38 be deviated explicitly. 39* The complexity of a module should be limited. 40 41Minimizing Cyclic Dependencies 42============================== 43 44Cyclic dependencies are mostly avoided through careful definition of module 45boundaries. The following methods can be used when a cyclic dependency cannot 46be resolved by design: 47 48* **Use callbacks** Callback registration and invocation help to reverse 49 dependencies between modules and break cyclic dependencies. However, 50 callbacks must be used with care due to their dynamic behavior. Send 51 proposals or patches to the 52 `acrn-dev mailing list <https://lists.projectacrn.org/g/acrn-dev>`_ for 53 discussing whether specific callbacks are appropriate. 54* **Making the cyclic dependency an exception** A specific cyclic dependency 55 can be regarded as an exception if it is well justified and a workaround is 56 available to break the cyclic dependency for integration testing. 57 58Measuring Complexity 59==================== 60 61ACRN uses the number of functions and the cyclomatic complexity [CC]_ of each 62function to measure the complexity of a module. Concrete criteria on 63complexity will be determined during the process of enhancing the modularity 64of the hypervisor. The current recommendation is to limit the cyclomatic 65complexity of a function to under 20. 66 67Architecture 68************ 69 70The following figure shows the high-level components of ACRN hypervisor: 71 72.. figure:: images/modularity-architecture.png 73 :align: center 74 :name: modularity-architecture 75 76 Layered Architecture of ACRN Hypervisor 77 78The components are listed as follows. 79 80* **Boot** This component carries out the most basic hardware initialization 81 to enable the execution of C code. 82* **Library** This component consists of subroutines that require no explicit 83 initialization. Examples include standard memory and string manipulation 84 functions like strncpy, atomic operations, and bitmap operations. This 85 component is independent from and widely used in the other components. 86* **Hardware Management and Utilities** This component abstracts hardware 87 resources and provide services such as timers and physical interrupt handler 88 registration to the upper layers. 89* **Virtual CPU** This component implements CPU, memory, and interrupt 90 virtualization. The vCPU loop module in this component handles VM exit 91 events by calling the proper handler in the other components. Hypercalls are 92 implemented as a special type of VM exit event. This component is also able 93 to inject upcall interrupts to the Service VM. 94* **Device Emulation** This component implements devices that are emulated in 95 the hypervisor itself, such as the virtual programmable interrupt 96 controllers including vPIC, vLAPIC, and vIOAPIC. 97* **Passthrough Management** This component manages devices that are passed 98 through to specific VMs. 99* **Extended Device Emulation** This component implements an I/O request 100 mechanism that enables the hypervisor to forward I/O accesses from a User 101 VM to the Service VM for emulation. 102* **VM Management** This component manages the creation, deletion, and other 103 lifecycle operations of VMs. 104* **Hypervisor Initialization** This component invokes the initialization 105 subroutines in the other components to bring up the hypervisor and start 106 the Service VM in sharing mode or all the VMs in partitioning mode. 107 108ACRN hypervisor adopts a layered design where higher layers can invoke the 109interfaces of lower layers but not vice versa. The only exception is the 110invocation of initialization routine in the **Boot** component, illustrated as 111the arrow from bottom to top on the left side of figure 112:numref:`modularity-architecture`. This exception is made due to the following 113reasons. 114 115* **Boot** enables the execution of C code and thus has to be the lowest layer 116 in the architecture. 117* **Hypervisor Initialization** contains the hypervisor initialization 118 function that calls the initialization functions of each layer. Thus this 119 component is the highest layer to minimize reverse dependencies. 120* **Boot** shall invoke the hypervisor initialization routine after bringing 121 up the hardware. This inevitably causes a reverse dependency from **Boot** 122 to **Hypervisor Initialization**. 123 124To enable integration testing of a layer in the middle (e.g. **Virtual CPU**), 125**Boot** will invoke a customized function that invokes only the 126initialization functions of that layer as well as the layers below. 127 128References 129********** 130 131.. [IEC_61508-3] IEC 61508-3:2010, Functional safety of electrical/electronic/programmable electronic safety-related systems - Part 3: Software requirements 132 133.. [ISO_26262-6] ISO 26262-6:2011, Road vehicles - Functional safety - Part 6: Product development at the software level 134 135.. [CC] Cyclomatic complexity - Wikipedia, https://en.wikipedia.org/wiki/Cyclomatic_complexity 136
