1.. _acrn_configuration_tool:
2
3Introduction to ACRN Configuration
4##################################
5
6ACRN configuration is designed for System Integrators and Tier 1s to customize
7ACRN to meet their own needs. It allows users to adapt ACRN to target boards as
8well as configure hypervisor capabilities and provision VMs.
9
10ACRN configuration consists of the following key components.
11
12* Configuration data saved as XML files.
13* A configuration toolset to generate and edit configuration data.
14
15The following sections introduce the concepts and tools of ACRN configuration
16from the aspects below.
17
18* :ref:`acrn_config_types` introduces the objectives and main contents of
19  different types of configuration data.
20* :ref:`acrn_config_workflow` overviews the steps to customize ACRN
21  configuration using the configuration toolset.
22
23.. _acrn_config_types:
24
25Types of Configurations
26***********************
27
28ACRN includes two types of configurations: board and scenario. The
29configuration data are saved in XML files. The following sections briefly
30describe the objectives and main contents of each file.
31
32Board Configuration File
33========================
34
35The board configuration file stores hardware-specific information extracted
36from the target platform. Examples of information:
37
38* Capacity of hardware resources (such as processors and memory)
39* Platform power states
40* Available devices
41* BIOS versions
42
43You need a board configuration file to create scenario configurations. The
44board configuration is scenario-neutral by nature. Thus, multiple scenario
45configurations can be based on the same board configuration.
46
47You also need a board configuration file to build an ACRN hypervisor. The
48build process uses the file to build a hypervisor that can
49initialize and manage the platform at runtime.
50
51Scenario Configuration File
52===========================
53
54The scenario configuration file defines a working scenario by configuring
55hypervisor capabilities and defining VM attributes and resources. Examples of
56parameters:
57
58* Hypervisor capabilities
59
60  - Availability and settings of hypervisor features, such as debugging
61    facilities, scheduling algorithm, inter-VM shared memory (ivshmem),
62    and security features.
63  - Hardware management capacity of the hypervisor, such as maximum PCI devices
64    and maximum interrupt lines supported.
65  - Memory consumption of the hypervisor, such as the entry point and stack
66    size.
67
68* VM attributes and resources
69
70  - VM attributes, such as VM names.
71  - Maximum number of VMs supported.
72  - Resources allocated to each VM, such as number of vCPUs, amount of guest
73    memory, and pass-through devices.
74  - User VM settings, such as boot protocol and VM OS kernel parameters.
75  - Settings of virtual devices, such as virtual UARTs.
76
77You 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.
78
79For pre-launched User VMs, all attributes and resources are static
80configurations. The VM attributes and resources are exactly the amount of
81resources allocated to them.
82
83For post-launched User VMs, some resources are static configurations. Other
84resources are under the control of the Service VM and can be dynamically
85allocated to a VM via a launch script.
86
87.. _acrn_config_workflow:
88
89Using ACRN Configuration Toolset
90********************************
91
92The ACRN configuration toolset lets you create and edit configuration data. The
93toolset includes:
94
95* :ref:`Board Inspector <board_inspector_tool>`: Collects information from your
96  target machine and generates a board configuration file.
97* :ref:`ACRN Configurator <acrn_configurator_tool>`: Provides a graphical user
98  interface (GUI) for configuring your hypervisor and VM parameters, and
99  generates a scenario configuration file and launch scripts.
100
101As introduced in :ref:`overview_dev`, configuration takes place at
102:ref:`overview_dev_board_config` and :ref:`overview_dev_config_editor` in
103the overall development process:
104
105.. image:: ../getting-started/images/overview_flow-1-0.6x.png
106
107ACRN source also includes makefile targets to aid customization. See
108:ref:`hypervisor-make-options`.
109