diff --git a/doc/getting-started/building-from-source.rst b/doc/getting-started/building-from-source.rst index 1049d4672..b3f1f14f8 100644 --- a/doc/getting-started/building-from-source.rst +++ b/doc/getting-started/building-from-source.rst @@ -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 `_. 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 `_. 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 `_). .. 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 `_ 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 `_ + 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 `_ -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 - # + .. 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