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

doc: discourage modifications to predefined scenario XMLs

Browse Source 
This patch modifies the instructions that lead users to modify predefined
scenario XMLs under ``misc/config_tools/data`` which is not a preferred
way. It is recommended to make and edit a local copy, instead.

Also fixes a few references to ``misc/vm_configs`` which has been moved.

v2:
 * fix typos in paths
 * explain on the candidate values of ``port_base`` and ``irq`` fields

Tracked-On: #5644
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
This commit is contained in:
Junjie Mao 2021-03-04 14:12:29 +08:00 committed by fitchbe
parent c0da58c7ec
commit 42fd1b1d5c
4 changed files with 34 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/developer-guides/hld/vuart-virt-hld.rst
View File

@ -95,9 +95,11 @@ Usage
- For console vUART
To enable the console port for a VM, change the
port_base and IRQ in ``misc/vm_configs/scenarios/<scenario
name>/vm_configurations.c``. If the IRQ number has been used in your
To enable the console port for a VM, change the ``port_base`` and ``irq``
fields in
``configs/scenarios/<scenario name>/vm_configurations.c`` under the
hypervisor build directory using the combinations listed below. If the IRQ
number has been used in your
system ( ``cat /proc/interrupt``), you can choose other IRQ number. Set
the ``.irq =0``, the vUART will work in polling mode.

11
doc/introduction/index.rst
View File

@ -93,13 +93,11 @@ above, i.e. the *logical partitioning*, *sharing*, and *hybrid* modes. They
further specify the number of VMs that can be run, their attributes and the
resources they have access to, either shared with other VMs or exclusively.
The predefined scenarios are in the
:acrn_file:`misc/vm_configs/scenarios` folder
in the source code. XML examples for some platforms can also be found under
:acrn_file:`misc/vm_configs/xmls/config-xmls`.
The predefined scenarios are in the :acrn_file:`misc/config_tools/data` folder
in the source code.
The :ref:`acrn_configuration_tool` tutorial explains how to use the ACRN
Configuration tool to create your own scenario or modify an existing one.
configuration toolset to create your own scenario or modify an existing one.
Industrial Workload Consolidation
=================================
@ -423,7 +421,8 @@ The Boot process proceeds as follows:
In this boot mode, the boot options of pre-launched VM and service VM are defined
in the variable of ``bootargs`` of struct ``vm_configs[vm id].os_config``
in the source code ``misc/vm_configs/$(SCENARIO)/vm_configurations.c`` by default.
in the source code ``configs/scenarios/$(SCENARIO)/vm_configurations.c`` (which
resides under the hypervisor build directory) by default.
Their boot options can be overridden by the GRUB menu. See :ref:`using_grub` for
details. The boot options of a post-launched VM are not covered by hypervisor
source code or a GRUB menu; they are defined in a guest image file or specified by

40
doc/tutorials/enable_ivshmem.rst
View File

@ -38,12 +38,11 @@ where
Ivshmem HV-Land Usage
*********************
The ``ivshmem`` hv-land solution is disabled by default in ACRN. You
enable it using the :ref:`acrn_configuration_tool` with these steps:
The ``ivshmem`` hv-land solution is disabled by default in ACRN. You can enable
it using the :ref:`ACRN configuration toolset <acrn_config_workflow>` with these
steps:
- Enable ``ivshmem`` hv-land in ACRN XML configuration file. For example, the
XML configuration file for the hybrid_rt scenario on a whl-ipc-i5 board is found in
``acrn-hypervisor/misc/vm_configs/xmls/config-xmls/whl-ipc-i5/hybrid_rt.xml``
- Enable ``ivshmem`` hv-land in ACRN XML configuration file.
- Edit ``IVSHMEM_ENABLED`` to ``y`` in ACRN scenario XML configuration
to enable ``ivshmem`` hv-land
@ -66,7 +65,7 @@ enable it using the :ref:`acrn_configuration_tool` with these steps:
.. note:: You can define up to eight ``ivshmem`` hv-land shared regions.
- Build the XML configuration, refer to :ref:`getting-started-building`
- Build with the XML configuration, refer to :ref:`getting-started-building`.
Ivshmem Notification Mechanism
******************************
@ -173,28 +172,23 @@ HV-Land Example
This example uses hv-land inter-VM communication between two
Linux-based VMs (VM0 is a pre-launched VM and VM2 is a post-launched VM).
1. Configure shared memory for the communication between VM0 and VM2 for hybrid_rt
scenario on whl-ipc-i5 board, the shared memory name is ``hv:/shm_region_0``,
and shared memory size is 2M bytes:
1. Make a copy of the predefined hybrid_rt scenario on whl-ipc-i5 (available at
``acrn-hypervisor/misc/config_tools/data/whl-ipc-i5/hybrid_rt.xml``) and
configure shared memory for the communication between VM0 and VM2. The shared
memory name is ``hv:/shm_region_0``, and shared memory size is 2M bytes. The
resulting scenario XML should look like this:
- Edit XML configuration file for hybrid_rt scenario on whl-ipc-i5 board
``acrn-hypervisor/misc/config_tools/data/whl-ipc-i5/hybrid_rt.xml``
to enable ``ivshmem`` and configure the shared memory region using the format
``shm_name, shm_size, VM IDs`` (as described above in the ACRN dm boot parameters).
The region name must start with ``hv:/`` for an hv-land shared region, and we'll allocate 2MB
shared between VMs 0 and 2:
.. code-block:: none
:emphasize-lines: 2,3
.. code-block:: none
:emphasize-lines: 2,3
<IVSHMEM desc="IVSHMEM configuration">
<IVSHMEM_ENABLED>y</IVSHMEM_ENABLED>
<IVSHMEM_REGION>hv:/shm_region_0, 2, 0:2</IVSHMEM_REGION>
</IVSHMEM>
<IVSHMEM desc="IVSHMEM configuration">
<IVSHMEM_ENABLED>y</IVSHMEM_ENABLED>
<IVSHMEM_REGION>hv:/shm_region_0, 2, 0:2</IVSHMEM_REGION>
</IVSHMEM>
2. Build ACRN based on the XML configuration for hybrid_rt scenario on whl-ipc-i5 board::
make BOARD=whl-ipc-i5 SCENARIO=hybrid_rt TARGET_DIR=xxx
make BOARD=whl-ipc-i5 SCENARIO=<path/to/edited/scenario.xml> TARGET_DIR=xxx
3. Add a new virtual PCI device for VM2 (post-launched VM): the device type is
``ivshmem``, shared memory name is ``hv:/shm_region_0``, and shared memory

28
doc/tutorials/vuart_configuration.rst
View File

@ -10,24 +10,9 @@ The virtual universal asynchronous receiver/transmitter (vUART) supports
two functions: one is the console, the other is communication. vUART
only works on a single function.
Currently, only two vUART configurations are added to the
``misc/vm_configs/scenarios/<xxx>/vm_configuration.c`` file, but you can
change the value in it.
.. code-block:: none
.vuart[0] = {
.type = VUART_LEGACY_PIO,
.addr.port_base = INVALID_COM_BASE,
},
.vuart[1] = {
.type = VUART_LEGACY_PIO,
.addr.port_base = INVALID_COM_BASE,
}
``vuart[0]`` is initiated as the **console** port.
``vuart[1]`` is initiated as a **communication** port.
Currently, only two vUART configurations are added to the predefined scenarios,
but you can customize the scenarios to enable more using the :ref:`ACRN
configuration toolset <acrn_config_workflow>`
Console Enable List
===================
@ -266,8 +251,8 @@ vUART settings. Configuration tools will override your settings in
and :ref:`How to Configure a Communication Port
<how-to-configure-a-communication-port>`.
You can configure both Legacy vUART and PCI-vUART in
``./misc/config_tools/data/<board>/<scenario>.xml``. For
You can configure both Legacy vUART and PCI-vUART in :ref:`scenario
configurations <acrn_config_types>`. For
example, if VM0 has a legacy vUART0 and a PCI-vUART1, VM1 has no legacy
vUART but has a PCI-vUART0 and a PCI-vUART1, VM0's PCI-vUART1 and VM1's
PCI-vUART1 are connected to each other. You should configure then like this:
@ -338,7 +323,8 @@ Run the command to build ACRN with this XML configuration file::
The configuration tools will test your settings, and check :ref:`vUART
Rules <index-of-vuart>` for compilation issue. After compiling, you can find
the generated sources under ``build/configs/scenarios/<scenario>/pci_dev.c``
the generated sources under
``build/hypervisor/configs/scenarios/<scenario>/pci_dev.c``
which is based on the XML settings, something like:
.. code-block:: none