OrgACRN
/
acrn-hypervisor
mirror of https://github.com/projectacrn/acrn-hypervisor.git
1
0
Fork 0
Code Issues Releases Wiki Activity

doc: remove obsolete (and orphaned) docs 

We removed some documentation from the table of contents but left them
around in the published documentation.  All of these documents are
obsolete and haven't been updated since they were last validated on
earlier versions of ACRN.  (They all can still be referenced in the
older version archives if needed.)

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2022-05-03 09:57:51 -07:00 committed by David Kinder
parent ca3251a47d
commit e491773f5e
6 changed files with 0 additions and 717 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/getting-started/roscube/roscube-gsg.rst
View File

@ -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
<https://projectacrn.github.io/2.5/getting-started/roscube/roscube-gsg.html>`_
for the latest instructions.

15
doc/learn.rst
View File

@ -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

158
doc/tutorials/running_deb_as_serv_vm.rst
View File

@ -1,158 +0,0 @@
:orphan:
.. _running_deb_as_serv_vm:
Run Debian as the Service VM
############################
The `Debian Project <https://www.debian.org/>`_ is an association of
individuals who have made common cause to create a `free
<https://www.debian.org/intro/free>`_ operating system. The `latest
stable Debian release <https://www.debian.org/releases/stable/>`_ 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
<https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/>`_.
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
<https://www.debian.org/releases/stable/amd64/index.en.html>`_ 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 <https://github.com/projectacrn/acrn-hypervisor>`_ 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 <device node>``.
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

260
doc/tutorials/running_deb_as_user_vm.rst
View File

@ -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
<http://releases.ubuntu.com/18.04.3/ubuntu-18.04.3-desktop-amd64.iso?_ga=2.160010942.221344839.1566963570-491064742.1554370503>`_
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
<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 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
<Add console=ttyS0,115200>
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
<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 the figure below:
.. figure:: images/debian-uservm-7.png
:align: center
:name: console output-debian
Debian VM console output

230
doc/tutorials/running_ubun_as_user_vm.rst
View File

@ -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
<http://releases.ubuntu.com/18.04.3/ubuntu-18.04.3-desktop-amd64.iso?_ga=2.160010942.221344839.1566963570-491064742.1554370503>`_
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
<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:
.. 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
<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 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
<Add console=ttyS0,115200>
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
<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 the figure below:
.. figure:: images/ubuntu-uservm-5.png
:align: center
:name: console output-ubun
Ubuntu VM console output

43
doc/tutorials/using_yp.rst
View File

@ -1,43 +0,0 @@
:orphan:
.. _using_yp:
Using Yocto Project With ACRN
#############################
The `Yocto Project <https://yoctoproject.org>`_ (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
<http://layers.openembedded.org/layerindex/branch/master/layer/meta-acrn/>`_
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
<https://github.com/intel/meta-acrn/tree/master/docs>`_:
* `Getting Started guide
<https://github.com/intel/meta-acrn/blob/master/docs/getting-started.md>`_
* `Booting ACRN with Slim Bootloader
<https://github.com/intel/meta-acrn/blob/master/docs/slimbootloader.md>`_
* `Testing Procedure
<https://github.com/intel/meta-acrn/blob/master/docs/qa.md>`_
* `References
<https://github.com/intel/meta-acrn/blob/master/docs/references.md>`_