github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-22 13:37:10 +00:00
Code Issues Projects Releases Wiki Activity

doc: Update Getting Started Guide

Browse Source 
- Update to Ubuntu 20.04
- Add Debian pkg usage.
- Modify mem parameter in launch xml to 1024M.

Signed-off-by: Reyes, Amy <amy.reyes@intel.com>
This commit is contained in:
Reyes, Amy 2022-03-14 11:12:48 -07:00 committed by David Kinder
parent cfcea64976
commit 4eb14e7a0d
6 changed files with 212 additions and 368 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

580
doc/getting-started/getting-started.rst
View File

@ -8,9 +8,8 @@ Getting Started Guide
This guide will help you get started with ACRN. We'll show how to prepare a This guide will help you get started with ACRN. We'll show how to prepare a
build environment on your development computer. Then we'll walk through the build environment on your development computer. Then we'll walk through the
steps to set up a simple ACRN configuration on a target system. The steps to set up a simple ACRN configuration on a target system. The
configuration is based on the ACRN predefined **shared** scenario and consists configuration is an ACRN shared scenario and consists of an ACRN hypervisor,
of an ACRN hypervisor, Service VM, and six User VMs, but we'll launch only one Service VM, and one post-launched User VM as illustrated in this figure:
User VM, as illustrated in this figure:
.. image:: ./images/gsg_scenario-1-0.75x.png .. image:: ./images/gsg_scenario-1-0.75x.png
@ -37,32 +36,32 @@ Before you begin, make sure your machines have the following prerequisites:
* Software specifications * Software specifications
- Ubuntu Desktop 18.04 or newer - Ubuntu Desktop 20.04 LTS (ACRN development is not supported on Windows.)
(ACRN development is not supported on Windows.)
**Target system**: **Target system**:
* Hardware specifications * Hardware specifications
- Target board (see :ref:`hardware_tested`) - Target board (see :ref:`hardware_tested`)
- Ubuntu 18.04 Desktop bootable USB disk: download the `Ubuntu 18.04.05 - Ubuntu Desktop 20.04 LTS bootable USB disk: download the latest `Ubuntu
Desktop ISO image <https://releases.ubuntu.com/18.04.5/>`_ and follow the Desktop 20.04 LTS ISO image <https://releases.ubuntu.com/focal/>`__ and
`Ubuntu documentation follow the `Ubuntu documentation
<https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu#1-overview>`__ <https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu#1-overview>`__
for creating the USB disk. for creating the USB disk.
- USB keyboard and mouse - USB keyboard and mouse
- Monitor - Monitor
- Ethernet cable and Internet access - Ethernet cable and Internet access
- A second USB disk with minimum 1GB capacity to copy files between the - A second USB disk with minimum 1GB capacity to copy files between the
development computer and target system development computer and target system (this guide offers steps for
copying via USB disk, but you can use another method if you prefer)
- Local storage device (NVMe or SATA drive, for example) - Local storage device (NVMe or SATA drive, for example)
.. rst-class:: numbered-step .. rst-class:: numbered-step
Set Up the Hardware Set Up the Target Hardware
******************* **************************
To set up the hardware environment: To set up the target hardware environment:
#. Connect the mouse, keyboard, monitor, and power supply cable to the target #. Connect the mouse, keyboard, monitor, and power supply cable to the target
system. system.
@ -82,7 +81,7 @@ Prepare the Development Computer
To set up the ACRN build environment on the development computer: To set up the ACRN build environment on the development computer:
#. On the development computer, run the following command to confirm that Ubuntu #. On the development computer, run the following command to confirm that Ubuntu
Desktop 18.04 or newer is running: Desktop 20.04 is running:
.. code-block:: bash .. code-block:: bash
@ -92,13 +91,18 @@ To set up the ACRN build environment on the development computer:
<https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview>`__ to <https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview>`__ to
install a new OS on the development computer. install a new OS on the development computer.
#. Update Ubuntu with any outstanding patches: #. Download the information database about all available package updates for
your Ubuntu release. We'll need it to get the latest tools and libraries used
for ACRN builds:
.. code-block:: bash .. code-block:: bash
sudo apt update sudo apt update
Followed by: This next command upgrades packages already installed on your system with
minor updates and security patches. This command is optional as there is a
small risk that upgrading your system software can introduce unexpected
issues:
.. code-block:: bash .. code-block:: bash
@ -126,20 +130,13 @@ To set up the ACRN build environment on the development computer:
e2fslibs-dev \ e2fslibs-dev \
pkg-config \ pkg-config \
libnuma-dev \ libnuma-dev \
libcjson-dev \
liblz4-tool \ liblz4-tool \
flex \ flex \
bison \ bison \
xsltproc \ xsltproc \
clang-format \ clang-format \
bc bc
.. note:: You need to follow these steps if you are on Ubuntu 18.04 as ``libcjson-dev`` is not available in the default repositories.
.. code-block:: bash
sudo add-apt-repository ppa:jrtc27/cjson
sudo apt-get update
sudo apt install libcjson-dev
#. Install Python package dependencies: #. Install Python package dependencies:
@ -160,7 +157,7 @@ To set up the ACRN build environment on the development computer:
make clean && make iasl make clean && make iasl
sudo cp ./generate/unix/bin/iasl /usr/sbin sudo cp ./generate/unix/bin/iasl /usr/sbin
#. Get the ACRN hypervisor and kernel source code. (Because the acrn-kernel repo #. Get the ACRN hypervisor and kernel source code. (Because the ``acrn-kernel`` repo
has a lot of Linux kernel history, you can clone the relevant release branch has a lot of Linux kernel history, you can clone the relevant release branch
with minimal history, as shown here.) with minimal history, as shown here.)
@ -181,26 +178,27 @@ To set up the ACRN build environment on the development computer:
Prepare the Target and Generate a Board Configuration File Prepare the Target and Generate a Board Configuration File
*************************************************************** ***************************************************************
In this step, you will use the **Board Inspector** to generate a board
configuration file.
A **board configuration file** is an XML file that stores hardware-specific A **board configuration file** is an XML file that stores hardware-specific
information extracted from the target system. The file is used to configure the information extracted from the target system. The file is used to configure the
ACRN hypervisor, because each hypervisor instance is specific to your target ACRN hypervisor, because each hypervisor instance is specific to your target
hardware. hardware.
You use the **Board Inspector tool** to generate the board
configuration file.
.. important:: .. important::
Whenever you change the configuration of the board, such as BIOS settings, Whenever you change the configuration of the board, such as peripherals, BIOS
additional memory, or PCI devices, you must settings, additional memory, or PCI devices, you must generate a new board
generate a new board configuration file. configuration file.
Install OS on the Target Install OS on the Target
============================ ============================
The target system needs Ubuntu 18.04 to run the Board Inspector tool. The target system needs Ubuntu Desktop 20.04 LTS to run the Board Inspector
tool.
To install Ubuntu 18.04: To install Ubuntu 20.04:
#. Insert the Ubuntu bootable USB disk into the target system. #. Insert the Ubuntu bootable USB disk into the target system.
@ -220,8 +218,7 @@ To install Ubuntu 18.04:
another operating system, or delete your existing operating system and another operating system, or delete your existing operating system and
replace it with Ubuntu: replace it with Ubuntu:
.. image:: ./images/gsg_ubuntu_install_02.jpg .. image:: ./images/gsg_ubuntu_install_02.png
:scale: 85%
#. Complete the Ubuntu installation and create a new user account ``acrn`` and #. Complete the Ubuntu installation and create a new user account ``acrn`` and
set a password. set a password.
@ -248,110 +245,97 @@ Configure Target BIOS Settings
The names and locations of the BIOS settings differ depending on the target The names and locations of the BIOS settings differ depending on the target
hardware and BIOS version. hardware and BIOS version.
#. Set other BIOS settings, such as Hyper-Threading, depending on the needs
of your application.
Generate a Board Configuration File Generate a Board Configuration File
========================================= =========================================
#. On the target system, install the Board Inspector dependencies: #. Build the Board Inspector Debian package on the development computer:
.. code-block:: bash
sudo apt install -y cpuid msr-tools pciutils dmidecode python3 python3-pip
#. Install the Python package dependencies:
.. code-block:: bash
sudo pip3 install lxml
#. Configure the GRUB kernel command line as follows:
a. Edit the ``grub`` file. The following command uses ``vi``, but you
can use any text editor.
.. code-block:: bash
sudo vi /etc/default/grub
#. Find the line starting with ``GRUB_CMDLINE_LINUX_DEFAULT`` and append:
.. code-block:: bash
idle=nomwait iomem=relaxed intel_idle.max_cstate=0 intel_pstate=disable
Example:
.. code-block:: bash
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash idle=nomwait iomem=relaxed intel_idle.max_cstate=0 intel_pstate=disable"
These settings allow the Board Inspector tool to
gather important information about the board.
#. Save and close the file.
#. Update GRUB and reboot the system:
.. code-block:: bash
sudo update-grub
reboot
#. Copy the Board Inspector tool folder from the development computer to the
target via USB disk as follows:
a. Move to the development computer. a. Move to the development computer.
#. On the development computer, insert the USB disk that you intend to #. On the development computer, go to the ``acrn-hypervisor`` directory:
use to copy files.
#. Ensure that there is only one USB disk inserted by running the .. code-block:: bash
following command:
cd ~/acrn-work/acrn-hypervisor
#. Build the Board Inspector Debian package:
.. code-block:: bash
make clean && make board_inspector
When done, the build generates a Debian package in the ``./build``
directory.
#. Copy the Board Inspector Debian package from the development computer to the
target system via USB disk as follows:
a. On the development computer, insert the USB disk that you intend to use to
copy files.
#. Ensure that there is only one USB disk inserted by running the following
command:
.. code-block:: bash .. code-block:: bash
ls /media/$USER ls /media/$USER
Confirm that only one disk name appears. You'll use that disk name in Confirm that only one disk name appears. You'll use that disk name in the following steps.
the following steps.
#. Copy the Board Inspector tool folder from the acrn-hypervisor source code to the USB disk: #. Copy the Board Inspector Debian package to the USB disk:
.. code-block:: bash .. code-block:: bash
cd ~/acrn-work/ cd ~/acrn-work/
disk="/media/$USER/"$(ls /media/$USER) disk="/media/$USER/"$(ls /media/$USER)
cp -r acrn-hypervisor/misc/config_tools/board_inspector/ "$disk"/ cp -r acrn-hypervisor/build/acrn-board-inspector*.deb "$disk"/
sync && sudo umount "$disk" sync && sudo umount "$disk"
#. Insert the USB disk into the target system. #. Insert the USB disk into the target system.
#. Copy the Board Inspector tool from the USB disk to the target: #. Copy the Board Inspector Debian package from the USB disk to the target:
.. code-block:: bash .. code-block:: bash
mkdir -p ~/acrn-work mkdir -p ~/acrn-work
disk="/media/$USER/"$(ls /media/$USER) disk="/media/$USER/"$(ls /media/$USER)
cp -r "$disk"/board_inspector ~/acrn-work cp -r "$disk"/acrn-board-inspector*.deb ~/acrn-work
#. Run the Board Inspector tool ( ``board_inspector.py``) #. Install the Board Inspector Debian package on the target system:
to generate the board configuration file. This
.. code-block:: bash
cd ~/acrn-work
sudo apt install ./acrn-board-inspector*.deb
#. Reboot the system:
.. code-block:: bash
reboot
#. Run the Board Inspector to generate the board configuration file. This
example uses the parameter ``my_board`` as the file name. example uses the parameter ``my_board`` as the file name.
.. code-block:: bash .. code-block:: bash
cd ~/acrn-work/board_inspector/ cd ~/acrn-work
sudo python3 board_inspector.py my_board sudo board_inspector.py my_board
#. Confirm that the board configuration file ``my_board.xml`` was generated .. note::
in the current directory::
If you get an error that mentions Pstate and editing the GRUB
configuration, reboot the system and run this command again.
#. Confirm that the board configuration file ``my_board.xml`` was generated in
the current directory:
.. code-block:: bash
ls ./my_board.xml ls ./my_board.xml
#. Copy ``my_board.xml`` from the target to the development computer #. Copy ``my_board.xml`` from the target to the development computer via USB
via USB disk as follows: disk as follows:
a. Make sure the USB disk is connected to the target. a. Make sure the USB disk is connected to the target.
@ -360,7 +344,7 @@ Generate a Board Configuration File
.. code-block:: bash .. code-block:: bash
disk="/media/$USER/"$(ls /media/$USER) disk="/media/$USER/"$(ls /media/$USER)
cp ~/acrn-work/board_inspector/my_board.xml "$disk"/ cp ~/acrn-work/my_board.xml "$disk"/
sync && sudo umount "$disk" sync && sudo umount "$disk"
#. Insert the USB disk into the development computer. #. Insert the USB disk into the development computer.
@ -371,17 +355,17 @@ Generate a Board Configuration File
disk="/media/$USER/"$(ls /media/$USER) disk="/media/$USER/"$(ls /media/$USER)
cp "$disk"/my_board.xml ~/acrn-work cp "$disk"/my_board.xml ~/acrn-work
sudo umount "$disk" sync && sudo umount "$disk"
.. _gsg-dev-setup: .. _gsg-dev-setup:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Generate a Scenario Configuration File and Launch Scripts Generate a Scenario Configuration File and Launch Script
********************************************************* ********************************************************
You use the **ACRN Configurator** to generate scenario configuration files and In this step, you will use the **ACRN Configurator** to generate a scenario
launch scripts. configuration file and launch script.
A **scenario configuration file** is an XML file that holds the parameters of A **scenario configuration file** is an XML file that holds the parameters of
a specific ACRN configuration, such as the number of VMs that can be run, a specific ACRN configuration, such as the number of VMs that can be run,
@ -390,7 +374,7 @@ their attributes, and the resources they have access to.
A **launch script** is a shell script that is used to configure and create a A **launch script** is a shell script that is used to configure and create a
post-launched User VM. Each User VM has its own launch script. post-launched User VM. Each User VM has its own launch script.
To generate a scenario configuration file and launch scripts: To generate a scenario configuration file and launch script:
#. On the development computer, install ACRN Configurator dependencies: #. On the development computer, install ACRN Configurator dependencies:
@ -403,7 +387,7 @@ To generate a scenario configuration file and launch scripts:
.. code-block:: bash .. code-block:: bash
./acrn_configurator.py python3 acrn_configurator.py
#. Your web browser should open the website `<http://127.0.0.1:5001/>`__ #. Your web browser should open the website `<http://127.0.0.1:5001/>`__
automatically, or you may need to visit this website manually. automatically, or you may need to visit this website manually.
@ -449,11 +433,7 @@ To generate a scenario configuration file and launch scripts:
.. image:: ./images/gsg_config_scenario_save.png .. image:: ./images/gsg_config_scenario_save.png
:class: drop-shadow :class: drop-shadow
#. Confirm that ``shared.xml`` appears in your ``acrn-work`` directory:: #. Generate the launch script:
ls ~/acrn-work/shared.xml
#. Generate the launch scripts:
a. Click the **Launch Settings** menu on the top banner of the UI and select a. Click the **Launch Settings** menu on the top banner of the UI and select
**Load a default launch script**. **Load a default launch script**.
@ -469,6 +449,22 @@ To generate a scenario configuration file and launch scripts:
.. image:: ./images/gsg_config_launch_load.png .. image:: ./images/gsg_config_launch_load.png
:class: drop-shadow :class: drop-shadow
Of the six User VMs, we will use User VM 3 and modify its default settings to run Ubuntu 20.04.
#. Scroll down, find **User VM 3**, and change the **mem_size** to **1024**.
Ubuntu 20.04 needs at least 1024 megabytes of memory to boot.
.. image:: ./images/gsg_config_mem.png
:class: drop-shadow
#. Under virtio_devices, change the **block** to
**/home/acrn/acrn-work/ubuntu-20.04.4-desktop-amd64.iso**. The parameter
specifies the VM's OS image and its location on the target system. Later
in this guide, you will save the ISO file to that directory.
.. image:: ./images/gsg_config_blk.png
:class: drop-shadow
#. Click the **Generate Launch Script** button. #. Click the **Generate Launch Script** button.
.. image:: ./images/gsg_config_launch_generate.png .. image:: ./images/gsg_config_launch_generate.png
@ -481,14 +477,19 @@ To generate a scenario configuration file and launch scripts:
.. image:: ./images/gsg_config_launch_save.png .. image:: ./images/gsg_config_launch_save.png
:class: drop-shadow :class: drop-shadow
#. Confirm that ``launch_user_vm_id3.sh`` appears in the expected output
directory::
ls ~/acrn-work/my_board/output/launch_user_vm_id3.sh
#. Close the browser and press :kbd:`CTRL` + :kbd:`C` to terminate the #. Close the browser and press :kbd:`CTRL` + :kbd:`C` to terminate the
``acrn_configurator.py`` program running in the terminal window. ``acrn_configurator.py`` program running in the terminal window.
#. Confirm that the scenario configuration file ``shared.xml`` appears in your
``acrn-work`` directory::
ls ~/acrn-work/shared.xml
#. Confirm that the launch script ``launch_user_vm_id3.sh`` appears in the
expected output directory::
ls ~/acrn-work/my_board/output/launch_user_vm_id3.sh
.. _gsg_build: .. _gsg_build:
.. rst-class:: numbered-step .. rst-class:: numbered-step
@ -501,24 +502,52 @@ Build ACRN
.. code-block:: bash .. code-block:: bash
cd ~/acrn-work/acrn-hypervisor cd ~/acrn-work/acrn-hypervisor
make -j $(nproc) BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml make clean && make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml
make targz-pkg
The build typically takes a few minutes. By default, the build results are The build typically takes a few minutes. When done, the build generates a
found in the build directory. For convenience, we also built a compressed tar Debian package in the ``./build`` directory:
file to ease copying files to the target.
#. Build the ACRN kernel for the Service VM:
.. code-block:: bash .. code-block:: bash
cd ~/acrn-work/acrn-kernel cd ./build
cp kernel_config_service_vm .config ls *.deb
make olddefconfig acrn-my_board-shared-2.7.deb
make -j $(nproc) targz-pkg
The Debian package contains the ACRN hypervisor and tools to ease installing
ACRN on the target.
#. Build the ACRN kernel for the Service VM:
a. If you have built the ACRN kernel before, run the following command to
remove all artifacts from the previous build. Otherwise, an error will
occur during the build.
.. code-block:: bash
make distclean
#. Build the ACRN kernel:
.. code-block:: bash
cd ~/acrn-work/acrn-kernel
cp kernel_config_service_vm .config
make olddefconfig
make -j $(nproc) deb-pkg
The kernel build can take 15 minutes or less on a fast computer, but could The kernel build can take 15 minutes or less on a fast computer, but could
take an hour or more depending on the performance of your development computer. take an hour or more depending on the performance of your development
computer. When done, the build generates four Debian packages in the
directory above the build root directory:
.. code-block:: bash
cd ..
ls *.deb
linux-headers-5.10.78-acrn-service-vm_5.10.78-acrn-service-vm-1_amd64.deb
linux-image-5.10.78-acrn-service-vm_5.10.78-acrn-service-vm-1_amd64.deb
linux-image-5.10.78-acrn-service-vm-dbg_5.10.78-acrn-service-vm-1_amd64.deb
linux-libc-dev_5.10.78-acrn-service-vm-1_amd64.deb
#. Copy all the necessary files generated on the development computer to the #. Copy all the necessary files generated on the development computer to the
target system by USB disk as follows: target system by USB disk as follows:
@ -528,208 +557,59 @@ Build ACRN
.. code-block:: bash .. code-block:: bash
disk="/media/$USER/"$(ls /media/$USER) disk="/media/$USER/"$(ls /media/$USER)
cp linux-5.10.65-acrn-service-vm-x86.tar.gz "$disk"/ cp ~/acrn-work/acrn-hypervisor/build/acrn-my_board-shared-2.7.deb "$disk"/
cp ~/acrn-work/acrn-hypervisor/build/hypervisor/acrn.bin "$disk"/ cp ~/acrn-work/*acrn-service-vm*.deb "$disk"/
cp ~/acrn-work/my_board/output/launch_user_vm_id3.sh "$disk"/ cp ~/acrn-work/my_board/output/launch_user_vm_id3.sh "$disk"/
cp ~/acrn-work/acpica-unix-20210105/generate/unix/bin/iasl "$disk"/ cp ~/acrn-work/acpica-unix-20210105/generate/unix/bin/iasl "$disk"/
cp ~/acrn-work/acrn-hypervisor/build/acrn-2.7-unstable.tar.gz "$disk"/ sync && sudo umount "$disk"
sync && sudo umount "$disk"/
Even though our sample default scenario defines six User VMs, we're only Even though our sample default scenario defines six User VMs, we're only
going to launch one of them, so we'll only need the one launch script. going to launch one of them, so we'll only need the one launch script.
.. note:: The :file:`serial.conf` is only generated if non-standard
vUARTs (not COM1-COM4)
are configured for the Service VM in the scenario XML file.
Please copy the ``serial.conf`` file using::
cp ~/acrn-work/acrn-hypervisor/build/hypervisor/serial.conf "$disk"/
#. Insert the USB disk you just used into the target system and run these #. Insert the USB disk you just used into the target system and run these
commands to copy the tar files locally: commands to copy the files locally:
.. code-block:: bash .. code-block:: bash
disk="/media/$USER/"$(ls /media/$USER) disk="/media/$USER/"$(ls /media/$USER)
cp "$disk"/linux-5.10.65-acrn-service-vm-x86.tar.gz ~/acrn-work cp "$disk"/acrn-my_board-shared-2.7.deb ~/acrn-work
cp "$disk"/acrn-2.7-unstable.tar.gz ~/acrn-work cp "$disk"/*acrn-service-vm*.deb ~/acrn-work
#. Extract the Service VM files onto the target system:
.. code-block:: bash
cd ~/acrn-work
sudo tar -zxvf linux-5.10.65-acrn-service-vm-x86.tar.gz -C / --keep-directory-symlink
This tar extraction replaces parts of the Ubuntu installation we installed
and used for running the Board Inspector, with the Linux kernel we built
based on the board and scenario configuration.
#. Extract the ACRN tools and images:
.. code-block:: bash
sudo tar -zxvf acrn-2.7-unstable.tar.gz -C / --keep-directory-symlink
#. Copy a few additional ACRN files to the expected locations:
.. code-block:: bash
sudo mkdir -p /boot/acrn/
sudo cp "$disk"/acrn.bin /boot/acrn
sudo cp "$disk"/serial.conf /etc
sudo cp "$disk"/iasl /usr/sbin/
cp "$disk"/launch_user_vm_id3.sh ~/acrn-work cp "$disk"/launch_user_vm_id3.sh ~/acrn-work
sudo umount "$disk"/ sudo cp "$disk"/iasl /usr/sbin/
sync && sudo umount "$disk"
.. rst-class:: numbered-step .. rst-class:: numbered-step
Install ACRN Install ACRN
************ ************
In the following steps, you will install the serial configuration tool and #. Install the ACRN Debian package and ACRN kernel Debian packages using these
configure GRUB on the target system. commands:
#. Install the serial configuration tool in the target system as follows:
.. code-block:: bash .. code-block:: bash
sudo apt install setserial cd ~/acrn-work
sudo apt install ./acrn-my_board-shared-2.7.deb
sudo apt install ./*acrn-service-vm*.deb
#. On the target, find the root filesystem (rootfs) device name by using the #. Reboot the system:
``lsblk`` command:
.. code-block:: console
:emphasize-lines: 24
~$ lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
loop0 7:0 0 255.6M 1 loop /snap/gnome-3-34-1804/36
loop1 7:1 0 62.1M 1 loop /snap/gtk-common-themes/1506
loop2 7:2 0 2.5M 1 loop /snap/gnome-calculator/884
loop3 7:3 0 241.4M 1 loop /snap/gnome-3-38-2004/70
loop4 7:4 0 61.8M 1 loop /snap/core20/1081
loop5 7:5 0 956K 1 loop /snap/gnome-logs/100
loop6 7:6 0 2.2M 1 loop /snap/gnome-system-monitor/148
loop7 7:7 0 2.4M 1 loop /snap/gnome-calculator/748
loop8 7:8 0 29.9M 1 loop /snap/snapd/8542
loop9 7:9 0 32.3M 1 loop /snap/snapd/12704
loop10 7:10 0 65.1M 1 loop /snap/gtk-common-themes/1515
loop11 7:11 0 219M 1 loop /snap/gnome-3-34-1804/72
loop12 7:12 0 55.4M 1 loop /snap/core18/2128
loop13 7:13 0 55.5M 1 loop /snap/core18/2074
loop14 7:14 0 2.5M 1 loop /snap/gnome-system-monitor/163
loop15 7:15 0 704K 1 loop /snap/gnome-characters/726
loop16 7:16 0 276K 1 loop /snap/gnome-characters/550
loop17 7:17 0 548K 1 loop /snap/gnome-logs/106
loop18 7:18 0 243.9M 1 loop /snap/gnome-3-38-2004/39
nvme0n1 259:0 0 119.2G 0 disk
├─nvme0n1p1 259:1 0 512M 0 part /boot/efi
└─nvme0n1p2 259:2 0 118.8G 0 part /
As highlighted, you're looking for the device name associated with the
partition named ``/``, in this case ``nvme0n1p2``.
#. Run the ``blkid`` command to get the UUID and PARTUUID for the rootfs device
(replace the ``nvme0n1p2`` name with the name shown for the rootfs on your
system):
.. code-block:: bash .. code-block:: bash
sudo blkid /dev/nvme0n1p2
In the output, look for the UUID and PARTUUID (example below). You will need
them in the next step.
.. code-block:: console
/dev/nvme0n1p2: UUID="3cac5675-e329-4cal-b346-0a3e65f99016" TYPE="ext4" PARTUUID="03db7f45-8a6c-454b-adf7-30343d82c4f4"
#. Add the ACRN Service VM to the GRUB boot menu:
a. Edit the GRUB ``40_custom`` file. The following command uses ``vi``, but
you can use any text editor.
.. code-block:: bash
sudo vi /etc/grub.d/40_custom
#. Add the following text at the end of the file. Replace ``UUID`` and
``PARTUUID`` with the output from the previous step.
.. code-block:: bash
:emphasize-lines: 6,8
menuentry "ACRN Multiboot Ubuntu Service VM" --id ubuntu-service-vm {
load_video
insmod gzio
insmod part_gpt
insmod ext2
search --no-floppy --fs-uuid --set "UUID"
echo 'loading ACRN...'
multiboot2 /boot/acrn/acrn.bin root=PARTUUID="PARTUUID"
module2 /boot/vmlinuz-5.10.65-acrn-service-vm Linux_bzImage
}
Example:
.. code-block:: console
menuentry "ACRN Multiboot Ubuntu Service VM" --id ubuntu-service-vm {
load_video
insmod gzio
insmod part_gpt
insmod ext2
search --no-floppy --fs-uuid --set "3cac5675-e329-4cal-b346-0a3e65f99016"
echo 'loading ACRN...'
multiboot2 /boot/acrn/acrn.bin root=PARTUUID="03db7f45-8a6c-454b-adf7-30343d82c4f4"
module2 /boot/vmlinuz-5.10.65-acrn-service-vm Linux_bzImage
}
#. Save and close the file.
#. Make the GRUB menu visible when
booting and make it load the Service VM kernel by default:
a. Edit the ``grub`` file:
.. code-block:: bash
sudo vi /etc/default/grub
#. Edit lines with these settings (comment out the ``GRUB_TIMEOUT_STYLE`` line).
Leave other lines as they are:
.. code-block:: bash
GRUB_DEFAULT=ubuntu-service-vm
#GRUB_TIMEOUT_STYLE=hidden
GRUB_TIMEOUT=5
#. Save and close the file.
#. Update GRUB and reboot the system:
.. code-block:: bash
sudo update-grub
reboot reboot
#. Confirm that you see the GRUB menu with the "ACRN Multiboot Ubuntu Service #. Confirm that you see the GRUB menu with the “ACRN multiboot2” entry. Select
VM" entry. Select it and proceed to booting ACRN. (It may be autoselected, in it and proceed to booting ACRN. (It may be autoselected, in which case it
which case it will boot with this option automatically in 5 seconds.) will boot with this option automatically in 5 seconds.)
.. code-block:: console .. code-block:: console
:emphasize-lines: 8
GNU GRUB version 2.04 GNU GRUB version 2.04
──────────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────────────
Ubuntu Ubuntu
Advanced options for Ubuntu Advanced options for Ubuntu
Ubuntu 18.04.05 LTS (18.04) (on /dev/nvme0n1p2) UEFI Firmware Settings
Advanced options for Ubuntu 18.04.05 LTS (18.04) (on /dev/nvme0n1p2) *ACRN multiboot2
System setup
*ACRN Multiboot Ubuntu Service VM
.. rst-class:: numbered-step .. rst-class:: numbered-step
@ -741,12 +621,12 @@ The ACRN hypervisor boots the Ubuntu Service VM automatically.
#. On the target, log in to the Service VM. (It will look like a normal Ubuntu #. On the target, log in to the Service VM. (It will look like a normal Ubuntu
session.) session.)
#. Verify that the hypervisor is running by checking ``dmesg`` in #. Verify that the hypervisor is running by checking ``dmesg`` in the Service
the Service VM: VM:
.. code-block:: bash .. code-block:: bash
dmesg | grep ACRN dmesg | grep -i hypervisor
You should see "Hypervisor detected: ACRN" in the output. Example output of a You should see "Hypervisor detected: ACRN" in the output. Example output of a
successful installation (yours may look slightly different): successful installation (yours may look slightly different):
@ -754,96 +634,44 @@ The ACRN hypervisor boots the Ubuntu Service VM automatically.
.. code-block:: console .. code-block:: console
[ 0.000000] Hypervisor detected: ACRN [ 0.000000] Hypervisor detected: ACRN
[ 3.875620] ACRNTrace: Initialized acrn trace module with 4 cpu
.. rst-class:: numbered-step .. rst-class:: numbered-step
Launch the User VM Launch the User VM
******************* *******************
#. A User VM image is required on the target system before launching it. The #. Go to the `official Ubuntu website <https://releases.ubuntu.com/focal/>`__ to
following steps use Ubuntu: get the Ubuntu Desktop 20.04 LTS ISO image
``ubuntu-20.04.4-desktop-amd64.iso`` for the User VM. (The same image you
specified earlier in the ACRN Configurator UI.)
a. Go to the `official Ubuntu website #. Put the ISO file in the path ``~/acrn-work/`` on the target system.
<https://releases.ubuntu.com/bionic>`__ to get an ISO format of the Ubuntu
18.04 desktop image.
#. Put the ISO file in the path ``~/acrn-work/`` on the target system.
#. Even though our sample default scenario defines six User VMs, we're only
going to launch one of them.
Open the launch script in a text editor. The following command uses ``vi``, but
you can use any text editor.
.. code-block:: bash
vi ~/acrn-work/launch_user_vm_id3.sh
#. Look for the line that contains the term ``virtio-blk`` and replace the
existing image file path with your ISO image file path. In the following
example, the ISO image file path is
``/home/acrn/acrn-work/ubuntu-18.04.6-desktop-amd64.iso``. Here is the
``launch_user_vm_id3.sh`` before editing:
.. code-block:: bash
:emphasize-lines: 4
acrn-dm -m $mem_size -s 0:0,hostbridge \
--mac_seed $mac_seed \
$logger_setting \
-s 9,virtio-blk,./YaaG.img \
-s 10,virtio-net,tap_YaaG3 \
-s 8,virtio-console,@stdio:stdio_port \
--ovmf /usr/share/acrn/bios/OVMF.fd \
--cpu_affinity 0,1 \
-s 1:0,lpc \
$vm_name
And here is the example ``launch_user_vm_id3.sh`` after editing:
.. code-block:: bash
:emphasize-lines: 4
acrn-dm -m $mem_size -s 0:0,hostbridge \
--mac_seed $mac_seed \
$logger_setting \
-s 9,virtio-blk,/home/acrn/acrn-work/ubuntu-18.04.6-desktop-amd64.iso \
-s 10,virtio-net,tap_YaaG3 \
-s 8,virtio-console,@stdio:stdio_port \
--ovmf /usr/share/acrn/bios/OVMF.fd \
--cpu_affinity 0,1 \
-s 1:0,lpc \
$vm_name
#. Save and close the file.
#. Launch the User VM: #. Launch the User VM:
.. code-block:: bash .. code-block:: bash
sudo chmod +x ~/acrn-work/launch_user_vm_id3.sh sudo chmod +x ~/acrn-work/launch_user_vm_id3.sh
sudo chmod +x /usr/bin/acrn-dm
sudo chmod +x /usr/sbin/iasl
sudo ~/acrn-work/launch_user_vm_id3.sh sudo ~/acrn-work/launch_user_vm_id3.sh
#. It will take a few seconds for the User VM to boot and start running the #. It may take about one minute for the User VM to boot and start running the
Ubuntu image. Confirm that you see the console of the User VM on the Service Ubuntu image. You will see a lot of output, then the console of the User VM
VM's terminal. Example: will appear as follows:
.. code-block:: console .. code-block:: console
Ubuntu 18.04.5 LTS ubuntu hvc0 Ubuntu 20.04.4 LTS ubuntu hvc0
ubuntu login: ubuntu login:
#. Log in to the User VM. For the Ubuntu 18.04 ISO, the user is ``ubuntu``, and #. Log in to the User VM. For the Ubuntu 20.04 ISO, the user is ``ubuntu``, and
there's no password. there's no password.
#. Confirm that you see output similar to this example: #. Confirm that you see output similar to this example:
.. code-block:: console .. code-block:: console
Welcome to Ubuntu 18.04.5 LTS (GNU/Linux 5.4.0-42-generic x86_64) Welcome to Ubuntu 20.04.4 LTS (GNU/Linux 5.11.0-27-generic x86_64)
* Documentation: https://help.ubuntu.com * Documentation: https://help.ubuntu.com
* Management: https://landscape.canonical.com * Management: https://landscape.canonical.com
@ -852,7 +680,7 @@ Launch the User VM
0 packages can be updated. 0 packages can be updated.
0 updates are security updates. 0 updates are security updates.
Your Hardware Enablement Stack (HWE) is supported until April 2023. Your Hardware Enablement Stack (HWE) is supported until April 2025.
The programs included with the Ubuntu system are free software; The programs included with the Ubuntu system are free software;
the exact distribution terms for each program are described in the the exact distribution terms for each program are described in the
@ -866,6 +694,22 @@ Launch the User VM
ubuntu@ubuntu:~$ ubuntu@ubuntu:~$
#. This User VM and the Service VM are running different Ubuntu images. Use this
command to see that the User VM is running the downloaded Ubuntu ISO image:
.. code-block:: console
ubuntu@ubuntu:~$ uname -r
5.11.0-27-generic
Then open a new terminal window and use the command to see that the Service
VM is running the ``acrn-kernel`` Service VM image:
.. code-block:: console
acrn@vecow:~$ uname -r
5.10.78-acrn-service-vm
The User VM has launched successfully. You have completed this ACRN setup. The User VM has launched successfully. You have completed this ACRN setup.
Next Steps Next Steps

BIN
doc/getting-started/images/gsg_config_blk.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
doc/getting-started/images/gsg_config_mem.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
doc/getting-started/images/gsg_ubuntu_install_01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 91 KiB

After

Width:  |  Height:  |  Size: 120 KiB

BIN
doc/getting-started/images/gsg_ubuntu_install_02.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 39 KiB

BIN
doc/getting-started/images/gsg_ubuntu_install_02.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 84 KiB