doc: update draft 3.0 published docs to include changes on master

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

doc/getting-started/getting-started.rst

@@ -58,25 +58,6 @@ Before you begin, make sure your machines have the following prerequisites:
     copying via USB disk, but you can use another method if you prefer)
   - Local storage device (NVMe or SATA drive, for example)
 
-.. _gsg-target-hardware:
-
-.. rst-class:: numbered-step
-
-Set Up the Target Hardware
-**************************
-
-To set up the target hardware environment:
-
-#. Connect the mouse, keyboard, monitor, and power supply cable to the target
-   system.
-
-#. Connect the target system to the LAN with the Ethernet cable.
-
-Example of a target system with cables connected:
-
-.. image:: ./images/gsg_nuc.png
-   :scale: 25%
-
 .. _gsg-dev-computer:
 
 .. rst-class:: numbered-step
@@ -154,7 +135,7 @@ To set up the ACRN build environment on the development computer:
 
    .. code-block:: bash
 
-      sudo pip3 install lxml xmlschema defusedxml tqbm
+      sudo pip3 install lxml xmlschema defusedxml tqdm
 
 #. Create a working directory:
 
@@ -183,10 +164,10 @@ To set up the ACRN build environment on the development computer:
       cd ~/acrn-work
       git clone https://github.com/projectacrn/acrn-hypervisor.git
       cd acrn-hypervisor
-      git checkout acrn-2022w18.4-180000p
+      git checkout release_3.0
 
       cd ..
-      git clone --depth 1 --branch acrn-2022w18.4-180000p https://github.com/projectacrn/acrn-kernel.git
+      git clone --depth 1 --branch release_3.0 https://github.com/projectacrn/acrn-kernel.git
 
 .. _gsg-board-setup:
 
@@ -205,9 +186,29 @@ hardware.
 
 .. important::
 
-   Whenever you change the configuration of the board, such as peripherals, BIOS
+   Before running the Board Inspector, you must set up your target hardware and
-   settings, additional memory, or PCI devices, you must generate a new board
+   BIOS exactly as you want it, including connecting all peripherals,
-   configuration file.
+   configuring BIOS settings, and adding memory and PCI devices. For example,
+   you must connect all USB devices; otherwise, the Board Inspector will not
+   detect the USB devices for passthrough. If you change the hardware or BIOS
+   configuration, or add or remove USB devices, you must run the Board Inspector
+   again to generate a new board configuration file.
+
+Set Up the Target Hardware
+============================
+
+To set up the target hardware environment:
+
+#. Connect all USB devices, such as a mouse and keyboard.
+
+#. Connect the monitor and power supply cable.
+
+#. Connect the target system to the LAN with the Ethernet cable.
+
+Example of a target system with cables connected:
+
+.. image:: ./images/gsg_nuc.png
+   :scale: 25%
 
 Install OS on the Target
 ============================
@@ -323,7 +324,7 @@ Generate a Board Configuration File
    .. code-block:: bash
 
       cd  ~/acrn-work
-      sudo apt install ./acrn-board-inspector*.deb
+      sudo apt install -y ./acrn-board-inspector*.deb
 
 #. Reboot the system:
 
@@ -391,90 +392,11 @@ their attributes, and the resources they have access to.
 A **launch script** is a shell script that is used to configure and create a
 post-launched User VM. Each User VM has its own launch script.
 
-First, you will install dependencies, build the ACRN Configurator Debian
+#. On the development computer, install the ACRN Configurator:
-package, and install it on your development computer. Then you will use the ACRN
-Configurator to generate a scenario configuration file and launch script.
-
-#. On the development computer, install the ACRN Configurator build tools:
 
    .. code-block:: bash
 
-      sudo apt install -y libwebkit2gtk-4.0-dev \
+      sudo apt install -y ~/acrn-work/acrn-hypervisor/build/acrn-configurator_*_amd64.deb # TODO update file path
-         build-essential \
-         curl \
-         wget \
-         libssl-dev \
-         libgtk-3-dev \
-         libappindicator3-dev \
-         librsvg2-dev \
-         python3-venv
-
-#. Install Node.js (npm included) as follows:
-
-   a. We recommend using nvm to manage your Node.js runtime. It allows you to
-      switch versions and update Node.js easily.
-
-      .. code-block:: bash
-
-         curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
-
-   #. Rerun your ``.bashrc`` initialization script and then install the latest
-      version of Node.js and npm:
-
-      .. code-block:: bash
-
-         source ~/.bashrc
-         nvm install node --latest-npm
-         nvm use node
-
-#. Install and upgrade Yarn:
-
-   .. code-block:: bash
-
-      npm install --global yarn
-
-#. Install rustup, the official installer for Rust:
-
-   .. code-block:: bash
-
-      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-
-   When prompted by the Rust installation script, type ``1`` and press
-   :kbd:`Enter`.
-
-   .. code-block:: console
-
-      1) Proceed with installation (default)
-      2) Customize installation
-      3) Cancel installation
-      >1
-
-#. Configure the current shell:
-
-   .. code-block:: bash
-
-      source $HOME/.cargo/env
-
-#. Install additional ACRN Configurator dependencies:
-
-   .. code-block:: bash
-
-      cd ~/acrn-work/acrn-hypervisor/misc/config_tools/configurator
-      python3 -m pip install -r requirements.txt
-      yarn
-
-#. Build the ACRN Configurator Debian package:
-
-   .. code-block:: bash
-
-      cd ~/acrn-work/acrn-hypervisor
-      make configurator
-
-#. Install the ACRN Configurator:
-
-   .. code-block:: bash
-
-      sudo apt install -y ~/acrn-work/acrn-hypervisor/build/acrn-configurator_*_amd64.deb
 
 #. Launch the ACRN Configurator:
 
@@ -482,69 +404,111 @@ Configurator to generate a scenario configuration file and launch script.
 
       acrn-configurator
 
-#. On the left-hand side, look for **Start a new configuration**.
+#. Under **Start a new configuration**, confirm that the working folder is
-   Confirm that the working folder is ``<path to>/acrn-work/MyConfiguration``. Click **Use This Folder**.
+   ``<path to>/acrn-work/MyConfiguration``. Click **Use This Folder**.
 
-   TODO add screenshots to Configurator steps
+   .. image:: images/configurator-newconfig.png
+      :align: center
+      :class: drop-shadow
 
 #. Import your board configuration file as follows:
 
-   a. Under **Import a board configuration file**, click **Browse for file**.
+   a. In the **1. Import a board configuration file** panel, click **Browse for
+      file**.
 
    #. Browse to ``~/acrn-work/my_board.xml`` and click **Open**.
 
    #. Click **Import Board File**.
 
+   .. image:: images/configurator-board01.png
+      :align: center
+      :class: drop-shadow
+
    The ACRN Configurator makes a copy of your board file, changes the file
    extension to ``.board.xml``, and saves the file to the working folder.
 
 #. Create a new scenario as follows:
 
-   a. Under **Create new or import an existing scenario**, click **Create
+   a. In the **2. Create new or import an existing scenario** panel, click
-      Scenario**.
+      **Create Scenario**.
+
+      .. image:: images/configurator-newscenario01.png
+         :align: center
+         :class: drop-shadow
 
    #. In the dialog box, confirm that **Shared (Post-launched VMs only)** is
       selected.
 
    #. Confirm that one Service VM and one post-launched VM are selected.
 
-   #. Click **Create**.
+   #. Click **Ok**.
 
-#. Generate the scenario configuration file and launch script:
+      .. image:: images/configurator-newscenario02.png
+         :align: center
+         :class: drop-shadow
 
-   a. Under **Configure settings for scenario and launch scripts**, the
+#. In the **3. Configure settings for scenario and launch scripts** panel,
-      scenario's configurable items appear. Feel free to look through all the
+   the scenario's configurable items appear. Feel free to look through all
-      available configuration settings. This is where you can change the
+   the available configuration settings. This is where you can change the
-      settings to meet your application's particular needs. But for now, you will update only a few settings to make this example work.
+   settings to meet your application's particular needs. But for now, you
+   will update only a few settings for functional and educational purposes.
 
-   #. Click the **VM1 Post-launched** tab to access the post-launched VM's
+#. Click the **Hypervisor Global Settings > Basic Parameters** tab, select the
-      settings.
+   ``Debug`` build type, and select the serial console port (the example shows
+   ``/dev/ttyS0``, but yours may be different). If your board doesn't have a
+   serial console port, select the ``Release`` build type. The Debug build type
+   requires a serial console port.
 
-   #. Confirm that the Basic Parameters tab is selected, and scroll down to
+   .. image:: images/configurator-buildtype.png
-      **Memory size (MB)**. Change the value to ``1024``. For this example, we
+      :align: center
-      will use Ubuntu 20.04 to boot the post-launched VM. Ubuntu 20.04 needs at
+      :class: drop-shadow
-      least 1024 MB to boot.
 
-   #. Scroll down to **Virtio block device**, click **+**, and enter
+#. Click the **VM0 ServiceVM > Basic Parameters** tab and change the VM name
+   to ``ACRN_Service_VM`` for this example.
+
+   .. image:: images/configurator-servicevm.png
+      :align: center
+      :class: drop-shadow
+
+#. Configure the post-launched VM as follows:
+
+   #. Click the **VM1 Post-launched > Basic Parameters** tab and change the VM
+      name to ``POST_STD_VM1`` for this example.
+
+   #. Confirm that the **OS type** is ``Standard``. In the previous step,
+      ``STD`` in the VM name is short for Standard. 
+
+   #. Scroll down to **Memory size (MB)** and change the value to ``1024``. For
+      this example, we will use Ubuntu 20.04 to boot the post-launched VM.
+      Ubuntu 20.04 needs at least 1024 MB to boot.
+
+   #. For **Physical CPU affinity**, select pCPU ID ``0``, then click **+** and
+      select pCPU ID ``1`` to affine the VM to CPU cores 0 and 1.
+
+   #. For **Virtio block device**, click **+** and enter
       ``~/acrn-work/ubuntu-20.04.4-desktop-amd64.iso``. This parameter
       specifies the VM's OS image and its location on the target system. Later
       in this guide, you will save the ISO file to that directory.
 
-   #. Click **Save Scenario And Launch Scripts** to generate the scenario
+   .. image:: images/configurator-postvm.png
-      configuration file and launch script.
+      :align: center
+      :class: drop-shadow
+
+#. Scroll up to the top of the panel and click **Save Scenario And Launch
+   Scripts** to generate the scenario configuration file and launch script.
 
 #. Click the **x** in the upper-right corner to close the ACRN
    Configurator.
 
-#. Confirm that the scenario configuration file ``scenario.xml`` appears in your
+#. Confirm that the scenario configuration file ``scenario.xml`` appears in the
-   ``acrn-work/MyConfiguration`` directory::
+   working directory::
 
          ls ~/acrn-work/MyConfiguration/scenario.xml
 
-#. Confirm that the launch script ``TODO`` appears in the
+#. Confirm that the launch script appears in the
-   expected output directory::
+   working directory::
 
-         ls ~/acrn-work/MyConfiguration/TODO
+         ls ~/acrn-work/MyConfiguration/launch_user_vm_id1.sh
 
 .. _gsg_build:
 
@@ -695,6 +659,14 @@ The ACRN hypervisor boots the Ubuntu Service VM automatically.
 
       [  0.000000] Hypervisor detected: ACRN
 
+#. Enable and start the Service VM's system daemon for managing network configurations,
+   so the Device Model can create a bridge device (acrn-br0) that provides User VMs with
+   wired network access:
+
+   .. code-block:: bash
+
+      sudo systemctl enable --now systemd-networkd
+
 .. _gsg-user-vm:
 
 .. rst-class:: numbered-step

doc/tutorials/acrn_configuration_tool.rst

@@ -3,20 +3,14 @@
 Introduction to ACRN Configuration
 ##################################
 
-ACRN configuration is designed for System Integrators / Tier 1s to customize
+ACRN configuration is designed for System Integrators and Tier 1s to customize
 ACRN to meet their own needs. It allows users to adapt ACRN to target boards as
 well as configure hypervisor capabilities and provision VMs.
 
 ACRN configuration consists of the following key components.
 
 * Configuration data saved as XML files.
-* A configuration toolset that helps users to generate and edit configuration
+* A configuration toolset to generate and edit configuration data.
-  data. The toolset includes:
-
-  - **Board Inspector**: Collects board-specific information on target
-    machines.
-  - **ACRN Configurator**: Enables you to edit configuration data via a
-    web-based UI.
 
 The following sections introduce the concepts and tools of ACRN configuration
 from the aspects below.
@@ -25,16 +19,14 @@ from the aspects below.
   different types of configuration data.
 * :ref:`acrn_config_workflow` overviews the steps to customize ACRN
   configuration using the configuration toolset.
-* :ref:`acrn_config_data` explains the location and format of configuration
-  data saved as XML files.
 
 .. _acrn_config_types:
 
 Types of Configurations
 ***********************
 
-ACRN includes three types of configurations: board, scenario, and launch. The
+ACRN includes two types of configurations: board and scenario. The
-configuration data are saved in three XML files. The following sections briefly
+configuration data are saved in XML files. The following sections briefly
 describe the objectives and main contents of each file.
 
 Board Configuration File
@@ -60,9 +52,8 @@ Scenario Configuration File
 ===========================
 
 The scenario configuration file defines a working scenario by configuring
-hypervisor capabilities and defining some VM attributes and resources.
+hypervisor capabilities and defining VM attributes and resources. Examples of
-We call these settings "static" because they are used to build the hypervisor.
+parameters:
-You can specify the following information in a scenario configuration:
 
 * Hypervisor capabilities
 
@@ -83,46 +74,29 @@ You can specify the following information in a scenario configuration:
   - User VM settings, such as boot protocol and VM OS kernel parameters.
   - Settings of virtual devices, such as virtual UARTs.
 
-You need a scenario configuration file to build an ACRN hypervisor. The
+You need a scenario configuration file to build an ACRN hypervisor. The build process uses the file to build a hypervisor that can initialize its capabilities and set up the VMs at runtime.
-build process uses the file to build a hypervisor that can initialize its
-capabilities and set up the VMs at runtime.
 
-The scenario configuration defines User VMs as follows:
+For pre-launched User VMs, all attributes and resources are static
+configurations. The VM attributes and resources are exactly the amount of
+resources allocated to them.
 
-* For pre-launched User VMs, the scenario configuration defines all attributes
+For post-launched User VMs, some resources are static configurations. Other
-  and resources (these VMs have static configurations by nature). The VM
+resources are under the control of the Service VM and can be dynamically
-  attributes and resources are exactly the amount
+allocated to a VM via a launch script.
-  of resources allocated to them.
-
-* For post-launched User VMs, the scenario configuration defines only static
-  attributes and resources. Other resources are under the control of the
-  Service VM and can be dynamically allocated to these VMs via launch
-  scripts.
-
-Launch Configuration File for Launch Scripts
-============================================
-
-The launch configuration file applies only to scenarios that have
-post-launched User VMs. The file defines certain attributes and
-resources of the post-launched VMs specified in the scenario configuration
-file. We call these settings "dynamic" because they are used at runtime.
-
-You need a launch configuration file to generate a launch script (shell script)
-for each post-launched User VM. The launch script invokes the
-Service VM's :ref:`Device Model <hld-devicemodel>` ``acrn-dm`` to create
-the VM. Unlike board and scenario configurations used at build time or by
-ACRN hypervisor, launch configurations are used dynamically in the Service VM.
 
 .. _acrn_config_workflow:
 
 Using ACRN Configuration Toolset
 ********************************
 
-The ACRN configuration toolset enables you to create
+The ACRN configuration toolset lets you create and edit configuration data. The
-and edit configuration data. The toolset consists of the following:
+toolset includes:
 
-* :ref:`Board Inspector <board_inspector_tool>`
+* :ref:`Board Inspector <board_inspector_tool>`: Collects information from your
-* :ref:`ACRN Configurator <acrn_configurator_tool>`
+  target machine and generates a board configuration file.
+* :ref:`ACRN Configurator <acrn_configurator_tool>`: Provides a graphical user
+  interface (GUI) for configuring your hypervisor and VM parameters, and
+  generates a scenario configuration file and launch scripts.
 
 As introduced in :ref:`overview_dev`, configuration takes place at
 :ref:`overview_dev_board_config` and :ref:`overview_dev_config_editor` in
@@ -132,73 +106,3 @@ the overall development process:
 
 ACRN source also includes makefile targets to aid customization. See
 :ref:`hypervisor-make-options`.
-
-.. _acrn_config_data:
-
-ACRN Configuration Data
-***********************
-
-The following sections explain the format of the board, scenario, and launch
-configuration files. Although we recommend using the ACRN configuration toolset
-to create these files, this reference may be useful for advanced usage and
-troubleshooting.
-
-ACRN source code offers predefined XMLs, and the generic templates used for
-new boards and scenarios, in the ``misc/config_tools/data/`` directory of
-the ``acrn-hypervisor`` repo.
-
-Board XML Format
-================
-
-The board XML has an ``acrn-config`` root element and a
-``board`` attribute:
-
-.. code-block:: xml
-
-   <acrn-config board="BOARD">
-
-The ``board`` attribute defines the board name and must match the
-``board`` attribute in the scenario configuration file and the launch
-configuration file. The file name of the board configuration file
-(example: ``my_board.xml``) doesn't affect the board name.
-
-Board XML files are input to the ACRN Configurator tool and the build system,
-and are not intended for end users to modify.
-
-Scenario XML Format
-===================
-
-The scenario XML has an ``acrn-config`` root element as well as ``board`` and
-``scenario`` attributes:
-
-.. code-block:: xml
-
-   <acrn-config board="BOARD" scenario="SCENARIO">
-
-The ``board`` attribute specifies the board name and must match the ``board``
-attribute in the board configuration file.
-
-The ``scenario`` attribute specifies the scenario name, followed by hypervisor
-and VM settings.
-
-See :ref:`scenario-config-options` for a full explanation of available scenario
-XML elements.
-
-Launch XML Format
-=================
-
-The launch XML has an ``acrn-config`` root element as well as
-``board``, ``scenario``, and ``user_vm_launcher`` attributes:
-
-.. code-block:: xml
-
-   <acrn-config board="BOARD" scenario="SCENARIO" user_vm_launcher="USER_VM_NUMBER">
-
-The ``board`` attribute specifies the board name and must match the ``board``
-attribute in the board configuration file and the scenario configuration file.
-
-The ``scenario`` attribute specifies the scenario name and must match the
-``scenario`` attribute in the scenario configuration file.
-
-The ``user_vm_launcher`` attribute specifies the number of post-launched User
-VMs in a scenario.

doc/tutorials/acrn_configurator_tool.rst

@@ -25,7 +25,6 @@ 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`

doc/tutorials/board_inspector_tool.rst

@@ -13,21 +13,28 @@ configuration file on the target system. The board configuration file stores
 hardware-specific information extracted from the target platform and is used to
 customize your :ref:`ACRN configuration <acrn_configuration_tool>`.
 
+Prerequisites
+*************
+
+This guide assumes you have set up your target system and successfully launched
+the Board Inspector. For steps, see the following Getting Started Guide
+sections:
+
+* :ref:`gsg-dev-computer`
+* :ref:`gsg-board-setup`
+
 Generate a Board Configuration File
 ***********************************
 
 .. important::
 
-   Whenever you change the configuration of the board, such as BIOS settings,
+   Whenever you change the configuration of the board, such as peripherals, BIOS
-   additional memory, or PCI devices, you must generate a new board
+   settings, additional memory, USB devices, or PCI devices, you must generate a
-   configuration file.
+   new board configuration file.
 
 The following steps describe all options in the Board Inspector for generating
 a board configuration file.
 
-#. Make sure the target system is set up and ready to run the Board Inspector,
-   according to :ref:`gsg-board-setup` in the Getting Started Guide.
-
 #. Run the Board Inspector tool (``board_inspector.py``) to generate the board
    configuration file. This example assumes the tool is in the
    ``~/acrn-work/`` directory and ``my_board`` is the desired file
@@ -35,14 +42,8 @@ a board configuration file.
 
    .. code-block:: bash
 
-      cd ~/acrn-work/board_inspector/
+      cd ~/acrn-work
-      sudo python3 board_inspector.py my_board
+      sudo board_inspector.py my_board
-
-   Upon success, the tool displays a message similar to this example:
-
-   .. code-block:: console
-
-      my_board.xml saved successfully!
 
 #. Confirm that the board configuration file ``my_board.xml`` was generated in
    the current directory.
@@ -58,7 +59,9 @@ Board Inspector with the ``-h`` option yields the following usage message:
 .. code-block::
 
    usage: board_inspector.py [-h] [--out OUT] [--basic] [--loglevel LOGLEVEL]
-                [--check-device-status] board_name
+                             [--check-device-status]
+                             [--add-llc-cat <capacity_mask_length:int>,<clos_number:int>,<has_CDP:bool>]
+                             board_name
 
    positional arguments:
      board_name            the name of the board that runs the ACRN hypervisor
@@ -66,11 +69,15 @@ Board Inspector with the ``-h`` option yields the following usage message:
    optional arguments:
      -h, --help            show this help message and exit
      --out OUT             the name of board info file
-     --basic               do not extract advanced information such as ACPI namespace
+     --basic               do not extract advanced information such as ACPI
-     --loglevel LOGLEVEL   choose log level, e.g. info, warning or error
+                           namespace
+     --loglevel LOGLEVEL   choose log level, e.g. debug, info, warning, error or
+                           critical
      --check-device-status
-
                            filter out devices whose _STA object evaluates to 0
+     --add-llc-cat <capacity_mask_length:int>,<clos_number:int>,<has_CDP:bool>
+                           manually set the Cache Allocation Technology
+                           capability of the last level cache
 
 Details about certain arguments:
 
@@ -98,8 +105,7 @@ Details about certain arguments:
        of board configuration files.
 
    * - ``--loglevel``
-     - Optional. Choose log level, e.g., info, warning or error.
+     - Optional. Choose the log level. (Default is warning.)
-       (Default is warning.)
 
    * - ``--check-device-status``
      - Optional. On some boards, the device status (reported by the _STA
@@ -107,3 +113,12 @@ Details about certain arguments:
        pass-through devices. By default, the Board Inspector includes the
        devices in the board configuration file. This option filters out the
        devices, so that they cannot be used.
+
+   * - ``--add-llc-cat``
+     - Optional. Add the Cache Allocation Technology (CAT) capabilities of the
+       last level cache (LLC) to the generated board configuration file even
+       when the hardware does not report them for any reason. For example,
+       ``--add-llc-cat=12,16,y``. CDP (Code and Data Prioritization) performance
+       feature enables separate control over code and data placement in the
+       processor's cache. Valid values for ``bool`` are
+       ``true|false|y|n|yes|no``.

doc/tutorials/upgrading_configuration.rst

@@ -3,7 +3,7 @@
 Upgrading ACRN Configurations to Recent Releases
 ################################################
 
-The configuration files, introduced in :ref:`acrn_config_data`, are refined
+The configuration files, introduced in :ref:`acrn_config_types`, are refined
 every release for richer features, clearer organization, and more user-friendly
 presentation. Due to the strict validation ACRN adopts, configuration files
 for a former release may not work for a latter if they are not upgraded. This