diff --git a/doc/getting_started/images/gsg-bootmenu.png b/doc/getting_started/images/gsg-bootmenu.png new file mode 100644 index 000000000..98b2a53b3 Binary files /dev/null and b/doc/getting_started/images/gsg-bootmenu.png differ diff --git a/doc/getting_started/images/gsg-sos-console.png b/doc/getting_started/images/gsg-sos-console.png new file mode 100644 index 000000000..eb390702f Binary files /dev/null and b/doc/getting_started/images/gsg-sos-console.png differ diff --git a/doc/getting_started/images/gsg-successful-boot.png b/doc/getting_started/images/gsg-successful-boot.png new file mode 100644 index 000000000..4c78ffd75 Binary files /dev/null and b/doc/getting_started/images/gsg-successful-boot.png differ diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst index ac52ddb45..58dd331ff 100644 --- a/doc/getting_started/index.rst +++ b/doc/getting_started/index.rst @@ -3,8 +3,302 @@ Getting Started Guide ##################### -This Getting Started Guide (GSG) provides information for setting up -your host development computer with the needed software and tools for -developing with Project ACRN. We'll also provide setup -instructions for the targeted hardware platform, and running a sample -application on this platform. +After reading the :ref:`introduction`, use this guide to get started +using ACRN in a reference setup. We'll show how to set up your +development and target hardware, and then how to boot up of the ACRN +hypervisor and the `Clear Linux`_ Service OS and Guest OS on the Intel +|reg| NUC, using the UEFI BIOS. + +.. _Clear Linux: https://clearlinux.org + +Hardware setup +************** + +The Intel |reg| NUC (NUC6CAYH) is the supported reference target +platform for ACRN work, as described in :ref:`hardware`, and is the only +platform tested with these setup instructions. + +The recommended NUC hardware configuration is: + +- NUC: `NUC Kit + NUC6CAYH `__ +- Memory: 8G DDR3 +- SSD: 120G SATA + +In the software setup, we'll ensure the NUC is running the latest +(version 0047) +`UEFI BIOS `__. + +Software setup +************** + +Firmware update on the NUC +========================== + +You may need to update to the latest UEFI firmware for the NUC hardware. +Follow these `BIOS Update Instructions +`__ +for downloading and flashing an updated BIOS for the NUC. + +Set up a Clear Linux Operating System +===================================== + +Currently, an installable version of ARCN does not exist. Therefore, we +need to setup a base Clear Linux OS to bootstrap ACRN. ACRN requires +Clear Linux version 21190 or newer. + +1. Follow this `Clear Linux installation guide + `__ + as a starting point for installing Clear Linux onto your NUC. + +2. At the "Choose Installation Type" screen, choose the "< Automatic >" + option. This will install the minimum Clear Linux components. + +3. At the "Choose target device for installation" screen, select your + NUC's storage device to delete all existing content and create + partitions automatically. The installer will + create three partitions as shown in :numref:`CL-partitions` + for the recommended 120GB SSD drive. + + .. table:: Clear Linux Partitions + :widths: auto + :name: CL-partitions + + +-------------+----------+-----------------------+ + | Partition | Size | Type | + +=============+==========+=======================+ + | /dev/sda1 | 511M | EFI System | + +-------------+----------+-----------------------+ + | /dev/sda2 | 32M | Linux swap | + +-------------+----------+-----------------------+ + | /dev/sda3 | 111.3G | Linux root (x86-64) | + +-------------+----------+-----------------------+ + +4. After installation is complete, boot into Clear Linux and log in as + root and set a password. + +5. Clear Linux is set to automatically update. If you do not wish for + autoupdate, issue this command: + + .. code-block:: none + + # swupd autoupdate --disable + +6. Use the ``swupd bundle-add`` command and add these Clear Linux bundles: + + .. table:: Clear Linux bundles + :widths: auto + :name: CL-bundles + + +--------------------+---------------------------------------------------+ + | Bundle | Description | + +====================+===================================================+ + | vim | vim text editor | + +--------------------+---------------------------------------------------+ + | curl | Provide the curl command-line utility | + +--------------------+---------------------------------------------------+ + | network-basic | Run network utilities and modify network settings | + +--------------------+---------------------------------------------------+ + | service-os | Add the acrn hypervisor, the acrn devicemodel and | + | | Service OS kernel | + +--------------------+---------------------------------------------------+ + | kernel-pk | Run the Intel "PK" kernel(product kernel source) | + | | and enterprise-style kernel with backports | + +--------------------+---------------------------------------------------+ + | os-clr-on-clr-dev | Install dependent packages and libs | + +--------------------+---------------------------------------------------+ + + .. code-block:: none + + # swupd bundle-add vim curl network-basic service-os kernel-pk os-clr-on-clr-dev + +Add the ACRN hypervisor to the EFI Partition +============================================ + +In order to boot the ACRN SOS on the NUC, we need to add it to the EFI +partition. Follow these steps: + +#. Mount the EFI partition and verify you have the following files: + + .. code-block:: none + + + # mount /dev/sda1 /mnt + + # ls /mnt/EFI/org.clearlinux + bootloaderx64.efi + kernel-org.clearlinux.native.4.15.7-536 + kernel-org.clearlinux.pk414-sos.4.14.23-19 + kernel-org.clearlinux.pk414-standard.4.14.23-19 + loaderx64.efi + +#. Copy the ``acrn.efi`` hypervisor application to the EFI partition. + + .. code-block:: none + + # cp /usr/share/acrn.efi /mnt/EFI/org.clearlinux + +#. Create a boot entry for ACRN. It must contain these settings: + + +-----------+----------------------------------------------------------------+ + | Setting | Description | + +===========+================================================================+ + | title | Text to show in the boot menu | + +-----------+----------------------------------------------------------------+ + | efi | Executable EFI image | + +-----------+----------------------------------------------------------------+ + | options | Options to pass to the EFI program or kernel boot parameters | + +-----------+----------------------------------------------------------------+ + + A sample `acrn.conf + `__ + is available in the acrn-hypervisor GitHub repo (in the bsp/uefi/clearlinux + folder) as shown here: + + .. literalinclude:: ../../acrn-hypervisor/bsp/uefi/clearlinux/acrn.conf + :caption: acrn-hypervisor/bsp/uefi/clearlinux/acrn.conf + + You can download ``acrn.conf`` and copy it to + ``/mnt/loader/entries/acrn.conf`` and use it directly. If you're following + the instructions above, the partition (``root=/dev/sda3``) and image + locatations will match. + +#. Add a timeout period for Systemd-Boot to wait, otherwise it will not + present the boot menu and will always boot the base Clear Linux + kernel. + + .. code-block:: none + + # clr-boot-manager set-timeout 20 + # clr-boot-manager update + +#. Reboot and select "The ACRN Hypervisor" to boot, as shown in + :numref:`gsg-bootmenu`: + + .. figure:: images/gsg-bootmenu.png + :align: center + :name: gsg-bootmenu + + ACRN Hypervisor Boot menu + +#. After booting up the ACRN hypervisor, the Service OS be launched + automatically by default, as shown in :numref:`gsg-sos-console`: + + .. figure:: images/gsg-sos-console.png + :align: center + :name: gsg-sos-console + + Service OS Console + +#. From here you can login as root and set the first-time root password. + +Create a Network Bridge +======================= + +Without a network bridge, the SOS and UOS are not able to talk to each +other. + +A sample `bridge.sh +`__ +is available in the acrn-devicemodel GitHub repo (in the samples +folder) as shown here: + +.. literalinclude:: ../../acrn-devicemodel/samples/bridge.sh + :caption: acrn-devicemodel/samples/bridge.sh + :language: bash + +You can download ``bridge.sh``, copy it to your root home +directory, and use it directly by making it executable and running it: + +.. code-block:: none + + # chmod +x ./bridge.sh + # ./bridge.sh + +Set up Reference UOS +==================== + +#. Download the pre-built reference Clear Linux UOS image. + + .. code-block:: none + + # curl -O https://download.clearlinux.org/image/clear-21180-kvm.img.xz + +#. Uncompress it. + + .. code-block:: none + + # unxz clear-21180-kvm.img.xz + +#. Deploy the UOS kernel modules to UOS virtual disk image + + .. code-block:: none + + # losetup -f -P --show /root/clear-21180-kvm.img + # ls /dev/loop0* + # mount /dev/**loop0p3** /mnt + # cp -r /usr/lib/doc/modules/4.14.23-19.pk414-standard /mnt/lib/doc/modules/ + # umount /mnt + # sync + +#. Create the launch_uos.sh script and run it to launch the UOS. + A sample `launch_uos.sh + `__ + is available in the acrn-devicemodel GitHub repo (in the samples + folder) as shown here: + + .. literalinclude:: ../../acrn-devicemodel/samples/launch_uos.sh + :caption: acrn-devicemodel/samples/launch_uos.sh + :language: bash + + You can download ``launch_uos.sh``, copy it to your root home + directory, and use it directly by making it executable and running it: + + .. code-block:: none + + # chmod +x ./launch_uos.sh + # ./launch_uos.sh + +#. At this point, you've successfully booted the ACRN system, + hypervisor, SOS and UOS: + + .. figure:: images/gsg-successful-boot.png + :align: center + :name: gsg-successful-boot + + +Build ACRN from Source +********************** + +If you would like to build ACRN hypervisor and device model from source, +follow these steps: + +#. On your Clear Linux system, install the os-clr-on-clr bundle to get + the necessary tools. + + .. code-block:: none + + # swupd bundle-add os-clr-on-clr + +#. Download the ACRN hypervisor and build it. + + .. code-block:: none + + # git clone https://github.com/projectacrn/acrn-hypervisor + # cd acrn-hypervisor + # make PLATFORM=uefi + + The build results are found in the ``build`` directory. + +#. Download the ACRN device model and build it. + + .. code-block:: none + + # git clone https://github.com/projectacrn/acrn-devicemodel + # cd acrn-devicemodel + # make + + The build results are found in the ``build`` directory. + +Follow the same instructions to boot and test the images you created +from your build. diff --git a/doc/static/acrn-custom.css b/doc/static/acrn-custom.css index 4e8d5f43c..cd472a640 100644 --- a/doc/static/acrn-custom.css +++ b/doc/static/acrn-custom.css @@ -33,6 +33,14 @@ table.align-center { display: table !important; } + +.code-block-caption { + color: #000; + font: italic 85%/1 arial,sans-serif; + padding: 1em 0; + text-align: center; +} +` /* make .. hlist:: tables fill the page */ table.hlist { width: 95% !important;