diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst index a4a49dfdc..22874e1da 100644 --- a/doc/getting_started/index.rst +++ b/doc/getting_started/index.rst @@ -7,7 +7,7 @@ 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 the ACRN hypervisor and the `Clear Linux`_ Service OS and Guest OS on the Intel -|reg| NUC. +(EFI) platform. .. _Clear Linux: https://clearlinux.org @@ -142,12 +142,33 @@ partition. Follow these steps: .. note:: Be aware that a Clearlinux update that includes a kernel upgrade will - reset the boot option changes you just made.. A Clearlinux update could - happen automatically (if you have - not disabled it as described above), if you later install a new - bundle to your system, or simply if you decide to trigger an update - manually. Whenever that happens, double-check the platform boot order - using ``efibootmgr -v`` and modify it if needed. + reset the boot option changes you just made. A Clearlinux update could + happen automatically (if you have not disabled it as described above), + if you later install a new bundle to your system, or simply if you + decide to trigger an update manually. Whenever that happens, + double-check the platform boot order using ``efibootmgr -v`` and + modify it if needed. + + The ACRN hypervisor (``acrn.efi``) accepts two command-line parameters that + tweak its behaviour: + + 1. ``bootloader=``: this sets the EFI executable to be loaded once the hypervisor + is up and running. This is typically the bootloader of the Service OS and the + default value is to use the Clearlinux bootloader, i.e.: ``\EFI\org.clearlinux\bootloaderx64.efi``. + #. ``uart=``: this tells the hypervisor where the serial port (UART) is found or + whether it should be disabled. There are three forms for this parameter: + + #. ``uart=disabled``: this disables the serial port completely + #. ``uart=mmio@``: this sets the serial port MMIO address + #. ``uart=port@``: this sets the serial port address + + Here is a more complete example of how to configure the EFI firmware to load the ACRN + hypervisor and set these parameters. + + .. code-block:: + + # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN Hypervisor" \ + -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=mmio@0x9141e000" #. Create a boot entry for the ACRN Service OS by copying a provided ``acrn.conf`` and editing it to account for the kernel versions noted in a previous step. diff --git a/doc/getting_started/up2.rst b/doc/getting_started/up2.rst index a73af7d1e..7a21d8bb8 100644 --- a/doc/getting_started/up2.rst +++ b/doc/getting_started/up2.rst @@ -1,206 +1,86 @@ -========================================== -ACRN - Getting started guide for UP2 board -========================================== +.. _getting_started_up2: + +Getting started guide for UP2 board +################################### Hardware setup -============== +************** -The `*UP squared board* `__ (UP2) is -the x86 maker board based on Intel Apollo Lake platform. The UP boards -have been used in IoT, industrial automation, digital signage and more. -The UP2 features Intel `*Celeron -N3550* `__ -and Intel `*Pentium -N4200* `__ -SoCs. Both have been confirmed to work with ACRN. +The `UP Squared board `_ (UP2) is the x86 maker board based on Intel Apollo Lake platform. The UP boards have been used in IoT, industrial automation, digital signage and more. The UP2 features Intel `Celeron N3550 `_ and Intel `Pentium N4200 `_ SoCs. Both have been confirmed to work with ACRN. Connecting to the serial port ------------------------------ +============================= -The UP2 board has two serial ports: one via the M10 header and one via -the I/O pins in the 40-pin HAT connector. Please refer to the `*UP2 -specifications* `__ -for more information. In this instruction, we use the latter. To connect -to the UP2 board, use a USB TTL serial cable like `*this -one* `__. -Connect pin 6 (GND), pin 8 (TX) and pin 10 (RX) of the HAT connector to -GND, RX and TX pins of your USB serial cable. The USB serial cable can -be plugged into another PC for debugging. Tool like minicom or screen -can help to connect. +The UP2 board has two serial ports. Please refer to the `UP2 specifications `_ for more information. We'll access the serial port through the I/O pins in the 40-pin HAT connector using a `USB TTL serial cable `_. Connect pin 6 (``GND``), pin 8 (``TX``) and pin 10 (``RX``) of the HAT connector to respectively the ``GND``, ``RX`` and ``TX`` pins of your USB serial cable. Plug the USB TTL serial cable into your PC and use a console emulation tool such as ``minicom`` or ``putty`` to communicate with the UP2 board for debugging. Software setup -============== +************** -Setting up the operating system -------------------------------- +Setting up the ACRN hypervisor (and associated components) on the UP2 +board is no different than other hardware platforms so please follow +the instructions provided in the :ref:`getting_started`. -Download the compressed Clear installer image from -`*here* `__ -and follow the `*Clear Linux installation -guide* `__ -as a starting point for installing Clear Linux onto your UP2. Follow -the recommended options for choosing an Automatic installation type, -and using the UP2’s storage as the target device for installation -(overwriting the existing data and creating three partitions on the -UP2’s eMMC drive). -After installation is complete, boot into Clear Linux, login as **root**, -and set a password. -Clear Linux is set to automatically update itself. We recommend that -you disable this feature to have more control over when the updates -happen. +There are a few parameters specific to the UP2 board that differ from +what is referenced in the :ref:`getting_started` section: -Use this command to disable the autoupdate feature: +1. Serial Port settings +#. Storage device name +#. ``pci_devices_ignore`` parameter -.. code-block:: none +You will need to keep these in mind in a few places: - # swupd autoupdate --disable +* When mounting the EFI System Partition (ESP) -Use the swupd bundle-add command and add these Clear Linux bundles: + .. code-block:: console -.. code-block:: none + # mount /dev/mmcblk0p1 /mnt - # swupd bundle-add vim network-basic service-os kernel-pk os-clr-on-clr +* When adjusting the ``acrn.conf`` file + + * Change the ``options`` line and set ``pci_devices_ignore=(0:18:1)`` + * Set the ``root=`` parameter using the ``PARTUUID`` or device name directly -Building and installing software --------------------------------- +* When configuring the EFI firmware to boot the ACRN hypervisor by default -Downloading ACRN source code -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: console -.. code-block:: none + # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/mmcblk0 -p 1 -L "ACRN Hypervisor" \ + -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=mmio@0x9141e000" - # git clone https://github.com/projectacrn/acrn-hypervisor - # cd acrn-hypervisor +UP2 serial port setting +======================= -Building ACRN hypervisor and the device model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The serial port in the 40-pin HAT connector is located at ``MMIO 0x0x9141e000``. +You can check this from the ``dmesg`` output from the initial Clearlinux installation. -.. code-block:: none +.. code-block:: console - # make hypervisor PLATFORM=uefi - # make devicemodel + # dmesg | grep dw-apb-uart + [2.150689] dw-apb-uart.8: ttyS1 at MMIO 0x91420000 (irq = 4, base_baud = 115200) is a 16550A + [2.152072] dw-apb-uart.9: ttyS2 at MMIO 0x9141e000 (irq = 5, base_baud = 115200) is a 16550A -Deploying to the system -~~~~~~~~~~~~~~~~~~~~~~~ +The second entry associated with ``dw-apb-uart.9`` is the one on the 40-pin HAT connector. -Follow the guidance "`*Add the ACRN hypervisor to the EFI -partition* `__" -to deploy the hypervisor to the system. The file acrn.efi is in the -folder "build/hypervisor/". ACRN allows the user to pass the cmdline -to the hypervisor. For the UP2, here the UART address is added to -enable the serial port. +UP2 block device +================ -.. code-block:: none +The UP2 board has an on-board eMMC device. The device name to be used +throughout the :ref:`getting_started` therefore is ``/dev/mmcblk0`` +(and ``/dev/mmcblk0pX`` for any partition). - # mount /dev/mmcblk0p1 /mnt - # mkdir /mnt/EFI/acrn - # cp build/hypervisor/acrn.efi /mnt/EFI/acrn/ - # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/mmcblk0p3 -p 1 -L "ACRN Hypervisor" \ - -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=mmio@0x9141e000" - # cp /mnt/EFI/org.clearlinux/mnbootloaderx64.efi /mnt/EFI/org.clearlinux/bootloaderx64_origin.efi +The UUID of the partition ``/dev/mmcblk0p3`` can be found by -Note that the uart address can be obtained from dmesg (after booting Clearlinux on -your UP2 board) +.. code-block:: console -.. code-block:: none + # blkid /dev/mmcblk - # dmesg | grep dw-apb-uart - [2.150689] dw-apb-uart.8: ttyS1 at MMIO 0x91420000 (irq = 4, base_baud = 115200) is a 16550A - [2.152072] dw-apb-uart.9: ttyS2 at MMIO 0x9141e000 (irq = 5, base_baud = 115200) is a 16550A +.. note:: + You can also use the device name directly, e.g.: ``root=/dev/mmcblk0p3`` -The second one associated with ‘dw-apb-uart.9’ is the one on the 40-pin -HAT connector. +Running the hypervisor +********************** -Copy ‘acrn.conf’ to the directory ‘loader/entries’ +Now that the hypervisor and Service OS have been installed on your UP2 board, +you can proceed with the rest of the instructions in the :ref:`getting_started` +and install the User OS (UOS). -.. code-block:: none - - # cp hypervisor/bsp/uefi/clearlinux/acrn.conf /mnt/loader/entries - -Modify the acrn.conf like below: - -.. code-block:: none - - title The ACRN Service OS - linux /EFI/org.clearlinux/kernel-org.clearlinux.pk414-sos.4.14.23-19 - options **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 - cma=1024M@0x30000000-0 - -The UUID of the partition /dev/mmcblk0p3 can be found by - -.. code-block:: none - - # blkid /dev/mmcblk0p3 - - -Note that the Clear Linux system gets updated to the latest status when -adding new packages with bundle-add. The SOS kernel version above is -only an example. Look at the "/EFI/org.clearlinux/" under the EFI -partition and adjust the kernel version. - -.. code-block:: none - - # mount /dev/mmcblk0p1 /mnt - # ls /mnt/EFI/org.clearlinux - bootloaderx64.efi - kernel-org.clearlinux.native.4.15.9-538 - kernel-org.clearlinux.pk414-sos.4.14.23-19 - kernel-org.clearlinux.pk414-standard.4.14.23-19 - loaderx64.efi - -Replace the ACRN devicemodel with the newly built one. - -.. code-block:: none - - # cp build/devicemodel/acrn-dm /usr/bin/acrn-dm - -Reboot UP2 board and select "The ACRN Service OS" to boot. From here you -can login as root using the password you set previously when installing -Clear Linux. - -Installing the UOS -~~~~~~~~~~~~~~~~~~ - -Follow the ACRN getting started guide to `*create a bridge -network* `__ -and `*setup a reference -UOS* `__. - -Launching UOS in the GUI -~~~~~~~~~~~~~~~~~~~~~~~~ - -Mouse and keyboard have also been confirmed to work with the GUI -control. Follow the `*Clear Linux -guidance* `__ -on how to enable the GUI. - -.. code-block:: none - - # useradd - # passwd - # usermod -G wheel -a - # swupd bundle-add desktop - # systemctl start gdm - -When the GUI starts, login with the userID and password, launch a new -terminal, and from there launch the UOS. - -.. code-block:: none - - $ cd /usr/share/acrn/samples/nuc - $ sudo ./launch_UOS.sh - -|image0| - -Figure 1. Launching UOS in GUI environment on top of ACRN - -.. |image0| image:: images/up2-gui.png - :width: 6.50000in - :height: 3.65278in diff --git a/doc/hardware.rst b/doc/hardware.rst index b18de43bc..b66a7d861 100644 --- a/doc/hardware.rst +++ b/doc/hardware.rst @@ -30,3 +30,12 @@ recommended memory and storage options noted above. .. _SimplyNUC: https://www.simplynuc.com/?s=NUC6CAYH&post_type=product + +UP Squared board +**************** + +The `UP Squared board `_ (UP2) is the x86 maker board based on Intel Apollo Lake platform. The UP boards have been used in IoT, industrial automation, digital signage and more. The UP2 features Intel `Celeron N3550 `_ and Intel `Pentium N4200 `_ SoCs. Both have been confirmed to work with ACRN. + +You can purchase this board directly online from `UP Shop `_ or contact one of the `local reseller `_. + +Visit the :ref:`getting_started_up2` page for instructions on how to set up ACRN on the UP2 board.