mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-09-06 11:20:32 +00:00
Doc: content updates to ACRN Config Tool and Build frm Source
Signed-off-by: Deb Taylor <deb.taylor@intel.com>
This commit is contained in:
Deb Taylor
deb-intel
@@ -6,69 +6,68 @@ Build ACRN from Source
|
||||
Introduction
|
||||
************
|
||||
|
||||
Following a general embedded system programming model, the ACRN
|
||||
hypervisor is designed to be customized at build-time per hardware
|
||||
Following a general embedded-system programming model, the ACRN
|
||||
hypervisor is designed to be customized at build time per hardware
|
||||
platform and per usage scenario, rather than one binary for all
|
||||
scenarios.
|
||||
|
||||
The hypervisor binary is generated based on Kconfig configuration
|
||||
settings. Instruction about these settings can be found in
|
||||
settings. Instructions about these settings can be found in
|
||||
:ref:`getting-started-hypervisor-configuration`.
|
||||
|
||||
.. note::
|
||||
A generic configuration named ``hypervisor/arch/x86/configs/generic.config``
|
||||
is provided to help developers try out ACRN more easily. This configuration
|
||||
will likely work for most x86-based platforms, supported with limited features.
|
||||
This configuration can be enabled by specifying ``BOARD=generic`` in
|
||||
the make command line.
|
||||
is provided to help developers try out ACRN more easily.
|
||||
This configuration works for most x86-based platforms; it is supported
|
||||
with limited features. It can be enabled by specifying ``BOARD=generic``
|
||||
in the ``make`` command line.
|
||||
|
||||
One binary for all platforms and all usage scenarios is currently not
|
||||
supported, primarily because dynamic configuration parsing is restricted in
|
||||
the ACRN hypervisor for the following reasons:
|
||||
|
||||
A primary reason one binary for all platforms and all usage scenarios is
|
||||
not supported is because dynamic configuration parsing is restricted in
|
||||
ACRN hypervisor, for the following considerations:
|
||||
- **Meeting functional safety requirements.** Implementing dynamic parsing
|
||||
introduces dynamic objects, which violates functional safety requirements.
|
||||
|
||||
* **Meeting functional safety requirements** Absence of dynamic objects is
|
||||
required in functional safety standards. Implementation of dynamic parsing
|
||||
would introduce dynamic objects. Avoiding use of dynamic
|
||||
parsing would help the ACRN hypervisor meet functional safety requirements.
|
||||
|
||||
* **Reduce complexity** ACRN is a lightweight reference hypervisor, built for
|
||||
- **Reduce complexity.** ACRN is a lightweight reference hypervisor, built for
|
||||
embedded IoT. As new platforms for embedded systems are rapidly introduced,
|
||||
support for one binary would require more and more complexity in the
|
||||
hypervisor, something we need to avoid.
|
||||
support for one binary could require more and more complexity in the
|
||||
hypervisor, which is something we strive to avoid.
|
||||
|
||||
* **Keep small footprint** Implementation of dynamic parsing would introduce
|
||||
hundreds or thousands of code. Avoiding dynamic parsing would help keep
|
||||
Lines of Code (LOC) of the hypervisor in a desirable range (around 30K).
|
||||
- **Keep small footprint.** Implementing dynamic parsing introduces
|
||||
hundreds or thousands of lines of code. Avoiding dynamic parsing
|
||||
helps keep the hypervisor's Lines of Code (LOC) in a desirable range (around 30K).
|
||||
|
||||
* **Improve boot up time** Dynamic parsing at runtime would increase the boot
|
||||
up time. Using build-time configuration and not dynamic parsing would help
|
||||
improve boot up time of the hypervisor.
|
||||
- **Improve boot up time.** Dynamic parsing at runtime increases the boot
|
||||
up time. Using a build-time configuration and not dynamic parsing
|
||||
helps improve the boot up time of the hypervisor.
|
||||
|
||||
|
||||
You can build the ACRN hypervisor, device model, and tools from
|
||||
source, by following these steps.
|
||||
Build the ACRN hypervisor, device model, and tools from source by following
|
||||
these steps.
|
||||
|
||||
.. _install-build-tools-dependencies:
|
||||
|
||||
Install build tools and dependencies
|
||||
************************************
|
||||
Step 1: Install build tools and dependencies
|
||||
********************************************
|
||||
|
||||
ACRN development is supported on popular Linux distributions,
|
||||
each with their own way to install development tools:
|
||||
ACRN development is supported on popular Linux distributions, each with
|
||||
their own way to install development tools:
|
||||
|
||||
.. note::
|
||||
ACRN uses ``menuconfig``, a python3 text-based user interface (TUI) for
|
||||
configuring hypervisor options and using python's ``kconfiglib`` library.
|
||||
|
||||
* On a Clear Linux OS development system, install the necessary tools:
|
||||
Install the necessary tools for the following systems:
|
||||
|
||||
* Clear Linux OS development system:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo swupd bundle-add os-clr-on-clr os-core-dev python3-basic
|
||||
$ pip3 install --user kconfiglib
|
||||
|
||||
* On a Ubuntu/Debian development system:
|
||||
* Ubuntu/Debian development system:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -92,9 +91,8 @@ each with their own way to install development tools:
|
||||
$ sudo pip3 install kconfiglib
|
||||
|
||||
.. note::
|
||||
You need to use ``gcc`` version 7.3.* or higher else you will run into issue
|
||||
`#1396 <https://github.com/projectacrn/acrn-hypervisor/issues/1396>`_. Follow
|
||||
these instructions to install the ``gcc-7`` package on Ubuntu 16.04:
|
||||
Use ``gcc`` version 7.3.* or higher to avoid running into
|
||||
issue `#1396 <https://github.com/projectacrn/acrn-hypervisor/issues/1396>`_. Follow these instructions to install the ``gcc-7`` package on Ubuntu 16.04:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -104,11 +102,11 @@ each with their own way to install development tools:
|
||||
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 \
|
||||
--slave /usr/bin/g++ g++ /usr/bin/g++-7
|
||||
|
||||
.. note::
|
||||
ACRN development requires ``binutils`` version 2.27 (or higher). You can
|
||||
verify your version of ``binutils`` with the command ``apt show binutils``.
|
||||
While Ubuntu 18.04 has a new version of ``binutils`` the default version on
|
||||
Ubuntu 16.04 needs updating (see issue `#1133
|
||||
|
||||
ACRN development requires ``binutils`` version 2.27 (or higher).
|
||||
Verify your version of ``binutils`` with the command ``apt show binutils
|
||||
``. While Ubuntu 18.04 has a new version of ``binutils``, the default
|
||||
version on Ubuntu 16.04 must be updated (see issue `#1133
|
||||
<https://github.com/projectacrn/acrn-hypervisor/issues/1133>`_).
|
||||
|
||||
.. code-block:: none
|
||||
@@ -119,11 +117,10 @@ each with their own way to install development tools:
|
||||
$ make
|
||||
$ sudo make install
|
||||
|
||||
.. note::
|
||||
Ubuntu 14.04 requires ``libsystemd-journal-dev`` instead of ``libsystemd-dev``
|
||||
as indicated above.
|
||||
|
||||
* On a Fedora/Redhat development system:
|
||||
Ubuntu 14.04 requires ``libsystemd-journal-dev`` instead of ``libsystemd-dev`` as indicated above.
|
||||
|
||||
* Fedora/Redhat development system:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -146,7 +143,7 @@ each with their own way to install development tools:
|
||||
$ sudo pip3 install kconfiglib
|
||||
|
||||
|
||||
* On a CentOS development system:
|
||||
* CentOS development system:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -168,47 +165,43 @@ each with their own way to install development tools:
|
||||
$ sudo pip3 install kconfiglib
|
||||
|
||||
.. note::
|
||||
You may need to install `EPEL <https://fedoraproject.org/wiki/EPEL>`_ for
|
||||
installing python3 via yum for CentOS 7. For CentOS 6 you need to install
|
||||
pip manually. Please refer to https://pip.pypa.io/en/stable/installing for
|
||||
details.
|
||||
You may need to install `EPEL <https://fedoraproject.org/wiki/EPEL>`_
|
||||
for installing python3 via yum for CentOS 7. For CentOS 6, you need to
|
||||
install pip manually. Refer to https://pip.pypa.io/en/stable/installing
|
||||
for details.
|
||||
|
||||
|
||||
Get the ACRN hypervisor source code
|
||||
***********************************
|
||||
Step 2: Get the ACRN hypervisor source code
|
||||
*******************************************
|
||||
|
||||
The `acrn-hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
|
||||
repository has four main components in it:
|
||||
repository contains four main components:
|
||||
|
||||
1. The ACRN hypervisor code located in the ``hypervisor`` directory
|
||||
#. The EFI stub code located in the ``misc/efi-stub`` directory
|
||||
#. The ACRN devicemodel code located in the ``devicemodel`` directory
|
||||
#. The ACRN tools source code located in the ``misc/tools`` directory
|
||||
1. The ACRN hypervisor code, located in the ``hypervisor`` directory.
|
||||
#. The EFI stub code, located in the ``misc/efi-stub`` directory.
|
||||
#. The ACRN device model code, located in the ``devicemodel`` directory.
|
||||
#. The ACRN tools source code, located in the ``misc/tools`` directory.
|
||||
|
||||
Follow this step to get the acrn-hypervisor source code:
|
||||
Enter the following to get the acrn-hypervisor source code:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ git clone https://github.com/projectacrn/acrn-hypervisor
|
||||
|
||||
|
||||
Choose the ACRN scenario
|
||||
************************
|
||||
Step 3: Build with the ACRN scenario
|
||||
************************************
|
||||
|
||||
.. note:: Documentation about the new ACRN use-case scenarios is a
|
||||
work-in-progress on the master branch as we work towards the v1.2
|
||||
release.
|
||||
|
||||
Currently ACRN hypervisor defines these typical usage scenarios:
|
||||
Currently, the ACRN hypervisor defines these typical usage scenarios:
|
||||
|
||||
SDC:
|
||||
The SDC (Software Defined Cockpit) scenario defines a simple
|
||||
automotive use-case where there is one pre-launched Service VM and one
|
||||
automotive use-case that includes one pre-launched Service VM and one
|
||||
post-launched User VM.
|
||||
|
||||
SDC2:
|
||||
SDC2 (Software Defined Cockpit 2) is an extended scenario for an
|
||||
automotive SDC system. SDC2 defined one pre-launched Service VM and up
|
||||
automotive SDC system. SDC2 defines one pre-launched Service VM and up
|
||||
to three post-launched VMs.
|
||||
|
||||
LOGICAL_PARTITION:
|
||||
@@ -221,60 +214,61 @@ INDUSTRY:
|
||||
control.
|
||||
|
||||
HYBRID:
|
||||
This scenario defines a hybrid use-case with three VMs: one
|
||||
This scenario defines a hybrid use case with three VMs: one
|
||||
pre-launched VM, one pre-launched Service VM, and one post-launched
|
||||
Standard VM.
|
||||
|
||||
You can select a build scenario by changing the default Kconfig name in
|
||||
the choice block of **ACRN Scenario** in ``arch/x86/Kconfig``. The
|
||||
corresponding VM configuration files in the corresponding
|
||||
``scenarios/$SCENARIO_NAME/`` folder.
|
||||
Assuming that you are at the top level of the acrn-hypervisor directory:
|
||||
|
||||
.. code-block:: none
|
||||
:emphasize-lines: 7
|
||||
* Build ``INDUSTRY`` scenario on ``nuc7i7dnb``:
|
||||
|
||||
$ cd acrn-hypervisor/hypervisor
|
||||
$ sudo vim arch/x86/Kconfig
|
||||
# <Fill the scenario name into below and save>
|
||||
.. code-block:: none
|
||||
|
||||
choice
|
||||
prompt "ACRN Scenario"
|
||||
default SDC
|
||||
$ make all BOARD=nuc7i7dnb SCENARIO=industry
|
||||
|
||||
See the :ref:`hardware` document for information about the platform
|
||||
needs for each scenario.
|
||||
* Build ``SDC`` scenario on ``nuc6cayh``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make all BOARD=nuc6cayh SCENARIO=sdc
|
||||
|
||||
See the :ref:`hardware` document for information about the platform needs
|
||||
for each scenario.
|
||||
|
||||
.. _getting-started-hypervisor-configuration:
|
||||
|
||||
Modify the hypervisor configuration
|
||||
***********************************
|
||||
Step 4: Build the hypervisor configuration
|
||||
******************************************
|
||||
|
||||
The ACRN hypervisor leverages Kconfig to manage configurations, powered by
|
||||
Kconfiglib. A default configuration is generated based on the board you have
|
||||
selected via the ``BOARD=`` command line parameter. You can make further
|
||||
changes to that default configuration to adjust to your specific
|
||||
Modify the hypervisor configuration
|
||||
===================================
|
||||
|
||||
The ACRN hypervisor leverages Kconfig to manage configurations; it is
|
||||
powered by ``Kconfiglib``. A default configuration is generated based on the
|
||||
board you have selected via the ``BOARD=`` command line parameter. You can
|
||||
make further changes to that default configuration to adjust to your specific
|
||||
requirements.
|
||||
|
||||
To generate hypervisor configurations, you need to build the hypervisor
|
||||
individually. The following steps generate a default but complete configuration,
|
||||
based on the platform selected, assuming that you are under the top-level
|
||||
directory of acrn-hypervisor. The configuration file, named ``.config``, can be
|
||||
found under the target folder of your build.
|
||||
To generate hypervisor configurations, you must build the hypervisor
|
||||
individually. The following steps generate a default but complete
|
||||
configuration, based on the platform selected, assuming that you are at the
|
||||
top level of the acrn-hypervisor directory. The configuration file, named
|
||||
``.config``, can be found under the target folder of your build.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make defconfig BOARD=nuc6cayh
|
||||
|
||||
The BOARD specified is used to select a defconfig under
|
||||
``arch/x86/configs/``. The other command-line based options (e.g. ``RELEASE``)
|
||||
take no effects when generating a defconfig.
|
||||
The BOARD specified is used to select a ``defconfig`` under
|
||||
``arch/x86/configs/``. The other command line-based options (e.g. ``RELEASE``)
|
||||
take no effect when generating a defconfig.
|
||||
|
||||
To modify the hypervisor configurations, you can either edit ``.config``
|
||||
manually, or invoke a TUI-based menuconfig, powered by kconfiglib, by executing
|
||||
``make menuconfig``. As an example, the following commands, assuming that you
|
||||
are under the top-level directory of acrn-hypervisor, generate a default
|
||||
configuration file for UEFI, allow you to modify some configurations and build
|
||||
the hypervisor using the updated ``.config``.
|
||||
manually, or invoke a TUI-based menuconfig, powered by kconfiglib, by
|
||||
executing ``make menuconfig``. As an example, the following commands
|
||||
(assuming that you are at the top level of the acrn-hypervisor directory)
|
||||
generate a default configuration file for UEFI, allowing you to modify some
|
||||
configurations and build the hypervisor using the updated ``.config``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -282,29 +276,29 @@ the hypervisor using the updated ``.config``.
|
||||
$ cd ../ # Enter top-level folder of acrn-hypervisor source
|
||||
$ make menuconfig -C hypervisor BOARD=kbl-nuc-i7 <select industry scenario>
|
||||
|
||||
.. note::
|
||||
Menuconfig is python3 only.
|
||||
|
||||
Refer to the help on menuconfig for a detailed guide on the interface.
|
||||
Note that ``menuconfig`` is python3 only.
|
||||
|
||||
Refer to the help on menuconfig for a detailed guide on the interface:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ pydoc3 menuconfig
|
||||
|
||||
Build the hypervisor, device model and tools
|
||||
********************************************
|
||||
Step 5: Build the hypervisor, device model, and tools
|
||||
*****************************************************
|
||||
|
||||
Now you can build all these components in one go as follows:
|
||||
Now you can build all these components at once as follows:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make FIRMWARE=uefi # Build the UEFI hypervisor with the new .config
|
||||
|
||||
The build results are found in the ``build`` directory. You can specify
|
||||
use a different Output folder by setting the ``O`` make parameter,
|
||||
The build results are found in the ``build`` directory. You can specify
|
||||
a different Output folder by setting the ``O`` ``make`` parameter,
|
||||
for example: ``make O=build-nuc BOARD=nuc6cayh``.
|
||||
|
||||
If you only need the hypervisor, then use this command:
|
||||
If you only need the hypervisor, use this command:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -312,23 +306,19 @@ If you only need the hypervisor, then use this command:
|
||||
$ make -C hypervisor
|
||||
$ make -C misc/efi-stub HV_OBJDIR=$PWD/hypervisor/build EFI_OBJDIR=$PWD/hypervisor/build
|
||||
|
||||
The``acrn.efi`` will be generated in directory: ``./hypervisor/build/acrn.efi``
|
||||
(`Slim bootloader
|
||||
<https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html>`_)
|
||||
hypervisor.
|
||||
The ``acrn.efi`` will be generated in the ``./hypervisor/build/acrn.efi`` directory hypervisor.
|
||||
|
||||
As mentioned in :ref:`ACRN Configuration Tool <vm_config_workflow>`,
|
||||
Board configuration and VM configuration could be imported from XML files.
|
||||
If you want to build hypervisor with XML configuration files, please specify the
|
||||
file location as follows:
|
||||
As mentioned in :ref:`ACRN Configuration Tool <vm_config_workflow>`, the Board configuration and VM configuration can be imported from XML files.
|
||||
If you want to build the hypervisor with XML configuration files, specify
|
||||
the file location as follows:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ BOARD_FILE=/home/acrn-hypervisor/misc/acrn-config/xmls/board-xmls/apl-up2.xml
|
||||
$ BOARD_FILE=/home/acrn-hypervisor/misc/acrn-config/xmls/board-xmls/apl-up2.xml
|
||||
SCENARIO_FILE=/home/acrn-hypervisor/misc/acrn-config/xmls/config-xmls/apl-up2/sdc.xml FIRMWARE=uefi
|
||||
|
||||
.. note:: The file path must be absolute path. Both of the ``BOARD`` and ``SCENARIO``
|
||||
parameters are not needed because the information could be got from XML.
|
||||
|
||||
Note that the file path must be absolute. Both of the ``BOARD`` and ``SCENARIO`` parameters are not needed because the information is retrieved from the XML file. Adjust the example above to your own environment path.
|
||||
|
||||
Follow the same instructions to boot and test the images you created from your build.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user