diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 10e1b7402..c3508e378 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -48,9 +48,9 @@ the TSC and its membership, are described in the project's `technical-charter`_. These are the current TSC voting members and chair person: -- Anthony Xu (chair): anthony.xu@intel.com +- Junjie Mao (chair): junjie.mao@intel.com - Helmut Buchsbaum: helmut.buchsbaum@tttech-industrial.com -- Thomas Gleixner: tglx@linutronix.de +- Thomas Gleixner: thomas.gleixner@intel.com .. _ACRN user mailing list: https://lists.projectacrn.org/g/acrn-user .. _BSD 3-Clause license: https://github.com/projectacrn/acrn-hypervisor/blob/master/LICENSE diff --git a/doc/.known-issues/doc/pdf.conf b/doc/.known-issues/doc/pdf.conf index 6015f088c..0b244e75d 100644 --- a/doc/.known-issues/doc/pdf.conf +++ b/doc/.known-issues/doc/pdf.conf @@ -3,7 +3,7 @@ # ^WARNING: Not copying tabs assets! Not compatible with latex builder # -^Latexmk: Summary of warnings: +^Latexmk: Summary of warnings.*: ^ Latex failed to resolve [0-9]+ reference\(s\) ^ Latex failed to resolve [0-9]+ citation\(s\) # @@ -20,3 +20,7 @@ ^ =====Latex reported missing or unavailable character\(s\). ^=====See log file for details. # +^Collected error summary \(may duplicate other messages\): +^ pdflatex: Command for 'pdflatex' gave return code 1 +^ Refer to 'acrn.log' for details +# diff --git a/doc/Makefile b/doc/Makefile index e254c6a6f..9729cb358 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -15,6 +15,9 @@ BUILDDIR ?= _build SOURCEDIR = $(BUILDDIR)/rst LATEXMKOPTS = -silent +# should the config option doc show hidden config options? +XSLTPARAM ?= --stringparam showHidden 'n' + # document publication assumes the folder structure is setup # with the acrn-hypervisor and projectacrn.github.io repos as # sibling folders and make is run inside the acrn-hypervisor/docs @@ -54,7 +57,7 @@ content: $(Q)scripts/extract_content.py $(SOURCEDIR) misc $(Q)mkdir -p $(SOURCEDIR)/misc/config_tools/schema $(Q)rsync -rt ../misc/config_tools/schema/*.xsd $(SOURCEDIR)/misc/config_tools/schema - $(Q)xsltproc -xinclude ./scripts/configdoc.xsl $(SOURCEDIR)/misc/config_tools/schema/config.xsd > $(SOURCEDIR)/reference/configdoc.txt + $(Q)xsltproc $(XSLTPARAM) -xinclude ./scripts/configdoc.xsl $(SOURCEDIR)/misc/config_tools/schema/config.xsd > $(SOURCEDIR)/reference/configdoc.txt html: content doxy @@ -69,7 +72,7 @@ singlehtml: content doxy pdf: html @echo now making $(BUILDDIR)/latex/acrn.pdf - -$(Q)make -silent latexpdf LATEXMKOPTS=$(LATEXMKOPTS) >> $(BUILDDIR)/doc.log 2>&1 + $(Q)make -silent latexpdf LATEXMKOPTS=$(LATEXMKOPTS) >> $(BUILDDIR)/doc.log 2>&1 $(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log diff --git a/doc/conf.py b/doc/conf.py index 23a838bb0..2819686fa 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -319,7 +319,7 @@ VerbatimBorderColor={HTML}{00285A}', # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'acrn.tex', u'Project ACRN Documentation', - u'Project ACRN', 'manual'), + u'Project ACRN', 'manual',True), ] latex_logo = 'images/ACRN_Logo_PrimaryLockup_COLOR-300x300-1.png' diff --git a/doc/develop.rst b/doc/develop.rst index 885794f72..8283ec5c0 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -39,9 +39,9 @@ Configuration Tutorials tutorials/acrn_configuration_tool tutorials/board_inspector_tool + tutorials/acrn_configurator_tool tutorials/upgrading_configuration reference/config-options - reference/config-options-launch reference/hv-make-options user-guides/hv-parameters user-guides/kernel-parameters @@ -57,7 +57,6 @@ Advanced Features .. toctree:: :maxdepth: 1 - tutorials/nvmx_virtualization tutorials/vuart_configuration tutorials/rdt_configuration tutorials/vcat_configuration diff --git a/doc/getting-started/overview_dev.rst b/doc/getting-started/overview_dev.rst index b21481445..028090bad 100644 --- a/doc/getting-started/overview_dev.rst +++ b/doc/getting-started/overview_dev.rst @@ -72,8 +72,9 @@ See :ref:`hardware`. Select Your Scenario ==================== -A scenario defines a specific ACRN configuration, such as the type and number of -VMs that can be run, their attributes, and the resources they have access to. +A scenario defines a specific ACRN configuration, such as hypervisor +capabilities, the type and number of VMs that can be run, their attributes, and +the resources they have access to. This image shows an example of an ACRN scenario to illustrate the types of VMs that ACRN offers: @@ -82,13 +83,12 @@ that ACRN offers: ACRN offers three types of VMs: -* **Pre-launched User VMs**: These VMs are automatically launched at boot time - by the hypervisor. They run independently of other VMs and own dedicated - hardware resources, such as a CPU core, memory, and I/O devices. Other VMs, - including the Service VM, may not even be aware of a pre-launched VM's - existence. The configuration of pre-launched VMs is static and must be defined - at build time. They are well-suited for safety-critical applications and where - very strict isolation, including from the Service VM, is desirable. +* **Pre-launched User VMs**: These VMs run independently of other VMs and own + dedicated hardware resources, such as CPU cores, memory, and I/O devices. + Other VMs, including the Service VM, may not even be aware of a pre-launched + VM's existence. The configuration of pre-launched VMs is static and must be + defined at build time. They are well-suited for safety-critical applications + and where very strict isolation, including from the Service VM, is desirable. * **Service VM**: A special VM, required for scenarios that have post-launched User VMs. The Service VM can access hardware resources directly by running @@ -116,29 +116,29 @@ meet their requirements without pre-launched VMs. Even if your application has stringent real-time requirements, start by testing the application on a post-launched VM before considering a pre-launched VM. -Predefined Scenarios ---------------------- +Scenario Types +--------------- -To help accelerate the configuration process, ACRN offers the following -:ref:`predefined sample scenarios `: +ACRN categorizes scenarios into :ref:`three types `: * **Shared scenario:** This scenario represents a traditional computing, memory, and device resource sharing model among VMs. It has post-launched User VMs and the required Service VM. There are no pre-launched VMs in this scenario. -* **Partitioned scenario:** This scenario has pre-launched User VMs to - demonstrate VM partitioning: the User VMs are independent and isolated, and - they do not share resources. There is no need for the Service VM or Device - Model because all partitioned VMs run native device drivers and directly - access their configured resources. +* **Partitioned scenario:** This scenario has pre-launched User VMs only. It + demonstrates VM partitioning: the User VMs are independent and isolated, and + they do not share resources. For example, a pre-launched VM may not share a + storage device with any other VM, so each pre-launched VM requires its own + boot device. There is no need for the Service VM or Device Model because all + partitioned VMs run native device drivers and directly access their configured + resources. * **Hybrid scenario:** This scenario simultaneously supports both sharing and - partitioning on the consolidated system. It has pre-launched and + partitioning on the consolidated system. It has pre-launched VMs and post-launched VMs, along with the Service VM. -ACRN provides predefined configuration files and documentation to help you set -up these scenarios. You can customize the files for your use case, as described -later in :ref:`overview_dev_config_editor`. +While designing your scenario, keep these concepts in mind as you will see them +mentioned in ACRN components and documentation. |icon_host| Step 2: Prepare the Development Computer **************************************************** @@ -160,7 +160,7 @@ ACRN: .. |icon_target| image:: ./images/icon_target.png -The :ref:`board_inspector_tool` ``board_inspector.py``, found in the ACRN +The :ref:`board_inspector_tool`, found in the ACRN hypervisor source code, enables you to generate a board configuration file on the target system. @@ -181,8 +181,8 @@ You must configure all of your target's BIOS settings before running the Board Inspector tool, because the tool records the current BIOS settings in the board configuration file. -ACRN requires the BIOS settings listed in :ref:`gsg-board-setup` of the Getting -Started Guide. +ACRN requires the BIOS settings listed in :ref:`gsg-board-setup` of +the Getting Started Guide. Use the Board Inspector to Generate a Board Configuration File ============================================================== @@ -208,67 +208,22 @@ and :ref:`overview_dev_build`. |icon_host| Step 4: Generate a Scenario Configuration File and Launch Scripts ***************************************************************************** -The :ref:`acrn_configurator_tool` ``acrn_configurator.py`` enables you to -configure your ACRN hypervisor and VMs via a web-based user interface on your -development computer. Using the tool, you define your scenario settings and save -them to a scenario configuration file. For scenarios with post-launched User -VMs, you must also configure and generate launch scripts. +The :ref:`acrn_configurator_tool` lets you configure your scenario settings via +a graphical user interface (GUI) on your development computer. -The following sections provide an overview and important information to keep -in mind when using the ACRN Configurator. +The tool imports the board configuration file that you generated in +:ref:`overview_dev_board_config`. Then you can configure your scenario, such as +set hypervisor capabilities, add VMs, modify their attributes, and delete VMs. +The tool validates your inputs against your board configuration file to ensure +the scenario is supported by the target hardware. The tool saves your settings +to a **scenario configuration file** in XML format. You will need this file in +:ref:`overview_dev_build`. -Generate a Scenario Configuration File -====================================== - -A **scenario configuration file** defines a working scenario by configuring -hypervisor capabilities and defining some VM attributes and resources. We call -these settings "static" because they are used to build the hypervisor. The file -contains: - -* All hypervisor settings -* All pre-launched User VM settings -* All Service VM settings -* Some post-launched User VM settings, while other settings are in - the launch script - -Before using the ACRN Configurator to generate a scenario configuration -file, be sure you have the board configuration file that you generated in -:ref:`overview_dev_board_config`. The tool needs the board configuration file to -validate that your custom scenario is supported by the target hardware. - -You can use the tool to create a new scenario configuration file or modify an -existing one, such as a predefined scenario described in -:ref:`overview_dev_hw_scenario`. The tool's GUI enables you to edit the -configurable items in the file, such as adding VMs, modifying VM attributes, or -deleting VMs. The tool validates your inputs against your board configuration -file. After validation is successful, the tool generates your custom scenario -configuration file in XML format. - -Generate Launch Scripts -======================= - -A **launch script** invokes the Service VM's Device Model to create a -post-launched User VM. The launch script defines settings needed to launch the -User VM and emulate the devices configured for sharing with that User VM. We -call these settings "dynamic" because they are used at runtime. - -Before using the ACRN Configurator to generate a launch script, be sure -you have your board configuration file and scenario configuration file. The tool -needs both files to validate your launch script configuration. - -The process of generating launch scripts begins by choosing to create a new -launch configuration or modify an existing one. You then use the GUI to -edit the configurable settings of each post-launched User VM in your scenario. -The tool validates your inputs against your board configuration file and -scenario configuration file. After validation is successful, the tool generates -your custom launch configuration file in XML format. You then use the tool to -generate the launch scripts. The tool creates one launch script for each VM -defined in the launch configuration file. - -.. note:: - The ACRN Configurator may not show all editable - parameters for scenario configuration files and launch scripts. You can edit - the parameters manually. See :ref:`acrn_config_data`. +If your scenario configuration has post-launched User VMs, the tool also +generates a **launch script** for each of those VMs. The launch script contains +the settings needed to launch the User VM and emulate the devices configured for +sharing with that User VM. You will run this script in the Service VM in +:ref:`overview_dev_install`. .. _overview_dev_build: @@ -284,8 +239,7 @@ If your scenario has a Service VM, you also need to build the ACRN kernel for the Service VM. The ACRN kernel source code provides a predefined configuration file and a makefile to build the ACRN kernel binary and associated components. The kernel build can take 15 minutes or less on a fast computer, but could take -an hour or more depending on the performance of your development computer. For -more information about the kernel parameters, see :ref:`kernel-parameters`. +an hour or more depending on the performance of your development computer. .. _overview_dev_install: @@ -303,9 +257,10 @@ At a high level, you will: * Configure GRUB to boot the ACRN hypervisor, pre-launched VMs, and Service VM. Reboot the target, and launch ACRN. -* If your scenario contains a post-launched VM, install an OS image for the +* If your scenario contains a post-launched User VM, install an OS image for the post-launched VM and run the launch script you created in - :ref:`overview_dev_config_editor`. + :ref:`overview_dev_config_editor`. The script invokes the Service VM's Device + Model to create the User VM. Learn More ********** @@ -313,6 +268,5 @@ Learn More * To get ACRN up and running for the first time, see the :ref:`gsg` for step-by-step instructions. -* If you have already completed the :ref:`gsg` , see the - :ref:`develop_acrn` for more information about complex scenarios, advanced - features, and debugging. +* If you have already completed the :ref:`gsg` , see the :ref:`develop_acrn` for + more information about configuring and debugging ACRN. diff --git a/doc/reference/config-options-launch.rst b/doc/reference/config-options-launch.rst deleted file mode 100644 index 2b04dd230..000000000 --- a/doc/reference/config-options-launch.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _launch-config-options: - -Launch Configuration Options -############################## - -As explained in :ref:`acrn_configuration_tool`, launch configuration files -define post-launched User VM settings. This document describes these option settings. - -``user_vm``: - Specify the User VM ``id`` to the Service VM. - -``user_vm_type``: - Specify the User VM type, such as ``CLEARLINUX``, ``ANDROID``, ``ALIOS``, - ``PREEMPT-RT LINUX``, ``GENERIC LINUX``, ``WINDOWS``, ``YOCTO``, ``UBUNTU``, - ``ZEPHYR`` or ``VXWORKS``. - -``rtos_type``: - Specify the User VM Real-time capability: Soft RT, Hard RT, or none of them. - -``mem_size``: - Specify the User VM memory size in megabytes. - -``vbootloader``: - Virtual bootloader type; 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. - -``enable_ptm``: - Enable the Precision Timing Measurement (PTM) feature. - -``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. - -``shm_regions``: - List of shared memory regions for inter-VM communication. - -``shm_region`` (a child node of ``shm_regions``): - Configure the shared memory regions for the current VM, input format: - ``[hv|dm]:/,``. Refer to :ref:`ivshmem-hld` - for details. - -``console_vuart``: - Enable a PCI-based console vUART. Refer to :ref:`vuart_config` for details. - -``communication_vuarts``: - List of PCI-based communication vUARTs. Refer to :ref:`vuart_config` for - details. - -``communication_vuart`` (a child node of ``communication_vuarts``): - Enable a PCI-based communication vUART with its ID. Refer to - :ref:`vuart_config` for details. - -``passthrough_devices``: - Select the passthrough device from the PCI device list. We support: - ``usb_xdci``, ``audio``, ``audio_codec``, ``ipu``, ``ipu_i2c``, - ``cse``, ``wifi``, ``bluetooth``, ``sd_card``, - ``ethernet``, ``sata``, and ``nvme``. - -``network`` (a child node of ``virtio_devices``): - The virtio network device setting. - Input format: ``[,vhost][,mac=]``. - The ```` is the name of the TAP (or MacVTap) device. - It must include the keyword ``tap``. ``vhost`` specifies the - vhost backend; otherwise, the VBSU backend is used. The ``mac`` - address is optional. - -``block`` (a child node of ``virtio_devices``): - The virtio block device setting. - Input format: ``[blk partition:][img path]`` e.g.: ``/dev/sda3:./a/b.img``. - -``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]]``. - -``cpu_affinity``: - A comma-separated list of Service VM vCPUs assigned to this VM. A Service VM vCPU is identified - by its lapic ID. - -.. note:: - - The ``configurable`` and ``readonly`` attributes are used to mark - whether the item is configurable for users. When ``configurable="n"`` - and ``readonly="y"``, the item is not configurable from the web - interface. When ``configurable="n"``, the item does not appear on the - interface. diff --git a/doc/reference/config-options.rst b/doc/reference/config-options.rst index a49824fda..fa1b76a63 100644 --- a/doc/reference/config-options.rst +++ b/doc/reference/config-options.rst @@ -37,19 +37,19 @@ String .. comment These images are used in generated option documentation -.. |icon-advanced| image:: images/Advanced.svg +.. |icon-advanced| image:: images/Advanced.png :alt: Find this option on the Configurator's Advanced Parameters tab -.. |icon-basic| image:: images/Basic.svg +.. |icon-basic| image:: images/Basic.png :alt: Find this option on the Configurator's Basic Parameters tab -.. |icon-not-available| image:: images/Not-available.svg +.. |icon-not-available| image:: images/Not-available.png :alt: This is a hidden option and not user-editable using the Configurator -.. |icon-post-launched-vm| image:: images/Post-launched-VM.svg +.. |icon-post-launched-vm| image:: images/Post-launched-VM.png :alt: Find this option on a Configurator Post-launched VM tab -.. |icon-pre-launched-vm| image:: images/Pre-launched-VM.svg +.. |icon-pre-launched-vm| image:: images/Pre-launched-VM.png :alt: Find this option on a Configurator Pre-launched VM tab -.. |icon-service-vm| image:: images/Service-VM.svg +.. |icon-service-vm| image:: images/Service-VM.png :alt: Find this option on the Configurator Service VM tab -.. |icon-hypervisor| image:: images/Hypervisor.svg +.. |icon-hypervisor| image:: images/Hypervisor.png :alt: Find this option on the Configurator's Hypervisor Global Settings tab We use icons within an option description to indicate where the option can be diff --git a/doc/reference/images/Advanced.png b/doc/reference/images/Advanced.png new file mode 100644 index 000000000..b1ba00112 Binary files /dev/null and b/doc/reference/images/Advanced.png differ diff --git a/doc/reference/images/Basic.png b/doc/reference/images/Basic.png new file mode 100644 index 000000000..4163e22ac Binary files /dev/null and b/doc/reference/images/Basic.png differ diff --git a/doc/reference/images/Hypervisor.png b/doc/reference/images/Hypervisor.png new file mode 100644 index 000000000..9283544fd Binary files /dev/null and b/doc/reference/images/Hypervisor.png differ diff --git a/doc/reference/images/Not-available.png b/doc/reference/images/Not-available.png new file mode 100644 index 000000000..92a1ebb8f Binary files /dev/null and b/doc/reference/images/Not-available.png differ diff --git a/doc/reference/images/Post-launched-VM.png b/doc/reference/images/Post-launched-VM.png new file mode 100644 index 000000000..bd376f5f2 Binary files /dev/null and b/doc/reference/images/Post-launched-VM.png differ diff --git a/doc/reference/images/Pre-launched-VM.png b/doc/reference/images/Pre-launched-VM.png new file mode 100644 index 000000000..9d85bea36 Binary files /dev/null and b/doc/reference/images/Pre-launched-VM.png differ diff --git a/doc/reference/images/Service-VM.png b/doc/reference/images/Service-VM.png new file mode 100644 index 000000000..f399afc64 Binary files /dev/null and b/doc/reference/images/Service-VM.png differ diff --git a/doc/scripts/configdoc.xsl b/doc/scripts/configdoc.xsl index 435964083..035a562b5 100644 --- a/doc/scripts/configdoc.xsl +++ b/doc/scripts/configdoc.xsl @@ -5,6 +5,8 @@ + + @@ -57,7 +59,7 @@ described as an option --> - + diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index a47e47856..6af41903d 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -202,6 +202,3 @@ The ``scenario`` attribute specifies the scenario name and must match the The ``user_vm_launcher`` attribute specifies the number of post-launched User VMs in a scenario. - -See :ref:`launch-config-options` for a full explanation of available launch -XML elements. diff --git a/doc/tutorials/acrn_configurator_tool.rst b/doc/tutorials/acrn_configurator_tool.rst new file mode 100644 index 000000000..d9b209f1b --- /dev/null +++ b/doc/tutorials/acrn_configurator_tool.rst @@ -0,0 +1,360 @@ +.. _acrn_configurator_tool: + +ACRN Configurator Tool +###################### + +This guide describes all features and uses of the tool. + +About the ACRN Configurator Tool +********************************* + +The ACRN Configurator ``acrn_configurator.py`` provides a user interface to help +you customize your :ref:`ACRN configuration `. +Capabilities: + +* Reads board information from the specified board configuration file +* Helps you configure a scenario of hypervisor and VM settings +* Generates a scenario configuration file that stores the configured settings in + XML format +* Generates a launch script for each post-launched User VM + +Prerequisites +************* + +This guide assumes you have a board configuration file and have successfully +launched the ACRN Configurator. For steps, see the following Getting Started +Guide sections: + +* :ref:`gsg-target-hardware` +* :ref:`gsg-dev-computer` +* :ref:`gsg-board-setup` +* :ref:`gsg-dev-setup` + +Start with a New or Existing Configuration +****************************************** + +When the ACRN Configurator opens, the introduction screen appears. + +.. image:: images/configurator-intro.png + :align: center + :class: drop-shadow + +The introduction screen lets you start a new configuration or use an existing +one by selecting a working folder. + +As described in :ref:`acrn_configuration_tool`, a configuration defines one +ACRN instance, and its data is stored in a set of configuration files: + +* One board configuration file +* One scenario configuration file +* One launch script per post-launched VM + +When you use the ACRN Configurator, it saves these files in the selected working +folder. + +Each configuration must have a unique working folder. For example, imagine you +want to create three configurations. Perhaps you want to create a configuration +for three different boards, or you have one board but want to create three sets +of hypervisor settings to test on it. You would need to select a different +working folder for each configuration. After you have selected the working +folder in the ACRN Configurator, it saves the configuration files there. The +following figure shows an example file system consisting of a top-level folder, +``acrn-work``, and a working folder for each configuration, ``ConfigA``, +``ConfigB``, and ``ConfigC``. + +.. image:: images/config-file.png + :align: center + +Start a New Configuration +========================== + +You can start by selecting a new working folder. The tool assumes you are +starting from scratch. It checks the folder for existing configuration files, +such as a board configuration file, scenario configuration file, and launch +scripts. If it finds any, it will delete them. + +1. Under **Start a new configuration**, use the displayed working folder or + select a different folder by clicking **Browse for folder**. + + .. image:: images/configurator-newconfig.png + :align: center + :class: drop-shadow + +#. If the folder contains configuration files, the tool displays a message about + deleting the files. Click **OK** to delete the files. + +#. Click **Use This Folder**. + +Use an Existing Configuration +============================= + +You can use an existing configuration by selecting a working folder that has one +or more configuration files in it. For example, the folder can contain a board +configuration file alone, or a board configuration file and scenario +configuration file. The tool uses the information in the files to populate the +UI, so that you can continue working on the configuration where you left off. + +1. Under **Use an existing configuration**, use the displayed working folder or + select a different folder by clicking **Browse for folder**. + + .. image:: images/configurator-exconfig.png + :align: center + :class: drop-shadow + +#. Click **Open Folder**. + +Navigate the Configuration Screen +********************************* + +After you have selected a working folder, the tool opens the second (and final) +screen, where you can customize your configuration. The following figure shows +an example: + +.. image:: images/configurator-configscreen.png + :align: center + :class: drop-shadow + +At the top of the screen, the tool shows the selected working folder. To return +to the introduction screen, click the arrow next to the working folder path: + +.. image:: images/configurator-backintro.png + :align: center + :class: drop-shadow + +The rest of the configuration screen is divided into three panels: + +1. Import a board configuration file +#. Create new or import an existing scenario +#. Configure settings for scenario and launch scripts + +The panels are labeled 1, 2, and 3 to guide you through the configuration steps. +The tool also enforces this order of operation by enabling each panel only after +you have completed the preceding panel. + +The title bar of each panel has an arrow icon. Click the icon to expand +or collapse the panel. + +.. image:: images/configurator-expand.png + :align: center + :class: drop-shadow + +Import a Board Configuration File +********************************** + +The first step in the configuration process is to import the board configuration +file generated via the :ref:`board_inspector_tool`. You can import a board configuration file for the first time, or replace the existing file. + +Import a Board Configuration File for the First Time +==================================================== + +If the working folder doesn't have a board configuration file, the tool shows +that no board information has been imported yet. + +To import a board configuration file for the first time: + +1. Under **Import a board configuration file**, select a scenario configuration + file from the dropdown menu or click **Browse for file** to select a + different file. + + .. image:: images/configurator-board01.png + :align: center + :class: drop-shadow + +#. Click **Import Board File**. + +The tool makes a copy of your board configuration file, changes the +file extension to ``.board.xml``, and saves the file in the working folder. + +The tool displays the current board information. Example: + +.. image:: images/configurator-board02.png + :align: center + :class: drop-shadow + +Replace an Existing Board Configuration File +============================================ + +After a board configuration file has been imported, you can choose to replace it +at any time. This option is useful, for example, when you need to iterate your +board's configuration while you are customizing your hypervisor settings. +Whenever you change the configuration of your board, you must generate a new +board configuration file via the :ref:`board_inspector_tool`. Examples include +changing any BIOS setting such as hyper-threading, adding or removing a physical +device, or adding or removing memory. If this happens after you've started +customizing your hypervisor in the ACRN Configurator, you can import the new +board file into your existing configuration and continue editing. + +To replace an existing board configuration file: + +1. Under **Import a board configuration file**, click **Use a Different Board**. + + .. image:: images/configurator-board03.png + :align: center + :class: drop-shadow + +#. Browse to the board configuration file and click **Open**. + +#. The tool displays a warning message about overwriting the existing file. + Click **Ok** to proceed. + +The tool replaces the file and displays the new board information. + +Create New or Import an Existing Scenario +******************************************* + +After importing the board configuration file, the next step is to specify an +initial scenario. You can create a new scenario, or import an existing scenario +configuration file. In both cases, this step is a starting point for configuring +your hypervisor and VMs. Later, you can choose to change the configuration, such +as adding or deleting VMs. + +Create a Scenario +================= + +You can create a scenario by specifying an initial number of VMs. + +1. Under **Create new or import an existing scenario**, click **Create + Scenario**. + + .. image:: images/configurator-newscenario01.png + :align: center + :class: drop-shadow + +#. In the dialog box, select a scenario type and number of VMs. The tool + enforces dependencies. For example, a scenario with post-launched VMs must + have a Service VM, so the tool adds a Service VM and doesn't allow you to + delete it here. + + .. image:: images/configurator-newscenario02.png + :align: center + :class: drop-shadow + +#. Click **Ok**. + +The tool displays the name of the scenario configuration file, but it doesn't +save it to the working folder until you click **Save Scenario And Launch +Scripts** in the third panel. + +Import a Scenario Configuration File +==================================== + +You can import an existing scenario configuration file. The tool uses the +information in the file to populate the UI, so that you can continue working on +the configuration where you left off. + +1. Due to the strict validation ACRN adopts, scenario configuration files for a + former release may not work for a latter if they are not upgraded. Starting + from v3.0, upgrade an older scenario XML per the steps in + :ref:`upgrading_configuration` then import the upgraded file into the tool in + the next step. + +#. Under **Create new or import an existing scenario**, go to the right side of + the screen and select a scenario configuration file from the dropdown menu or + click **Browse for scenario file** to select a different file. + + .. image:: images/configurator-exscenario.png + :align: center + :class: drop-shadow + +#. Click **Import Scenario**. + +The tool displays the name of the scenario configuration file, but it doesn't +save it to the working folder until you click **Save Scenario And Launch +Scripts** in the third panel. + +Configure Settings for Scenario and Launch Scripts +************************************************** + +After creating a scenario or importing an existing one, you can configure +hypervisor and VM parameters, as well as add or delete VMs. + +Configure the Hypervisor and VM Parameters +========================================== + +1. Click the hypervisor or VM tab in the selector menu. The selected tab is + darker in color. + + .. image:: images/configurator-selecthypervisor.png + :align: center + :class: drop-shadow + +#. Click the Basic Parameters tab or Advanced Parameters tab and make updates. + To learn more about each parameter, hover over the |tooltip| icon for a short + description or go to :ref:`scenario-config-options` for documentation. + + .. |tooltip| image:: images/tooltip.png + +Basic parameters are generally defined as: + +* Parameters that are necessary for ACRN configuration, compilation, and + execution. + +* Parameters that are common for software like ACRN. + +Advanced parameters are generally defined as: + +* Parameters that are optional for ACRN configuration, compilation, and + execution. + +* Parameters that are used for fine-grained tuning, such as reducing code + lines or optimizing performance. Default values cover most use cases. + +Add a VM +========= + +In the selector menu, click **+** to add a pre-launched VM or post-launched VM. + +.. image:: images/configurator-addvm.png + :align: center + :class: drop-shadow + +Delete a VM +============ + +1. In the selector menu, click the VM tab. The selected tab is darker in color. + +#. Click **Delete VM**. + + .. image:: images/configurator-deletevm.png + :align: center + :class: drop-shadow + +Save and Check for Errors +========================= + +#. To save your configuration, click **Save Scenario And Launch Scripts** at the + top of the panel. + + .. image:: images/configurator-save.png + :align: center + :class: drop-shadow + + The tool saves your configuration data in a set of files in the working folder: + + * Scenario configuration file (``scenario.xml``): Raw format of all + hypervisor and VM settings. You will need this file to build ACRN. + + * One launch script per post-launched VM (``launch_user_vm_id*.sh``): This + file is used to start the post-launched VM in the Service VM. You can find + the VM's name inside the script: + + .. code-block:: bash + + # Launch script for VM name: + + The tool validates hypervisor and VM settings whenever you save. If an error + occurs, such as an empty required field, the tool saves the changes to the + files, but prompts you to correct the error. Error messages appear below the + applicable settings. Example: + + .. image:: images/configurator-rederror.png + :align: center + :class: drop-shadow + +#. Fix the errors and save again to generate a valid configuration. + +Next Steps +========== + +After generating a valid scenario configuration file, you can build ACRN. See +:ref:`gsg_build`. \ No newline at end of file diff --git a/doc/tutorials/images/config-file.png b/doc/tutorials/images/config-file.png new file mode 100644 index 000000000..36354e6f7 Binary files /dev/null and b/doc/tutorials/images/config-file.png differ diff --git a/doc/tutorials/images/configurator-addvm.png b/doc/tutorials/images/configurator-addvm.png new file mode 100644 index 000000000..c88ebb7a9 Binary files /dev/null and b/doc/tutorials/images/configurator-addvm.png differ diff --git a/doc/tutorials/images/configurator-backintro.png b/doc/tutorials/images/configurator-backintro.png new file mode 100644 index 000000000..021d252a0 Binary files /dev/null and b/doc/tutorials/images/configurator-backintro.png differ diff --git a/doc/tutorials/images/configurator-board01.png b/doc/tutorials/images/configurator-board01.png new file mode 100644 index 000000000..e159c2d44 Binary files /dev/null and b/doc/tutorials/images/configurator-board01.png differ diff --git a/doc/tutorials/images/configurator-board02.png b/doc/tutorials/images/configurator-board02.png new file mode 100644 index 000000000..f100ec34c Binary files /dev/null and b/doc/tutorials/images/configurator-board02.png differ diff --git a/doc/tutorials/images/configurator-board03.png b/doc/tutorials/images/configurator-board03.png new file mode 100644 index 000000000..0b4401a2a Binary files /dev/null and b/doc/tutorials/images/configurator-board03.png differ diff --git a/doc/tutorials/images/configurator-configscreen.png b/doc/tutorials/images/configurator-configscreen.png new file mode 100644 index 000000000..9cd4e6db4 Binary files /dev/null and b/doc/tutorials/images/configurator-configscreen.png differ diff --git a/doc/tutorials/images/configurator-deletevm.png b/doc/tutorials/images/configurator-deletevm.png new file mode 100644 index 000000000..8c6b8172a Binary files /dev/null and b/doc/tutorials/images/configurator-deletevm.png differ diff --git a/doc/tutorials/images/configurator-exconfig.png b/doc/tutorials/images/configurator-exconfig.png new file mode 100644 index 000000000..79ecbdeda Binary files /dev/null and b/doc/tutorials/images/configurator-exconfig.png differ diff --git a/doc/tutorials/images/configurator-expand.png b/doc/tutorials/images/configurator-expand.png new file mode 100644 index 000000000..d8910d054 Binary files /dev/null and b/doc/tutorials/images/configurator-expand.png differ diff --git a/doc/tutorials/images/configurator-exscenario.png b/doc/tutorials/images/configurator-exscenario.png new file mode 100644 index 000000000..7a2e1301b Binary files /dev/null and b/doc/tutorials/images/configurator-exscenario.png differ diff --git a/doc/tutorials/images/configurator-intro.png b/doc/tutorials/images/configurator-intro.png new file mode 100644 index 000000000..45a4ddc9b Binary files /dev/null and b/doc/tutorials/images/configurator-intro.png differ diff --git a/doc/tutorials/images/configurator-newconfig.png b/doc/tutorials/images/configurator-newconfig.png new file mode 100644 index 000000000..ba6641abc Binary files /dev/null and b/doc/tutorials/images/configurator-newconfig.png differ diff --git a/doc/tutorials/images/configurator-newscenario01.png b/doc/tutorials/images/configurator-newscenario01.png new file mode 100644 index 000000000..6cba6bef9 Binary files /dev/null and b/doc/tutorials/images/configurator-newscenario01.png differ diff --git a/doc/tutorials/images/configurator-newscenario02.png b/doc/tutorials/images/configurator-newscenario02.png new file mode 100644 index 000000000..ae108fe66 Binary files /dev/null and b/doc/tutorials/images/configurator-newscenario02.png differ diff --git a/doc/tutorials/images/configurator-rederror.png b/doc/tutorials/images/configurator-rederror.png new file mode 100644 index 000000000..ba78b367e Binary files /dev/null and b/doc/tutorials/images/configurator-rederror.png differ diff --git a/doc/tutorials/images/configurator-save.png b/doc/tutorials/images/configurator-save.png new file mode 100644 index 000000000..e59cf792a Binary files /dev/null and b/doc/tutorials/images/configurator-save.png differ diff --git a/doc/tutorials/images/configurator-selecthypervisor.png b/doc/tutorials/images/configurator-selecthypervisor.png new file mode 100644 index 000000000..fabc47f8f Binary files /dev/null and b/doc/tutorials/images/configurator-selecthypervisor.png differ diff --git a/doc/tutorials/images/tooltip.png b/doc/tutorials/images/tooltip.png new file mode 100644 index 000000000..42f703f7e Binary files /dev/null and b/doc/tutorials/images/tooltip.png differ diff --git a/doc/tutorials/nvmx_virtualization.rst b/doc/tutorials/nvmx_virtualization.rst deleted file mode 100644 index 1c02e7758..000000000 --- a/doc/tutorials/nvmx_virtualization.rst +++ /dev/null @@ -1,351 +0,0 @@ -.. _nested_virt: - -Enable Nested Virtualization -############################ - -With nested virtualization enabled in ACRN, you can run virtual machine -instances inside of a guest VM (also called a User VM) running on the ACRN hypervisor. -Although both "level 1" guest VMs and nested guest VMs can be launched -from the Service VM, the following distinction is worth noting: - -* The VMX feature (``CPUID01.01H:ECX[5]``) does not need to be visible to the Service VM - in order to launch guest VMs. A guest VM not running on top of the - Service VM is considered a level 1 (L1) guest. - -* The VMX feature must be visible to an L1 guest to launch a nested VM. An instance - of a guest hypervisor (KVM) runs on the L1 guest and works with the - L0 ACRN hypervisor to run the nested VM. - -The conventional single-level virtualization has two levels - the L0 host -(ACRN hypervisor) and the L1 guest VMs. With nested virtualization enabled, -ACRN can run guest VMs with their associated virtual machines that define a -third level: - -* The host (ACRN hypervisor), which we call the L0 hypervisor -* The guest hypervisor (KVM), which we call the L1 hypervisor -* The nested guest VMs, which we call the L2 guest VMs - -.. figure:: images/nvmx_1.png - :width: 700px - :align: center - - Generic Nested Virtualization - - -High-Level ACRN Nested Virtualization Design -******************************************** - -The high-level design of nested virtualization in ACRN is shown in :numref:`nested_virt_hld`. -Nested VMX is enabled by allowing a guest VM to use VMX instructions, -and emulating them using the single level of VMX available in the hardware. - -In x86, a logical processor uses a VM control structure (named VMCS in Intel -processors) to manage the state for each vCPU of its guest VMs. These VMCSs -manage VM entries and VM exits as well as processor behavior in VMX non-root -operation. We'll suffix each VMCS with two digits, the hypervisor level managing -it, and the VM level it represents. For example, L0 stores the state of L1 in -VMCS01. The trick of nVMX emulation is ACRN builds a VMCS02 out of the VMCS01, -which is the VMCS ACRN uses to run the L1 VM, and VMCS12 which is built by L1 -hypervisor to actually run the L2 guest. - -.. figure:: images/nvmx_arch_1.png - :width: 400px - :align: center - :name: nested_virt_hld - - Nested Virtualization in ACRN - -#. L0 hypervisor (ACRN) runs L1 guest with VMCS01 - -#. L1 hypervisor (KVM) creates VMCS12 to run a L2 guest - -#. VMX instructions from L1 hypervisor trigger VMExits to L0 hypervisor: - -#. L0 hypervisor runs a L2 guest with VMCS02 - - a. L0 caches VMCS12 in host memory - #. L0 merges VMCS01 and VMCS12 to create VMCS02 - -#. L2 guest runs until triggering VMExits to L0 - - a. L0 reflects most VMExits to L1 hypervisor - #. L0 runs L1 guest with VMCS01 and VMCS02 as the shadow VMCS - - -Restrictions and Constraints -**************************** - -Nested virtualization is considered an experimental feature, and only tested -on Tiger Lake and Kaby Lake platforms (see :ref:`hardware`). - -L1 VMs have the following restrictions: - -* KVM is the only L1 hypervisor supported by ACRN -* KVM runs in 64-bit mode -* KVM enables EPT for L2 guests -* QEMU is used to launch L2 guests - -Constraints on L1 guest configuration: - -* Local APIC passthrough must be enabled -* Only the ``SCHED_NOOP`` scheduler is supported. ACRN can't receive timer interrupts - on LAPIC passthrough pCPUs - -VPID Allocation -=============== - -ACRN doesn't emulate L2 VPIDs and allocates VPIDs for L1 VMs from the reserved top -16-bit VPID range (``0x10000U - CONFIG_MAX_VM_NUM * MAX_VCPUS_PER_VM`` and up). -If the L1 hypervisor enables VPID for L2 VMs and allocates L2 VPIDs not in this -range, ACRN doesn't need to flush L2 VPID during L2 VMX transitions. - -This is the expected behavior most of the time. But in special cases where a -L2 VPID allocated by L1 hypervisor is within this reserved range, it's possible -that this L2 VPID may conflict with a L1 VPID. In this case, ACRN flushes VPID -on L2 VMExit/VMEntry that are associated with this L2 VPID, which may significantly -negatively impact performances of this L2 VM. - - -Service VM Configuration -************************* - -ACRN only supports enabling the nested virtualization feature on the Service VM, not on pre-launched -VMs. - -The nested virtualization feature is disabled by default in ACRN. You can -enable it using the :ref:`ACRN Configurator ` -with these settings: - -.. note:: Normally you'd use the ACRN Configurator GUI to edit the scenario XML file. - The tool wasn't updated in time for the v2.5 release, so you'll need to manually edit - the ACRN scenario XML configuration file to edit the ``SCHEDULER``, ``pcpu_id``, - ``guest_flags``, ``legacy_vuart``, and ``console_vuart`` settings for - the Service VM, as shown below. - -#. Configure system level features: - - - Edit ``hv.features.scheduler`` to ``SCHED_NOOP`` to disable CPU sharing - - .. code-block:: xml - :emphasize-lines: 3,18 - - - y - SCHED_NOOP - y - y - - n - y - 0xfff - 0xfff - 0xfff - 0xfff - 0xfff - 0xfff - 0xfff - 0xfff - - y - -#. In each guest VM configuration: - - - Edit ``vm.nested_virtualization_support`` on the Service VM section and set it to `y` - to enable the nested virtualization feature on the Service VM. - - Edit ``vm.lapic_passthrough`` and set it to `y` to enable local - APIC passthrough on the Service VM. - - Edit ``vm.cpu_affinity.pcpu_id`` to assign ``pCPU`` IDs to run the Service VM. If you are - using debug build and need the hypervisor console, don't assign - ``pCPU0`` to the Service VM. - - .. code-block:: xml - :emphasize-lines: 5,6,7,10,11 - - - SERVICE_VM - ACRN_Service_VM - - 1 - 2 - 3 - - - GUEST_FLAG_NVMX_ENABLED - GUEST_FLAG_LAPIC_PASSTHROUGH - - - The Service VM's virtual legacy UART interrupt doesn't work with LAPIC - passthrough, which may prevent the Service VM from booting. Instead, we need to use - the PCI-vUART for the Service VM. Refer to :ref:`Enable vUART Configurations ` - for more details about VUART configuration. - - - Set ``vm.console_vuart`` to ``PCI`` - - .. code-block:: xml - :emphasize-lines: 1 - - PCI - -#. Remove CPU sharing VMs - - Since CPU sharing is disabled, you may need to delete all ``POST_STD_VM`` and - ``KATA_VM`` VMs from the scenario configuration file, which may share a pCPU - with the Service VM. - -#. Follow instructions in :ref:`gsg` and build with this XML configuration. - - -Prepare for Service VM Kernel and rootfs -**************************************** - -The Service VM can run Ubuntu or other Linux distributions. -Instructions on how to boot Ubuntu as the Service VM can be found in -:ref:`gsg`. - -The Service VM kernel needs to be built from the ``acrn-kernel`` repo, and some changes -to the kernel ``.config`` are needed. -Instructions on how to build and install the Service VM kernel can be found -in :ref:`gsg`. - -Here is a summary of how to modify and build the kernel: - -.. code-block:: none - - git clone https://github.com/projectacrn/acrn-kernel - cd acrn-kernel - cp kernel_config_service_vm .config - make olddefconfig - -The following configuration entries are needed to launch nested -guests on the Service VM: - -.. code-block:: none - - CONFIG_KVM=y - CONFIG_KVM_INTEL=y - CONFIG_ACRN_GUEST=y - -After you make these configuration modifications, build and install the kernel -as described in :ref:`gsg`. - - -Launch a Nested Guest VM -************************ - -Create an Ubuntu KVM Image -========================== - -Refer to :ref:`Build the Ubuntu KVM Image ` -on how to create an Ubuntu KVM image as the nested guest VM's root filesystem. -There is no particular requirement for this image, e.g., it could be of either -qcow2 or raw format. - -Prepare for Launch Scripts -========================== - -Install QEMU on the Service VM that will launch the nested guest VM: - -.. code-block:: none - - sudo apt-get install qemu-kvm qemu virt-manager virt-viewer libvirt-bin - -.. important:: The QEMU ``-cpu host`` option is needed to launch a nested guest VM, and ``-nographics`` - is required to run nested guest VMs reliably. - -You can prepare the script just like the one you use to launch a VM -on native Linux. For example, other than ``-hda``, you can use the following option to launch -a virtio block based RAW image:: - - -drive format=raw,file=/root/ubuntu-20.04.img,if=virtio - -Use the following option to enable Ethernet on the guest VM:: - - -netdev tap,id=net0 -device virtio-net-pci,netdev=net0,mac=a6:cd:47:5f:20:dc - -The following is a simple example for the script to launch a nested guest VM. - -.. code-block:: bash - :emphasize-lines: 2-4 - - sudo qemu-system-x86_64 \ - -enable-kvm \ - -cpu host \ - -nographic \ - -m 2G -smp 2 -hda /root/ubuntu-20.04.qcow2 \ - -net nic,macaddr=00:16:3d:60:0a:80 -net tap,script=/etc/qemu-ifup - -Launch the Guest VM -=================== - -You can launch the nested guest VM from the Service VM's virtual serial console -or from an SSH remote login. - -If the nested VM is launched successfully, you should see the nested -VM's login prompt: - -.. code-block:: console - - [ OK ] Started Terminate Plymouth Boot Screen. - [ OK ] Started Hold until boot process finishes up. - [ OK ] Starting Set console scheme... - [ OK ] Started Serial Getty on ttyS0. - [ OK ] Started LXD - container startup/shutdown. - [ OK ] Started Set console scheme. - [ OK ] Started Getty on tty1. - [ OK ] Reached target Login Prompts. - [ OK ] Reached target Multi-User System. - [ OK ] Started Update UTMP about System Runlevel Changes. - - Ubuntu 20.04 LTS ubuntu_vm ttyS0 - - ubuntu_vm login: - -You won't see the nested guest from a ``vcpu_list`` or ``vm_list`` command -on the ACRN hypervisor console because these commands only show level 1 VMs. - -.. code-block:: console - - ACRN:\>vm_list - - VM_UUID VM_ID VM_NAME VM_STATE - ================================ ===== ========================== - dbbbd4347a574216a12c2201f1ab0240 0 ACRN_Service_VM Running - ACRN:\>vcpu_list - - VM ID PCPU ID VCPU ID VCPU ROLE VCPU STATE THREAD STATE - ===== ======= ======= ========= ========== ============ - 0 1 0 PRIMARY Running RUNNING - 0 2 1 SECONDARY Running RUNNING - 0 3 2 SECONDARY Running RUNNING - -On the nested guest VM console, run an ``lshw`` or ``dmidecode`` command -and you'll see that this is a QEMU-managed virtual machine: - -.. code-block:: console - :emphasize-lines: 4,5 - - $ sudo lshw -c system - ubuntu_vm - description: Computer - product: Standard PC (i440FX + PIIX, 1996) - vendor: QEMU - version: pc-i440fx-5.2 - width: 64 bits - capabilities: smbios-2.8 dmi-2.8 smp vsyscall32 - configuration: boot=normal - -For example, compare this to the same command run on the L1 guest (Service VM): - -.. code-block:: console - :emphasize-lines: 4,5 - - $ sudo lshw -c system - localhost.localdomain - description: Computer - product: NUC7i5DNHE - vendor: Intel Corporation - version: J57828-507 - serial: DW1710099900081 - width: 64 bits - capabilities: smbios-3.1 dmi-3.1 smp vsyscall32 - configuration: boot=normal family=Intel NUC uuid=36711CA2-A784-AD49-B0DC-54B2030B16AB