update doc -Using Ubuntu as the Service OS

1, update contents to align latest acrn and clear Linux release
2, change /etc/grub.d/40_custom file to specify 'insmod ext2', not 'insmod ext4' and github issue- https://github.com/projectacrn/acrn-hypervisor/issues/707
3, add tap device and network sharing enabling script as the example for ubuntu SOS
4, add several tips for new user to use ubuntu as the SOS

Signed-off-by: ailun258 ailin.yang@intel.com

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
 `<https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages/>`_
-(**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-<kernel-version>-<build-version>.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-linux-release>/clear/x86_64/os/Packages.
+   e.g.:
+   Clear-linux-release = 24040
+   `<https://download.clearlinux.org/releases/24040/clear/x86_64/os/linux-pk414-sos-4.14.57-69.x86_64.rpm/>`_
+   
+ .. 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 -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.41-39 /boot/acrn/
+      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
+                insmod ext2
-                linux /boot/acrn/org.clearlinux.pk414-sos.4.14.41-39 pci_devices_ignore=(0:18:1) maxcpus=1 console=tty0 console=ttyS0
+                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=<UUID of rootfs partition> 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
-                i915.nuclear_pageflip=1 root=PARTUUID=<ID of rootfs partition> 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
         }
 
-     .. 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 `<https://download.clearlinux.org>`_
 
   .. code-block:: none
 
      cd ~
-     wget https://download.clearlinux.org/releases/22780/clear/clear-22780-kvm.img.xz
+     wget https://download.clearlinux.org/releases/current/clear/clear-24040-kvm.img.xz
-     unxz clear-22780-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
+     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.47-44.x86_64.rpm | cpio -idmv
+     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
+     -s 3,virtio-blk,/root/clear-24040-kvm.img
-     -k /lib/modules/kernel/org.clearlinux.pk414-standard.4.14.47-44
+     -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