doc: update release_2.0 branch with doc changes

Update the working release_2.0 branch with doc updates made since the
code feature freeze two weeks ago.  (This is an update of all docs
changed in master since then, instead of doing cherry-picks of the
individual doc PRs/commits).

Signed-off-by: David B. Kinder <[email protected]>

doc/404.rst

@@ -5,7 +5,7 @@
 Page Not Found
 ##############
 
-.. rst-class:: rst-columns
+.. rst-class:: rst-columns2
 
    .. image:: images/ACRN-fall-from-tree-small.png
       :align: left

doc/api/GVT-g_api.rst

@@ -83,8 +83,8 @@ responses to user space modules, notified by vIRQ injections.
 
 .. _MPT_interface:
 
-AcrnGT mediated pass-through (MPT) interface
-**************************************************
+AcrnGT mediated passthrough (MPT) interface
+*******************************************
 
 AcrnGT receives request from GVT module through MPT interface. Refer to the
 :ref:`Graphic_mediation` page.

doc/conf.py

@@ -240,6 +240,10 @@ def setup(app):
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+html_search_scorer = 'scorer.js'
+
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.

doc/develop.rst

@@ -15,6 +15,7 @@ Configuration and Tools
 
    tutorials/acrn_configuration_tool
    reference/kconfig/index
+   user-guides/hv-parameters
    user-guides/kernel-parameters
    user-guides/acrn-shell
    user-guides/acrn-dm-parameters
@@ -76,6 +77,7 @@ Enable ACRN Features
    tutorials/rtvm_workload_design_guideline
    tutorials/setup_openstack_libvirt
    tutorials/acrn_on_qemu
+   tutorials/using_grub
 
 Debug
 *****

doc/developer-guides/hld/hld-APL_GVT-g.rst

@@ -17,7 +17,7 @@ SoCs.
 This document describes:
 
 -  The different GPU virtualization techniques
--  GVT-g mediated pass-through
+-  GVT-g mediated passthrough
 -  High level design
 -  Key components
 -  GVT-g new architecture differentiation
@@ -47,7 +47,7 @@ Background
 
 Intel GVT-g is an enabling technology in emerging graphics
 virtualization scenarios. It adopts a full GPU virtualization approach
-based on mediated pass-through technology, to achieve good performance,
+based on mediated passthrough technology, to achieve good performance,
 scalability and secure isolation among Virtual Machines (VMs). A virtual
 GPU (vGPU), with full GPU features, is presented to each VM so that a
 native graphics driver can run directly inside a VM.
@@ -161,10 +161,10 @@ also suffers from the following intrinsic limitations:
    exhibit quite different performance, which gives rise to a need for a
    fine-grained graphics tuning effort.
 
-Direct Pass-Through
+Direct Passthrough
 -------------------
 
-"Direct pass-through" dedicates the GPU to a single VM, providing full
+"Direct passthrough" dedicates the GPU to a single VM, providing full
 features and good performance, but at the cost of device sharing
 capability among VMs. Only one VM at a time can use the hardware
 acceleration capability of the GPU, which is a major limitation of this
@@ -177,7 +177,7 @@ solution. Intel GVT-d uses this mechanism.
    :align: center
    :name: gvt-pass-through
 
-   Pass-Through
+   Passthrough
 
 SR-IOV
 ------
@@ -188,16 +188,16 @@ with each VF directly assignable to a VM.
 
 .. _Graphic_mediation:
 
-Mediated Pass-Through
+Mediated Passthrough
 *********************
 
 Intel GVT-g achieves full GPU virtualization using a "mediated
-pass-through" technique.
+passthrough" technique.
 
 Concept
 =======
 
-Mediated pass-through allows a VM to access performance-critical I/O
+Mediated passthrough allows a VM to access performance-critical I/O
 resources (usually partitioned) directly, without intervention from the
 hypervisor in most cases. Privileged operations from this VM are
 trapped-and-emulated to provide secure isolation among VMs.
@@ -207,7 +207,7 @@ trapped-and-emulated to provide secure isolation among VMs.
    :align: center
    :name: mediated-pass-through
 
-   Mediated Pass-Through
+   Mediated Passthrough
 
 The Hypervisor must ensure that no vulnerability is exposed when
 assigning performance-critical resource to each VM. When a
@@ -229,7 +229,7 @@ Examples of performance-critical I/O resources include the following:
    Performance-Critical I/O Resources
 
 
-The key to implementing mediated pass-through for a specific device is
+The key to implementing mediated passthrough for a specific device is
 to define the right policy for various I/O resources.
 
 Virtualization Policies for GPU Resources
@@ -317,7 +317,7 @@ High Level Architecture
 :numref:`gvt-arch` shows the overall architecture of GVT-g, based on the
 ACRN hypervisor, with Service VM as the privileged VM, and multiple user
 guests. A GVT-g device model working with the ACRN hypervisor,
-implements the policies of trap and pass-through. Each guest runs the
+implements the policies of trap and passthrough. Each guest runs the
 native graphics driver and can directly access performance-critical
 resources: the Frame Buffer and Command Buffer, with resource
 partitioning (as presented later). To protect privileged resources, that
@@ -331,14 +331,14 @@ concurrently with the CPU scheduler in ACRN to share the physical GPU
 timeslot among the VMs. GVT-g uses the physical GPU to directly execute
 all the commands submitted from a VM, so it avoids the complexity of
 emulating the Render Engine, which is the most complex part of the GPU.
-In the meantime, the resource pass-through of both the Frame Buffer and
+In the meantime, the resource passthrough of both the Frame Buffer and
 Command Buffer minimizes the hypervisor's intervention of CPU accesses,
 while the GPU scheduler guarantees every VM a quantum time-slice for
 direct GPU execution. With that, GVT-g can achieve near-native
 performance for a VM workload.
 
 In :numref:`gvt-arch`, the yellow GVT device model works as a client on
-top of an i915 driver in the Service VM. It has a generic Mediated Pass-Through
+top of an i915 driver in the Service VM. It has a generic Mediated Passthrough
 (MPT) interface, compatible with all types of hypervisors. For ACRN,
 some extra development work is needed for such MPT interfaces. For
 example, we need some changes in ACRN-DM to make ACRN compatible with
@@ -795,7 +795,7 @@ the shadow PTE entries.
 Per-VM Shadow PPGTT
 -------------------
 
-To support local graphics memory access pass-through, GVT-g implements
+To support local graphics memory access passthrough, GVT-g implements
 per-VM shadow local page tables. The local graphics memory is only
 accessible from the Render Engine. The local page tables have two-level
 paging structures, as shown in :numref:`per-vm-shadow`.

doc/developer-guides/hld/hld-devicemodel.rst

@@ -1189,8 +1189,8 @@ and waits for a resume signal. When the User VM should exit from S3, DM will
 get a wakeup signal and reset the User VM to emulate the User VM exit from
 S3.
 
-Pass-through in Device Model
+Passthrough in Device Model
 ****************************
 
-You may refer to :ref:`hv-device-passthrough` for pass-through realization
+You may refer to :ref:`hv-device-passthrough` for passthrough realization
 in device model.

doc/developer-guides/hld/hld-emulated-devices.rst

@@ -22,3 +22,4 @@ documented in this section.
    Hostbridge emulation <hostbridge-virt-hld>
    AT keyboard controller emulation <atkbdc-virt-hld>
    Split Device Model <split-dm>
+   Shared memory based inter-vm communication <ivshmem-hld>

doc/developer-guides/hld/hld-overview.rst

@@ -61,7 +61,7 @@ for its RT VM:
 
 - CAT (Cache Allocation Technology)
 - MBA (Memory Bandwidth Allocation)
-- LAPIC pass-thru
+- LAPIC passthrough
 - Polling mode driver
 - ART (always running timer)
 - other TCC features like split lock detection, Pseudo locking for cache
@@ -109,7 +109,7 @@ separate instrument cluster VM is started after the User VM is booted.
 :numref:`overview-arch1.0` shows the architecture of ACRN 1.0 together with
 the IC VM and Service VM. As shown, the Service VM owns most of platform devices and
 provides I/O mediation to VMs. Some of the PCIe devices function as a
-pass-through mode to User VMs according to VM configuration. In addition,
+passthrough mode to User VMs according to VM configuration. In addition,
 the Service VM could run the IC applications and HV helper applications such
 as the Device Model, VM manager, etc. where the VM manager is responsible
 for VM start/stop/pause, virtual CPU pause/resume, etc.
@@ -136,7 +136,7 @@ compared to ACRN 1.0 is that:
    interference between different VMs
 
 -  ACRN 2.0 supports RT VM for a post-launched User VM, with assistant features like LAPIC
-   pass-thru and PMD virtio driver
+   passthrough and PMD virtio driver
 
 ACRN 2.0 is still WIP, and some of its features are already merged in the master.
 
@@ -162,12 +162,12 @@ ACRN adopts various approaches for emulating devices for the User VM:
    -  para-virtualized, requiring front-end drivers in
       the User VM to function.
 
--  **Pass-through device**: A device passed through to the User VM is fully
+-  **Passthrough device**: A device passed through to the User VM is fully
    accessible to the User VM without interception. However, interrupts
    are first handled by the hypervisor before
    being injected to the User VM.
 
--  **Mediated pass-through device**: A mediated pass-through device is a
+-  **Mediated passthrough device**: A mediated passthrough device is a
    hybrid of the previous two approaches. Performance-critical
    resources (mostly data-plane related) are passed-through to the User VMs and
    others (mostly control-plane related) are emulated.
@@ -275,7 +275,7 @@ used by commercial OS).
 
 -  On top of vCPUs are three components for device emulation: one for
    emulation inside the hypervisor, another for communicating with
-   the Service VM for mediation, and the third for managing pass-through
+   the Service VM for mediation, and the third for managing passthrough
    devices.
 
 -  The highest layer is a VM management module providing
@@ -311,7 +311,7 @@ based on command line configurations.
 Based on a VHM kernel module, DM interacts with VM manager to create the User
 VM. It then emulates devices through full virtualization on the DM user
 level, or para-virtualized based on kernel mediator (such as virtio,
-GVT), or pass-through based on kernel VHM APIs.
+GVT), or passthrough based on kernel VHM APIs.
 
 Refer to :ref:`hld-devicemodel` for more details.
 
@@ -592,6 +592,6 @@ Some details about the ACPI table for the User and Service VMs:
    knows which register the User VM writes to trigger power state
    transitions. Device Model must register an I/O handler for it.
 
--  The ACPI table in the Service VM is passthru. There is no ACPI parser
+-  The ACPI table in the Service VM is passthrough. There is no ACPI parser
    in ACRN HV. The power management related ACPI table is
    generated offline and hardcoded in ACRN HV.

doc/developer-guides/hld/hld-power-management.rst

@@ -19,7 +19,7 @@ for the Device Model to build a virtual ACPI table.
 The Px/Cx data includes four
 ACPI objects: _PCT, _PPC, and _PSS for P-state management, and _CST for
 C-state management. All these ACPI data must be consistent with the
-native data because the control method is a kind of pass through.
+native data because the control method is a kind of passthrough.
 
 These ACPI objects data are parsed by an offline tool and hard-coded in a
 Hypervisor module named CPU state table:

doc/developer-guides/hld/hv-dev-passthrough.rst

@@ -126,6 +126,9 @@ a passthrough device to/from a post-launched VM is shown in the following figure
 
    ptdev de-assignment control flow
 
+.. _vtd-posted-interrupt:
+
+
 VT-d Interrupt-remapping
 ************************
 

doc/developer-guides/hld/hv-interrupt.rst

@@ -11,10 +11,10 @@ to manage interrupts and exceptions, as shown in
 :numref:`interrupt-modules-overview`. In its native layer, it configures
 the physical PIC, IOAPIC, and LAPIC to support different interrupt
 sources from the local timer/IPI to the external INTx/MSI. In its virtual guest
-layer, it emulates virtual PIC, virtual IOAPIC, and virtual LAPIC/pass-thru
+layer, it emulates virtual PIC, virtual IOAPIC, and virtual LAPIC/passthrough
 LAPIC. It provides full APIs, allowing virtual interrupt injection from
-emulated or pass-thru devices. The contents in this section do not include
-the pass-thru LAPIC case. For the pass-thru LAPIC, refer to
+emulated or passthrough devices. The contents in this section do not include
+the passthrough LAPIC case. For the passthrough LAPIC, refer to
 :ref:`lapic_passthru`
 
 .. figure:: images/interrupt-image3.png
@@ -29,10 +29,10 @@ the ACRN hypervisor sets up the physical interrupt in its basic
 interrupt modules (e.g., IOAPIC/LAPIC/IDT). It dispatches the interrupt
 in the hypervisor interrupt flow control layer to the corresponding
 handlers; this could be pre-defined IPI notification, timer, or runtime
-registered pass-thru devices. The ACRN hypervisor then uses its VM
+registered passthrough devices. The ACRN hypervisor then uses its VM
 interfaces based on vPIC, vIOAPIC, and vMSI modules, to inject the
 necessary virtual interrupt into the specific VM, or directly deliver
-interrupt to the specific RT VM with pass-thru LAPIC.
+interrupt to the specific RT VM with passthrough LAPIC.
 
 .. figure:: images/interrupt-image2.png
    :align: center
@@ -100,7 +100,7 @@ Physical Interrupt Initialization
 After ACRN hypervisor gets control from the bootloader, it
 initializes all physical interrupt-related modules for all the CPUs. ACRN
 hypervisor creates a framework to manage the physical interrupt for
-hypervisor local devices, pass-thru devices, and IPI between CPUs, as
+hypervisor local devices, passthrough devices, and IPI between CPUs, as
 shown in :numref:`hv-interrupt-init`:
 
 .. figure:: images/interrupt-image66.png
@@ -323,7 +323,7 @@ there are three different handling flows according to flags:
 
 -  ``IRQF_LEVEL && IRQF_PT``
 
-   For pass-thru devices, to avoid continuous interrupt triggers, it masks
+   For passthrough devices, to avoid continuous interrupt triggers, it masks
    the IOAPIC pin and leaves it unmasked until corresponding vIOAPIC
    pin gets an explicit EOI ACK from guest.