github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-08-14 06:16:38 +00:00
Code Issues Projects Releases Wiki Activity

doc: update Overview with DX recommendations

Browse Source 
- 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 2021-10-18 13:50:39 -07:00 committed by David Kinder
parent 2c5db9b7af
commit fc0112067e
3 changed files with 124 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/getting-started/images/gsg_overview_image_sources.pptx
View File

Binary file not shown.

BIN
doc/getting-started/images/overview_flow.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 109 KiB

After

Width:  |  Height:  |  Size: 109 KiB

228
doc/getting-started/overview_dev.rst
View File

@ -3,19 +3,21 @@
Configuration and Development Overview Configuration and Development Overview
###################################### ######################################
This overview is for developers who are new or relatively new to ACRN. It will This overview is for developers who are new or relatively new to ACRN and are
help you get familiar with ACRN basics: ACRN components and general process for responsible for configuring and building ACRN hypervisors. It will introduce you to the general development process, including ACRN components and
building an ACRN hypervisor. tools.
The overview covers the process at an abstract and universal level. The overview covers the process at an abstract and universal level.
* Abstract: the overall structure rather than detailed instructions * Abstract: the overall structure rather than detailed instructions
* Universal: applicable to most use cases * Universal: applicable to most use cases
Although the overview describes the process as a series of steps, it's intended The overview is intended to complement the :ref:`gsg`. The guide provides
to be a summary, not a step-by-step guide. Throughout the overview, you will see step-by-step instructions to enable an ACRN example for first-time use, while
links to the :ref:`gsg` for first-time setup instructions. Links to advanced the overview provides background information and serves as a gateway to
guides and additional information are also provided. 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: .. _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 have a serial output, :ref:`here are some tips for connecting a serial output
<connect_serial_port>`. <connect_serial_port>`.
You will need a way to copy the built ACRN images from the development computer You need a way to copy the built ACRN images and other files between the
to the target system. A USB drive is recommended. 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 General Process for Building an ACRN Hypervisor
*********************************************** ***********************************************
@ -69,9 +72,8 @@ See :ref:`hardware`.
Select Your Scenario Select Your Scenario
==================== ====================
A :ref:`scenario <usage-scenarios>` is a specific ACRN configuration, such as A scenario defines a specific ACRN configuration, such as the type and number of
the type and number of VMs that can be run, their attributes, and the resources VMs that can be run, their attributes, and the resources they have access to.
they have access to.
This image shows an example of an ACRN scenario to illustrate the types of VMs This image shows an example of an ACRN scenario to illustrate the types of VMs
that ACRN offers: that ACRN offers:
@ -81,18 +83,26 @@ that ACRN offers:
ACRN offers three types of VMs: ACRN offers three types of VMs:
* **Pre-launched User VMs**: These VMs run independently of other VMs and own * **Pre-launched User VMs**: These VMs are automatically launched at boot time
dedicated hardware resources, such as a CPU core, memory, and I/O devices. by the hypervisor. They run independently of other VMs and own dedicated
Other VMs may not even be aware of the existence of pre-launched VMs. The hardware resources, such as a CPU core, memory, and I/O devices. Other VMs,
configuration of these VMs is static and must be defined at build time. They including the Service VM, may not even be aware of a pre-launched VM’s
are well-suited for safety-critical applications. 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. * **Service VM**: A special VM, required for scenarios that have post-launched
It controls post-launched VMs and provides device sharing services to them. User VMs. The Service VM can access hardware resources directly by running
ACRN supports one Service VM. 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 * **Post-launched User VMs**: These VMs typically share hardware resources via
pre-launched VMs, you can change the configuration at run-time. They are 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 well-suited for non-safety applications, including human machine interface
(HMI), artificial intelligence (AI), computer vision, real-time, and others. (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 stringent real-time requirements, start by testing the application on a
post-launched VM before considering a pre-launched VM. post-launched VM before considering a pre-launched VM.
Predefined Scenarios
---------------------
To help accelerate the configuration process, ACRN offers the following 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 * **Shared scenario:** This scenario represents a traditional computing, memory,
(post-launched). 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 * **Partitioned scenario:** This scenario has pre-launched User VMs to
each other and don't share resources (pre-launched). 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 * **Hybrid scenario:** This scenario simultaneously supports both sharing and
post-launched VMs. 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 ACRN provides predefined configuration files and documentation to help you set
up these scenarios. up these scenarios. You can customize the files for your use case, as described
later in :ref:`overview_dev_config_editor`.
* 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`.
|icon_host| Step 2: Prepare the Development Computer |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 Your development computer requires certain dependencies to configure and build
ACRN: ACRN:
* Ubuntu OS * Ubuntu OS (ACRN development is not supported on Windows.)
* Build tools * Build tools
* ACRN hypervisor source code * ACRN hypervisor source code
* If your scenario has a Service VM: ACRN kernel 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 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
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
about the target hardware and generate a board configuration file. about the target hardware and generate a board configuration file.
.. _overview_dev_board_config: .. _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 .. |icon_target| image:: ./images/icon_target.png
:scale: 75% :scale: 75%
A **board configuration file** is an XML file that stores hardware-specific The :ref:`board_inspector_tool` ``board_inspector.py`` enables you to generate a
information extracted from the target system. It describes the capacity of board configuration file on the target system.
hardware resources (such as processors and memory), platform power states,
available devices, and BIOS settings. The file is used to configure the ACRN 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 hypervisor, because each hypervisor instance is specific to your target
hardware. hardware.
The **board inspector tool** ``board_inspector.py`` enables you to generate a board The following sections provide an overview and important information to keep
configuration file on the target system. The following sections provide an in mind when using the Board Inspector.
overview and important information to keep in mind when using the tool.
Configure BIOS Settings Configure BIOS Settings
======================= =======================
You must configure all of your target's BIOS settings before running 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 Inspector tool, because the tool records the current BIOS settings in the board
configuration file. configuration file.
Some BIOS settings are required by ACRN. The :ref:`gsg` provides a list of the ACRN requires the following BIOS settings:
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 Use the Board Inspector to Generate a Board Configuration File
============================================================== ==============================================================
The board inspector tool requires certain dependencies to be present on the The Board Inspector requires certain dependencies to be present on the target
target system: system:
* Ubuntu OS * 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 collect information about the target hardware
After setting up the dependencies, you run the board inspector via command-line. After setting up the dependencies, you run the Board Inspector via command-line.
The tool generates a board configuration file specific to your hardware. The tool generates the board configuration file specific to your hardware.
.. important:: Whenever you change the configuration of the board, such as BIOS .. important:: Whenever you change the configuration of the board, such as BIOS
settings or PCI ports, you must generate a new board configuration file. 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 You will need the board configuration file in :ref:`overview_dev_config_editor`
information about the tool, see :ref:`board_inspector_tool`. and :ref:`overview_dev_build`.
.. _overview_dev_config_editor: .. _overview_dev_config_editor:
|icon_host| Step 4: Generate a Scenario Configuration File and Launch Scripts |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 The :ref:`acrn_configurator_tool` ``acrn_configurator.py`` enables you to
ACRN configuration, such as the number of VMs that can be run, their attributes, configure your ACRN hypervisor and VMs via a web-based user interface on your
and the resources they have access to. These parameters are saved in a development computer. Using the tool, you define your scenario settings and save
**scenario configuration file** in XML format. 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 following sections provide an overview and important information to keep
in mind when using the ACRN Configurator.
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.
Generate a Scenario Configuration File 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 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 :ref:`overview_dev_board_config`. The tool needs the board configuration file to
validate that your custom scenario is supported by the target hardware. 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 You can use the tool to create a new scenario configuration file or modify an
existing one, such as a predefined scenario described in 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 configurable items in the file, such as adding VMs, modifying VM attributes, or
deleting VMs. The tool validates your inputs against your board configuration deleting VMs. The tool validates your inputs against your board configuration
file. After validation is successful, the tool generates your custom scenario file. After validation is successful, the tool generates your custom scenario
configuration file. configuration file in XML format.
Generate Launch Scripts 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 you have your board configuration file and scenario configuration file. The tool
needs both files to validate your launch script configuration. needs both files to validate your launch script configuration.
The process of customizing launch scripts is similar to the process of The process of generating launch scripts begins by choosing to create a new
customizing scenario configuration files. You can choose to create a new launch launch configuration or modify an existing one. You then use the GUI to
script or modify an existing one. You can then use the GUI to edit the edit the configurable settings of each post-launched User VM in your scenario.
configurable parameters. The tool validates your inputs against your board The tool validates your inputs against your board configuration file and
configuration file and scenario configuration file. After validation is scenario configuration file. After validation is successful, the tool generates
successful, the tool generates your custom launch script. 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:: .. 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 parameters for scenario configuration files and launch scripts. You can edit
the parameters manually. See :ref:`acrn_config_data`. the parameters manually. See :ref:`acrn_config_data`.
The :ref:`gsg` walks you through a simple example of using the tool. For more .. _overview_dev_build:
information about the tool, see :ref:`acrn_configurator_tool`.
|icon_host| Step 5: Build ACRN |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 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 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. 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 The kernel build can take 15 minutes or less on a fast computer, but could take
computer and network. an hour or more depending on the performance of your development computer. For
more information about the kernel, see :ref:`kernel-parameters`.
The :ref:`gsg` provides step-by-step instructions.
For more information about the kernel, see :ref:`kernel-parameters`.
.. _overview_dev_install: .. _overview_dev_install:
@ -282,8 +305,11 @@ then boot ACRN.
At a high level, you will: At a high level, you will:
* Copy the built ACRN hypervisor files, kernel files, and launch scripts from * Copy the built ACRN hypervisor files, Service VM kernel files, and launch
the development computer to the target. 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. * Configure GRUB to boot the ACRN hypervisor, pre-launched VMs, and Service VM.
Reboot the target, and launch ACRN. 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 post-launched VM and run the launch script you created in
:ref:`overview_dev_config_editor`. :ref:`overview_dev_config_editor`.
For a basic example, see the :ref:`gsg`. Learn More
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
********** **********
* To get ACRN up and running for the first time, see the :ref:`gsg` for * To get ACRN up and running for the first time, see the :ref:`gsg` for
step-by-step instructions. step-by-step instructions.
* If you have already completed the :ref:`gsg`, see the :ref:`develop_acrn` for * If you have already completed the Getting Started Guide, see the
more information about complex scenarios, advanced features, and debugging. :ref:`develop_acrn` for more information about complex scenarios, advanced
features, and debugging