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

doc: update documentation for configuring ACRN RDT features

Browse Source 
Given the recent changes in the way ACRN configures RDT features,
this patch updates the documentation as well to provide clear
guidelines to the user.

Tracked-On: #5063
Signed-off-by: Vijay Dhanraj <vijay.dhanraj@intel.com>
This commit is contained in:
Vijay Dhanraj 2020-07-20 10:16:31 -07:00 committed by David Kinder
parent a524148ca1
commit cd1b133ac5
3 changed files with 96 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
doc/developer-guides/hld/hv-rdt.rst
View File

@ -38,58 +38,36 @@ IA32_PQR_ASSOC MSR to CLOS 0. (Note that CLOS, or Class of Service, is a
resource allocator.) The user can check the cache capabilities such as cache resource allocator.) The user can check the cache capabilities such as cache
mask and max supported CLOS as described in :ref:`rdt_detection_capabilities` mask and max supported CLOS as described in :ref:`rdt_detection_capabilities`
and then program the IA32_type_MASK_n and IA32_PQR_ASSOC MSR with a and then program the IA32_type_MASK_n and IA32_PQR_ASSOC MSR with a
CLOS ID, to select a cache mask to take effect. ACRN uses CLOS ID, to select a cache mask to take effect. These configurations can be
VMCS MSR loads on every VM Entry/VM Exit for non-root and root modes to done in scenario xml file under ``FEATURES`` section as shown in the below example.
enforce the settings. ACRN uses VMCS MSR loads on every VM Entry/VM Exit for non-root and root modes
to enforce the settings.
.. code-block:: none .. code-block:: none
:emphasize-lines: 3,7,11,15 :emphasize-lines: 2,4
struct platform_clos_info platform_l2_clos_array[MAX_PLATFORM_CLOS_NUM] = { <RDT desc="Intel RDT (Resource Director Technology).">
{ <RDT_ENABLED desc="Enable RDT">y</RDT_ENABLED>
.clos_mask = 0xff, <CDP_ENABLED desc="CDP (Code and Data Prioritization). CDP is an extension of CAT.">n</CDP_ENABLED>
.msr_index = MSR_IA32_L3_MASK_BASE + 0, <CLOS_MASK desc="Cache Capacity Bitmask">0xF</CLOS_MASK>
},
{ Once the cache mask is set of each individual CPU, the respective CLOS ID
.clos_mask = 0xff, needs to be set in the scenario xml file under ``VM`` section. If user desires
.msr_index = MSR_IA32_L3_MASK_BASE + 1, to use CDP feature, CDP_ENABLED should be set to ``y``.
},
{
.clos_mask = 0xff,
.msr_index = MSR_IA32_L3_MASK_BASE + 2,
},
{
.clos_mask = 0xff,
.msr_index = MSR_IA32_L3_MASK_BASE + 3,
},
};
.. code-block:: none .. code-block:: none
:emphasize-lines: 6 :emphasize-lines: 2
struct acrn_vm_config vm_configs[CONFIG_MAX_VM_NUM] __aligned(PAGE_SIZE) = { <clos desc="Class of Service for Cache Allocation Technology. Please refer SDM 17.19.2 for details and use with caution.">
{ <vcpu_clos>0</vcpu_clos>
.type = SOS_VM,
.name = SOS_VM_CONFIG_NAME,
.guest_flags = 0UL,
.clos = 0,
.memory = {
.start_hpa = 0x0UL,
.size = CONFIG_SOS_RAM_SIZE,
},
.os_config = {
.name = SOS_VM_CONFIG_OS_NAME,
},
},
};
.. note:: .. note::
ACRN takes the lowest common CLOS max value between the supported ACRN takes the lowest common CLOS max value between the supported
resources and sets the MAX_PLATFORM_CLOS_NUM. For example, if max CLOS resources as maximum supported CLOS ID. For example, if max CLOS
supported by L3 is 16 and L2 is 8, ACRN programs MAX_PLATFORM_CLOS_NUM to supported by L3 is 16 and MBA is 8, ACRN programs MAX_PLATFORM_CLOS_NUM
8. ACRN recommends consistent capabilities across all RDT to 8. ACRN recommends to have consistent capabilities across all RDT
resources by using the common subset CLOS. This is done in order to resources by using a common subset CLOS. This is done in order to minimize
minimize misconfiguration errors. misconfiguration errors.
Objective of MBA Objective of MBA
@ -128,53 +106,31 @@ that corresponds to each CLOS and then setting IA32_PQR_ASSOC MSR with CLOS
users can check the MBA capabilities such as mba delay values and users can check the MBA capabilities such as mba delay values and
max supported CLOS as described in :ref:`rdt_detection_capabilities` and max supported CLOS as described in :ref:`rdt_detection_capabilities` and
then program the IA32_MBA_MASK_n and IA32_PQR_ASSOC MSR with the CLOS ID. then program the IA32_MBA_MASK_n and IA32_PQR_ASSOC MSR with the CLOS ID.
ACRN uses VMCS MSR loads on every VM Entry/VM Exit for non-root and root These configurations can be done in scenario xml file under ``FEATURES`` section
modes to enforce the settings. as shown in the below example. ACRN uses VMCS MSR loads on every VM Entry/VM Exit
for non-root and root modes to enforce the settings.
.. code-block:: none .. code-block:: none
:emphasize-lines: 3,7,11,15 :emphasize-lines: 2,5
struct platform_clos_info platform_mba_clos_array[MAX_PLATFORM_CLOS_NUM] = { <RDT desc="Intel RDT (Resource Director Technology).">
{ <RDT_ENABLED desc="Enable RDT">y</RDT_ENABLED>
.mba_delay = 0, <CDP_ENABLED desc="CDP (Code and Data Prioritization). CDP is an extension of CAT.">n</CDP_ENABLED>
.msr_index = MSR_IA32_MBA_MASK_BASE + 0, <CLOS_MASK desc="Cache Capacity Bitmask"></CLOS_MASK>
}, <MBA_DELAY desc="Memory Bandwidth Allocation delay value">0</MBA_DELAY>
{
.mba_delay = 0, Once the cache mask is set of each individual CPU, the respective CLOS ID
.msr_index = MSR_IA32_MBA_MASK_BASE + 1, needs to be set in the scenario xml file under ``VM`` section.
},
{
.mba_delay = 0,
.msr_index = MSR_IA32_MBA_MASK_BASE + 2,
},
{
.mba_delay = 0,
.msr_index = MSR_IA32_MBA_MASK_BASE + 3,
},
};
.. code-block:: none .. code-block:: none
:emphasize-lines: 6 :emphasize-lines: 2
struct acrn_vm_config vm_configs[CONFIG_MAX_VM_NUM] __aligned(PAGE_SIZE) = { <clos desc="Class of Service for Cache Allocation Technology. Please refer SDM 17.19.2 for details and use with caution.">
{ <vcpu_clos>0</vcpu_clos>
.type = SOS_VM,
.name = SOS_VM_CONFIG_NAME,
.guest_flags = 0UL,
.clos = 0,
.memory = {
.start_hpa = 0x0UL,
.size = CONFIG_SOS_RAM_SIZE,
},
.os_config = {
.name = SOS_VM_CONFIG_OS_NAME,
},
},
};
.. note:: .. note::
ACRN takes the lowest common CLOS max value between the supported ACRN takes the lowest common CLOS max value between the supported
resources and sets the MAX_PLATFORM_CLOS_NUM. For example, if max CLOS resources as maximum supported CLOS ID. For example, if max CLOS
supported by L3 is 16 and MBA is 8, ACRN programs MAX_PLATFORM_CLOS_NUM supported by L3 is 16 and MBA is 8, ACRN programs MAX_PLATFORM_CLOS_NUM
to 8. ACRN recommends to have consistent capabilities across all RDT to 8. ACRN recommends to have consistent capabilities across all RDT
resources by using a common subset CLOS. This is done in order to minimize resources by using a common subset CLOS. This is done in order to minimize

2
doc/getting-started/building-from-source.rst
View File

@ -121,6 +121,8 @@ Enter the following to get the acrn-hypervisor source code:
$ git clone https://github.com/projectacrn/acrn-hypervisor $ git clone https://github.com/projectacrn/acrn-hypervisor
.. _build-with-acrn-scenario:
.. rst-class:: numbered-step .. rst-class:: numbered-step
Build with the ACRN scenario Build with the ACRN scenario

109
doc/tutorials/rdt_configuration.rst
View File

@ -89,6 +89,13 @@ MBA bit encoding:
ACRN:\>cpuid 0x10 **0x3** ACRN:\>cpuid 0x10 **0x3**
cpuid leaf: 0x10, subleaf: 0x3, 0x59:0x0:0x4:0x7 cpuid leaf: 0x10, subleaf: 0x3, 0x59:0x0:0x4:0x7
.. note::
ACRN takes the lowest common CLOS max value between the supported
resources as maximum supported CLOS ID. For example, if max CLOS
supported by L3 is 16 and MBA is 8, ACRN programs MAX_PLATFORM_CLOS_NUM
to 8. ACRN recommends to have consistent capabilities across all RDT
resources by using a common subset CLOS. This is done in order to minimize
misconfiguration errors.
Tuning RDT resources in HV debug shell Tuning RDT resources in HV debug shell
************************************** **************************************
@ -136,46 +143,51 @@ shell.
Configure RDT for VM using VM Configuration Configure RDT for VM using VM Configuration
******************************************* *******************************************
#. RDT on ACRN is enabled by default on supported platforms. This #. RDT hardware feature is enabled by default on supported platforms. This
information can be found using an offline tool that generates a information can be found using an offline tool that generates a
platform-specific xml file that helps ACRN identify RDT-supported platform-specific xml file that helps ACRN identify RDT-supported
platforms. This feature can be also be toggled using the platforms. RDT on ACRN is enabled by configuring the ``FEATURES``
CONFIG_RDT_ENABLED flag with the ``make menuconfig`` command. The first sub-section of the scenario xml file as in the below example. For
step is to clone the ACRN source code (if you haven't already done so): details on building ACRN with scenario refer to :ref:`build-with-acrn-scenario`.
.. code-block:: none .. code-block:: none
:emphasize-lines: 6
$ git clone https://github.com/projectacrn/acrn-hypervisor.git <FEATURES>
$ cd acrn-hypervisor/ <RELOC desc="Enable hypervisor relocation">y</RELOC>
<SCHEDULER desc="The CPU scheduler to be used by the hypervisor.">SCHED_BVT</SCHEDULER>
<MULTIBOOT2 desc="Support boot ACRN from multiboot2 protocol.">y</MULTIBOOT2>
<RDT desc="Intel RDT (Resource Director Technology).">
<RDT_ENABLED desc="Enable RDT">*y*</RDT_ENABLED>
<CDP_ENABLED desc="CDP (Code and Data Prioritization). CDP is an extension of CAT.">n</CDP_ENABLED>
<CLOS_MASK desc="Cache Capacity Bitmask"></CLOS_MASK>
<MBA_DELAY desc="Memory Bandwidth Allocation delay value"></MBA_DELAY>
</RDT>
.. figure:: images/menuconfig-rdt.png #. Once RDT is enabled in the scenario xml file, the next step is to program
:align: center the desired cache mask or/and the MBA delay value as needed in the
scenario file. Each cache mask or MBA delay configuration corresponds
#. The predefined cache masks can be found at to a CLOS ID. For example, if the maximum supported CLOS ID is 4, then 4
``hypervisor/arch/x86/configs/$(CONFIG_BOARD)/board.c`` for respective boards. cache mask settings needs to be in place where each setting corresponds
For example, apl-up2 can found at ``hypervisor/arch/x86/configs/apl-up2/board.c``. to a CLOS ID starting from 0. To set the cache masks for 4 CLOS ID and
use default delay value for MBA, it can be done as shown in the example below.
.. code-block:: none .. code-block:: none
:emphasize-lines: 3,7,11,15 :emphasize-lines: 8,9,10,11,12
struct platform_clos_info platform_l2_clos_array[MAX_PLATFORM_CLOS_NUM] = { <FEATURES>
{ <RELOC desc="Enable hypervisor relocation">y</RELOC>
.clos_mask = 0xff, <SCHEDULER desc="The CPU scheduler to be used by the hypervisor.">SCHED_BVT</SCHEDULER>
.msr_index = MSR_IA32_L3_MASK_BASE + 0, <MULTIBOOT2 desc="Support boot ACRN from multiboot2 protocol.">y</MULTIBOOT2>
}, <RDT desc="Intel RDT (Resource Director Technology).">
{ <RDT_ENABLED desc="Enable RDT">y</RDT_ENABLED>
.clos_mask = 0xff, <CDP_ENABLED desc="CDP (Code and Data Prioritization). CDP is an extension of CAT.">n</CDP_ENABLED>
.msr_index = MSR_IA32_L3_MASK_BASE + 1, <CLOS_MASK desc="Cache Capacity Bitmask">*0xff*</CLOS_MASK>
}, <CLOS_MASK desc="Cache Capacity Bitmask">*0x3f*</CLOS_MASK>
{ <CLOS_MASK desc="Cache Capacity Bitmask">*0xf*</CLOS_MASK>
.clos_mask = 0xff, <CLOS_MASK desc="Cache Capacity Bitmask">*0x3*</CLOS_MASK>
.msr_index = MSR_IA32_L3_MASK_BASE + 2, <MBA_DELAY desc="Memory Bandwidth Allocation delay value">*0*</MBA_DELAY>
}, </RDT>
{
.clos_mask = 0xff,
.msr_index = MSR_IA32_L3_MASK_BASE + 3,
},
};
.. note:: .. note::
Users can change the mask values, but the cache mask must have Users can change the mask values, but the cache mask must have
@ -183,31 +195,24 @@ Configure RDT for VM using VM Configuration
programming an MBA delay value, be sure to set the value to less than or programming an MBA delay value, be sure to set the value to less than or
equal to the MAX delay value. equal to the MAX delay value.
#. Set up the CLOS in the VM config. Follow `RDT detection and resource capabilities`_ #. Configure each CPU in VMs to a desired CLOS ID in the ``VM`` section of the
to identify the MAX CLOS that can be used. ACRN uses the scenario file. Follow `RDT detection and resource capabilities`_
to identify the maximum supported CLOS ID that can be used. ACRN uses the
**the lowest common MAX CLOS** value among all RDT resources to avoid **the lowest common MAX CLOS** value among all RDT resources to avoid
resource misconfigurations. For example, configuration data for the resource misconfigurations.
Service VM sharing mode can be found at
``hypervisor/arch/x86/configs/vm_config.c``
.. code-block:: none .. code-block:: none
:emphasize-lines: 6 :emphasize-lines: 5,6,7,8
struct acrn_vm_config vm_configs[CONFIG_MAX_VM_NUM] __aligned(PAGE_SIZE) = { <vm id="0">
{ <vm_type desc="Specify the VM type" readonly="true">PRE_STD_VM</vm_type>
.type = SOS_VM, <name desc="Specify the VM name which will be shown in hypervisor console command: vm_list.">ACRN PRE-LAUNCHED VM0</name>
.name = SOS_VM_CONFIG_NAME, <uuid configurable="0" desc="vm uuid">26c5e0d8-8f8a-47d8-8109-f201ebd61a5e</uuid>
.guest_flags = 0UL, <clos desc="Class of Service for Cache Allocation Technology. Please refer SDM 17.19.2 for details and use with caution.">
.clos = 1, <vcpu_clos>*0*</vcpu_clos>
.memory = { <vcpu_clos>*1*</vcpu_clos>
.start_hpa = 0x0UL, </clos>
.size = CONFIG_SOS_RAM_SIZE, </vm>
},
.os_config = {
.name = SOS_VM_CONFIG_OS_NAME,
},
},
};
.. note:: .. note::
In ACRN, Lower CLOS always means higher priority (clos 0 > clos 1 > clos 2> ...clos n). In ACRN, Lower CLOS always means higher priority (clos 0 > clos 1 > clos 2> ...clos n).