doc: Add instruction for gsg_quick_setup.sh script.

An instruction is needed from gsg so that user could know where
to get the script and also how to use it to setup SOS, UOS automatically.

Signed-off-by: ruix.li <ruix.li@intel.com>

doc/getting-started/acrn_quick_setup.sh

@@ -174,7 +174,17 @@ function upgrade_uos()
     fi
 
     # Do upgrade UOS process.
-    if [[ $skip_download_uos == 1 ]]; then
+    if [[ $skip_download_uos != 1 ]]; then
+        cd ~
+        echo "Downloading UOS image: $uos_image_link"
+        curl $uos_image_link -o clear-$uos_ver-kvm.img.xz
+        if [[ $? -ne 0 ]]; then
+            echo "Download UOS failed."
+            rm clear-$uos_ver-kvm.img.xz
+            exit 1
+        fi
+    fi
+
     uos_img_xz=$(find ~/ -name clear-$uos_ver-kvm.img.xz)
     uos_img=$(find ~/ -name clear-$uos_ver-kvm.img)
     if [[ -f $uos_img ]] && [[ -f $uos_img.xz ]]; then echo "Moving $uos_img to $uos_img.old."; mv $uos_img $uos_img.old; fi
@@ -186,15 +196,6 @@ function upgrade_uos()
         unxz $uos_img_xz
         uos_img=`echo $uos_img_xz | sed 's/.xz$//g'`
     fi
-    else
-        cd ~
-        echo "Downloading UOS image: $uos_image_link"
-        curl $uos_image_link -o clear-$uos_ver-kvm.img.xz || echo "Download UOS failed." && rm clear-$uos_ver-kvm.img.xz && exit 1
-        uos_img=clear-$uos_ver-kvm.img
-        if [[ -f $uos_img ]] && [[ -f $uos_img.xz ]]; then echo "Moving $uos_img to $uos_img.old."; mv $uos_img $uos_img.old; fi
-        echo "Unxz UOS image: clear-$uos_ver-kvm.img.xz"
-        unxz clear-$uos_ver-kvm.img.xz
-    fi
 
     echo "Get UOS image: $uos_img"
     uos_partition=`losetup -f -P --show $uos_img`p3
@@ -204,12 +205,12 @@ function upgrade_uos()
     umount /mnt
     sync
 
-    cp -r /usr/share/acrn/samples/nuc/launch_uos.sh ~/
+    cp -r /usr/share/acrn/samples/nuc/launch_uos.sh ~/launch_uos_$uos_ver.sh
-    sed -i "s/\(virtio-blk.*\)\/home\/clear\/uos\/uos.img/\1$(echo $uos_img | sed "s/\//\\\\\//g")/" ~/launch_uos.sh
+    sed -i "s/\(virtio-blk.*\)\/home\/clear\/uos\/uos.img/\1$(echo $uos_img | sed "s/\//\\\\\//g")/" ~/launch_uos_$uos_ver.sh
-    [[ -z `grep $uos_img ~/launch_uos.sh` ]] && echo "Fail to replace uos image in launch script: ~/launch_uos.sh" && exit 1
+    [[ -z `grep $uos_img ~/launch_uos_$uos_ver.sh` ]] && echo "Fail to replace uos image in launch script: ~/launch_uos_$uos_ver.sh" && exit 1
     echo "Upgrade UOS done..."
     echo "Now you can run this command to start UOS..."
-    echo "# cd ~/ && ./launch_uos.sh"
+    echo "sudo /root/launch_uos_$uos_ver.sh"
     exit
 }
 

doc/getting-started/apl-nuc.rst

@@ -64,29 +64,206 @@ complete this setup.
    Please refer to the ACRN :ref:`release_notes` for the Clear Linux OS
    version number tested with a specific ACRN release.  Adjust the
    instruction below to reference the appropriate version number of Clear
-   Linux OS (we use version 27960 as an example).
+   Linux OS (we use version 28960 as an example).
 
 #. Download the compressed Clear Linux OS installer image from
-   https://download.clearlinux.org/releases/27960/clear/clear-27960-installer.img.xz
+   https://download.clearlinux.org/releases/28960/clear/clear-28960-installer.img.xz
    and follow the `Clear Linux OS installation guide
    <https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install>`__
    as a starting point for installing Clear Linux OS onto your platform. Follow the recommended
-   options for choosing an **Manual (Advanced)** installation type, and using the platform's
+   options for choosing an **Advanced options** installation type, and using the platform's
    storage as the target device for installation (overwriting the existing data
    and creating three partitions on the platform's storage drive).
 
    High-level steps should be:
 
-   #.  Install Clear Linux OS on a NUC using the "Manual (Advanced)" option.
+   #.  Launch the Clear Linux OS installer boot menu
-   #.  Use default partition scheme for storage
+   #.  With Clear Linux OS highlighted, select Enter.
-   #.  Name the host "clr-sos-guest"
+   #.  From the Main Menu, select "Configure Media" and set "Auto Partition" to your desired hard disk.
-   #.  Add an administrative user "clear" with "sudoers" privilege
+   #.  ``shift + A`` to the "Advanced options".
-   #.  Add these additional bundles "editors", "user-basic", "desktop-autostart", "network-basic"
+   #.  Select "Additional Bundle Selection" to add additional bundles "desktop-autostart", "editors", "network-basic", "user-basic"
-   #.  For network, choose "DHCP"
+   #.  Select "User Manager" to add an administrative user "clear"
+   #.  Select "Assign Hostname" to set the hostname as "clr-sos-guest"
 
 #. After installation is complete, boot into Clear Linux OS, login as
    **clear**, and set a password.
 
+#. The remaining instructions below provide detailed instructions on setting
+   up the ACRN Hypervisor, Service OS, and Guest OS.  We also provide an
+   automated script that does all these steps for you, so you can skip these
+   manual steps.  See the `quick-setup-guide`_ section below to use the
+   automated setup script.
+
+.. _quick-setup-guide:
+
+Use the script to set up ACRN automatically
+===========================================
+
+It is little complicate to setup the SOS or UOS, so we provide a script to do it quickly and automatically.
+You can find the script `here
+<https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/doc/getting-started/acrn_quick_setup.sh>`__
+and please note that should be run with root privilege since it will modify various system parameters.
+
+#. Installing Clear Linux and login system
+
+#. Open a terminal
+
+#. Download ``acrn_quick_setup.sh`` script to set up the SOS. If you don't need a proxy to
+   get the script, you can just skip the ``export`` command.
+
+   .. code-block:: console
+
+      $ export https_proxy=https://myproxy.mycompany.com:port
+      $ cd ~ && wget https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/doc/getting-started/acrn_quick_setup.sh
+      $ sudo sh acrn_quick_setup.sh -s 28960
+      Password:
+      Upgrading SOS...
+      Disable auto update...
+      Clear Linux version 28960 is already installed. Continuing to setup SOS...
+      Adding the service-os and kernel-iot-lts2018 bundles...
+        ...100%
+        ...100%
+        ...100%
+      none
+      Add /mnt/EFI/acrn folder
+      Copy /usr/share/acrn/samples/nuc/acrn.conf /mnt/loader/entries/
+      Copy /usr/lib/acrn/acrn.efi to /mnt/EFI/acrn
+      Check ACRN efi boot event
+      Clean all ACRN efi boot event
+      Check linux bootloader event
+      Clean all Linux bootloader event
+      Add new ACRN efi boot event
+      Create loader.conf
+      Add default (5 seconds) boot wait time
+      Add default boot to ACRN
+      Getting latest Service OS kernel version: kernel-org.clearlinux.iot-lts2018-sos.4.19.34-45
+      Getting current Service OS kernel version: kernel-org.clearlinux.iot-lts2018-sos.4.19.13-1901141830
+      Replacing root partition uuid in acrn.conf
+      Replace with new SOS kernel in acrn.conf
+      Service OS setup done!
+      Rebooting Service OS to take effects.
+      Rebooting.
+
+   .. note::
+      This script is using ``/dev/sda1`` as default EFI System Partition (ESP). The ESP
+      may be different based on your hardware and then you should specify it directly with ``-e`` option.
+      Here is an example for setup SOS on NVMe SSD: ``sudo sh acrn_quick_setup.sh -s 28960 -e /dev/nvme0n1p1``
+
+   .. note::
+      If you don't need reboot automatically after set up SOS, then you should run this command:
+      ``sudo sh acrn_quick_setup.sh -s 28960 -d``
+
+#. After the system reboots and login as the clear user, you may need to check the ``dmesg`` to make sure
+   the SOS is boot successfully.
+
+   .. code-block:: console
+
+      $ dmesg | grep ACRN
+      [    0.000000] Hypervisor detected: ACRN
+      [    1.220887] ACRNTrace: Initialized acrn trace module with 4 cpu
+      [    1.224401] ACRN HVLog: Initialized hvlog module with 4 cpu
+
+#. If you want to continue to set up a Guest OS after boot SOS, then you can run
+   ``sudo sh acrn_quick_setup.sh -u 28960`` to get your UOS ready.
+
+   .. code-block:: console
+
+      $ sudo sh acrn_quick_setup.sh -u 28960
+      Password:
+      Upgrading UOS...
+      Downloading UOS image: https://download.clearlinux.org/releases/28960/clear/clear-28960-kvm.img.xz
+        % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                       Dload  Upload   Total   Spent    Left  Speed
+       14  248M   14 35.4M    0     0   851k      0  0:04:57  0:00:42  0:04:15  293k
+
+   After download is completed, you'll get this output.
+
+   .. code-block:: console
+
+      Unxz UOS image: clear-28960-kvm.img.xz
+      Get UOS image: clear-28960-kvm.img
+      Upgrade UOS done...
+      Now you can run this command to start UOS...
+      $ sudo /root/launch_uos_28960.sh
+
+   .. note::
+      If you have a local UOS image which is named ``clear-28960-kvm.img.xz`` or it's just uncompressed into
+      ``/root`` folder which is named ``clear-28960-kvm.img``, then you can run
+      ``sudo sh acrn_quick_setup.sh -u 28960 -k`` to skip downloading it again and set up UOS directly.
+
+#. Now you can run ``sudo /root/launch_uos_28960.sh`` to launch UOS.
+
+   .. code-block:: console
+
+      $ sudo /root/launch_uos_28960.sh
+      Password:
+      cpu1 online=0
+      cpu2 online=0
+      cpu3 online=0
+      passed gvt-g optargs low_gm 64, high_gm 448, fence 8
+      SW_LOAD: get kernel path /usr/lib/kernel/default-iot-lts2018
+      SW_LOAD: get bootargs root=/dev/vda3 rw rootwait maxcpus=1 nohpet console=tty0 console=hvc0   console=ttyS0 no_timer_check ignore_loglevel log_buf_len=16M   consoleblank=0 tsc=reliable i915.avail_planes_per_pipe=0x070F00   i915.enable_hangcheck=0 i915.nuclear_pageflip=1 i915.enable_guc_loading=0   i915.enable_guc_submission=0 i915.enable_guc=0
+      VHM api version 1.0
+      open hugetlbfs file /run/hugepage/acrn/huge_lv1/D279543825D611E8864ECB7A18B34643
+      open hugetlbfs file /run/hugepage/acrn/huge_lv2/D279543825D611E8864ECB7A18B34643
+      level 0 free/need pages:512/0 page size:0x200000
+      level 1 free/need pages:1/2 page size:0x40000000
+      to reserve more free pages:
+      to reserve pages (+orig 1): echo 2 > /sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages
+      now enough free pages are reserved!
+
+      try to setup hugepage with:
+          level 0 - lowmem 0x0, biosmem 0x0, highmem 0x0
+          level 1 - lowmem 0x80000000, biosmem 0x0, highmem 0x0
+      total_size 0x180000000
+
+      mmap ptr 0x0x7efef33bb000 -> baseaddr 0x0x7eff00000000
+      mmap 0x40000000@0x7eff00000000
+      touch 1 pages with pagesz 0x40000000
+      mmap 0x40000000@0x7eff40000000
+      touch 512 pages with pagesz 0x200000
+      ...
+      [  OK  ] Started Login Service.
+      [  OK  ] Started Network Name Resolution.
+      [  OK  ] Reached target Network.
+               Starting Permit User Sessions...
+      [  OK  ] Reached target Host and Network Name Lookups.
+      [  OK  ] Started Permit User Sessions.
+      [  OK  ] Started Serial Getty on ttyS0.
+      [  OK  ] Started Getty on tty1.
+      [  OK  ] Started Serial Getty on hvc0.
+      [  OK  ] Reached target Login Prompts.
+      [  OK  ] Reached target Multi-User System.
+      [  OK  ] Reached target Graphical Interface.
+
+      clr-0d449d5327d64aee8a6b8a3484dcd880 login:
+
+#. After you login, these commands and results would show you're running
+   in the UOS::
+
+      # uname -r
+      4.19.34-45.iot-lts2018
+      # ls /dev/acrn*
+      ls: cannot access '/dev/acrn*': No such file or directory
+
+   In the UOS there won't be any /dev/acrn* devices.  If you're in the SOS,
+   you'd see results such as these::
+
+      # uname -r
+      4.19.34-45.iot-lts2018-sos
+      # ls /dev/acrn*
+      /dev/acrn_hvlog_cur_0   /dev/acrn_hvlog_cur_2  /dev/acrn_trace_0  /dev/acrn_trace_2  /dev/acrn_vhm
+      /dev/acrn_hvlog_cur_1   /dev/acrn_hvlog_cur_3  /dev/acrn_trace_1  /dev/acrn_trace_3
+
+
+.. _manual-setup-guide:
+
+Manual setup ACRN guide
+=======================
+
+If you don't need the script to setup ACRN by manual, and then you should follow these steps
+after installation of Clear Linux and login system.
+
 #. Clear Linux OS is set to automatically update itself. We recommend that you disable
    this feature to have more control over when the updates happen. Use this command
    to disable the autoupdate feature:
@@ -98,16 +275,16 @@ complete this setup.
    .. note::
       The Clear Linux OS installer will automatically check for updates and install the
       latest version available on your system. If you wish to use a specific version
-      (such as 27960), you can achieve that after the installation has completed using
+      (such as 28960), you can achieve that after the installation has completed using
-      ``sudo swupd verify --fix --picky -m 27960``
+      ``sudo swupd verify --fix --picky -m 28960``
 
 #. If you have an older version of Clear Linux OS already installed
    on your hardware, use this command to upgrade Clear Linux OS
-   to version 27960 (or newer):
+   to version 28960 (or newer):
 
    .. code-block:: none
 
-      $ sudo swupd update -m 27960     # or newer version
+      $ sudo swupd update -m 28960     # or newer version
 
 #. Use the ``sudo swupd bundle-add`` command and add these Clear Linux OS bundles:
 
@@ -129,6 +306,7 @@ complete this setup.
       |                    | which is enterprise-style kernel with backports   |
       +--------------------+---------------------------------------------------+
 
+
 .. _add-acrn-to-efi:
 
 Add the ACRN hypervisor to the EFI Partition
@@ -329,14 +507,14 @@ Set up Reference UOS
 ====================
 
 #. On your platform, download the pre-built reference Clear Linux OS UOS
-   image version 27960 (or newer) into your (root) home directory:
+   image version 28960 (or newer) into your (root) home directory:
 
    .. code-block:: none
 
       $ cd ~
       $ mkdir uos
       $ cd uos
-      $ curl https://download.clearlinux.org/releases/27960/clear/clear-27960-kvm.img.xz -o uos.img.xz
+      $ curl https://download.clearlinux.org/releases/28960/clear/clear-28960-kvm.img.xz -o uos.img.xz
 
    .. note::
       In case you want to use or try out a newer version of Clear Linux OS as the UOS, you can
@@ -386,4 +564,3 @@ Set up Reference UOS
    .. figure:: images/gsg-successful-boot.png
       :align: center
       :name: gsg-successful-boot
-