diff --git a/doc/getting-started/getting-started.rst b/doc/getting-started/getting-started.rst index f2d0acbca..b821fac24 100644 --- a/doc/getting-started/getting-started.rst +++ b/doc/getting-started/getting-started.rst @@ -34,7 +34,7 @@ Before you begin, make sure your machines have the following prerequisites: * Hardware specifications - - A PC with Internet access (A fast system with multiple cores and 16MB + - A PC with Internet access (A fast system with multiple cores and 16GB memory or more will make the builds go faster.) * Software specifications @@ -55,7 +55,6 @@ Before you begin, make sure your machines have the following prerequisites: - USB keyboard and mouse - Monitor - Ethernet cable and Internet access - - Serial-to-USB cable to view the ACRN and VM console (optional) - A second USB disk with minimum 1GB capacity to copy files between the development computer and target system - Local storage device (NVMe or SATA drive, for example) @@ -72,10 +71,6 @@ To set up the hardware environment: #. Connect the target system to the LAN with the Ethernet cable. -#. (Optional) Connect the serial cable between the target and development - computer to view the ACRN and VM console (for an example, see - :ref:`connect_serial_port`). - Example of a target system with cables connected: .. image:: ./images/gsg_nuc.png @@ -215,7 +210,7 @@ To install Ubuntu 18.04: .. image:: ./images/gsg_ubuntu_install_01.png -#. Use the checkboxes to choose whether you'd like to install Ubuntu alongside +#. Use the check boxes to choose whether you'd like to install Ubuntu alongside another operating system, or delete your existing operating system and replace it with Ubuntu: @@ -242,20 +237,10 @@ Configure Target BIOS Settings assist for CPU virtualization). * Enable **VT-d** (Intel Virtualization Technology for Directed I/O, which provides additional support for managing I/O virtualization). - * Disable **Secure Boot**. This simplifies the steps for this example. + * Disable **Secure Boot**. This setting simplifies the steps for this example. The names and locations of the BIOS settings differ depending on the target - hardware and BIOS version. You can search for the items in the BIOS - configuration editor. - - For example, on a Tiger Lake NUC, quickly press :kbd:`F2` while the system - is booting. (If the GRUB menu or Ubuntu login screen - appears, press :kbd:`CTRL` + :kbd:`ALT` + :kbd:`DEL` to reboot again and - press :kbd:`F2` sooner.) The settings are in the following paths: - - * **System Agent (SA) Configuration** > **VT-d** > **Enabled** - * **CPU Configuration** > **VMX** > **Enabled** - * **Boot** > **Secure Boot** > **Secure Boot** > **Disabled** + hardware and BIOS version. #. Set other BIOS settings, such as Hyper-Threading, depending on the needs of your application. @@ -323,7 +308,7 @@ Generate a Board Configuration File ls /media/$USER - Confirm that one disk name appears. You'll use that disk name in + Confirm that only one disk name appears. You'll use that disk name in the following steps. #. Copy the board inspector tool folder from the acrn-hypervisor source code to the USB disk: @@ -361,7 +346,9 @@ Generate a Board Configuration File sudo python3 board_inspector.py my_board #. Confirm that the board configuration file ``my_board.xml`` was generated - in the current directory. + in the current directory:: + + ls ./my_board.xml #. Copy ``my_board.xml`` from the target to the development computer via USB disk as follows: @@ -390,7 +377,7 @@ Generate a Board Configuration File .. rst-class:: numbered-step -Generate a Scenario Configuration File and Launch Script +Generate a Scenario Configuration File and Launch Scripts ********************************************************* You use the **ACRN configurator** to generate scenario configuration files and @@ -400,9 +387,10 @@ A **scenario configuration file** is an XML file that holds the parameters of a specific ACRN configuration, such as the number of VMs that can be run, their attributes, and the resources they have access to. -A **launch script** is a shell script that is used to create a User VM. +A **launch script** is a shell script that is used to configure and create a +User VM. Each User VM has its own launch script. -To generate a scenario configuration file and launch script: +To generate a scenario configuration file and launch scripts: #. On the development computer, install ACRN configurator dependencies: @@ -438,7 +426,7 @@ To generate a scenario configuration file and launch script: :class: drop-shadow #. In the dialog box, select **shared** as the default scenario setting and - then click **OK**. + then click **OK**. This sample default scenario defines six User VMs. .. image:: ./images/gsg_config_scenario_load.png :class: drop-shadow @@ -455,16 +443,17 @@ To generate a scenario configuration file and launch script: #. In the dialog box, keep the default name as is. Type ``/home//acrn-work`` in the Scenario XML Path field. In the - following example, acrn is the username. Click **Submit** to save the + following example, ``acrn`` is the username. Click **Submit** to save the file. .. image:: ./images/gsg_config_scenario_save.png :class: drop-shadow - #. Confirm that ``shared.xml`` appears in the directory - ``/home//acrn-work``. + #. Confirm that ``shared.xml`` appears in your ``acrn-work`` directory:: -#. Generate the launch script: + ls ~/acrn-work/shared.xml + +#. Generate the launch scripts: a. Click the **Launch Setting** menu on the top banner of the UI and select **Load a default launch script**. @@ -473,7 +462,8 @@ To generate a scenario configuration file and launch script: :class: drop-shadow #. In the dialog box, select **shared_launch_6uos** as the default launch - setting and click **OK**. + setting and click **OK**. Because our sample ``shared`` scenario defines six + User VMs, we're using this ``shared_launch_6uos`` launch XML configuration. .. image:: ./images/gsg_config_launch_load.png :class: drop-shadow @@ -490,8 +480,9 @@ To generate a scenario configuration file and launch script: .. image:: ./images/gsg_config_launch_save.png :class: drop-shadow - #. Confirm that ``launch_uos_id3.sh`` appears in the directory - ``/home//acrn-work/my_board/output/``. + #. Confirm that ``launch_uos_id3.sh`` appears in the expected output directory:: + + ls ~/acrn-work/my_board/output/launch_uos_id3.sh #. Close the browser and press :kbd:`CTRL` + :kbd:`C` to terminate the ``acrn_configurator.py`` program running in the terminal window. @@ -523,7 +514,7 @@ Build ACRN make -j $(nproc) targz-pkg The kernel build can take 15 minutes or less on a fast computer, but could - take 1-3 hours depending on the performance of your development computer. + take an hour or more depending on the performance of your development computer. #. Copy all the necessary files generated on the development computer to the target system by USB disk as follows: @@ -540,6 +531,9 @@ Build ACRN cp ~/acrn-work/acrn-hypervisor/build/acrn-2.6-unstable.tar.gz $disk/ sync && sudo umount $disk/ + Even though our sample default scenario defines six User VMs, we're only + going to launch one of them, so we'll only need the one launch script. + #. Insert the USB disk you just used into the target system and run these commands to copy the tar files locally: @@ -556,6 +550,10 @@ Build ACRN cd ~/acrn-work sudo tar -zxvf linux-5.10.52-acrn-sos-x86.tar.gz -C / --keep-directory-symlink + This tar extraction replaces parts of the Ubuntu installation we installed + and used for running the board inspector, with the Linux kernel we built + based on the board and scenario configuration. + #. Extract the ACRN tools and images: .. code-block:: bash @@ -579,7 +577,7 @@ Install ACRN In the following steps, you will configure GRUB on the target system. -#. On the target, find the root file system (rootfs) device name by using the +#. On the target, find the root filesystem (rootfs) device name by using the ``lsblk`` command: .. code-block:: console @@ -719,9 +717,7 @@ In the following steps, you will configure GRUB on the target system. Run ACRN and the Service VM ****************************** -When the ACRN hypervisor starts to boot, the ACRN console log will be displayed -to the serial port (optional). The ACRN hypervisor boots the Ubuntu Service VM -automatically. +The ACRN hypervisor boots the Ubuntu Service VM automatically. #. On the target, log in to the Service VM. (It will look like a normal Ubuntu session.) @@ -755,7 +751,9 @@ Launch the User VM #. Put the ISO file in the path ``~/acrn-work/`` on the target system. -#. Open the launch script in a text editor. The following command uses vi, but +#. Even though our sample default scenario defines six User VMs, we're only + going to launch one of them. + Open the launch script in a text editor. The following command uses ``vi``, but you can use any text editor. .. code-block:: bash @@ -791,8 +789,9 @@ Launch the User VM sudo chmod +x /usr/sbin/iasl sudo ~/acrn-work/launch_uos_id3.sh -#. Confirm that you see the console of the User VM on the Service VM's terminal - (on the monitor connected to the target system). Example: +#. It will take a few seconds for the User VM to boot and start running the + Ubuntu image. Confirm that you see the console of the User VM on the Service + VM's terminal (on the monitor connected to the target system). Example: .. code-block:: console