github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-24 14:33:38 +00:00
Code Issues Projects Releases Wiki Activity

doc: update gsg to adapt latest release

Browse Source 
1, changed Clear Linux installation from "automatically" to "manually"
2, removed bundle "soft-defined-cockpit" installation
3, removed bundle "openssh-server" installation
4, add a bundle"desktop-autostart" as the default installation. so that a desktop is showing for the first time reboot after setup done
5, add a non room user with “sudoers” privilege to avoid using root directly
6,  removed section "Device Manager memory allocation mechanism"

Tracked-On: #1794
Signed-off-by: ailun258 <ailin.yang@intel.com>
This commit is contained in:
ailin,yang 2018-12-05 14:41:32 +08:00 committed by David Kinder
parent e24039a7ef
commit f657f40157
1 changed files with 63 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

168
doc/getting-started/apl-nuc.rst
View File

@ -47,12 +47,21 @@ complete this setup.
and follow the `Clear Linux installation guide and follow the `Clear Linux installation guide
<https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install>`__ <https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install>`__
as a starting point for installing Clear Linux onto your platform. Follow the recommended as a starting point for installing Clear Linux onto your platform. Follow the recommended
options for choosing an **Automatic** installation type, and using the platform's options for choosing an **Manual (Advanced)** installation type, and using the platform's
storage as the target device for installation (overwriting the existing data storage as the target device for installation (overwriting the existing data
and creating three partitions on the platform's storage drive). and creating three partitions on the platform's storage drive).
High-level steps should be:
#. Install Clear on a NUC using the "Manual (Advanced)" option.
#. Use default partition scheme for storage
#. Name the host "clr-sos-guest"
#. Add an administrative user "clear" with "sudoers" privilege
#. Add these additional bundles "editors", "user-basic", "desktop-autostart", "network-basic"
#. For network, choose “DHCP”
#. After installation is complete, boot into Clear Linux, login as #. After installation is complete, boot into Clear Linux, login as
**root**, and set a password. **clear**, and set a password.
#. Clear Linux is set to automatically update itself. We recommend that you disable #. Clear Linux 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 this feature to have more control over when the updates happen. Use this command
@ -60,13 +69,13 @@ complete this setup.
.. code-block:: none .. code-block:: none
# swupd autoupdate --disable $ sudo swupd autoupdate --disable
.. note:: .. note::
The Clear Linux installer will automatically check for updates and install the The Clear Linux installer will automatically check for updates and install the
latest version available on your system. If you wish to use a specific version latest version available on your system. If you wish to use a specific version
(such as 26200), you can achieve that after the installation has completed using (such as 26200), you can achieve that after the installation has completed using
``swupd verify --fix --picky -m 26200`` ``sudo swupd verify --fix --picky -m 26200``
#. If you have an older version of Clear Linux already installed #. If you have an older version of Clear Linux already installed
on your hardware, use this command to upgrade Clear Linux on your hardware, use this command to upgrade Clear Linux
@ -74,14 +83,13 @@ complete this setup.
.. code-block:: none .. code-block:: none
# swupd update -m 26200 # or newer version $ sudo swupd update -m 26200 # or newer version
#. Use the ``swupd bundle-add`` command and add these Clear Linux bundles: #. Use the ``sudo swupd bundle-add`` command and add these Clear Linux bundles:
.. code-block:: none .. code-block:: none
# swupd bundle-add vim sudo network-basic service-os kernel-iot-lts2018 \ $ sudo swupd bundle-add service-os kernel-iot-lts2018
openssh-server software-defined-cockpit
.. table:: Clear Linux bundles .. table:: Clear Linux bundles
:widths: auto :widths: auto
@ -90,25 +98,13 @@ complete this setup.
+--------------------+---------------------------------------------------+ +--------------------+---------------------------------------------------+
| Bundle | Description | | Bundle | Description |
+====================+===================================================+ +====================+===================================================+
| vim | vim text editor |
+--------------------+---------------------------------------------------+
| sudo | sudo command |
+--------------------+---------------------------------------------------+
| network-basic | Run network utilities and modify network settings |
+--------------------+---------------------------------------------------+
| service-os | Add the acrn hypervisor, the acrn devicemodel and | | service-os | Add the acrn hypervisor, the acrn devicemodel and |
| | Service OS kernel | | | Service OS kernel |
+--------------------+---------------------------------------------------+ +--------------------+---------------------------------------------------+
| kernel-iot-lts2018 | Run the Intel kernel"kernel-iot-lts2018" | | kernel-iot-lts2018 | Run the Intel kernel"kernel-iot-lts2018" |
| | which is enterprise-style kernel with backports | | | which is enterprise-style kernel with backports |
+--------------------+---------------------------------------------------+ +--------------------+---------------------------------------------------+
| openssh-server | Server-side support for secure connectivity and |
| | remote login using the SSH protocol |
+--------------------+---------------------------------------------------+
| software-defined | Run the automotive software defined cockpit |
| -cockpit | which has graphic, media, sound and connectivity |
| | |
+--------------------+---------------------------------------------------+
Add the ACRN hypervisor to the EFI Partition Add the ACRN hypervisor to the EFI Partition
============================================ ============================================
@ -120,16 +116,16 @@ partition. Follow these steps:
.. code-block:: none .. code-block:: none
# mount /dev/sda1 /mnt $ sudo ls -1 /boot/EFI/org.clearlinux
# ls -1 /mnt/EFI/org.clearlinux
bootloaderx64.efi bootloaderx64.efi
kernel-org.clearlinux.native.4.19.1-654 kernel-org.clearlinux.native.4.19.1-654
kernel-org.clearlinux.iot-lts2018-sos.4.19.0-19 kernel-org.clearlinux.iot-lts2018-sos.4.19.0-19
kernel-org.clearlinux.iot-lts2018.4.19.0-19 kernel-org.clearlinux.iot-lts2018.4.19.0-19
kernel-org.clearlinux.pk414-sos.4.14.74-115
loaderx64.efi loaderx64.efi
.. note:: .. note::
On Clear Linux, the EFI System Partion (e.g.: ``/dev/sda1``) is mounted under ``/boot`` by default
The Clear Linux project releases updates often, sometimes The Clear Linux project releases updates often, sometimes
twice a day, so make note of the specific kernel versions (*iot-lts2018 and *iot-lts2018-sos*) listed on your system, twice a day, so make note of the specific kernel versions (*iot-lts2018 and *iot-lts2018-sos*) listed on your system,
as you will need them later. as you will need them later.
@ -146,8 +142,8 @@ partition. Follow these steps:
.. code-block:: none .. code-block:: none
# mkdir /mnt/EFI/acrn $ sudo mkdir /boot/EFI/acrn
# cp /usr/lib/acrn/acrn.efi /mnt/EFI/acrn/ $ sudo cp /usr/lib/acrn/acrn.efi /boot/EFI/acrn/
#. Configure the EFI firmware to boot the ACRN hypervisor by default #. Configure the EFI firmware to boot the ACRN hypervisor by default
@ -158,7 +154,7 @@ partition. Follow these steps:
.. code-block:: none .. code-block:: none
# efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN" $ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN"
.. note:: .. note::
@ -189,7 +185,7 @@ partition. Follow these steps:
.. code-block:: none .. code-block:: none
# efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \ $ 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 "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=disabled"
#. Create a boot entry for the ACRN Service OS by copying a provided ``acrn.conf`` #. Create a boot entry for the ACRN Service OS by copying a provided ``acrn.conf``
@ -219,7 +215,7 @@ partition. Follow these steps:
.. code-block:: none .. code-block:: none
# cp /usr/share/acrn/samples/nuc/acrn.conf /mnt/loader/entries/ $ sudo cp /usr/share/acrn/samples/nuc/acrn.conf /boot/loader/entries/
You will need to edit this file to adjust the kernel version (``linux`` section), You will need to edit this file to adjust the kernel version (``linux`` section),
insert the ``PARTUUID`` of your ``/dev/sda3`` partition insert the ``PARTUUID`` of your ``/dev/sda3`` partition
@ -231,28 +227,17 @@ partition. Follow these steps:
.. note:: .. note::
It is also possible to use the device name directly, e.g. ``root=/dev/sda3`` It is also possible to use the device name directly, e.g. ``root=/dev/sda3``
.. code-block:: none
#. Add a timeout period for Systemd-Boot to wait, otherwise it will not #. 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 present the boot menu and will always boot the base Clear Linux
.. code-block:: none .. code-block:: none
# clr-boot-manager set-timeout 20 $ sudo clr-boot-manager set-timeout 20
# clr-boot-manager update $ sudo clr-boot-manager update
#. Add new user
.. code-block:: none
# useradd cl_sos
# passwd cl_sos
# usermod -G wheel -a cl_sos
#. Enable weston service
.. code-block:: none
# systemctl enable weston@cl_sos
# systemctl start weston@cl_sos
#. Reboot and select "The ACRN Service OS" to boot, as shown below: #. Reboot and select "The ACRN Service OS" to boot, as shown below:
@ -269,32 +254,26 @@ partition. Follow these steps:
Reboot Into Firmware Interface Reboot Into Firmware Interface
#. After booting up the ACRN hypervisor, the Service OS will be launched #. After booting up the ACRN hypervisor, the Service OS will be launched
automatically by default, as shown here: automatically by default, and the Clear Linux desktop will be showing with user "clear",
(or you can login remotely with an "ssh" client).
If there is any issue which makes the GNOME desktop doens't show succesfully, then the system will go to
shell console.
.. code-block:: console #. From ssh client, login as user "clear" using the password you set previously when
:caption: Service OS Console
clr-7259a7c5bbdd4bcaa9a59d5841b4ace login: root
You are required to change your password immediately (administrator enforced)
New password:
Retype new password:
root@clr-7259a7c5bbdd4bcaa9a59d5841b4ace ~ # _
.. note:: You may need to hit ``Enter`` to get a clean login prompt
#. From here you can login as root using the password you set previously when
you installed Clear Linux. you installed Clear Linux.
#. (**Optional**) The ``software-defined-cockpit`` bundle installs the #. After rebooting the system, check that the ACRN hypervisor is running properly with:
``ioc-cbc-tools`` on the system and activates three ``systemd`` services.
Those services do not work on off-the-shelf platforms such as NUCs, UP2.
You can disable them as shown here:
.. code-block:: none .. code-block:: none
# systemctl mask cbc_attach $ dmesg | grep ACRN
# systemctl mask cbc_lifecycle [ 0.000000] Hypervisor detected: ACRN
# systemctl mask cbc_thermald [ 1.687128] ACRNTrace: acrn_trace_init, cpu_num 4
[ 1.693129] ACRN HVLog: acrn_hvlog_init
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, SOS
kernel, and ``acrn.conf`` settings are correct (as described above).
ACRN Network Bridge ACRN Network Bridge
@ -313,8 +292,10 @@ Set up Reference UOS
.. code-block:: none .. code-block:: none
# cd ~ $ cd ~
# curl -O https://download.clearlinux.org/releases/26200/clear/clear-26200-kvm.img.xz $ mkdir uos
$ cd uos
$ curl -O https://download.clearlinux.org/releases/26200/clear/clear-26200-kvm.img.xz
.. note:: .. note::
In case you want to use or try out a newer version of Clear Linux as the UOS, you can In case you want to use or try out a newer version of Clear Linux as the UOS, you can
@ -325,18 +306,18 @@ Set up Reference UOS
.. code-block:: none .. code-block:: none
# unxz clear-26200-kvm.img.xz $ unxz clear-26200-kvm.img.xz
#. Deploy the UOS kernel modules to UOS virtual disk image (note: you'll need to use #. Deploy the UOS kernel modules to UOS virtual disk image (note: you'll need to use
the same **standard** image version number noted in step 1 above): the same **iot-lts2018** image version number noted in step 1 above):
.. code-block:: none .. code-block:: none
# losetup -f -P --show /root/clear-26200-kvm.img $ sudo losetup -f -P --show clear-26200-kvm.img
# mount /dev/loop0p3 /mnt $ sudo mount /dev/loop0p3 /mnt
# cp -r /usr/lib/modules/4.19.0-19.iot-lts2018 /mnt/lib/modules/ $ sudo cp -r /usr/lib/modules/4.19.0-19.iot-lts2018 /mnt/lib/modules/
# umount /mnt $ sudo umount /mnt
# sync $ sync
#. Edit and Run the ``launch_uos.sh`` script to launch the UOS. #. Edit and Run the ``launch_uos.sh`` script to launch the UOS.
@ -355,23 +336,17 @@ Set up Reference UOS
In case you have downloaded a different Clear Linux image than the one above In case you have downloaded a different Clear Linux image than the one above
(``clear-26200-kvm.img.xz``), you will need to modify the Clear Linux file name (``clear-26200-kvm.img.xz``), you will need to modify the Clear Linux file name
and version number highlighted above (the ``-s 3,virtio-blk`` argument) to match and version number highlighted above (the ``-s 3,virtio-blk`` argument) to match
what you have downloaded above. Likewise, you may need to adjust the kernel file what you have downloaded above. Otherwise, you may need to adjust the kernel file
name on the second line highlighted (check the exact name to be used using: name on the second line highlighted (check the exact name to be used using:
``ls /usr/lib/kernel/org.clearlinux*-standard*``). ``ls /usr/lib/kernel/org.clearlinux.iot-lts2018*``).
.. note::
The script uses ``/usr/lib/kernel/default-iot-lts2018`` which is a symlink
to the latest ``*-iot-lts2018`` installed on the system. This provides a
sane default but double-check the version in case things do not work as
expected.
By default, the script is located in the ``/usr/share/acrn/samples/nuc/`` By default, the script is located in the ``/usr/share/acrn/samples/nuc/``
directory. You can edit it there, and then run it to launch the User OS: directory. You can edit it there, and then run it to launch the User OS:
.. code-block:: none .. code-block:: none
# cd /usr/share/acrn/samples/nuc/ $ cd /usr/share/acrn/samples/nuc/
# ./launch_uos.sh $ sudo ./launch_uos.sh
#. At this point, you've successfully booted the ACRN hypervisor, #. At this point, you've successfully booted the ACRN hypervisor,
SOS, and UOS: SOS, and UOS:
@ -381,30 +356,6 @@ Set up Reference UOS
:name: gsg-successful-boot :name: gsg-successful-boot
Device Manager memory allocation mechanism
==========================================
The ACRN Device Manager (DM) virtual memory allocation uses the HugeTLB mechanism.
(You can read more about `HugeTLB in the linux kernel <https://linuxgazette.net/155/krishnakumar.html>`_
for more information about how this mechanism works.)
For hugeTLB to work, you'll need to reserve huge pages:
- For a (large) 1GB huge page reservation, add ``hugepagesz=1G hugepages=reserved_pg_num``
(for example, ``hugepagesz=1G hugepages=4``) to the SOS cmdline in
``acrn.conf`` (for EFI)
- For a (smaller) 2MB huge page reservation, after the SOS starts up, run the
command::
echo reserved_pg_num > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
.. note::
You can use 2M reserving method to do reservation for 1G page size, but it
may fail. For an EFI platform, you may skip 1G page reservation
by using a 2M page, but make sure your huge page reservation size is
large enough for your usage.
Build ACRN from Source Build ACRN from Source
********************** **********************
@ -649,3 +600,4 @@ example above) to 'BOARD=':
.. code-block:: none .. code-block:: none
$ make defconfig BOARD=xxx $ make defconfig BOARD=xxx