diff --git a/doc/getting-started/getting-started.rst b/doc/getting-started/getting-started.rst index bdff566d3..cfe5f7369 100644 --- a/doc/getting-started/getting-started.rst +++ b/doc/getting-started/getting-started.rst @@ -38,15 +38,15 @@ Before you begin, make sure your machines have the following prerequisites: * Software specifications - - Ubuntu Desktop 22.04 LTS (ACRN development is not supported on Windows.) + - Ubuntu Desktop 24.04 LTS (ACRN development is not supported on Windows.) **Target system**: * Hardware specifications - Target board (see :ref:`hardware_tested`) - - Ubuntu Desktop 22.04 LTS bootable USB disk: download the latest `Ubuntu - Desktop 22.04 LTS ISO image `__ and + - Ubuntu Desktop 24.04 LTS bootable USB disk: download the latest `Ubuntu + Desktop 24.04 LTS ISO image `__ and follow the `Ubuntu documentation `__ for creating the USB disk. @@ -75,7 +75,7 @@ Prepare 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 - Desktop 22.04 is running: + Desktop 24.04 is running: .. code-block:: bash @@ -117,10 +117,10 @@ To set up the ACRN build environment on the development computer: python3 python3-pip libblkid-dev e2fslibs-dev \ pkg-config libnuma-dev libcjson-dev liblz4-tool flex bison \ xsltproc clang-format bc libpixman-1-dev libsdl2-dev libegl-dev \ - libgles-dev libdrm-dev gnu-efi libelf-dev \ + libgles-dev libdrm-dev gnu-efi libelf-dev liburing-dev \ build-essential git-buildpackage devscripts dpkg-dev equivs lintian \ apt-utils pristine-tar dh-python python3-lxml python3-defusedxml \ - python3-tqdm python3-xmlschema python3-elementpath acpica-tools + python3-tqdm python3-xmlschema python3-elementpath acpica-tools #. Get the ACRN hypervisor and ACRN kernel source code, and check out the current release branch. @@ -130,12 +130,12 @@ To set up the ACRN build environment on the development computer: cd ~/acrn-work git clone https://github.com/projectacrn/acrn-hypervisor.git cd acrn-hypervisor - git checkout release_3.2 + git checkout release_3.3 cd .. git clone https://github.com/projectacrn/acrn-kernel.git cd acrn-kernel - git checkout release_3.2 + git checkout release_3.3 .. _gsg-board-setup: @@ -175,19 +175,19 @@ To set up the target hardware environment: Example of a target system with cables connected: -.. image:: ./images/gsg_vecow.png +.. image:: ./images/gsg_asus_minipc64.png :align: center Install OS on the Target ============================ -The target system needs Ubuntu Desktop 22.04 LTS to run the Board Inspector +The target system needs Ubuntu Desktop 24.04 LTS to run the Board Inspector tool. You can read the full instructions to download, create a bootable USB drive, and `Install Ubuntu desktop `_ on the Ubuntu site. We'll provide a summary here: -To install Ubuntu 22.04: +To install Ubuntu 24.04: #. Insert the Ubuntu bootable USB disk into the target system. @@ -247,9 +247,9 @@ Configure Target BIOS Settings #. Boot your target and enter the BIOS configuration editor. Tip: When you are booting your target, you'll see an option (quickly) to - enter the BIOS configuration editor, typically by pressing :kbd:`F2` during - the boot and before the GRUB menu (or Ubuntu login screen) appears. If you - are not quick enough, you can reboot the system to try again. + enter the BIOS configuration editor, typically by pressing :kbd:`F2` or :kbd:`DEL` during + the boot and before the GRUB menu (or Ubuntu login screen) appears. If you + are not quick enough, you can still choose ``UEFI settings`` in the GRUB menu. #. Configure these BIOS settings: @@ -339,7 +339,7 @@ Generate a Scenario Configuration File and Launch Script ******************************************************** In this step, you will download, install, and use the `ACRN Configurator -`__ +`__ to generate a scenario configuration file and launch script. A **scenario configuration file** is an XML file that holds the parameters of @@ -355,7 +355,7 @@ post-launched User VM. Each User VM has its own launch script. .. code-block:: bash cd ~/acrn-work - wget https://github.com/projectacrn/acrn-hypervisor/releases/download/v3.2/acrn-configurator-3.2.deb -P /tmp + wget https://github.com/projectacrn/acrn-hypervisor/releases/download/v3.3/acrn-configurator-3.3.deb -P /tmp If you already have a previous version of the acrn-configurator installed, you should first remove it: @@ -368,7 +368,7 @@ post-launched User VM. Each User VM has its own launch script. .. code-block:: bash - sudo apt install -y /tmp/acrn-configurator-3.2.deb + sudo apt install -y /tmp/acrn-configurator-3.3.deb #. Launch the ACRN Configurator: @@ -433,7 +433,7 @@ post-launched User VM. Each User VM has its own launch script. :class: drop-shadow The Configurator does consistency and validation checks when you load or save - a scenario. Notice the Hypervisor and VM1 tabs both have an error icon, + a scenario. Notice the Hypervisor and VM1 tabs both have an error icon, meaning there are issues with configuration options in two areas. Since the Hypervisor tab is currently highlighted, we're seeing an issue we can resolve on the Hypervisor settings. Once we resolve all the errors and save the @@ -466,26 +466,25 @@ post-launched User VM. Each User VM has its own launch script. #. Confirm that the **VM type** is ``Standard``. In the previous step, ``STD`` in the VM name is short for Standard. - #. Scroll down to **Memory size (MB)** and change the value to ``2048``. For - this example, we will use Ubuntu 22.04 to boot the post-launched VM. - Ubuntu 22.04 needs at least 2048 MB to boot. + #. Scroll down to **Memory size (MB)** and change the value to ``4096``. For + this example, we will use Ubuntu 24.04 to boot the post-launched VM. + Ubuntu 24.04 needs at least 4096 MB to boot. #. For **Physical CPU affinity**, select pCPU ID ``0``, then click **+** and select pCPU ID ``1`` to affine (or pin) the VM to CPU cores 0 and 1. (That will resolve the missing physical CPU affinity assignment error.) #. For **Virtio console device**, click **+** to add a device and keep the - default options. This parameter specifies the console that you will use to - log in to the User VM later in this guide. + default options. #. For **Virtio block device**, click **+** and enter - ``/home/acrn/acrn-work/ubuntu-22.04.2-desktop-amd64.iso``. This parameter + ``/home/acrn/acrn-work/user-vm1.img``. This 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. (If you used + in this guide, you will create the image file to that directory. (If you used a different username when installing Ubuntu on the target system, here's where you'll need to change the ``acrn`` username to the username you used.) - .. image:: images/configurator_postvm01.png + .. image:: images/configurator-postvm01.png :align: center :class: drop-shadow @@ -572,10 +571,10 @@ Build ACRN cd .. ls *acrn-service-vm*.deb - linux-headers-5.15.71-acrn-service-vm_5.15.71-acrn-service-vm-1_amd64.deb - linux-image-5.15.71-acrn-service-vm_5.15.71-acrn-service-vm-1_amd64.deb - linux-image-5.15.71-acrn-service-vm-dbg_5.15.71-acrn-service-vm-1_amd64.deb - linux-libc-dev_5.15.71-acrn-service-vm-1_amd64.deb + linux-headers-6.1.80-acrn-service-vm_6.1.80-acrn-service-vm-1_amd64.deb + linux-image-6.1.80-acrn-service-vm_6.1.80-acrn-service-vm-1_amd64.deb + linux-image-6.1.80-acrn-service-vm-dbg_6.1.80-acrn-service-vm-1_amd64.deb + linux-libc-dev_6.1.80-acrn-service-vm-1_amd64.deb #. Use the ``scp`` command to copy files from your development computer to the target system. Replace ``10.0.0.200`` with the target system's IP address @@ -622,7 +621,7 @@ Install ACRN The target system will reboot into the ACRN hypervisor and start the Ubuntu Service VM. -#. Confirm that you see the GRUB menu with "Ubuntu with ACRN hypervisor, with Linux 5.15.71-acrn-service-vm (ACRN 3.2)" +#. Confirm that you see the GRUB menu with "Ubuntu with ACRN hypervisor, with Linux 6.1.80-acrn-service-vm (ACRN 3.3)" entry. Select it and proceed to booting ACRN. (It may be auto-selected, in which case it will boot with this option automatically in 5 seconds.) @@ -634,10 +633,12 @@ Install ACRN ──────────────────────────────────────────────────────────────────────────────── Ubuntu Advanced options for Ubuntu - Ubuntu-ACRN Board Inspector, with Linux 5.15.71-acrn-service-vm - Ubuntu-ACRN Board Inspector, with Linux 5.15.0-56-generic - *Ubuntu with ACRN hypervisor, with Linux 5.15.71-acrn-service-vm (ACRN 3.2) - Ubuntu with ACRN hypervisor, with Linux 5.15.0-56-generic (ACRN 3.2) + Ubuntu-ACRN Board Inspector, with Linux 6.8.0-35-generic + Ubuntu-ACRN Board Inspector, with Linux 6.1.80-acrn-service-vm + Memory test (memtest86+x64.efi) + Memory test (memtest86+x64.efi, serial console) + Ubuntu with ACRN hypervisor, with Linux 6.8.0-35-generic (ACRN 3.3) + *Ubuntu with ACRN hypervisor, with Linux 6.1.80-acrn-service-vm (ACRN 3.3) UEFI Firmware Settings .. _gsg-run-acrn: @@ -686,21 +687,24 @@ The ACRN hypervisor boots the Ubuntu Service VM automatically. Launch the User VM ******************* -#. On the target system, use the web browser to visit the `official Ubuntu website `__ and - get the Ubuntu Desktop 22.04 LTS ISO image - ``ubuntu-22.04.2-desktop-amd64.iso`` for the User VM. (The same image you - specified earlier in the ACRN Configurator UI.) Alternatively, instead of - downloading it again, you could use ``scp`` to copy the ISO - image file from the development system to the ``~/acrn-work`` directory on the target system. +#. On the target system, download the Ubuntu cloud images ``noble-server-cloudimg-amd64.img`` + for the User VM into the ``~/acrn-work/`` directory (the location we said + in the ACRN Configurator for the scenario configuration for the VM): -#. If you downloaded the ISO file on the target system, copy it from the - Downloads directory to the ``~/acrn-work/`` directory (the location we said - in the ACRN Configurator for the scenario configuration for the VM), for - example: + .. code-block:: bash + + cd ~/acrn-work/ + wget https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img ./ + +#. We need to do some steps before booting into cloud image User VM: Set up username and password both to ``acrn``; + Change the image format to ``raw`` and change the image size: .. code-block:: bash - cp ~/Downloads/ubuntu-22.04.2-desktop-amd64.iso ~/acrn-work + sudo apt install qemu-utils guestfs-tools + sudo virt-customize -a ./noble-server-cloudimg-amd64.img --run-command 'useradd -m -s /bin/bash acrn' --run-command 'echo "acrn:acrn" | chpasswd' --run-command 'systemctl disable systemd-networkd-wait-online.service' + qemu-img convert -f qcow2 -O raw ./noble-server-cloudimg-amd64.img ./user-vm1.img + qemu-img -f raw ./user-vm1.img 16G #. Launch the User VM: @@ -710,66 +714,30 @@ Launch the User VM sudo ~/acrn-work/launch_user_vm_id1.sh #. It may take about a minute for the User VM to boot and start running the - Ubuntu image. You will see a lot of output, then the console of the User VM + Ubuntu image. You will see a lot of output, then the console of the User VM will appear as follows: - + .. code-block:: console - Ubuntu 22.04.2 LTS ubuntu hvc0 + Ubuntu 24.04 LTS ubuntu hvc0 ubuntu login: -#. Log in to the User VM. For the Ubuntu 22.04 ISO, the user is ``ubuntu``, and - there's no password. - -#. Confirm that you see output similar to this example: - - .. code-block:: console - - Welcome to Ubuntu 22.04.2 LTS (GNU/Linux 5.19.0-32-generic x86_64) - - * Documentation: https://help.ubuntu.com - * Management: https://landscape.canonical.com - * Support: https://ubuntu.com/advantage - - Expanded Security Maintenance for Applications is not enabled. - - 0 updates can be applied immediately. - - Enable ESM Apps to receive additional future security updates. - See https://ubuntu.com/esm or run: sudo pro status - - - The list of available updates is more than a week old. - To check for new updates run: sudo apt update - - The programs included with the Ubuntu system are free software; - the exact distribution terms for each program are described in the - individual files in /usr/share/doc/*/copyright. - - Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by - applicable law. - - To run a command as administrator (user "root"), use "sudo ". - See "man sudo_root" for details. - - 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: + command to see that the User VM is running the downloaded Ubuntu image: .. code-block:: console - ubuntu@ubuntu:~$ uname -r - 5.19.0-32-generic + acrn@ubuntu:~$ uname -r + 6.8.0-36-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.15.71-acrn-service-vm + acrn@asus-MINIPC-PN64:~$ uname -r + 6.1.80-acrn-service-vm The User VM has launched successfully. You have completed this ACRN setup. diff --git a/doc/getting-started/images/configurator-postvm01.png b/doc/getting-started/images/configurator-postvm01.png new file mode 100755 index 000000000..7d03c0fe5 Binary files /dev/null and b/doc/getting-started/images/configurator-postvm01.png differ diff --git a/doc/getting-started/images/configurator-postvm02.png b/doc/getting-started/images/configurator-postvm02.png index ebe14944b..180f6573f 100644 Binary files a/doc/getting-started/images/configurator-postvm02.png and b/doc/getting-started/images/configurator-postvm02.png differ diff --git a/doc/getting-started/images/gsg_asus_minipc64.png b/doc/getting-started/images/gsg_asus_minipc64.png new file mode 100755 index 000000000..a6f6ea8b6 Binary files /dev/null and b/doc/getting-started/images/gsg_asus_minipc64.png differ diff --git a/doc/getting-started/images/gsg_ubuntu_install_01.png b/doc/getting-started/images/gsg_ubuntu_install_01.png index c3e8f824c..19c80ec47 100644 Binary files a/doc/getting-started/images/gsg_ubuntu_install_01.png and b/doc/getting-started/images/gsg_ubuntu_install_01.png differ diff --git a/doc/getting-started/images/gsg_ubuntu_install_02.png b/doc/getting-started/images/gsg_ubuntu_install_02.png index e09733de1..ebb2bf758 100644 Binary files a/doc/getting-started/images/gsg_ubuntu_install_02.png and b/doc/getting-started/images/gsg_ubuntu_install_02.png differ