diff --git a/doc/develop.rst b/doc/develop.rst index d2bed42aa..d05255748 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -61,6 +61,7 @@ Configuration Tutorials user-guides/kernel-parameters user-guides/acrn-dm-parameters misc/packaging/README + tutorials/tar_installation Advanced Features ******************** diff --git a/doc/tutorials/tar_installation.rst b/doc/tutorials/tar_installation.rst new file mode 100644 index 000000000..5b6eb712e --- /dev/null +++ b/doc/tutorials/tar_installation.rst @@ -0,0 +1,250 @@ +.. _tar_installation: + +ACRN Installation via Tar Files +#################################### + +Project ACRN offers two ways to install ACRN on target systems, either via +Debian packages or tar files. This document covers the tar file method. For +information about the Debian method, see :ref:`debian_packaging`. + +Tar files provide a way to package ACRN configurations for Linux +target systems running non-Debian operating systems. You generate the tar +files on your development computer, copy them to your target system, +extract the tar files to the right places, +and reboot the system with ACRN up and running. + +This document shows examples of commands used to build and install the tar +files. You might need to modify the commands for your environment. + +Prerequisites +************* + +* A development computer configured according to the :ref:`gsg` (for example, it + has an Ubuntu OS, ACRN dependencies, and ACRN hypervisor and kernel source + code from the ACRN GitHub repository). + +Build the Tar Files +*************************** + +#. On your development computer, navigate to the ``acrn-hypervisor`` source code + directory and build the ACRN hypervisor tar files. Replace + ```` and ```` with the paths to your board + configuration file and scenario configuration file. + + .. code-block:: bash + + cd ~/acrn-work/acrn-hypervisor + make -j $(nproc) BOARD= SCENARIO= + make targz-pkg + + The build typically takes a few minutes. By default, the build results are + found in the ``build`` directory. + +#. Navigate to the ``acrn-kernel`` source code directory and build the ACRN + kernel tar files for the Service VM: + + .. code-block:: bash + + cd ~/acrn-work/acrn-kernel + cp kernel_config_service_vm .config + make olddefconfig + make -j $(nproc) targz-pkg + + 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. By default, the build results are found in the current directory. + +Install and Run ACRN +************************** + +In the following steps, you will install the tar files, install the serial +configuration tool, configure GRUB, and run ACRN on the target system. + +#. Copy all the necessary files generated on the development computer to the + target system. The following steps show how to copy via USB disk; feel free + to use a different method. Modify the file names in the following commands to + match your files. + + a. Insert the USB disk into the development computer and run these commands: + + .. code-block:: bash + + cd ~/acrn-work/acrn-kernel + disk="/media/$USER/"$(ls /media/$USER) + cp linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz "$disk"/ + cp ~/acrn-work/acpica-unix-20210105/generate/unix/bin/iasl "$disk"/ + cp ~/acrn-work/acrn-hypervisor/build/acrn-2.8-unstable.tar.gz "$disk"/ + sync && sudo umount "$disk"/ + + #. Insert the USB disk you just used into the target system and run these + commands to copy the files locally: + + .. code-block:: bash + + disk="/media/$USER/"$(ls /media/$USER) + cp "$disk"/linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz ~/acrn-work + cp "$disk"/acrn-2.8-unstable.tar.gz ~/acrn-work + sudo cp "$disk"/iasl /usr/sbin/ + sync && sudo umount "$disk"/ + +#. Extract the Service VM files onto the target system: + + .. code-block:: bash + + cd ~/acrn-work + sudo tar -zxvf linux-5.10.90-acrn-service-vm-206626-g140f5035e1b1-x86.tar.gz -C / --keep-directory-symlink + +#. Extract the ACRN tools and images: + + .. code-block:: bash + + sudo tar -zxvf acrn-2.8-unstable.tar.gz -C / --keep-directory-symlink + +#. Copy the ACRN bin file to the boot directory. Replace ```` and + ```` to match your file. + + .. code-block:: bash + + sudo mkdir -p /boot/acrn/ + sudo cp /usr/lib64/acrn/acrn...bin /boot/acrn + +#. Install the serial configuration tool in the target system as follows: + + .. code-block:: bash + + sudo apt install setserial + +#. Find the root filesystem (rootfs) device name by using the + ``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 + + 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. Replace ```` + and ```` to match your bin file. Confirm the module2 file name + matches the file in your ``boot`` directory. + + .. code-block:: bash + :emphasize-lines: 6,8,9 + + 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.90-acrn-service-vm-206626-g140f5035e1b1 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.my_board.shared.bin root=PARTUUID="03db7f45-8a6c-454b-adf7-30343d82c4f4" + module2 /boot/vmlinuz-5.10.90-acrn-service-vm-206626-g140f5035e1b1 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 + +#. Confirm that you see the GRUB menu with the "ACRN Multiboot Ubuntu Service + VM" entry. Select it and proceed to booting ACRN. (It may be autoselected, in + which case it will boot with this option automatically in 5 seconds.) + + .. code-block:: console + :emphasize-lines: 6 + + GNU GRUB version 2.04 + ──────────────────────────────────────────────────────────────────────────────── + Ubuntu + Advanced options for Ubuntu + UEFI Firmware Settings + *ACRN Multiboot Ubuntu Service VM \ No newline at end of file