acrn-hypervisor/misc/config_tools/schema/config.xsd
Kunhui-Li 25c677dc39 doc: fix documentation's issue
1. Update the necessary libraries to consistent with the "Build ACRN From Source"
document in the "Getting Started Guide" document.
2. Delete the related introduction with acrngt.conf and launch_uos_id1.sh files in
"Getting Started Guide" document.
3. Update WHL-IPC-I7 board's processor in Supported HW document.
4. Add cpu_affinity element's description in ACRN Configuration Data.
5. Update the description for shm_region in Launch XML format.
6. Update configurable/readonly attributes values.
7. Update the description for hv.CAPACITIES.MAX_MSIX_TABLE_NUM in schema/config.xsd.

Tracked-On: #5692
Signed-off-by: Kunhui-Li <kunhuix.li@intel.com>
2021-06-23 19:25:22 -07:00

471 lines
19 KiB
XML

<?xml version="1.0"?>
<xs:schema
xmlns:xi="http://www.w3.org/2003/XInclude"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:acrn="https://projectacrn.org">
<xi:include href="types.xsd" xpointer="xpointer(id('root')/*)" />
<xi:include href="VMtypes.xsd" xpointer="xpointer(id('root')/*)" />
<xs:complexType name="DebugOptionsType">
<xs:annotation>
<xs:documentation>Options for debugging the hypervisor.</xs:documentation>
</xs:annotation>
<xs:all>
<xs:element name="RELEASE" type="Boolean" default="n">
<xs:annotation>
<xs:documentation>Build an image for release (``y``) or debug (``n``).
In a **release** image, assertions are not enforced and debugging
features are disabled, including logs, serial console, and the
hypervisor shell.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="SERIAL_CONSOLE" type="SerialConsoleOptions" default="/dev/ttyS0">
<xs:annotation>
<xs:documentation>Specify the host serial device used for hypervisor debugging.
This option is only valid if the Service VM :ref:`vm.legacy_vuart` is
enabled. Leave this field empty if the Service VM's :ref:`vm.console_vuart` is enabled. Uses
:option:`vm.os_config.bootargs` for :ref:`vm.console_vuart`
configuration.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="MEM_LOGLEVEL" type="LogLevelType" default="5">
<xs:annotation>
<xs:documentation>Default loglevel for log messages stored in
memory. Value can be changed at runtime.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="NPK_LOGLEVEL" type="LogLevelType" default="5">
<xs:annotation>
<xs:documentation>Default loglevel for the hypervisor North Peak
(NPK) log. Value can be changed at runtime.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="CONSOLE_LOGLEVEL" type="LogLevelType" default="3">
<xs:annotation>
<xs:documentation>Default loglevel for log messages
written to the serial console.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="LOG_DESTINATION" default="7">
<xs:annotation>
<xs:documentation>Bitmap indicating the destination of log messages.
There are three log destinations available:
- Bit 0 enables the serial console (``0x1``),
- Bit 1 enables the Service VM log (``0x2``), and
- Bit 2 enables the NPK log (``0x4``).
For example, a value of ``3`` enables only the
serial console and Service VM logs. Effective only in debug builds (when
:option:`hv.DEBUG_OPTIONS.RELEASE` is ``n``).</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:annotation>
<xs:documentation>Integer value from 0 to 7.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:integer">
<xs:minInclusive value="0" />
<xs:maxInclusive value="7" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="LOG_BUF_SIZE" type="HexFormat" default="0x40000">
<xs:annotation>
<xs:documentation>Capacity (in bytes) of logbuf for each
physical CPU, for example, ``0x40000``.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:all>
</xs:complexType>
<xs:complexType name="FeatureOptionsType">
<xs:annotation>
<xs:documentation>Options for enabling hypervisor features.</xs:documentation>
</xs:annotation>
<xs:all>
<xs:element name="RELOC" type="Boolean" default="y">
<xs:annotation>
<xs:documentation>Specify if hypervisor relocation is enabled on
booting.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="SCHEDULER" type="SchedulerType" default="SCHED_BVT">
<xs:annotation>
<xs:documentation>The CPU scheduler used by the hypervisor.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="MULTIBOOT2" type="Boolean" default="y">
<xs:annotation>
<xs:documentation>Specify if the ACRN hypervisor image can be booted using the
multiboot2 protocol. If set to ``n``, GRUB's multiboot2 is not available as a
boot option.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="ENFORCE_TURNOFF_AC" type="Boolean" default="y">
<xs:annotation>
<xs:documentation>Force to disable #AC for Split-locked Access. If CPU has #AC for
split-locked access, HV enables it and VMs can't disable. Set this to enforce turning off that
#AC, for debugging purposes only.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="RDT" type="RDTType">
<xs:annotation>
<xs:documentation>Enable the Intel Resource Director Technology (RDT)
allocation feature and Code and Data Prioritization (CDP). If the board hardware does not
support RDT or CDP, setting this option to ``y`` is ignored.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="HYPERV_ENABLED" type="Boolean" default="y">
<xs:annotation>
<xs:documentation>Enable Hyper-V.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="NVMX_ENABLED" type="Boolean" default="n">
<xs:annotation>
<xs:documentation>Enable nested virtualization.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="IOMMU_ENFORCE_SNP" type="Boolean" default="n">
<xs:annotation>
<xs:documentation>Specify if the IOMMU enforces snoop behavior
of DMA operations.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="ACPI_PARSE_ENABLED" type="Boolean" default="y">
<xs:annotation>
<xs:documentation>Enable ACPI runtime parsing.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="L1D_VMENTRY_ENABLED" type="Boolean" default="n">
<xs:annotation>
<xs:documentation>Enable L1 cache flush before VM entry. Default
value ``n``.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="MCE_ON_PSC_DISABLED" type="Boolean" default="n">
<xs:annotation>
<xs:documentation>Force disabling software workaround for
Machine Check Error on Page Size Change.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="IVSHMEM" type="IVSHMEMInfo">
<xs:annotation>
<xs:documentation>Enable Inter-VM Shared memory feature.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="SSRAM" minOccurs="0" type="SSRAMInfo">
<xs:annotation>
<xs:documentation>Pseudo SRAM configuration.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:all>
<xs:assert test="not (RDT/RDT_ENABLED = 'y' and SSRAM/SSRAM_ENABLED = 'y')"/>
<xs:assert test="not (NVMX_ENABLED = 'y' and not (SCHEDULER = 'SCHED_NOOP'))"/>
</xs:complexType>
<xs:complexType name="MemoryOptionsType">
<xs:all>
<xs:element name="STACK_SIZE" type="HexFormat" default="0x2000">
<xs:annotation>
<xs:documentation>Capacity of one stack (in bytes) used by a
physical core. Each core uses one stack for normal operation and another
three for specific exceptions.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="HV_RAM_SIZE" type="HVRamSizeType">
<xs:annotation>
<xs:documentation>Size of the RAM region used by the hypervisor.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="HV_RAM_START" type="HVRamStartType">
<xs:annotation>
<xs:documentation>The 2MB-aligned starting physical address of
the RAM region used by the hypervisor.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="LOW_RAM_SIZE" type="HexFormat" default="0x00010000">
<xs:annotation>
<xs:documentation>Size of the low RAM region below address
``0x10000``, starting from address ``0x0``.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="PLATFORM_RAM_SIZE" type="HexFormat" default="0x400000000">
<xs:annotation>
<xs:documentation>Size of the physical platform RAM. Default
value ``0x400000000``.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:all>
</xs:complexType>
<xs:complexType name="CapacitiesOptionsType">
<xs:annotation>
<xs:documentation>Capacity limits for static assigned data structure or
maximum supported resource.</xs:documentation>
</xs:annotation>
<xs:all>
<xs:element name="IOMMU_BUS_NUM" type="HexFormat" default="0x100">
<xs:annotation>
<xs:documentation>Highest PCI bus ID used during IOMMU
initialization.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="MAX_IR_ENTRIES" type="xs:integer" default="256">
<xs:annotation>
<xs:documentation>Maximum number of Interrupt Remapping Entries.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="MAX_IOAPIC_NUM" default="1">
<xs:annotation>
<xs:documentation>Maximum number of IOAPICs.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:annotation>
<xs:documentation>Integer from 1 to 10.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1" />
<xs:maxInclusive value="10" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="MAX_KATA_VM_NUM" type="xs:integer" minOccurs="0" default="0">
<xs:annotation>
<xs:documentation>Maximum number of KATA VM.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="MAX_PCI_DEV_NUM" default="96">
<xs:annotation>
<xs:documentation>Maximum number of PCI devices.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:annotation>
<xs:documentation>Integer from 1 to 1024.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1" />
<xs:maxInclusive value="1024" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="MAX_IOAPIC_LINES" default="120">
<xs:annotation>
<xs:documentation>Maximum number of interrupt lines per IOAPIC.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:annotation>
<xs:documentation>Integer from 1 to 120.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1" />
<xs:maxInclusive value="120" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="MAX_PT_IRQ_ENTRIES" type="xs:integer" default="256">
<xs:annotation>
<xs:documentation>Maximum number of interrupt source for PT
devices.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="MAX_MSIX_TABLE_NUM" default="64">
<xs:annotation>
<xs:documentation>Maximum number of MSI-X tables per device.
If this value is empty, then the default value will be calculated from the board XML file.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:annotation>
<xs:documentation>Integer value from 1 to 2048.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1" />
<xs:maxInclusive value="2048" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="MAX_EMULATED_MMIO" default="16">
<xs:annotation>
<xs:documentation>Maximum number of emulated MMIO regions.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:annotation>
<xs:documentation>Integer value from 1 to 128.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1" />
<xs:maxInclusive value="128" />
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:all>
</xs:complexType>
<xs:complexType name="MiscCfgOptionsType">
<xs:all>
<xs:element name="GPU_SBDF" type="HexFormat" default="0x00000010">
<xs:annotation>
<xs:documentation>Segment, Bus, Device, and function of the GPU.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="UEFI_OS_LOADER_NAME" type="xs:string" minOccurs="0">
<xs:annotation>
<xs:documentation>UEFI OS loader name.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:all>
</xs:complexType>
<xs:complexType name="HVConfigType">
<xs:all>
<xs:element name="DEBUG_OPTIONS" type="DebugOptionsType" />
<xs:element name="FEATURES" type="FeatureOptionsType" />
<xs:element name="MEMORY" type="MemoryOptionsType" />
<xs:element name="CAPACITIES" type="CapacitiesOptionsType" />
<xs:element name="MISC_CFG" type="MiscCfgOptionsType" />
</xs:all>
</xs:complexType>
<xs:complexType name="VMConfigType">
<xs:all>
<xs:element name="vm_type" type="VMOptionsType">
<xs:annotation acrn:readonly="y">
<xs:documentation>Specify the VM type.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="name" minOccurs="0">
<xs:annotation>
<xs:documentation>Specify the VM name shown in the
hypervisor console ``vm_list`` command.</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:annotation>
<xs:documentation>string from 1 to 32 characters long.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="32" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="guest_flags" type="GuestFlagsInfo" minOccurs="0">
<xs:annotation acrn:multiselect="y">
<xs:documentation>Select all applicable flags for the VM.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="cpu_affinity" type="CPUAffinityConfiguration" minOccurs="0">
<xs:annotation>
<xs:documentation>List of pCPU that this VM's vCPUs are pinned to.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="clos" type="CLOSConfiguration">
<xs:annotation>
<xs:documentation>Class of Service for Cache Allocation Technology.
Refer SDM 17.19.2 for details, and use with caution.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="epc_section" type="EPCSection" minOccurs="0">
<xs:annotation>
<xs:documentation>Specify SGX Enclave Page Cache section base and size in byte. It must be page aligned.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="memory" type="MemoryInfo" minOccurs="0">
<xs:annotation>
<xs:documentation>Specify memory information for Service and User VMs.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="os_config" type="OSConfigurations" minOccurs="0">
<xs:annotation>
<xs:documentation>General information for host kernel, boot
argument and memory.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="legacy_vuart" type="LegacyVuartConfiguration" minOccurs="2" maxOccurs="2">
<xs:annotation>
<xs:documentation>Specify the vUART (aka COM) with the vUART ID by its ``id`` attribute.
Refer to :ref:`vuart_config` for detailed vUART settings.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="console_vuart" type="ConsoleVuartConfiguration">
<xs:annotation>
<xs:documentation>Specify the console vUART (aka PCI based vUART) with the vUART ID by
its ``id`` attribute.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="communication_vuart" type="CommunicationVuartConfiguration" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>Specify the communication vUART (aka PCI based vUART) with the vUART ID by
its ``id`` attribute. When it is enabled, specify which target VM's vUART the current VM connects to.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="mmio_resources" type="MMIOResourcesConfiguration" minOccurs="0">
<xs:annotation>
<xs:documentation>MMIO resources to passthrough.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="pci_dev_num" type="xs:string" minOccurs="0">
<xs:annotation>
<xs:documentation>PCI devices number of the VM.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="pt_intx" type="xs:string" minOccurs="0">
<xs:annotation>
<xs:documentation>pt intx mapping.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="pci_devs" type="PCIDevsConfiguration" minOccurs="0">
<xs:annotation>
<xs:documentation>PCI devices list.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="board_private" type="BoardPrivateConfiguration" minOccurs="0" />
<xs:element name="PTM" type="Boolean" default="n" minOccurs="0">
<xs:annotation>
<xs:documentation>Enable and disable PTM(Precision Timing Measurement) feature.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:all>
<xs:attribute name="id" type="xs:integer" />
<xs:assert test="vm_type != 'SOS_VM' or count(guest_flags[guest_flag = 'GUEST_FLAG_LAPIC_PASSTHROUGH']) = 0 or count(guest_flags[guest_flag = 'GUEST_FLAG_NVMX_ENABLED']) > 0">
<xs:annotation>
<xs:documentation>SOS cannot use LAPIC passthrough unless GUEST_FLAG_NVMX_ENABLED is set.</xs:documentation>
</xs:annotation>
</xs:assert>
</xs:complexType>
<xs:complexType name="ACRNConfigType">
<xs:all>
<xs:element name="hv" type="HVConfigType">
<xs:annotation>
<xs:documentation>The hypervisor configuration defines a working scenario and target
board by configuring the hypervisor image features and capabilities such as
setting up the log and the serial port.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="vm" type="VMConfigType" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>VM configuration includes **scenario-based** VM configuration
information that is used to describe the characteristics and attributes for
all VMs in a user scenario. It also includes **launch script-based** VM
configuration information, where parameters are passed to the device model
to launch post-launched User VMs.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:all>
<xs:attribute name="board" type="xs:string" use="required" />
<xs:attribute name="scenario" type="xs:string" use="required" />
<xs:assert test="count(//guest_flag[text() = 'GUEST_FLAG_NVMX_ENABLED']) = 0 or //NVMX_ENABLED = 'y'">
<xs:annotation>
<xs:documentation>Per VM GUEST_FLAG_NVMX_ENABLED can be set only if CONFIG_NVMX_ENABLED is set.</xs:documentation>
</xs:annotation>
</xs:assert>
</xs:complexType>
<xs:element name="acrn-config" type="ACRNConfigType" />
</xs:schema>