OrgACRN
/
acrn-hypervisor
mirror of https://github.com/projectacrn/acrn-hypervisor.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Documentation: split the build instructions into its own guide 

Split the build instructions, and the hypervisor configuration instructions
into its own separate document.

Tracked-On: #2154
Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This commit is contained in:
Geoffroy Van Cutsem 2018-12-21 17:00:13 +01:00 committed by David Kinder
parent c358d29c89
commit 9c97f6bec5
5 changed files with 229 additions and 248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
doc/getting-started/apl-nuc.rst
View File

@ -353,249 +353,3 @@ Set up Reference UOS
:align: center
:name: gsg-successful-boot
Build ACRN from Source
**********************
If you would like to build ACRN hypervisor and device model from source,
follow these steps.
Install build tools and dependencies
====================================
ARCN 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 development system, install the necessary tools:
.. 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:
.. code-block:: none
$ sudo apt install gcc \
git \
make \
gnu-efi \
libssl-dev \
libpciaccess-dev \
uuid-dev \
libsystemd-dev \
libevent-dev \
libxml2-dev \
libusb-1.0-0-dev \
python3 \
python3-pip \
libblkid-dev \
e2fslibs-dev
$ 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:
.. code-block:: none
$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
$ sudo apt update
$ sudo apt install g++-7 -y
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 \
--slave /usr/bin/g++ g++ /usr/bin/g++-7
.. note::
Ubuntu 14.04 requires ``libsystemd-journal-dev`` instead of ``libsystemd-dev``
as indicated above.
* On a Fedora/Redhat development system:
.. code-block:: none
$ sudo dnf install gcc \
git \
make \
findutils \
gnu-efi-devel \
libuuid-devel \
openssl-devel \
libpciaccess-devel \
systemd-devel \
libxml2-devel \
libevent-devel \
libusbx-devel \
python3 \
python3-pip \
libblkid-devel \
e2fsprogs-devel
$ sudo pip3 install kconfiglib
* On a CentOS development system:
.. code-block:: none
$ sudo yum install gcc \
git \
make \
gnu-efi-devel \
libuuid-devel \
openssl-devel \
libpciaccess-devel \
systemd-devel \
libxml2-devel \
libevent-devel \
libusbx-devel \
python34 \
python34-pip \
libblkid-devel \
e2fsprogs-devel
$ 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.
Build the hypervisor, device model and tools
============================================
The `acrn-hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
repository has three main components in it:
1. The ACRN hypervisor code located in the ``hypervisor`` directory
#. The ACRN devicemodel code located in the ``devicemodel`` directory
#. The ACRN tools source code located in the ``tools`` directory
You can build all these components in one go as follows:
.. code-block:: none
$ git clone https://github.com/projectacrn/acrn-hypervisor
$ cd acrn-hypervisor
$ make
The build results are found in the ``build`` directory.
.. note::
if you wish to use a different target folder for the build
artefacts, set the ``O`` (that is capital letter 'O') to the
desired value. Example: ``make O=build-nuc BOARD=nuc6cayh``.
Generating the documentation is described in details in the :ref:`acrn_doc`
tutorial.
You can also build these components individually. The following
steps assume that you have already cloned the ``acrn-hypervisor`` repository
and are using it as the current working directory.
#. Build the ACRN hypervisor.
.. code-block:: none
$ cd hypervisor
$ make BOARD=nuc6cayh
The build results are found in the ``build`` directory.
#. Build the ACRN device model (included in the acrn-hypervisor repo):
.. code-block:: none
$ cd ../devicemodel
$ make
The build results are found in the ``build`` directory.
#. Build the ACRN tools (included in the acrn-hypervisor repo):
.. code-block:: none
$ cd ../tools
$ for d in */; do make -C "$d"; done
Follow the same instructions to boot and test the images you created
from your build.
Generate the hypervisor configurations
======================================
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
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.
.. code-block:: none
$ cd hypervisor
$ 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.
Modify the hypervisor configurations
====================================
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``.
.. code-block:: none
$ cd hypervisor
$ make defconfig BOARD=nuc6cayh
$ make menuconfig # Modify the configurations per your needs
$ make # Build the hypervisor with the new .config
.. note::
Menuconfig is python3 only.
Refer to the help on menuconfig for a detailed guide on the interface.
.. code-block:: none
$ pydoc3 menuconfig
Create a new default configuration
==================================
Currently the ACRN hypervisor looks for default configurations under
``hypervisor/arch/x86/configs/<BOARD>.config``, where ``<BOARD>`` is the
specified platform. The following steps allow you to create a defconfig for
another platform based on a current one.
.. code-block:: none
$ cd hypervisor
$ make defconfig BOARD=nuc6cayh
$ make menuconfig # Modify the configurations
$ make savedefconfig # The minimized config reside at build/defconfig
$ cp build/defconfig arch/x86/configs/xxx.config
Then you can re-use that configuration by passing the name (``xxx`` in the
example above) to 'BOARD=':
.. code-block:: none
$ make defconfig BOARD=xxx

221
doc/getting-started/building-from-source.rst Normal file
View File

@ -0,0 +1,221 @@
.. _getting-started-building:
Build ACRN from Source
######################
If you would like to build the ACRN hypervisor, device model, and tools from
source, follow these steps.
Install build tools and dependencies
************************************
ARCN 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 development system, install the necessary tools:
.. 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:
.. code-block:: none
$ sudo apt install gcc \
git \
make \
gnu-efi \
libssl-dev \
libpciaccess-dev \
uuid-dev \
libsystemd-dev \
libevent-dev \
libxml2-dev \
libusb-1.0-0-dev \
python3 \
python3-pip \
libblkid-dev \
e2fslibs-dev
$ 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:
.. code-block:: none
$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
$ sudo apt update
$ sudo apt install g++-7 -y
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 60 \
--slave /usr/bin/g++ g++ /usr/bin/g++-7
.. note::
Ubuntu 14.04 requires ``libsystemd-journal-dev`` instead of ``libsystemd-dev``
as indicated above.
* On a Fedora/Redhat development system:
.. code-block:: none
$ sudo dnf install gcc \
git \
make \
findutils \
gnu-efi-devel \
libuuid-devel \
openssl-devel \
libpciaccess-devel \
systemd-devel \
libxml2-devel \
libevent-devel \
libusbx-devel \
python3 \
python3-pip \
libblkid-devel \
e2fsprogs-devel
$ sudo pip3 install kconfiglib
* On a CentOS development system:
.. code-block:: none
$ sudo yum install gcc \
git \
make \
gnu-efi-devel \
libuuid-devel \
openssl-devel \
libpciaccess-devel \
systemd-devel \
libxml2-devel \
libevent-devel \
libusbx-devel \
python34 \
python34-pip \
libblkid-devel \
e2fsprogs-devel
$ 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.
Build the hypervisor, device model and tools
********************************************
The `acrn-hypervisor <https://github.com/projectacrn/acrn-hypervisor/>`_
repository has four main components in it:
1. The ACRN hypervisor code located in the ``hypervisor`` directory
#. The EFI stub code located in the ``efi-stub`` directory
#. The ACRN devicemodel code located in the ``devicemodel`` directory
#. The ACRN tools source code located in the ``tools`` directory
You can build all these components in one go as follows:
.. code-block:: none
$ git clone https://github.com/projectacrn/acrn-hypervisor
$ cd acrn-hypervisor
$ make
The build results are found in the ``build`` directory.
.. note::
if you wish to use a different target folder for the build
artefacts, set the ``O`` (that is capital letter 'O') to the
desired value. Example: ``make O=build-nuc BOARD=nuc6cayh``.
Generating the documentation is described in details in the :ref:`acrn_doc`
tutorial.
Follow the same instructions to boot and test the images you created
from your build.
.. _getting-started-hypervisor-configuration:
Configuring the hypervisor
**************************
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
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.
.. code-block:: none
$ cd hypervisor
$ 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.
Modify the hypervisor configurations
************************************
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``.
.. code-block:: none
$ cd hypervisor
$ make defconfig BOARD=nuc6cayh
$ make menuconfig # Modify the configurations per your needs
$ make # Build the hypervisor with the new .config
.. note::
Menuconfig is python3 only.
Refer to the help on menuconfig for a detailed guide on the interface.
.. code-block:: none
$ pydoc3 menuconfig
Create a new default configuration
**********************************
Currently the ACRN hypervisor looks for default configurations under
``hypervisor/arch/x86/configs/<BOARD>.config``, where ``<BOARD>`` is the
specified platform. The following steps allow you to create a defconfig for
another platform based on a current one.
.. code-block:: none
$ cd hypervisor
$ make defconfig BOARD=nuc6cayh
$ make menuconfig # Modify the configurations
$ make savedefconfig # The minimized config reside at build/defconfig
$ cp build/defconfig arch/x86/configs/xxx.config
Then you can re-use that configuration by passing the name (``xxx`` in the
example above) to 'BOARD=':
.. code-block:: none
$ make defconfig BOARD=xxx

1
doc/getting-started/index.rst
View File

@ -19,3 +19,4 @@ described in :ref:`hardware`. Follow the setup guides listed here:
apl-nuc.rst
up2.rst
building-from-source.rst

5
doc/tutorials/using_partition_mode_on_up2.rst
View File

@ -159,6 +159,11 @@ Enable partition mode in ACRN hypervisor
.. figure:: images/menuconfig-partition-mode.png
:align: center
.. note::
Refer to the :ref:`getting-started-building` for more information on how
to install all the ACRN build dependencies.
#. Configure the PCI device info for each VM
PCI devices that are available to the privileged VMs

4
doc/tutorials/using_ubuntu_as_sos.rst
View File

@ -43,7 +43,7 @@ the source code, build it, and install it on your device.
1. Install the build tools and dependencies
Follow the instructions found in the :ref:`getting-started-apl-nuc` to
Follow the instructions found in the :ref:`getting-started-building` to
install all the build tools and dependencies on your system.
#. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_
@ -70,7 +70,7 @@ the source code, build it, and install it on your device.
make PLATFORM=uefi
sudo make install
For more details, please refer to the :ref:`getting-started-apl-nuc`.
For more details, please refer to the :ref:`getting-started-building`.
#. Install the hypervisor