doc: rst syntax tweaks

There are some subtle syntax errors in some documents that, while they
render OK (most of the time), are being caught by rstcheck (a
restructuredText linter). This PR fixes most of the issues encountered.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2020-06-03 14:16:53 -07:00 committed by David Kinder
parent 2e9da35ea3
commit db454dcdf1
13 changed files with 120 additions and 70 deletions

View File

@ -880,7 +880,7 @@ passthrough directly:
* - MSR_IA32_BIOS_SIGN_ID
- BIOS update signature ID
- "
- \"
* - MSR_IA32_TIME_STAMP_COUNTER
- Time-stamp counter
@ -924,24 +924,24 @@ passthrough directly:
- Handled by MTRR emulation.
* - MSR_IA32_MTRR_DEF_TYPE
- "
- "
- \"
- \"
* - MSR_IA32_MTRR_PHYSBASE_0~9
- "
- "
- \"
- \"
* - MSR_IA32_MTRR_FIX64K_00000
- "
- "
- \"
- \"
* - MSR_IA32_MTRR_FIX16K_80000/A0000
- "
- "
- \"
- \"
* - MSR_IA32_MTRR_FIX4K_C0000~F8000
- "
- "
- \"
- \"
* - MSR_IA32_X2APIC_*
- x2APIC related MSRs (offset from 0x800 to 0x900)

View File

@ -107,7 +107,7 @@ be updated.
.. figure:: images/ept-hierarchy.png
:align: center
:width: 800px
:name: EPT hierarchy
:name: EPT hierarchy pic
API
===

View File

@ -1,7 +1,7 @@
.. _faq:
FAQ
###
Frequently Asked Questions
##########################
Here are some frequently asked questions about the ACRN project.

View File

@ -82,7 +82,7 @@ license.
contribute
release_notes/index
asa
faq
FAQ <faq>
glossary
.. _BSD 3-clause license:

View File

@ -432,16 +432,23 @@ bootloader used by the Operating System (OS).
.. note::
The `Slim Bootloader <https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html>`_
is an alternative boot firmware that can be used to boot ACRN. The `Boot ACRN Hyervisor <https://slimbootloader.github.io/how-tos/boot-acrn.html>`_
tutorial provides more information on how to use SBL with ACRN.
The `Slim Bootloader
<https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html>`__
is an alternative boot firmware that can be used to boot ACRN. The `Boot
ACRN Hyervisor
<https://slimbootloader.github.io/how-tos/boot-acrn.html>`_ tutorial
provides more information on how to use SBL with ACRN.
.. note::
A virtual `Slim Bootloader <https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html>`_, called ``vSBL``,
can also be used to start User VMs. The :ref:`acrn-dm_parameters` provides more information
on how to boot a User VM using ``vSBL``. Note that in this case, the kernel command-line parameters are
defined by the combination of the ``cmdline.txt`` passed on to the ``iasimage`` script and in the launch script, via the ``-B`` option.
A virtual `Slim Bootloader
<https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html>`__,
called ``vSBL``, can also be used to start User VMs. The
:ref:`acrn-dm_parameters` provides more information on how to boot a
User VM using ``vSBL``. Note that in this case, the kernel command-line
parameters are defined by the combination of the ``cmdline.txt`` passed
on to the ``iasimage`` script and in the launch script, via the ``-B``
option.
Direct boot mode
================

View File

@ -234,7 +234,7 @@ Known Issues
1) Insert USB keyboard and mouse in standard A port (USB3.0 port)
2) Boot UOS by sharing the USB keyboard and mouse in cmd line:
-s n,xhci,1-1:1-2:1-3:1-4:2-1:2-2:2-3:2-4 \
-s n,xhci,1-1:1-2:1-3:1-4:2-1:2-2:2-3:2-4 \
3) UOS access USB keyboard and mouse.

View File

@ -453,7 +453,7 @@ Here is the offline configuration tool workflow:
.. note:: Refer to :ref:`acrn_config_tool_ui` for more details on
the configuration tool UI.
3. Auto generate the code.
#. Auto generate the code.
Python tools are used to generate configurations in patch format.
The patches are applied to your local ``acrn-hypervisor`` git tree

View File

@ -36,7 +36,7 @@ Install Kata Containers
The Kata Containers installation from Clear Linux's official repository does
not work with ACRN at the moment. Therefore, you must install Kata
Containers using the `manual installation
<https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md>`_
<https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md>`__
instructions (using a ``rootfs`` image).
#. Install the build dependencies.
@ -48,7 +48,7 @@ instructions (using a ``rootfs`` image).
#. Install Kata Containers.
At a high level, the `manual installation
<https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md>`_
<https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md>`__
steps are:
#. Build and install the Kata runtime.

View File

@ -9,8 +9,11 @@ Prerequisites
This tutorial assumes you have already set up the ACRN Service VM on an
Intel NUC Kit. If you have not, refer to the following instructions:
- Install a `Clear Linux OS <https://docs.01.org/clearlinux/latest/get-started/bare-metal-install-server.html>`_ on your NUC kit.
- Follow the instructions at :ref:`quick-setup-guide` to set up the Service VM automatically on your NUC kit. Follow steps 1 - 4.
- Install a `Clear Linux OS
<https://docs.01.org/clearlinux/latest/get-started/bare-metal-install-server.html>`_
on your NUC kit.
- Follow the instructions at :ref:`quick-setup-guide` to set up the
Service VM automatically on your NUC kit. Follow steps 1 - 4.
We are using Intel Kaby Lake NUC (NUC7i7DNHE) and Debian 10 as the User VM in this tutorial.
@ -92,7 +95,9 @@ steps will detail how to use the Debian CD-ROM (ISO) image to install Debian
#. Right-click **QEMU/KVM** and select **New**.
a. Choose **Local install media (ISO image or CDROM)** and then click **Forward**. A **Create a new virtual machine** box displays, as shown in :numref:`newVM-debian` below.
a. Choose **Local install media (ISO image or CDROM)** and then click
**Forward**. A **Create a new virtual machine** box displays, as shown
in :numref:`newVM-debian` below.
.. figure:: images/debian-uservm-2.png
:align: center
@ -100,15 +105,17 @@ steps will detail how to use the Debian CD-ROM (ISO) image to install Debian
Create a New Virtual Machine
b. Choose **Use ISO image** and click **Browse** - **Browse Local**. Select the ISO which you get from Step 1 above.
#. Choose **Use ISO image** and click **Browse** - **Browse Local**. Select the ISO which you get from Step 1 above.
c. Choose the **OS type:** Linux, **Version:** Debian Stretch and then click **Forward**.
#. Choose the **OS type:** Linux, **Version:** Debian Stretch and then click **Forward**.
d. Select **Forward** if you do not need to make customized CPU settings.
#. Select **Forward** if you do not need to make customized CPU settings.
e. Choose **Create a disk image for virtual machine**. Set the storage to 20 GB or more if necessary and click **Forward**.
#. Choose **Create a disk image for virtual machine**. Set the
storage to 20 GB or more if necessary and click **Forward**.
f. Rename the image if you desire. You must check the **customize configuration before install** option before you finish all stages.
#. Rename the image if you desire. You must check the **customize
configuration before install** option before you finish all stages.
#. Verify that you can see the Overview screen as set up, as shown in :numref:`debian10-setup` below:
@ -118,7 +125,8 @@ steps will detail how to use the Debian CD-ROM (ISO) image to install Debian
Debian Setup Overview
#. Complete the Debian installation. Verify that you have set up a vda disk partition, as shown in :numref:`partition-vda` below:
#. Complete the Debian installation. Verify that you have set up a vda
disk partition, as shown in :numref:`partition-vda` below:
.. figure:: images/debian-uservm-4.png
:align: center
@ -126,7 +134,9 @@ steps will detail how to use the Debian CD-ROM (ISO) image to install Debian
Virtual Disk (vda) partition
#. Upon installation completion, the KVM image is created in the ``/var/lib/libvirt/images`` folder. Convert the `gcow2` format to `img` **as the root user**:
#. Upon installation completion, the KVM image is created in the
``/var/lib/libvirt/images`` folder. Convert the `gcow2` format to `img`
**as the root user**:
.. code-block:: none
@ -138,7 +148,9 @@ Launch the Debian Image as the User VM
Re-use and modify the `launch_win.sh` script in order to launch the new Debian 10 User VM.
.. note:: This tutorial assumes SATA is the default boot drive; replace "/dev/sda1" mentioned below with "/dev/nvme0n1p1" if you are using an NVMe drive.
.. note:: This tutorial assumes SATA is the default boot drive; replace
"/dev/sda1" mentioned below with "/dev/nvme0n1p1" if you are using an
NVMe drive.
1. Copy the debian.img to your NUC:
@ -163,9 +175,16 @@ Re-use and modify the `launch_win.sh` script in order to launch the new Debian 1
<Add below as the acrn-dm parameter>
-s 7,xhci,1-2:1-3:1-4:1-5 \
.. note:: This will assign all USB ports (2 front and 2 rear) to the User VM. If you want to only assign the USB ports at the front, use "-s 7,xhci,1-2:1-3 \" instead. Refer to :ref:`acrn-dm_parameters` for ACRN for more information.
.. note:: This will assign all USB ports (2 front and 2 rear) to the
User VM. If you want to only assign the USB ports at the front,
use this instead::
#. Modify acrn.conf and reboot the Service VM to assign the Pipe A monitor to the Debian VM and the Pipe B monitor to the Service VM:
-s 7,xhci,1-2:1-3 \
Refer to :ref:`acrn-dm_parameters` for ACRN for more information.
#. Modify acrn.conf and reboot the Service VM to assign the Pipe A
monitor to the Debian VM and the Pipe B monitor to the Service VM:
.. code-block:: none
@ -206,7 +225,8 @@ Re-use and modify the `launch_win.sh` script in order to launch the new Debian 1
Enable the ttyS0 Console on the Debian VM
*****************************************
After the Debian VM reboots, follow the steps below to enable the ttyS0 console so you can make command-line entries directly from it.
After the Debian VM reboots, follow the steps below to enable the ttyS0
console so you can make command-line entries directly from it.
1. Log in to the Debian user interface and launch **Terminal** from the Application list.
@ -219,7 +239,8 @@ After the Debian VM reboots, follow the steps below to enable the ttyS0 console
GRUB_CMDLINE_LINUX="console=ttyS0,115200"
$ sudo update-grub
#. Add `virtio_console` to `/etc/initramfs-tools/modules`. **Power OFF** the Debian VM after `initramfs` is updated:
#. Add `virtio_console` to `/etc/initramfs-tools/modules`. **Power OFF**
the Debian VM after `initramfs` is updated:
.. code-block:: none
@ -227,7 +248,8 @@ After the Debian VM reboots, follow the steps below to enable the ttyS0 console
$ sudo update-initramfs -u
$ sudo poweroff
#. Log in to the Service VM and the modify the launch script to add the `virtio-console` parameter to the Device Model for the Debian VM:
#. Log in to the Service VM and the modify the launch script to add the
`virtio-console` parameter to the Device Model for the Debian VM:
.. code-block:: none
@ -235,7 +257,8 @@ After the Debian VM reboots, follow the steps below to enable the ttyS0 console
<add below to the acrn-dm command line>
-s 9,virtio-console,@stdio:stdio_port \
#. Launch Debian using the modified script. Verify that you see the console output shown in :numref:`console output-debian` below:
#. Launch Debian using the modified script. Verify that you see the
console output shown in :numref:`console output-debian` below:
.. figure:: images/debian-uservm-7.png
:align: center

View File

@ -9,8 +9,11 @@ Prerequisites
This tutorial assumes you have already set up the ACRN Service VM on an
Intel NUC Kit. If you have not, refer to the following instructions:
- Install a `Clear Linux OS <https://docs.01.org/clearlinux/latest/get-started/bare-metal-install-server.html>`_ on your NUC kit.
- Follow the instructions at :ref:`quick-setup-guide` to set up the Service VM automatically on your NUC kit. Follow steps 1 - 4.
- Install a `Clear Linux OS
<https://docs.01.org/clearlinux/latest/get-started/bare-metal-install-server.html>`_
on your NUC kit.
- Follow the instructions at :ref:`quick-setup-guide` to set up the
Service VM automatically on your NUC kit. Follow steps 1 - 4.
Before you start this tutorial, make sure the KVM tools are installed on the
development machine and set **IGD Aperture Size to 512** in the BIOS
@ -67,7 +70,9 @@ Build the Ubuntu KVM Image
This tutorial uses the Ubuntu 18.04 desktop ISO as the base image.
#. Download the `Ubuntu 18.04 desktop ISO <http://releases.ubuntu.com/18.04.3/ubuntu-18.04.3-desktop-amd64.iso?_ga=2.160010942.221344839.1566963570-491064742.1554370503>`_ on your development machine:
#. Download the `Ubuntu 18.04 desktop ISO
<http://releases.ubuntu.com/18.04.3/ubuntu-18.04.3-desktop-amd64.iso?_ga=2.160010942.221344839.1566963570-491064742.1554370503>`_
on your development machine:
#. Install Ubuntu via the virt-manager tool:
@ -85,7 +90,9 @@ This tutorial uses the Ubuntu 18.04 desktop ISO as the base image.
#. Right-click **QEMU/KVM** and select **New**.
a. Choose **Local install media (ISO image or CDROM)** and then click **Forward**. A **Create a new virtual machine** box displays, as shown in :numref:`newVM-ubun` below.
a. Choose **Local install media (ISO image or CDROM)** and then click
**Forward**. A **Create a new virtual machine** box displays, as shown
in :numref:`newVM-ubun` below.
.. figure:: images/ubuntu-uservm-2.png
:align: center
@ -93,15 +100,17 @@ This tutorial uses the Ubuntu 18.04 desktop ISO as the base image.
Create a New Virtual Machine
b. Choose **Use ISO image** and click **Browse** - **Browse Local**. Select the ISO which you get from Step 2 above.
#. Choose **Use ISO image** and click **Browse** - **Browse Local**. Select the ISO which you get from Step 2 above.
c. Choose the **OS type:** Linux, **Version:** Ubuntu 18.04 LTS and then click **Forward**.
#. Choose the **OS type:** Linux, **Version:** Ubuntu 18.04 LTS and then click **Forward**.
d. Select **Forward** if you do not need to make customized CPU settings.
#. Select **Forward** if you do not need to make customized CPU settings.
e. Choose **Create a disk image for virtual machine**. Set the storage to 20 GB or more if necessary and click **Forward**.
#. Choose **Create a disk image for virtual machine**. Set the
storage to 20 GB or more if necessary and click **Forward**.
f. Rename the image if you desire. You must check the **customize configuration before install** option before you finish all stages.
#. Rename the image if you desire. You must check the
**customize configuration before install** option before you finish all stages.
#. Verify that you can see the Overview screen as set up, as shown in :numref:`ubun-setup` below:
@ -118,7 +127,8 @@ This tutorial uses the Ubuntu 18.04 desktop ISO as the base image.
#. Upon installation completion, click **Restart** Now to make sure the Ubuntu OS boots successfully.
#. The KVM image is created in the ``/var/lib/libvirt/images`` folder. Convert the `gcow2` format to `img` **as the root user**:
#. The KVM image is created in the ``/var/lib/libvirt/images`` folder.
Convert the ``gcow2`` format to ``img`` **as the root user**:
.. code-block:: none
@ -128,11 +138,13 @@ This tutorial uses the Ubuntu 18.04 desktop ISO as the base image.
Launch the Ubuntu Image as the User VM
**************************************
Modify the `launch_win.sh` script in order to launch Ubuntu as the User VM.
Modify the ``launch_win.sh`` script in order to launch Ubuntu as the User VM.
.. note:: This tutorial assumes SATA is the default boot drive; replace "/dev/sda1" mentioned below with "/dev/nvme0n1p1" if you are using SSD.
.. note:: This tutorial assumes SATA is the default boot drive; replace
``/dev/sda1`` mentioned below with ``/dev/nvme0n1p1`` if you are
using an SSD.
1. Copy the uos.img to your NUC:
1. Copy the ``uos.img`` to your NUC:
.. code-block:: none
@ -155,9 +167,15 @@ Modify the `launch_win.sh` script in order to launch Ubuntu as the User VM.
<Add below as the acrn-dm parameter>
-s 7,xhci,1-2:1-3:1-4:1-5 \
.. note:: This will assign all USB ports (2 front and 2 rear) to the User VM. If you want to only assign the USB ports at the front, use "-s 7,xhci,1-2:1-3 \" instead. Refer to :ref:`acrn-dm_parameters` for ACRN for more information.
.. note:: This will assign all USB ports (2 front and 2 rear) to the
User VM. If you want to only assign the USB ports at the front,
use this instead::
#. Modify acrn.conf and reboot the Service VM:
-s 7,xhci,1-2:1-3 \
Refer to :ref:`acrn-dm_parameters` for ACRN for more information.
#. Modify ``acrn.conf`` and reboot the Service VM:
.. code-block:: none
@ -184,11 +202,12 @@ Modify the `launch_win.sh` script in order to launch Ubuntu as the User VM.
Enable the Ubuntu Console instead of the User Interface
*******************************************************
After the Ubuntu VM reboots, follow the steps below to enable the Ubuntu VM console so you can make command-line entries directly from it.
After the Ubuntu VM reboots, follow the steps below to enable the Ubuntu
VM console so you can make command-line entries directly from it.
1. Log in to the Ubuntu user interface and launch **Terminal** from the Application list.
#. Add "console=ttyS0,115200" to the grub file on the terminal:
#. Add ``console=ttyS0,115200`` to the grub file on the terminal:
.. code-block:: none
@ -198,7 +217,7 @@ After the Ubuntu VM reboots, follow the steps below to enable the Ubuntu VM cons
$ sudo update-grub
$ sudo poweroff
#. Modify the launch script to enable `virtio-console` for the Ubuntu VM:
#. Modify the launch script to enable ``virtio-console`` for the Ubuntu VM:
.. code-block:: none
@ -206,14 +225,11 @@ After the Ubuntu VM reboots, follow the steps below to enable the Ubuntu VM cons
<add below to the acrn-dm command line>
-s 9,virtio-console,@stdio:stdio_port \
#. Log in to the Service VM and launch Ubuntu. Verify that you see the console output shown in :numref:`console output-ubun` below:
#. Log in to the Service VM and launch Ubuntu. Verify that you see the
console output shown in :numref:`console output-ubun` below:
.. figure:: images/ubuntu-uservm-5.png
:align: center
:name: console output-ubun
Ubuntu VM console output

View File

@ -33,7 +33,7 @@ Build Celadon from source
*************************
#. Follow the instructions in the `Build Celadon from source
<https://01.org/projectceladon/documentation/getting-started/build-source>`_ guide
<https://01.org/projectceladon/documentation/getting-started/build-source>`__ guide
to set up the Celadon project source code.
.. note:: The master branch is based on the Google Android 10

View File

@ -121,7 +121,8 @@ Download Win10 ISO and drivers
- Complete the required info. Click **Continue**.
- Select the language and **x86 64 bit**. Click **Download ISO** and save as ``windows10-LTSC-17763.iso``.
#. Download the `Intel DCH Graphics Driver <https://downloadmirror.intel.com/29074/a08/igfx_win10_100.7212.zip>`_.
#. Download the `Intel DCH Graphics Driver
<https://downloadmirror.intel.com/29074/a08/igfx_win10_100.7212.zip>`__.
#. Download the `Oracle Windows driver <https://edelivery.oracle.com/osdc/faces/SoftwareDelivery>`_.
@ -244,7 +245,8 @@ Install Windows 10 by GVT-g
.. figure:: images/windows_install_10.png
:align: center
#. Copy the `Intel DCH Graphics Driver <https://downloadmirror.intel.com/29074/a08/igfx_win10_100.7212.zip>`_ into
#. Copy the `Intel DCH Graphics Driver
<https://downloadmirror.intel.com/29074/a08/igfx_win10_100.7212.zip>`__ into
Windows and install in safe mode. The display driver is updated to 7212.
.. _waag_display_conf_lable:
@ -352,4 +354,4 @@ obtain a licensed version of Windows.
For Windows 10 activation steps, refer to
`Activate Windows 10 <https://support.microsoft.com/en-us/help/12440/windows-10-activate>`__.
.. comment Reviewed for grammatical content on 20 May 2020.
.. comment Reviewed for grammatical content on 20 May 2020.

View File

@ -332,6 +332,7 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
ACRN supports three channels: ``ioc``, ``power button`` and ``uart``.
usage::
--pm_notify_channel ioc
Use ioc as power management event motify channel.
@ -360,4 +361,5 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
guests with secure boot.
usage::
--windows