1.. _acrn_configurator_tool: 2 3ACRN Configurator Tool 4###################### 5 6This guide describes all features and uses of the tool. 7 8About the ACRN Configurator Tool 9********************************* 10 11The ACRN Configurator provides a user interface to help 12you customize your :ref:`ACRN configuration <acrn_configuration_tool>`. 13Capabilities: 14 15* Reads board information from the board configuration file generated by the 16 :ref:`board_inspector_tool` 17* Helps you configure a scenario of hypervisor and VM settings 18* Generates a scenario configuration file that stores the configured settings in 19 XML format 20* Generates a launch script for each post-launched User VM 21 22.. _acrn_configurator_tool_prerequisites: 23 24Prerequisites 25************* 26 27This guide assumes you have a board configuration file and have successfully 28launched the ACRN Configurator. For steps, see the following Getting Started 29Guide sections: 30 31* :ref:`gsg-dev-computer` 32* :ref:`gsg-board-setup` 33* :ref:`gsg-dev-setup` 34 35The above Getting Started Guide steps use a prebuilt Debian package to install 36the ACRN Configurator. :ref:`acrn_configurator_tool_source` describes how to 37build the Debian package. 38 39Scenario Error Checking 40*********************** 41 42The Configurator includes many validation checks that verify input values, 43ensure the consistency of configuration options, and interactions between 44options. 45 46Simple data validation checks on values are detected immediately with red 47text indicating the problem, or with an indicator within a data entry field. For 48example, if you type in a value that is out of range, you'll see your value 49crossed out: 50 51.. image:: images/config-out-of-range-error.png 52 :align: center 53 :class: drop-shadow 54 55If you delete a required value, you'll see an error message in red text: 56 57.. image:: images/config-required-value-error.png 58 :align: center 59 :class: drop-shadow 60 61More complex checks, including those that look for conflicting settings, are 62done when you initially open a saved (or newly created) scenario, or when you 63use the "Save Scenario" button. If problems are detected, the response window 64from the save action will indicate that problems were found. The Hypervisor or 65VM tabs will then display an error icon leading you to the configuration option 66panels where you can resolve the errors. For example, both the Hypervisor and 67VM1 tabs indicate an option setting problem: 68 69.. image:: images/config-tab-errors.png 70 :align: center 71 :class: drop-shadow 72 73Since we're on the Hypervisor (Basic Parameters) options, we see the Hypervisor 74configuration error message. If we click the VM1 tab, we'll see what the 75issues are with that VM's configuration options: 76 77.. image:: images/config-tab-errors2.png 78 :align: center 79 :class: drop-shadow 80 81In both cases, you can scroll down to see the specific problem (on either the 82basic or advanced parameters tab) and fix the issues. 83When all issues are resolved, click the "Save Scenario" button to 84validate the changes and save the settings. If all issues were resolved, the 85save scenario response window will indicate that no issues were found, and all 86the error indicators will be cleared. 87 88Start with a New or Existing Configuration 89****************************************** 90 91When the ACRN Configurator opens, the introduction screen appears. 92 93.. image:: images/configurator-intro.png 94 :align: center 95 :class: drop-shadow 96 97The introduction screen lets you start a new configuration or use an existing 98one by selecting a working folder. 99 100As described in :ref:`acrn_configuration_tool`, a configuration defines one 101ACRN instance, and its data is stored in a set of configuration files: 102 103* One board configuration file 104* One scenario configuration file 105* One launch script per post-launched VM 106 107When you use the ACRN Configurator, it saves these files in the selected working 108folder. 109 110Each configuration must have a unique working folder. For example, imagine you 111want to create three configurations. Perhaps you want to create a configuration 112for three different boards, or you have one board but want to create three sets 113of hypervisor settings to test on it. You would need to select a different 114working folder for each configuration. After you have selected the working 115folder in the ACRN Configurator, it saves the configuration files there. The 116following figure shows an example file system consisting of a top-level folder, 117``acrn-work``, and a working folder for each configuration, ``ConfigA``, 118``ConfigB``, and ``ConfigC``. 119 120.. image:: images/config-file.png 121 :align: center 122 123Start a New Configuration 124========================== 125 126You can start by selecting a new working folder. The tool assumes you are 127starting from scratch. It checks the folder for existing configuration files, 128such as a board configuration file, scenario configuration file, and launch 129scripts. If it finds any, it will delete them. 130 1311. Under **Start a new configuration**, use the displayed working folder or 132 select a different folder by clicking **Browse for folder**. Use a 133 folder name that is meaningful to you. 134 135 .. image:: images/configurator-newconfig.png 136 :align: center 137 :class: drop-shadow 138 139#. If the folder contains configuration files, the tool displays a message about 140 deleting the files. Click **OK** to delete the files. 141 142#. Click **Use This Folder**. 143 144Use an Existing Configuration 145============================= 146 147You can use an existing configuration by selecting a working folder that has one 148or more configuration files in it. For example, the folder can contain a board 149configuration file alone, or a board configuration file and scenario 150configuration file. The tool uses the information in the files to populate the 151UI, so that you can continue working on the configuration where you left off. 152 1531. Under **Use an existing configuration**, use the displayed working folder or 154 select a different folder by clicking **Browse for folder**. 155 156 .. image:: images/configurator-exconfig.png 157 :align: center 158 :class: drop-shadow 159 160#. Click **Open Folder**. 161 162Navigate the Configuration Screen 163********************************* 164 165After you have selected a working folder, the tool opens the second (and final) 166screen, where you can customize your configuration. The following figure shows 167an example: 168 169.. image:: images/configurator-configscreen.png 170 :align: center 171 :class: drop-shadow 172 173At the top of the screen, the tool shows the selected working folder. To return 174to the introduction screen, click the arrow next to the working folder path: 175 176.. image:: images/configurator-backintro.png 177 :align: center 178 :class: drop-shadow 179 180The rest of the configuration screen is divided into three panels: 181 1821. Import a board configuration file 183#. Create new or import an existing scenario 184#. Configure settings for scenario and launch scripts 185 186The panels are labeled 1, 2, and 3 to guide you through the configuration steps. 187The tool also enforces this order of operation by enabling each panel only after 188you have completed the preceding panel. 189 190The title bar of each panel has an arrow icon. Click the icon to expand 191or collapse the panel. 192 193.. image:: images/configurator-expand.png 194 :align: center 195 :class: drop-shadow 196 197Import a Board Configuration File 198********************************** 199 200The first step in the configuration process is to import the board configuration 201file generated via the :ref:`board_inspector_tool`. You can import a board configuration file for the first time, or replace the existing file. 202 203Import a Board Configuration File for the First Time 204==================================================== 205 206If the working folder doesn't have a board configuration file, the tool shows 207that no board information has been imported yet. 208 209To import a board configuration file for the first time: 210 2111. Under **Import a board configuration file**, select a 212 file from the drop-down menu or click **Browse for file** to select a 213 different file. 214 215 .. image:: images/configurator-board01.png 216 :align: center 217 :class: drop-shadow 218 219#. Click **Import Board File**. 220 221The tool makes a copy of your board configuration file, changes the 222file extension to ``.board.xml``, and saves the file in the working folder. 223 224The tool displays the current board information. Example: 225 226.. image:: images/configurator-board02.png 227 :align: center 228 :class: drop-shadow 229 230Replace an Existing Board Configuration File 231============================================ 232 233After a board configuration file has been imported, you can choose to replace it 234at any time. This option is useful, for example, when you need to change your 235board's configuration while you are customizing your hypervisor settings. 236Whenever you change the configuration of your board, you must generate a new 237board configuration file via the :ref:`board_inspector_tool`. Examples include 238changing any BIOS setting such as hyper-threading, adding or removing a physical 239device, or adding or removing memory. If this happens after you've started 240customizing your hypervisor in the ACRN Configurator, you can import the new 241board file into your existing configuration and continue editing. 242 243To replace an existing board configuration file: 244 2451. Under **Import a board configuration file**, click **Use a Different Board**. 246 247 .. image:: images/configurator-board03.png 248 :align: center 249 :class: drop-shadow 250 251#. Browse to the board configuration file and click **Open**. 252 253#. The tool displays a warning message about overwriting the existing file. 254 Click **Ok** to proceed. 255 256The tool replaces the file and displays the new board information. 257 258Create New or Import an Existing Scenario 259******************************************* 260 261After importing the board configuration file, the next step is to specify an 262initial scenario. You can create a scenario, or import an existing scenario 263configuration file. In both cases, this step is a starting point for configuring 264your hypervisor and VMs. Later, you can choose to change the configuration, such 265as adding or deleting VMs. 266 267Create a Scenario 268================= 269 270You can create a scenario by specifying an initial number of VMs. 271 2721. Under **Create new or import an existing scenario**, click **Create 273 Scenario**. 274 275 .. image:: images/configurator-newscenario01.png 276 :align: center 277 :class: drop-shadow 278 279#. In the dialog box, select a scenario type and number of VMs. The tool 280 enforces dependencies. For example, a scenario with post-launched VMs must 281 have a Service VM, so the tool adds a Service VM and doesn't allow you to 282 delete it here. 283 284 .. image:: images/configurator-newscenario02.png 285 :align: center 286 :class: drop-shadow 287 288#. Click **Ok**. 289 290The tool displays the name of the scenario configuration file, but it doesn't 291save it to the working folder until you click **Save Scenario And Launch 292Scripts** in the third panel. 293 294Import a Scenario Configuration File 295==================================== 296 297You can import an existing scenario configuration file. The tool uses the 298information in the file to populate the UI, so that you can continue working on 299the configuration where you left off. 300 3011. Due to the strict validation ACRN adopts, scenario configuration files for a 302 former release may not work in the current release unless they are upgraded. 303 Starting from v3.0, upgrade an older scenario XML per the steps in 304 :ref:`upgrading_configuration` then import the upgraded file into the tool in 305 the next step. 306 307#. Under **Create new or import an existing scenario**, go to the right side of 308 the screen and select a scenario configuration file from the drop-down menu 309 or click **Browse for scenario file** to select a different file. 310 311 .. image:: images/configurator-exscenario.png 312 :align: center 313 :class: drop-shadow 314 315#. Click **Import Scenario**. 316 317The tool displays the name of the scenario configuration file, but it doesn't 318save it to the working folder until you click **Save Scenario And Launch 319Scripts** in the third panel. 320 321Configure Settings for Scenario and Launch Scripts 322************************************************** 323 324After creating a scenario or importing an existing one, you can configure 325hypervisor and VM parameters, as well as add or delete VMs. 326 327Configure the Hypervisor and VM Parameters 328========================================== 329 3301. Click the hypervisor or VM tab in the selector menu. The selected tab is 331 darker in color. 332 333 .. image:: images/configurator-selecthypervisor.png 334 :align: center 335 :class: drop-shadow 336 337#. Click the Basic Parameters tab or Advanced Parameters tab and make updates. 338 To learn more about each parameter, hover over the |tooltip| icon for a short 339 description or go to :ref:`scenario-config-options` for documentation. 340 341 .. |tooltip| image:: images/tooltip.png 342 343Basic parameters are generally defined as: 344 345* Parameters that are necessary for ACRN configuration, compilation, and 346 execution. 347 348* Parameters that are common for software like ACRN. 349 350* Parameters that are anticipated to be commonly used for typical ACRN use 351 cases. 352 353Advanced parameters are generally defined as: 354 355* Parameters that are optional for ACRN configuration, compilation, and 356 execution. Default values cover most use cases. 357 358* Parameters that are used for fine-grained tuning, such as reducing code 359 lines or optimizing performance. 360 361Add a VM 362========= 363 364In the selector menu, click **+** to add a pre-launched VM or post-launched VM. 365 366.. image:: images/configurator-addvm.png 367 :align: center 368 :class: drop-shadow 369 370Delete a VM 371============ 372 3731. In the selector menu, click the VM tab. The selected tab is darker in color. 374 375#. Click **Delete VM**. 376 377 .. image:: images/configurator-deletevm.png 378 :align: center 379 :class: drop-shadow 380 381Save and Check for Errors 382========================= 383 384#. To save your configuration, click **Save Scenario And Launch Scripts** at the 385 top of the panel. 386 387 .. image:: images/configurator-save.png 388 :align: center 389 :class: drop-shadow 390 391 The tool validates hypervisor and VM settings whenever you save. 392 393 If no errors occur, the tool saves your configuration data in a set of files 394 in the working folder: 395 396 * Scenario configuration file (``scenario.xml``): Raw format of all 397 hypervisor and VM settings. You will need this file to build ACRN. 398 399 * One launch script per post-launched VM (``launch_user_vm_id*.sh``): This 400 file is used to start the post-launched VM in the Service VM. You can find 401 the VM's name inside the script: 402 403 .. code-block:: bash 404 405 # Launch script for VM name: <name> 406 407 If an error occurs, such as an empty required field, the tool saves the 408 changes to the scenario configuration file, but prompts you to correct the 409 error. 410 411#. On the selector menu, check for error messages on all tabs that have an error 412 icon. The following figure shows that the Hypervisor tab and the VM1 tab 413 contain errors. 414 415 .. image:: images/configurator-erroricon.png 416 :align: center 417 :class: drop-shadow 418 419 Error messages appear below the selector menu or below the applicable 420 parameter. 421 422#. Fix all errors and save again to generate a valid configuration. 423 424#. Click the **x** in the upper-right corner to close the ACRN Configurator. 425 426Next Steps 427========== 428 429After generating a valid scenario configuration file, you can build ACRN. See 430:ref:`gsg_build`. 431 432.. _acrn_configurator_tool_source: 433 434Build ACRN Configurator from Source Code 435***************************************** 436 437The :ref:`prerequisites<acrn_configurator_tool_prerequisites>` use a prebuilt 438Debian package to install the ACRN Configurator. The following steps describe 439how to build the Debian package from source code. 440 441#. On the development computer, complete the steps in :ref:`gsg-dev-computer`. 442 443#. Install the ACRN Configurator build tools: 444 445 .. code-block:: bash 446 447 sudo apt install -y build-essential \ 448 curl \ 449 wget \ 450 libssl-dev \ 451 libgtk-3-dev \ 452 librsvg2-dev \ 453 python3-venv 454 455 cd /tmp/ 456 wget http://security.ubuntu.com/ubuntu/pool/main/w/webkit2gtk/libwebkit2gtk-4.0-37_2.44.2-0ubuntu0.22.04.1_amd64.deb http://mirrors.kernel.org/ubuntu/pool/main/i/icu/libicu70_70.1-2_amd64.deb http://security.ubuntu.com/ubuntu/pool/main/w/webkit2gtk/libjavascriptcoregtk-4.0-18_2.44.2-0ubuntu0.22.04.1_amd64.deb 457 sudo apt install ./libwebkit2gtk-4.0-37_2.44.2-0ubuntu0.22.04.1_amd64.deb ./libicu70_70.1-2_amd64.deb ./libjavascriptcoregtk-4.0-18_2.44.2-0ubuntu0.22.04.1_amd64.deb 458 459#. Install Node.js (npm included) as follows: 460 461 a. We recommend using nvm to manage your Node.js runtime. It allows you to 462 switch versions and update Node.js easily. 463 464 .. code-block:: bash 465 466 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash 467 468 #. Rerun your ``.bashrc`` initialization script and then install the latest 469 version of Node.js and npm: 470 471 .. code-block:: bash 472 473 source ~/.bashrc 474 nvm install node --latest-npm 475 nvm use node 476 477#. Install and upgrade Yarn: 478 479 .. code-block:: bash 480 481 npm install --global yarn 482 483#. Install rustup, the official installer for Rust: 484 485 .. code-block:: bash 486 487 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 488 489 When prompted by the Rust installation script, type ``1`` and press 490 :kbd:`Enter`. 491 492 .. code-block:: console 493 494 1) Proceed with installation (default) 495 2) Customize installation 496 3) Cancel installation 497 >1 498 499#. Configure the current shell: 500 501 .. code-block:: bash 502 503 source $HOME/.cargo/env 504 505#. Install additional ACRN Configurator dependencies: 506 507 .. code-block:: bash 508 509 cd ~/acrn-work/acrn-hypervisor/misc/config_tools/configurator 510 python3 -m pip install -r requirements.txt 511 yarn 512 513#. Build the ACRN Configurator Debian package: 514 515 .. code-block:: bash 516 517 cd ~/acrn-work/acrn-hypervisor 518 make configurator 519 520#. Install the ACRN Configurator: 521 522 .. code-block:: bash 523 524 sudo apt install -y ~/acrn-work/acrn-hypervisor/build/acrn-configurator*.deb 525 526#. Launch the ACRN Configurator: 527 528 .. code-block:: bash 529 530 acrn-configurator 531
