diff --git a/doc/developer-guides/hld/hv-rdt.rst b/doc/developer-guides/hld/hv-rdt.rst index 5850b5e44..73f3051cf 100644 --- a/doc/developer-guides/hld/hv-rdt.rst +++ b/doc/developer-guides/hld/hv-rdt.rst @@ -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 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 -CLOS ID, to select a cache mask to take effect. ACRN uses -VMCS MSR loads on every VM Entry/VM Exit for non-root and root modes to -enforce the settings. +CLOS ID, to select a cache mask to take effect. These configurations can be +done in scenario xml file under ``FEATURES`` section 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 - :emphasize-lines: 3,7,11,15 + :emphasize-lines: 2,4 - struct platform_clos_info platform_l2_clos_array[MAX_PLATFORM_CLOS_NUM] = { - { - .clos_mask = 0xff, - .msr_index = MSR_IA32_L3_MASK_BASE + 0, - }, - { - .clos_mask = 0xff, - .msr_index = MSR_IA32_L3_MASK_BASE + 1, - }, - { - .clos_mask = 0xff, - .msr_index = MSR_IA32_L3_MASK_BASE + 2, - }, - { - .clos_mask = 0xff, - .msr_index = MSR_IA32_L3_MASK_BASE + 3, - }, - }; + + y + n + 0xF + +Once the cache mask is set of each individual CPU, the respective CLOS ID +needs to be set in the scenario xml file under ``VM`` section. If user desires +to use CDP feature, CDP_ENABLED should be set to ``y``. .. code-block:: none - :emphasize-lines: 6 + :emphasize-lines: 2 - struct acrn_vm_config vm_configs[CONFIG_MAX_VM_NUM] __aligned(PAGE_SIZE) = { - { - .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, - }, - }, - }; + + 0 .. note:: ACRN takes the lowest common CLOS max value between the supported - resources and sets the MAX_PLATFORM_CLOS_NUM. For example, if max CLOS - supported by L3 is 16 and L2 is 8, ACRN programs MAX_PLATFORM_CLOS_NUM to - 8. ACRN recommends consistent capabilities across all RDT - resources by using the common subset CLOS. This is done in order to - minimize misconfiguration errors. + 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. 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 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. -ACRN uses VMCS MSR loads on every VM Entry/VM Exit for non-root and root -modes to enforce the settings. +These configurations can be done in scenario xml file under ``FEATURES`` section +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 - :emphasize-lines: 3,7,11,15 + :emphasize-lines: 2,5 - struct platform_clos_info platform_mba_clos_array[MAX_PLATFORM_CLOS_NUM] = { - { - .mba_delay = 0, - .msr_index = MSR_IA32_MBA_MASK_BASE + 0, - }, - { - .mba_delay = 0, - .msr_index = MSR_IA32_MBA_MASK_BASE + 1, - }, - { - .mba_delay = 0, - .msr_index = MSR_IA32_MBA_MASK_BASE + 2, - }, - { - .mba_delay = 0, - .msr_index = MSR_IA32_MBA_MASK_BASE + 3, - }, - }; + + y + n + + 0 + +Once the cache mask is set of each individual CPU, the respective CLOS ID +needs to be set in the scenario xml file under ``VM`` section. .. code-block:: none - :emphasize-lines: 6 + :emphasize-lines: 2 - struct acrn_vm_config vm_configs[CONFIG_MAX_VM_NUM] __aligned(PAGE_SIZE) = { - { - .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, - }, - }, - }; + + 0 .. note:: 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 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 diff --git a/doc/getting-started/building-from-source.rst b/doc/getting-started/building-from-source.rst index 595fe6be1..4f1c3eef6 100644 --- a/doc/getting-started/building-from-source.rst +++ b/doc/getting-started/building-from-source.rst @@ -121,6 +121,8 @@ Enter the following to get the acrn-hypervisor source code: $ git clone https://github.com/projectacrn/acrn-hypervisor +.. _build-with-acrn-scenario: + .. rst-class:: numbered-step Build with the ACRN scenario diff --git a/doc/tutorials/rdt_configuration.rst b/doc/tutorials/rdt_configuration.rst index c8223b400..147e32d68 100644 --- a/doc/tutorials/rdt_configuration.rst +++ b/doc/tutorials/rdt_configuration.rst @@ -89,6 +89,13 @@ MBA bit encoding: ACRN:\>cpuid 0x10 **0x3** 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 ************************************** @@ -136,46 +143,51 @@ shell. 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 platform-specific xml file that helps ACRN identify RDT-supported - platforms. This feature can be also be toggled using the - CONFIG_RDT_ENABLED flag with the ``make menuconfig`` command. The first - step is to clone the ACRN source code (if you haven't already done so): + platforms. RDT on ACRN is enabled by configuring the ``FEATURES`` + sub-section of the scenario xml file as in the below example. For + details on building ACRN with scenario refer to :ref:`build-with-acrn-scenario`. .. code-block:: none + :emphasize-lines: 6 - $ git clone https://github.com/projectacrn/acrn-hypervisor.git - $ cd acrn-hypervisor/ + + y + SCHED_BVT + y + + *y* + n + + + - .. figure:: images/menuconfig-rdt.png - :align: center - -#. The predefined cache masks can be found at - ``hypervisor/arch/x86/configs/$(CONFIG_BOARD)/board.c`` for respective boards. - For example, apl-up2 can found at ``hypervisor/arch/x86/configs/apl-up2/board.c``. +#. Once RDT is enabled in the scenario xml file, the next step is to program + the desired cache mask or/and the MBA delay value as needed in the + scenario file. Each cache mask or MBA delay configuration corresponds + to a CLOS ID. For example, if the maximum supported CLOS ID is 4, then 4 + cache mask settings needs to be in place where each setting corresponds + 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 - :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] = { - { - .clos_mask = 0xff, - .msr_index = MSR_IA32_L3_MASK_BASE + 0, - }, - { - .clos_mask = 0xff, - .msr_index = MSR_IA32_L3_MASK_BASE + 1, - }, - { - .clos_mask = 0xff, - .msr_index = MSR_IA32_L3_MASK_BASE + 2, - }, - { - .clos_mask = 0xff, - .msr_index = MSR_IA32_L3_MASK_BASE + 3, - }, - }; + + y + SCHED_BVT + y + + y + n + *0xff* + *0x3f* + *0xf* + *0x3* + *0* + .. note:: 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 equal to the MAX delay value. -#. Set up the CLOS in the VM config. Follow `RDT detection and resource capabilities`_ - to identify the MAX CLOS that can be used. ACRN uses the +#. Configure each CPU in VMs to a desired CLOS ID in the ``VM`` section of 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 - resource misconfigurations. For example, configuration data for the - Service VM sharing mode can be found at - ``hypervisor/arch/x86/configs/vm_config.c`` + resource misconfigurations. .. 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) = { - { - .type = SOS_VM, - .name = SOS_VM_CONFIG_NAME, - .guest_flags = 0UL, - .clos = 1, - .memory = { - .start_hpa = 0x0UL, - .size = CONFIG_SOS_RAM_SIZE, - }, - .os_config = { - .name = SOS_VM_CONFIG_OS_NAME, - }, - }, - }; + + PRE_STD_VM + ACRN PRE-LAUNCHED VM0 + 26c5e0d8-8f8a-47d8-8109-f201ebd61a5e + + *0* + *1* + + .. note:: In ACRN, Lower CLOS always means higher priority (clos 0 > clos 1 > clos 2> ...clos n).