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

doc: Update Configurator steps

Browse Source 
- Add build steps
- Update steps per new UI

Signed-off-by: Reyes, Amy <amy.reyes@intel.com>
This commit is contained in:
Reyes, Amy 2022-04-21 11:08:20 -07:00 committed by David Kinder
parent 69f8f6dcdc
commit ca3251a47d
1 changed files with 150 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

240
doc/getting-started/getting-started.rst
View File

@ -16,6 +16,8 @@ Service VM, and one post-launched User VM as illustrated in this figure:
Throughout this guide, you will be exposed to some of the tools, processes, and Throughout this guide, you will be exposed to some of the tools, processes, and
components of the ACRN project. Let's get started. components of the ACRN project. Let's get started.
.. _gsg-prereq:
Prerequisites Prerequisites
************** **************
@ -56,6 +58,8 @@ Before you begin, make sure your machines have the following prerequisites:
copying via USB disk, but you can use another method if you prefer) copying via USB disk, but you can use another method if you prefer)
- Local storage device (NVMe or SATA drive, for example) - Local storage device (NVMe or SATA drive, for example)
.. _gsg-target-hardware:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Set Up the Target Hardware Set Up the Target Hardware
@ -73,6 +77,8 @@ Example of a target system with cables connected:
.. image:: ./images/gsg_nuc.png .. image:: ./images/gsg_nuc.png
:scale: 25% :scale: 25%
.. _gsg-dev-computer:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Prepare the Development Computer Prepare the Development Computer
@ -148,12 +154,17 @@ To set up the ACRN build environment on the development computer:
sudo pip3 install lxml xmlschema defusedxml sudo pip3 install lxml xmlschema defusedxml
#. Create a working directory:
.. code-block:: bash
mkdir ~/acrn-work
#. Install the iASL compiler/disassembler used for advanced power management, #. Install the iASL compiler/disassembler used for advanced power management,
device discovery, and configuration (ACPI) within the host OS: device discovery, and configuration (ACPI) within the host OS:
.. code-block:: bash .. code-block:: bash
mkdir ~/acrn-work
cd ~/acrn-work cd ~/acrn-work
wget https://acpica.org/sites/acpica/files/acpica-unix-20210105.tar.gz wget https://acpica.org/sites/acpica/files/acpica-unix-20210105.tar.gz
tar zxvf acpica-unix-20210105.tar.gz tar zxvf acpica-unix-20210105.tar.gz
@ -170,10 +181,10 @@ To set up the ACRN build environment on the development computer:
cd ~/acrn-work cd ~/acrn-work
git clone https://github.com/projectacrn/acrn-hypervisor.git git clone https://github.com/projectacrn/acrn-hypervisor.git
cd acrn-hypervisor cd acrn-hypervisor
git checkout v2.7 git checkout acrn-2022w18.4-180000p
cd .. cd ..
git clone --depth 1 --branch release_2.7 https://github.com/projectacrn/acrn-kernel.git git clone --depth 1 --branch acrn-2022w18.4-180000p https://github.com/projectacrn/acrn-kernel.git
.. _gsg-board-setup: .. _gsg-board-setup:
@ -378,121 +389,162 @@ their attributes, and the resources they have access to.
A **launch script** is a shell script that is used to configure and create a A **launch script** is a shell script that is used to configure and create a
post-launched User VM. Each User VM has its own launch script. post-launched User VM. Each User VM has its own launch script.
To generate a scenario configuration file and launch script: First, you will install dependencies, build the ACRN Configurator Debian
package, and install it on your development computer. Then you will use the ACRN
Configurator to generate a scenario configuration file and launch script.
#. On the development computer, install ACRN Configurator dependencies: #. On the development computer, install the ACRN Configurator build tools:
.. code-block:: bash .. code-block:: bash
cd ~/acrn-work/acrn-hypervisor/misc/config_tools/config_app sudo apt install -y libwebkit2gtk-4.0-dev \
sudo pip3 install -r requirements build-essential \
curl \
wget \
libssl-dev \
libgtk-3-dev \
libappindicator3-dev \
librsvg2-dev \
python3-venv
#. Install Node.js (npm included) as follows:
a. We recommend using nvm to manage your Node.js runtime. It allows you to
switch versions and update Node.js easily.
.. code-block:: bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
#. Rerun your ``.bashrc`` initialization script and then install the latest
version of Node.js and npm:
.. code-block:: bash
source ~/.bashrc
nvm install node --latest-npm
nvm use node
#. Install and upgrade Yarn:
.. code-block:: bash
npm install --global yarn
#. Install rustup, the official installer for Rust:
.. code-block:: bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
When prompted by the Rust installation script, type ``1`` and press
:kbd:`Enter`.
.. code-block:: console
1) Proceed with installation (default)
2) Customize installation
3) Cancel installation
>1
#. Configure the current shell:
.. code-block:: bash
source $HOME/.cargo/env
#. Install additional ACRN Configurator dependencies:
.. code-block:: bash
cd ~/acrn-work/acrn-hypervisor/misc/config_tools
python3 -m pip install -r requirements.txt
cd configurator
python3 -m pip install -r requirements.txt
yarn
#. Build the ACRN Configurator Debian package:
.. code-block:: bash
cd ~/acrn-work/acrn-hypervisor
make configurator
#. Install the ACRN Configurator:
.. code-block:: bash
sudo apt install -y ~/acrn-work/acrn-hypervisor/build/acrn-configurator_*_amd64.deb
#. Launch the ACRN Configurator: #. Launch the ACRN Configurator:
.. code-block:: bash .. code-block:: bash
python3 acrn_configurator.py acrn-configurator
#. Your web browser should open the website `<http://127.0.0.1:5001/>`__ #. On the left-hand side, look for **Start a new configuration**.
automatically, or you may need to visit this website manually. Confirm that the working folder is ``<path to>/acrn-work/MyConfiguration``. Click **Use This Folder**.
The ACRN Configurator is supported on Chrome and Firefox.
#. Click the **Import Board XML** button and browse to the board configuration TODO add screenshots to Configurator steps
file ``my_board.xml`` previously generated. When it is successfully
imported, the board information appears.
Example:
.. image:: ./images/gsg_config_board.png #. Import your board configuration file as follows:
:class: drop-shadow
#. Generate the scenario configuration file: a. Under **Import a board configuration file**, click **Browse for file**.
a. Click the **Scenario Settings** menu on the top banner of the UI and #. Browse to ``~/acrn-work/my_board.xml`` and click **Open**.
select **Load a default scenario**. Example:
.. image:: ./images/gsg_config_scenario_default.png #. Click **Import Board File**.
:class: drop-shadow
#. In the dialog box, select **shared** as the default scenario setting and The ACRN Configurator makes a copy of your board file, changes the file
then click **OK**. This sample default scenario defines six User VMs. extension to ``.board.xml``, and saves the file to the working folder.
.. image:: ./images/gsg_config_scenario_load.png #. Create a new scenario as follows:
:class: drop-shadow
#. The scenario's configurable items appear. Feel free to look through all a. Under **Create new or import an existing scenario**, click **Create
the available configuration settings used in this sample scenario. This Scenario**.
is where you can change the sample scenario to meet your application's
particular needs. But for now, leave them as they're set in the
sample.
#. Click the **Export XML** button to save the scenario configuration file #. In the dialog box, confirm that **Shared (Post-launched VMs only)** is
that will be selected.
used in the build process.
#. In the dialog box, keep the default name as is. Type #. Confirm that one Service VM and one post-launched VM are selected.
``/home/<username>/acrn-work`` in the Scenario XML Path field. In the
following example, ``acrn`` is the username. Click **Submit** to save the
file.
.. image:: ./images/gsg_config_scenario_save.png #. Click **Create**.
:class: drop-shadow
#. Generate the launch script: #. Generate the scenario configuration file and launch script:
a. Click the **Launch Settings** menu on the top banner of the UI and select a. Under **Configure settings for scenario and launch scripts**, the
**Load a default launch script**. scenario's configurable items appear. Feel free to look through all the
available configuration settings. This is where you can change the
settings to meet your application's particular needs. But for now, you will update only a few settings to make this example work.
.. image:: ./images/gsg_config_launch_default.png #. Click the **VM1 Post-launched** tab to access the post-launched VM's
:class: drop-shadow settings.
#. In the dialog box, select **shared_launch_6user_vm** as the default launch #. Confirm that the Basic Parameters tab is selected, and scroll down to
setting and click **OK**. Because our sample ``shared`` scenario defines **Memory size (MB)**. Change the value to ``1024``. For this example, we
six User VMs, we're using this ``shared_launch_6user_vm`` launch XML will use Ubuntu 20.04 to boot the post-launched VM. Ubuntu 20.04 needs at
configuration. least 1024 MB to boot.
.. image:: ./images/gsg_config_launch_load.png #. Scroll down to **Virtio block device**, click **+**, and enter
:class: drop-shadow ``~/acrn-work/ubuntu-20.04.4-desktop-amd64.iso``. This parameter
Of the six User VMs, we will use User VM 3 and modify its default settings to run Ubuntu 20.04.
#. Scroll down, find **User VM 3**, and change the **mem_size** to **1024**.
Ubuntu 20.04 needs at least 1024 megabytes of memory to boot.
.. image:: ./images/gsg_config_mem.png
:class: drop-shadow
#. Under virtio_devices, change the **block** to
**/home/acrn/acrn-work/ubuntu-20.04.4-desktop-amd64.iso**. The parameter
specifies the VM's OS image and its location on the target system. Later specifies the VM's OS image and its location on the target system. Later
in this guide, you will save the ISO file to that directory. in this guide, you will save the ISO file to that directory.
.. image:: ./images/gsg_config_blk.png #. Click **Save Scenario And Launch Scripts** to generate the scenario
:class: drop-shadow configuration file and launch script.
#. Click the **Generate Launch Script** button. #. Click the **x** in the upper-right corner to close the ACRN
Configurator.
.. image:: ./images/gsg_config_launch_generate.png #. Confirm that the scenario configuration file ``scenario.xml`` appears in your
:class: drop-shadow ``acrn-work/MyConfiguration`` directory::
#. In the dialog box, type ``/home/<username>/acrn-work/`` in the Launch XML ls ~/acrn-work/MyConfiguration/scenario.xml
Path field. In the following example, ``acrn`` is the username. Click
**Submit** to save the script.
.. image:: ./images/gsg_config_launch_save.png #. Confirm that the launch script ``TODO`` appears in the
:class: drop-shadow
#. Close the browser and press :kbd:`CTRL` + :kbd:`C` to terminate the
``acrn_configurator.py`` program running in the terminal window.
#. Confirm that the scenario configuration file ``shared.xml`` appears in your
``acrn-work`` directory::
ls ~/acrn-work/shared.xml
#. Confirm that the launch script ``launch_user_vm_id3.sh`` appears in the
expected output directory:: expected output directory::
ls ~/acrn-work/my_board/output/launch_user_vm_id3.sh ls ~/acrn-work/MyConfiguration/TODO
.. _gsg_build: .. _gsg_build:
@ -506,7 +558,7 @@ Build ACRN
.. code-block:: bash .. code-block:: bash
cd ~/acrn-work/acrn-hypervisor cd ~/acrn-work/acrn-hypervisor
make clean && make BOARD=~/acrn-work/my_board.xml SCENARIO=~/acrn-work/shared.xml make clean && make BOARD=~/acrn-work/MyConfiguration/my_board.board.xml SCENARIO=~/acrn-work/MyConfiguration/scenario.xml
The build typically takes a few minutes. When done, the build generates a The build typically takes a few minutes. When done, the build generates a
Debian package in the ``./build`` directory: Debian package in the ``./build`` directory:
@ -515,7 +567,7 @@ Build ACRN
cd ./build cd ./build
ls *.deb ls *.deb
acrn-my_board-shared-2.7.deb acrn-my_board-shared-2.7.deb # TODO update file name
The Debian package contains the ACRN hypervisor and tools to ease installing The Debian package contains the ACRN hypervisor and tools to ease installing
ACRN on the target. ACRN on the target.
@ -561,7 +613,7 @@ Build ACRN
.. code-block:: bash .. code-block:: bash
disk="/media/$USER/"$(ls /media/$USER) disk="/media/$USER/"$(ls /media/$USER)
cp ~/acrn-work/acrn-hypervisor/build/acrn-my_board-shared-2.7.deb "$disk"/ cp ~/acrn-work/acrn-hypervisor/build/acrn-my_board-shared-2.7.deb "$disk"/ # TODO update file name
cp ~/acrn-work/*acrn-service-vm*.deb "$disk"/ cp ~/acrn-work/*acrn-service-vm*.deb "$disk"/
cp ~/acrn-work/my_board/output/launch_user_vm_id3.sh "$disk"/ cp ~/acrn-work/my_board/output/launch_user_vm_id3.sh "$disk"/
cp ~/acrn-work/acpica-unix-20210105/generate/unix/bin/iasl "$disk"/ cp ~/acrn-work/acpica-unix-20210105/generate/unix/bin/iasl "$disk"/
@ -576,12 +628,14 @@ Build ACRN
.. code-block:: bash .. code-block:: bash
disk="/media/$USER/"$(ls /media/$USER) disk="/media/$USER/"$(ls /media/$USER)
cp "$disk"/acrn-my_board-shared-2.7.deb ~/acrn-work cp "$disk"/acrn-my_board-shared-2.7.deb ~/acrn-work # TODO update file name
cp "$disk"/*acrn-service-vm*.deb ~/acrn-work cp "$disk"/*acrn-service-vm*.deb ~/acrn-work
cp "$disk"/launch_user_vm_id3.sh ~/acrn-work cp "$disk"/launch_user_vm_id3.sh ~/acrn-work
sudo cp "$disk"/iasl /usr/sbin/ sudo cp "$disk"/iasl /usr/sbin/
sync && sudo umount "$disk" sync && sudo umount "$disk"
.. _gsg-install-acrn:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Install ACRN Install ACRN
@ -593,7 +647,7 @@ Install ACRN
.. code-block:: bash .. code-block:: bash
cd ~/acrn-work cd ~/acrn-work
sudo apt install ./acrn-my_board-shared-2.7.deb sudo apt install ./acrn-my_board-shared-2.7.deb # TODO update file name
sudo apt install ./*acrn-service-vm*.deb sudo apt install ./*acrn-service-vm*.deb
#. Reboot the system: #. Reboot the system:
@ -615,6 +669,8 @@ Install ACRN
UEFI Firmware Settings UEFI Firmware Settings
*ACRN multiboot2 *ACRN multiboot2
.. _gsg-run-acrn:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Run ACRN and the Service VM Run ACRN and the Service VM
@ -639,6 +695,8 @@ The ACRN hypervisor boots the Ubuntu Service VM automatically.
[ 0.000000] Hypervisor detected: ACRN [ 0.000000] Hypervisor detected: ACRN
.. _gsg-user-vm:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Launch the User VM Launch the User VM
@ -655,8 +713,8 @@ Launch the User VM
.. code-block:: bash .. code-block:: bash
sudo chmod +x ~/acrn-work/launch_user_vm_id3.sh sudo chmod +x ~/acrn-work/launch_user_vm_id3.sh # TODO update file name
sudo ~/acrn-work/launch_user_vm_id3.sh sudo ~/acrn-work/launch_user_vm_id3.sh # TODO update file name
#. It may take about one minute for the User VM to boot and start running the #. It may take about one minute for the User VM to boot and start running the
Ubuntu image. You will see a lot of output, then the console of the User VM Ubuntu image. You will see a lot of output, then the console of the User VM
@ -723,6 +781,8 @@ Launch the User VM
sudo poweroff sudo poweroff
.. _gsg-next-steps:
Next Steps Next Steps
************** **************