github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-09-10 21:29:20 +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
Download Patch File Download Diff File Expand all files Collapse all files

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