On 17/01/2019 09:14, Juergen Gross wrote: > On 17/01/2019 10:08, Andrew Cooper wrote: >> On 17/01/2019 08:43, Roger Pau Monné wrote: >>> 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.coop...@citrix.com> 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. >> I have a rewrite of the head of the document pending anyway which I hope >> to get sorted properly for 4.12 >> >> While having a Kconfig: section would probably be fine for ~80% of the >> simple cases, it doesn't work for this patch. >> >> I guess the root of the issue is that I do not believe that phrasing the >> information like this makes it harder for non-expert users >> read/comprehend, and there definitely are a group of readers for which >> this information is relevant. > In any case I'd prefer to spell out the complete config option (e.g. > CONFIG_FOO) in case we ever get a way to read the config from the > running hypervisor (FWIW I'm just writing a series for doing that).
I think having a Xen equivalent of /proc/config.gz is a good move, irrespective of any documentation concerns. ~Andrew _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel
