mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-19 20:22:46 +00:00
doc: update build-from-source instructions
Users no longer need to explicitly generate configuration source code as they are now generated at build time. This patch updates the relevant instructions in the documentation. v3: * RELEASE now defaults to n. * Cleanup the unnecessary target `all` in the `make` commands * Remove menuconfig related stuff. * Refine the introductory paragraph as only steps on Ubuntu is introduced * Also introduce the targets introduced by PR #5791 v2: * Add python3 lxml as a dependency * Explain how to use out-of-tree XML files Tracked-On: #5644 Signed-off-by: Junjie Mao <junjie.mao@intel.com> Co-authored-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This commit is contained in:
Junjie Mao
fitchbe
parent
5df65eeb19
commit
9b4bf5e2a8
@ -8,8 +8,8 @@ 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. Instructions about these settings can be found in
|
||||
The hypervisor binary is generated based on configuration settings in XML
|
||||
files. Instructions about customizing these settings can be found in
|
||||
:ref:`getting-started-hypervisor-configuration`.
|
||||
|
||||
One binary for all platforms and all usage scenarios is currently not
|
||||
@ -48,19 +48,12 @@ these steps.
|
||||
Install Build Tools and Dependencies
|
||||
************************************
|
||||
|
||||
ACRN development is supported on popular Linux distributions, each with
|
||||
their own way to install development tools. This user guide covers the
|
||||
different steps to configure and build ACRN natively on your
|
||||
distribution.
|
||||
ACRN development is supported on popular Linux distributions, each with their
|
||||
own way to install development tools. This user guide covers the steps to
|
||||
configure and build ACRN natively on **Ubuntu 18.04 or newer**.
|
||||
|
||||
.. note::
|
||||
ACRN uses ``menuconfig``, a python3 text-based user interface (TUI)
|
||||
for configuring hypervisor options and using Python's ``kconfiglib``
|
||||
library.
|
||||
|
||||
Install the necessary tools for the following systems:
|
||||
|
||||
* Ubuntu development system:
|
||||
The following commands install the necessary tools for configuring and building
|
||||
ACRN.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@ -82,21 +75,16 @@ Install the necessary tools for the following systems:
|
||||
libnuma-dev \
|
||||
liblz4-tool \
|
||||
flex \
|
||||
bison
|
||||
bison \
|
||||
xsltproc
|
||||
|
||||
$ sudo pip3 install kconfiglib
|
||||
$ sudo pip3 install lxml xmlschema
|
||||
$ wget https://acpica.org/sites/acpica/files/acpica-unix-20191018.tar.gz
|
||||
$ tar zxvf acpica-unix-20191018.tar.gz
|
||||
$ cd acpica-unix-20191018
|
||||
$ make clean && make iasl
|
||||
$ sudo cp ./generate/unix/bin/iasl /usr/sbin/
|
||||
|
||||
.. note::
|
||||
ACRN requires ``gcc`` version 7.3.* (or higher) and ``binutils`` version
|
||||
2.27 (or higher). Check your development environment to ensure you have
|
||||
appropriate versions of these packages by using the commands: ``gcc -v``
|
||||
and ``ld -v``.
|
||||
|
||||
.. rst-class:: numbered-step
|
||||
|
||||
Get the ACRN Hypervisor Source Code
|
||||
@ -107,7 +95,8 @@ repository contains four main components:
|
||||
|
||||
1. The ACRN hypervisor code, located in the ``hypervisor`` directory.
|
||||
#. The ACRN device model code, located in the ``devicemodel`` directory.
|
||||
#. The ACRN tools source code, located in the ``misc/tools`` directory.
|
||||
#. The ACRN debug tools source code, located in the ``misc/debug_tools`` directory.
|
||||
#. The ACRN online services source code, located in the ``misc/services`` directory.
|
||||
|
||||
Enter the following to get the acrn-hypervisor source code:
|
||||
|
||||
@ -149,126 +138,125 @@ HYBRID_RT:
|
||||
pre-launched RTVM, one pre-launched Service VM, and one post-launched
|
||||
Standard VM.
|
||||
|
||||
Assuming that you are at the top level of the acrn-hypervisor directory, perform the following:
|
||||
XML configuration files for those scenarios on supported boards are available
|
||||
under the ``misc/config_tools/data`` directory.
|
||||
|
||||
Assuming that you are at the top level of the ``acrn-hypervisor`` directory, perform
|
||||
the following to build the hypervisor, device model and tools:
|
||||
|
||||
.. note::
|
||||
The release version is built by default, ``RELEASE=0`` builds the debug version.
|
||||
The debug version is built by default. To build a release version, a user
|
||||
must builds with ``RELEASE=y`` explicitly, regardless of whether a previous
|
||||
build exists.
|
||||
|
||||
* Build the ``INDUSTRY`` scenario on the ``nuc7i7dnb``:
|
||||
* Build the debug version of ``INDUSTRY`` scenario on the ``nuc7i7dnb``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make all BOARD=nuc7i7dnb SCENARIO=industry RELEASE=0
|
||||
$ make BOARD=nuc7i7dnb SCENARIO=industry
|
||||
|
||||
* Build the ``HYBRID`` scenario on the ``whl-ipc-i5``:
|
||||
* Build the release version of ``HYBRID`` scenario on the ``whl-ipc-i5``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make all BOARD=whl-ipc-i5 SCENARIO=hybrid RELEASE=0
|
||||
$ make BOARD=whl-ipc-i5 SCENARIO=hybrid RELEASE=y
|
||||
|
||||
* Build the ``HYBRID_RT`` scenario on the ``whl-ipc-i7``:
|
||||
* Build the release version of ``HYBRID_RT`` scenario on the ``whl-ipc-i7``
|
||||
(hypervisor only):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make all BOARD=whl-ipc-i7 SCENARIO=hybrid_rt RELEASE=0
|
||||
$ make BOARD=whl-ipc-i7 SCENARIO=hybrid_rt RELEASE=y hypervisor
|
||||
|
||||
* Build the ``SDC`` scenario on the ``nuc6cayh``:
|
||||
* Build the release version of the device model and tools:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make all BOARD_FILE=$PWD/misc/vm_configs/xmls/board-xmls/nuc6cayh.xml \
|
||||
SCENARIO_FILE=$PWD/misc/vm_configs/xmls/config-xmls/nuc6cayh/sdc.xml
|
||||
$ make RELEASE=y devicemodel tools
|
||||
|
||||
You can also build ACRN with your customized scenario:
|
||||
|
||||
See the :ref:`hardware` document for information about platform needs
|
||||
for each scenario.
|
||||
* Build with your own scenario configuration on the ``nuc6cayh``, assuming the
|
||||
scenario is defined in ``/path/to/scenario.xml``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make BOARD=nuc6cayh SCENARIO=/path/to/scenario.xml
|
||||
|
||||
* Build with your own board and scenario configuration, assuming the board and
|
||||
scenario XML files are ``/path/to/board.xml`` and ``/path/to/scenario.xml``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make BOARD=/path/to/board.xml SCENARIO=/path/to/scenario.xml
|
||||
|
||||
.. note::
|
||||
ACRN uses XML files to summarize board characteristics and scenario
|
||||
settings. The ``BOARD`` and ``SCENARIO`` variables accept board/scenario
|
||||
names as well as paths to XML files. When board/scenario names are given, the
|
||||
build system searches for XML files with the same names under
|
||||
``misc/config_tools/data/``. When paths (absolute or relative) to the XML
|
||||
files are given, the build system uses the files pointed at. If relative
|
||||
paths are used, they are considered relative to the current working
|
||||
directory.
|
||||
|
||||
See the :ref:`hardware` document for information about platform needs for each
|
||||
scenario. For more instructions to customize scenarios, see
|
||||
:ref:`getting-started-hypervisor-configuration` and
|
||||
:ref:`acrn_configuration_tool`.
|
||||
|
||||
The build results are found in the ``build`` directory. You can specify
|
||||
a different build directory by setting the ``O`` ``make`` parameter,
|
||||
for example: ``make O=build-nuc``.
|
||||
|
||||
To query the board, scenario and build type of an existing build, the
|
||||
``hvshowconfig`` target will help.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make BOARD=tgl-rvp SCENARIO=hybrid_rt hypervisor
|
||||
...
|
||||
$ make hvshowconfig
|
||||
Build directory: /path/to/acrn-hypervisor/build/hypervisor
|
||||
This build directory is configured with the settings below.
|
||||
- BOARD = tgl-rvp
|
||||
- SCENARIO = hybrid_rt
|
||||
- RELEASE = n
|
||||
|
||||
.. _getting-started-hypervisor-configuration:
|
||||
|
||||
.. rst-class:: numbered-step
|
||||
|
||||
Build the Hypervisor Configuration
|
||||
**********************************
|
||||
|
||||
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.
|
||||
The ACRN hypervisor is built with scenario encoded in an XML file (referred to
|
||||
as the scenario XML hereinafter). The scenario XML of a build can be found at
|
||||
``<build>/hypervisor/.scenario.xml``, where ``<build>`` is the name of the build
|
||||
directory. You can make further changes to this file to adjust to your specific
|
||||
requirements. Another ``make`` will rebuild the hypervisor using the updated
|
||||
scenario XML.
|
||||
|
||||
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.
|
||||
The following commands show how to customize manually the scenario XML based on
|
||||
the predefined ``INDUSTRY`` scenario for ``nuc7i7dnb`` and rebuild the
|
||||
hypervisor.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd hypervisor
|
||||
$ make defconfig BOARD=nuc7i7dnb SCENARIO=industry
|
||||
|
||||
The BOARD specified is used to select a ``defconfig`` under
|
||||
``misc/vm_configs/scenarios/``. 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 you can 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, allowing you to modify some
|
||||
configurations and build the hypervisor using the updated ``.config``:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# Modify the configurations per your needs
|
||||
$ cd ../ # Enter top-level folder of acrn-hypervisor source
|
||||
$ make menuconfig -C hypervisor
|
||||
# modify your own "ACRN Scenario" and "Target board" that want to build
|
||||
# in pop up menu
|
||||
|
||||
Note that ``menuconfig`` is python3 only.
|
||||
|
||||
Refer to the help on menuconfig for a detailed guide on the interface:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ pydoc3 menuconfig
|
||||
|
||||
.. rst-class:: numbered-step
|
||||
|
||||
Build the Hypervisor, Device Model, and Tools
|
||||
*********************************************
|
||||
|
||||
Now you can build all these components at once as follows:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make # Build hypervisor with the new .config
|
||||
|
||||
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``.
|
||||
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ make all BOARD_FILE=$PWD/misc/vm_configs/xmls/board-xmls/nuc7i7dnb.xml \
|
||||
SCENARIO_FILE=$PWD/misc/vm_configs/xmls/config-xmls/nuc7i7dnb/industry.xml TARGET_DIR=xxx
|
||||
|
||||
The build results are found in the ``build`` directory. You can specify
|
||||
a different build folder by setting the ``O`` ``make`` parameter,
|
||||
for example: ``make O=build-nuc``.
|
||||
|
||||
$ make BOARD=nuc7i7dnb SCENARIO=industry hvdefconfig
|
||||
$ vim build/hypervisor/.scenario.xml
|
||||
(Modify the XML file per your needs)
|
||||
$ make
|
||||
|
||||
.. note::
|
||||
The ``BOARD`` and ``SCENARIO`` parameters are not needed because the
|
||||
information is retrieved from the corresponding ``BOARD_FILE`` and
|
||||
``SCENARIO_FILE`` XML configuration files. The ``TARGET_DIR`` parameter
|
||||
specifies what directory is used to store configuration files imported
|
||||
from XML files. If the ``TARGET_DIR`` is not specified, the original
|
||||
configuration files of acrn-hypervisor would be overridden.
|
||||
A hypervisor build memorizes the board and scenario previously
|
||||
configured. Thus, there is no need to duplicate BOARD and SCENARIO in the
|
||||
second ``make`` above.
|
||||
|
||||
Follow the same instructions to boot and test the images you created from your build.
|
||||
While the scenario XML files can be changed manually, we recommend to use the
|
||||
ACRN web-based configuration app which provides valid options and descriptions
|
||||
of the configuration entries. Refer to :ref:`acrn_config_tool_ui` for more
|
||||
instructions.
|
||||
|
||||
Descriptions of each configuration entry in scenario XML files are also
|
||||
available at :ref:`scenario-config-options`.
|
||||
|
||||
@ -191,32 +191,6 @@ current scenario has:
|
||||
Configuration Tool Workflow
|
||||
***************************
|
||||
|
||||
Hypervisor Configuration Workflow
|
||||
==================================
|
||||
|
||||
The hypervisor configuration is based on the ``Kconfig``
|
||||
mechanism. Begin by creating a board-specific ``defconfig`` file to
|
||||
set up the default ``Kconfig`` values for the specified board.
|
||||
Next, configure the hypervisor build options using the ``make menuconfig``
|
||||
graphical interface or ``make defconfig`` to generate
|
||||
a ``.config`` file. The resulting ``.config`` file is
|
||||
used by the ACRN build process to create a configured scenario- and
|
||||
board-specific hypervisor image.
|
||||
|
||||
.. figure:: images/sample_of_defconfig.png
|
||||
:align: center
|
||||
|
||||
defconfig file sample
|
||||
|
||||
.. figure:: images/GUI_of_menuconfig.png
|
||||
:align: center
|
||||
|
||||
``menuconfig`` interface sample
|
||||
|
||||
Refer to :ref:`getting-started-hypervisor-configuration` for detailed
|
||||
configuration steps.
|
||||
|
||||
|
||||
.. _vm_config_workflow:
|
||||
|
||||
Board and VM Configuration Workflow
|
||||
@ -258,37 +232,8 @@ Here is the offline configuration tool workflow:
|
||||
.. note:: Refer to :ref:`acrn_config_tool_ui` for more details on
|
||||
the configuration tool UI.
|
||||
|
||||
#. Auto generate the code.
|
||||
|
||||
Python tools are used to generate configurations in patch format.
|
||||
The patches are applied to your local ``acrn-hypervisor`` git tree
|
||||
automatically.
|
||||
|
||||
a. Generate a patch for the board-related configuration::
|
||||
|
||||
cd misc/acrn-config/board_config
|
||||
python3 board_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml
|
||||
|
||||
Note that this can also be done by clicking **Generate Board SRC** in the acrn-config UI.
|
||||
|
||||
|
||||
#. Generate a patch for scenario-based VM configuration::
|
||||
|
||||
cd misc/acrn-config/scenario_config
|
||||
python3 scenario_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml
|
||||
|
||||
Note that this can also be done by clicking **Generate Scenario SRC** in the acrn-config UI.
|
||||
|
||||
#. Generate the launch script for the specified
|
||||
post-launched User VM::
|
||||
|
||||
cd misc/acrn-config/launch_config
|
||||
python3 launch_cfg_gen.py --board $(BOARD).xml --scenario $(SCENARIO).xml --launch $(LAUNCH).xml --uosid xx
|
||||
|
||||
Note that this can also be done by clicking **Generate Launch Script** in the acrn-config UI.
|
||||
|
||||
#. Re-build the ACRN hypervisor. Refer to
|
||||
:ref:`getting-started-building` to re-build the ACRN hypervisor on the host machine.
|
||||
#. Build with your XML files. Refer to :ref:`getting-started-building` to build
|
||||
the ACRN hypervisor with your XML files on the host machine.
|
||||
|
||||
#. Deploy VMs and run ACRN hypervisor on the target board.
|
||||
|
||||
|
||||
@ -178,7 +178,7 @@ Linux-based VMs (VM0 is a pre-launched VM and VM2 is a post-launched VM).
|
||||
and shared memory size is 2M bytes:
|
||||
|
||||
- Edit XML configuration file for hybrid_rt scenario on whl-ipc-i5 board
|
||||
``acrn-hypervisor/misc/vm_configs/xmls/config-xmls/whl-ipc-i5/hybrid_rt.xml``
|
||||
``acrn-hypervisor/misc/config_tools/data/whl-ipc-i5/hybrid_rt.xml``
|
||||
to enable ``ivshmem`` and configure the shared memory region using the format
|
||||
``shm_name, shm_size, VM IDs`` (as described above in the ACRN dm boot parameters).
|
||||
The region name must start with ``hv:/`` for an hv-land shared region, and we'll allocate 2MB
|
||||
@ -194,8 +194,7 @@ Linux-based VMs (VM0 is a pre-launched VM and VM2 is a post-launched VM).
|
||||
|
||||
2. Build ACRN based on the XML configuration for hybrid_rt scenario on whl-ipc-i5 board::
|
||||
|
||||
make BOARD_FILE=acrn-hypervisor/misc/vm_configs/xmls/board-xmls/whl-ipc-i5.xml \
|
||||
SCENARIO_FILE=acrn-hypervisor/misc/vm_configs/xmls/config-xmls/whl-ipc-i5/hybrid_rt.xml TARGET_DIR=xxx
|
||||
make BOARD=whl-ipc-i5 SCENARIO=hybrid_rt TARGET_DIR=xxx
|
||||
|
||||
3. Add a new virtual PCI device for VM2 (post-launched VM): the device type is
|
||||
``ivshmem``, shared memory name is ``hv:/shm_region_0``, and shared memory
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 267 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 95 KiB |
@ -267,7 +267,7 @@ and :ref:`How to Configure a Communication Port
|
||||
<how-to-configure-a-communication-port>`.
|
||||
|
||||
You can configure both Legacy vUART and PCI-vUART in
|
||||
``./misc/vm_configs/xmls/config-xmls/<board>/<scenario>.xml``. For
|
||||
``./misc/config_tools/data/<board>/<scenario>.xml``. For
|
||||
example, if VM0 has a legacy vUART0 and a PCI-vUART1, VM1 has no legacy
|
||||
vUART but has a PCI-vUART0 and a PCI-vUART1, VM0's PCI-vUART1 and VM1's
|
||||
PCI-vUART1 are connected to each other. You should configure then like this:
|
||||
@ -334,13 +334,12 @@ The ACRN vUART related XML fields:
|
||||
|
||||
Run the command to build ACRN with this XML configuration file::
|
||||
|
||||
make BOARD_FILE=$PWD/misc/acrn-config/xmls/board-xmls/<board>.xml \
|
||||
SCENARIO_FILE=$PWD/misc/acrn-config/xmls/config-xmls/<board>/<scenario>.xml
|
||||
make BOARD=<board> SCENARIO=<scenario>
|
||||
|
||||
The configuration tools will test your settings, and check :ref:`vUART
|
||||
Rules <index-of-vuart>` for compilation issue. After compiling, you can find
|
||||
``./misc/vm_configs/scenarios/<scenario>/<board>/pci_dev.c`` has been
|
||||
changed by the configuration tools based on the XML settings, something like:
|
||||
the generated sources under ``build/configs/scenarios/<scenario>/pci_dev.c``
|
||||
which is based on the XML settings, something like:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user