mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2026-01-06 08:04:55 +00:00
doc: Reorganize documentation site content
Take the existing ACRN technical documentation and reorganize its presentation to be persona and use-case based, in preparation for adding new scenario/use-case based architecture introduction and getting started documents. Introduce a more graphical home page and theme color tweaks. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
committed by
David Kinder
David Kinder
parent
e188e1f245
commit
11d4f4159f
@@ -1,247 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Copyright (C) 2019 Intel Corporation.
|
||||
# SPDX-License-Identifier: BSD-3-Clause
|
||||
#
|
||||
# This script provides a quick and automatic setup of the SOS or UOS.
|
||||
# You should run this script with root privilege since it will modify various system parameters.
|
||||
#
|
||||
# Usages:
|
||||
# Upgrade SOS to 28100 without reboot, it's highly recommended so that you can check configurations after upgrade SOS.
|
||||
# sudo <script> -s 28100 -d
|
||||
# Upgrade SOS to 28100 with specified proxy server
|
||||
# sudo <script> -s 28100 -p <your proxy server>:<port>
|
||||
# Upgrade UOS to 28100 with specified proxy server
|
||||
# sudo <script> -u 28100 -p <your proxy server>:<port>
|
||||
# Upgrade UOS to 28100 without downloading UOS image, you should put UOS image in /root directory previously.
|
||||
# sudo <script> -u 28100 -k
|
||||
|
||||
function print_help()
|
||||
{
|
||||
echo "Usage:"
|
||||
echo "Launch this script as: sudo $0 -s 28100"
|
||||
echo -e "\t-s to upgrade SOS"
|
||||
echo -e "\t-u to upgrade UOS"
|
||||
echo -e "\t-p to specify a proxy server (HTTPS)"
|
||||
echo -e "\t-m to use swupd mirror url"
|
||||
echo -e "\t-k to skip downloading UOS; if enabled, you have to download UOS img firstly before upgrading, default is off"
|
||||
echo -e "\t-d to disable reboot device so that you can check the configurations after upgrading SOS"
|
||||
echo -e "\t-e to specify EFI System Partition (ESP), default: /dev/sda1"
|
||||
echo -e "\n\t<Note>:"
|
||||
echo -e "\tThis script is using /dev/sda1 as default EFI System Partition (ESP)."
|
||||
echo -e "\tThe ESP may be different based on your hardware and then you should specify it directly with '-e' option."
|
||||
echo -e "\tIt will typically be something like /dev/mmcblk0p1 on platforms that have an on-board eMMC"
|
||||
echo -e "\tOr /dev/nvme0n1p1 if your system has a non-volatile storage media attached via a PCI Express (PCIe) bus (NVMe)."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# get clear linux version previously
|
||||
source /etc/os-release
|
||||
# switcher for download UOS function
|
||||
skip_download_uos=0
|
||||
# switcher for disabling reboot device
|
||||
disable_reboot=0
|
||||
|
||||
# acrn.conf path
|
||||
acrn_conf_path=/usr/share/acrn/samples/nuc/acrn.conf
|
||||
# acrn.efi path
|
||||
acrn_efi_path=/usr/lib/acrn/acrn.efi
|
||||
|
||||
function upgrade_sos()
|
||||
{
|
||||
# Check SOS version
|
||||
[[ `echo $sos_ver | awk '{print length($0)}'` -ne 5 ]] && echo "Please input right SOS version to upgrade" && exit 1
|
||||
[[ $VERSION_ID -gt $sos_ver ]] && echo "You're trying to install an older version of Clear Linux." && exit 1
|
||||
|
||||
echo "Upgrading SOS..."
|
||||
|
||||
# setup mirror and proxy url while specified with m and p options
|
||||
[[ -n $mirror ]] && echo "Setting swupd mirror to: $mirror" && swupd mirror -s $mirror
|
||||
[[ -n $proxy ]] && echo "Setting proxy to: $proxy" && export https_proxy=$proxy
|
||||
|
||||
# Check EFI path exists.
|
||||
[[ ! -b $efi_partition ]] && echo "Please set the right EFI System partition firstly." && exit 1
|
||||
efi_mount_point=`findmnt $efi_partition -n | cut -d' ' -f1`
|
||||
root_partition=`echo $efi_partition | sed 's/1$/3/g'`
|
||||
partition=`echo $efi_partition | sed 's/1$//g;s/p$//g'`
|
||||
|
||||
echo "Disable auto update..."
|
||||
swupd autoupdate --disable 2>/dev/null
|
||||
|
||||
# Compare with current clear linux and skip upgrade SOS if get the same version.
|
||||
if [[ $VERSION_ID -eq $sos_ver ]]; then
|
||||
echo "Clear Linux version $sos_ver is already installed. Continuing to setup SOS..."
|
||||
else
|
||||
echo "Upgrading Clear Linux version from $VERSION_ID to $sos_ver ..."
|
||||
swupd verify --fix --picky -m $sos_ver 2>/dev/null
|
||||
fi
|
||||
|
||||
# Do the setups if previous process succeed.
|
||||
if [[ $? -eq 0 ]]; then
|
||||
echo "Adding the service-os, kernel-iot-lts2018 and systemd-networkd-autostart bundles..."
|
||||
swupd bundle-add service-os kernel-iot-lts2018 systemd-networkd-autostart 2>/dev/null
|
||||
|
||||
mount $efi_partition /mnt
|
||||
echo "Add /mnt/EFI/acrn folder"
|
||||
mkdir -p /mnt/EFI/acrn
|
||||
echo "Copy $acrn_conf_path /mnt/loader/entries/"
|
||||
if [[ ! -f $acrn_conf_path ]]; then
|
||||
echo "Missing acrn.conf file in folder: $acrn_conf_path"
|
||||
umount /mnt && sync
|
||||
exit 1
|
||||
fi
|
||||
cp -r $acrn_conf_path /mnt/loader/entries/
|
||||
if [[ $? -ne 0 ]]; then echo "Fail to copy $acrn_conf_path" && exit 1; fi
|
||||
echo "Copy $acrn_efi_path to /mnt/EFI/acrn"
|
||||
if [[ ! -f $acrn_efi_path ]]; then
|
||||
echo "Missing acrn.efi file in folder: $acrn_efi_path"
|
||||
umount /mnt && sync
|
||||
exit 1
|
||||
fi
|
||||
cp -r $acrn_efi_path /mnt/EFI/acrn/
|
||||
if [[ $? -ne 0 ]]; then echo "Fail to copy $acrn_efi_path" && exit 1; fi
|
||||
echo "Check ACRN efi boot event"
|
||||
check_acrn_bootefi=`efibootmgr | grep ACRN`
|
||||
if [[ "$check_arcn_bootefi" -ge "ACRN" ]]; then
|
||||
echo "Clean all ACRN efi boot event"
|
||||
efibootmgr | grep ACRN | cut -d'*' -f1 | cut -d't' -f2 | xargs -i efibootmgr -b {} -B >/dev/null
|
||||
fi
|
||||
echo "Check linux bootloader event"
|
||||
number=$(expr `efibootmgr | grep 'Linux bootloader' | wc -l` - 1)
|
||||
if [[ $number -ge 1 ]]; then
|
||||
echo "Clean all Linux bootloader event"
|
||||
efibootmgr | grep 'Linux bootloader' | cut -d'*' -f1 | cut -d't' -f2 | head -n$number | xargs -i efibootmgr -b {} -B >/dev/null
|
||||
fi
|
||||
|
||||
echo "Add new ACRN efi boot event"
|
||||
efibootmgr -c -l "\EFI\acrn\acrn.efi" -d $partition -p 1 -L "ACRN" >/dev/null
|
||||
|
||||
echo "Create loader.conf"
|
||||
mv /mnt/loader/loader.conf /mnt/loader/loader.conf.bck && touch /mnt/loader/loader.conf
|
||||
echo "Add default (5 seconds) boot wait time"
|
||||
echo "timeout 5" > /mnt/loader/loader.conf
|
||||
echo "Add default boot to ACRN"
|
||||
echo "default acrn" >> /mnt/loader/loader.conf
|
||||
|
||||
new_kernel=`ls /mnt/EFI/org.clearlinux/*sos* -tl | grep kernel | head -n1 | awk -F'/' '{print $5}'`
|
||||
echo "Getting latest Service OS kernel version: $new_kernel"
|
||||
cur_kernel=`cat /mnt/loader/entries/acrn.conf | sed -n 2p | cut -d'/' -f4`
|
||||
echo "Getting current Service OS kernel version: $cur_kernel"
|
||||
|
||||
echo "Replacing root partition uuid in acrn.conf"
|
||||
sed -i "s/<UUID of rootfs partition>/`blkid -s PARTUUID -o value $root_partition`/g" /mnt/loader/entries/acrn.conf
|
||||
# test replacing succeed or not.
|
||||
if [[ -z `grep $(blkid -s PARTUUID -o value $root_partition) /mnt/loader/entries/acrn.conf` ]]; then
|
||||
echo "Fail to replace root uuid in this file: /mnt/loader/entries/acrn.conf"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ "$cur_kernel" == "$new_kernel" ]]; then
|
||||
echo "No need to replace kernel conf info"
|
||||
else
|
||||
echo "Replace with new SOS kernel in acrn.conf"
|
||||
sed -i "s/$cur_kernel/$new_kernel/g" /mnt/loader/entries/acrn.conf
|
||||
fi
|
||||
|
||||
echo "Service OS setup done!"
|
||||
else
|
||||
echo "Fail to upgrade SOS to $sos_ver."
|
||||
echo "Please try upgrade SOS with this command:"
|
||||
echo "swupd update -m $sos_ver"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
umount /mnt
|
||||
sync
|
||||
[[ $disable_reboot == 0 ]] && echo "Rebooting Service OS to take effects." && reboot -f
|
||||
}
|
||||
|
||||
function upgrade_uos()
|
||||
{
|
||||
# Check UOS version
|
||||
[[ `echo $uos_ver | awk '{print length($0)}'` -ne 5 ]] && echo "Please input right UOS version to upgrade" && exit 1
|
||||
|
||||
echo "Upgrading UOS..."
|
||||
|
||||
# UOS download link
|
||||
uos_image_link="https://download.clearlinux.org/releases/$uos_ver/clear/clear-$uos_ver-kvm.img.xz"
|
||||
|
||||
# Set proxy if needed.
|
||||
[[ -n $proxy ]] && echo "Setting proxy to: $proxy" && export https_proxy=$proxy
|
||||
# Corrupt script if /mnt is already mounted.
|
||||
if [[ ! -z `findmnt /mnt -n` ]]; then
|
||||
echo "/mnt is already mounted, please unmount it if you want to continue upgrade UOS."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Do upgrade UOS process.
|
||||
if [[ $skip_download_uos != 1 ]]; then
|
||||
cd ~
|
||||
echo "Downloading UOS image: $uos_image_link"
|
||||
curl $uos_image_link -o clear-$uos_ver-kvm.img.xz
|
||||
if [[ $? -ne 0 ]]; then
|
||||
echo "Download UOS failed."
|
||||
rm clear-$uos_ver-kvm.img.xz
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
uos_img_xz=$(find ~/ -name clear-$uos_ver-kvm.img.xz)
|
||||
uos_img=$(find ~/ -name clear-$uos_ver-kvm.img)
|
||||
if [[ -f $uos_img ]] && [[ -f $uos_img.xz ]]; then echo "Moving $uos_img to $uos_img.old."; mv $uos_img $uos_img.old; fi
|
||||
if [[ ! -f $uos_img_xz ]] && [[ ! -f $uos_img ]]; then
|
||||
echo "You should download UOS clear-$uos_ver-kvm.img.xz file firstly." && exit 1
|
||||
fi
|
||||
if [[ -f $uos_img_xz ]]; then
|
||||
echo "Unxz UOS file: $uos_img_xz"
|
||||
unxz $uos_img_xz
|
||||
uos_img=`echo $uos_img_xz | sed 's/.xz$//g'`
|
||||
fi
|
||||
|
||||
echo "Get UOS image: $uos_img"
|
||||
uos_partition=`losetup -f -P --show $uos_img`p3
|
||||
mount $uos_partition /mnt
|
||||
[[ $? -ne 0 ]] && echo "Fail to mount UOS partition" && exit 1
|
||||
cp -r /usr/lib/modules/"`readlink /usr/lib/kernel/default-iot-lts2018 | awk -F '2018.' '{print $2}'`.iot-lts2018" /mnt/lib/modules
|
||||
umount /mnt
|
||||
sync
|
||||
|
||||
cp -r /usr/share/acrn/samples/nuc/launch_uos.sh ~/launch_uos_$uos_ver.sh
|
||||
sed -i "s/\(virtio-blk.*\)\/home\/clear\/uos\/uos.img/\1$(echo $uos_img | sed "s/\//\\\\\//g")/" ~/launch_uos_$uos_ver.sh
|
||||
[[ -z `grep $uos_img ~/launch_uos_$uos_ver.sh` ]] && echo "Fail to replace uos image in launch script: ~/launch_uos_$uos_ver.sh" && exit 1
|
||||
echo "Upgrade UOS done..."
|
||||
echo "Now you can run this command to start UOS..."
|
||||
echo "sudo /root/launch_uos_$uos_ver.sh"
|
||||
exit
|
||||
}
|
||||
|
||||
# Set script options.
|
||||
while getopts "s:u:p:m:e:kdh" opt
|
||||
do
|
||||
case "$opt" in
|
||||
s) sos_ver="$OPTARG"
|
||||
;;
|
||||
u) uos_ver="$OPTARG"
|
||||
;;
|
||||
p) proxy="$OPTARG"
|
||||
;;
|
||||
m) mirror="$OPTARG"
|
||||
;;
|
||||
e) efi_partition="$OPTARG"
|
||||
;;
|
||||
k) skip_download_uos=1
|
||||
;;
|
||||
d) disable_reboot=1
|
||||
;;
|
||||
h) print_help
|
||||
;;
|
||||
?) print_help
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Check args
|
||||
[[ $EUID -ne 0 ]] && echo "You have to run script as root." && exit 1
|
||||
[[ -z $1 ]] && print_help
|
||||
[[ -z $efi_partition ]] && efi_partition=/dev/sda1 || echo "Setting EFI System partition to: $efi_partition..."
|
||||
[[ -n $sos_ver && -n $uos_ver ]] && echo "You should select upgrading SOS or UOS" && exit 1
|
||||
[[ -n $uos_ver ]] && upgrade_uos || upgrade_sos
|
||||
@@ -1,630 +0,0 @@
|
||||
.. _getting-started-apl-nuc:
|
||||
|
||||
Getting started guide for Intel NUC
|
||||
###################################
|
||||
|
||||
The Intel |reg| NUC is the primary tested platform for ACRN development,
|
||||
and its setup is described below.
|
||||
|
||||
|
||||
Hardware setup
|
||||
**************
|
||||
|
||||
Intel Apollo Lake NUC (APL) and Intel Kaby Lake NUC (KBL),
|
||||
described in :ref:`hardware`, are currently supported for ACRN development:
|
||||
|
||||
- We can enable the serial console on `KBL
|
||||
<https://www.amazon.com/Intel-Business-Mini-Technology-BLKNUC7i7DNH1E/dp/B07CCQ8V4R>`__
|
||||
(NUC7i7DN), but this is not supported on APL (NUC6CAYH).
|
||||
|
||||
|
||||
Connecting to the serial port
|
||||
=============================
|
||||
|
||||
If you don't need a serial console you can ignore this section.
|
||||
|
||||
Neither the APL or KBL NUCs present an external serial port interface.
|
||||
However, the KBL NUC does have a serial port header you can
|
||||
expose with a serial DB9 header cable. You can build this cable yourself,
|
||||
referring to the `KBL NUC product specification
|
||||
<https://www.intel.com/content/dam/support/us/en/documents/mini-pcs/nuc-kits/NUC7i7DN_TechProdSpec.pdf>`__
|
||||
as shown below:
|
||||
|
||||
|
||||
.. figure:: images/KBL-serial-port-header.png
|
||||
:align: center
|
||||
|
||||
KBL serial port header details
|
||||
|
||||
|
||||
.. figure:: images/KBL-serial-port-header-to-RS232-cable.jpg
|
||||
:align: center
|
||||
|
||||
KBL `serial port header to RS232 cable
|
||||
<https://www.amazon.com/dp/B07BV1W6N8/ref=cm_sw_r_cp_ep_dp_wYm0BbABD5AK6>`_
|
||||
|
||||
|
||||
Or you can `purchase
|
||||
<https://www.amazon.com/dp/B07BV1W6N8/ref=cm_sw_r_cp_ep_dp_wYm0BbABD5AK6>`_
|
||||
such a cable.
|
||||
|
||||
You'll also need an `RS232 DB9 female to USB cable
|
||||
<https://www.amazon.com/Adapter-Chipset-CableCreation-Converter-Register/dp/B0769DVQM1>`__,
|
||||
or an `RS232 DB9 female/female (NULL modem) cross-over cable
|
||||
<https://www.amazon.com/SF-Cable-Null-Modem-RS232/dp/B006W0I3BA>`__
|
||||
to connect to your host system.
|
||||
|
||||
.. note::
|
||||
If you want to use the RS232 DB9 female/female cable, please choose
|
||||
the ``cross-over`` type rather than ``straight-through`` type.
|
||||
|
||||
Firmware update on the NUC
|
||||
==========================
|
||||
|
||||
You may need to update to the latest UEFI firmware for the NUC hardware.
|
||||
Follow these `BIOS Update Instructions
|
||||
<https://www.intel.com/content/www/us/en/support/articles/000005636.html>`__
|
||||
for downloading and flashing an updated BIOS for the NUC.
|
||||
|
||||
|
||||
Software setup
|
||||
**************
|
||||
|
||||
.. _set-up-CL:
|
||||
|
||||
Set up a Clear Linux Operating System
|
||||
=====================================
|
||||
|
||||
We begin by installing Clear Linux* as the development OS on the NUC.
|
||||
The Clear Linux release includes an ``acrn.efi`` hypervisor application
|
||||
that will be added to the EFI partition (by the quick setup script or
|
||||
manually, as described below).
|
||||
|
||||
.. note::
|
||||
|
||||
Please refer to the ACRN :ref:`release_notes` for the Clear Linux OS
|
||||
version number tested with a specific ACRN release. Adjust the
|
||||
instruction below to reference the appropriate version number of Clear
|
||||
Linux OS (we use version 30210 as an example).
|
||||
|
||||
#. Download the compressed Clear Linux OS installer image from
|
||||
https://download.clearlinux.org/releases/30210/clear/clear-30210-live-server.img.xz
|
||||
and follow the `Clear Linux OS installation guide
|
||||
<https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install-server>`_
|
||||
as a starting point for installing Clear Linux OS onto your platform. Follow the recommended
|
||||
options for choosing an **Advanced options** installation type, and using the platform's
|
||||
storage as the target device for installation (overwriting the
|
||||
existing data).
|
||||
|
||||
When setting up Clear Linux on your NUC:
|
||||
|
||||
#. Launch the Clear Linux OS installer boot menu
|
||||
#. With Clear Linux OS highlighted, select Enter
|
||||
#. Login with your root account, and new password
|
||||
#. Run the installer using the command::
|
||||
|
||||
$ clr-installer
|
||||
|
||||
#. From the Main Menu, select "Configure Media" and set
|
||||
"Auto Partition" to your desired hard disk.
|
||||
#. Press :kbd:`A` to show the "Advanced options".
|
||||
#. Select "Additional Bundle Selection" to add bundles for
|
||||
"desktop-autostart", "editors", "network-basic", "user-basic"
|
||||
#. Select "User Manager" to add an administrative user "clear" and
|
||||
password.
|
||||
#. Select "Assign Hostname" to set the hostname as "clr-sos-guest"
|
||||
#. Select Confirm to start installation.
|
||||
|
||||
#. After installation is complete, boot into Clear Linux OS, login as
|
||||
**clear** (using the password you set earlier).
|
||||
|
||||
#. The instructions below provide details for setting
|
||||
up the ACRN Hypervisor, Service OS, and Guest OS. Along with the
|
||||
manual step details, We also provide an
|
||||
automated script that does all these steps for you, so you can skip these
|
||||
manual steps. See the `quick-setup-guide`_ section below to use the
|
||||
automated setup script.
|
||||
|
||||
.. _quick-setup-guide:
|
||||
|
||||
Use the script to set up ACRN automatically
|
||||
===========================================
|
||||
|
||||
We provide an `acrn_quick_setup.sh script
|
||||
<https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/doc/getting-started/acrn_quick_setup.sh>`__
|
||||
in the ACRN GitHub repo to quickly and automatically set up the SOS and UOS
|
||||
and generate a customized script for launching the UOS.
|
||||
|
||||
This script requires the Clear Linux version number you'd like to set up
|
||||
for the ACRN SOS and UOS. The version specified must be greater than or
|
||||
equal to the Clear Linux version currently installed on the NUC. You
|
||||
can see your current Clear Linux version with the command::
|
||||
|
||||
$ cat /etc/os-release
|
||||
|
||||
.. note:: In the following steps, we're using Clear Linux version 30210. You should
|
||||
specify the Clear Linux version you want to use.
|
||||
|
||||
Here are the steps to install Clear Linux on your NUC, set up the SOS
|
||||
and UOS using the ``acrn_quick_setup.sh`` script, and launch the UOS:
|
||||
|
||||
#. Installing Clear Linux and login system
|
||||
|
||||
#. Open a terminal
|
||||
|
||||
#. Download ``acrn_quick_setup.sh`` script to set up the SOS. (If you don't need a proxy to
|
||||
get the script, you can just skip the ``export`` command.)
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ export https_proxy=https://myproxy.mycompany.com:port
|
||||
$ cd ~
|
||||
$ wget https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/doc/getting-started/acrn_quick_setup.sh
|
||||
|
||||
$ sudo sh acrn_quick_setup.sh -s 30210
|
||||
Password:
|
||||
Upgrading SOS...
|
||||
Disable auto update...
|
||||
Clear Linux version 30210 is already installed. Continuing to setup SOS...
|
||||
Adding the service-os, kernel-iot-lts2018 and systemd-networkd-autostart bundles...
|
||||
...100%
|
||||
...100%
|
||||
...100%
|
||||
none
|
||||
Add /mnt/EFI/acrn folder
|
||||
Copy /usr/share/acrn/samples/nuc/acrn.conf /mnt/loader/entries/
|
||||
Copy /usr/lib/acrn/acrn.efi to /mnt/EFI/acrn
|
||||
Check ACRN efi boot event
|
||||
Clean all ACRN efi boot event
|
||||
Check linux bootloader event
|
||||
Clean all Linux bootloader event
|
||||
Add new ACRN efi boot event
|
||||
Create loader.conf
|
||||
Add default (5 seconds) boot wait time
|
||||
Add default boot to ACRN
|
||||
Getting latest Service OS kernel version: kernel-org.clearlinux.iot-lts2018-sos.4.19.34-45
|
||||
Getting current Service OS kernel version: kernel-org.clearlinux.iot-lts2018-sos.4.19.13-1901141830
|
||||
Replacing root partition uuid in acrn.conf
|
||||
Replace with new SOS kernel in acrn.conf
|
||||
Service OS setup done!
|
||||
Rebooting Service OS to take effects.
|
||||
Rebooting.
|
||||
|
||||
.. note::
|
||||
This script is using ``/dev/sda1`` as default EFI System Partition
|
||||
ESP). If the ESP is different based on your hardware, you can specify
|
||||
it using ``-e`` option. For example, to set up the SOS on an NVMe
|
||||
SSD, you could specify::
|
||||
|
||||
sudo sh acrn_quick_setup.sh -s 30210 -e /dev/nvme0n1p1
|
||||
|
||||
.. note::
|
||||
If you don't need to reboot automatically after setting up the SOS, you
|
||||
can specify the ``-d`` parameter (don't reboot)
|
||||
|
||||
#. After the system reboots, login as the clear user. You can verify
|
||||
the SOS booted successfully by checking the ``dmesg`` log:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ dmesg | grep ACRN
|
||||
[ 0.000000] Hypervisor detected: ACRN
|
||||
[ 1.220887] ACRNTrace: Initialized acrn trace module with 4 cpu
|
||||
[ 1.224401] ACRN HVLog: Initialized hvlog module with 4 cpu
|
||||
|
||||
#. Continue by setting up a Guest OS using the ``acrn_quick_setup.sh``
|
||||
script with the ``-u`` option (and the same Clear Linux version
|
||||
number):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo sh acrn_quick_setup.sh -u 30210
|
||||
Password:
|
||||
Upgrading UOS...
|
||||
Downloading UOS image: https://download.clearlinux.org/releases/30210/clear/clear-30210-kvm.img.xz
|
||||
% Total % Received % Xferd Average Speed Time Time Time Current
|
||||
Dload Upload Total Spent Left Speed
|
||||
14 248M 14 35.4M 0 0 851k 0 0:04:57 0:00:42 0:04:15 293k
|
||||
|
||||
After the download is completed, you'll get this output.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
Unxz UOS image: clear-30210-kvm.img.xz
|
||||
Get UOS image: clear-30210-kvm.img
|
||||
Upgrade UOS done...
|
||||
Now you can run this command to start UOS...
|
||||
$ sudo /root/launch_uos_30210.sh
|
||||
|
||||
#. Now you can launch the UOS using the customized launch_uos script
|
||||
(with sudo):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo /root/launch_uos_30210.sh
|
||||
Password:
|
||||
cpu1 online=0
|
||||
cpu2 online=0
|
||||
cpu3 online=0
|
||||
passed gvt-g optargs low_gm 64, high_gm 448, fence 8
|
||||
SW_LOAD: get kernel path /usr/lib/kernel/default-iot-lts2018
|
||||
SW_LOAD: get bootargs root=/dev/vda3 rw rootwait maxcpus=1 nohpet console=tty0 console=hvc0 console=ttyS0 no_timer_check ignore_loglevel log_buf_len=16M consoleblank=0 tsc=reliable i915.avail_planes_per_pipe=0x070F00 i915.enable_hangcheck=0 i915.nuclear_pageflip=1 i915.enable_guc_loading=0 i915.enable_guc_submission=0 i915.enable_guc=0
|
||||
VHM api version 1.0
|
||||
open hugetlbfs file /run/hugepage/acrn/huge_lv1/D279543825D611E8864ECB7A18B34643
|
||||
open hugetlbfs file /run/hugepage/acrn/huge_lv2/D279543825D611E8864ECB7A18B34643
|
||||
level 0 free/need pages:512/0 page size:0x200000
|
||||
level 1 free/need pages:1/2 page size:0x40000000
|
||||
to reserve more free pages:
|
||||
to reserve pages (+orig 1): echo 2 > /sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages
|
||||
now enough free pages are reserved!
|
||||
|
||||
try to setup hugepage with:
|
||||
level 0 - lowmem 0x0, biosmem 0x0, highmem 0x0
|
||||
level 1 - lowmem 0x80000000, biosmem 0x0, highmem 0x0
|
||||
total_size 0x180000000
|
||||
|
||||
mmap ptr 0x0x7efef33bb000 -> baseaddr 0x0x7eff00000000
|
||||
mmap 0x40000000@0x7eff00000000
|
||||
touch 1 pages with pagesz 0x40000000
|
||||
mmap 0x40000000@0x7eff40000000
|
||||
touch 512 pages with pagesz 0x200000
|
||||
...
|
||||
[ OK ] Started Login Service.
|
||||
[ OK ] Started Network Name Resolution.
|
||||
[ OK ] Reached target Network.
|
||||
Starting Permit User Sessions...
|
||||
[ OK ] Reached target Host and Network Name Lookups.
|
||||
[ OK ] Started Permit User Sessions.
|
||||
[ OK ] Started Serial Getty on ttyS0.
|
||||
[ OK ] Started Getty on tty1.
|
||||
[ OK ] Started Serial Getty on hvc0.
|
||||
[ OK ] Reached target Login Prompts.
|
||||
[ OK ] Reached target Multi-User System.
|
||||
[ OK ] Reached target Graphical Interface.
|
||||
|
||||
clr-0d449d5327d64aee8a6b8a3484dcd880 login:
|
||||
|
||||
#. Login as root (and specify the new password). You can verify you're
|
||||
running in the UOS by checking the kernel release version or seeing
|
||||
if acrn devices are visible:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# uname -r
|
||||
4.19.34-45.iot-lts2018
|
||||
# ls /dev/acrn*
|
||||
ls: cannot access '/dev/acrn*': No such file or directory
|
||||
|
||||
In the UOS there won't be any ``/dev/acrn*`` devices. If you're in the SOS,
|
||||
you'd see results such as these:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# uname -r
|
||||
4.19.55-67.iot-lts2018-sos
|
||||
# ls /dev/acrn*
|
||||
/dev/acrn_hvlog_cur_0 /dev/acrn_hvlog_cur_2 /dev/acrn_trace_0 /dev/acrn_trace_2 /dev/acrn_vhm
|
||||
/dev/acrn_hvlog_cur_1 /dev/acrn_hvlog_cur_3 /dev/acrn_trace_1 /dev/acrn_trace_3
|
||||
|
||||
With that you've successfully set up Clear Linux at the Service and User
|
||||
OS and started up a UOS VM.
|
||||
|
||||
.. _manual-setup-guide:
|
||||
|
||||
Manual setup ACRN guide
|
||||
=======================
|
||||
|
||||
Instead of using the quick setup script, you can also set up ACRN, SOS,
|
||||
and UOS manually following these steps:
|
||||
|
||||
#. After installing Clear Linux on the NUC, login as the **clear** user
|
||||
and open a terminal window.
|
||||
#. Clear Linux OS is set to automatically update itself. We recommend that you disable
|
||||
this feature to have more control over when updates happen. Use this command
|
||||
to disable the autoupdate feature:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo swupd autoupdate --disable
|
||||
|
||||
.. note::
|
||||
The Clear Linux OS installer will automatically check for updates and install the
|
||||
latest version available on your system. If you wish to use a specific version
|
||||
(such as 30210), you can achieve that after the installation has completed using
|
||||
``sudo swupd verify --fix --picky -m 30210``
|
||||
|
||||
#. If you have an older version of Clear Linux OS already installed
|
||||
on your hardware, use this command to upgrade Clear Linux OS
|
||||
to version 30210 (or newer):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo swupd update -m 30210 # or newer version
|
||||
|
||||
#. Use the ``sudo swupd bundle-add`` command and add these Clear Linux OS bundles:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo swupd bundle-add service-os kernel-iot-lts2018 systemd-networkd-autostart
|
||||
|
||||
.. table:: Clear Linux OS bundles
|
||||
:widths: auto
|
||||
:name: CL-bundles
|
||||
|
||||
+----------------------------+-------------------------------------------+
|
||||
| Bundle | Description |
|
||||
+============================+===========================================+
|
||||
| service-os | Add the acrn hypervisor, acrn |
|
||||
| | devicemodel, and Service OS kernel |
|
||||
+----------------------------+-------------------------------------------+
|
||||
| kernel-iot-lts2018 | Run the Intel kernel "kernel-iot-lts2018" |
|
||||
| | which is enterprise-style kernel with |
|
||||
| | backports |
|
||||
+----------------------------+-------------------------------------------+
|
||||
| systemd-networkd-autostart | Enable systemd-networkd as the default |
|
||||
| | network manager |
|
||||
+----------------------------+-------------------------------------------+
|
||||
|
||||
|
||||
.. _add-acrn-to-efi:
|
||||
|
||||
Add the ACRN hypervisor to the EFI Partition
|
||||
============================================
|
||||
|
||||
In order to boot the ACRN SOS on the platform, you'll need to add it to the EFI
|
||||
partition. Follow these steps:
|
||||
|
||||
#. Mount the EFI partition and verify you have the following files:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo ls -1 /boot/EFI/org.clearlinux
|
||||
bootloaderx64.efi
|
||||
kernel-org.clearlinux.native.4.20.11-702
|
||||
kernel-org.clearlinux.iot-lts2018-sos.4.19.23-19
|
||||
kernel-org.clearlinux.iot-lts2018.4.19.23-19
|
||||
loaderx64.efi
|
||||
|
||||
.. note::
|
||||
On Clear Linux OS, the EFI System Partition (e.g.: ``/dev/sda1``)
|
||||
is mounted under ``/boot`` by default
|
||||
The Clear Linux project releases updates often, sometimes
|
||||
twice a day, so make note of the specific kernel versions
|
||||
(*iot-lts2018 and *iot-lts2018-sos*) listed on your system,
|
||||
as you will need them later.
|
||||
|
||||
.. note::
|
||||
The EFI System Partition (ESP) may be different based on your hardware.
|
||||
It will typically be something like ``/dev/mmcblk0p1`` on platforms
|
||||
that have an on-board eMMC or ``/dev/nvme0n1p1`` if your system has
|
||||
a non-volatile storage media attached via a PCI Express (PCIe) bus
|
||||
(NVMe).
|
||||
|
||||
#. Put the ``acrn.efi`` hypervisor application (included in the Clear
|
||||
Linux OS release) on the EFI partition with:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo mkdir /boot/EFI/acrn
|
||||
$ sudo cp /usr/lib/acrn/acrn.efi /boot/EFI/acrn/
|
||||
|
||||
#. Configure the EFI firmware to boot the ACRN hypervisor by default
|
||||
|
||||
The ACRN hypervisor (``acrn.efi``) is an EFI executable
|
||||
loaded directly by the platform EFI firmware. It then in turns loads the
|
||||
Service OS bootloader. Use the ``efibootmgr`` utility to configure the EFI
|
||||
firmware and add a new entry that loads the ACRN hypervisor.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN"
|
||||
|
||||
.. note::
|
||||
|
||||
Be aware that a Clear Linux OS update that includes a kernel upgrade will
|
||||
reset the boot option changes you just made. A Clear Linux OS update could
|
||||
happen automatically (if you have not disabled it as described above),
|
||||
if you later install a new bundle to your system, or simply if you
|
||||
decide to trigger an update manually. Whenever that happens,
|
||||
double-check the platform boot order using ``efibootmgr -v`` and
|
||||
modify it if needed.
|
||||
|
||||
The ACRN hypervisor (``acrn.efi``) accepts two command-line parameters that
|
||||
tweak its behavior:
|
||||
|
||||
1. ``bootloader=``: this sets the EFI executable to be loaded once the hypervisor
|
||||
is up and running. This is typically the bootloader of the Service OS and the
|
||||
default value is to use the Clear Linux OS bootloader, i.e.:
|
||||
``\EFI\org.clearlinux\bootloaderx64.efi``.
|
||||
#. ``uart=``: this tells the hypervisor where the serial port (UART) is found or
|
||||
whether it should be disabled. There are three forms for this parameter:
|
||||
|
||||
#. ``uart=disabled``: this disables the serial port completely
|
||||
#. ``uart=bdf@<BDF value>``: this sets the PCI serial port based on its BDF.
|
||||
For example, use ``bdf@0:18.1`` for a BDF of 0:18.1 ttyS1.
|
||||
#. ``uart=port@<port address>``: this sets the serial port address
|
||||
|
||||
.. note::
|
||||
|
||||
``uart=port@<port address>`` is required if you want to enable the serial console.
|
||||
You should run ``dmesg |grep ttyS0`` to get port address from the output, and then
|
||||
add the ``uart`` parameter into the ``efibootmgr`` command.
|
||||
|
||||
|
||||
Here is a more complete example of how to configure the EFI firmware to load the ACRN
|
||||
hypervisor and set these parameters.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \
|
||||
-u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=disabled"
|
||||
|
||||
And also here is the example of how to enable a serial console for KBL NUC.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \
|
||||
-u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=port@0x3f8"
|
||||
|
||||
#. Create a boot entry for the ACRN Service OS by copying a provided ``acrn.conf``
|
||||
and editing it to account for the kernel versions noted in a previous step.
|
||||
|
||||
It must contain these settings:
|
||||
|
||||
+-----------+----------------------------------------------------------------+
|
||||
| Setting | Description |
|
||||
+===========+================================================================+
|
||||
| title | Text to show in the boot menu |
|
||||
+-----------+----------------------------------------------------------------+
|
||||
| linux | Linux kernel for the Service OS (\*-sos) |
|
||||
+-----------+----------------------------------------------------------------+
|
||||
| options | Options to pass to the Service OS kernel (kernel parameters) |
|
||||
+-----------+----------------------------------------------------------------+
|
||||
|
||||
A starter acrn.conf configuration file is included in the Clear Linux
|
||||
OS release and is
|
||||
also available in the acrn-hypervisor/hypervisor GitHub repo as `acrn.conf
|
||||
<https://github.com/projectacrn/acrn-hypervisor/blob/master/efi-stub/clearlinux/acrn.conf>`__
|
||||
as shown here:
|
||||
|
||||
.. literalinclude:: ../../misc/efi-stub/clearlinux/acrn.conf
|
||||
:caption: efi-stub/clearlinux/acrn.conf
|
||||
|
||||
On the platform, copy the ``acrn.conf`` file to the EFI partition we mounted earlier:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo cp /usr/share/acrn/samples/nuc/acrn.conf /boot/loader/entries/
|
||||
|
||||
You will need to edit this file to adjust the kernel version (``linux`` section),
|
||||
insert the ``PARTUUID`` of your ``/dev/sda3`` partition
|
||||
(``root=PARTUUID=<UUID of rootfs partition>``) in the ``options`` section, and
|
||||
add the ``hugepagesz=1G hugepages=2`` at end of the ``options`` section.
|
||||
|
||||
Use ``blkid`` to find out what your ``/dev/sda3`` ``PARTUUID`` value is. Here
|
||||
is a handy one-line command to do that:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# sed -i "s/<UUID of rootfs partition>/`blkid -s PARTUUID -o value \
|
||||
/dev/sda3`/g" /boot/loader/entries/acrn.conf
|
||||
|
||||
.. note::
|
||||
It is also possible to use the device name directly, e.g. ``root=/dev/sda3``
|
||||
|
||||
#. Add a timeout period for Systemd-Boot to wait, otherwise it will not
|
||||
present the boot menu and will always boot the base Clear Linux OS
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo clr-boot-manager set-timeout 20
|
||||
$ sudo clr-boot-manager update
|
||||
|
||||
|
||||
#. Reboot and select "The ACRN Service OS" to boot, as shown below:
|
||||
|
||||
|
||||
.. code-block:: console
|
||||
:emphasize-lines: 1
|
||||
:caption: ACRN Service OS Boot Menu
|
||||
|
||||
=> The ACRN Service OS
|
||||
Clear Linux OS for Intel Architecture (Clear-linux-iot-lts2018-4.19.23-19)
|
||||
Clear Linux OS for Intel Architecture (Clear-linux-iot-lts2018-sos-4.19.23-19)
|
||||
Clear Linux OS for Intel Architecture (Clear-linux-native.4.20.11-702)
|
||||
EFI Default Loader
|
||||
Reboot Into Firmware Interface
|
||||
|
||||
#. After booting up the ACRN hypervisor, the Service OS will be launched
|
||||
automatically by default, and the Clear Linux OS desktop will be showing with user "clear",
|
||||
(or you can login remotely with an "ssh" client).
|
||||
If there is any issue which makes the GNOME desktop doesn't show successfully, then the system will go to
|
||||
shell console.
|
||||
|
||||
#. From ssh client, login as user "clear" using the password you set previously when
|
||||
you installed Clear Linux OS.
|
||||
|
||||
#. After rebooting the system, check that the ACRN hypervisor is running properly with:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ dmesg | grep ACRN
|
||||
[ 0.000000] Hypervisor detected: ACRN
|
||||
[ 1.687128] ACRNTrace: acrn_trace_init, cpu_num 4
|
||||
[ 1.693129] ACRN HVLog: acrn_hvlog_init
|
||||
|
||||
If you see log information similar to this, the ACRN hypervisor is running properly
|
||||
and you can start deploying a User OS. If not, verify the EFI boot options, SOS
|
||||
kernel, and ``acrn.conf`` settings are correct (as described above).
|
||||
|
||||
|
||||
ACRN Network Bridge
|
||||
===================
|
||||
|
||||
ACRN bridge has been setup as a part of systemd services for device communication. The default
|
||||
bridge creates ``acrn_br0`` which is the bridge and ``tap0`` as an initial setup. The files can be
|
||||
found in ``/usr/lib/systemd/network``. No additional setup is needed since systemd-networkd is
|
||||
automatically enabled after a system restart.
|
||||
|
||||
Set up Reference UOS
|
||||
====================
|
||||
|
||||
#. On your platform, download the pre-built reference Clear Linux OS UOS
|
||||
image version 30210 (or newer) into your (root) home directory:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd ~
|
||||
$ mkdir uos
|
||||
$ cd uos
|
||||
$ curl https://download.clearlinux.org/releases/30210/clear/clear-30210-kvm.img.xz -o uos.img.xz
|
||||
|
||||
.. note::
|
||||
In case you want to use or try out a newer version of Clear Linux OS as the UOS, you can
|
||||
download the latest from http://download.clearlinux.org/image. Make sure to adjust the steps
|
||||
described below accordingly (image file name and kernel modules version).
|
||||
|
||||
#. Uncompress it:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ unxz uos.img.xz
|
||||
|
||||
#. Deploy the UOS kernel modules to UOS virtual disk image (note: you'll need to use
|
||||
the same **iot-lts2018** image version number noted in step 1 above):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo losetup -f -P --show uos.img
|
||||
$ sudo mount /dev/loop0p3 /mnt
|
||||
$ sudo cp -r /usr/lib/modules/"`readlink /usr/lib/kernel/default-iot-lts2018 | awk -F '2018.' '{print $2}'`.iot-lts2018" /mnt/lib/modules
|
||||
$ sudo umount /mnt
|
||||
$ sync
|
||||
|
||||
#. Edit and Run the ``launch_uos.sh`` script to launch the UOS.
|
||||
|
||||
A sample `launch_uos.sh
|
||||
<https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/devicemodel/samples/nuc/launch_uos.sh>`__
|
||||
is included in the Clear Linux OS release, and
|
||||
is also available in the acrn-hypervisor/devicemodel GitHub repo (in the samples
|
||||
folder) as shown here:
|
||||
|
||||
.. literalinclude:: ../../devicemodel/samples/nuc/launch_uos.sh
|
||||
:caption: devicemodel/samples/nuc/launch_uos.sh
|
||||
:language: bash
|
||||
|
||||
By default, the script is located in the ``/usr/share/acrn/samples/nuc/``
|
||||
directory. You can run it to launch the User OS:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd /usr/share/acrn/samples/nuc/
|
||||
$ sudo ./launch_uos.sh
|
||||
|
||||
#. At this point, you've successfully booted the ACRN hypervisor,
|
||||
SOS, and UOS:
|
||||
|
||||
.. figure:: images/gsg-successful-boot.png
|
||||
:align: center
|
||||
|
||||
Successful boot
|
||||
@@ -1,280 +0,0 @@
|
||||
.. _getting-started-building:
|
||||
|
||||
Build ACRN from Source
|
||||
######################
|
||||
|
||||
Introduction
|
||||
************
|
||||
|
||||
Following a general embedded system programming model, the ACRN
|
||||
hypervisor is designed to be customized at build-time per hardware
|
||||
platform and per usage scenario, rather than one binary for all
|
||||
scenarios.
|
||||
|
||||
The hypervisor binary is generated based on Kconfig configuration
|
||||
settings. Instruction about these settings can be found in
|
||||
:ref:`getting-started-hypervisor-configuration`.
|
||||
|
||||
.. note::
|
||||
A generic configuration named ``hypervisor/arch/x86/configs/generic.config``
|
||||
is provided to help developers try out ACRN more easily. This configuration
|
||||
will likely work for most x86-based platforms, supported with limited features.
|
||||
This configuration can be enabled by specifying ``BOARD=generic`` in
|
||||
the make command line.
|
||||
|
||||
|
||||
A primary reason one binary for all platforms and all usage scenarios is
|
||||
not supported is because dynamic configuration parsing is restricted in
|
||||
ACRN hypervisor, for the following considerations:
|
||||
|
||||
* **Meeting functional safety requirements** Absence of dynamic objects is
|
||||
required in functional safety standards. Implementation of dynamic parsing
|
||||
would introduce dynamic objects. Avoiding use of dynamic
|
||||
parsing would help the ACRN hypervisor meet functional safety requirements.
|
||||
|
||||
* **Reduce complexity** ACRN is a lightweight reference hypervisor, built for
|
||||
embedded IoT. As new platforms for embedded systems are rapidly introduced,
|
||||
support for one binary would require more and more complexity in the
|
||||
hypervisor, something we need to avoid.
|
||||
|
||||
* **Keep small footprint** Implementation of dynamic parsing would introduce
|
||||
hundreds or thousands of code. Avoiding dynamic parsing would help keep
|
||||
Lines of Code (LOC) of the hypervisor in a desirable range (around 30K).
|
||||
|
||||
* **Improve boot up time** Dynamic parsing at runtime would increase the boot
|
||||
up time. Using build-time configuration and not dynamic parsing would help
|
||||
improve boot up time of the hypervisor.
|
||||
|
||||
|
||||
You can build the ACRN hypervisor, device model, and tools from
|
||||
source, by following these steps.
|
||||
|
||||
Install build tools and dependencies
|
||||
************************************
|
||||
|
||||
ACRN development is supported on popular Linux distributions,
|
||||
each with their own way to install development tools:
|
||||
|
||||
.. note::
|
||||
ACRN uses ``menuconfig``, a python3 text-based user interface (TUI) for
|
||||
configuring hypervisor options and using python's ``kconfiglib`` library.
|
||||
|
||||
* On a Clear Linux OS development system, install the necessary tools:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo swupd bundle-add os-clr-on-clr os-core-dev python3-basic
|
||||
$ pip3 install --user kconfiglib
|
||||
|
||||
* On a Ubuntu/Debian development system:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo apt install gcc \
|
||||
git \
|
||||
make \
|
||||
gnu-efi \
|
||||
libssl-dev \
|
||||
libpciaccess-dev \
|
||||
uuid-dev \
|
||||
libsystemd-dev \
|
||||
libevent-dev \
|
||||
libxml2-dev \
|
||||
libusb-1.0-0-dev \
|
||||
python3 \
|
||||
python3-pip \
|
||||
libblkid-dev \
|
||||
e2fslibs-dev \
|
||||
pkg-config
|
||||
$ sudo pip3 install kconfiglib
|
||||
|
||||
.. note::
|
||||
You need to use ``gcc`` version 7.3.* or higher else you will run into issue
|
||||
`#1396 <https://github.com/projectacrn/acrn-hypervisor/issues/1396>`_. Follow
|
||||
these instructions to install the ``gcc-7`` package on Ubuntu 16.04:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
|
||||
$ sudo apt update
|
||||
$ sudo apt install g++-7 -y
|
||||
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 \
|
||||
--slave /usr/bin/g++ g++ /usr/bin/g++-7
|
||||
|
||||
.. note::
|
||||
ACRN development requires ``binutils`` version 2.27 (or higher). You can
|
||||
verify your version of ``binutils`` with the command ``apt show binutils``.
|
||||
While Ubuntu 18.04 has a new version of ``binutils`` the default version on
|
||||
Ubuntu 16.04 needs updating (see issue `#1133
|
||||
<https://github.com/projectacrn/acrn-hypervisor/issues/1133>`_).
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ wget https://mirrors.ocf.berkeley.edu/gnu/binutils/binutils-2.27.tar.gz
|
||||
$ tar xzvf binutils-2.27.tar.gz && cd binutils-2.27
|
||||
$ ./configure
|
||||
$ make
|
||||
$ sudo make install
|
||||
|
||||
.. note::
|
||||
Ubuntu 14.04 requires ``libsystemd-journal-dev`` instead of ``libsystemd-dev``
|
||||
as indicated above.
|
||||
|
||||
* On a Fedora/Redhat development system:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo dnf install gcc \
|
||||
git \
|
||||
make \
|
||||
findutils \
|
||||
gnu-efi-devel \
|
||||
libuuid-devel \
|
||||
openssl-devel \
|
||||
libpciaccess-devel \
|
||||
systemd-devel \
|
||||
libxml2-devel \
|
||||
libevent-devel \
|
||||
libusbx-devel \
|
||||
python3 \
|
||||
python3-pip \
|
||||
libblkid-devel \
|
||||
e2fsprogs-devel
|
||||
$ sudo pip3 install kconfiglib
|
||||
|
||||
|
||||
* On a CentOS development system:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo yum install gcc \
|
||||
git \
|
||||
make \
|
||||
gnu-efi-devel \
|
||||
libuuid-devel \
|
||||
openssl-devel \
|
||||
libpciaccess-devel \
|
||||
systemd-devel \
|
||||
libxml2-devel \
|
||||
libevent-devel \
|
||||
libusbx-devel \
|
||||
python34 \
|
||||
python34-pip \
|
||||
libblkid-devel \
|
||||
e2fsprogs-devel
|
||||
$ sudo pip3 install kconfiglib
|
||||
|
||||
.. note::
|
||||
You may need to install `EPEL <https://fedoraproject.org/wiki/EPEL>`_ for
|
||||
installing python3 via yum for CentOS 7. For CentOS 6 you need to install
|
||||
pip manually. Please refer to https://pip.pypa.io/en/stable/installing for
|
||||
details.
|
||||
|
||||
|
||||
Build the hypervisor, device model and tools
|
||||
********************************************
|
||||
|
||||
The `acrn-hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
|
||||
repository has four main components in it:
|
||||
|
||||
1. The ACRN hypervisor code located in the ``hypervisor`` directory
|
||||
#. The EFI stub code located in the ``efi-stub`` directory
|
||||
#. The ACRN devicemodel code located in the ``devicemodel`` directory
|
||||
#. The ACRN tools source code located in the ``tools`` directory
|
||||
|
||||
You can build all these components in one go as follows:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ git clone https://github.com/projectacrn/acrn-hypervisor
|
||||
$ cd acrn-hypervisor
|
||||
$ make
|
||||
|
||||
The build results are found in the ``build`` directory.
|
||||
|
||||
.. note::
|
||||
if you wish to use a different target folder for the build
|
||||
artifacts, set the ``O`` (that is capital letter 'O') to the
|
||||
desired value. Example: ``make O=build-nuc BOARD=nuc6cayh``.
|
||||
|
||||
Generating the documentation is described in details in the :ref:`acrn_doc`
|
||||
tutorial.
|
||||
|
||||
Follow the same instructions to boot and test the images you created
|
||||
from your build.
|
||||
|
||||
.. _getting-started-hypervisor-configuration:
|
||||
|
||||
Configuring the hypervisor
|
||||
**************************
|
||||
|
||||
The ACRN hypervisor leverages Kconfig to manage configurations, powered by
|
||||
Kconfiglib. A default configuration is generated based on the board you have
|
||||
selected via the ``BOARD=`` command line parameter. You can make further
|
||||
changes to that default configuration to adjust to your specific
|
||||
requirements.
|
||||
|
||||
To generate hypervisor configurations, you need to build the hypervisor
|
||||
individually. The following steps generate a default but complete configuration,
|
||||
based on the platform selected, assuming that you are under the top-level
|
||||
directory of acrn-hypervisor. The configuration file, named ``.config``, can be
|
||||
found under the target folder of your build.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd hypervisor
|
||||
$ make defconfig BOARD=nuc6cayh
|
||||
|
||||
The BOARD specified is used to select a defconfig under
|
||||
``arch/x86/configs/``. The other command-line based options (e.g. ``RELEASE``)
|
||||
take no effects when generating a defconfig.
|
||||
|
||||
Modify the hypervisor configurations
|
||||
************************************
|
||||
|
||||
To modify the hypervisor configurations, you can either edit ``.config``
|
||||
manually, or invoke a TUI-based menuconfig, powered by kconfiglib, by executing
|
||||
``make menuconfig``. As an example, the following commands, assuming that you
|
||||
are under the top-level directory of acrn-hypervisor, generate a default
|
||||
configuration file for UEFI, allow you to modify some configurations and build
|
||||
the hypervisor using the updated ``.config``.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd hypervisor
|
||||
$ make defconfig BOARD=nuc6cayh
|
||||
$ make menuconfig # Modify the configurations per your needs
|
||||
$ make # Build the hypervisor with the new .config
|
||||
|
||||
.. note::
|
||||
Menuconfig is python3 only.
|
||||
|
||||
Refer to the help on menuconfig for a detailed guide on the interface.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ pydoc3 menuconfig
|
||||
|
||||
Create a new default configuration
|
||||
**********************************
|
||||
|
||||
Currently the ACRN hypervisor looks for default configurations under
|
||||
``hypervisor/arch/x86/configs/<BOARD>.config``, where ``<BOARD>`` is the
|
||||
specified platform. The following steps allow you to create a defconfig for
|
||||
another platform based on a current one.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd hypervisor
|
||||
$ make defconfig BOARD=nuc6cayh
|
||||
$ make menuconfig # Modify the configurations
|
||||
$ make savedefconfig # The minimized config reside at build/defconfig
|
||||
$ cp build/defconfig arch/x86/configs/xxx.config
|
||||
|
||||
Then you can re-use that configuration by passing the name (``xxx`` in the
|
||||
example above) to 'BOARD=':
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make defconfig BOARD=xxx
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 256 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 126 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.0 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 350 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 762 KiB |
@@ -1,22 +0,0 @@
|
||||
.. _getting_started:
|
||||
|
||||
Getting Started Guides
|
||||
######################
|
||||
|
||||
After reading the :ref:`introduction`, use these guides to get started
|
||||
using ACRN in a reference setup. We'll show how to set up your
|
||||
development and target hardware, and then how to boot up the ACRN
|
||||
hypervisor and the `Clear Linux`_ Service OS and Guest OS on the Intel
|
||||
(EFI) platform.
|
||||
|
||||
.. _Clear Linux: https://clearlinux.org
|
||||
|
||||
ACRN development is currently supported on Apollo Lake Intel platforms,
|
||||
described in :ref:`hardware`. Follow the setup guides listed here:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
apl-nuc.rst
|
||||
up2.rst
|
||||
building-from-source.rst
|
||||
@@ -1,121 +0,0 @@
|
||||
.. _getting-started-up2:
|
||||
|
||||
Getting started guide for UP2 board
|
||||
###################################
|
||||
|
||||
Hardware setup
|
||||
**************
|
||||
|
||||
The `UP Squared board <http://www.up-board.org/upsquared/specifications/>`_ (UP2) is
|
||||
an x86 maker board based on the Intel Apollo Lake platform. The UP boards
|
||||
are used in IoT applications, industrial automation, digital signage, and more.
|
||||
|
||||
The UP2 features Intel `Celeron N3550
|
||||
<https://ark.intel.com/products/95598/Intel-Celeron-Processor-N3350-2M-Cache-up-to-2_4-GHz>`_
|
||||
and Intel `Pentium N4200
|
||||
<https://ark.intel.com/products/95592/Intel-Pentium-Processor-N4200-2M-Cache-up-to-2_5-GHz>`_
|
||||
SoCs. Both have been confirmed to work with ACRN.
|
||||
|
||||
Connecting to the serial port
|
||||
=============================
|
||||
|
||||
The UP2 board has two serial ports. The following figure shows the UP2 board's
|
||||
40-pin HAT connector we'll be using as documented in the `UP2 Datasheet
|
||||
<https://up-board.org/wp-content/uploads/datasheets/UP-Square-DatasheetV0.5.pdf>`_.
|
||||
|
||||
.. image:: images/the-bottom-side-of-UP2-board.png
|
||||
:align: center
|
||||
|
||||
We'll access the serial port through the I/O pins in the
|
||||
40-pin HAT connector using a `USB TTL serial cable
|
||||
<http://www.ftdichip.com/Products/USBTTLSerial.htm>`_,
|
||||
and show how to connect a serial port with
|
||||
``PL2303TA USB to TTL serial cable`` for example:
|
||||
|
||||
.. image:: images/USB-to-TTL-serial-cable.png
|
||||
:align: center
|
||||
|
||||
Connect pin 6 (``Ground``), pin 8 (``UART_TXD``) and pin 10 (``UART_RXD``) of the HAT
|
||||
connector to respectively the ``GND``, ``RX`` and ``TX`` pins of your
|
||||
USB serial cable. Plug the USB TTL serial cable into your PC and use a
|
||||
console emulation tool such as ``minicom`` or ``putty`` to communicate
|
||||
with the UP2 board for debugging.
|
||||
|
||||
.. image:: images/the-connection-of-serial-port.png
|
||||
:align: center
|
||||
|
||||
Software setup
|
||||
**************
|
||||
|
||||
Setting up the ACRN hypervisor (and associated components) on the UP2
|
||||
board is no different than other hardware platforms so please follow
|
||||
the instructions provided in the :ref:`getting-started-apl-nuc`, with
|
||||
the additional information below.
|
||||
|
||||
There are a few parameters specific to the UP2 board that differ from
|
||||
what is referenced in the :ref:`getting-started-apl-nuc` section:
|
||||
|
||||
1. Serial Port settings
|
||||
#. Storage device name
|
||||
|
||||
You will need to keep these in mind in a few places:
|
||||
|
||||
* When mounting the EFI System Partition (ESP)
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# mount /dev/mmcblk0p1 /mnt
|
||||
|
||||
* When adjusting the ``acrn.conf`` file
|
||||
|
||||
* Set the ``root=`` parameter using the ``PARTUUID`` or device name directly
|
||||
|
||||
* When configuring the EFI firmware to boot the ACRN hypervisor by default
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/mmcblk0 -p 1 -L "ACRN Hypervisor" \
|
||||
-u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=bdf@0:18.1"
|
||||
|
||||
UP2 serial port setting
|
||||
=======================
|
||||
|
||||
The serial port (ttyS1) in the 40-pin HAT connector is located at ``serial PCI BDF 0:18.1``.
|
||||
You can check this from the ``lspci`` output from the initial Clearlinux installation.
|
||||
Also you can use ``dmesg | grep tty`` to get its IRQ information for console setting; and update
|
||||
SOS bootargs ``console=ttyS1`` in acrn.conf to match with console setting.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# lspci | grep UART
|
||||
00:18.0 . Series HSUART Controller #1 (rev 0b)
|
||||
00:18.1 . Series HSUART Controller #2 (rev 0b)
|
||||
|
||||
# dmesg | grep tty
|
||||
dw-apb-uart.8: ttyS0 at MMIO 0x91524000 (irq = 4, base_baud = 115200) is a 16550A
|
||||
dw-apb-uart.9: ttyS1 at MMIO 0x91522000 (irq = 5, base_baud = 115200) is a 16550A
|
||||
|
||||
The second entry associated with ``00:18.1 @irq5`` is the one on the 40-pin HAT connector.
|
||||
|
||||
UP2 block device
|
||||
================
|
||||
|
||||
The UP2 board has an on-board eMMC device. The device name to be used
|
||||
throughout the :ref:`getting_started` therefore is ``/dev/mmcblk0``
|
||||
(and ``/dev/mmcblk0pX`` for any partition).
|
||||
|
||||
The UUID of the partition ``/dev/mmcblk0p3`` can be found by
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# blkid /dev/mmcblk
|
||||
|
||||
.. note::
|
||||
You can also use the device name directly, e.g.: ``root=/dev/mmcblk0p3``
|
||||
|
||||
Running the hypervisor
|
||||
**********************
|
||||
|
||||
Now that the hypervisor and Service OS have been installed on your UP2 board,
|
||||
you can proceed with the rest of the instructions in the
|
||||
:ref:`getting-started-apl-nuc` and install the User OS (UOS).
|
||||
Reference in New Issue
Block a user