doc: update Overview with DX recommendations
- Capitalize Board Inspector and ACRN Configurator names to highlight them in images and content - Remove duplicate links between the Overview and GSG where not needed - Provide additional details that help to deepen developer’s knowledge where applicable. Potential items: acrn-dm, more clarity of the relationship between the ServiceVM and UserVMs, expanded definitions of scenarios (beyond one liners). Signed-off-by: Amy Reyes <amy.reyes@intel.com>
This commit is contained in:
Amy Reyes
David Kinder
parent
2c5db9b7af
commit
fc0112067e
Binary file not shown.
Binary file not shown.
|
Before Width: | Height: | Size: 109 KiB After Width: | Height: | Size: 109 KiB |
|
|
@ -3,19 +3,21 @@
|
|||
Configuration and Development Overview
|
||||
######################################
|
||||
|
||||
This overview is for developers who are new or relatively new to ACRN. It will
|
||||
help you get familiar with ACRN basics: ACRN components and general process for
|
||||
building an ACRN hypervisor.
|
||||
This overview is for developers who are new or relatively new to ACRN and are
|
||||
responsible for configuring and building ACRN hypervisors. It will introduce you to the general development process, including ACRN components and
|
||||
tools.
|
||||
|
||||
The overview covers the process at an abstract and universal level.
|
||||
|
||||
* Abstract: the overall structure rather than detailed instructions
|
||||
* Universal: applicable to most use cases
|
||||
|
||||
Although the overview describes the process as a series of steps, it's intended
|
||||
to be a summary, not a step-by-step guide. Throughout the overview, you will see
|
||||
links to the :ref:`gsg` for first-time setup instructions. Links to advanced
|
||||
guides and additional information are also provided.
|
||||
The overview is intended to complement the :ref:`gsg`. The guide provides
|
||||
step-by-step instructions to enable an ACRN example for first-time use, while
|
||||
the overview provides background information and serves as a gateway to
|
||||
additional features and resources that can help you develop your solution.
|
||||
|
||||
The overview doesn't cover ACRN benefits, use cases, or architecture. See :ref:`introduction` to learn more.
|
||||
|
||||
.. _overview_dev_dev_env:
|
||||
|
||||
|
|
@ -35,8 +37,9 @@ for :ref:`debugging and system messaging <acrn-debug>`. If your target doesn't
|
|||
have a serial output, :ref:`here are some tips for connecting a serial output
|
||||
<connect_serial_port>`.
|
||||
|
||||
You will need a way to copy the built ACRN images from the development computer
|
||||
to the target system. A USB drive is recommended.
|
||||
You need a way to copy the built ACRN images and other files between the
|
||||
development computer and target system. ACRN documentation, such as the Getting
|
||||
Started Guide, offers steps for copying via USB disk as a simple solution.
|
||||
|
||||
General Process for Building an ACRN Hypervisor
|
||||
***********************************************
|
||||
|
|
@ -69,9 +72,8 @@ See :ref:`hardware`.
|
|||
Select Your Scenario
|
||||
====================
|
||||
|
||||
A :ref:`scenario <usage-scenarios>` is a specific ACRN configuration, such as
|
||||
the type and number of VMs that can be run, their attributes, and the resources
|
||||
they have access to.
|
||||
A scenario defines a specific ACRN configuration, such as the type and number of
|
||||
VMs that can be run, their attributes, and the resources they have access to.
|
||||
|
||||
This image shows an example of an ACRN scenario to illustrate the types of VMs
|
||||
that ACRN offers:
|
||||
|
|
@ -81,18 +83,26 @@ that ACRN offers:
|
|||
|
||||
ACRN offers three types of VMs:
|
||||
|
||||
* **Pre-launched User VMs**: These VMs run independently of other VMs and own
|
||||
dedicated hardware resources, such as a CPU core, memory, and I/O devices.
|
||||
Other VMs may not even be aware of the existence of pre-launched VMs. The
|
||||
configuration of these VMs is static and must be defined at build time. They
|
||||
are well-suited for safety-critical applications.
|
||||
* **Pre-launched User VMs**: These VMs are automatically launched at boot time
|
||||
by the hypervisor. They run independently of other VMs and own dedicated
|
||||
hardware resources, such as a CPU core, memory, and I/O devices. Other VMs,
|
||||
including the Service VM, may not even be aware of a pre-launched VM’s
|
||||
existence. The configuration of pre-launched VMs is static and must be defined
|
||||
at build time. They are well-suited for safety-critical applications.
|
||||
|
||||
* **Service VM**: This VM is required for scenarios that have post-launched VMs.
|
||||
It controls post-launched VMs and provides device sharing services to them.
|
||||
ACRN supports one Service VM.
|
||||
* **Service VM**: A special VM, required for scenarios that have post-launched
|
||||
User VMs. The Service VM can access hardware resources directly by running
|
||||
native drivers and provides device sharing services to post-launched User VMs
|
||||
through the :ref:`ACRN Device Model (DM) <hld-devicemodel>` ``acrn-dm``
|
||||
application. The Device Model runs inside the Service VM and is responsible
|
||||
for creating and launching a User VM and then performing device emulation for
|
||||
the devices configured for sharing with that User VM. ACRN supports one
|
||||
Service VM.
|
||||
|
||||
* **Post-launched User VMs**: These VMs share hardware resources. Unlike
|
||||
pre-launched VMs, you can change the configuration at run-time. They are
|
||||
* **Post-launched User VMs**: These VMs typically share hardware resources via
|
||||
the Service VM and Device Model. They can also access hardware devices
|
||||
directly if they've been configured as passthrough devices. Unlike
|
||||
pre-launched VMs, you can change the configuration at runtime. They are
|
||||
well-suited for non-safety applications, including human machine interface
|
||||
(HMI), artificial intelligence (AI), computer vision, real-time, and others.
|
||||
|
||||
|
|
@ -106,28 +116,29 @@ meet their requirements without pre-launched VMs. Even if your application has
|
|||
stringent real-time requirements, start by testing the application on a
|
||||
post-launched VM before considering a pre-launched VM.
|
||||
|
||||
Predefined Scenarios
|
||||
---------------------
|
||||
|
||||
To help accelerate the configuration process, ACRN offers the following
|
||||
:ref:`predefined scenarios <usage-scenarios>`:
|
||||
:ref:`predefined sample scenarios <usage-scenarios>`:
|
||||
|
||||
* **Shared scenario:** A configuration in which the VMs share resources
|
||||
(post-launched).
|
||||
* **Shared scenario:** This scenario represents a traditional computing, memory,
|
||||
and device resource sharing model among VMs. It has post-launched User VMs and
|
||||
the required Service VM. There are no pre-launched VMs in this scenario.
|
||||
|
||||
* **Partitioned scenario:** A configuration in which the VMs are isolated from
|
||||
each other and don't share resources (pre-launched).
|
||||
* **Partitioned scenario:** This scenario has pre-launched User VMs to
|
||||
demonstrate VM partitioning: the User VMs are independent and isolated, and
|
||||
they do not share resources. There is no need for the Service VM or Device
|
||||
Model since all partitioned VMs run native device drivers and directly access
|
||||
their configured resources.
|
||||
|
||||
* **Hybrid scenario:** A configuration that has both pre-launched and
|
||||
post-launched VMs.
|
||||
* **Hybrid scenario:** This scenario simultaneously supports both sharing and
|
||||
partitioning on the consolidated system. It has pre-launched and
|
||||
post-launched VMs, along with the Service VM.
|
||||
|
||||
ACRN provides predefined configuration files and documentation to help you set
|
||||
up these scenarios.
|
||||
|
||||
* New ACRN users start with the shared scenario, as described in the :ref:`gsg`.
|
||||
|
||||
* The other predefined scenarios are more complex. The :ref:`develop_acrn`
|
||||
provide setup instructions.
|
||||
|
||||
You can copy the predefined configuration files and customize them for your use
|
||||
case, as described later in :ref:`overview_dev_config_editor`.
|
||||
up these scenarios. You can customize the files for your use case, as described
|
||||
later in :ref:`overview_dev_config_editor`.
|
||||
|
||||
|icon_host| Step 2: Prepare the Development Computer
|
||||
****************************************************
|
||||
|
|
@ -138,16 +149,12 @@ case, as described later in :ref:`overview_dev_config_editor`.
|
|||
Your development computer requires certain dependencies to configure and build
|
||||
ACRN:
|
||||
|
||||
* Ubuntu OS
|
||||
* Ubuntu OS (ACRN development is not supported on Windows.)
|
||||
* Build tools
|
||||
* ACRN hypervisor source code
|
||||
* If your scenario has a Service VM: ACRN kernel source code
|
||||
|
||||
The :ref:`gsg` provides step-by-step instructions for setting up your
|
||||
development computer.
|
||||
|
||||
In the next step, :ref:`overview_dev_board_config`, you will need the board
|
||||
inspector tool found in the ACRN hypervisor source code to collect information
|
||||
In the next step, :ref:`overview_dev_board_config`, you will need the Board Inspector tool found in the ACRN hypervisor source code to collect information
|
||||
about the target hardware and generate a board configuration file.
|
||||
|
||||
.. _overview_dev_board_config:
|
||||
|
|
@ -158,101 +165,120 @@ about the target hardware and generate a board configuration file.
|
|||
.. |icon_target| image:: ./images/icon_target.png
|
||||
:scale: 75%
|
||||
|
||||
A **board configuration file** is an XML file that stores hardware-specific
|
||||
information extracted from the target system. It describes the capacity of
|
||||
hardware resources (such as processors and memory), platform power states,
|
||||
available devices, and BIOS settings. The file is used to configure the ACRN
|
||||
The :ref:`board_inspector_tool` ``board_inspector.py`` enables you to generate a
|
||||
board configuration file on the target system.
|
||||
|
||||
A **board configuration file** stores hardware-specific information extracted
|
||||
from the target system. This XML file describes the capacity of hardware
|
||||
resources (such as processors and memory), platform power states, available
|
||||
devices, and BIOS settings. The file is used to configure and build the ACRN
|
||||
hypervisor, because each hypervisor instance is specific to your target
|
||||
hardware.
|
||||
|
||||
The **board inspector tool** ``board_inspector.py`` enables you to generate a board
|
||||
configuration file on the target system. The following sections provide an
|
||||
overview and important information to keep in mind when using the tool.
|
||||
The following sections provide an overview and important information to keep
|
||||
in mind when using the Board Inspector.
|
||||
|
||||
Configure BIOS Settings
|
||||
=======================
|
||||
|
||||
You must configure all of your target's BIOS settings before running the board
|
||||
inspector tool, because the tool records the current BIOS settings in the board
|
||||
You must configure all of your target's BIOS settings before running the Board
|
||||
Inspector tool, because the tool records the current BIOS settings in the board
|
||||
configuration file.
|
||||
|
||||
Some BIOS settings are required by ACRN. The :ref:`gsg` provides a list of the
|
||||
settings.
|
||||
ACRN requires the following BIOS settings:
|
||||
|
||||
* Enable **VMX** (Virtual Machine Extensions, which provide hardware assist
|
||||
for CPU virtualization).
|
||||
|
||||
* Enable **VT-d** (Intel Virtualization Technology for Directed I/O, which
|
||||
provides additional support for managing I/O virtualization).
|
||||
|
||||
Be sure to configure any other settings that your application needs.
|
||||
|
||||
Use the Board Inspector to Generate a Board Configuration File
|
||||
==============================================================
|
||||
|
||||
The board inspector tool requires certain dependencies to be present on the
|
||||
target system:
|
||||
The Board Inspector requires certain dependencies to be present on the target
|
||||
system:
|
||||
|
||||
* Ubuntu OS
|
||||
* Tools and kernel command-line options that allow the board inspector to
|
||||
* Tools and kernel command-line options that allow the Board Inspector to
|
||||
collect information about the target hardware
|
||||
|
||||
After setting up the dependencies, you run the board inspector via command-line.
|
||||
The tool generates a board configuration file specific to your hardware.
|
||||
After setting up the dependencies, you run the Board Inspector via command-line.
|
||||
The tool generates the board configuration file specific to your hardware.
|
||||
|
||||
.. important:: Whenever you change the configuration of the board, such as BIOS
|
||||
settings or PCI ports, you must generate a new board configuration file.
|
||||
|
||||
The :ref:`gsg` provides step-by-step instructions for using the tool. For more
|
||||
information about the tool, see :ref:`board_inspector_tool`.
|
||||
You will need the board configuration file in :ref:`overview_dev_config_editor`
|
||||
and :ref:`overview_dev_build`.
|
||||
|
||||
.. _overview_dev_config_editor:
|
||||
|
||||
|icon_host| Step 4: Generate a Scenario Configuration File and Launch Scripts
|
||||
*****************************************************************************
|
||||
|
||||
As described in :ref:`overview_dev_select_scenario`, a scenario is a specific
|
||||
ACRN configuration, such as the number of VMs that can be run, their attributes,
|
||||
and the resources they have access to. These parameters are saved in a
|
||||
**scenario configuration file** in XML format.
|
||||
The :ref:`acrn_configurator_tool` ``acrn_configurator.py`` enables you to
|
||||
configure your ACRN hypervisor and VMs via a web-based user interface on your
|
||||
development computer. Using the tool, you define your scenario settings and save
|
||||
them to a scenario configuration file. For scenarios with post-launched User
|
||||
VMs, you must also configure and generate launch scripts.
|
||||
|
||||
A **launch script** is a shell script that is used to create a post-launched VM.
|
||||
|
||||
The **ACRN configurator** ``acrn_configurator.py`` is a web-based user interface that
|
||||
runs on your development computer. It enables you to customize, validate, and
|
||||
generate scenario configuration files and launch scripts. The following sections
|
||||
provide an overview and important information to keep in mind when using the
|
||||
tool.
|
||||
The following sections provide an overview and important information to keep
|
||||
in mind when using the ACRN Configurator.
|
||||
|
||||
Generate a Scenario Configuration File
|
||||
======================================
|
||||
|
||||
Before using the ACRN configurator to generate a scenario configuration
|
||||
A **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. The file contains:
|
||||
|
||||
* All hypervisor settings
|
||||
* All pre-launched User VM settings
|
||||
* All Service VM settings
|
||||
* Some post-launched User VM settings, while other settings are in
|
||||
the launch script
|
||||
|
||||
Before using the ACRN Configurator to generate a scenario configuration
|
||||
file, be sure you have the board configuration file that you generated in
|
||||
:ref:`overview_dev_board_config`. The tool needs the board configuration file to
|
||||
validate that your custom scenario is supported by the target hardware.
|
||||
|
||||
You can use the tool to create a new scenario configuration file or modify an
|
||||
existing one, such as a predefined scenario described in
|
||||
:ref:`overview_dev_hw_scenario`. The tool's GUI enables you to edit the
|
||||
:ref:`overview_dev_hw_scenario`. The tool’s GUI enables you to edit the
|
||||
configurable items in the file, such as adding VMs, modifying VM attributes, or
|
||||
deleting VMs. The tool validates your inputs against your board configuration
|
||||
file. After validation is successful, the tool generates your custom scenario
|
||||
configuration file.
|
||||
configuration file in XML format.
|
||||
|
||||
Generate Launch Scripts
|
||||
=======================
|
||||
|
||||
Before using the ACRN configurator to generate a launch script, be sure
|
||||
A **launch script** invokes the Service VM’s Device Model to create a
|
||||
post-launched User VM. The launch script defines settings needed to launch the
|
||||
User VM and emulate the devices configured for sharing with that User VM. We
|
||||
call these settings “dynamic” because they are used at runtime.
|
||||
|
||||
Before using the ACRN Configurator to generate a launch script, be sure
|
||||
you have your board configuration file and scenario configuration file. The tool
|
||||
needs both files to validate your launch script configuration.
|
||||
|
||||
The process of customizing launch scripts is similar to the process of
|
||||
customizing scenario configuration files. You can choose to create a new launch
|
||||
script or modify an existing one. You can then use the GUI to edit the
|
||||
configurable parameters. The tool validates your inputs against your board
|
||||
configuration file and scenario configuration file. After validation is
|
||||
successful, the tool generates your custom launch script.
|
||||
The process of generating launch scripts begins by choosing to create a new
|
||||
launch configuration or modify an existing one. You then use the GUI to
|
||||
edit the configurable settings of each post-launched User VM in your scenario.
|
||||
The tool validates your inputs against your board configuration file and
|
||||
scenario configuration file. After validation is successful, the tool generates
|
||||
your custom launch configuration file in XML format. You then use the tool to
|
||||
generate the launch scripts. The tool creates one launch script for each VM
|
||||
defined in the launch configuration file.
|
||||
|
||||
.. note::
|
||||
The ACRN configurator may not show all editable
|
||||
The ACRN Configurator may not show all editable
|
||||
parameters for scenario configuration files and launch scripts. You can edit
|
||||
the parameters manually. See :ref:`acrn_config_data`.
|
||||
|
||||
The :ref:`gsg` walks you through a simple example of using the tool. For more
|
||||
information about the tool, see :ref:`acrn_configurator_tool`.
|
||||
.. _overview_dev_build:
|
||||
|
||||
|icon_host| Step 5: Build ACRN
|
||||
******************************
|
||||
|
|
@ -265,12 +291,9 @@ typically takes a few minutes.
|
|||
If your scenario has a Service VM, you also need to build the ACRN kernel for
|
||||
the Service VM. The ACRN kernel source code provides a predefined configuration
|
||||
file and a makefile to build the ACRN kernel binary and associated components.
|
||||
The build can take 1-3 hours depending on the performance of your development
|
||||
computer and network.
|
||||
|
||||
The :ref:`gsg` provides step-by-step instructions.
|
||||
|
||||
For more information about the kernel, see :ref:`kernel-parameters`.
|
||||
The kernel build can take 15 minutes or less on a fast computer, but could take
|
||||
an hour or more depending on the performance of your development computer. For
|
||||
more information about the kernel, see :ref:`kernel-parameters`.
|
||||
|
||||
.. _overview_dev_install:
|
||||
|
||||
|
|
@ -282,8 +305,11 @@ then boot ACRN.
|
|||
|
||||
At a high level, you will:
|
||||
|
||||
* Copy the built ACRN hypervisor files, kernel files, and launch scripts from
|
||||
the development computer to the target.
|
||||
* Copy the built ACRN hypervisor files, Service VM kernel files, and launch
|
||||
scripts from the development computer to the target. The Service VM kernel
|
||||
files replace parts of the Ubuntu installation we installed and used for
|
||||
running the Board Inspector, with the Linux kernel we built based on the board
|
||||
and scenario configuration.
|
||||
|
||||
* Configure GRUB to boot the ACRN hypervisor, pre-launched VMs, and Service VM.
|
||||
Reboot the target, and launch ACRN.
|
||||
|
|
@ -292,18 +318,12 @@ At a high level, you will:
|
|||
post-launched VM and run the launch script you created in
|
||||
:ref:`overview_dev_config_editor`.
|
||||
|
||||
For a basic example, see the :ref:`gsg`.
|
||||
|
||||
For details about GRUB, see :ref:`using_grub`.
|
||||
|
||||
For more complex examples of post-launched VMs, see the
|
||||
:ref:`develop_acrn_user_vm`.
|
||||
|
||||
Next Steps
|
||||
Learn More
|
||||
**********
|
||||
|
||||
* To get ACRN up and running for the first time, see the :ref:`gsg` for
|
||||
step-by-step instructions.
|
||||
|
||||
* If you have already completed the :ref:`gsg`, see the :ref:`develop_acrn` for
|
||||
more information about complex scenarios, advanced features, and debugging.
|
||||
* If you have already completed the Getting Started Guide, see the
|
||||
:ref:`develop_acrn` for more information about complex scenarios, advanced
|
||||
features, and debugging
|
||||
Loading…
Reference in New Issue