From db454dcdf1a95966dca6ba0da81ef6b51fde9729 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Wed, 3 Jun 2020 14:16:53 -0700 Subject: [PATCH] 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 --- doc/developer-guides/hld/hv-cpu-virt.rst | 22 ++++---- doc/developer-guides/trusty.rst | 2 +- doc/faq.rst | 4 +- doc/index.rst | 2 +- doc/introduction/index.rst | 21 +++++--- doc/release_notes/release_notes_0.5.rst | 2 +- doc/tutorials/acrn_configuration_tool.rst | 2 +- doc/tutorials/run_kata_containers.rst | 4 +- doc/tutorials/running_deb_as_user_vm.rst | 57 ++++++++++++++------- doc/tutorials/running_ubun_as_user_vm.rst | 62 ++++++++++++++--------- doc/tutorials/using_celadon_as_uos.rst | 2 +- doc/tutorials/using_windows_as_uos.rst | 8 +-- doc/user-guides/acrn-dm-parameters.rst | 2 + 13 files changed, 120 insertions(+), 70 deletions(-) diff --git a/doc/developer-guides/hld/hv-cpu-virt.rst b/doc/developer-guides/hld/hv-cpu-virt.rst index 56d8a6b2a..58447e823 100644 --- a/doc/developer-guides/hld/hv-cpu-virt.rst +++ b/doc/developer-guides/hld/hv-cpu-virt.rst @@ -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) diff --git a/doc/developer-guides/trusty.rst b/doc/developer-guides/trusty.rst index 9a8cf31ca..8c8d9443f 100644 --- a/doc/developer-guides/trusty.rst +++ b/doc/developer-guides/trusty.rst @@ -107,7 +107,7 @@ be updated. .. figure:: images/ept-hierarchy.png :align: center :width: 800px - :name: EPT hierarchy + :name: EPT hierarchy pic API === diff --git a/doc/faq.rst b/doc/faq.rst index 7348a54fd..45e2ae957 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -1,7 +1,7 @@ .. _faq: -FAQ -### +Frequently Asked Questions +########################## Here are some frequently asked questions about the ACRN project. diff --git a/doc/index.rst b/doc/index.rst index 1950b1349..6e61b96a2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -82,7 +82,7 @@ license. contribute release_notes/index asa - faq + FAQ glossary .. _BSD 3-clause license: diff --git a/doc/introduction/index.rst b/doc/introduction/index.rst index f71ab3ed2..e798697e1 100644 --- a/doc/introduction/index.rst +++ b/doc/introduction/index.rst @@ -432,16 +432,23 @@ bootloader used by the Operating System (OS). .. note:: - The `Slim Bootloader `_ - is an alternative boot firmware that can be used to boot ACRN. The `Boot ACRN Hyervisor `_ - tutorial provides more information on how to use SBL with ACRN. + The `Slim Bootloader + `__ + is an alternative boot firmware that can be used to boot ACRN. The `Boot + ACRN Hyervisor + `_ tutorial + provides more information on how to use SBL with ACRN. .. note:: - A virtual `Slim Bootloader `_, 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 + `__, + 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 ================ diff --git a/doc/release_notes/release_notes_0.5.rst b/doc/release_notes/release_notes_0.5.rst index 13f6ac16a..7f57c586f 100644 --- a/doc/release_notes/release_notes_0.5.rst +++ b/doc/release_notes/release_notes_0.5.rst @@ -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. diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index 5bb30ed48..76d66f0f3 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -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 diff --git a/doc/tutorials/run_kata_containers.rst b/doc/tutorials/run_kata_containers.rst index 3e863fc65..8b3cd54bf 100644 --- a/doc/tutorials/run_kata_containers.rst +++ b/doc/tutorials/run_kata_containers.rst @@ -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 -`_ +`__ 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 - `_ + `__ steps are: #. Build and install the Kata runtime. diff --git a/doc/tutorials/running_deb_as_user_vm.rst b/doc/tutorials/running_deb_as_user_vm.rst index c480f2650..ad235af37 100644 --- a/doc/tutorials/running_deb_as_user_vm.rst +++ b/doc/tutorials/running_deb_as_user_vm.rst @@ -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 `_ 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 + `_ + 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 -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 -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 diff --git a/doc/tutorials/running_ubun_as_user_vm.rst b/doc/tutorials/running_ubun_as_user_vm.rst index 54a7cf628..d8534c357 100644 --- a/doc/tutorials/running_ubun_as_user_vm.rst +++ b/doc/tutorials/running_ubun_as_user_vm.rst @@ -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 `_ 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 + `_ + 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 `_ on your development machine: +#. Download the `Ubuntu 18.04 desktop ISO + `_ + 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. -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 -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 - - - - diff --git a/doc/tutorials/using_celadon_as_uos.rst b/doc/tutorials/using_celadon_as_uos.rst index 9808d7056..ce4332610 100644 --- a/doc/tutorials/using_celadon_as_uos.rst +++ b/doc/tutorials/using_celadon_as_uos.rst @@ -33,7 +33,7 @@ Build Celadon from source ************************* #. Follow the instructions in the `Build Celadon from source - `_ guide + `__ guide to set up the Celadon project source code. .. note:: The master branch is based on the Google Android 10 diff --git a/doc/tutorials/using_windows_as_uos.rst b/doc/tutorials/using_windows_as_uos.rst index a1d8b3495..da290bbf0 100644 --- a/doc/tutorials/using_windows_as_uos.rst +++ b/doc/tutorials/using_windows_as_uos.rst @@ -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 `_. +#. Download the `Intel DCH Graphics Driver + `__. #. Download the `Oracle Windows driver `_. @@ -244,7 +245,8 @@ Install Windows 10 by GVT-g .. figure:: images/windows_install_10.png :align: center -#. Copy the `Intel DCH Graphics Driver `_ into +#. Copy the `Intel DCH Graphics Driver + `__ 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 `__. -.. comment Reviewed for grammatical content on 20 May 2020. \ No newline at end of file +.. comment Reviewed for grammatical content on 20 May 2020. diff --git a/doc/user-guides/acrn-dm-parameters.rst b/doc/user-guides/acrn-dm-parameters.rst index 40029c4be..926e0e024 100644 --- a/doc/user-guides/acrn-dm-parameters.rst +++ b/doc/user-guides/acrn-dm-parameters.rst @@ -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