diff --git a/doc/getting-started/images/gsg_overview_image_sources.pptx b/doc/getting-started/images/gsg_overview_image_sources.pptx index a29b3f862..8fa558864 100644 Binary files a/doc/getting-started/images/gsg_overview_image_sources.pptx and b/doc/getting-started/images/gsg_overview_image_sources.pptx differ diff --git a/doc/getting-started/images/overview_flow.png b/doc/getting-started/images/overview_flow.png index 46f034a03..d1a168b92 100644 Binary files a/doc/getting-started/images/overview_flow.png and b/doc/getting-started/images/overview_flow.png differ diff --git a/doc/getting-started/overview_dev.rst b/doc/getting-started/overview_dev.rst index e8fea1520..ccdf00700 100644 --- a/doc/getting-started/overview_dev.rst +++ b/doc/getting-started/overview_dev.rst @@ -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 `. If your target doesn't have a serial output, :ref:`here are some tips for connecting a serial output `. -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 ` 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) ` ``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 `: +:ref:`predefined sample 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 \ No newline at end of file