doc: general edit for typos

Fix typos and misspellings, and tweak CSS for spacing before lists.

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

doc/api/devicemodel_api.rst

@@ -3,7 +3,11 @@
 Device Model APIs
 #################
 
-This section contains APIs for the SOS Device Model services.
+This section contains APIs for the SOS Device Model services.  Sources
+for the Device Model are found in the `ACRN Device Model GitHub repo`_
+
+.. _ACRN Device Model GitHub repo:
+   https://github.com/projectacrn/acrn-devicemodel/
 
 .. doxygengroup:: acrn_virtio
    :project: Project ACRN

doc/api/hypercall_api.rst

@@ -3,7 +3,11 @@
 Hypercall APIs
 ##############
 
-This section contains APIs for the hypercall services.
+This section contains APIs for the hypercall services.  Sources
+for the Device Model are found in the `ACRN Hypervisor GitHub repo`_
+
+.. _ACRN Hypervisor GitHub repo:
+   https://github.com/projectacrn/acrn-hypervisor/
 
 .. doxygengroup:: acrn_hypercall
    :project: Project ACRN

doc/contribute.rst

@@ -78,8 +78,8 @@ agreement is shown below and at http://developercertificate.org/.
 DCO Sign-Off Methods
 ====================
 
-The DCO requires a sign-off message in the following format appear on each
+The DCO requires that a sign-off message, in the following format,
-commit in the pull request::
+appears on each commit in the pull request::
 
    Signed-off-by: Acrnus Jones <acrnusj@gmail.com>
 
@@ -95,9 +95,9 @@ Prerequisites
 .. _project ACRN website: https://projectacrn.org
 
 As a contributor, you'll want to be familiar with project ACRN, how to
-configure, install, and use it as explained in the `project ACRN website`_
+configure, install, and use it as explained on the
-and how to set up your development environment as introduced in the
+`project ACRN website`_, and how to set up your development environment
-project ACRN `Getting Started Guide`_.
+as introduced in the project ACRN `Getting Started Guide`_.
 
 .. _Getting Started Guide:
    https://projectacrn.github.io/getting_started/
@@ -114,17 +114,24 @@ Repository layout
 To clone the ACRN hypervisor repository use::
 
     git clone https://github.com/projectacrn/acrn-hypervisor
-    
+
 To clone the ACRN device model repository use::
 
     git clone https://github.com/projectacrn/acrn-devicemodel
 
+To clone the ACRN documentation repository use::
+
+    git clone https://github.com/projectacrn/acrn-documentation
+
 The project ACRN directory structure is described in the `Hypervisor
 Primer`_ document. In addition to the ACRN hypervisor and device model itself,
-you'll also find the sources for technical documentation, sample code
+you'll also find the sources for technical documentation available from
-and supported board configurations.  All of these are available for
+the `ACRN documentation site`_.  All of these are available for
 developers to contribute to and enhance.
 
+.. _ACRN documentation site:
+   https://projectacrn.github.io/
+
 .. _Hypervisor Primer:
    https://projectacrn.github.io/hypervisor_primer
 
@@ -134,8 +141,9 @@ Submitting Issues
 .. _ACRN-dev mailing list:
    https://lists.projectacrn.org/g/acrn-dev
 
-Before starting on a patch, first check in our issues in the `ACRN-dev
+Issue tracking for ACRN is done using the `ACRN-dev mailing list`_.
-mailing list`_ system to see what's been reported on the issue you'd
+Before starting on a patch, first read through discussions in the `ACRN-dev
+mailing list`_ to see what's been reported on the issue you'd
 like to address.  Have a conversation on the `ACRN-dev mailing list`_ to
 see what others think of your issue (and proposed solution).  You may
 find others that have encountered the issue you're finding, or that have
@@ -158,7 +166,7 @@ Signed-off-by
 
 The name in the commit message ``Signed-off-by:`` line and your email must
 match the change authorship information. Make sure your :file:`.gitconfig`
-is set up correctly:
+is set up correctly by using:
 
 .. code-block:: console
 
@@ -203,7 +211,8 @@ and test your changes thoroughly before submitting.
 The general GitHub workflow used by project ACRN developers uses a combination of
 command line Git commands and browser interaction with GitHub.  As it is with
 Git, there are multiple ways of getting a task done.  We'll describe a typical
-workflow here:
+workflow here for the acrn-hypervisor repo that can also be used for the
+acrn-devicemodel and acrn-documentation repos:
 
 .. _Create a Fork of acrn-hypervisor:
    https://github.com/projectacrn/acrn-hypervisor#fork-destination-box
@@ -232,14 +241,18 @@ workflow here:
 
 #. Make changes, test locally, change, test, test again, ...
 
-#. When things look good, start the pull request process by adding your changed
+#. When things look good, start the pull request process by checking
-   files::
+   which files have not been staged::
+
+     git status
+
+   Then add the changed files::
 
      git add [file(s) that changed, add -p if you want to be more specific]
 
-   You can see files that are not yet staged using::
+   (or to have all changed files added use)::
 
-     git status
+     git add -A
 
 #. Verify changes to be committed look as you expected::
 
@@ -259,9 +272,9 @@ workflow here:
 
      git push origin fix_comment_typo
 
-#. In your web browser, go to your forked repo and click on the Compare & pull
+#. In your web browser, go to your personal forked repo and click on the Compare & pull
-   request button for the branch you just worked on and you want to open a pull
+   request button for the branch you just worked on and you want to
-   request with.
+   submit to the upstream repo.
 
 #. Review the pull request changes, and verify that you are opening a pull request
    for the appropriate branch. The title and message from your commit message should
@@ -285,7 +298,12 @@ workflow here:
    and use the same process described above to work on this new topic branch.
 
 #. If reviewers do request changes to your patch, you can interactively rebase
-   commit(s) to fix review issues. In your development repo::
+   commit(s) to fix review issues. In your development repo, make the
+   needed changes on the branch you made the initial submission::
+
+     git checkout fix-comment-typo
+
+   then::
 
      git fetch --all
      git rebase --ignore-whitespace upstream/master
@@ -311,8 +329,9 @@ workflow here:
 
    By force pushing your update, your original pull request will be updated with
    your changes so you won't need to resubmit the pull request.
-   
+
-   You can follow the same workflow for contributing to acrn-devicemodel.
+   You can follow the same workflow for contributing to acrn-devicemodel
+   or acrn-documentation repos.
 
 
 Commit Guidelines

doc/getting_started/index.rst

@@ -5,9 +5,9 @@ Getting Started Guide
 
 After reading the :ref:`introduction`, use this guide to get started
 using ACRN in a reference setup.  We'll show how to set up your
-development and target hardware, and then how to boot up of the ACRN
+development and target hardware, and then how to boot up the ACRN
 hypervisor and the `Clear Linux`_ Service OS and Guest OS on the Intel
-|reg| NUC, using the UEFI BIOS.
+|reg| NUC.
 
 .. _Clear Linux: https://clearlinux.org
 
@@ -16,7 +16,7 @@ Hardware setup
 
 The Intel |reg| NUC (NUC6CAYH) is the supported reference target
 platform for ACRN work, as described in :ref:`hardware`, and is the only
-platform tested with these setup instructions.
+platform currently tested with these setup instructions.
 
 The recommended NUC hardware configuration is:
 
@@ -40,9 +40,11 @@ for downloading and flashing an updated BIOS for the NUC.
 Set up a Clear Linux Operating System
 =====================================
 
-Currently, an installable version of ARCN does not exist. Therefore, we
+Currently, an installable version of ARCN does not exist. Therefore, you
-need to setup a base Clear Linux OS to bootstrap ACRN.
+need to setup a base Clear Linux OS to bootstrap ACRN on the NUC. You'll
-**ACRN requires Clear Linux version 21260 or newer.**
+need a network connection for your NUC to complete this setup.
+
+.. note:: ACRN requires Clear Linux version 21260 or newer.
 
 1. Follow this `Clear Linux installation guide
    <https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install>`__
@@ -71,11 +73,11 @@ need to setup a base Clear Linux OS to bootstrap ACRN.
       | /dev/sda3   | 111.3G   | Linux root (x86-64)   |
       +-------------+----------+-----------------------+
 
-4. After installation is complete, boot into Clear Linux and log in as
+4. After installation is complete, boot into Clear Linux, login as
-   root and set a password.
+   root, and set a password.
 
-5. Clear Linux is set to automatically update. If you do not wish for
+5. Clear Linux is set to automatically update itself. If you do not want
-   autoupdate, issue this command:
+   it to autoupdate, issue this command:
 
    .. code-block:: none
 
@@ -110,7 +112,7 @@ need to setup a base Clear Linux OS to bootstrap ACRN.
 Add the ACRN hypervisor to the EFI Partition
 ============================================
 
-In order to boot the ACRN SOS on the NUC, we need to add it to the EFI
+In order to boot the ACRN SOS on the NUC, you'll need to add it to the EFI
 partition. Follow these steps:
 
 #. Mount the EFI partition and verify you have the following files:
@@ -210,8 +212,9 @@ folder) as shown here:
    :caption: acrn-devicemodel/samples/bridge.sh
    :language: bash
 
-By default, it is located in the ``/usr/share/acrn/demo/``
+By default, the script is located in the ``/usr/share/acrn/demo/``
-directory. Use it directly by making it executable and running it:
+directory. Use it directly by making it executable and run it to create
+a network bridge:
 
 .. code-block:: none
 
@@ -256,8 +259,9 @@ Set up Reference UOS
       :caption: acrn-devicemodel/samples/launch_uos.sh
       :language: bash
 
-   By default, it is located in the ``/usr/share/acrn/demo/``
+   By default, the script is located in the ``/usr/share/acrn/demo/``
-   directory. Use it directly by making it executable and running it:
+   directory. Use it directly by making it executable and run it to
+   launch the User OS:
 
    .. code-block:: none
 
@@ -266,7 +270,7 @@ Set up Reference UOS
       # ./launch_uos.sh
 
 #. At this point, you've successfully booted the ACRN system,
-   hypervisor, SOS and UOS:
+   hypervisor, SOS, and UOS:
 
    .. figure:: images/gsg-successful-boot.png
       :align: center
@@ -277,7 +281,7 @@ Build ACRN from Source
 **********************
 
 If you would like to build ACRN hypervisor and device model from source,
-follow these steps:
+follow these steps, using your NUC as a development system:
 
 #. On your Clear Linux system, install the os-clr-on-clr bundle to get
    the necessary tools.

doc/hardware.rst

@@ -16,3 +16,17 @@ Intel Apollo Lake NUC
   <https://www.intel.com/content/www/us/en/products/boards-kits/nuc/kits/nuc6cayh.html>`_
 * Intel |reg| Celeron |reg| Processor J3455
 * Tested NUC with 8GB of RAM and using an 128GB SSD
+
+You can read a full `AnandTech review`_ of the NUC6CAYH NUC Kit and
+search online for where to purchase this NUC from `Amazon`_,
+`SimplyNUC`_, and other vendors. Be sure to purchase the NUC with the
+recommended memory and storage options noted above.
+
+.. _AnandTech review:
+   https://www.anandtech.com/show/12295/intel-nuc6cayh-arches-canyon-apollo-lake-ucff-pc-review
+
+.. _Amazon:
+   https://www.amazon.com/s/ref=nb_sb_noss_2?url=search-alias%3Daps&field-keywords=NUC6CAYH
+
+.. _SimplyNUC:
+   https://www.simplynuc.com/?s=NUC6CAYH&post_type=product

doc/index.rst

@@ -9,8 +9,8 @@ For information about the changes and additions for releases, please
 consult the published :ref:`release_notes` documentation.
 
 Source code for Project ACRN is maintained in the
-`Project ACRN GitHub repo`_, and is provided under the `BSD 3-clause license`_ (as found in
+`Project ACRN GitHub repo`_, and is provided under the BSD 3-clause
-the LICENSE file in the project repo).
+license.
 
 .. _BSD 3-clause license:
    https://github.com/projectacrn/acrn-hypervisor/blob/doc/master/LICENSE

doc/introduction/index.rst

@@ -17,7 +17,10 @@ partitioning hypervisors. The ACRN hypervisor architecture partitions
 the system into different functional domains, with carefully selected
 guest OS sharing optimizations for IoT and embedded devices.
 
-An interesting use case example for the ACRN Hypervisor is in automotive
+Automotive Use Case Example
+***************************
+
+An interesting use case example for the ACRN Hypervisor is in an automotive
 scenario.  The ACRN hypervisor can be used for building a Software
 Defined Cockpit (SDC) or an In-Vehicle Experience (IVE) solution.  As a
 reference implementation, ACRN provides the basis for embedded
@@ -33,28 +36,28 @@ considerations.
 An **Instrument Cluster (IC)** system is used to show the driver operational
 information about the vehicle, such as:
 
--  the speed, the fuel level, trip mile and other driving information of
+- the speed, the fuel level, trip mile and other driving information of
-   the car;
+  the car;
--  projecting heads-up images on the windshield, with alerts for low
+- projecting heads-up images on the windshield, with alerts for low
-   fuel or tire pressure;
+  fuel or tire pressure;
--  showing rear-view camera, and surround-view for parking assistance.
+- showing rear-view camera, and surround-view for parking assistance.
 
 An **In-Vehicle Infotainment (IVI)** system's capabilities can include:
 
--  navigation systems, radios, and other entertainment systems;
+- navigation systems, radios, and other entertainment systems;
--  connection to mobile devices for phone calls, music, and applications
+- connection to mobile devices for phone calls, music, and applications
-   via voice recognition;
+  via voice recognition;
--  control interaction by gesture recognition or touch.
+- control interaction by gesture recognition or touch.
 
 A **Rear Seat Entertainment (RSE)** system could run:
 
--  entertainment system;
+- entertainment system;
--  virtual office;
+- virtual office;
--  connection to the front-seat IVI system and mobile devices (cloud
+- connection to the front-seat IVI system and mobile devices (cloud
-   connectivity).
+  connectivity).
--  connection to mobile devices for phone calls, music, and
+- connection to mobile devices for phone calls, music, and
-   applications via voice recognition;
+  applications via voice recognition;
--  control interaction by gesture recognition or touch
+- control interaction by gesture recognition or touch
 
 The ACRN hypervisor can support both Linux\* VM and Android\* VM as a
 User OS, with the User OS managed by the ACRN hypervisor. Developers and
@@ -73,14 +76,14 @@ hypervisor.
 
 This ACRN hypervisor block diagram shows:
 
--  The ACRN hypervisor sits right on top of the bootloader for fast
+- The ACRN hypervisor sits right on top of the bootloader for fast
-   booting capabilities.
+  booting capabilities.
--  Partitioning of resources to ensure safety-critical and non-safety
+- Partitioning of resources to ensure safety-critical and non-safety
-   critical domains are able to coexist on one platform.
+  critical domains are able to coexist on one platform.
--  Rich I/O mediators allows various I/O devices shared across VMs, and
+- Rich I/O mediators allows various I/O devices shared across VMs, and
-   thus delivers a comprehensive user experience
+  thus delivers a comprehensive user experience
--  Multiple operating systems are supported by one SoC through efficient
+- Multiple operating systems are supported by one SoC through efficient
-   virtualization.
+  virtualization.
 
 .. note::
    The yellow color parts in :numref:`ivi-block` are part of the project
@@ -145,11 +148,11 @@ on an Intel |reg| Architecture platform NUC (see :ref:`hardware`).
 
 The Boot process proceeds as follows:
 
-1. UEFI verifies and boots the ACRN hypervisor and Service OS Bootloader
+#. UEFI verifies and boots the ACRN hypervisor and Service OS Bootloader
-2. UEFI (or Service OS Bootloader) verifies and boots Service OS kernel
+#. UEFI (or Service OS Bootloader) verifies and boots Service OS kernel
-3. Service OS kernel verifies and loads ACRN Device Model and Virtual
+#. Service OS kernel verifies and loads ACRN Device Model and Virtual
    bootloader through dm-verity
-4. Virtual bootloader starts the User-side verified boot process
+#. Virtual bootloader starts the User-side verified boot process
 
 
 ACRN Hypervisor Architecture
@@ -243,14 +246,14 @@ used to give VM applications (and OSes) access to these shared devices.
 Traditionally there are three architectural approaches to device
 emulation:
 
-* The first architecture is device emulation within the hypervisor which
+* The first architecture is **device emulation within the hypervisor** which
   is a common method implemented within the VMware\* workstation product
   (an operating system-based hypervisor). In this method, the hypervisor
   includes emulations of common devices that the various guest operating
   systems can share, including virtual disks, virtual network adapters,
   and other necessary platform elements.
 
-* The second architecture is called user space device emulation. As the
+* The second architecture is called **user space device emulation**. As the
   name implies, rather than the device emulation being embedded within
   the hypervisor, it is instead implemented in a separate user space
   application. QEMU, for example, provides this kind of device emulation
@@ -262,7 +265,7 @@ emulation:
   functionality.
 
 * The third variation on hypervisor-based device emulation is
-  paravirtualized (PV) drivers. In this model introduced by the `XEN
+  **paravirtualized (PV) drivers**. In this model introduced by the `XEN
   project`_ the hypervisor includes the physical drivers, and each guest
   operating system includes a hypervisor-aware driver that works in
   concert with the hypervisor drivers.

doc/primer/index.rst

@@ -490,21 +490,21 @@ PIO/MMIO trap Flow
 
 Here is a description of the PIO/MMIO trap flow:
 
-1. Instruction decoder: get the Guest Physical Address (GPA) from VM
+#. Instruction decoder: get the Guest Physical Address (GPA) from VM
    Exit, go through gla2gpa() page walker if necessary.
 
-2. Emulate the instruction. Here the hypervisor will have an address
+#. Emulate the instruction. Here the hypervisor will have an address
    range check to see if the hypervisor is interested in this IO
    port or MMIO GPA access.
 
-3. Hypervisor emulates vLAPIC, vIOAPIC, vPIC, and vUART only (for
+#. Hypervisor emulates vLAPIC, vIOAPIC, vPIC, and vUART only (for
    Service OS only). Any other emulation request are forwarded to
    the SOS for handling. The vCPU raising the I/O request will
    halt until this I/O request is processed successfully. An IPI will
    send to vCPU0 of SOS to notify there is an I/O request waiting for
    service.
 
-4. Service OS VHM module takes the I/O request and dispatches the request
+#. Service OS VHM module takes the I/O request and dispatches the request
    to multiple clients. These clients could be SOS kernel space
    VBS-K, MPT, or User-land Device model. VHM I/O request server
    selects a default fallback client responsible to handle any I/O
@@ -514,7 +514,7 @@ Here is a description of the PIO/MMIO trap flow:
    request falls into the client range, the I/O request server will
    send the request to that client.
 
-5. Multiple clients - fallback client (Device Model in user-land),
+#. Multiple clients - fallback client (Device Model in user-land),
    VBS-K client, MPT client.
    Once the I/O request emulation completes, the client updates the
    request status and notifies the hypervisor by a hypercall.
@@ -560,12 +560,12 @@ hypervisor will support APIC-v and Post interrupts in a future release.
 
 vLAPIC provides the same feature as a native LAPIC:
 
--  Mask/Unmask vectors
+- Mask/Unmask vectors
--  Inject virtual vectors (Level or Edge trigger mode) to vCPU
+- Inject virtual vectors (Level or Edge trigger mode) to vCPU
--  Notify vIOAPIC of EOI processing
+- Notify vIOAPIC of EOI processing
--  Provide TSC Timer service
+- Provide TSC Timer service
--  vLAPIC support CR8 to update TPR
+- vLAPIC support CR8 to update TPR
--  INIT/STARTUP handling
+- INIT/STARTUP handling
 
 Virtual IOAPIC
 ==============
@@ -695,7 +695,7 @@ all the Back-end Virtio drivers are implemented using the Virtio APIs
 and the FE drivers are re-using Linux standard Front-end Virtio drivers.
 
 Virtio-rnd
-=================
+==========
 
 The Virtio-rnd entropy device supplies high-quality randomness for guest
 use. The Virtio device ID of the Virtio-rnd device is 4, and supports

doc/release_notes.rst

@@ -15,14 +15,14 @@ In March 2018, Intel announced the open source Project ACRN at the
 
 ACRN is a flexible, lightweight reference hypervisor, built with
 real-time and safety-criticality in mind, optimized to streamline
-embedded development through an open source platform.
+embedded development through an open source platform. Check out the
+:ref:`introduction` for more information.
 
 The project ACRN reference code can be found on GitHub in
 https://github.com/projectacrn.  It includes the ACRN hypervisor, the
-ACRN device model and documentation.  ACRN is a flexible, lightweight
+ACRN device model, and documentation.
-hypervisor, built with real-time and safety-criticality in mind,it is
+
-optimized to streamline embedded development through an open source
+ACRN's key features include:
-reference platform. ACRNs key features include:
 
 * Small footprint
 * Built with real-time in mind
@@ -37,7 +37,7 @@ This version 0.1 release has the following software components:
 * The ACRN Device Model
 * The ACRN Virtio framework
 * The ACRN Block & NIC & console Virtio drivers
-* The ACRN Virtio Backend Service(VBS) & Vibrio and Hypervisor Service Module(VHM).
+* The ACRN Virtio Backend Service(VBS) & Virtio and Hypervisor Service Module(VHM).
 
 Version 0.1 features include:
 

doc/static/acrn-custom.css

@@ -19,6 +19,11 @@
     color: rgba(255,255,255,1);
 }
 
+/* squish the space between a paragraph before a list */
+div > p + ul, div > p + ol {
+   margin-top: -20px;
+}
+
 /* add some space before the figure caption */
 p.caption  {
 #    border-top: 1px solid;