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