diff --git a/doc/getting-started/roscube/roscube-gsg.rst b/doc/getting-started/roscube/roscube-gsg.rst deleted file mode 100644 index bdf5b9aae..000000000 --- a/doc/getting-started/roscube/roscube-gsg.rst +++ /dev/null @@ -1,11 +0,0 @@ -:orphan: - -.. _roscube-gsg: - -Getting Started Guide for ACRN Industry Scenario With ROScube-I -############################################################### - -ROScube support is not verified with the latest release of ACRN. See the -`v2.5 release ROSCube documentation -`_ -for the latest instructions. diff --git a/doc/learn.rst b/doc/learn.rst deleted file mode 100644 index 3e2d71f85..000000000 --- a/doc/learn.rst +++ /dev/null @@ -1,15 +0,0 @@ -:orphan: - -.. _learn_acrn: - -What Is ACRN -############ - -ACRN is supported on Apollo Lake and Kaby Lake Intel platforms, -as described in :ref:`hardware`. - -.. toctree:: - :maxdepth: 1 - - introduction/index - diff --git a/doc/tutorials/running_deb_as_serv_vm.rst b/doc/tutorials/running_deb_as_serv_vm.rst deleted file mode 100644 index 602ef5552..000000000 --- a/doc/tutorials/running_deb_as_serv_vm.rst +++ /dev/null @@ -1,158 +0,0 @@ -:orphan: - -.. _running_deb_as_serv_vm: - -Run Debian as the Service VM -############################ - -The `Debian Project `_ is an association of -individuals who have made common cause to create a `free -`_ operating system. The `latest -stable Debian release `_ is -10.0. - -This tutorial describes how to use Debian 10.0 as the Service VM OS with -the ACRN hypervisor. - -Prerequisites -************* - -Use the following instructions to install Debian. - -- Navigate to `Debian 10 iso - `_. - Select and download **debian-10.1.0-amd64-netinst.iso** (scroll down to - the bottom of the page). - - .. note:: These instructions were validated with the - debian_10.1.0 ISO image. A newer Debian 10 version - should still work as expected. - -- Follow the `Debian installation guide - `_ to - install it on your board; we are using a Kaby Lake Intel NUC (NUC7i7DNHE) - in this tutorial. -- :ref:`gsg` for ACRN. -- Update to the newer iASL: - - .. code-block:: bash - - $ sudo apt update - $ sudo apt install m4 bison flex zlib1g-dev - $ cd ~ - $ wget https://acpica.org/sites/acpica/files/acpica-unix-20190816.tar.gz - $ tar zxvf acpica-unix-20190816.tar.gz - $ cd acpica-unix-20190816 - $ make clean && make iasl - $ sudo cp ./generate/unix/bin/iasl /usr/sbin/ - -Validated Versions -****************** - -- **Debian version:** 10.1 (buster) -- **ACRN hypervisor tag:** acrn-2020w40.1-180000p -- **Debian Service VM Kernel version:** release_2.2 - -Install ACRN on the Debian VM -***************************** - -#. Clone the `Project ACRN `_ code repository: - - .. code-block:: bash - - $ cd ~ - $ git clone https://github.com/projectacrn/acrn-hypervisor - $ cd acrn-hypervisor - $ git checkout acrn-2020w40.1-180000p - -#. Build and install ACRN: - - .. code-block:: bash - - $ make all BOARD_FILE=misc/vm_configs/xmls/board-xmls/nuc7i7dnb.xml SCENARIO_FILE=misc/vm_configs/xmls/config-xmls/nuc7i7dnb/industry.xml RELEASE=0 - $ sudo make install - $ sudo mkdir /boot/acrn/ - $ sudo cp ~/acrn-hypervisor/build/hypervisor/acrn.bin /boot/acrn/ - -#. Build and Install the Service VM kernel: - - .. code-block:: bash - - $ mkdir ~/sos-kernel && cd ~/sos-kernel - $ git clone https://github.com/projectacrn/acrn-kernel - $ cd acrn-kernel - $ git checkout release_2.2 - $ cp kernel_config_uefi_sos .config - $ make olddefconfig - $ make all - $ sudo make modules_install - $ sudo cp arch/x86/boot/bzImage /boot/bzImage - -#. Update Grub for the Debian Service VM: - - Update the ``/etc/grub.d/40_custom`` file as shown below. - - .. note:: - Enter the command line for the kernel in ``/etc/grub.d/40_custom`` as - a single line and not as multiple lines. Otherwise, the kernel will - fail to boot. - - .. code-block:: none - - menuentry "ACRN Multiboot Debian Service VM" --id debian-service-vm { - recordfail - load_video - insmod gzio - insmod part_gpt - insmod ext2 - - search --no-floppy --fs-uuid --set 9bd58889-add7-410c-bdb7-1fbc2af9b0e1 - echo 'loading ACRN...' - multiboot2 /boot/acrn/acrn.bin root=PARTUUID="e515916d-aac4-4439-aaa0-33231a9f4d83" - module2 /boot/bzImage Linux_bzImage - } - - .. note:: - Update this to use the UUID (``--set``) and PARTUUID (``root=`` parameter) - (or use the device node directly) of the root partition (e.g. - ``/dev/nvme0n1p2``). Hint: use ``sudo blkid ``. - - Update the kernel name if you used a different name as the source - for your Service VM kernel. - -#. Modify the ``/etc/default/grub`` file to make the Grub menu visible when - booting and make it load the Service VM kernel by default. Modify the - lines shown below: - - .. code-block:: none - - GRUB_DEFAULT=debian-service-vm - #GRUB_TIMEOUT_STYLE=hidden - GRUB_TIMEOUT=5 - GRUB_CMDLINE_LINUX="text" - -#. Update Grub on your system: - - .. code-block:: none - - $ sudo update-grub - $ sudo reboot - -#. Log in to the Debian Service VM and check the ACRN status: - - .. code-block:: bash - - $ dmesg | grep ACRN - [ 0.000000] Hypervisor detected: ACRN - [ 0.981476] ACRNTrace: Initialized acrn trace module with 4 cpu - [ 0.982837] ACRN HVLog: Failed to init last hvlog devs, errno -19 - [ 0.983023] ACRN HVLog: Initialized hvlog module with 4 cp - -Enable Network Sharing to Give Network Access to the User VM -************************************************************ - -.. code-block:: bash - - $ sudo systemctl enable systemd-networkd - $ sudo systemctl start systemd-networkd - diff --git a/doc/tutorials/running_deb_as_user_vm.rst b/doc/tutorials/running_deb_as_user_vm.rst deleted file mode 100644 index f7e09aa68..000000000 --- a/doc/tutorials/running_deb_as_user_vm.rst +++ /dev/null @@ -1,260 +0,0 @@ -:orphan: - -.. _running_deb_as_user_vm: - -Run Debian as the User VM -######################### - -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 `Ubuntu 18.04 desktop ISO - `_ - on your board. -- Follow the instructions in :ref:`gsg` guide to setup the Service VM. - -We are using a Kaby Lake Intel NUC (NUC7i7DNHE) and Debian 10 as the User VM in this tutorial. - -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 -settings. Connect two monitors to your -Intel NUC: - -.. code-block:: none - - $ sudo apt install qemu-kvm libvirt-clients libvirt-daemon-system bridge-utils virt-manager ovmf - -.. figure:: images/debian-uservm-0.png - :align: center - :name: intel-bios-deb - - Intel Visual BIOS - -We installed these KVM tools on Ubuntu 18.04; refer to the table below for our hardware configurations. - -Hardware Configurations -======================= - -+--------------------------+----------------------+---------------------------------------------------------------------+ -| Platform (Intel x86) | Product/Kit Name | Hardware | Description | -+==========================+======================+======================+=====================================+========+ -| Kaby Lake | NUC7i7DNH | Processor | - Intel(R) Core(TM) i7-8650U CPU @ 1.90GHz | -| | +----------------------+----------------------------------------------+ -| | | Graphics | - UHD Graphics 620 | -| | | | - Two HDMI 2.0a ports supporting 4K at 60 Hz | -| | +----------------------+----------------------------------------------+ -| | | System memory | - 8GiB SO-DIMM DDR4 2400 MHz | -| | +----------------------+----------------------------------------------+ -| | | Storage capabilities | - 1TB WDC WD10SPZX-22Z | -+--------------------------+----------------------+----------------------+----------------------------------------------+ -| PC (development machine) | | Processor | - Intel(R) Core(TM) i7-2600 CPU @ 3.40GHz | -| | +----------------------+----------------------------------------------+ -| | | System memory | - 2GiB DIMM DDR3 Synchronous 1333 MHz x 4 | -| | +----------------------+----------------------------------------------+ -| | | Storage capabilities | - 1TB WDC WD10JPLX-00M | -+--------------------------+----------------------+----------------------+----------------------------------------------+ - - - -Validated Versions -================== - -- **Ubuntu version:** 18.04 -- **ACRN hypervisor tag:** v2.2 -- **Service VM Kernel version:** v2.2 - -Build the Debian KVM Image -************************** - -This tutorial describes how to build a Debian 10 KVM image. The next few -steps will detail how to use the Debian CD-ROM (ISO) image to install Debian -10 onto a virtual disk. - -#. Download the Debian ISO on your development machine: - - .. code-block:: none - - $ mkdir ~/debian10 && cd ~/debian10 - $ wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-10.0.0-amd64-netinst.iso - -#. Install the Debian ISO via the virt-manager tool: - - .. code-block:: none - - $ sudo virt-manager - -#. Verify that you can see the main menu as shown in the figure below. - - .. figure:: images/debian-uservm-1.png - :align: center - :name: vmmanager-debian - - Virtual Machine Manager - -#. Right-click **QEMU/KVM** and select **New**. - - a. Choose **Local install media (ISO image or CD-ROM)** and then click - **Forward**. A **Create a new virtual machine** box displays, as shown - in the figure below. - - .. figure:: images/debian-uservm-2.png - :align: center - :name: newVM-debian - - Create a New Virtual Machine - - #. Choose **Use ISO image** and click **Browse** - **Browse Local**. - Select the ISO image you get from Step 1 above. - - #. Choose the **OS type:** Linux, **Version:** Debian Stretch and then click **Forward**. - - #. Select **Forward** if you do not need to make customized CPU settings. - - #. Choose **Create a disk image for virtual machine**. Set the - storage to 20 GB or more if necessary and click **Forward**. - - #. 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 has been set up, shown in the - figure below: - - .. figure:: images/debian-uservm-3.png - :align: center - :name: debian10-setup - - Debian Setup Overview - -#. Complete the Debian installation. Verify that you have set up a - Virtual Disk (VDA) partition, as shown in the figure below: - - .. figure:: images/debian-uservm-4.png - :align: center - :name: partition-vda - - 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**: - - .. code-block:: none - - $ cd ~/debian10 - $ qemu-img convert -f qcow2 -O raw /var/lib/libvirt/images/debian10.qcow2 debian10.img - -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. - -1. Copy the debian.img to your Intel NUC: - - .. code-block:: none - - # scp ~/debian10/debian10.img user_name@ip_address:~/debian10.img - -#. Log in to the ACRN Service VM, and create a launch script from the existing script: - - .. code-block:: none - - $ cd ~ - $ cp /usr/share/acrn/samples/nuc/launch_win.sh ./launch_debian.sh - $ sed -i "s/win10-ltsc.img/debian10.img/" launch_debian.sh - -#. Assign USB ports to the Debian VM in order to use the mouse and keyboard before the launch: - - .. code-block:: none - - $ vim launch_debian.sh - - - -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 this instead:: - - -s 7,xhci,1-2:1-3 \ - - Refer to :ref:`acrn-dm_parameters` for ACRN for more information. - -#. Copy grubx64.efi to bootx64.efi: - - .. code-block:: none - - $ sudo losetup -f -P --show ~/debian10.img - $ sudo mount /dev/loop0p1 /mnt - $ sudo mkdir -p /mnt/EFI/boot - $ sudo cp /mnt/EFI/debian/grubx64.efi /mnt/EFI/boot/bootx64.efi - $ sync && sudo umount /mnt - -#. Launch the Debian VM after logging in to the Service VM: - - .. code-block:: none - - $ sudo ./launch_debian.sh - -#. View the Debian desktop on the secondary monitor, as shown in the figure - below: - - .. figure:: images/debian-uservm-5.png - :align: center - :name: debian-display1 - - .. figure:: images/debian-uservm-6.png - :align: center - :name: debian-display2 - - The Debian desktop appears on the secondary monitor (bottom image) - -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. - -1. Log in to the Debian user interface and launch **Terminal** from the Application list. - -#. Add "console=ttyS0,115200" to the grub file on the terminal: - - .. code-block:: none - - $ sudo vim /etc/default/grub - - 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: - - .. code-block:: none - - $ sudo echo "virtio_console" >> /etc/initramfs-tools/modules - $ sudo update-initramfs -u - $ sudo poweroff - -#. Log in to the Service VM and modify the launch script to add the - `virtio-console` parameter to the Device Model for the Debian VM: - - .. code-block:: none - - $ vim ~/launch_debian.sh - - -s 9,virtio-console,@stdio:stdio_port \ - -#. Launch Debian using the modified script. Verify that you see the - console output shown in the figure below: - - .. figure:: images/debian-uservm-7.png - :align: center - :name: console output-debian - - Debian VM console output diff --git a/doc/tutorials/running_ubun_as_user_vm.rst b/doc/tutorials/running_ubun_as_user_vm.rst deleted file mode 100644 index 990efdd0b..000000000 --- a/doc/tutorials/running_ubun_as_user_vm.rst +++ /dev/null @@ -1,230 +0,0 @@ -:orphan: - -.. _running_ubun_as_user_vm: - -Run Ubuntu as the User VM -######################### - -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 `Ubuntu 18.04 desktop ISO - `_ - on your board. -- Follow the instructions in :ref:`gsg` to set up the Service VM. - - -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 -settings. Connect two monitors to your -Intel NUC: - -.. code-block:: none - - $ sudo apt install qemu-kvm libvirt-clients libvirt-daemon-system bridge-utils virt-manager ovmf - -.. figure:: images/ubuntu-uservm-0.png - :align: center - :name: intel-bios-ubun - - Intel Visual BIOS - -We installed these KVM tools on Ubuntu 18.04; refer to the table below for our hardware configurations. - -Hardware Configurations -======================= - -+--------------------------+----------------------+---------------------------------------------------------------------+ -| Platform (Intel x86) | Product/Kit Name | Hardware | Description | -+==========================+======================+======================+=====================================+========+ -| Kaby Lake | NUC7i7DNH | Processor | - Intel(R) Core(TM) i7-8650U CPU @ 1.90GHz | -| | +----------------------+----------------------------------------------+ -| | | Graphics | - UHD Graphics 620 | -| | | | - Two HDMI 2.0a ports supporting 4K at 60 Hz | -| | +----------------------+----------------------------------------------+ -| | | System memory | - 8GiB SO-DIMM DDR4 2400 MHz | -| | +----------------------+----------------------------------------------+ -| | | Storage capabilities | - 1TB WDC WD10SPZX-22Z | -+--------------------------+----------------------+----------------------+----------------------------------------------+ -| PC (development machine) | | Processor | - Intel(R) Core(TM) i7-2600 CPU @ 3.40GHz | -| | +----------------------+----------------------------------------------+ -| | | System memory | - 2GiB DIMM DDR3 Synchronous 1333 MHz x 4 | -| | +----------------------+----------------------------------------------+ -| | | Storage capabilities | - 1TB WDC WD10JPLX-00M | -+--------------------------+----------------------+----------------------+----------------------------------------------+ - - - -Validated Versions -================== - -- **Ubuntu version:** 18.04 -- **ACRN hypervisor tag:** v2.2 -- **Service VM Kernel version:** v2.2 - -.. _build-the-ubuntu-kvm-image: - -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: - -#. Install Ubuntu via the virt-manager tool: - - .. code-block:: none - - $ sudo virt-manager - -#. Verify that you can see the main menu as shown in the figure below. - - .. figure:: images/ubuntu-uservm-1.png - :align: center - :name: vmmanager-ubun - - Virtual Machine Manager - -#. Right-click **QEMU/KVM** and select **New**. - - a. Choose **Local install media (ISO image or CD-ROM)** and then click - **Forward**. A **Create a new virtual machine** box displays, as shown - in the figure below. - - .. figure:: images/ubuntu-uservm-2.png - :align: center - :name: newVM-ubun - - Create a New Virtual Machine - - #. Choose **Use ISO image** and click **Browse** - **Browse Local**. - Select the ISO that you get from Step 2 above. - - #. Choose the **OS type:** Linux, **Version:** Ubuntu 18.04 LTS and then click **Forward**. - - #. Select **Forward** if you do not need to make customized CPU settings. - - #. Choose **Create a disk image for virtual machine**. Set the - storage to 20 GB or more if necessary and click **Forward**. - - #. 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 the figure - below: - - .. figure:: images/ubuntu-uservm-3.png - :align: center - :name: ubun-setup - - Debian Setup Overview - -#. Complete the Ubuntu installation. Verify that you have set up the disk partition as follows: - - - /dev/vda1: EFI System Partition - - /dev/vda2: File System Partition - -#. 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**: - - .. code-block:: none - - $ cd ~ && mkdir ubuntu_images && cd ubuntu_images - $ sudo qemu-img convert -f qcow2 -O raw /var/lib/libvirt/images/ubuntu18.04.qcow2 uos.img - -Launch the Ubuntu Image 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 an SSD. - -1. Copy the ``uos.img`` to your Intel NUC: - - .. code-block:: none - - # scp ~/ubuntu_images/uos.img user_name@ip_address:~/uos.img - -#. Log in to the ACRN Service VM, and create a launch script from the existing script: - - .. code-block:: none - - $ cd ~ - $ cp /usr/share/acrn/samples/nuc/launch_win.sh ./launch_ubuntu.sh - $ sed -i "s/win10-ltsc.img/uos.img/" launch_ubuntu.sh - -#. Assign USB ports to the Ubuntu VM in order to use the mouse and keyboard before the launch: - - .. code-block:: none - - $ vim launch_ubuntu.sh - - - -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 this instead:: - - -s 7,xhci,1-2:1-3 \ - - Refer to :ref:`acrn-dm_parameters` for ACRN for more information. - -#. Launch the Ubuntu VM after logging in to the Service VM: - - .. code-block:: none - - $ sudo sh launch_ubuntu.sh - -#. View the Ubuntu desktop on the secondary monitor, as shown in the figure - below: - - .. figure:: images/ubuntu-uservm-4.png - :align: center - :name: ubun-display1 - - The Ubuntu desktop on the secondary monitor - -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. - -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: - - .. code-block:: none - - $ sudo vim /etc/default/grub - - GRUB_CMDLINE_LINUX="console=ttyS0,115200" - $ sudo update-grub - $ sudo poweroff - -#. Modify the launch script to enable ``virtio-console`` for the Ubuntu VM: - - .. code-block:: none - - $ vim ~/launch_ubuntu.sh - - -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 the figure below: - - .. figure:: images/ubuntu-uservm-5.png - :align: center - :name: console output-ubun - - Ubuntu VM console output diff --git a/doc/tutorials/using_yp.rst b/doc/tutorials/using_yp.rst deleted file mode 100644 index d6da75beb..000000000 --- a/doc/tutorials/using_yp.rst +++ /dev/null @@ -1,43 +0,0 @@ -:orphan: - -.. _using_yp: - -Using Yocto Project With ACRN -############################# - -The `Yocto Project `_ (YP) is an open source -collaboration project that helps developers create custom Linux-based -systems. The project provides a flexible set of tools and a space where -embedded developers worldwide can share technologies, software stacks, -configurations, and best practices used to create tailored Linux images -for embedded and IoT devices, or anywhere a customized Linux OS is -needed. - -Yocto Project layers support the inclusion of technologies, hardware -components, and software components. Layers are repositories containing -related sets of instructions that tell the Yocto Project build system -what to do. - -The meta-acrn Layer -******************* - -The meta-acrn layer integrates the ACRN hypervisor with OpenEmbedded, -letting you build your Service VM or Guest VM OS with the Yocto Project. -The `OpenEmbedded Layer Index's meta-acrn entry -`_ -tracks work on this meta-acrn layer and lists the available meta-acrn -recipes including Service and User VM OSs for Linux Kernel 4.19 and 5.4 -with the ACRN hypervisor enabled. - -Read more about the meta-acrn layer and how to use it, directly from the -`meta-acrn GitHub repo documentation -`_: - -* `Getting Started guide - `_ -* `Booting ACRN with Slim Bootloader - `_ -* `Testing Procedure - `_ -* `References - `_