doc: update rest of hypervisor HLD sections

Transcode, edit, and upload HLD 0.7 section 3.10 (PM in hypervisor),
3.11 (Console, shell, vUART), 3.12 (Hypercall/VHM upcall), and
3.13 (Compile-time config)

Also scan/replace UTF-8 punctuation missed in previous PRs.

Add anchor targets in referenced docs.

Tracked-on: #1648

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

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

@@ -16,3 +16,7 @@ Hypervisor high-level design
    Virtual Interrupt <hv-virt-interrupt>
    VT-d <hv-vt-d>
    Device Passthrough <hv-dev-passthrough>
+   Power Management <hv-pm>
+   Console, Shell, and vUART <hv-console>
+   Hypercall / VHM upcall <hv-hypercall>
+   Compile-time configuration <hv-config>

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

@@ -0,0 +1,51 @@
+.. _hv-config:
+
+Compile-time Configuration
+##########################
+
+The hypervisor provides a kconfig-like way for manipulating compile-time
+configurations. Basically the hypervisor defines a set of configuration
+symbols and declare their default value. A configuration file is
+created, containing the values of each symbol, before building the
+sources.
+
+Similar to Linux kconfig, there are three files involved:
+
+-  **.config** This files stores the values of all configuration
+   symbols.
+
+-  **config.mk** This file is a conversion of .config in Makefile
+   syntax, and can be included in makefiles so that the build
+   process can rely on the configurations.
+
+-  **config.h** This file is a conversion of .config in C syntax, and is
+   automatically included in every source file so that the values of
+   the configuration symbols are available in the sources.
+
+.. figure:: images/config-image103.png
+   :align: center
+   :name: config-build-workflow
+
+   Hypervisor configuration and build workflow
+
+:numref:`config-build-workflow` shows the workflow of building the
+hypervisor:
+
+1. Three targets are introduced for manipulating the configurations.
+
+   a. **defconfig** creates a .config based on a predefined
+      configuration file.
+
+   b. **oldconfig** updates an existing .config after creating one if it
+      does not exist.
+
+   c. **menuconfig** presents a terminal UI to navigate and modify the
+      configurations in an interactive manner.
+
+2. The target oldconfig is also used to create a .config if a .config
+   file does not exist when building the source directly.
+
+3. The other two files for makefiles and C sources are regenerated after
+   .config changes.
+
+Refer to :ref:`configuration` for a complete list of configuration symbols.

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

@@ -0,0 +1,99 @@
+.. _hv-console:
+
+Hypervisor console, hypervisor shell, and virtual UART
+######################################################
+
+Hypervisor console
+******************
+
+The hypervisor console is a text-based terminal accessible from UART.
+:numref:`console-processing` shows the workflow of the console:
+
+.. figure:: images/console-image93.png
+   :align: center
+   :name: console-processing
+
+   Periodic console processing
+
+A periodic timer is set on initialization to trigger console processing every 40ms.
+Processing behavior depends on whether the vUART
+is active:
+
+- If it is not active, the hypervisor shell is kicked to handle
+  inputs from the physical UART, if there are any.
+
+- If the vUART is active, the bytes from
+  the physical UART are redirected to the RX fifo of the vUART, and those
+  in the vUART TX fifo to the physical UART.
+
+.. note:: The console is only available in the debug version of the hypervisor,
+   configured at compile time. In the release version, the console is
+   disabled and the physical UART is not used by the hypervisor or SOS.
+
+Hypervisor shell
+****************
+
+For debugging, the hypervisor shell provides commands to list some
+internal states and statistics of the hypervisor. It is accessible on
+the physical UART only when the vUART is deactivated. See
+:ref:`acrnshell` for the list of available hypervisor shell commands.
+
+Virtual UART
+************
+
+Currently UART 16550 is owned by the hypervisor itself and used for
+debugging purposes. Properties are configured by hypervisor command
+line. Hypervisor emulates a UART device with 0x3F8 address to SOS that
+acts as the console of SOS with these features:
+
+-  The vUART is exposed via I/O port 0x3f8.
+-  Incorporate a 256-byte RX buffer and 65536 TX buffer.
+-  Full emulation of input/output bytes and related interrupts.
+-  For other read-write registers the value is stored without effects
+   and reads get the latest stored value. For read-only registers
+   writes are ignored.
+-  vUART activation via shell command and deactivate via hotkey.
+
+The following diagram shows the activation state transition of vUART.
+
+.. figure:: images/console-image41.png
+   :align: center
+
+   Periodic console processing
+
+Specifically:
+
+-  After initialization vUART is disabled.
+-  The vUART is activated after the command "vm_console" is executed on
+   the hypervisor shell. Inputs to the physical UART will be
+   redirected to the vUART starting from the next timer event.
+
+-  The vUART is deactivated after a :kbd:`Ctrl + Space` hotkey is received
+   from the physical UART. Inputs to the physical UART will be
+   handled by the hypervisor shell starting from the next timer
+   event.
+
+The workflows are described as follows:
+
+-  RX flow:
+
+   -  Characters are read from UART HW into a sbuf whose size is 2048
+      bytes, triggered by console_read
+
+   -  Characters are read from this sbuf and put to rxFIFO,
+      triggered by vuart_console_rx_chars
+
+   -  A virtual interrupt is sent to SOS, triggered by a read from
+      SOS. Characters in rxFIFO are sent to SOS by emulation of
+      read of register UART16550_RBR
+
+-  TX flow:
+
+   -  Characters are put to txFIFO by emulation of write of register
+      UART16550_THR
+
+   -  Characters in txFIFO are read out one by one and sent to console
+      by printf,  triggered by vuart_console_tx_chars
+
+   -  Implementation of printf is based on console, which finally sends
+      characters to UART HW by writing to register UART16550_RBR

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

@@ -23,7 +23,7 @@ The difference between device emulation and passthrough is shown in
 :numref:`emu-passthru-diff`. You can notice device emulation has
 a longer access path which causes worse performance compared with
 passthrough. Passthrough can deliver near-native performance, but
-can’t support device sharing.
+can't support device sharing.
 
 .. figure:: images/passthru-image30.png
    :align: center
@@ -66,7 +66,7 @@ DMA Remapping
 To enable passthrough, for VM DMA access the VM can only
 support GPA, while physical DMA requires HPA. One work-around
 is building identity mapping so that GPA is equal to HPA, but this
-is not recommended as some VM don’t support relocation well. To
+is not recommended as some VM don't support relocation well. To
 address this issue, Intel introduces VT-d in chipset to add one
 remapping engine to translate GPA to HPA for DMA operations.
 

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

@@ -0,0 +1,21 @@
+.. _hv-hypercall:
+
+Hypercall / VHM upcall
+######################
+
+HV currently supports hypercall APIs for VM management, I/O request
+distribution, and guest memory mapping.
+
+HV and Service OS (SOS) also use vector 0xF7, reserved as x86 platform
+IPI vector for HV notification to SOS. This upcall is necessary whenever
+there is device emulation requirement to SOS. The upcall vector 0xF7 is
+injected to SOS vCPU0
+
+SOS will register the irq handler for 0xF7 and notify the I/O emulation
+module in SOS once the irq is triggered.
+
+
+.. note:: Add API doc references for General interface, VM management
+   interface, IRQ and Interrupts, Device Model IO request distribution,
+   Guest memory management, PCI assignment and IOMMU, Debug, Trusty, Power
+   management

doc/developer-guides/hld/hv-io-emulation.rst

@@ -37,7 +37,7 @@ inside the hypervisor:
 :option:`CONFIG_PARTITION_MODE` is the only configuration option that affects the
 functionality of I/O emulation. With :option:`CONFIG_PARTITION_MODE` enabled,
 the hypervisor never sends I/O request to any VM. Unhandled I/O reads
-get all 1’s and writes are silently dropped.
+get all 1's and writes are silently dropped.
 
 I/O emulation does not rely on any calibration data.
 
@@ -97,7 +97,7 @@ following cases exist:
    -  Otherwise it is implied that the access crosses the boundary of
       multiple devices which the hypervisor does not emulate. Thus
       no handler is called and no I/O request will be delivered to
-      SOS. I/O reads get all 1’s and I/O writes are dropped.
+      SOS. I/O reads get all 1's and I/O writes are dropped.
 
 -  If the range of the I/O access does not overlap with any range of the
    handlers, the I/O access is delivered to SOS as an I/O request
@@ -119,7 +119,7 @@ requests. The 4-KByte page consists of 16 256-Byte slots, indexed by
 vCPU ID. It is required for the DM to allocate and set up the request
 buffer on VM creation, otherwise I/O accesses from UOS cannot be
 emulated by SOS, and all I/O accesses not handled by the I/O handlers in
-the hypervisor will be dropped (reads get all 1’s).
+the hypervisor will be dropped (reads get all 1's).
 
 Refer to Section 4.4.1 for the details of I/O requests and the
 initialization of the I/O request buffer.
@@ -216,8 +216,8 @@ The states are transferred as follow:
 States are accessed using atomic operations to avoid getting unexpected
 states on one core when it is written on another.
 
-Note that there is no state to represent a ‘failed’ I/O request. SOS
+Note that there is no state to represent a 'failed' I/O request. SOS
-should return all 1’s for reads and ignore writes whenever it cannot
+should return all 1's for reads and ignore writes whenever it cannot
 handle the I/O request, and change the state of the request to COMPLETE.
 
 Post-work

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

@@ -0,0 +1,49 @@
+.. _pm_hld:
+
+Power Management
+################
+
+System PM module
+****************
+
+The PM module in the hypervisor does three things:
+
+-  When all UOSes enter low power state, VM management will notify the SOS
+   lifecycle service and trigger the SOS to enter a low-power state.
+   SOS follows its own standard low-power state entry process and
+   writes the ACPI control register to put SOS into low-power state.
+   Hypervisor traps the ACPI control register writing and
+   emulates SOS low-power state entry.
+
+-  Once SOS low-power emulation is done, Hypervisor handles its
+   own low-power state transition
+
+-  Once system resumes from low-power mode, the hypervisor handles its
+   own resume and emulates SOS resume too.
+
+It is assumed that SOS does not trigger any power state transition until
+the VM manager of ACRN notifies it that all UOSes are inactive and SOS
+offlines all its virtual APs.
+
+:numref:`pm-low-power-transition` shows the SOS/Hypervisor low-power
+state transition process.  SOS triggers power state transition by
+writing ACPI control register on its virtual BSP (which is pinned to the
+physical BSP). The hypervisor then does the following in sequence before
+it writes to the physical ACPI control register to trigger physical
+power state transition:
+
+-  Pauses SOS.
+-  Offlines all physical APs.
+-  Save the context of console, ioapic of SOS, I/O MMU, lapic of SOS,
+   virtual BSP.
+-  Save the context of physical BSP.
+
+When exiting from low-power mode, the hypervisor does similar steps in
+reverse order to restore contexts, start APs and resume SOS. SOS is
+responsible for starting its own virtual APs as well as UOSes.
+
+.. figure:: images/pm-image24-105.png
+   :align: center
+   :name: pm-low-power-transition
+
+   SOS/Hypervisor low power state transition process

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

@@ -50,7 +50,7 @@ The timer softirq handler will check each expired timer on its
 timer_list.  Before calling the expired timer callback handler, it will
 remove the timer from its logical cpu timer_list. After calling the
 timer callback handler, it will re-add the timer to the timer_list if
-it’s a periodic timer. If you want to modify a timer before it expires,
+it's a periodic timer. If you want to modify a timer before it expires,
 you should call del_timer to remove the timer from the timer_list, then
 call add_timer again after updating the timer fields.
 

doc/developer-guides/hld/hv-vt-d.rst

@@ -138,7 +138,7 @@ host physical address (HPA).
 Domains and Memory Isolation
 ============================
 
-There are no DMA operations inside the hypervisor, so ACRN doesn’t
+There are no DMA operations inside the hypervisor, so ACRN doesn't
 create a domain for the hypervisor. No DMA operations from pass-through
 devices can access the hypervisor memory.
 
@@ -152,9 +152,9 @@ VM0 domain
    Service OS.
 
    IOMMU uses the EPT table of Normal world of VM0 as the address
-   translation structures for the devices in VM0 domain. The Normal world’s
+   translation structures for the devices in VM0 domain. The Normal world's
-   EPT table of VM0 doesn’t include the memory resource of the hypervisor
+   EPT table of VM0 doesn't include the memory resource of the hypervisor
-   and Secure worlds if any. So the devices in VM0 domain can’t access the
+   and Secure worlds if any. So the devices in VM0 domain can't access the
    memory belong to hypervisor or secure worlds.
 
 Other domains
@@ -162,14 +162,14 @@ Other domains
    domain for each User OS.
 
    IOMMU uses the EPT table of Normal world of a VM as the address
-   translation structures for the devices in the domain. The Normal world’s
+   translation structures for the devices in the domain. The Normal world's
    EPT table of the VM only allows devices to access the memory
    allocated for Normal world of the VM.
 
 Page-walk coherency
 ===================
 
-For the VT-d hardware, which doesn’t support page-walk coherency,
+For the VT-d hardware, which doesn't support page-walk coherency,
 hypervisor needs to make sure the updates of VT-d tables are synced in
 memory:
 
@@ -179,7 +179,7 @@ memory:
 -  EPT table of a VM.
 
 ACRN will flush the related cache line after updates of these structures
-if the VT-d hardware doesn’t support page-walk coherency.
+if the VT-d hardware doesn't support page-walk coherency.
 
 Super-page support
 ==================
@@ -191,7 +191,7 @@ Snoop control
 =============
 
 If VT-d hardware supports snoop control, it allows VT-d to control to
-ignore the “no-snoop attribute” in PCI-E transactions.
+ignore the "no-snoop attribute" in PCI-E transactions.
 
 The following table shows the snoop behavior of DMA operation controlled by the
 combination of:
@@ -238,7 +238,7 @@ ACRN enable Snoop Control by default if all enabled VT-d DMAR units
 support Snoop Control by setting bit 11 of leaf PTE of EPT table. Bit 11
 of leaf PTE of EPT is ignored by MMU. So no side effect for MMU.
 
-If one of the enabled VT-d DMAR units doesn’t support Snoop Control,
+If one of the enabled VT-d DMAR units doesn't support Snoop Control,
 then Bit 11 of leaf PET of EPT is not set since the field is treated as
 reserved(0) by VT-d hardware implementations not supporting Snoop
 Control.
@@ -252,7 +252,7 @@ be multiple DMAR units on the platform, ACRN allows some of the DMAR
 units to be ignored. If some DMAR unit(s) are marked as ignored, they
 would not be enabled.
 
-Hypervisor creates VM0 domain using the Normal World’s EPT table of VM0
+Hypervisor creates VM0 domain using the Normal World's EPT table of VM0
 as address translation table when creating VM0 as Service OS. And all
 PCI devices on the platform are added to VM0 domain. Then enable DMAR
 translation for DMAR unit(s) if they are not marked as ignored.
@@ -312,7 +312,7 @@ information or DMAR table.
 
 -  void init_iommu_vm0_domain(struct vm \*vm0)
 
-   Create VM0 domain using the Normal World’s EPT table of VM0 as address
+   Create VM0 domain using the Normal World's EPT table of VM0 as address
    translation table. Add all PCI devices on the platform to VM0 domain. Then enable
    DMAR translation.
 

doc/user-guides/acrn-shell.rst

@@ -1,4 +1,4 @@
-.. acrnshell:
+.. _acrnshell:
 
 ACRN Shell Commands
 ###################