[Xen-devel] [PATCH 1/2] xen/dom0: Improve documentation for dom0= and dom0-iommu=

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

Update to the latest metadata style, and expand each of the clauses with more
information, including applicable CONFIG_* options.

Drop the redundant comment beside parse_dom0_param(), to avoid it getting out
of sync with the main documentation.

Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
---
CC: Jan Beulich <JBeulich@xxxxxxxx>
CC: Wei Liu <wei.liu2@xxxxxxxxxx>
CC: Roger Pau Monné <roger.pau@xxxxxxxxxx>
CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
CC: Julien Grall <julien.grall@xxxxxxx>

Please double check for correctness.  The text matches my
understanding/reading of the code, but some of it is rather subtle going.

It occurs to me that:

 * The choice of dom0 boot mode should in part be derived from the available
   CONFIG_* options, and ELF notes advertised in the dom0 kernel.

 * AMD probably needs to gain an `ivmd=` to mirror `rmrr=` on the Intel side,
   because we know there are other errors in the IVRS table.

 * Neither of map-{inclusive,reserved} should be active by default, even on
   Intel hardware, and we should (wherever possible) have quirks like we have
   for all other firmware screwups.  Requiring the user to diagnose/work
   around firmware problems like this is quite rude.

But this is all future work to do.
---
 docs/misc/xen-command-line.markdown | 103 ++++++++++++++++++++++--------------
 xen/arch/x86/dom0_build.c           |   6 ---
 2 files changed, 62 insertions(+), 47 deletions(-)

diff --git a/docs/misc/xen-command-line.markdown 
b/docs/misc/xen-command-line.markdown
index 44ee51a..94ee703 100644
--- a/docs/misc/xen-command-line.markdown
+++ b/docs/misc/xen-command-line.markdown
@@ -636,55 +636,76 @@ trace feature is only enabled in debugging builds of Xen.
 
 Specify the bit width of the DMA heap.
 
-### dom0 (x86)
-> `= List of [ pvh | shadow ]`
+### dom0
+> `= List of [ pvh=<bool>, shadow=<bool> ]`
 
-> Sub-options:
-
-> `pvh`
+> Applicability: x86
 
-> Default: `false`
+Controls for how dom0 is constructed on x86 systems.
 
-Flag that makes a dom0 boot in PVHv2 mode.
+*   The `pvh` boolean controls whether dom0 is constructed as a PV or a PVH
+    guest.  For backwards compatibility, the default is PV.  In addition, the
+    following requirements must be met.
 
-> `shadow`
+    *    The dom0 kernel selected by the boot loader must be capable of the
+         selected mode.
+    *    For a PV dom0, Xen must have been compiled with `CONFIG_PV` enabled.
+    *    For a PVH dom0, Xen must have been compiled with `CONFIG_HVM` enabled,
+         and the hardware must have VT-x/SVM extensions available.
 
-> Default: `false`
+*   The `shadow` boolean is only applicable when dom0 is constructed as a PVH
+    guest, and controls whether dom0 uses hardware assisted paging, or shadow
+    paging.  The default is HAP when available, and shadow otherwise.
 
-Flag that makes a dom0 use shadow paging. Only works when "pvh" is
-enabled.
+    This option is unavailable when `CONFIG_SHADOW_PAGING` is compiled out.  A
+    PVH dom0 cannot be used if `CONFIG_SHADOW_PAGING` is compiled out, and the
+    hardware is not HAP-capable.
 
 ### dom0-iommu
-> `= List of [ passthrough | strict | map-inclusive ]`
-
-This list of booleans controls the iommu usage by Dom0:
-
-* `passthrough`: disables DMA remapping for Dom0. Default is `false`. Note that
-  this option is hard coded to `false` for a PVH Dom0 and any attempt to
-  overwrite it from the command line is ignored.
-
-* `strict`: sets up DMA remapping only for the RAM Dom0 actually got assigned.
-  Default is `false` which means Dom0 will get mappings for all the host
-  RAM except regions in use by Xen. Note that this option is hard coded to
-  `true` for a PVH Dom0 and any attempt to overwrite it from the command line
-  is ignored.
-
-* `map-inclusive`: sets up DMA remapping for all the non-RAM regions below 4GB
-  except for unusable ranges. Use this to work around firmware issues providing
-  incorrect RMRR/IVMD entries. Rather than only mapping RAM pages for IOMMU
-  accesses for Dom0, with this option all pages up to 4GB, not marked as
-  unusable in the E820 table, will get a mapping established. Note that this
-  option is only applicable to a PV Dom0 and is enabled by default on Intel
-  hardware.
-
-* `map-reserved`: sets up DMA remapping for all the reserved regions in the
-  memory map for Dom0. Use this to work around firmware issues providing
-  incorrect RMRR/IVMD entries. Rather than only mapping RAM pages for IOMMU
-  accesses for Dom0, all memory regions marked as reserved in the memory map
-  that don't overlap with any MMIO region from emulated devices will be
-  identity mapped. This option maps a subset of the memory that would be
-  mapped when using the `map-inclusive` option. This option is available to all
-  Dom0 modes and is enabled by default on Intel hardware.
+> `= List of [ passthrough=<bool>, strict=<bool>, map-inclusive=<bool>,
+>              map-reserved=<bool> ]`
+
+Controls for the dom0 IOMMU setup.
+
+*   The `passthrough` boolean is applicable to x86 PV dom0's only and defaults
+    to false.  It controls whether the IOMMU is fully disabled for devices
+    belonging to dom0 (`passthrough=1`), or whether the IOMMU is set up with
+    an identity transform for dom0 (`passthrough=0`) to prevent dom0 from
+    DMA'ing outside of its permitted areas.
+
+    This option is hardwired to false for x86 PVH dom0's (where a non-identity
+    transform is required for dom0 to function), and is ignored for ARM.
+
+*   The `strict` boolean is applicable to x86 PV dom0's only and defaults to
+    false.  It controls whether dom0 can have IOMMU mappings for all domain
+    RAM in the system, or only for its allocated RAM (and grant mappings etc.)
+
+    This option is hardwired to true for x86 PVH dom0's (as RAM belonging to
+    other domains in the system don't live in a compatible address space), and
+    is ignored for ARM.
+
+*   The `map-inclusive` boolean is applicable to x86 PV dom0's, and sets up DMA
+    remapping for all non-RAM regions below 4GB except for unusable ranges.
+
+    Typically, some devices in a system use bits of RAM for communication, and
+    these areas should be listed via RMRR or IVMD entries in the APCI tables,
+    so Xen can ensure that they are identity-mapped in the IOMMU.  However,
+    some firmware makes mistakes writing its APCI tables, and this option is a
+    coarse-grain workaround for those errors.
+
+    Where possible, finer grain corrections should be made with the `rmrr=`,
+    `ivrs_hpet=` or `ivrs_ioapic=` command line options.
+
+    This option is enabled by default on x86 Intel systems, disabled by
+    default on other x86 systems, and invalid on ARM systems.
+
+*   The `map-reserved` functionality is very similar to `map-inclusive`, but is
+    applicable to both x86 PV and PVH dom0's, and represents a subset of the
+    correction by only mapping reserved memory regions rather than all non-RAM
+    regions.
+
+    This option is enabled by default on x86 Intel systems, disabled by
+    default on other x86 systems, and invalid on ARM systems.
 
 ### dom0\_ioports\_disable (x86)
 > `= List of <hex>-<hex>`
diff --git a/xen/arch/x86/dom0_build.c b/xen/arch/x86/dom0_build.c
index 54737da..85d4ff2 100644
--- a/xen/arch/x86/dom0_build.c
+++ b/xen/arch/x86/dom0_build.c
@@ -282,12 +282,6 @@ bool __initdata opt_dom0_shadow;
 #endif
 bool __initdata dom0_pvh;
 
-/*
- * List of parameters that affect Dom0 creation:
- *
- *  - pvh               Create a PVHv2 Dom0.
- *  - shadow            Use shadow paging for Dom0.
- */
 static int __init parse_dom0_param(const char *s)
 {
     const char *ss;
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel