github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-19 12:12:16 +00:00
Code Issues Projects Releases Wiki Activity

doc: content updates to Install ACRN out of the box file

Browse Source 
Signed-off-by: Deb Taylor <deb.taylor@intel.com>
This commit is contained in:
Deb Taylor 2019-09-25 19:20:20 -04:00 committed by deb-intel
parent df465cc1df
commit dd1172ee63
1 changed files with 173 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

337
doc/getting-started/acrn_ootb.rst
View File

@ -1,46 +1,47 @@
.. _acrn_ootb: .. _acrn_ootb:
Install ACRN use out-of-the-box image Install ACRN Out-of-the-box
##################################### ###########################
In this tutorial, we will learn to generate an out-of-the-box (OOTB) Service VM
or even a Preempt-RT VM image so that we can use ACRN or RTVM immediately after In this tutorial, we will learn to generate an out-of-the-box (OOTB) Service VM or a Preempt-RT VM image so that we can use ACRN or RTVM immediately after installation without any configuration or modification.
installation without any configuration or modification.
Set up a Build Environment
**************************
Set up build environment
************************
#. Follow the `Clear Linux OS installation guide #. Follow the `Clear Linux OS installation guide
<https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install-server>`_ <https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install-server>`_
to install a native Clear Linux OS on development machine. to install a native Clear Linux OS on a development machine.
#. Login in the Clear Linux OS and install these bundles:: #. Log in to the Clear Linux OS and install these bundles::
$ sudo swupd bundle-add clr-installer vim network-basic $ sudo swupd bundle-add clr-installer vim network-basic
.. _set_up_ootb_service_vm: .. _set_up_ootb_service_vm:
Generate Service VM image Generate a Service VM image
************************* ***************************
Create Service VM image YAML file and script Step 1: Create a Service VM YAML file and script
============================================ ================================================
- **Example 1**: `ACRN SDC scenario`
**Scenario 1: ACRN SDC**
#. Create the ACRN SDC ``service-os.yaml`` file: #. Create the ACRN SDC ``service-os.yaml`` file:
.. code-block:: console .. code-block:: none
$ mkdir -p ~/service-os && cd ~/service-os $ mkdir -p ~/service-os && cd ~/service-os
$ vim service-os.yaml $ vim service-os.yaml
Update the ``service-os.yaml`` to: Update the ``service-os.yaml`` file to:
.. code-block:: bash .. code-block:: bash
:emphasize-lines: 51 :emphasize-lines: 51
block-devices: [ block-devices: [
{name: "bdevice", file: "sos.img"} {name: "bdevice", file: "sos.img"}
] ]
targetMedia: targetMedia:
- name: ${bdevice} - name: ${bdevice}
size: "108.54G" size: "108.54G"
@ -60,7 +61,7 @@ Create Service VM image YAML file and script
mountpoint: / mountpoint: /
size: "108G" size: "108G"
type: part type: part
bundles: [ bundles: [
bootloader, bootloader,
editors, editors,
@ -72,75 +73,75 @@ Create Service VM image YAML file and script
systemd-networkd-autostart, systemd-networkd-autostart,
service-os service-os
] ]
autoUpdate: false autoUpdate: false
postArchive: false postArchive: false
postReboot: false postReboot: false
telemetry: false telemetry: false
hostname: clr-sos hostname: clr-sos
keyboard: us keyboard: us
language: en_US.UTF-8 language: en_US.UTF-8
kernel: kernel-iot-lts2018-sos kernel: kernel-iot-lts2018-sos
post-install: [ post-install: [
{cmd: "${yamlDir}/service-os-post.sh ${chrootDir}"}, {cmd: "${yamlDir}/service-os-post.sh ${chrootDir}"},
] ]
version: 30970 version: 30970
.. note:: Update version value to your target Clear Linux version. .. note:: Update the version value to your target Clear Linux version.
#. Create ACRN SDC ``service-os-post.sh``: #. Create the ACRN SDC ``service-os-post.sh`` script:
.. code-block:: console .. code-block:: none
$ vim service-os-post.sh $ vim service-os-post.sh
Update the ``service-os-post.sh`` to: Update the ``service-os-post.sh`` script to:
.. code-block:: bash .. code-block:: bash
#!/bin/bash #!/bin/bash
# ACRN SOS Image Post Install steps # ACRN SOS Image Post Install steps
set -ex set -ex
CHROOTPATH=$1 CHROOTPATH=$1
# acrn.efi path # acrn.efi path
acrn_efi_path="$CHROOTPATH/usr/lib/acrn/acrn.efi" acrn_efi_path="$CHROOTPATH/usr/lib/acrn/acrn.efi"
# copy acrn.efi to efi partition # copy acrn.efi to efi partition
mkdir -p "$CHROOTPATH/boot/EFI/acrn" || exit 1 mkdir -p "$CHROOTPATH/boot/EFI/acrn" || exit 1
cp "$acrn_efi_path" "$CHROOTPATH/boot/EFI/acrn" || exit 1 cp "$acrn_efi_path" "$CHROOTPATH/boot/EFI/acrn" || exit 1
# create load.conf # create load.conf
echo "Add default (5 seconds) boot wait time" echo "Add default (5 seconds) boot wait time"
echo "timeout 5" >> "$CHROOTPATH/boot/loader/loader.conf" || exit 1 echo "timeout 5" >> "$CHROOTPATH/boot/loader/loader.conf" || exit 1
chroot $CHROOTPATH systemd-machine-id-setup chroot $CHROOTPATH systemd-machine-id-setup
chroot $CHROOTPATH systemctl enable getty@tty1.service chroot $CHROOTPATH systemctl enable getty@tty1.service
echo "Welcome to the Clear Linux* ACRN SOS image! echo "Welcome to the Clear Linux* ACRN SOS image!
Please login as root for the first time! Please login as root for the first time!
" >> $1/etc/issue " >> $1/etc/issue
exit 0 exit 0
- **Example 2**: `ACRN INDUSTRY scenario` **Scenario 2: ACRN INDUSTRY**
#. Create ACRN INDUSTRY ``service-os-industry.yaml`` file: #. Create the ACRN INDUSTRY ``service-os-industry.yaml`` file:
.. code-block:: console .. code-block:: none
$ mkdir -p ~/service-os-industry && cd ~/service-os-industry $ mkdir -p ~/service-os-industry && cd ~/service-os-industry
$ vim service-os-industry.yaml $ vim service-os-industry.yaml
Update the ``service-os-industry.yaml`` to: Update the ``service-os-industry.yaml`` file to:
.. code-block:: bash .. code-block:: bash
:emphasize-lines: 52 :emphasize-lines: 52
@ -148,7 +149,7 @@ Create Service VM image YAML file and script
block-devices: [ block-devices: [
{name: "bdevice", file: "sos-industry.img"} {name: "bdevice", file: "sos-industry.img"}
] ]
targetMedia: targetMedia:
- name: ${bdevice} - name: ${bdevice}
size: "108.54G" size: "108.54G"
@ -168,7 +169,7 @@ Create Service VM image YAML file and script
mountpoint: / mountpoint: /
size: "108G" size: "108G"
type: part type: part
bundles: [ bundles: [
bootloader, bootloader,
editors, editors,
@ -180,107 +181,113 @@ Create Service VM image YAML file and script
systemd-networkd-autostart, systemd-networkd-autostart,
service-os service-os
] ]
autoUpdate: false autoUpdate: false
postArchive: false postArchive: false
postReboot: false postReboot: false
telemetry: false telemetry: false
hostname: clr-sos hostname: clr-sos
keyboard: us keyboard: us
language: en_US.UTF-8 language: en_US.UTF-8
kernel: kernel-iot-lts2018-sos kernel: kernel-iot-lts2018-sos
post-install: [ post-install: [
{cmd: "${yamlDir}/service-os-industry-post.sh ${chrootDir}"}, {cmd: "${yamlDir}/service-os-industry-post.sh ${chrootDir}"},
] ]
version: 30970 version: 30970
.. note:: Update version value to your target Clear Linux version. .. note:: Update the version value to your target Clear Linux version.
#. Create ``service-os-industry-post.sh``: #. Create the ``service-os-industry-post.sh`` script:
.. code-block:: console .. code-block:: none
$ vim service-os-industry-post.sh $ vim service-os-industry-post.sh
Update the ``service-os-industry-post.sh`` to: Update the ``service-os-industry-post.sh`` script to:
.. code-block:: bash .. code-block:: bash
#!/bin/bash #!/bin/bash
# ACRN SOS Image Post Install steps # ACRN SOS Image Post Install steps
set -ex
CHROOTPATH=$1
# acrn.kbl-nuc-i7.industry.efi path
acrn_industry_efi_path="$CHROOTPATH/usr/lib/acrn/acrn.kbl-nuc-i7.industry.efi"
# copy acrn.efi to efi partition
mkdir -p "$CHROOTPATH/boot/EFI/acrn" || exit 1
cp "$acrn_industry_efi_path" "$CHROOTPATH/boot/EFI/acrn/acrn.efi" || exit 1
# create load.conf
echo "Add default (5 seconds) boot wait time"
echo "timeout 5" >> "$CHROOTPATH/boot/loader/loader.conf" || exit 1
chroot $CHROOTPATH systemd-machine-id-setup
chroot $CHROOTPATH systemctl enable getty@tty1.service
echo "Welcome to the Clear Linux* ACRN SOS Industry image!
Please login as root for the first time!
" >> $1/etc/issue
exit 0
Use clr-installer to build Service VM image set -ex
===========================================
- Build ACRN SDC Service VM image:
.. code-block:: console CHROOTPATH=$1
# acrn.kbl-nuc-i7.industry.efi path
acrn_industry_efi_path="$CHROOTPATH/usr/lib/acrn/acrn.kbl-nuc-i7.industry.efi"
# copy acrn.efi to efi partition
mkdir -p "$CHROOTPATH/boot/EFI/acrn" || exit 1
cp "$acrn_industry_efi_path" "$CHROOTPATH/boot/EFI/acrn/acrn.efi" || exit 1
# create load.conf
echo "Add default (5 seconds) boot wait time"
echo "timeout 5" >> "$CHROOTPATH/boot/loader/loader.conf" || exit 1
chroot $CHROOTPATH systemd-machine-id-setup
chroot $CHROOTPATH systemctl enable getty@tty1.service
echo "Welcome to the Clear Linux* ACRN SOS Industry image!
Please login as root for the first time!
" >> $1/etc/issue
exit 0
Step 2: Build the Service VM image
==================================
Use the clr-installer to build the Service VM image.
**Scenario 1: ACRN SDC**
.. code-block:: none
$ cd ~/service-os $ cd ~/service-os
$ sudo clr-installer -c service-os.yaml $ sudo clr-installer -c service-os.yaml
.. note:: The ``service-os.img`` will be generated at current directory.
The ``service-os.img`` will be generated at current directory.
- Build ACRN INDUSTRY Service VM image: **Scenario 2: ACRN INDUSTRY**
.. code-block:: console .. code-block:: none
$ cd ~/service-os-industry $ cd ~/service-os-industry
$ sudo clr-installer -c service-os-industry.yaml $ sudo clr-installer -c service-os-industry.yaml
.. note:: The ``service-os-industry.img`` will be generated at current directory.
Deploy Service VM image The ``service-os-industry.img`` will be generated at current directory.
=======================
Step 3: Deploy the Service VM image
===================================
#. Prepare a U disk with at least 8GB memory. #. Prepare a U disk with at least 8GB memory.
#. Follow these steps to create two partitions on the U disk, #. Follow these steps to create two partitions on the U disk.
the first partition is 4G, and the second partition use the left free space: Keep 4GB in the first partition and leave free space in the second parition.
.. code-block:: console .. code-block:: none
# sudo gdisk /dev/sdb # sudo gdisk /dev/sdb
GPT fdisk (gdisk) version 1.0.3 GPT fdisk (gdisk) version 1.0.3
Partition table scan: Partition table scan:
MBR: protective MBR: protective
BSD: not present BSD: not present
APM: not present APM: not present
GPT: present GPT: present
Found valid GPT with protective MBR; using GPT. Found valid GPT with protective MBR; using GPT.
Command (? for help): n Command (? for help): n
Partition number (1-128, default 1): Partition number (1-128, default 1):
First sector (34-15249374, default = 2048) or {+-}size{KMGTP}: First sector (34-15249374, default = 2048) or {+-}size{KMGTP}:
@ -288,7 +295,7 @@ Deploy Service VM image
Current type is 'Linux filesystem' Current type is 'Linux filesystem'
Hex code or GUID (L to show codes, Enter = 8300): Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to 'Linux filesystem' Changed type of partition to 'Linux filesystem'
Command (? for help): n Command (? for help): n
Partition number (2-128, default 2): Partition number (2-128, default 2):
First sector (34-15249374, default = 8390656) or {+-}size{KMGTP}: First sector (34-15249374, default = 8390656) or {+-}size{KMGTP}:
@ -296,7 +303,7 @@ Deploy Service VM image
Current type is 'Linux filesystem' Current type is 'Linux filesystem'
Hex code or GUID (L to show codes, Enter = 8300): Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to 'Linux filesystem' Changed type of partition to 'Linux filesystem'
Command (? for help): p Command (? for help): p
Disk /dev/sdb: 15249408 sectors, 7.3 GiB Disk /dev/sdb: 15249408 sectors, 7.3 GiB
Model: USB FLASH DRIVE Model: USB FLASH DRIVE
@ -307,23 +314,23 @@ Deploy Service VM image
First usable sector is 34, last usable sector is 15249374 First usable sector is 34, last usable sector is 15249374
Partitions will be aligned on 2048-sector boundaries Partitions will be aligned on 2048-sector boundaries
Total free space is 2014 sectors (1007.0 KiB) Total free space is 2014 sectors (1007.0 KiB)
Number Start (sector) End (sector) Size Code Name Number Start (sector) End (sector) Size Code Name
1 2048 8390655 4.0 GiB 8300 Linux filesystem 1 2048 8390655 4.0 GiB 8300 Linux filesystem
2 8390656 15249374 3.3 GiB 8300 Linux filesystem 2 8390656 15249374 3.3 GiB 8300 Linux filesystem
Command (? for help): w Command (? for help): w
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!! PARTITIONS!!
Do you want to proceed? (Y/N): Y Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/sdb. OK; writing new GUID partition table (GPT) to /dev/sdb.
The operation has completed successfully. The operation has completed successfully.
#. Download and install a bootable Clear Linux on the U disk: #. Download and install a bootable Clear Linux on the U disk:
.. code-block:: console .. code-block:: none
$ wget https://download.clearlinux.org/releases/30970/clear/clear-30970-live-server.iso.xz $ wget https://download.clearlinux.org/releases/30970/clear/clear-30970-live-server.iso.xz
$ xz -d clear-30970-live-server.iso.xz $ xz -d clear-30970-live-server.iso.xz
@ -331,67 +338,67 @@ Deploy Service VM image
#. Copy the ``service-os.img`` or ``service-os-industry.img`` to the U disk: #. Copy the ``service-os.img`` or ``service-os-industry.img`` to the U disk:
.. code-block:: console .. code-block:: none
$ sudo mkfs.ext4 /dev/sdb2 $ sudo mkfs.ext4 /dev/sdb2
$ sudo mount /dev/sdb2 /mnt $ sudo mount /dev/sdb2 /mnt
- SDC scenario: - ACRN SDC scenario:
.. code-block:: console .. code-block:: none
$ cp ~/service-os/service-os.img /mnt $ cp ~/service-os/service-os.img /mnt
$ sync && umount /mnt $ sync && umount /mnt
- INDUSTRY scenario: - ACRN INDUSTRY scenario:
.. code-block:: console .. code-block:: none
$ cp ~/service-os-industry/service-os-industry.img /mnt $ cp ~/service-os-industry/service-os-industry.img /mnt
$ sync && umount /mnt $ sync && umount /mnt
#. Unplug the U disk from development machine and plugin it to your test machine. #. Unplug the U disk from the development machine and plug it in to your test machine.
#. Reboot the test machine and boot from USB. #. Reboot the test machine and boot from the USB.
#. Login in Live Service Clear Linux OS with "root" account, #. Log in to the Live Service Clear Linux OS with your "root" account and
mount the second partition on U disk: mount the second partition on the U disk:
.. code-block:: console .. code-block:: none
# mount /dev/sdb2 /mnt # mount /dev/sdb2 /mnt
#. Format the disk which will install the Service VM image: #. Format the disk that will install the Service VM image:
.. code-block:: console .. code-block:: none
# sudo gdisk /dev/nvme0n1 # sudo gdisk /dev/nvme0n1
GPT fdisk (gdisk) version 1.0.3 GPT fdisk (gdisk) version 1.0.3
Partition table scan: Partition table scan:
MBR: protective MBR: protective
BSD: not present BSD: not present
APM: not present APM: not present
GPT: present GPT: present
Found valid GPT with protective MBR; using GPT. Found valid GPT with protective MBR; using GPT.
Command (? for help): o Command (? for help): o
This option deletes all partitions and creates a new protective MBR. This option deletes all partitions and creates a new protective MBR.
Proceed? (Y/N): Y Proceed? (Y/N): Y
Command (? for help): w Command (? for help): w
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!! PARTITIONS!!
Do you want to proceed? (Y/N): Y Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/nvme0n1. OK; writing new GUID partition table (GPT) to /dev/nvme0n1.
The operation has completed successfully. The operation has completed successfully.
#. Delete the old ACRN EFI firmware info: #. Delete the old ACRN EFI firmware info:
.. code-block:: console .. code-block:: none
# efibootmgr | grep ACRN | cut -d'*' -f1 | cut -d't' -f2 | xargs -i efibootmgr -b {} -B # efibootmgr | grep ACRN | cut -d'*' -f1 | cut -d't' -f2 | xargs -i efibootmgr -b {} -B
@ -399,40 +406,40 @@ Deploy Service VM image
- ACRN SDC scenario: - ACRN SDC scenario:
.. code-block:: console .. code-block:: none
# dd if=/mnt/sos.img of=/dev/nvme0n1 bs=4M oflag=sync status=progress # dd if=/mnt/sos.img of=/dev/nvme0n1 bs=4M oflag=sync status=progress
- ACRN INDUSTRY scenario: - ACRN INDUSTRY scenario:
.. code-block:: console .. code-block:: none
# dd if=/mnt/sos-industry.img of=/dev/nvme0n1 bs=4M oflag=sync status=progress # dd if=/mnt/sos-industry.img of=/dev/nvme0n1 bs=4M oflag=sync status=progress
#. Configure the EFI firmware to boot the ACRN hypervisor by default: #. Configure the EFI firmware to boot the ACRN hypervisor by default:
.. code-block:: console .. code-block:: none
# efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/nvme0n1 -p 1 -L "ACRN" # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/nvme0n1 -p 1 -L "ACRN"
#. Unplug the U disk and reboot the test machine, and after the Clear Linux OS boots, #. Unplug the U disk and reboot the test machine. After the Clear Linux OS boots, log in as "root" for the first time.
everything is ready, you could login as "root" for the first time.
.. _set_up_ootb_rtvm: .. _set_up_ootb_rtvm:
Generate User VM Preempt-RT image Generate a User VM Preempt-RT image
********************************* ***********************************
Step 1: Create a Preempt-RT image YAML file and script
======================================================
Create Preempt-RT image YAML file and script
============================================
#. Create the ``preempt-rt.yaml`` file: #. Create the ``preempt-rt.yaml`` file:
.. code-block:: console .. code-block:: none
$ mkdir -p ~/preempt-rt && cd ~/preempt-rt $ mkdir -p ~/preempt-rt && cd ~/preempt-rt
$ vim preempt-rt.yaml $ vim preempt-rt.yaml
Update ``preempt-rt.yaml`` to: Update the ``preempt-rt.yaml`` file to:
.. code-block:: bash .. code-block:: bash
:emphasize-lines: 46 :emphasize-lines: 46
@ -440,7 +447,7 @@ Create Preempt-RT image YAML file and script
block-devices: [ block-devices: [
{name: "bdevice", file: "preempt-rt.img"} {name: "bdevice", file: "preempt-rt.img"}
] ]
targetMedia: targetMedia:
- name: ${bdevice} - name: ${bdevice}
size: "8.54G" size: "8.54G"
@ -460,7 +467,7 @@ Create Preempt-RT image YAML file and script
mountpoint: / mountpoint: /
size: "8G" size: "8G"
type: part type: part
bundles: [ bundles: [
bootloader, bootloader,
editors, editors,
@ -471,55 +478,57 @@ Create Preempt-RT image YAML file and script
sysadmin-basic, sysadmin-basic,
systemd-networkd-autostart systemd-networkd-autostart
] ]
autoUpdate: false autoUpdate: false
postArchive: false postArchive: false
postReboot: false postReboot: false
telemetry: false telemetry: false
hostname: clr-preempt-rt hostname: clr-preempt-rt
keyboard: us keyboard: us
language: en_US.UTF-8 language: en_US.UTF-8
kernel: kernel-lts2018-preempt-rt kernel: kernel-lts2018-preempt-rt
version: 30970 version: 30970
.. note:: Update version value to your target Clear Linux version .. note:: Update the version value to your target Clear Linux version
Build User VM Preempt-RT image Step 2: Build a User VM Preempt-RT image
============================== ========================================
.. code-block:: console .. code-block:: none
$ sudo clr-installer -c preempt-rt.yaml $ sudo clr-installer -c preempt-rt.yaml
The ``preempt-rt.img`` will be generated at current directory.
Deploy User VM Preempt-RT image The ``preempt-rt.img`` will be generated at the current directory.
===============================
#. Login the Service VM and copy the ``preempt-rt.img`` from development machine:
.. code-block:: console Step 3: Deploy the User VM Preempt-RT image
===========================================
#. Log in to the Service VM and copy the ``preempt-rt.img`` from the development machine:
.. code-block:: none
$ mkdir -p preempt-rt && cd preempt-rt $ mkdir -p preempt-rt && cd preempt-rt
$ scp <development username>@<development machine ip>:<path to preempt-rt.img> . $ scp <development username>@<development machine ip>:<path to preempt-rt.img> .
#. Write ``preempt-rt.img`` to disk: #. Write ``preempt-rt.img`` to disk:
.. code-block:: console .. code-block:: none
$ sudo dd if=<path to preempt-rt.img> of=/dev/sda bs=4M oflag=sync status=progress $ sudo dd if=<path to preempt-rt.img> of=/dev/sda bs=4M oflag=sync status=progress
#. Copy the ``OVMF.fd`` and ``launch_hard_rt_vm.sh``: #. Copy the ``OVMF.fd`` and ``launch_hard_rt_vm.sh``:
.. code-block:: console .. code-block:: none
$ cp /usr/share/acrn/bios/OVMF.fd . $ cp /usr/share/acrn/bios/OVMF.fd .
$ cp /usr/share/acrn/samples/nuc/launch_hard_rt_vm.sh . $ cp /usr/share/acrn/samples/nuc/launch_hard_rt_vm.sh .
#. Launch the Preempt-RT User VM: #. Launch the Preempt-RT User VM:
.. code-block:: console .. code-block:: none
$ chmod +x launch_hard_rt_vm.sh $ chmod +x launch_hard_rt_vm.sh
$ ./launch_hard_rt_vm.sh $ ./launch_hard_rt_vm.sh