`version_find_latest` is removed in grub 2.12, replace it with
`sort -V -r` for maximum compatibility.
Tracked-On: #8576
Signed-off-by: Jiaqing Zhao <jiaqing.zhao@linux.intel.com>
Reviewed-by: Junjie Mao <junjie.mao@intel.com>
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
ACRN Debianization
==================
ACRN is a flexible, lightweight reference hypervisor, built with
real-time and safety-criticality in mind, optimized to streamline
embedded development through an open source platform. This part
represents the debianization for ACRN.
Table of Contents
-----------------
1. `Building <#building>`__
2. `Development Build from Source
Package <#development-build-from-source-package>`__
3. `Package Maintenance <#package-maintenance>`__
4. `Special Package Properties <#special-package-properties>`__
5. `About initramfs on Debian/Ubuntu
Systems <#about-initramfs-on-debianubuntu-systems>`__
6. `Scenario Configuration - GRUB
configuration <#scenario-configuration---grub-configuration>`__
7. `Known Build Warnings <#known-build-warnings>`__
8. `General Remarks and
Restrictions <#general-remarks-and-restrictions>`__
The Debian source package ``acrn-hypervisor`` provides the following
Debian packages:
- ``acrn-dev``: Public headers and libraries for ACRN manager.
- ``acrn-devicemodel``: Device model for ACRN Hypervisor
- ``acrn-doc``: Reference to ACRN Documentation
- ``acrn-hypervisor``: ACRN Hypervisor for IoT
- ``acrn-lifemngr``: ACRN life manager service
- ``acrn-system``: metapackage to deploy a minimum of ACRN packages
- ``acrn-tools``: Supplementary tools for ACRN Hypervisor
- ``acrnd``: ACRN Hypervisor control daemon
- ``grub-acrn``: Grub setup scripts for ACRN Hypervisor
- ``python3-acrn-board-inspector``: Generate Board Configuration for
ACRN
Building
--------
The ``acrn-hypervisor`` source package uses ``git-buildpackage``
(``gbp``) for package building (see ``debian/gbp.conf``). For more
information on ``gbp`` refer to the `Git-Buildpackage
manual <http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html>`__.
To ease the build process a shell script wrapper around a docker
controlled build is provided:
::
debian/docker/acrn-docker-build.sh
This script features the ``DISTRO`` and ``VENDOR`` environment variables
to set the Debian or Ubuntu distribution the ACRN packages are built
for. ``VENDOR`` defaults to ``debian`` and ``DISTRO`` defaults to
``stable``, which then is transformed to its canonical name
(``bullseye`` for now).
To build ACRN packages on master branch for Debian Buster use:
::
VENDOR=debian DISTRO=buster debian/docker/acrn-docker-build.sh
or for Ubuntu 20.04:
VENDOR=ubuntu DISTRO=focal debian/docker/acrn-docker-build.sh
If building on any other branch, the ``debian/gbp.conf`` file has to be
adapted accordingly. To override this necessity simply add a
``--git-ignore-branch``:
::
debian/docker/acrn-docker-build.sh --git-ignore-branch
This not only builds the ACRN packages listed above, but eventually all
required packages (for build or runtime), too.
Remark: Since the required, dependent package repositories are accessed
at build time, your build machine needs a properly configured internet
access.
All these build results including the required third party packages are
located in the ``build/<distroname>`` folder and prepared to be used as
a local APT repository. To use it as such, add a proper apt
configuration (assuming the result folder has been copied to ``/apt``):
::
echo "deb [trusted=yes] file:/apt ./" > /etc/apt/sources.list.d/acrn-local.list
echo "deb-src [trusted=yes] file:/apt ./" >> /etc/apt/sources.list.d/acrn-local.list
Now ``apt update`` will also take into account all the local packages,
so you can easily install, e.g.board-inspector via:
::
apt install python3-acrn-board-inspector
This will install python3-acrn-board-inspector with all required
dependencies.
Development Build from Source Package
-------------------------------------
Once the local APT repository is in place, it can also be used to
quickly create proprietary built ACRN packages from the acrn-hypervisor
soure package, e.g.to add a new scenario for testing or change the list
of supported board. Many thanks to Pirouf for bringing in this idea!
::
apt-get install devscripts build-essential
cd <working dir>
apt-get source acrn-hypervisor
apt-get build-dep acrn-hypervisor
cd acrn-hypervisor-<version>
Now you can make your changes, e.g.use a new board and scenario, preferrably using ``debian/config`` as a hook directory for proprietary configurations, see also `debian/configs/README.rst <configs/README.rst>`__:
::
mkdir -p debian/config/newboard
cp <user>/newboard.xml debian/config/newboard/newboard.xml
cp <user>/newscenario.xml debian/config/newboard/newscenario.xml
cat << EOF > debian/config/configurations.mk
ACRN_BOARDLIST += newboard
ACRN_SCENARIOLIST += newscenario
EOF
dpkg-buildpackage
The resulting packages are then located in ``<working dir>``.
Package Maintenance
-------------------
During development ``debian/changelog`` should always present the
``UNRELEASED`` stage of package build. Before creating new (temporary)
packages ``debian/changelog`` can be easily updated using
::
DEBEMAIL="<add your email here> DEBFULLNAME="<enter your full name here>" gbp dch --snapshot --git-ignore-branch
This updates/creates an ``UNRELEASED`` changelog entry, which has to be
committed separately. BTW, I always use the following to align with what
is already configured in git:
::
DEBEMAIL=$(git config user.email) DEBFULLNAME=$(git config user.name) gbp dch --snapshot --git-ignore-branch
At release create a proper entry using
::
DEBEMAIL="<add your email here> DEBFULLNAME="<enter your full name here>" gbp dch --release
This fires up the editor to review the newly created
``debian/changelog`` entry. Edit, save and commit it to finish the
package release from a Debian point of view.
Special Package Properties
--------------------------
acrn-hypervisor
~~~~~~~~~~~~~~~
This package contains multiple ACRN hypervisor binaries, with the final
binary being chosen usually at install time via Debian’s ``debconf``
mechanism. This allows you to choose the board as well as the respective
scenario but still use the same Debian package for various hardware
platforms.
**WARNING**
Always choose an appropriate board/scenario setting! Wrong settings may
refuse to boot!
You can also preseed your choice by setting the respective ``debconf``
keys ``acrn-hypervisor/board`` and ``acrn-hypervisor/scenario``,
e.g.during image creation. Please refer to
https://wiki.debian.org/debconf for details.
To reconfigure the choice later, use
::
dpkg-reconfigure acrn-hypervisor
The ACRN hypervisor configurations are chosen as follows: All
directories given in ``CONFIGDIRS`` in ``acrn-hypervisor.conf.mk`` are
searched for valid board- and scenario-configuration files. The
``ACRN_BOARDLIST`` and ``ACRN_SCENARIOLIST`` in
``acrn-hypervisor.conf.mk`` can be used to restrict the
hypervisor/scenario configurations built into ``acrn-hypervisor``
package. If unset, all possible configurations found under the
directories given are built.
acrn-lifemngr
~~~~~~~~~~~~~
To adapt the needs of a Debian distribution the service file has been
adapted and a start script wrapper added to automatically set up the
parameters for User VMs or the Service VM.
acrnd
~~~~~
There is also an adapted variant for the systemd service file. As for
``acrn-lifemngr`` this also is provided as part of the Debian packaging
process rather than patching the files provided with the sources.
About initramfs on Debian/Ubuntu Systems
----------------------------------------
If the ``ramdisk_mod`` node in the scenario configuration is empty (at
the moment this is true especially for all ``shared`` scenarios), an
initrd/initramfs image is neither required nor used. Grub config helper
then creates a rootfs parameter using the respective device name at
install time, like ``/dev/sda2``. Since this depends on device
enumeration of the kernel, which might change when additional storage
devices are added (your ``/dev/sda2`` might turn into
e.g.``/dev/sdb2``, but your grub configuration stays unchanged!)
Debian/Ubuntu decided to use UUIDs to identify the storage device
partitions. This is implemented by respective scripts provided in
initrd/initramfs and **NOT** within the kernel, so apparently
initrd/initramfs is required!
To use this feature properly (as the standard distribution setup does)
add a ``ramdisk_mod`` node value (usually ``Linux_initrd``) in the
scenario configuration and provide a kernel package with
initrd/initramfs support. This is state-of-the-art nowadays and also
supported by the acrn-kernel service vm configuration. It enables the
UUID boot device support and avoids the device enumeration issues
completely, see the ``shared+initrd`` scenarios in ``debian/configs``
for an example.
Scenario Configuration - GRUB configuration
-------------------------------------------
The following subnodes of the ``SERVICE_VM`` node (VM with
``load_order=SERVICE_VM``) are considered by grub-acrn when creating the
GRUB menu entries for ACRN:
- ``kern_mod`` must not be empty to add a menu entry
- ``ramdisk_mod`` enables initrd/initramfs image usage (see above)
- ``bootargs``: kernel boot parameters, that are added to the kernel
boot command line. Exception: ``rootfs`` parameter is ignored, since
this is automatically determined by GRUB config helpers. This can be
used e.g.to add ``hvlog`` parameter for logging support.
Known Build Warnings
--------------------
Depending to which distribution the build is targeted, the following
warnings can occur, but can safely be ignored:
- in ``override_dh_strip`` build stage:
These warnings only occur in builds for the most recent
distributions, but do not harm the binary packages. The usability of
dbgsym packages is questionable in this case (untested).
- ``debugedit: .debug_line offset 0xXXXX referenced multiple times``
- ``Unknown DWARF DW_FORM 0xXXXX``
- in ``override_dh_auto_build-indep`` build stage:
- ``package init file '<...>/__init__.py' not found (or not a regular file)``
This is a result of the the python components not being structured
for packaging with setuptools. The warnings are harmless and do not
imply any restrictions to the python packages.
- in ``override_dh_auto_install-arch`` build stage
- ``/usr/bin/ld: <...>/boot_mod.a(cpu_primary.o): warning: relocation in read-only section 'multiboot_header'``
This warning is emitted on all but the oldest distros (gcc/binutils
version dependent?). **This might be of concern and must be
investigated.** Up till now, no issues have been found when using the
binaries triggering this warning.
- lintian
- ``elf-error In program headers: Unable to find program interpreter name``
This is a known issue, see `Debian
Bug#1000977 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1000977>`__
and `Debian
Bug#1000449 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1000449>`__.
General Remarks and Restrictions
--------------------------------
- ACRN >=2.6 needs a Linux 5.10 kernel with the respective Intel/ACRN
patches applied, see `Project ACRN
Documentation <https://projectacrn.github.io/latest/index.html>`__
for details.
- The packages are built in debug mode to be able to access the HV
console. This can be changed by setting the ``RELEASE`` variable in
``debian/rules`` to 1.
- The built configurations are restricted to the hardware platforms
available for testing.
- The systemd services provided by various ACRN packages are enabled at
install time but not started, since they are most likely installed on
a non-ACRN system which requires a reboot anyway. Only the acrn-tools
related services (acrnlog, acrnprobe, usercrash) might be installed
on a running ACRN system and then either need a reboot or must be
started manually (``systemd start <service name>``).
- acrn-configurator is still under heavy development and therefore not
yet packaged.
-- Helmut Buchsbaum <helmut.buchsbaum@opensource.tttech-industrial.com>
Sat, 06 May 2022 20:07:19 +0200
40d6172247