diff --git a/doc/develop.rst b/doc/develop.rst index 9245197ef..827eedad1 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -27,6 +27,7 @@ Configuration Tutorials tutorials/using_sdc2_mode_on_nuc tutorials/using_hybrid_mode_on_nuc tutorials/realtime_performance_tuning + tutorials/kbl-nuc-sdc User VM Tutorials ***************** diff --git a/doc/faq.rst b/doc/faq.rst index 415325230..841ada41b 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -31,8 +31,10 @@ fails to boot, here are some options to try: not checked in the "Boot Options" * Make sure you are using EFI (and not legacy BIOS) -How do I configure ACRN's memory use? -************************************* +.. _config_32GB_memory: + +How do I configure ACRN's memory size? +************************************** It's important that the ACRN Kconfig settings are aligned with the physical memory on your platform. Check the documentation for these option settings for @@ -43,44 +45,53 @@ details: * :option:`CONFIG_UOS_RAM_SIZE` * :option:`CONFIG_HV_RAM_SIZE` -For example, if memory is 32G, setup ``PLATFORM_RAM_SIZE`` = 32G +For example, if the NUC's physical memory size is 32G, you may follow these steps +to make the new uefi ACRN hypervisor, and then deploy it onto the NUC board to boot +ACRN Service VM with the 32G memory size. -:: +#. Modify the ``hypervisor/arch/x86/Kconfig`` from the ACRN source on host machine. - config PLATFORM_RAM_SIZE - hex "Size of the physical platform RAM" - default 0x200000000 if PLATFORM_SBL - default 0x800000000 if PLATFORM_UEFI + :: + + config HV_RAM_SIZE + hex "Size of the RAM region used by the hypervisor" + - default 0x0b800000 + + default 0x0f000000 + help + A 64-bit integer indicating the size of RAM used by the hypervisor. + It is ensured at link time that the footprint of the hypervisor + + :: + + config PLATFORM_RAM_SIZE + hex "Size of the physical platform RAM" + - default 0x400000000 + + default 0x800000000 + help + A 64-bit integer indicating the size of the physical platform RAM + (MMIO not included). + + :: + + config SOS_RAM_SIZE + hex "Size of the Service OS (SOS) RAM" + - default 0x400000000 + + default 0x800000000 + help + A 64-bit integer indicating the size of the Service OS RAM (MMIO not + included). -Setup ``SOS_RAM_SIZE`` = 32G too (The SOS will have the whole resource) +#. Use ``make BOARD=nuc7i7dnb FIRMWARE=uefi hypervisor`` command to build the new + efi image for KBL NUC. -:: +#. Log in to your KBL NUC (assumes all the ACRN configurations are set up), then copy + the new efi image into the EFI partition:: - config SOS_RAM_SIZE - hex "Size of the Service OS (SOS) RAM" - default 0x200000000 if PLATFORM_SBL - default 0x800000000 if PLATFORM_UEFI + # mount /dev/sda1 /mnt + # scp -r :/build/hypervisor/acrn.efi /mnt/EFI/acrn/ + # sync && umount /mnt -Setup ``UOS_RAM_SIZE`` to what you need, for example, 16G - -:: - - config UOS_RAM_SIZE - hex "Size of the User OS (UOS) RAM" - default 0x100000000 if PLATFORM_SBL - default 0x400000000 if PLATFORM_UEFI - -Setup ``HV_RAM_SIZE`` (we will reserve memory for guest EPT paging -table), if you setup 32G (default 16G), you must enlarge it with -(32G-16G)/2M pages (where pages are 4K). The example below is after -HV_RAM_SIZE is changed to 240M - -:: - - config HV_RAM_SIZE - hex "Size of the RAM region used by the hypervisor" - default 0x07800000 if PLATFORM_SBL - default 0x0f000000 if PLATFORM_UEFI +#. Reboot KBL NUC to enjoy the ACRN with 32G memory. How to modify the default display output for a UOS? *************************************************** diff --git a/doc/getting-started/acrn_quick_setup.sh b/doc/getting-started/acrn_quick_setup.sh index 48514c0c0..31f67d967 100644 --- a/doc/getting-started/acrn_quick_setup.sh +++ b/doc/getting-started/acrn_quick_setup.sh @@ -18,7 +18,7 @@ function print_help() { echo "Usage:" - echo "Launch this script as: sudo $0 -s 31080" + echo "Launch this script as: sudo $0 -s 31470" echo -e "\t-s to upgrade Service VM" echo -e "\t-u to upgrade User VM" echo -e "\t-p to specify a proxy server (HTTPS)" @@ -42,9 +42,6 @@ skip_download_uos=0 # switcher for disabling reboot device disable_reboot=0 -# acrn.efi path -acrn_efi_path=/usr/lib/acrn/acrn.nuc6cayh.sdc.efi - function upgrade_sos() { # Check Service VM version @@ -53,6 +50,14 @@ function upgrade_sos() echo "Upgrading Service VM..." + # get board name + BOARD_NAME=`cat /sys/devices/virtual/dmi/id/board_name` + BOARD_NAME=${BOARD_NAME,,} + [[ -z $BOARD_NAME ]] && echo "Unknown board name." && exit 1 + echo "Board name is: $BOARD_NAME" + # set default scenario name + scenario=sdc + # setup mirror and proxy url while specified with m and p options [[ -n $mirror ]] && echo "Setting swupd mirror to: $mirror" && swupd mirror -s $mirror [[ -n $proxy ]] && echo "Setting proxy to: $proxy" && export https_proxy=$proxy @@ -77,6 +82,18 @@ function upgrade_sos() echo "Adding the service-os and systemd-networkd-autostart bundles..." swupd bundle-add service-os systemd-networkd-autostart 2>/dev/null + # get acrn.efi path + acrn_efi_path=/usr/lib/acrn/acrn.$BOARD_NAME.$scenario.efi + if [[ ! -f $acrn_efi_path ]]; then + echo "$acrn_efi_path doesn't exist." + echo "Use one of these efi images from /usr/lib/acrn." + echo "------" + ls /usr/lib/acrn/acrn.*.$scenario.efi -1 + echo "------" + echo "Copy the efi image to $acrn_efi_path, then run the script again." + exit 1 + fi + mount $efi_partition /mnt echo "Add /mnt/EFI/acrn folder" mkdir -p /mnt/EFI/acrn @@ -89,17 +106,22 @@ function upgrade_sos() cp -a $acrn_efi_path /mnt/EFI/acrn/acrn.efi if [[ $? -ne 0 ]]; then echo "Fail to copy $acrn_efi_path" && exit 1; fi - new_kernel=`ls /mnt/EFI/org.clearlinux/*sos* -tl | grep kernel | head -n1 | awk -F'/' '{print $5}'` - new_kernel=${new_kernel#kernel-} + new_kernel=`ls /usr/lib/kernel/org*sos* -tl | head -n1 | awk -F'/' '{print $5}'` echo "Getting latest Service OS kernel version: $new_kernel" echo "Add default (5 seconds) boot wait time." - clr-boot-manager set-timeout 5 || { echo "Faild to add default boot wait time" && exit 1; } + clr-boot-manager set-timeout 5 || { echo "Fail to add default boot wait time" && exit 1; } clr-boot-manager update - echo "Set $new_kernel as default boot kernel." clr-boot-manager set-kernel $new_kernel || { echo "Fail to set $new_kernel as default boot kernel." && exit 1; } + # Rename Clear-linux-iot-lts2018-sos conf to acrn.conf + conf_directory=/mnt/loader/entries/ + conf=`sed -n 2p /mnt/loader/loader.conf | sed "s/default //"` + cp -r ${conf_directory}${conf}.conf ${conf_directory}acrn.conf 2>/dev/null || \ + { echo "${conf_directory}${conf}.conf does not exist." && exit 1; } + sed -i 2"s/$conf/acrn/" /mnt/loader/loader.conf + echo "Check ACRN efi boot event" check_acrn_bootefi=`efibootmgr | grep ACRN | wc -l` if [[ "$check_acrn_bootefi" -ge 1 ]]; then @@ -113,9 +135,10 @@ function upgrade_sos() efibootmgr | grep 'Linux bootloader' | cut -d'*' -f1 | cut -d't' -f2 | head -n$number | xargs -i efibootmgr -b {} -B >/dev/null fi - echo "Add new ACRN efi boot event" - efibootmgr -c -l "\EFI\acrn\acrn.efi" -d $partition -p 1 -L "ACRN" >/dev/null - + echo "Add new ACRN efi boot event, uart is disabled by default." + set -x + efibootmgr -c -l "\EFI\acrn\acrn.efi" -d $partition -p 1 -L "ACRN" -u "uart=disabled" >/dev/null + { set +x; } 2>/dev/null echo "Service OS setup done!" else echo "Fail to upgrade Service VM to $sos_ver." @@ -218,7 +241,7 @@ do ;; h) print_help ;; - i) acrn_efi_path=/usr/lib/acrn/acrn.kbl-nuc-i7.industry.efi + i) scenario=industry ;; ?) print_help ;; diff --git a/doc/getting-started/changelog_QuickSetupScript.txt b/doc/getting-started/changelog_QuickSetupScript.txt new file mode 100644 index 000000000..f9ffebdca --- /dev/null +++ b/doc/getting-started/changelog_QuickSetupScript.txt @@ -0,0 +1,13 @@ +Release v1.4 + +- Fix ACRN bootloader not clean up issue. +- Add board_name and scenario variants use the right ACRN efi image. +- Add new parameter to set up ACRN as industry scenario. + +Release v1.3 + +- Use "clr-boot-manager" tool to set up ACRN kernel. + +Release v0.8 + +- Support Service VM and User VM upgrading. diff --git a/doc/getting-started/rt_industry.rst b/doc/getting-started/rt_industry.rst index 20d3d4669..9ad9e2938 100644 --- a/doc/getting-started/rt_industry.rst +++ b/doc/getting-started/rt_industry.rst @@ -6,9 +6,9 @@ Getting Started Guide for ACRN Industry Scenario Verified version **************** -- Clear Linux version: **31080** -- ACRN-hypervisor tag: **v1.3** -- ACRN-Kernel(Service VM kernel): **acrn-2019w39.1-140000p** +- Clear Linux version: **31470** +- ACRN-hypervisor tag: **v1.4** +- ACRN-Kernel(Service VM kernel): **4.19.78-95.iot-lts2018-sos** - ACRN-Kernel(Preempt-RT kernel): **acrn-2019w39.1-143000p** Prerequisites @@ -20,16 +20,17 @@ for the RTVM. - Intel Kaby Lake (aka KBL) NUC platform with two disks inside (refer to :ref:`the tables ` for detailed information). -- Follow below steps to install Clear Linux OS (Ver: 31080) onto both disks on the KBL NUC: +- If you need to enable the serial port on KBL NUC, navigate to the :ref:`troubleshooting ` to prepare the cable. +- Follow below steps to install Clear Linux OS (Ver: 31470) onto both disks on the KBL NUC: .. _Clear Linux OS Server image: - https://download.clearlinux.org/releases/31080/clear/clear-31080-live-server.iso.xz + https://download.clearlinux.org/releases/31470/clear/clear-31470-live-server.iso.xz #. Create a bootable USB drive on Linux*: a. Download and decompress the `Clear Linux OS Server image`_:: - $ unxz clear-31080-live-server.iso.xz + $ unxz clear-31470-live-server.iso.xz #. Plug in the USB drive. #. Use the ``lsblk`` command line to identify the USB drive: @@ -48,24 +49,25 @@ for the RTVM. #. Unmount all the ``/dev/sdc`` partitions and burn the image onto the USB drive:: $ umount /dev/sdc* 2>/dev/null - $ sudo dd if=./clear-31080-live-server.iso of=/dev/sdc oflag=sync status=progress bs=4M + $ sudo dd if=./clear-31470-live-server.iso of=/dev/sdc oflag=sync status=progress bs=4M #. Plug in the USB drive to the KBL NUC and boot from USB. #. Launch the Clear Linux OS installer boot menu. - #. With Clear Linux OS highlighted, select **Enter**. + #. With Clear Linux OS highlighted, select :kbd:`Enter`. #. Log in with your root account and new password. #. Run the installer using the following command:: # clr-installer - #. From the Main menu, select **Configure Installation Media** and set - **Destructive Installation** to your desired hard disk. - #. Select **Telemetry** to set Tab to highlight your choice. - #. Press :kbd:`A` to show the **Advanced** options. - #. Select **Select additional bundles** and add bundles for + #. From the Main menu, select :kbd:`Configure Installation Media` and set + :kbd:`Destructive Installation` to your desired hard disk. + #. Select :kbd:`Telemetry` to set Tab to highlight your choice. + #. Press :kbd:`A` to show the :kbd:`Advanced` options. + #. Select :kbd:`Select additional bundles` and add bundles for **network-basic**, and **user-basic**. - #. Select **Install**. - #. Select **Confirm Install** in the **Confirm Installation** window to start the installation. + #. Select :kbd:`Automatic OS Updates` and choose :kbd:`No [Disable]`. + #. Select :kbd:`Install`. + #. Select :kbd:`Confirm Install` in the :kbd:`Confirm Installation` window to start the installation. .. _step-by-step instruction: https://docs.01.org/clearlinux/latest/get-started/bare-metal-install-server.html @@ -90,12 +92,19 @@ Hardware Setup | | | Graphics | - UHD Graphics 620 | | | | | - Two HDMI 2.0a ports supporting 4K at 60 Hz | | | +----------------------+-----------------------------------------------------------+ - | | | System memory | - 8GiB SODIMM DDR4 2400 MHz | + | | | System memory | - 8GiB SODIMM DDR4 2400 MHz [1]_ | | | +----------------------+-----------------------------------------------------------+ | | | Storage capabilities | - SATA: 1TB WDC WD10SPZX-22Z | | | | | - NVMe: 256G Intel Corporation SSD Pro 7600p/760p/E 6100p | +----------------------+-------------------+----------------------+-----------------------------------------------------------+ +.. [1] The maximum supported memory size for ACRN is 16GB. If you are using + 32GB memory, follow the :ref:`config_32GB_memory` instruction to modify the + ``hypervisor/arch/x86/Kconfig`` and then use ``make FIRMWARE=uefi BOARD=nuc7i7dnb + SCENARIO=industry hypervisor`` command to make the latest ACRN hypervisor + which is supported 32GB memory. For more detailed instruction about how to build ACRN + from the source code, refer to this :ref:`guide `. + Set up the ACRN Hypervisor for industry scenario ************************************************ @@ -125,36 +134,11 @@ Use the pre-installed industry ACRN hypervisor .. code-block:: none - # ./acrn_quick_setup.sh -s 31080 -d -i + # ./acrn_quick_setup.sh -s 31470 -d -i - .. note:: ``-i`` option means the industry hypervisor image will be used: - ``acrn.kbl-nuc-i7.industry.efi``. - - These outputs show the script is running correctly and - industry hypervisor is also installed: - - .. code-block:: console - :emphasize-lines: 9 - - Upgrading Service VM... - Disable auto update... - Running systemctl to disable updates - Clear Linux version 31080 is already installed. Continuing to setup Service VM... - Adding the service-os and systemd-networkd-autostart bundles... - Loading required manifests... - 2 bundles were already installed - Add /mnt/EFI/acrn folder - Copy /usr/lib/acrn/acrn.kbl-nuc-i7.industry.efi to /mnt/EFI/acrn/acrn.efi - Getting latest Service OS kernel version: org.clearlinux.iot-lts2018-sos.4.19.73-92 - Add default (5 seconds) boot wait time. - New timeout value is: 5 - Set org.clearlinux.iot-lts2018-sos.4.19.73-92 as default boot kernel. - 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 - Service OS setup done! + .. note:: ``-i`` option means the industry scenario efi image will be used, e.g. + ``acrn.nuc7i7dnb.industry.efi``. For the detailed usage of the ``acrn_quick_setup.sh`` script, + move to this :ref:`quick setup ACRN guide ` or just type ``./acrn_quick_setup.sh -h``. #. Use ``efibootmgr -v`` command to check the ACRN boot order: @@ -165,7 +149,7 @@ Use the pre-installed industry ACRN hypervisor Timeout: 1 seconds BootOrder: 0001,0002,000C,000D,0008,000E,000B,0003,0000,0004,0007 Boot0000* Windows Boot Manager VenHw(99e275e7-75a0-4b37-a2e6-c5385e6c00cb)WINDOWS.........x...B.C.D.O.B.J.E.C.T.=.{.9.d.e.a.8.6.2.c.-.5.c.d.d.-.4.e.7.0.-.a.c.c.1.-.f.3.2.b.3.4.4.d.4.7.9.5.}...o................ - Boot0001* ACRN HD(1,GPT,c6715698-0f6e-4e27-bb1b-bf7779c1486d,0x800,0x47000)/File(\EFI\acrn\acrn.efi) + Boot0001* ACRN HD(1,GPT,c6715698-0f6e-4e27-bb1b-bf7779c1486d,0x800,0x47000)/File(\EFI\acrn\acrn.efi)u.a.r.t.=.d.i.s.a.b.l.e.d. Boot0002* Linux bootloader HD(3,GPT,b537f16f-d70f-4f1b-83b4-0f11be83cd83,0xc1800,0xded3000)/File(\EFI\org.clearlinux\bootloaderx64.efi) Boot0003* CentOS VenHw(99e275e7-75a0-4b37-a2e6-c5385e6c00cb) Boot0004* CentOS Linux VenHw(99e275e7-75a0-4b37-a2e6-c5385e6c00cb) @@ -179,6 +163,10 @@ Use the pre-installed industry ACRN hypervisor .. note:: Ensure the ACRN is the first boot order, or you may use ``efibootmgr -o 1`` command to move it to the first order. + .. note:: If you need to enable the serial port, run the following command before reboot: + + ``efibootmgr -c -l '\EFI\acrn\acrn.efi' -d /dev/sda -p 1 -L ACRN -u "uart=port@0x3f8"`` + #. Reboot KBL NUC. #. Use ``dmesg`` command to ensure the Service VM boots: @@ -214,11 +202,19 @@ Use the ACRN industry out-of-the-box image # dd if=sos-industry-31080.img of=/dev/sda bs=4M oflag=sync status=progress -#. Configure the EFI firmware to boot the ACRN hypervisor by default:: +#. Configure the EFI firmware to boot the ACRN hypervisor by default: + + :: - # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN" + # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN" -u "uart=disabled" -#. Unplug the U disk and reboot the test machine. After the Clear Linux OS boots, + Or use the following command to enable the serial port: + + :: + + # efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN" -u "uart=port@0x3f8" + +#. Reboot the test machine. After the Clear Linux OS boots, log in as “root” for the first time. .. _install_rtvm: @@ -273,16 +269,18 @@ Install and launch the Preempt-RT VM .. code-block:: none :emphasize-lines: 6 - /usr/bin/acrn-dm -A -m $mem_size -c $1 -s 0:0,hostbridge \ + /usr/bin/acrn-dm -A -m $mem_size -s 0:0,hostbridge \ --lapic_pt \ --rtvm \ --virtio_poll 1000000 \ -U 495ae2e5-2603-4d64-af76-d4bc5a8ec0e5 \ -s 2,passthru,02/00/0 \ -s 3,virtio-console,@stdio:stdio_port \ + -s 8,virtio-net,tap0 \ $pm_channel $pm_by_vuart \ --ovmf /usr/share/acrn/bios/OVMF.fd \ hard_rtvm + } #. Upon deployment completion, launch the RTVM directly on your KBL NUC:: @@ -309,6 +307,14 @@ suite rt-tests. Pre-Configurations ================== +Firmware update on the NUC +-------------------------- + +If you 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. + Recommended BIOS settings ------------------------- @@ -410,10 +416,6 @@ In our recommended configuration, two cores are allocated to the RTVM: core 0 for housekeeping and core 1 for RT tasks. In order to achieve this, follow the below steps to allocate all housekeeping tasks to core 0: -#. Modify the script to use two cores before launching RTVM:: - - # sed -i "s/launch_hard_rt_vm 1/launch_hard_rt_vm 2/" /usr/share/acrn/samples/nuc/launch_hard_rt_vm.sh - #. Launch RTVM:: # /usr/share/acrn/samples/nuc/launch_hard_rt_vm.sh @@ -462,11 +464,12 @@ Run cyclictest #. Use the following command to start cyclictest:: # cyclictest -a 1 -p 80 -m -N -D 1h -q -H 30000 --histfile=test.log - -- Usage: + + Parameter descriptions: :-a 1: to bind the RT task to core 1 :-p 80: to set the priority of the highest prio thread + :-m: lock current and future memory allocations :-N: print results in ns instead of us (default us) :-D 1h: to run for 1 hour, you can change it to other values :-q: quiee mode; print a summary only on exit @@ -475,9 +478,72 @@ Run cyclictest Troubleshooting *************** +.. _connect_serial_port: + +Use serial port on KBL NUC +========================== + +You can enable the serial console on the +`KBL NUC `_ +(NUC7i7DNH). The KBL NUC has a serial port header you can +expose with a serial DB9 header cable. You can build this cable yourself; +refer to the `KBL NUC product specification +`_ +as shown below: + +.. figure:: images/KBL-serial-port-header.png + :scale: 80 + + KBL serial port header details + + +.. figure:: images/KBL-serial-port-header-to-RS232-cable.jpg + :scale: 80 + + KBL `serial port header to RS232 cable + `_ + + +Or you can `purchase +`_ +such a cable. + +You'll also need an `RS232 DB9 female to USB cable +`_, +or an `RS232 DB9 female/female (NULL modem) cross-over cable +`_ +to connect to your host system. + +Note that If you want to use the RS232 DB9 female/female cable, choose the ``cross-over`` +type rather than ``straight-through`` type. + +.. _efi image not exist: + +EFI image doesn't exist +======================= + +You might see the error message if you are running the ``acrn_quick_setup.sh`` script +on an older Clear Linux OS ( < 31470 ): + + .. code-block:: console + + /usr/lib/acrn/acrn.nuc7i7dnb.industry.efi doesn't exist. + Use one of these efi images from /usr/lib/acrn. + ------ + /usr/lib/acrn/acrn.kbl-nuc-i7.industry.efi + ------ + Copy the efi image to /usr/lib/acrn/acrn.nuc7i7dnb.industry.efi, then run the script again. + +To fix it, just rename the existing efi image to ``/usr/lib/acrn/acrn.nuc7i7dnb.industry.efi`` and +then run the script again:: + + # cp -r /usr/lib/acrn/acrn.kbl-nuc-i7.industry.efi /usr/lib/acrn/acrn.nuc7i7dnb.industry.efi + # ./acrn_quick_setup.sh -s -i -d + .. _enabling the network on RTVM: -**Enabling the network on RTVM** +Enabling the network on RTVM +============================ If you need to access the internet, you must add the following command line to the ``launch_hard_rt_vm.sh`` script before launch it: @@ -485,7 +551,7 @@ If you need to access the internet, you must add the following command line to t .. code-block:: none :emphasize-lines: 8 - /usr/bin/acrn-dm -A -m $mem_size -c $1 -s 0:0,hostbridge \ + /usr/bin/acrn-dm -A -m $mem_size -s 0:0,hostbridge \ --lapic_pt \ --rtvm \ --virtio_poll 1000000 \ @@ -496,4 +562,6 @@ If you need to access the internet, you must add the following command line to t $pm_channel $pm_by_vuart \ --ovmf /usr/share/acrn/bios/OVMF.fd \ hard_rtvm + } + diff --git a/doc/getting-started/up2.rst b/doc/getting-started/up2.rst index bc3ef9a4b..d58ab6059 100644 --- a/doc/getting-started/up2.rst +++ b/doc/getting-started/up2.rst @@ -49,11 +49,11 @@ Software setup 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-apl-nuc`, with +the instructions provided in the :ref:`rt_industry_setup`, with the additional information below. There are a few parameters specific to the UP2 board that differ from -what is referenced in the :ref:`getting-started-apl-nuc` section: +what is referenced in the :ref:`rt_industry_setup` section: 1. Serial Port settings #. Storage device name @@ -118,4 +118,4 @@ Running the hypervisor 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-apl-nuc` and install the User OS (UOS). +:ref:`kbl-nuc-sdc` and install the User OS (UOS). diff --git a/doc/reference/hardware.rst b/doc/reference/hardware.rst index 4b0c47da4..0ba30d584 100644 --- a/doc/reference/hardware.rst +++ b/doc/reference/hardware.rst @@ -49,9 +49,7 @@ development team for Software-Defined Cockpit (SDC), Industrial Usage https://up-shop.org/home/270-up-squared.html -For general instructions setting up ACRN on supported hardware platforms, visit the :ref:`getting-started-apl-nuc` -and :ref:`getting-started-up2` pages. - +For general instructions setting up ACRN on supported hardware platforms, visit the :ref:`rt_industry_setup` page. +--------------------------------+-------------------------+-----------+-----------+-------------+------------+------------+ diff --git a/doc/release_notes/release_notes_0.6.rst b/doc/release_notes/release_notes_0.6.rst index b0e057c9c..aa5b0090f 100644 --- a/doc/release_notes/release_notes_0.6.rst +++ b/doc/release_notes/release_notes_0.6.rst @@ -31,7 +31,7 @@ https://projectacrn.github.io/0.6/. Documentation for the latest (master) branch is found at https://projectacrn.github.io/latest/. ACRN v0.6 requires Clear Linux OS version 27600. Please follow the -instructions in the :ref:`getting-started-apl-nuc`. +instructions in the :ref:`kbl-nuc-sdc`. Version 0.6 new features ************************ diff --git a/doc/release_notes/release_notes_0.7.rst b/doc/release_notes/release_notes_0.7.rst index 8e3109fab..f6d4f7d43 100644 --- a/doc/release_notes/release_notes_0.7.rst +++ b/doc/release_notes/release_notes_0.7.rst @@ -31,7 +31,7 @@ https://projectacrn.github.io/0.7/. Documentation for the latest (master) branch is found at https://projectacrn.github.io/latest/. ACRN v0.7 requires Clear Linux OS version 28260. Please follow the -instructions in the :ref:`getting-started-apl-nuc`. +instructions in the :ref:`kbl-nuc-sdc`. Version 0.7 new features ************************ diff --git a/doc/release_notes/release_notes_0.8.rst b/doc/release_notes/release_notes_0.8.rst index 61307d237..a20a1c7da 100644 --- a/doc/release_notes/release_notes_0.8.rst +++ b/doc/release_notes/release_notes_0.8.rst @@ -31,7 +31,7 @@ https://projectacrn.github.io/0.8/. Documentation for the latest (master) branch is found at https://projectacrn.github.io/latest/. ACRN v0.8 requires Clear Linux OS version 28600. Please follow the -instructions in the :ref:`getting-started-apl-nuc`. +instructions in the :ref:`kbl-nuc-sdc`. Version 0.8 new features ************************ diff --git a/doc/release_notes/release_notes_1.0.rst b/doc/release_notes/release_notes_1.0.rst index 935abe109..b31f7722b 100644 --- a/doc/release_notes/release_notes_1.0.rst +++ b/doc/release_notes/release_notes_1.0.rst @@ -32,7 +32,7 @@ The project's online technical documentation is also tagged to correspond with a specific release: generated v1.0 documents can be found at https://projectacrn.github.io/1.0/. Documentation for the latest (master) branch is found at https://projectacrn.github.io/latest/. ACRN v1.0 requires Clear Linux* OS version 29070. Please follow the -instructions in the :ref:`getting-started-apl-nuc`. +instructions in the :ref:`kbl-nuc-sdc`. Version 1.0 major features ************************** diff --git a/doc/release_notes/release_notes_1.1.rst b/doc/release_notes/release_notes_1.1.rst index 9f2ebbad3..91b43fef7 100644 --- a/doc/release_notes/release_notes_1.1.rst +++ b/doc/release_notes/release_notes_1.1.rst @@ -23,7 +23,7 @@ The project's online technical documentation is also tagged to correspond with a specific release: generated v1.1 documents can be found at https://projectacrn.github.io/1.1/. Documentation for the latest (master) branch is found at https://projectacrn.github.io/latest/. ACRN v1.1 requires Clear Linux* OS version 29970. Please follow the -instructions in the :ref:`getting-started-apl-nuc`. +instructions in the :ref:`kbl-nuc-sdc`. Version 1.1 major features ************************** diff --git a/doc/release_notes/release_notes_1.2.rst b/doc/release_notes/release_notes_1.2.rst index 8ef5c08ea..efb1338cc 100644 --- a/doc/release_notes/release_notes_1.2.rst +++ b/doc/release_notes/release_notes_1.2.rst @@ -23,7 +23,7 @@ The project's online technical documentation is also tagged to correspond with a specific release: generated v1.2 documents can be found at https://projectacrn.github.io/1.2/. Documentation for the latest (master) branch is found at https://projectacrn.github.io/latest/. ACRN v1.2 requires Clear Linux* OS version 30690. Please follow the -instructions in the :ref:`getting-started-apl-nuc`. +instructions in the :ref:`kbl-nuc-sdc`. Version 1.2 major features ************************** diff --git a/doc/release_notes/release_notes_1.3.rst b/doc/release_notes/release_notes_1.3.rst index faf485a6d..f4958335d 100644 --- a/doc/release_notes/release_notes_1.3.rst +++ b/doc/release_notes/release_notes_1.3.rst @@ -23,7 +23,7 @@ The project's online technical documentation is also tagged to correspond with a specific release: generated v1.3 documents can be found at https://projectacrn.github.io/1.3/. Documentation for the latest (master) branch is found at https://projectacrn.github.io/latest/. ACRN v1.3 requires Clear Linux* OS version 31080. Please follow the -instructions in the :ref:`getting-started-apl-nuc`. +instructions in the :ref:`kbl-nuc-sdc`. Version 1.3 major features ************************** diff --git a/doc/try.rst b/doc/try.rst index d2cb45999..7f1fcf4eb 100644 --- a/doc/try.rst +++ b/doc/try.rst @@ -20,7 +20,6 @@ Follow these getting started guides to give ACRN a try: :maxdepth: 1 reference/hardware - getting-started/apl-nuc getting-started/up2 getting-started/acrn_ootb getting-started/building-from-source diff --git a/doc/tutorials/acrn-dm_QoS.rst b/doc/tutorials/acrn-dm_QoS.rst index 617581bba..a76c0bd73 100644 --- a/doc/tutorials/acrn-dm_QoS.rst +++ b/doc/tutorials/acrn-dm_QoS.rst @@ -70,7 +70,7 @@ the maximal CPU resource for the VM0 or VM1 is 33% of the entire CPU resource. How to use ACRN-DM QoS ********************** -#. Follow :ref:`getting-started-apl-nuc` to boot "The ACRN Service OS" based on Clear Linux 29970 (ACRN tag v1.1). +#. Follow :ref:`kbl-nuc-sdc` to boot "The ACRN Service OS" based on Clear Linux 29970 (ACRN tag v1.1). #. Add these parameters to the ``runC.json`` file: diff --git a/doc/tutorials/debug.rst b/doc/tutorials/debug.rst index e769b5b0f..0a46a54c6 100644 --- a/doc/tutorials/debug.rst +++ b/doc/tutorials/debug.rst @@ -91,7 +91,7 @@ noted above. For example, add the following code into function Once you have instrumented the code, you need to rebuild the hypervisor and install it on your platform. Refer to :ref:`getting-started-building` and -:ref:`getting-started-apl-nuc` for detailed instructions on how to do that. +:ref:`kbl-nuc-sdc` for detailed instructions on how to do that. We set console log level to 5, and mem log level to 2 through the command:: @@ -205,7 +205,7 @@ shown in the following example: 4. After we have inserted the trace code addition, we need to rebuild the ACRN hypervisor and install it on the platform. Refer to - :ref:`getting-started-building` and :ref:`getting-started-apl-nuc` for + :ref:`getting-started-building` and :ref:`kbl-nuc-sdc` for detailed instructions on how to do that. 5. Now we can use the following command in the SOS console diff --git a/doc/tutorials/docbuild.rst b/doc/tutorials/docbuild.rst index 1d51c9c9d..6d9593f6e 100644 --- a/doc/tutorials/docbuild.rst +++ b/doc/tutorials/docbuild.rst @@ -137,7 +137,7 @@ Our documentation processing has been tested to run with: Depending on your Linux version, install the needed tools: -* For Clear Linux OS: follow the :ref:`getting-started-apl-nuc` to install +* For Clear Linux OS: follow the :ref:`kbl-nuc-sdc` to install all the tools required * For Ubuntu use: diff --git a/doc/getting-started/images/gsg-successful-boot.png b/doc/tutorials/images/gsg-successful-boot.png similarity index 100% rename from doc/getting-started/images/gsg-successful-boot.png rename to doc/tutorials/images/gsg-successful-boot.png diff --git a/doc/getting-started/apl-nuc.rst b/doc/tutorials/kbl-nuc-sdc.rst similarity index 53% rename from doc/getting-started/apl-nuc.rst rename to doc/tutorials/kbl-nuc-sdc.rst index b077a0323..5b62348da 100644 --- a/doc/getting-started/apl-nuc.rst +++ b/doc/tutorials/kbl-nuc-sdc.rst @@ -1,67 +1,17 @@ -.. _getting-started-apl-nuc: +.. _kbl-nuc-sdc: -Getting Started Guide for the Intel NUC -####################################### +Using SDC Mode on the NUC +######################### The Intel |reg| NUC is the primary tested platform for ACRN development, and its setup is described below. +Validated Version +***************** -Hardware Setup -************** - -The Intel Apollo Lake NUC (APL) and the Intel Kaby Lake NUC (KBL), -described in :ref:`hardware`, are currently supported for ACRN development. - -Note that we can enable the serial console on the `KBL `__ (NUC7i7DN), but this is not supported on the APL (NUC6CAYH). - -.. _connect_serial_port: - -Connecting to the serial port -============================= - -If you do not need a serial console, ignore this section. - -Neither the APL nor the KBL NUCs contain an external serial port interface. -However, the KBL NUC has a serial port header you can -expose with a serial DB9 header cable. You can build this cable yourself; -refer to the `KBL NUC product specification -`__ -as shown below: - -.. figure:: images/KBL-serial-port-header.png - :align: center - - KBL serial port header details - - -.. figure:: images/KBL-serial-port-header-to-RS232-cable.jpg - :align: center - - KBL `serial port header to RS232 cable - `_ - - -Or you can `purchase -`_ -such a cable. - -You'll also need an `RS232 DB9 female to USB cable -`__, -or an `RS232 DB9 female/female (NULL modem) cross-over cable -`__ -to connect to your host system. - -Note that If you want to use the RS232 DB9 female/female cable, choose the ``cross-over`` type rather than ``straight-through`` type. - -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. - +- Clear Linux version: **31470** +- ACRN-hypervisor tag: **acrn-2019w44.3-140000p** +- ACRN-Kernel(Service VM kernel): **4.19.78-95.iot-lts2018-sos** Software Setup ************** @@ -72,7 +22,7 @@ Set up a Clear Linux Operating System ===================================== We begin by installing Clear Linux as the development OS on the NUC. -The Clear Linux release includes an ``acrn.nuc6cayh.sdc.efi`` hypervisor application +The Clear Linux release includes an ``acrn.nuc7i7dnb.sdc.efi`` hypervisor application that will be added to the EFI partition (by the quick setup script or manually, as described below). @@ -81,64 +31,58 @@ manually, as described below). 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 31080 as an example). + Linux OS (we use version 31470 as an example). #. Download the compressed Clear Linux OS installer image from - https://download.clearlinux.org/releases/31080/clear/clear-31080-live-server.iso.xz + https://download.clearlinux.org/releases/31470/clear/clear-31470-live-server.iso.xz and follow the `Clear Linux OS Installation Guide `_ as a starting point for installing the Clear Linux OS onto your platform. - Follow the recommended options for choosing an **Advanced options** + Follow the recommended options for choosing an :kbd:`Advanced options` installation type, and using the platform's storage as the target device for installation (overwriting the existing data). When setting up Clear Linux on your NUC: #. Launch the Clear Linux OS installer boot menu. - #. With Clear Linux OS highlighted, select **Enter**. + #. With Clear Linux OS highlighted, select :kbd:`Enter`. #. Log in with your root account and new password. #. Run the installer using the following command:: $ clr-installer - #. From the Main menu, select **Configure Installation Media** and set - **Destructive Installation** to your desired hard disk. - #. Select **Telemetry** to set Tab to highlight your choice. - #. Press :kbd:`A` to show the **Advanced** options. - #. Select **Select additional bundles** and add bundles for - **desktop-autostart**, **editors**, **network-basic**, and **user-basic**. - #. Select **Manager User** to add an administrative user **clear** and + #. From the Main menu, select :kbd:`Configure Installation Media` and set + :kbd:`Destructive Installation` to your desired hard disk. + #. Select :kbd:`Telemetry` to set Tab to highlight your choice. + #. Press :kbd:`A` to show the :kbd:`Advanced` options. + #. Select :kbd:`Select additional bundles` and add bundles for + **network-basic**, and **user-basic**. + #. Select :kbd:`Manager User` to add an administrative user :kbd:`clear` and password. - #. Select **Install**. - #. Select **Confirm Install** in the **Confirm Installation** window to start the installation. + #. Select :kbd:`Install`. + #. Select :kbd:`Confirm Install` in the :kbd:`Confirm Installation` window to start the installation. #. After installation is complete, boot into Clear Linux OS, log in as - **clear** (using the password you set earlier). - -#. The instructions below provide details for setting - up the ACRN Hypervisor, Service OS, and Guest OS. Along with the - manual step details, 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. + :kbd:`clear` (using the password you set earlier). .. _quick-setup-guide: Use the script to set up ACRN automatically =========================================== -We provide an `acrn_quick_setup.sh script -`__ -in the ACRN GitHub repo to quickly and automatically set up the SOS and UOS -and generate a customized script for launching the UOS. +We provide an `acrn_quick_setup.sh +`_ +script in the ACRN GitHub repo to quickly and automatically set up the Service VM, +User VM and generate a customized script for launching the User VM. This script requires the Clear Linux version number you'd like to set up -for the ACRN SOS and UOS. The specified version must be greater than or +for the ACRN Service VM and User VM. The specified version must be greater than or equal to the Clear Linux version currently installed on the NUC. You can see -your current Clear Linux version with this command: +your current Clear Linux version with this command:: $ cat /etc/os-release -The following instructions use Clear Linux version 31080. Specify the Clear Linux version you want to use. +The following instructions use Clear Linux version 31470. Specify the Clear Linux version you want to use. Follow these steps: @@ -146,63 +90,45 @@ Follow these steps: #. Open a terminal. -#. Download the ``acrn_quick_setup.sh`` script to set up the SOS. (If you don't need a proxy to get the script, skip the ``export`` command.) +#. Download the ``acrn_quick_setup.sh`` script to set up the Service VM. + (If you don't need a proxy to get the script, skip the ``export`` command.) - .. code-block:: console + .. code-block:: none $ 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 31470 + +#. This output means the script ran successfully. + + .. code-block:: console - $ sudo sh acrn_quick_setup.sh -s 31080 - Password: - Upgrading SOS... - Disable auto update... - Running systemctl to disable updates - Clear Linux version 31080 is already installed. Continuing to setup SOS... - Adding the service-os, kernel-iot-lts2018 and systemd-networkd-autostart bundles... - Loading required manifests... - Downloading packs (104.41 MB) for: - - kernel-iot-lts2018-sos - - iasimage - - service-os - - kernel-iot-lts2018 - - systemd-networkd-autostart - ...100% - Finishing packs extraction... - No extra files need to be downloaded - Installing bundle(s) files... - ...100% - Calling post-update helper scripts - none - Successfully installed 3 bundles - Add /mnt/EFI/acrn folder - Copy /usr/lib/acrn/acrn.nuc6cayh.sdc.efi to /mnt/EFI/acrn/acrn.efi 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 - Getting latest Service OS kernel version: org.clearlinux.iot-lts2018-sos.4.19.73-92 - Add default (5 seconds) boot wait time. - New timeout value is: 5 - Set org.clearlinux.iot-lts2018-sos.4.19.73-92 as default boot kernel. + Add new ACRN efi boot event, uart is disabled by default. + + efibootmgr -c -l '\EFI\acrn\acrn.efi' -d /dev/sda -p 1 -L ACRN -u uart=disabled Service OS setup done! Rebooting Service OS to take effects. Rebooting. - + .. note:: This script is using ``/dev/sda1`` as the default EFI System Partition ESP). If the ESP is different based on your hardware, you can specify - it using the ``-e`` option. For example, to set up the SOS on an NVMe + it using the ``-e`` option. For example, to set up the Service VM on an NVMe SSD, you could specify: - sudo sh acrn_quick_setup.sh -s 31080 -e /dev/nvme0n1p1 + ``sudo sh acrn_quick_setup.sh -s 31470 -e /dev/nvme0n1p1`` - If you don't need to reboot automatically after setting up the SOS, you + If you don't need to reboot automatically after setting up the Service VM, you can specify the ``-d`` parameter (don't reboot). -#. After the system reboots, log in as the **clear** user. Verify that the SOS booted successfully by checking the ``dmesg`` log: + ``sudo sh acrn_quick_setup.sh -s 31470 -e /dev/nvme0n1p1 -d`` + +#. After the system reboots, log in as the **clear** user. Verify that the Service VM + booted successfully by checking the ``dmesg`` log: .. code-block:: console @@ -219,10 +145,10 @@ Follow these steps: .. code-block:: console - $ sudo sh acrn_quick_setup.sh -u 31080 + $ sudo sh acrn_quick_setup.sh -u 31470 Password: - Upgrading UOS... - Downloading UOS image: https://download.clearlinux.org/releases/31080/clear/clear-31080-kvm.img.xz + Upgrading User VM... + Downloading User VM image: https://download.clearlinux.org/releases/31470/clear/clear-31470-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 @@ -231,66 +157,16 @@ Follow these steps: .. code-block:: console - Unxz UOS image: clear-31080-kvm.img.xz - Get UOS image: clear-31080-kvm.img - Upgrade UOS done... - Now you can run this command to start UOS... - $ sudo /root/launch_uos_31080.sh + Unxz User VM image: clear-31470-kvm.img.xz + Get User VM image: clear-31470-kvm.img + Upgrade User VM done... + Now you can run this command to start User VM... + $ sudo /root/launch_uos_31470.sh -#. Launch the UOS using the customized launch_uos script (with sudo): +#. Launch the User VM using the customized ``launch_uos_31470.sh`` script (with sudo): .. code-block:: console - $ sudo /root/launch_uos_31080.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 ovmf path /usr/share/acrn/bios/OVMF.fd, size 0x200000 - pm by vuart node-index = 0 - logger: name=console, level=4 - logger: name=kmsg, level=3 - logger: name=disk, level=5 - vm_create: vm1 - VHM api version 1.0 - vm_setup_memory: size=0x80000000 - open hugetlbfs file /run/hugepage/acrn/huge_lv1/vm1/D279543825D611E8864ECB7A18B34643 - open hugetlbfs file /run/hugepage/acrn/huge_lv2/vm1/D279543825D611E8864ECB7A18B34643 - level 0 free/need pages:1/1 page size:0x200000 - level 1 free/need pages:2/2 page size:0x40000000 - - try to setup hugepage with: - level 0 - lowmem 0x0, biosmem 0x200000, highmem 0x0 - level 1 - lowmem 0x80000000, biosmem 0x0, highmem 0x0 - total_size 0x180000000 - - mmap ptr 0x0x7f792ace5000 -> baseaddr 0x0x7f7940000000 - mmap 0x80000000@0x7f7940000000 - touch 2 pages with pagesz 0x40000000 - mmap 0x200000@0x7f7a3fe00000 - touch 1 pages with pagesz 0x200000 - ... - [ 1.414873] Run /usr/lib/systemd/systemd-bootchart as init process - [ 1.521343] systemd[1]: systemd 242 running in system mode. (+PAM +AUDIT -SELINUX +IMA -APPARMOR -SMACK -SYSVINIT +UTMP +LIBCRYPTSETUP +GCRYPT +GNUTLS +ACL +XZ +LZ4 +SECCOMP +BLKID +ELFUTILS +KMOD -IDN2 -IDN -PCRE2 default-hierarchy=legacy) - [ 1.531173] systemd[1]: Detected virtualization acrn. - [ 1.533287] systemd[1]: Detected architecture x86-64. - [ 1.542775] systemd[1]: Failed to bump fs.file-max, ignoring: Invalid argument - [ 1.681326] systemd[1]: File /usr/lib/systemd/system/systemd-journald.service:12 configures an IP firewall (IPAddressDeny=any), but the local system does not support BPF/cgroup based firewalling. - [ 1.689540] systemd[1]: Proceeding WITHOUT firewalling in effect! (This warning is only shown for the first loaded unit using IP firewalling.) - [ 1.734816] [drm] Cannot find any crtc or sizes - [ 1.860168] systemd[1]: Set up automount Arbitrary Executable File Formats File System Automount Point. - [ 1.870434] systemd[1]: Listening on udev Kernel Socket. - [ 1.875555] systemd[1]: Created slice system-serial\x2dgetty.slice. - [ 1.878446] systemd[1]: Started Dispatch Password Requests to Console Directory Watch. - [ 2.075891] random: systemd-random-: uninitialized urandom read (512 bytes read) - [ 2.239775] [drm] Cannot find any crtc or sizes - [ 3.011537] systemd-journald[133]: Received request to flush runtime journal from PID 1 - [ 3.386326] i8042: PNP: PS/2 Controller [PNP0303:KBD,PNP0f13:MOU] at 0x60,0x64 irq 1,12 - [ 3.429277] i8042: Warning: Keylock active - [ 3.556872] serio: i8042 KBD port at 0x60,0x64 irq 1 - [ 3.610010] serio: i8042 AUX port at 0x60,0x64 irq 12 [ 3.658689] Adding 33788k swap on /dev/vda2. Priority:-2 extents:1 across:33788k [ 4.034712] random: dbus-daemon: uninitialized urandom read (12 bytes read) [ 4.101122] random: tallow: uninitialized urandom read (4 bytes read) @@ -304,56 +180,61 @@ Follow these steps: clr-a632ec84744d4e02974fe1891130002e login: -#. Log in as root. Specify the new password. Verify that you are running in the UOS by checking the kernel release version or seeing if acrn devices are visible: +#. Log in as root. Specify the new password. Verify that you are running in the User VM + by checking the kernel release version or seeing if acrn devices are visible: .. code-block:: console # uname -r - 4.19.73-92.iot-lts2018 + 4.19.78-95.iot-lts2018 # ls /dev/acrn* ls: cannot access '/dev/acrn*': No such file or directory - The UOS does not have ``/dev/acrn*`` devices. If you are in the SOS, + The User VM does not have ``/dev/acrn*`` devices. If you are in the Service VM, you will see results such as these: .. code-block:: console $ uname -r - 4.19.73-92.iot-lts2018-sos + 4.19.78-95.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 -You have successfully set up Clear Linux at the Service and User OS and started up a UOS VM. +You have successfully set up Clear Linux at the Service and User VM and started up a User VM. .. _manual-setup-guide: Manually Set Up ACRN ==================== -Instead of using the quick setup script, you can also set up ACRN, SOS, -and UOS manually. Follow these steps: +Instead of using the quick setup script, you can also set up ACRN, Service VM, +and User VM manually. Follow these steps: #. Install Clear Linux on the NUC, log in as the **clear** user, and open a terminal window. -#. Disable the auto-update feature. Clear Linux OS is set to automatically update itself. We recommend that you disable this feature to have more control over when updates happen. Use this command: + +#. Disable the auto-update feature. Clear Linux OS is set to automatically update itself. + We recommend that you disable this feature to have more control over when updates happen. Use this command: .. code-block:: none $ sudo swupd autoupdate --disable .. note:: - When enabled, the Clear Linux OS installer automatically checks for updates and installs the latest version available on your system. To use a specific version (such as 31080), enter the following command after the installation is complete: + When enabled, the Clear Linux OS installer automatically checks for updates and installs the latest version + available on your system. To use a specific version (such as 31470), enter the following command after the + installation is complete: - ``sudo swupd repair --picky -V 31080`` + ``sudo swupd repair --picky -V 31470`` #. If you have an older version of Clear Linux OS already installed on your hardware, use this command to upgrade the Clear Linux OS - to version 31080 (or newer): + to version 31470 (or newer): .. code-block:: none - $ sudo swupd update -V 31080 # or newer version + $ sudo swupd update -V 31470 # or newer version #. Use the ``sudo swupd bundle-add`` command to add these Clear Linux OS bundles: @@ -376,7 +257,7 @@ and UOS manually. Follow these steps: Add the ACRN hypervisor to the EFI Partition ============================================ -In order to boot the ACRN SOS on the platform, you must add it to the EFI +In order to boot the ACRN Service VM on the platform, you must add it to the EFI partition. Follow these steps: #. Mount the EFI partition and verify you have the following files: @@ -387,8 +268,8 @@ partition. Follow these steps: bootloaderx64.efi freestanding-00-intel-ucode.cpio freestanding-i915-firmware.cpio.xz - kernel-org.clearlinux.iot-lts2018-sos.4.19.73-92 - kernel-org.clearlinux.native.5.3.1-838 + kernel-org.clearlinux.iot-lts2018-sos.4.19.78-95 + kernel-org.clearlinux.native.5.3.8-854 loaderx64.efi .. note:: @@ -401,13 +282,13 @@ partition. Follow these steps: a non-volatile storage media attached via a PCI Express (PCIe) bus (NVMe). -#. Add the ``acrn.nuc6cayh.sdc.efi`` hypervisor application (included in the Clear +#. Add the ``acrn.nuc7i7dnb.sdc.efi`` hypervisor application (included in the Clear Linux OS release) to the EFI partition. Use these commands: .. code-block:: none $ sudo mkdir /boot/EFI/acrn - $ sudo cp /usr/lib/acrn/acrn.nuc6cayh.sdc.efi /boot/EFI/acrn/acrn.efi + $ sudo cp /usr/lib/acrn/acrn.nuc7i7dnb.sdc.efi /boot/EFI/acrn/acrn.efi #. Configure the EFI firmware to boot the ACRN hypervisor by default. @@ -458,14 +339,14 @@ partition. Follow these steps: .. code-block:: none $ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \ - -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=disabled" + -u "uart=disabled" Here is an example of how to enable a serial console for the KBL NUC: .. code-block:: none $ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \ - -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=port@0x3f8" + -u "uart=port@0x3f8" #. Add a timeout period for the Systemd-Boot to wait; otherwise, it will not present the boot menu and will always boot the base Clear Linux OS: @@ -480,19 +361,18 @@ partition. Follow these steps: .. code-block:: none $ sudo clr-boot-manager list-kernels - * org.clearlinux.native.5.3.1-838 - org.clearlinux.iot-lts2018-sos.4.19.73-92 + * org.clearlinux.native.5.3.8-854 + org.clearlinux.iot-lts2018-sos.4.19.78-95 - Set the default kernel from ``org.clearlinux.native.5.3.1-838`` to - ``org.clearlinux.iot-lts2018-sos.4.19.73-92``: + Set the default kernel from ``org.clearlinux.native.5.3.8-854`` to + ``org.clearlinux.iot-lts2018-sos.4.19.78-95``: .. code-block:: none - $ sudo clr-boot-manager set-kernel org.clearlinux.iot-lts2018-sos.4.19.73-92 + $ sudo clr-boot-manager set-kernel org.clearlinux.iot-lts2018-sos.4.19.78-95 $ sudo clr-boot-manager list-kernels - org.clearlinux.native.5.3.1-838 - * org.clearlinux.iot-lts2018-sos.4.19.73-92 - + org.clearlinux.native.5.3.8-854 + * org.clearlinux.iot-lts2018-sos.4.19.78-95 #. Reboot and wait until the boot menu is displayed, as shown below: @@ -500,8 +380,8 @@ partition. Follow these steps: :emphasize-lines: 1 :caption: ACRN Service OS Boot Menu - Clear Linux OS (Clear-linux-iot-lts2018-sos-4.19.73-92) - Clear Linux OS (Clear-linux-native.5.3.1-838) + Clear Linux OS (Clear-linux-iot-lts2018-sos-4.19.78-95) + Clear Linux OS (Clear-linux-native.5.3.8-854) Reboot Into Firmware Interface #. After booting up the ACRN hypervisor, the Service OS launches @@ -521,31 +401,33 @@ partition. Follow these steps: [ 1.253536] ACRN HVLog: Initialized hvlog module with 4 cpu If you see log information similar to this, the ACRN hypervisor is running properly -and you can start deploying a User OS. If not, verify the EFI boot options, and SOS +and you can start deploying a User OS. If not, verify the EFI boot options, and Service VM kernel settings are correct (as described above). - ACRN Network Bridge =================== The ACRN bridge has been set up as a part of systemd services for device -communication. The default bridge creates ``acrn_br0`` which is the bridge and ``tap0`` as an initial setup. The files can be found in ``/usr/lib/systemd/network``. No additional setup is needed since systemd-networkd is +communication. The default bridge creates ``acrn_br0`` which is the bridge and ``tap0`` as an initial setup. +The files can be found in ``/usr/lib/systemd/network``. No additional setup is needed since **systemd-networkd** is automatically enabled after a system restart. -Set up Reference UOS -==================== +Set up Reference User VM +======================== -#. On your platform, download the pre-built reference Clear Linux OS UOS - image version 31080 (or newer) into your (root) home directory: +#. On your platform, download the pre-built reference Clear Linux OS User VM + image version 31470 (or newer) into your (root) home directory: .. code-block:: none $ cd ~ $ mkdir uos $ cd uos - $ curl https://download.clearlinux.org/releases/31080/clear/clear-31080-kvm.img.xz -o uos.img.xz + $ curl https://download.clearlinux.org/releases/31470/clear/clear-31470-kvm.img.xz -o uos.img.xz - Note that if you want to use or try out a newer version of Clear Linux OS as the UOS, download the latest from http://download.clearlinux.org/image/. Make sure to adjust the steps described below accordingly (image file name and kernel modules version). + Note that if you want to use or try out a newer version of Clear Linux OS as the User VM, download the + latest from `http://download.clearlinux.org/image/`. + Make sure to adjust the steps described below accordingly (image file name and kernel modules version). #. Uncompress it: @@ -553,7 +435,8 @@ Set up Reference UOS $ unxz uos.img.xz -#. Deploy the UOS kernel modules to the UOS virtual disk image (note that you'll need to use the same **iot-lts2018** image version number noted in Step 1 above): +#. Deploy the User VM kernel modules to the User VM virtual disk image (note that you'll need to + use the same **iot-lts2018** image version number noted in Step 1 above): .. code-block:: none @@ -568,12 +451,12 @@ Set up Reference UOS $ sudo umount /mnt $ sync -#. Edit and run the ``launch_uos.sh`` script to launch the UOS. +#. Edit and run the ``launch_uos.sh`` script to launch the User VM. A sample `launch_uos.sh `__ is included in the Clear Linux OS release, and - is also available in the acrn-hypervisor/devicemodel GitHub repo (in the samples + is also available in the ``acrn-hypervisor/devicemodel`` GitHub repo (in the samples folder) as shown here: .. literalinclude:: ../../../../devicemodel/samples/nuc/launch_uos.sh @@ -588,7 +471,7 @@ Set up Reference UOS $ cd /usr/share/acrn/samples/nuc/ $ sudo ./launch_uos.sh -#. You have successfully booted the ACRN hypervisor, SOS, and UOS: +#. You have successfully booted the ACRN hypervisor, Service VM, and User VM: .. figure:: images/gsg-successful-boot.png :align: center diff --git a/doc/tutorials/skl-nuc.rst b/doc/tutorials/skl-nuc.rst index 2b2398637..e94b823a1 100644 --- a/doc/tutorials/skl-nuc.rst +++ b/doc/tutorials/skl-nuc.rst @@ -36,7 +36,7 @@ enabling GPU passthrough: Software Setup ************** -Please follow the :ref:`getting-started-apl-nuc`, with the following changes: +Please follow the :ref:`kbl-nuc-sdc`, with the following changes: 1. Set up a Clear Linux Operating System diff --git a/doc/tutorials/using_agl_as_uos.rst b/doc/tutorials/using_agl_as_uos.rst index b7989b51d..62f197f94 100644 --- a/doc/tutorials/using_agl_as_uos.rst +++ b/doc/tutorials/using_agl_as_uos.rst @@ -29,7 +29,7 @@ For more information about AGL, please visit `AGL's official website Steps for using AGL as the UOS ****************************** -#. Follow the instructions found in the :ref:`getting-started-apl-nuc` to +#. Follow the instructions found in the :ref:`kbl-nuc-sdc` to boot "The ACRN Service OS" #. In SOS, download the release of AGL from https://download.automotivelinux.org/AGL/release/eel/. @@ -52,7 +52,7 @@ Steps for using AGL as the UOS $ sync .. note:: - Follow the instructions in :ref:`getting-started-apl-nuc`, + Follow the instructions in :ref:`kbl-nuc-sdc`, the ``linux-iot-lts2018`` kernels and modules will be installed by default after adding the bundle ``kernel-iot-lts2018``. Here the version of modules is ``4.19.0-27.iot-lts2018``. diff --git a/doc/tutorials/using_celadon_as_uos.rst b/doc/tutorials/using_celadon_as_uos.rst index d410f45eb..822b3b8c7 100644 --- a/doc/tutorials/using_celadon_as_uos.rst +++ b/doc/tutorials/using_celadon_as_uos.rst @@ -79,7 +79,7 @@ Build Celadon from source Steps for Using Celadon as the User OS ************************************** -#. Follow :ref:`getting-started-apl-nuc` to boot the ACRN Service OS based on Clear Linux 29880. +#. Follow :ref:`kbl-nuc-sdc` to boot the ACRN Service OS based on Clear Linux 29880. #. Prepare dependencies on your NUC:: diff --git a/doc/tutorials/using_partition_mode_on_nuc.rst b/doc/tutorials/using_partition_mode_on_nuc.rst index b8537a572..9bb314171 100644 --- a/doc/tutorials/using_partition_mode_on_nuc.rst +++ b/doc/tutorials/using_partition_mode_on_nuc.rst @@ -22,7 +22,7 @@ Prerequisites ************* * `Intel NUC Kit NUC7i7DNHE `_ -* Connecting to the serial port, described in :ref:`getting-started-apl-nuc` +* Connecting to the serial port, described in :ref:`kbl-nuc-sdc` * NVMe disk * SATA disk * Storage device with USB interface (such as USB Flash diff --git a/doc/tutorials/using_sdc2_mode_on_nuc.rst b/doc/tutorials/using_sdc2_mode_on_nuc.rst index 2326e3174..ba326aa86 100644 --- a/doc/tutorials/using_sdc2_mode_on_nuc.rst +++ b/doc/tutorials/using_sdc2_mode_on_nuc.rst @@ -15,7 +15,7 @@ process can be applied to launch a third Linux VM as well. ACRN Service VM Setup ********************* -Follow the steps in :ref:`getting-started-apl-nuc` to set up ACRN on an +Follow the steps in :ref:`kbl-nuc-sdc` to set up ACRN on an Intel NUC. The target device must be capable of launching a Clear Linux User VM as a starting point. diff --git a/doc/tutorials/using_ubuntu_as_sos.rst b/doc/tutorials/using_ubuntu_as_sos.rst index 66a09a8b1..e8565a617 100644 --- a/doc/tutorials/using_ubuntu_as_sos.rst +++ b/doc/tutorials/using_ubuntu_as_sos.rst @@ -7,7 +7,7 @@ This document builds on the :ref:`getting_started`, and explains how to use Ubuntu instead of using `Clear Linux OS`_ as the Service OS with the ACRN hypervisor. (Note that different OSes can be used for the Service and User OS.) In the following instructions we'll build on material in the -:ref:`getting-started-apl-nuc`. +:ref:`kbl-nuc-sdc`. Install Ubuntu (natively) ************************* @@ -337,7 +337,7 @@ script example shows how to set this up (verified in Ubuntu 16.04 and 18.04 as t Enabling USB keyboard and mouse ******************************* -Please refer to :ref:`getting-started-apl-nuc` for enabling the +Please refer to :ref:`kbl-nuc-sdc` for enabling the USB keyboard and mouse for the UOS. diff --git a/doc/tutorials/using_vxworks_as_uos.rst b/doc/tutorials/using_vxworks_as_uos.rst index c4b6d9f17..c18e94057 100644 --- a/doc/tutorials/using_vxworks_as_uos.rst +++ b/doc/tutorials/using_vxworks_as_uos.rst @@ -92,7 +92,7 @@ Steps for Using VxWorks as User OS You now have a virtual disk image with bootable VxWorks in ``VxWorks.img``. -#. Follow :ref:`getting-started-apl-nuc` to boot "The ACRN Service OS". +#. Follow :ref:`kbl-nuc-sdc` to boot "The ACRN Service OS". #. Boot VxWorks as User OS. diff --git a/doc/tutorials/using_windows_as_uos.rst b/doc/tutorials/using_windows_as_uos.rst index 927c57626..54faac614 100644 --- a/doc/tutorials/using_windows_as_uos.rst +++ b/doc/tutorials/using_windows_as_uos.rst @@ -16,7 +16,7 @@ The following Intel Kaby Lake NUCs are verified: ACRN Service VM Setup ********************* -You may refer to the steps in :ref:`getting-started-apl-nuc` for +You may refer to the steps in :ref:`kbl-nuc-sdc` for Intel NUC to set up ACRN on the KBL NUC. After following the steps in that guide, you should be able to launch the Service VM successfully. diff --git a/doc/tutorials/using_zephyr_as_uos.rst b/doc/tutorials/using_zephyr_as_uos.rst index 3d1b65f9a..536197000 100644 --- a/doc/tutorials/using_zephyr_as_uos.rst +++ b/doc/tutorials/using_zephyr_as_uos.rst @@ -86,7 +86,7 @@ Steps for Using Zephyr as User OS You now have a virtual disk image with a bootable Zephyr in ``zephyr.img``. If the Zephyr build system is not the ACRN SOS, then you will need to transfer this image to the ACRN SOS (via, e.g, a USB stick or network ) -#. Follow :ref:`getting-started-apl-nuc` to boot "The ACRN Service OS" based on Clear Linux OS 28620 +#. Follow :ref:`kbl-nuc-sdc` to boot "The ACRN Service OS" based on Clear Linux OS 28620 (ACRN tag: acrn-2019w14.3-140000p) #. Boot Zephyr as User OS