doc: update release_3.0 with changes on master

For the 3.0.1 hot-fix release, update release_3.0 branch with doc
changes relevent updates since v3.0 tag.  This is primarily for the
doc/asa.rst and doc/release_notes/release_notes_3.0.1.rst files, but
there was also a cleanup of deleted image files, and some changes made
for copyright years.

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

doc/asa.rst

@@ -3,9 +3,24 @@
 Security Advisory
 #################
 
+Addressed in ACRN v3.0.1
+************************
+We recommend that all developers upgrade to this v3.0.1 release (or later), which
+addresses the following security issue discovered in previous releases:
+
+-----
+
+-  Disable RRSBA on platforms using retpoline
+    For platforms that supports RRSBA (Restricted Return Stack Buffer
+    Alternate), using retpoline may not be sufficient to guard against branch
+    history injection or intra-mode branch target injection. RRSBA must
+    be disabled to prevent CPUs from using alternate predictors for RETs.
+    (Addresses security issue tracked by CVE-2022-29901 and CVE-2022-28693.)
+
+    **Affected Release:** v3.0 and earlier
+
 Addressed in ACRN v2.7
 ************************
-
 We recommend that all developers upgrade to this v2.7 release (or later), which
 addresses the following security issue discovered in previous releases:
 

doc/developer-guides/asm_coding_guidelines.rst

@@ -720,7 +720,7 @@ Compliant example::
     -------------File Contents Start After This Line------------
 
     /*
-     * Copyright (C) 2019 Intel Corporation.
+     * Copyright (C) 2019-2022 Intel Corporation.
      *
      * SPDX-License-Identifier: BSD-3-Clause
      */

doc/developer-guides/c_coding_guidelines.rst

@@ -3386,7 +3386,7 @@ Compliant example::
     -------------File Contents Start After This Line------------
 
     /*
-     * Copyright (C) 2019 Intel Corporation.
+     * Copyright (C) 2019-2022 Intel Corporation.
      *
      * SPDX-License-Identifier: BSD-3-Clause
      */

doc/extensions/kerneldoc.py

@@ -1,6 +1,6 @@
 # coding=utf-8
 #
-# Copyright © 2016 Intel Corporation
+# Copyright © 2016-2022 Intel Corporation.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the "Software"),

doc/extensions/link_roles.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2019 Intel Corporation
+# Copyright (c) 2019-2022 Intel Corporation.
 #
 # SPDX-License-Identifier: Apache-2.0
 

doc/getting-started/getting-started.rst

@@ -471,11 +471,26 @@ post-launched User VM. Each User VM has its own launch script.
    settings to meet your application's particular needs. But for now, you
    will update only a few settings for functional and educational purposes.
 
+   You may see some error messages from the configurator, such as shown here:
+
+   .. image:: images/gsg-config-errors.png
+      :align: center
+      :class: drop-shadow
+
+   The configurator does consistency and validation checks when you load or save
+   a scenario.  Notice the Hypervisor and VM1 tabs both have an error icon,
+   meaning there are issues with configuration options in two areas.  Since the
+   Hypervisor tab is currently highlighted, we're seeing an issue we can resolve
+   on the Hypervisor settings.  Once we resolve all the errors and save the
+   scenario (forcing a full validation of the schema again), these error
+   indicators and messages will go away.
+
 #. Click the **Hypervisor Global Settings > Basic Parameters** tab, select the
    ``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.
+   requires a serial console port (and is reporting an error because a serial
+   console port hasn't been configured yet).
 
    .. image:: images/configurator-buildtype.png
       :align: center
@@ -501,7 +516,8 @@ post-launched User VM. Each User VM has its own launch script.
       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.
+      select pCPU ID ``1`` to affine (or pin) the VM to CPU cores 0 and 1. (That will
+      resolve the initial physical CPU affinity assignment error.)
 
    #. For **Virtio console device**, click **+** to add a device and keep the
       default options. This parameter specifies the console that you will use to

doc/reference/images/Advanced.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="125" height="20" role="img" aria-label="Advanced Parameter"><title>Advanced Parameter</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="125" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#e05d44"/><rect x="0" width="125" height="20" fill="#e05d44"/><rect width="125" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="625" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="1150">Advanced Parameter</text><text x="625" y="140" transform="scale(.1)" fill="#fff" textLength="1150">Advanced Parameter</text></g></svg>

doc/reference/images/Basic.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="99" height="20" role="img" aria-label="Basic Parameter"><title>Basic Parameter</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="99" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#007ec6"/><rect x="0" width="99" height="20" fill="#007ec6"/><rect width="99" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="495" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="890">Basic Parameter</text><text x="495" y="140" transform="scale(.1)" fill="#fff" textLength="890">Basic Parameter</text></g></svg>

doc/reference/images/Hypervisor.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="69" height="20" role="img" aria-label="Hypervisor"><title>Hypervisor</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="69" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#2b978f"/><rect x="0" width="69" height="20" fill="#2b978f"/><rect width="69" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="345" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="590">Hypervisor</text><text x="345" y="140" transform="scale(.1)" fill="#fff" textLength="590">Hypervisor</text></g></svg>

doc/reference/images/Not-available.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="185" height="20" role="img" aria-label="Not available in Configurator UI"><title>Not available in Configurator UI</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="185" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#9f9f9f"/><rect x="0" width="185" height="20" fill="#9f9f9f"/><rect width="185" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="925" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="1750">Not available in Configurator UI</text><text x="925" y="140" transform="scale(.1)" fill="#fff" textLength="1750">Not available in Configurator UI</text></g></svg>

doc/reference/images/Post-launched-VM.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="109" height="20" role="img" aria-label="Post-launched VM"><title>Post-launched VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="109" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#998265"/><rect x="0" width="109" height="20" fill="#998265"/><rect width="109" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="545" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="990">Post-launched VM</text><text x="545" y="140" transform="scale(.1)" fill="#fff" textLength="990">Post-launched VM</text></g></svg>

doc/reference/images/Pre-launched-VM.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="103" height="20" role="img" aria-label="Pre-launched VM"><title>Pre-launched VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="103" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#4c1"/><rect x="0" width="103" height="20" fill="#4c1"/><rect width="103" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="515" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="930">Pre-launched VM</text><text x="515" y="140" transform="scale(.1)" fill="#fff" textLength="930">Pre-launched VM</text></g></svg>

doc/reference/images/Service-VM.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="71" height="20" role="img" aria-label="Service VM"><title>Service VM</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="71" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="0" height="20" fill="#dfb317"/><rect x="0" width="71" height="20" fill="#dfb317"/><rect width="71" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="355" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="610">Service VM</text><text x="355" y="140" transform="scale(.1)" fill="#fff" textLength="610">Service VM</text></g></svg>

doc/release_notes/release_notes_3.0.1.rst

@@ -0,0 +1,54 @@
+.. _release_notes_3.0.1:
+
+ACRN v3.0.1 (Jul 2022)
+######################
+
+We are pleased to announce the release of the Project ACRN hypervisor
+version 3.0.1 with hot fixes to the v3.0 release.
+
+ACRN is a flexible, lightweight reference hypervisor that is built with
+real-time and safety-criticality in mind. It is optimized to streamline
+embedded development through an open-source platform. See the
+:ref:`introduction` introduction for more information.
+
+All project ACRN source code is maintained in the
+https://github.com/projectacrn/acrn-hypervisor repository and includes
+folders for the ACRN hypervisor, the ACRN device model, tools, and
+documentation. You can download this source code either as a zip or
+tar.gz file (see the `ACRN v3.0.1 GitHub release page
+<https://github.com/projectacrn/acrn-hypervisor/releases/tag/v3.0.1>`_) or
+use Git ``clone`` and ``checkout`` commands::
+
+   git clone https://github.com/projectacrn/acrn-hypervisor
+   cd acrn-hypervisor
+   git checkout v3.0.1
+
+The project's online technical documentation is also tagged to
+correspond with a specific release: generated v3.0 documents can be
+found at https://projectacrn.github.io/3.0/.  Documentation for the
+latest development branch is found at https://projectacrn.github.io/latest/.
+
+ACRN v3.0.1 requires Ubuntu 20.04 (as does v3.0).  Follow the instructions in the
+:ref:`gsg` to get started with ACRN.
+
+
+What's New in v3.0.1
+********************
+
+Mitigation for Return Stack Buffer Underflow security vulnerability
+  For platforms that supports RRSBA (Restricted Return Stack Buffer
+  Alternate), using retpoline may not be sufficient to guard against branch
+  history injection or intra-mode branch target injection. RRSBA must
+  be disabled to prevent CPUs from using alternate predictors for RETs.
+  (Addresses security issue tracked by CVE-2022-29901 and CVE-2022-28693.)
+
+ACRN shell commands added for real-time performance profiling
+  ACRN shell commands were added to sample vmexit data per virtual CPU to
+  facilitate real-time performance profiling:
+
+  * ``vmexit clear``: clears current vmexit buffer
+  * ``vmexit [vm_id]``: outputs vmexit info per vCPU
+  * ``vmexit enable | disable``: enabled by default
+
+
+See :ref:`release_notes_3.0` for additional release information.

doc/scorer.js

@@ -2,7 +2,7 @@
  * Simple search result scoring code.
  *
  * Copyright 2007-2018 by the Sphinx team
- * Copyright (c) 2019, Intel
+ * Copyright (c) 2019-2022, Intel Corporation.
  * SPDX-License-Identifier: Apache-2.0
  */
 

doc/scripts/extract_content.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 #
 # Copyright (c) 2018, Nordic Semiconductor ASA
-# Copyright (c) 2017, Intel Corporation
+# Copyright (c) 2017-2022, Intel Corporation
 #
 # SPDX-License-Identifier: Apache-2.0
 

doc/scripts/filter-doc-log.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# Copyright (C) 2019 Intel Corporation.
+# Copyright (C) 2019-2022 Intel Corporation.
 # SPDX-License-Identifier: BSD-3-Clause
 
 # run the filter-known-issues.py script to remove "expected" warning

doc/scripts/filter-known-issues.py

@@ -1,5 +1,5 @@
 #! /usr/bin/env python3
-# Copyright (c) 2017, Intel Corporation
+# Copyright (c) 2017-2022, Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 """
 Filters a file, classifying output in errors, warnings and discarding

doc/scripts/show-versions.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (c) 2018, Intel Corporation
+# Copyright (c) 2018-2022, Intel Corporation
 #
 # SPDX-License-Identifier: BSD-3-Clause
 #

doc/tutorials/acrn_configurator_tool.rst

@@ -36,6 +36,54 @@ The above Getting Started Guide steps use a prebuilt Debian package to install
 the ACRN Configurator. :ref:`acrn_configurator_tool_source` describes how to
 build the Debian package.
 
+Scenario Error Checking
+***********************
+
+The configurator includes many validation checks that verify input values, ensure the consistency of
+configuration options, and interactions between options.
+
+Simple data validation checks on values are detected immediately with red
+text indicating the problem, or with an indicator within a data entry field. For
+example, if you type in a value that is out of range, you'll see your value
+crossed out:
+
+.. image:: images/config-out-of-range-error.png
+   :align: center
+   :class: drop-shadow
+
+If you delete a required value, you'll see an error message in red text:
+
+.. image:: images/config-required-value-error.png
+   :align: center
+   :class: drop-shadow
+
+More complex checks, including those that look for conflicting settings, are
+done when you initially open a saved (or newly created) scenario, or when you
+use the "Save Scenario" button. If problems are detected, the response window
+from the save action will indicate that problems were found.  The Hypervisor or
+VM tabs will then display an error icon leading you to the configuration option
+panels where you can resolve the errors. For example, both the Hypervisor and
+VM1 tabs indicate an option setting problem:
+
+.. image:: images/config-tab-errors.png
+   :align: center
+   :class: drop-shadow
+
+Since we're on the Hypervisor (Basic Parameters) options, we see the Hypervisor
+configuration error message.  If we click on the VM1 tab, we'll see what the
+issues are with that VM's configuration options:
+
+.. image:: images/config-tab-errors2.png
+   :align: center
+   :class: drop-shadow
+
+In both cases, you can scroll down to see the specific problem (on either the
+basic or advanced parameters tab), fix the issues,
+and then when all issues are resolved, click on the "Save Scenario" button to
+validate the changes and save the settings.  If all issues were resolved, the
+save scenario response window will indicate no issues were found and all the
+error indicators will be cleared.
+
 Start with a New or Existing Configuration
 ******************************************
 

doc/tutorials/acrn_on_qemu.rst

@@ -267,7 +267,7 @@ Bring Up User VM (L2 Guest)
    .. code-block:: none
 
       #!/bin/bash
-      # Copyright (C) 2020 Intel Corporation.
+      # Copyright (C) 2020-2022 Intel Corporation.
       # SPDX-License-Identifier: BSD-3-Clause
       function launch_ubuntu()
       {

doc/tutorials/create-up2-images.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Copyright (C) 2018 Intel Corporation.
+# Copyright (C) 2018-2022 Intel Corporation.
 # SPDX-License-Identifier: BSD-3-Clause
 
 

doc/tutorials/gpt_ini2bin.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-# Copyright (C) 2018 Intel Corporation.
+# Copyright (C) 2018-2022 Intel Corporation.
 # SPDX-License-Identifier: BSD-3-Clause
 
 import ConfigParser

doc/tutorials/gpu-passthru.rst

@@ -61,6 +61,16 @@ The example extends the information provided in the :ref:`gsg`.
 #. In the ACRN Configurator, create a shared scenario with a Service VM and one
    post-launched User VM.
 
+#. Select the Service VM and go to **Basic Parameters > Kernel
+   command-line parameters**.
+
+#. Append ``i915.modeset=0`` in **Kernel command-line parameters** to disable the
+   GPU driver loading for Intel GPU device.
+
+   .. image:: images/kernel_cmd_line.png
+      :align: center
+      :class: drop-shadow
+
 #. Select the post-launched User VM and go to **Basic Parameters > PCI
    devices**.
 

doc/tutorials/launch_uos.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 
-# Copyright (C) 2018 Intel Corporation.
+# Copyright (C) 2018-2022 Intel Corporation.
 # SPDX-License-Identifier: BSD-3-Clause
 
 

doc/tutorials/upgrading_configuration.rst

@@ -68,7 +68,7 @@ XML files into the merged format:
 
 .. code-block:: bash
 
-   misc/config_tools/scenario_config/upgrader.py <your scenario XML> --launch <your launch XML> <out file>
+   misc/config_tools/scenario_config/upgrader.py --launch <your launch XML> <your scenario XML> <out file>
 
 The upgrader migrates all data in both XMLs into the ``<out file>`` and shows
 messages about discarded data in the same way as upgrading a scenario XML alone.

doc/tutorials/vuart_configuration.rst

@@ -84,10 +84,17 @@ For the connection:
 To add another connection, click **+** on the right side of an existing
 connection. Or click **-** to delete a connection.
 
+   .. note::
+
+      The release v3.0 ACRN Configurator assigns COM2 (I/O address ``0x2F8``) to
+      the S5 feature. A conflict will occur if you assign ``0x2F8`` to another
+      connection. In our example, we'll use COM3 (I/O address ``0x3F8``).
+
 .. image:: images/configurator-vuartconn01.png
    :align: center
    :class: drop-shadow
 
+
 Example Configuration
 =====================
 
@@ -108,7 +115,7 @@ connection between two VMs. The example extends the information provided in the
 
    #. For the vUART type, this example uses ``Legacy``.
 
-   #. For the virtual I/O address, this example uses ``0x2f8``.
+   #. For the virtual I/O address, this example uses ``0x3E8``.
 
    .. image:: images/configurator-vuartconn01.png
       :align: center
@@ -134,7 +141,7 @@ connection between two VMs. The example extends the information provided in the
          [    0.105303] printk: console [tty0] enabled
          [    0.105319] printk: console [ttyS0] enabled
          [    1.391979] 00:03: ttyS0 at I/O 0x3f8 (irq = 4, base_baud = 115200) is a 16550A
-         [    1.649819] serial8250: ttyS1 at I/O 0x2f8 (irq = 3, base_baud = 115200) is a 16550A
+         [    1.649819] serial8250: ttyS1 at I/O 0x3e8 (irq = 5, base_baud = 115200) is a 16550A
          [    3.394543] systemd[1]: Created slice system-serial\x2dgetty.slice.
 
    #. Test vUART communication:

doc/user-guides/kernel-parameters.rst

@@ -336,6 +336,19 @@ relevant for configuring or debugging ACRN-based systems.
          hugepages=10
          hugepagesz=1G
 
+   * - ``i915.modeset``
+     - Service VM
+     - GPU driver loading option.
+
+       ``0``:
+         Disable the GPU driver loading for Intel GPU device.
+
+       ``1``:
+         Enable the GPU driver loading for Intel GPU device.
+     - ::
+
+          i915.modeset=0
+
 .. note:: The ``hugepages`` and ``hugepagesz`` parameters are automatically
    taken care of by the ACRN Configurator tool. If users have customized
    hugepage settings to satisfy their particular workloads in the Service VM,

misc/hv_prebuild/README.rst

@@ -0,0 +1,14 @@
+:orphan:
+
+Hypervisor Pre-Build Check Tool
+###############################
+
+There are a number of configuration elements for the ACRN hypervisor that must
+defined before building the binaries. Those configuration elements are set
+by the user using the :ref:`ACRN Configurator tool <acrn_configuration_tool>`.
+
+
+This folder holds the source to a tool that is used to ensure that the
+configuration is coherent and valid. It is a tool used in the background by
+the build system before compiling the hypervisor and other components. It is
+not meant to be used as a stand-alone too.