diff --git a/doc/getting-started/building-from-source.rst b/doc/getting-started/building-from-source.rst index 98afea57f..0d4c44c8b 100644 --- a/doc/getting-started/building-from-source.rst +++ b/doc/getting-started/building-from-source.rst @@ -6,7 +6,10 @@ Build ACRN from Source Introduction ************ -Following a general embedded-system programming model, the ACRN hypervisor is designed to be customized at build time per hardware platform and per usage scenario, rather than one binary for all scenarios. +Following a general embedded-system programming model, the ACRN +hypervisor is designed to be customized at build time per hardware +platform and per usage scenario, rather than one binary for all +scenarios. The hypervisor binary is generated based on Kconfig configuration settings. Instructions about these settings can be found in @@ -46,10 +49,16 @@ these steps. .. _install-build-tools-dependencies: -Step 1: Install build tools and dependencies -******************************************** +.. rst-class:: numbered-step -ACRN development is supported on popular Linux distributions, each with their own way to install development tools. This user guide covers the different steps to configure and build ACRN natively on your distribution. Refer to the :ref:`building-acrn-in-docker` user guide for instructions on how to build ACRN using a container. +Install build tools and dependencies +************************************ + +ACRN development is supported on popular Linux distributions, each with +their own way to install development tools. This user guide covers the +different steps to configure and build ACRN natively on your +distribution. Refer to the :ref:`building-acrn-in-docker` user guide for +instructions on how to build ACRN using a container. .. note:: ACRN uses ``menuconfig``, a python3 text-based user interface (TUI) for configuring hypervisor options and using python's ``kconfiglib`` library. @@ -88,7 +97,9 @@ Install the necessary tools for the following systems: $ sudo pip3 install kconfiglib .. note:: - Use ``gcc`` version 7.3.* or higher to avoid gcc compilation issues. Follow these instructions to install the ``gcc-7`` package on Ubuntu 18.04: + Use ``gcc`` version 7.3.* or higher to avoid gcc compilation + issues. Follow these instructions to install the ``gcc-7`` package on + Ubuntu 18.04: .. code-block:: none @@ -103,8 +114,10 @@ Install the necessary tools for the following systems: Verify your version of ``binutils`` with the command ``apt show binutils``. -Step 2: Get the ACRN hypervisor source code -******************************************* +.. rst-class:: numbered-step + +Get the ACRN hypervisor source code +*********************************** The `acrn-hypervisor `_ repository contains four main components: @@ -121,8 +134,10 @@ Enter the following to get the acrn-hypervisor source code: $ git clone https://github.com/projectacrn/acrn-hypervisor -Step 3: Build with the ACRN scenario -************************************ +.. rst-class:: numbered-step + +Build with the ACRN scenario +**************************** Currently, the ACRN hypervisor defines these typical usage scenarios: @@ -148,7 +163,7 @@ HYBRID: Assuming that you are at the top level of the acrn-hypervisor directory, perform the following: .. note:: - The release version is built by default, 'RELEASE=0' builds the debug version. + The release version is built by default, ``RELEASE=0`` builds the debug version. * Build the ``INDUSTRY`` scenario on the ``nuc7i7dnb``: @@ -156,14 +171,11 @@ Assuming that you are at the top level of the acrn-hypervisor directory, perform $ make all BOARD=nuc7i7dnb SCENARIO=industry RELEASE=0 -* Build the ``INDUSTRY`` scenario on the ``whl-ipc-i5``: +* Build the ``HYBRID`` scenario on the ``whl-ipc-i5``: .. code-block:: none - $ make all BOARD=whl-ipc-i5 SCENARIO=industry BOARD_FILE=/absolute_path/ - acrn-hypervisor/misc/acrn-config/xmls/board-xmls/whl-ipc-i5.xml SCENARIO_FILE= - /absolute_patch/acrn-hypervisor/misc/acrn-config/xmls/config-xmls/whl-ipc-i5/industry.xml - RELEASE=0 + $ make all BOARD=whl-ipc-i5 SCENARIO=hybrid RELEASE=0 * Build the ``SDC`` scenario on the ``nuc6cayh``: @@ -176,8 +188,10 @@ for each scenario. .. _getting-started-hypervisor-configuration: -Step 4: Build the hypervisor configuration -****************************************** +.. rst-class:: numbered-step + +Build the hypervisor configuration +********************************** Modify the hypervisor configuration =================================== @@ -200,7 +214,8 @@ top level of the acrn-hypervisor directory. The configuration file, named $ make defconfig BOARD=nuc6cayh The BOARD specified is used to select a ``defconfig`` under -``arch/x86/configs/``. The other command line-based options (e.g. ``RELEASE``) take no effect when generating a defconfig. +``arch/x86/configs/``. The other command line-based options (e.g. +``RELEASE``) take no effect when generating a defconfig. To modify the hypervisor configurations, you can either edit ``.config`` manually, or you can invoke a TUI-based menuconfig--powered by kconfiglib--by @@ -213,7 +228,7 @@ configurations and build the hypervisor using the updated ``.config``: # Modify the configurations per your needs $ cd ../ # Enter top-level folder of acrn-hypervisor source - $ make menuconfig -C hypervisor BOARD=kbl-nuc-i7 Note that ``menuconfig`` is python3 only. @@ -224,8 +239,10 @@ Refer to the help on menuconfig for a detailed guide on the interface: $ pydoc3 menuconfig -Step 5: Build the hypervisor, device model, and tools -***************************************************** +.. rst-class:: numbered-step + +Build the hypervisor, device model, and tools +********************************************* Now you can build all these components at once as follows: @@ -247,17 +264,24 @@ If you only need the hypervisor, use this command: The ``acrn.efi`` will be generated in the ``./hypervisor/build/acrn.efi`` directory hypervisor. -As mentioned in :ref:`ACRN Configuration Tool `, the Board configuration and VM configuration can be imported from XML files. -If you want to build the hypervisor with XML configuration files, specify -the file location as follows: +As mentioned in :ref:`ACRN Configuration Tool `, the +Board configuration and VM configuration can be imported from XML files. +If you want to build the hypervisor with XML configuration files, +specify the file location as follows (assuming you're current directory +is at the top level of the acrn-hypervisor directory): .. code-block:: none $ make BOARD_FILE=$PWD/misc/acrn-config/xmls/board-xmls/nuc7i7dnb.xml \ - SCENARIO_FILE=$PWD/misc/acrn-config/xmls/config-xmls/nuc7i7dnb/industry.xml FIRMWARE=uefi + SCENARIO_FILE=$PWD/misc/acrn-config/xmls/config-xmls/nuc7i7dnb/industry.xml FIRMWARE=uefi TARGET_DIR=xxx -Note that the file path must be absolute. Both of the ``BOARD`` and ``SCENARIO`` parameters are not needed because the information is retrieved from the XML file. Adjust the example above to your own environment path. +.. note:: + The ``BOARD`` and ``SCENARIO`` parameters are not needed because the + information is retrieved from the corresponding ``BOARD_FILE`` and + ``SCENARIO_FILE`` XML configuration files. The ``TARGET_DIR`` parameter + specifies what directory is used to store configuration files imported + from XML files. If the ``TARGED_DIR`` it is not specified, the original + configuration files of acrn-hypervisor would be overridden. Follow the same instructions to boot and test the images you created from your build. - diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index 4ae6becca..939514fe0 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -18,7 +18,7 @@ are discussed in the following sections. Hypervisor configuration ======================== -The hypervisor configuration configures a working scenario and target +The hypervisor configuration defines a working scenario and target board by configuring the hypervisor image features and capabilities such as setting up the log and the serial port. @@ -49,9 +49,9 @@ VMs on each user scenario. It also includes **launch script-based** VM configuration information, where parameters are passed to the device model to launch post-launched User VMs. -Scenario based VM configurations are organized as ``*.c/*.h`` files, the -reference are located in the ``acrn-hypervisor/hypervisor/scenarios/$(SCENARIO)/`` -folder. +Scenario based VM configurations are organized as ``*.c/*.h`` files. The +reference scenarios are located in the +``acrn-hypervisor/hypervisor/scenarios/$(SCENARIO)/`` folder. User VM launch script samples are located in the ``acrn-hypervisor/devicemodel/samples/`` folder. @@ -107,7 +107,7 @@ Additional scenario XML elements: Specify the final build is for Release or Debug. ``SERIAL_CONSOLE`` (a child node of ``DEBUG_OPTIONS``): - Specify the host serial device which is used for hypervisor debug. + Specify the host serial device is used for hypervisor debugging. ``MEM_LOGLEVEL`` (a child node of ``DEBUG_OPTIONS``): Specify the default log level in memory. @@ -122,33 +122,34 @@ Additional scenario XML elements: Specify the bitmap of consoles where logs are printed. ``LOG_BUF_SIZE`` (a child node of ``DEBUG_OPTIONS``): - Specify the capacity of log buffer for each physical CPU. + Specify the capacity of the log buffer for each physical CPU. ``RELOC`` (a child node of ``FEATURES``): - Specify whether enable hypervisor image relocation when boot. + Specify whether hypervisor image relocation is enabled on booting. ``SCHEDULER`` (a child node of ``FEATURES``): - Specify the CPU scheduler to be used by the hypervisor. + Specify the CPU scheduler used by the hypervisor. Supported schedulers are: ``SCHED_NOOP``, ``SCHED_BVT`` and ``SCHED_IORR``. ``MULTIBOOT2`` (a child node of ``FEATURES``): - Specify whether support boot ACRN hypervisor image from multiboot2 protocol. - ACRN hypervisor support boot from multiboot protocol always. + Specify whether ACRN hypervisor image can be booted using multiboot2 protocol. + If not set, GRUB's multiboot2 is not available as a boot option. ``HYPERV_ENABLED`` (a child node of ``FEATURES``): - Specify whether enable Hyper-V enlightenment. + Specify whether Hyper-V is enabled. ``IOMMU_ENFORCE_SNP`` (a child node of ``FEATURES``): - Specify whether IOMMU enforce snoop behavior of DMA operation. + Specify whether IOMMU enforces snoop behavior of DMA operation. ``ACPI_PARSE_ENABLED`` (a child node of ``FEATURES``): - Specify whether enable ACPI runtime parsing. + Specify whether ACPI runtime parsing is enabled.. ``L1D_VMENTRY_ENABLED`` (a child node of ``FEATURES``): - Specify whether enable L1 cache flush before VM entry. + Specify whether L1 cache flush before VM entry is enabled. ``MCE_ON_PSC_DISABLED`` (a child node of ``FEATURE``): - Specify whether force to disable software workaround for Machine Check Error on Page Size Change. + Specify whether force to disable software workaround for Machine Check + Error on Page Size Change is enabled. ``STACK_SIZE`` (a child node of ``MEMORY``): Specify the size of stacks used by physical cores. Each core uses one stack @@ -203,36 +204,27 @@ Additional scenario XML elements: Specify the VM with VMID by its "id" attribute. ``vm_type``: - Current support VM type: + Current supported VM types are: - ``SAFETY_VM`` pre-launched Safety VM - - ``PRE_STD_VM`` pre-launched Standard VM - - ``SOS_VM`` pre-launched Service VM - - ``POST_STD_VM`` post-launched Standard VM - - ``POST_RT_VM`` post-launched Realtime capable VM - - ``KATA_VM`` post-launched Kata Container VM + - ``SAFETY_VM`` pre-launched Safety VM + - ``PRE_STD_VM`` pre-launched Standard VM + - ``SOS_VM`` pre-launched Service VM + - ``POST_STD_VM`` post-launched Standard VM + - ``POST_RT_VM`` post-launched realtime capable VM + - ``KATA_VM`` post-launched Kata Container VM ``name`` (a child node of ``vm``): - Specify the VM name which will be shown in the hypervisor console command: vm_list. + Specify the VM name shown in the hypervisor console command: vm_list. ``guest_flags``: Select all applicable flags for the VM: - ``GUEST_FLAG_SECURE_WORLD_ENABLED`` specify whether secure world is enabled - - ``GUEST_FLAG_LAPIC_PASSTHROUGH`` specify whether LAPIC is passed through - - ``GUEST_FLAG_IO_COMPLETION_POLLING`` specify whether the hypervisor needs - IO polling to completion - - ``GUEST_FLAG_HIDE_MTRR`` specify whether to hide MTRR from the VM - - ``GUEST_FLAG_RT`` specify whether the vm is RT-VM + - ``GUEST_FLAG_SECURE_WORLD_ENABLED`` specify whether secure world is enabled + - ``GUEST_FLAG_LAPIC_PASSTHROUGH`` specify whether LAPIC is passed through + - ``GUEST_FLAG_IO_COMPLETION_POLLING`` specify whether the hypervisor needs + IO polling to completion + - ``GUEST_FLAG_HIDE_MTRR`` specify whether to hide MTRR from the VM + - ``GUEST_FLAG_RT`` specify whether the VM is RT-VM (realtime) ``cpu_affinity``: List of pCPU: the guest VM is allowed to create vCPU from all or a subset of this list. @@ -260,10 +252,12 @@ Additional scenario XML elements: Currently supports ``KERNEL_BZIMAGE`` and ``KERNEL_ZEPHYR``. ``kern_mod`` (a child node of ``os_config``): - The tag for the kernel image that acts as a multiboot module; it must exactly match the module tag in the GRUB multiboot cmdline. + The tag for the kernel image that acts as a multiboot module; it must + exactly match the module tag in the GRUB multiboot cmdline. ``ramdisk_mod`` (a child node of ``os_config``): - The tag for the ramdisk image which acts as a multiboot module; it must exactly match the module tag in the GRUB multiboot cmdline. + The tag for the ramdisk image which acts as a multiboot module; it + must exactly match the module tag in the GRUB multiboot cmdline. ``bootargs`` (a child node of ``os_config``): For internal use and is not configurable. Specify the kernel boot arguments @@ -290,16 +284,19 @@ Additional scenario XML elements: vCOM irq. ``target_vm_id`` (a child node of ``vuart1``): - COM2 is used for VM communications. When it is enabled, specify which target VM the current VM connects to. + COM2 is used for VM communications. When it is enabled, specify which + target VM the current VM connects to. ``target_uart_id`` (a child node of ``vuart1``): Target vUART ID that vCOM2 connects to. ``pci_dev_num``: - PCI devices number of the VM; it is hard-coded for each scenario so it is not configurable for now. + PCI devices number of the VM; it is hard-coded for each scenario so it + is not configurable for now. ``pci_devs``: - PCI devices list of the VM; it is hard-coded for each scenario so it is not configurable for now. + PCI devices list of the VM; it is hard-coded for each scenario so it + is not configurable for now. ``board_private``: Stores scenario-relevant board configuration. @@ -338,24 +335,27 @@ current scenario has: Specify the User VM memory size in Mbyte. ``gvt_args``: - GVT arguments for the VM. Set it to ``gvtd`` for GVTd, otherwise stand for GVTg arguments. - The GVTg Input format: ``low_gm_size high_gm_size fence_sz``, The recommendation is ``64 448 8``. - Leave it blank to disable the GVT. + GVT arguments for the VM. Set it to ``gvtd`` for GVTd, otherwise stand + for GVTg arguments. The GVTg Input format: ``low_gm_size high_gm_size fence_sz``, + The recommendation is ``64 448 8``. Leave it blank to disable the GVT. ``vbootloader``: Virtual bootloader type; currently only supports OVMF. ``vuart0``: - Specify whether the device model emulates the vUART0(vCOM1); refer to :ref:`vuart_config` for details. - If set to ``Enable``, the vUART0 is emulated by the device model; - if set to ``Disable``, the vUART0 is emulated by the hypervisor if it is configured in the scenario XML. + Specify whether the device model emulates the vUART0(vCOM1); refer to + :ref:`vuart_config` for details. If set to ``Enable``, the vUART0 is + emulated by the device model; if set to ``Disable``, the vUART0 is + emulated by the hypervisor if it is configured in the scenario XML. ``poweroff_channel``: - Specify whether the User VM power off channel is through the IOC, Powerbutton, or vUART. + Specify whether the User VM power off channel is through the IOC, + Powerbutton, or vUART. ``usb_xhci``: - USB xHCI mediator configuration. Input format: ``bus#-port#[:bus#-port#: ...]``. e.g.: ``1-2:2-4``. - refer to :ref:`usb_virtualization` for details. + USB xHCI mediator configuration. Input format: + ``bus#-port#[:bus#-port#: ...]``, e.g.: ``1-2:2-4``. + Refer to :ref:`usb_virtualization` for details. ``passthrough_devices``: Select the passthrough device from the lspci list; currently we support: @@ -372,7 +372,8 @@ current scenario has: ``console`` (a child node of ``virtio_devices``): The virtio console device setting. - Input format: ``[@]stdio|tty|pty|sock:portname[=portpath][,[@]stdio|tty|pty:portname[=portpath]]``. + Input format: + ``[@]stdio|tty|pty|sock:portname[=portpath][,[@]stdio|tty|pty:portname[=portpath]]``. .. note::