diff --git a/doc/getting-started/building-from-source.rst b/doc/getting-started/building-from-source.rst index 2dc0bd4c1..b9a242b87 100644 --- a/doc/getting-started/building-from-source.rst +++ b/doc/getting-started/building-from-source.rst @@ -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 +``/hypervisor/.scenario.xml``, where ```` 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`. diff --git a/doc/tutorials/acrn_configuration_tool.rst b/doc/tutorials/acrn_configuration_tool.rst index 6bbeb97a4..8f1f1c3e4 100644 --- a/doc/tutorials/acrn_configuration_tool.rst +++ b/doc/tutorials/acrn_configuration_tool.rst @@ -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. diff --git a/doc/tutorials/enable_ivshmem.rst b/doc/tutorials/enable_ivshmem.rst index e9ad6de6b..d29c8e800 100644 --- a/doc/tutorials/enable_ivshmem.rst +++ b/doc/tutorials/enable_ivshmem.rst @@ -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 diff --git a/doc/tutorials/images/GUI_of_menuconfig.png b/doc/tutorials/images/GUI_of_menuconfig.png deleted file mode 100644 index 330f963ec..000000000 Binary files a/doc/tutorials/images/GUI_of_menuconfig.png and /dev/null differ diff --git a/doc/tutorials/images/sample_of_defconfig.png b/doc/tutorials/images/sample_of_defconfig.png deleted file mode 100644 index 050131902..000000000 Binary files a/doc/tutorials/images/sample_of_defconfig.png and /dev/null differ diff --git a/doc/tutorials/vuart_configuration.rst b/doc/tutorials/vuart_configuration.rst index 664f2b9ac..8484eb58f 100644 --- a/doc/tutorials/vuart_configuration.rst +++ b/doc/tutorials/vuart_configuration.rst @@ -267,7 +267,7 @@ and :ref:`How to Configure a Communication Port `. You can configure both Legacy vUART and PCI-vUART in -``./misc/vm_configs/xmls/config-xmls//.xml``. For +``./misc/config_tools/data//.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/.xml \ - SCENARIO_FILE=$PWD/misc/acrn-config/xmls/config-xmls//.xml + make BOARD= SCENARIO= The configuration tools will test your settings, and check :ref:`vUART Rules ` for compilation issue. After compiling, you can find -``./misc/vm_configs/scenarios///pci_dev.c`` has been -changed by the configuration tools based on the XML settings, something like: +the generated sources under ``build/configs/scenarios//pci_dev.c`` +which is based on the XML settings, something like: .. code-block:: none