From fa01261552cfa32bd5d5f79f85999efdb38997c0 Mon Sep 17 00:00:00 2001 From: "Yang, Yu-chu" Date: Thu, 28 Jan 2021 09:50:13 +0800 Subject: [PATCH] config_tools: add XML schema for the scenario XML This patch introduces a schema (in XSD 1.1) for the scenario XML of ACRN hypervisor for validation and documentation. An XML schema defines the expected layout and value ranges of an XML document. It allows a concise way to define our expectation on the information in a scenario XML, including: * structure of elements * number of occurrences of elements with the same tags * element data types and default values * element descriptions * any further properties such as readonly and configurable Multiple XSD-based validators are available in the open source community. A Python-based apporach will be introduced in a later patch and integrated into the build system to ensure the integrity of the scenario XML before we process it further. A reference of the configuration data will be generated from the blocks. Format for blocks will properly output multiple text lines so features such as lists can be used. All multi-line content must be left-aligned unless indentation is specifically required by rst syntax. The trailing tag should be on the same line as the last text line. For example: Three scheduler options are supported: - ``SCHED_NOOP``: The NOOP (No-Operation) scheduler means there is a strict 1 to 1 mapping between vCPUs and pCPUs. - ``SCHED_IORR``: The IORR (IO sensitive Round Robin) scheduler supports multipule vCPUs running on on one pCPU, scheduled by a IO sensitive round robin policy. ``SCHED_BVT``: The BVT (Borrowed Virtual time) scheduler is a virtual time based scheduling algorithm, it dispatchs the runnable thread with the earliest effective virtual time. *TODO: BVT scheduler will be built on top of a prioritized scheduling mechanism, i.e. higher priority threads get scheduled first, and same priority tasks are scheduled per BVT.* Read more about the available scheduling options in :ref:`cpu_sharing`. Tracked-On: #5672 Signed-off-by: Yang, Yu-chu Signed-off-by: David B. Kinder --- misc/config_tools/schema/VMtypes.xsd | 324 ++++++++++++++++++++ misc/config_tools/schema/config.xsd | 424 +++++++++++++++++++++++++++ misc/config_tools/schema/types.xsd | 202 +++++++++++++ 3 files changed, 950 insertions(+) create mode 100644 misc/config_tools/schema/VMtypes.xsd create mode 100644 misc/config_tools/schema/config.xsd create mode 100644 misc/config_tools/schema/types.xsd diff --git a/misc/config_tools/schema/VMtypes.xsd b/misc/config_tools/schema/VMtypes.xsd new file mode 100644 index 000000000..9d2716662 --- /dev/null +++ b/misc/config_tools/schema/VMtypes.xsd @@ -0,0 +1,324 @@ + + + + + + Description missing. + + + + + + + + + + + + + + + Description missing. + + + + + + + + + + + + + + + + + + Description missing. + + + + + + + + + + Description missing. + + + + + + + + + + Description missing. + + + + + + + + epc section. + + + + + Description missing. + + + + + Description missing. + + + + + + + + + + Description missing. + + + + + Description missing. + + + + + Start of second HPA for non-contiguous allocations in host for the VM. + + + + + Memory size of second HPA for non-contiguous allocations in Bytes for the VM. + + + + + + + + + + + Specify the OS name of VM; currently, it is not referenced by the hypervisor code.String from 1 to 32 +characters long. + + + + + + + + + + Description missing. + + + + + Description missing. + + + + + Description missing. + + + + + Configurable boot argument for pre-launched VM of hybrid or hybrid_rt mode. + + + + + Description missing. + + + + + Description missing. + + + + + + + + Description missing. + + + + + + + + + + vCOM type + + + + + + + + + + vUART (A.K.A COM) enabling switch. Enable by exposing its base address, disable by returning INVALID_COM_BASE. + + + + + + + + + + + + + + + vCOM irq + + + + + + + + + + + + + + + + + + + + + Description missing. + + + + + Description missing. + + + + + Description missing. + + + + + Description missing. + + + + + Description missing. + + + + + + + + + Description missing. + + + + + + + + + + + + Description missing. + + + + + + + + + + + Description missing. + + + + + Description missing. + + + + + Description missing. + + + + + + + + + + + Description missing. + + + + + Description missing. + + + + + + + + + + Description missing. + + + + + + + + + + Description missing. + + + + + Description missing. + + + + + + diff --git a/misc/config_tools/schema/config.xsd b/misc/config_tools/schema/config.xsd new file mode 100644 index 000000000..9c653857d --- /dev/null +++ b/misc/config_tools/schema/config.xsd @@ -0,0 +1,424 @@ + + + + + + + + + Options for debugging the hypervisor. + + + + + + Build an image for release (``y``) or debug (``n``). +In a **release** image, assertions are not enforced and these features +are **not** available: + +- logs +- serial console +- hypervisor shell + + + + + 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 :option:`hv.DEBUG_OPTIONS.SERIAL_CONSOLE` empty if the +Service VM :ref:`vm.console_vuart` is enabled. Uses +:option:`vm.board_private.bootargs` for the :ref:`vm.console_vuart` +configuration. + + + + + Default loglevel for log messages stored in memory. +Messages with a lower severity (higher value) are discarded. + + + + + Default loglevel for the hypervisor NPK log. + + + + + Default loglevel for log messages +written to the serial console. Messages with lower severity (higher +value) are not displayed. + + + + + + Bitmap indicating the destination of log messages. +Currently there are three log destinations available: + +- bit 0 for the serial console (``0x1``), +- bit 1 for the Service VM log (``0x2``), and +- bit 2 for 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``). + + + + + + + + + + Capacity (in bytes) of logbuf for each +physical cpu, for example, ``0x40000``. + + + + + + + + Options for hypervisor feature enablement. + + + + + + Specify if hypervisor relocation is enabled on booting. + + + + + The CPU scheduler used by the hypervisor. + + + + + 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. + + + + + Enable the Intel Resource Director Technology (RDT) +allocation feature. If the board hardware does not support +RDT, setting this option to ``y`` is ignored. + + + + + Enable Hyper-V. + + + + + Specify if the IOMMU enforces snoop behavior +of DMA operations. + + + + + Enable ACPI runtime parsing. + + + + + Enable L1 cache flush before VM entry. + + + + + Force disabling software workaround for +Machine Check Error on Page Size Change. + + + + + Enable Inter-VM Shared memory feature. + + + + + Description missing + + + + + + + + + + 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. + + + + + Size of the RAM region used by the hypervisor. + + + + + The 2MB-aligned starting physical address of +the RAM region used by the hypervisor. + + + + + Size of the low RAM region below address +``0x10000``, starting from address ``0x0``.. + + + + + Size of the User VM OS RAM region. + + + + + Size of the Service VM OS RAM region. + + + + + Size of the physical platform RAM. + + + + + + + + Capacity limits for static assigned data structure or +maximum supported resource. + + + + + Highest PCI bus ID used during IOMMU initialization. + + + + + Maximum number of Interrupt Remapping Entries. + + + + + + Maximum number of IO-APICs. Integer from 1 to 10. + + + + + + + + + + Description missing. + + + + + + Maximum number of PCI devices.Integer from 1 to 1024. + + + + + + + + + + + Maximum number of interrupt lines per IOAPIC.Integer from 1 to 120. + + + + + + + + + + Maximum number of interrupt source for PT devices. + + + + + + Maximum number of MSI-X tables per device. +Leave blank if not sure.Integer from 1 to 2048. + + + + + + + + + + + Maximum number of emulated MMIO regions.Integer from 1 to 128. + + + + + + + + + + + + + + + Segment, Bus, Device, and function of the GPU. + + + + + Description missing + + + + + + + + + + + + + + + + + + + + Specify the VM type. + + + + + + Specify the VM name shown in the + hypervisor console ``vm_lists`` command. String from 1 to 32 + characters long. + + + + + + + + + + Select all applicable flags for the VM. + + + + + List of pCPU that this VM's vCPUs are pinned to. + + + + + Class of Service for Cache Allocation Technology. +Refer SDM 17.19.2 for details, and use with caution. + + + + + Description missing + + + + + Description missing + + + + + Description missing + + + + + Description missing + + + + + Description missing + + + + + Description missing + + + + + Description missing + + + + + Description missing + + + + + pt intx mapping. + + + + + pci devices list. + + + + + + + + + + + + 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. + + + + + 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. + + + + + + + + + + diff --git a/misc/config_tools/schema/types.xsd b/misc/config_tools/schema/types.xsd new file mode 100644 index 000000000..56a3d5394 --- /dev/null +++ b/misc/config_tools/schema/types.xsd @@ -0,0 +1,202 @@ + + + + + + A boolean value, written as ``y`` or ``n``. + + + + + + + + + + An integer value in hexadecimal format. + + + + + + + + + + + + + + + Either empty, or a hexadecimal value. + + + + + + + Either empty, or a hexadecimal value. + + + + + + + Integer from 1 to 2048. + + + + + + + + + + Either empty, or an integer value between 1 and 2048. + + + + + + + + + + + + + Either a hexadecimal value or the string +``CONFIG_SOS_RAM_SIZE``. + + + + + + + An integer from 0 to 7 representing log message +severity and intent: + +- 1 (LOG_FATAL) system is unusable +- 2 (LOG_ACRN) +- 3 (LOG_ERROR) error conditions +- 4 (LOG_WARNING) warning conditions +- 5 (LOG_INFO) informational +- 6 (LOG_DEBUG) debug-level messages + +Note that lower values have a higher severity. Only log messages with a +severity level higher (lower value) than a specified value will be +recorded. + + + + + + + + + + Three scheduler options are supported: + +- ``SCHED_NOOP``: The NOOP (No-Operation) scheduler means there is a + strict 1 to 1 mapping between vCPUs and pCPUs. +- ``SCHED_IORR``: The IORR (IO sensitive Round Robin) scheduler supports + multipule vCPUs running on on one pCPU, scheduled by + a IO sensitive round robin policy. +- ``SCHED_BVT``: The BVT (Borrowed Virtual time) scheduler is a virtual time based + scheduling algorithm, it dispatchs the runnable thread with the + earliest effective virtual time. *TODO: BVT scheduler will be built on + top of a prioritized scheduling mechanism, i.e. higher priority threads + get scheduled first, and same priority tasks are scheduled per BVT.* + +Read more about the available scheduling options in :ref:`cpu_sharing`. + + + + + + + + + + + + + + + + + Either empty or a string. + + + + + + + + + + + + + Either empty or a string. + + + + + + + + + + Enable inter-VM shared memory (IVSHMEM) feature. + + + + + A comma-separated list with the inter-VM shared memory region name, +size, and VM IDs that may communicate using this shared region: + +* Prefix the region ``name`` with ``hv:/`` (for an hv-land solution). + (See :ref:`ivshmem-hld` for details.) +* Specify the region ``size`` in MB. Must be a power of 2, e.g., 2, 4, + 8, 16, up to 512. +* Specify all VM IDs that may use this shared memory area, + separated by a ``:``. For example, use ``0:2`` to share this area between + VMs 0 and 2, or ``0:1:2`` (to let VMs 0, 1, and 2 share this area). + + + + + + + + + + Description missing. + + + + + Description missing. + + + + + Description missing. + + + + + Description missing. + + + + + + + + + + + +