mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-08-08 03:35:14 +00:00
doc: update draft 3.0 published docs to include changes on master
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
David Kinder
parent
4a7d6e4119
commit
4bfbab8d89
@ -58,25 +58,6 @@ Before you begin, make sure your machines have the following prerequisites:
|
||||
copying via USB disk, but you can use another method if you prefer)
|
||||
- Local storage device (NVMe or SATA drive, for example)
|
||||
|
||||
.. _gsg-target-hardware:
|
||||
|
||||
.. rst-class:: numbered-step
|
||||
|
||||
Set Up the Target Hardware
|
||||
**************************
|
||||
|
||||
To set up the target hardware environment:
|
||||
|
||||
#. Connect the mouse, keyboard, monitor, and power supply cable to the target
|
||||
system.
|
||||
|
||||
#. Connect the target system to the LAN with the Ethernet cable.
|
||||
|
||||
Example of a target system with cables connected:
|
||||
|
||||
.. image:: ./images/gsg_nuc.png
|
||||
:scale: 25%
|
||||
|
||||
.. _gsg-dev-computer:
|
||||
|
||||
.. rst-class:: numbered-step
|
||||
@ -154,7 +135,7 @@ To set up the ACRN build environment on the development computer:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo pip3 install lxml xmlschema defusedxml tqbm
|
||||
sudo pip3 install lxml xmlschema defusedxml tqdm
|
||||
|
||||
#. Create a working directory:
|
||||
|
||||
@ -183,10 +164,10 @@ To set up the ACRN build environment on the development computer:
|
||||
cd ~/acrn-work
|
||||
git clone https://github.com/projectacrn/acrn-hypervisor.git
|
||||
cd acrn-hypervisor
|
||||
git checkout acrn-2022w18.4-180000p
|
||||
git checkout release_3.0
|
||||
|
||||
cd ..
|
||||
git clone --depth 1 --branch acrn-2022w18.4-180000p https://github.com/projectacrn/acrn-kernel.git
|
||||
git clone --depth 1 --branch release_3.0 https://github.com/projectacrn/acrn-kernel.git
|
||||
|
||||
.. _gsg-board-setup:
|
||||
|
||||
@ -205,9 +186,29 @@ hardware.
|
||||
|
||||
.. important::
|
||||
|
||||
Whenever you change the configuration of the board, such as peripherals, BIOS
|
||||
settings, additional memory, or PCI devices, you must generate a new board
|
||||
configuration file.
|
||||
Before running the Board Inspector, you must set up your target hardware and
|
||||
BIOS exactly as you want it, including connecting all peripherals,
|
||||
configuring BIOS settings, and adding memory and PCI devices. For example,
|
||||
you must connect all USB devices; otherwise, the Board Inspector will not
|
||||
detect the USB devices for passthrough. If you change the hardware or BIOS
|
||||
configuration, or add or remove USB devices, you must run the Board Inspector
|
||||
again to generate a new board configuration file.
|
||||
|
||||
Set Up the Target Hardware
|
||||
============================
|
||||
|
||||
To set up the target hardware environment:
|
||||
|
||||
#. Connect all USB devices, such as a mouse and keyboard.
|
||||
|
||||
#. Connect the monitor and power supply cable.
|
||||
|
||||
#. Connect the target system to the LAN with the Ethernet cable.
|
||||
|
||||
Example of a target system with cables connected:
|
||||
|
||||
.. image:: ./images/gsg_nuc.png
|
||||
:scale: 25%
|
||||
|
||||
Install OS on the Target
|
||||
============================
|
||||
@ -323,7 +324,7 @@ Generate a Board Configuration File
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/acrn-work
|
||||
sudo apt install ./acrn-board-inspector*.deb
|
||||
sudo apt install -y ./acrn-board-inspector*.deb
|
||||
|
||||
#. Reboot the system:
|
||||
|
||||
@ -391,90 +392,11 @@ their attributes, and the resources they have access to.
|
||||
A **launch script** is a shell script that is used to configure and create a
|
||||
post-launched User VM. Each User VM has its own launch script.
|
||||
|
||||
First, you will install dependencies, build the ACRN Configurator Debian
|
||||
package, and install it on your development computer. Then you will use the ACRN
|
||||
Configurator to generate a scenario configuration file and launch script.
|
||||
|
||||
#. On the development computer, install the ACRN Configurator build tools:
|
||||
#. On the development computer, install the ACRN Configurator:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt install -y libwebkit2gtk-4.0-dev \
|
||||
build-essential \
|
||||
curl \
|
||||
wget \
|
||||
libssl-dev \
|
||||
libgtk-3-dev \
|
||||
libappindicator3-dev \
|
||||
librsvg2-dev \
|
||||
python3-venv
|
||||
|
||||
#. Install Node.js (npm included) as follows:
|
||||
|
||||
a. We recommend using nvm to manage your Node.js runtime. It allows you to
|
||||
switch versions and update Node.js easily.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
|
||||
|
||||
#. Rerun your ``.bashrc`` initialization script and then install the latest
|
||||
version of Node.js and npm:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
source ~/.bashrc
|
||||
nvm install node --latest-npm
|
||||
nvm use node
|
||||
|
||||
#. Install and upgrade Yarn:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
npm install --global yarn
|
||||
|
||||
#. Install rustup, the official installer for Rust:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
|
||||
When prompted by the Rust installation script, type ``1`` and press
|
||||
:kbd:`Enter`.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
1) Proceed with installation (default)
|
||||
2) Customize installation
|
||||
3) Cancel installation
|
||||
>1
|
||||
|
||||
#. Configure the current shell:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
source $HOME/.cargo/env
|
||||
|
||||
#. Install additional ACRN Configurator dependencies:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/acrn-work/acrn-hypervisor/misc/config_tools/configurator
|
||||
python3 -m pip install -r requirements.txt
|
||||
yarn
|
||||
|
||||
#. Build the ACRN Configurator Debian package:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/acrn-work/acrn-hypervisor
|
||||
make configurator
|
||||
|
||||
#. Install the ACRN Configurator:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt install -y ~/acrn-work/acrn-hypervisor/build/acrn-configurator_*_amd64.deb
|
||||
sudo apt install -y ~/acrn-work/acrn-hypervisor/build/acrn-configurator_*_amd64.deb # TODO update file path
|
||||
|
||||
#. Launch the ACRN Configurator:
|
||||
|
||||
@ -482,69 +404,111 @@ Configurator to generate a scenario configuration file and launch script.
|
||||
|
||||
acrn-configurator
|
||||
|
||||
#. On the left-hand side, look for **Start a new configuration**.
|
||||
Confirm that the working folder is ``<path to>/acrn-work/MyConfiguration``. Click **Use This Folder**.
|
||||
#. Under **Start a new configuration**, confirm that the working folder is
|
||||
``<path to>/acrn-work/MyConfiguration``. Click **Use This Folder**.
|
||||
|
||||
TODO add screenshots to Configurator steps
|
||||
.. image:: images/configurator-newconfig.png
|
||||
:align: center
|
||||
:class: drop-shadow
|
||||
|
||||
#. Import your board configuration file as follows:
|
||||
|
||||
a. Under **Import a board configuration file**, click **Browse for file**.
|
||||
a. In the **1. Import a board configuration file** panel, click **Browse for
|
||||
file**.
|
||||
|
||||
#. Browse to ``~/acrn-work/my_board.xml`` and click **Open**.
|
||||
|
||||
#. Click **Import Board File**.
|
||||
|
||||
.. image:: images/configurator-board01.png
|
||||
:align: center
|
||||
:class: drop-shadow
|
||||
|
||||
The ACRN Configurator makes a copy of your board file, changes the file
|
||||
extension to ``.board.xml``, and saves the file to the working folder.
|
||||
|
||||
#. Create a new scenario as follows:
|
||||
|
||||
a. Under **Create new or import an existing scenario**, click **Create
|
||||
Scenario**.
|
||||
a. In the **2. Create new or import an existing scenario** panel, click
|
||||
**Create Scenario**.
|
||||
|
||||
.. image:: images/configurator-newscenario01.png
|
||||
:align: center
|
||||
:class: drop-shadow
|
||||
|
||||
#. In the dialog box, confirm that **Shared (Post-launched VMs only)** is
|
||||
selected.
|
||||
|
||||
#. Confirm that one Service VM and one post-launched VM are selected.
|
||||
|
||||
#. Click **Create**.
|
||||
#. Click **Ok**.
|
||||
|
||||
#. Generate the scenario configuration file and launch script:
|
||||
.. image:: images/configurator-newscenario02.png
|
||||
:align: center
|
||||
:class: drop-shadow
|
||||
|
||||
a. Under **Configure settings for scenario and launch scripts**, the
|
||||
scenario's configurable items appear. Feel free to look through all the
|
||||
available configuration settings. This is where you can change the
|
||||
settings to meet your application's particular needs. But for now, you will update only a few settings to make this example work.
|
||||
#. In the **3. Configure settings for scenario and launch scripts** panel,
|
||||
the scenario's configurable items appear. Feel free to look through all
|
||||
the available configuration settings. This is where you can change the
|
||||
settings to meet your application's particular needs. But for now, you
|
||||
will update only a few settings for functional and educational purposes.
|
||||
|
||||
#. Click the **VM1 Post-launched** tab to access the post-launched VM's
|
||||
settings.
|
||||
#. Click the **Hypervisor Global Settings > Basic Parameters** tab, select the
|
||||
``Debug`` build type, and select the serial console port (the example shows
|
||||
``/dev/ttyS0``, but yours may be different). If your board doesn't have a
|
||||
serial console port, select the ``Release`` build type. The Debug build type
|
||||
requires a serial console port.
|
||||
|
||||
#. Confirm that the Basic Parameters tab is selected, and scroll down to
|
||||
**Memory size (MB)**. Change the value to ``1024``. For this example, we
|
||||
will use Ubuntu 20.04 to boot the post-launched VM. Ubuntu 20.04 needs at
|
||||
least 1024 MB to boot.
|
||||
.. image:: images/configurator-buildtype.png
|
||||
:align: center
|
||||
:class: drop-shadow
|
||||
|
||||
#. Scroll down to **Virtio block device**, click **+**, and enter
|
||||
#. Click the **VM0 ServiceVM > Basic Parameters** tab and change the VM name
|
||||
to ``ACRN_Service_VM`` for this example.
|
||||
|
||||
.. image:: images/configurator-servicevm.png
|
||||
:align: center
|
||||
:class: drop-shadow
|
||||
|
||||
#. Configure the post-launched VM as follows:
|
||||
|
||||
#. Click the **VM1 Post-launched > Basic Parameters** tab and change the VM
|
||||
name to ``POST_STD_VM1`` for this example.
|
||||
|
||||
#. Confirm that the **OS type** is ``Standard``. In the previous step,
|
||||
``STD`` in the VM name is short for Standard.
|
||||
|
||||
#. Scroll down to **Memory size (MB)** and change the value to ``1024``. For
|
||||
this example, we will use Ubuntu 20.04 to boot the post-launched VM.
|
||||
Ubuntu 20.04 needs at least 1024 MB to boot.
|
||||
|
||||
#. For **Physical CPU affinity**, select pCPU ID ``0``, then click **+** and
|
||||
select pCPU ID ``1`` to affine the VM to CPU cores 0 and 1.
|
||||
|
||||
#. For **Virtio block device**, click **+** and enter
|
||||
``~/acrn-work/ubuntu-20.04.4-desktop-amd64.iso``. This parameter
|
||||
specifies the VM's OS image and its location on the target system. Later
|
||||
in this guide, you will save the ISO file to that directory.
|
||||
|
||||
#. Click **Save Scenario And Launch Scripts** to generate the scenario
|
||||
configuration file and launch script.
|
||||
.. image:: images/configurator-postvm.png
|
||||
:align: center
|
||||
:class: drop-shadow
|
||||
|
||||
#. Scroll up to the top of the panel and click **Save Scenario And Launch
|
||||
Scripts** to generate the scenario configuration file and launch script.
|
||||
|
||||
#. Click the **x** in the upper-right corner to close the ACRN
|
||||
Configurator.
|
||||
|
||||
#. Confirm that the scenario configuration file ``scenario.xml`` appears in your
|
||||
``acrn-work/MyConfiguration`` directory::
|
||||
#. Confirm that the scenario configuration file ``scenario.xml`` appears in the
|
||||
working directory::
|
||||
|
||||
ls ~/acrn-work/MyConfiguration/scenario.xml
|
||||
|
||||
#. Confirm that the launch script ``TODO`` appears in the
|
||||
expected output directory::
|
||||
#. Confirm that the launch script appears in the
|
||||
working directory::
|
||||
|
||||
ls ~/acrn-work/MyConfiguration/TODO
|
||||
ls ~/acrn-work/MyConfiguration/launch_user_vm_id1.sh
|
||||
|
||||
.. _gsg_build:
|
||||
|
||||
@ -695,6 +659,14 @@ The ACRN hypervisor boots the Ubuntu Service VM automatically.
|
||||
|
||||
[ 0.000000] Hypervisor detected: ACRN
|
||||
|
||||
#. Enable and start the Service VM's system daemon for managing network configurations,
|
||||
so the Device Model can create a bridge device (acrn-br0) that provides User VMs with
|
||||
wired network access:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl enable --now systemd-networkd
|
||||
|
||||
.. _gsg-user-vm:
|
||||
|
||||
.. rst-class:: numbered-step
|
||||
|
||||
BIN
doc/getting-started/images/configurator-board01.png
Normal file
BIN
doc/getting-started/images/configurator-board01.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
BIN
doc/getting-started/images/configurator-buildtype.png
Normal file
BIN
doc/getting-started/images/configurator-buildtype.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
BIN
doc/getting-started/images/configurator-newconfig.png
Normal file
BIN
doc/getting-started/images/configurator-newconfig.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 118 KiB |
BIN
doc/getting-started/images/configurator-newscenario01.png
Normal file
BIN
doc/getting-started/images/configurator-newscenario01.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
BIN
doc/getting-started/images/configurator-newscenario02.png
Normal file
BIN
doc/getting-started/images/configurator-newscenario02.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
BIN
doc/getting-started/images/configurator-postvm.png
Normal file
BIN
doc/getting-started/images/configurator-postvm.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 138 KiB |
BIN
doc/getting-started/images/configurator-servicevm.png
Normal file
BIN
doc/getting-started/images/configurator-servicevm.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
@ -3,20 +3,14 @@
|
||||
Introduction to ACRN Configuration
|
||||
##################################
|
||||
|
||||
ACRN configuration is designed for System Integrators / Tier 1s to customize
|
||||
ACRN configuration is designed for System Integrators and Tier 1s to customize
|
||||
ACRN to meet their own needs. It allows users to adapt ACRN to target boards as
|
||||
well as configure hypervisor capabilities and provision VMs.
|
||||
|
||||
ACRN configuration consists of the following key components.
|
||||
|
||||
* Configuration data saved as XML files.
|
||||
* A configuration toolset that helps users to generate and edit configuration
|
||||
data. The toolset includes:
|
||||
|
||||
- **Board Inspector**: Collects board-specific information on target
|
||||
machines.
|
||||
- **ACRN Configurator**: Enables you to edit configuration data via a
|
||||
web-based UI.
|
||||
* A configuration toolset to generate and edit configuration data.
|
||||
|
||||
The following sections introduce the concepts and tools of ACRN configuration
|
||||
from the aspects below.
|
||||
@ -25,16 +19,14 @@ from the aspects below.
|
||||
different types of configuration data.
|
||||
* :ref:`acrn_config_workflow` overviews the steps to customize ACRN
|
||||
configuration using the configuration toolset.
|
||||
* :ref:`acrn_config_data` explains the location and format of configuration
|
||||
data saved as XML files.
|
||||
|
||||
.. _acrn_config_types:
|
||||
|
||||
Types of Configurations
|
||||
***********************
|
||||
|
||||
ACRN includes three types of configurations: board, scenario, and launch. The
|
||||
configuration data are saved in three XML files. The following sections briefly
|
||||
ACRN includes two types of configurations: board and scenario. The
|
||||
configuration data are saved in XML files. The following sections briefly
|
||||
describe the objectives and main contents of each file.
|
||||
|
||||
Board Configuration File
|
||||
@ -60,9 +52,8 @@ Scenario Configuration File
|
||||
===========================
|
||||
|
||||
The scenario configuration file defines a working scenario by configuring
|
||||
hypervisor capabilities and defining some VM attributes and resources.
|
||||
We call these settings "static" because they are used to build the hypervisor.
|
||||
You can specify the following information in a scenario configuration:
|
||||
hypervisor capabilities and defining VM attributes and resources. Examples of
|
||||
parameters:
|
||||
|
||||
* Hypervisor capabilities
|
||||
|
||||
@ -83,46 +74,29 @@ You can specify the following information in a scenario configuration:
|
||||
- User VM settings, such as boot protocol and VM OS kernel parameters.
|
||||
- Settings of virtual devices, such as virtual UARTs.
|
||||
|
||||
You need a scenario configuration file to build an ACRN hypervisor. The
|
||||
build process uses the file to build a hypervisor that can initialize its
|
||||
capabilities and set up the VMs at runtime.
|
||||
You need a scenario configuration file to build an ACRN hypervisor. The build process uses the file to build a hypervisor that can initialize its capabilities and set up the VMs at runtime.
|
||||
|
||||
The scenario configuration defines User VMs as follows:
|
||||
For pre-launched User VMs, all attributes and resources are static
|
||||
configurations. The VM attributes and resources are exactly the amount of
|
||||
resources allocated to them.
|
||||
|
||||
* For pre-launched User VMs, the scenario configuration defines all attributes
|
||||
and resources (these VMs have static configurations by nature). The VM
|
||||
attributes and resources are exactly the amount
|
||||
of resources allocated to them.
|
||||
|
||||
* For post-launched User VMs, the scenario configuration defines only static
|
||||
attributes and resources. Other resources are under the control of the
|
||||
Service VM and can be dynamically allocated to these VMs via launch
|
||||
scripts.
|
||||
|
||||
Launch Configuration File for Launch Scripts
|
||||
============================================
|
||||
|
||||
The launch configuration file applies only to scenarios that have
|
||||
post-launched User VMs. The file defines certain attributes and
|
||||
resources of the post-launched VMs specified in the scenario configuration
|
||||
file. We call these settings "dynamic" because they are used at runtime.
|
||||
|
||||
You need a launch configuration file to generate a launch script (shell script)
|
||||
for each post-launched User VM. The launch script invokes the
|
||||
Service VM's :ref:`Device Model <hld-devicemodel>` ``acrn-dm`` to create
|
||||
the VM. Unlike board and scenario configurations used at build time or by
|
||||
ACRN hypervisor, launch configurations are used dynamically in the Service VM.
|
||||
For post-launched User VMs, some resources are static configurations. Other
|
||||
resources are under the control of the Service VM and can be dynamically
|
||||
allocated to a VM via a launch script.
|
||||
|
||||
.. _acrn_config_workflow:
|
||||
|
||||
Using ACRN Configuration Toolset
|
||||
********************************
|
||||
|
||||
The ACRN configuration toolset enables you to create
|
||||
and edit configuration data. The toolset consists of the following:
|
||||
The ACRN configuration toolset lets you create and edit configuration data. The
|
||||
toolset includes:
|
||||
|
||||
* :ref:`Board Inspector <board_inspector_tool>`
|
||||
* :ref:`ACRN Configurator <acrn_configurator_tool>`
|
||||
* :ref:`Board Inspector <board_inspector_tool>`: Collects information from your
|
||||
target machine and generates a board configuration file.
|
||||
* :ref:`ACRN Configurator <acrn_configurator_tool>`: Provides a graphical user
|
||||
interface (GUI) for configuring your hypervisor and VM parameters, and
|
||||
generates a scenario configuration file and launch scripts.
|
||||
|
||||
As introduced in :ref:`overview_dev`, configuration takes place at
|
||||
:ref:`overview_dev_board_config` and :ref:`overview_dev_config_editor` in
|
||||
@ -132,73 +106,3 @@ the overall development process:
|
||||
|
||||
ACRN source also includes makefile targets to aid customization. See
|
||||
:ref:`hypervisor-make-options`.
|
||||
|
||||
.. _acrn_config_data:
|
||||
|
||||
ACRN Configuration Data
|
||||
***********************
|
||||
|
||||
The following sections explain the format of the board, scenario, and launch
|
||||
configuration files. Although we recommend using the ACRN configuration toolset
|
||||
to create these files, this reference may be useful for advanced usage and
|
||||
troubleshooting.
|
||||
|
||||
ACRN source code offers predefined XMLs, and the generic templates used for
|
||||
new boards and scenarios, in the ``misc/config_tools/data/`` directory of
|
||||
the ``acrn-hypervisor`` repo.
|
||||
|
||||
Board XML Format
|
||||
================
|
||||
|
||||
The board XML has an ``acrn-config`` root element and a
|
||||
``board`` attribute:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<acrn-config board="BOARD">
|
||||
|
||||
The ``board`` attribute defines the board name and must match the
|
||||
``board`` attribute in the scenario configuration file and the launch
|
||||
configuration file. The file name of the board configuration file
|
||||
(example: ``my_board.xml``) doesn't affect the board name.
|
||||
|
||||
Board XML files are input to the ACRN Configurator tool and the build system,
|
||||
and are not intended for end users to modify.
|
||||
|
||||
Scenario XML Format
|
||||
===================
|
||||
|
||||
The scenario XML has an ``acrn-config`` root element as well as ``board`` and
|
||||
``scenario`` attributes:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<acrn-config board="BOARD" scenario="SCENARIO">
|
||||
|
||||
The ``board`` attribute specifies the board name and must match the ``board``
|
||||
attribute in the board configuration file.
|
||||
|
||||
The ``scenario`` attribute specifies the scenario name, followed by hypervisor
|
||||
and VM settings.
|
||||
|
||||
See :ref:`scenario-config-options` for a full explanation of available scenario
|
||||
XML elements.
|
||||
|
||||
Launch XML Format
|
||||
=================
|
||||
|
||||
The launch XML has an ``acrn-config`` root element as well as
|
||||
``board``, ``scenario``, and ``user_vm_launcher`` attributes:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<acrn-config board="BOARD" scenario="SCENARIO" user_vm_launcher="USER_VM_NUMBER">
|
||||
|
||||
The ``board`` attribute specifies the board name and must match the ``board``
|
||||
attribute in the board configuration file and the scenario configuration file.
|
||||
|
||||
The ``scenario`` attribute specifies the scenario name and must match the
|
||||
``scenario`` attribute in the scenario configuration file.
|
||||
|
||||
The ``user_vm_launcher`` attribute specifies the number of post-launched User
|
||||
VMs in a scenario.
|
||||
|
||||
@ -25,7 +25,6 @@ This guide assumes you have a board configuration file and have successfully
|
||||
launched the ACRN Configurator. For steps, see the following Getting Started
|
||||
Guide sections:
|
||||
|
||||
* :ref:`gsg-target-hardware`
|
||||
* :ref:`gsg-dev-computer`
|
||||
* :ref:`gsg-board-setup`
|
||||
* :ref:`gsg-dev-setup`
|
||||
|
||||
@ -13,21 +13,28 @@ configuration file on the target system. The board configuration file stores
|
||||
hardware-specific information extracted from the target platform and is used to
|
||||
customize your :ref:`ACRN configuration <acrn_configuration_tool>`.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
This guide assumes you have set up your target system and successfully launched
|
||||
the Board Inspector. For steps, see the following Getting Started Guide
|
||||
sections:
|
||||
|
||||
* :ref:`gsg-dev-computer`
|
||||
* :ref:`gsg-board-setup`
|
||||
|
||||
Generate a Board Configuration File
|
||||
***********************************
|
||||
|
||||
.. important::
|
||||
|
||||
Whenever you change the configuration of the board, such as BIOS settings,
|
||||
additional memory, or PCI devices, you must generate a new board
|
||||
configuration file.
|
||||
Whenever you change the configuration of the board, such as peripherals, BIOS
|
||||
settings, additional memory, USB devices, or PCI devices, you must generate a
|
||||
new board configuration file.
|
||||
|
||||
The following steps describe all options in the Board Inspector for generating
|
||||
a board configuration file.
|
||||
|
||||
#. Make sure the target system is set up and ready to run the Board Inspector,
|
||||
according to :ref:`gsg-board-setup` in the Getting Started Guide.
|
||||
|
||||
#. Run the Board Inspector tool (``board_inspector.py``) to generate the board
|
||||
configuration file. This example assumes the tool is in the
|
||||
``~/acrn-work/`` directory and ``my_board`` is the desired file
|
||||
@ -35,14 +42,8 @@ a board configuration file.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/acrn-work/board_inspector/
|
||||
sudo python3 board_inspector.py my_board
|
||||
|
||||
Upon success, the tool displays a message similar to this example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
my_board.xml saved successfully!
|
||||
cd ~/acrn-work
|
||||
sudo board_inspector.py my_board
|
||||
|
||||
#. Confirm that the board configuration file ``my_board.xml`` was generated in
|
||||
the current directory.
|
||||
@ -58,7 +59,9 @@ Board Inspector with the ``-h`` option yields the following usage message:
|
||||
.. code-block::
|
||||
|
||||
usage: board_inspector.py [-h] [--out OUT] [--basic] [--loglevel LOGLEVEL]
|
||||
[--check-device-status] board_name
|
||||
[--check-device-status]
|
||||
[--add-llc-cat <capacity_mask_length:int>,<clos_number:int>,<has_CDP:bool>]
|
||||
board_name
|
||||
|
||||
positional arguments:
|
||||
board_name the name of the board that runs the ACRN hypervisor
|
||||
@ -66,11 +69,15 @@ Board Inspector with the ``-h`` option yields the following usage message:
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--out OUT the name of board info file
|
||||
--basic do not extract advanced information such as ACPI namespace
|
||||
--loglevel LOGLEVEL choose log level, e.g. info, warning or error
|
||||
--basic do not extract advanced information such as ACPI
|
||||
namespace
|
||||
--loglevel LOGLEVEL choose log level, e.g. debug, info, warning, error or
|
||||
critical
|
||||
--check-device-status
|
||||
|
||||
filter out devices whose _STA object evaluates to 0
|
||||
--add-llc-cat <capacity_mask_length:int>,<clos_number:int>,<has_CDP:bool>
|
||||
manually set the Cache Allocation Technology
|
||||
capability of the last level cache
|
||||
|
||||
Details about certain arguments:
|
||||
|
||||
@ -98,8 +105,7 @@ Details about certain arguments:
|
||||
of board configuration files.
|
||||
|
||||
* - ``--loglevel``
|
||||
- Optional. Choose log level, e.g., info, warning or error.
|
||||
(Default is warning.)
|
||||
- Optional. Choose the log level. (Default is warning.)
|
||||
|
||||
* - ``--check-device-status``
|
||||
- Optional. On some boards, the device status (reported by the _STA
|
||||
@ -107,3 +113,12 @@ Details about certain arguments:
|
||||
pass-through devices. By default, the Board Inspector includes the
|
||||
devices in the board configuration file. This option filters out the
|
||||
devices, so that they cannot be used.
|
||||
|
||||
* - ``--add-llc-cat``
|
||||
- Optional. Add the Cache Allocation Technology (CAT) capabilities of the
|
||||
last level cache (LLC) to the generated board configuration file even
|
||||
when the hardware does not report them for any reason. For example,
|
||||
``--add-llc-cat=12,16,y``. CDP (Code and Data Prioritization) performance
|
||||
feature enables separate control over code and data placement in the
|
||||
processor's cache. Valid values for ``bool`` are
|
||||
``true|false|y|n|yes|no``.
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
Upgrading ACRN Configurations to Recent Releases
|
||||
################################################
|
||||
|
||||
The configuration files, introduced in :ref:`acrn_config_data`, are refined
|
||||
The configuration files, introduced in :ref:`acrn_config_types`, are refined
|
||||
every release for richer features, clearer organization, and more user-friendly
|
||||
presentation. Due to the strict validation ACRN adopts, configuration files
|
||||
for a former release may not work for a latter if they are not upgraded. This
|
||||
|
||||
Loading…
Reference in New Issue
Block a user