Re: [Xen-devel] [PATCH v3 1/7] docs: Improve documentation for dom0= and dom0-iommu=

[Roger Pau Monné <roger.pau@xxxxxxxxxx>]

On Wed, Jan 16, 2019 at 07:51:33PM +0000, Andrew Cooper wrote:
> On 16/01/2019 11:52, Jan Beulich wrote:
> >>>> On 16.01.19 at 10:00, <andrew.cooper3@xxxxxxxxxx> wrote:
> >> --- a/docs/misc/xen-command-line.pandoc
> >> +++ b/docs/misc/xen-command-line.pandoc
> >> @@ -636,61 +636,83 @@ trace feature is only enabled in debugging builds of 
> >> Xen.
> >>  
> >>  Specify the bit width of the DMA heap.
> >>  
> >> -### dom0 (x86)
> >> -> `= List of [ pvh | shadow | verbose ]`
> >> +### dom0
> >> +    = List of [ pvh=<bool>, shadow=<bool>, verbose=<bool> ]
> >>  
> >> -> Sub-options:
> >> +    Applicability: x86
> >>  
> >> -> `pvh`
> >> +Controls for how dom0 is constructed on x86 systems.
> >>  
> >> -> Default: `false`
> >> +*   The `pvh` boolean controls whether dom0 is constructed as a PV or a 
> >> PVH
> >> +    guest.  The default is PV.  In addition, the following requirements 
> >> must
> >> +    be met:
> >>  
> >> -Flag that makes a dom0 boot in PVHv2 mode.
> >> +    *   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.
> >>  
> >> -> `shadow`
> >> +*   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.
> >>  
> >> -> Default: `false`
> >> +    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.
> > As mentioned elsewhere, I object to adding CONFIG_* into this doc,
> > which is intended to be meaningful to non-developers. But not to the
> > degree of NAK-ing the whole thing, if everyone else disagrees with me.
> 
> I'm not sure what else to say.  I object to purposefully omitting
> relevant information from our documentation.

Maybe it would be helpful to add some kind of tag that could
standardize the relationship between Kconfig options and command line
options?

    Kconfig: SHADOW_PAGING

Or similar. This would get the specific Kconfig details out of the
general description of the functionality, thus not harming readability
by non-expert users?

Using such tag would require some explanation of it's meaning at the
top of the document.

> Most people reading it, including non-developers, will know what Kconfig
> is and how to check, owing to at least a basic knowledge of Linux. 
> Those that don't will be capable of basic human interaction such as
> asking a question of someone more knowledgeable.

If the above is not suitable, I might suggest to reword the sentence
as:

"This option is unavailable when the Kconfig `SHADOW_PAGING` option is
not selected at build time."

Explicitly mentioning Kconfig and selected simplifies the language for
non-expert users IMO, and makes it clear this is exclusively a build
time decision. Note I'm not a native speaker, so my sense of easier to
understand could be completely wrong.

Thanks, Roger.

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