diff --git a/doc/tutorials/using_ubuntu_as_sos.rst b/doc/tutorials/using_ubuntu_as_sos.rst index 802fa7e59..ee3d623ec 100644 --- a/doc/tutorials/using_ubuntu_as_sos.rst +++ b/doc/tutorials/using_ubuntu_as_sos.rst @@ -70,7 +70,7 @@ the source code, build it, and install it on your device. make PLATFORM=uefi sudo make install - For more details, please refer to the :ref:`getting_started`. + For more details, please refer to the :ref:`getting-started-apl-nuc`. #. Install the hypervisor @@ -109,11 +109,19 @@ the source code, build it, and install it on your device. sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 \ -L "ACRN Hypervisor" -u "bootloader=\EFI\ubuntu\grubx64.efi" - # Verify that the "ACRN Hypervisor" will be booted first + + #. Verify that the "ACRN Hypervisor" is added and make sure it will be booted first + + .. code-block:: none + sudo efibootmgr -v - You can change the boot order at any time using ``efibootmgr + #. You can change the boot order at any time using ``efibootmgr -o XXX,XXX,XXX`` + + .. code-block:: none + + sudo efibootmgr -o xxx,xxx,xxx .. note:: By default, the “ACRN Hypervisor” you have just added should be @@ -125,26 +133,41 @@ Install the Service OS kernel You can download latest Service OS kernel from ``_ -(**We need to update the URL to one that is known to work, and matches the -tag/release we use above!!!**). We will extract it and install it in the next -few steps. -a. Download and extract the Service OS kernel +1. Download the latest Service OS kernel from the latest Clear Linux release + from this area: + https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages. Look for an + ``.rpm`` file named ``linux-pk414-sos--.x86_64.rpm``. + + While we recommend using the "current" (latest) release of Clear Linux, you can download + a specific Clear Linux release from an area with that release number, e.g.: + https://download.clearlinux.org/releases/24040/clear/x86_64/os/linux-pk414-sos-4.14.57-69.x86_64.rpm + +2. Download Specific Service OS kenrel from specific Clear Linux release: + https://download.clearlinx.org/release//clear/x86_64/os/Packages. + e.g.: + Clear-linux-release = 24040 + ``_ + + .. note:: + in this guide, we use and recommend people downloading latest release from "current" path + +#. Download and extract the latest Service OS kernel(for example: current=24040) .. code-block:: none mkdir ~/kernel-build cd ~/kernel-build - wget https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages/linux-pk414-sos-4.14.41-39.x86_64.rpm + wget https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages/linux-pk414-sos-4.14.57-69.x86_64.rpm sudo apt-get install rpm2cpio - rpm2cpio linux-pk414-sos-4.14.41-39.x86_64.rpm | cpio -idmv + rpm2cpio linux-pk414-sos-4.14.57-69.x86_64.rpm | cpio -idmv #. Install the SOS kernel and its drivers (modules) .. code-block:: none - sudo cp -r ~/kernel-build/usr/lib/modules/4.14.41-39.pk414-sos/ /lib/modules/ - sudo cp ~/kernel-build/usr/lib/kernel/org.clearlinux.pk414-sos.4.14.41-39 /boot/acrn/ + sudo cp -r ~/kernel-build/usr/lib/modules/4.14.57-69.pk414-sos/ /lib/modules/ + sudo cp ~/kernel-build/usr/lib/kernel/org.clearlinux.pk414-sos.4.14.57-69 /boot/acrn/ #. Configure Grub to load the Service OS kernel @@ -158,21 +181,21 @@ a. Download and extract the Service OS kernel load_video insmod gzio insmod part_gpt - insmod ext4 - linux /boot/acrn/org.clearlinux.pk414-sos.4.14.41-39 pci_devices_ignore=(0:18:1) maxcpus=1 console=tty0 console=ttyS0 - i915.nuclear_pageflip=1 root=PARTUUID= rw rootwait ignore_loglevel no_timer_check consoleblank=0 - i915.tsd_init=7 i915.tsd_delay=2000 i915.avail_planes_per_pipe=0x00000F i915.domain_plane_owners=0x011111110000 - i915.enable_guc_loading=0 i915.enable_guc_submission=0 i915.enable_preemption=1 i915.context_priority_mode=2 - i915.enable_gvt=1 hvlog=2M@0x1FE00000 + insmod ext2 + linux /EFI/org.clearlinux/kernel-org.clearlinux.pk414-sos.4.14.57-69 pci_devices_ignore=(0:18:1) maxcpus=1 console=tty0 console=ttyS0 i915.nuclear_pageflip=1 root=PARTUUID= rw rootwait ignore_loglevel no_timer_check consoleblank=0 i915.tsd_init=7 i915.tsd_delay=2000 i915.avail_planes_per_pipe=0x01010F i915.domain_plane_owners=0x011111110000 i915.enable_guc_loading=0 i915.enable_guc_submission=0 i915.enable_preemption=1 i915.context_priority_mode=2 i915.enable_gvt=1 i915.enable_initial_modeset=1 hvlog=2M@0x1FE00000 } - .. note:: + .. note:: You need to adjust this to use your partition UUID (``PARTUUID``) for the ``root=`` parameter (or use the device node directly). - .. note:: + .. note:: You will also need to adjust the kernel name if you used a different RPM file as the source of your Service OS kernel. + + .. note:: + The command line for the kernel in /etc/grub.d/40_custom should be all + as a single line, not as multiple lines. Otherwise the kernel will fail to boot * Update Grub on your system @@ -195,6 +218,15 @@ a. Download and extract the Service OS kernel entry. Select it and proceed to booting the platform. The system will start the Ubuntu Desktop and you can now log in (as before). + .. note:: + if you are not seeing Grub menu after reboot system, you may go into a wrong boot entry + you may need to select “ACRN Hypervisor” manually by entering the EFI firmware at boot (using :kbd:`F10`) + + .. note:: + for the first time reboot after install ACRN, you may see Black Screen after boot up succusfully + don't worry about that, this is known issue becaue of fb mode is disabled, wait a moment + the Ubuntu desktop will be displayed + To check if the hypervisor is effectively running, check ``dmesg``. The typical output of a successful installation will look like this: @@ -207,30 +239,30 @@ a. Download and extract the Service OS kernel Prepare the User OS (UOS) ************************* -We are using a User OS based on `Clear Linux`_. +For the User OS, we are using the same `Clear Linux`_ release version as the Service OS. * Download the Clear Linux image from ``_ .. code-block:: none cd ~ - wget https://download.clearlinux.org/releases/22780/clear/clear-22780-kvm.img.xz - unxz clear-22780-kvm.img.xz + wget https://download.clearlinux.org/releases/current/clear/clear-24040-kvm.img.xz + unxz clear-24040-kvm.img.xz * Download the Production Kenrel (PK) kernel .. code-block:: none - wget https://download.clearlinux.org/releases/22780/clear/x86_64/os/Packages/linux-pk414-standard-4.14.47-44.x86_64.rpm - rpm2cpio linux-pk414-standard-4.14.47-44.x86_64.rpm | cpio -idmv + wget https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages/linux-pk414-standard-4.14.57-69.x86_64.rpm + rpm2cpio linux-pk414-standard-4.14.57-69.x86_64.rpm | cpio -idmv * Update the UOS kernel modules .. code-block:: none - sudo losetup -f -P --show /root/clear-22789-kvm.img + sudo losetup -f -P --show /root/clear-24040-kvm.img sudo mount /dev/loop0p3 /mnt - sudo cp -r /root/usr/lib/modules/4.14.47-44.pk414-standard /mnt/lib/modules/ + sudo cp -r /root/usr/lib/modules/4.14.57-69.pk414-standard /mnt/lib/modules/ sudo cp -r /root/usr/lib/kernel /lib/modules/ sudo umount /mnt sync @@ -255,18 +287,57 @@ We are using a User OS based on `Clear Linux`_. .. code-block:: none - -s 3,virtio-blk,/root/clear-22780-kvm.img - -k /lib/modules/kernel/org.clearlinux.pk414-standard.4.14.47-44 + -s 3,virtio-blk,/root/clear-24040-kvm.img + -k /lib/modules/kernel/org.clearlinux.pk414-standard.4.14.57-69 Start the User OS (UOS) *********************** You are now all set to start the User OS (UOS) -.. code-block:: none + .. code-block:: none sudo /usr/share/acrn/samples/nuc/launch_uos.sh **Congratulations**, you are now watching the User OS booting up! + +Enabling network sharing +************************ + +After booting up SOS and UOS, enabling network sharing is must to test networking in UOS side. +enabling the tap and networking bridge in the SOS, you can create a script file to setup. +below is an example for you reference:(verifed in Ubuntu 14.04 and 16.04 as the SOS) + + .. code-block:: none + + #!/bin/bash + #setup bridge for uos network + br=$(brctl show | grep acrn-br0) + br=${br-:0:6} + ip tuntap add dev acrn_tap0 mode tap + + taps=$(ifconfig | grep acrn_ | awk '{print $1}') + + # if bridge not existed + if [ "$br"x != "acrn-br0"x ]; then + #setup bridge for uos network + brctl addbr acrn-br0 + brctl addif acrn-br0 enp3s0 + ifconfig enp3s0 0 + dhclient acrn-br0 + # add existing tap devices under the bridge + for tap in $taps; do + ip tuntap add dev acrn_$tap mode tap + brctl addif acrn-br0 $tap + ip link set dev $tap down + ip link set dev $tap up + done + fi + + brctl addif acrn-br0 acrn_tap0 + ip link set dev acrn_tap0 up + +Enabling USB keyboard and mouse for UOS, please :ref:`getting-started-apl-nuc` + .. _Clear Linux: https://clearlinux.org