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

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 17/01/2019 12:26, Jan Beulich wrote:
>>>> On 17.01.19 at 13:15, <andrew.cooper3@xxxxxxxxxx> wrote:
>> On 17/01/2019 11:20, Jan Beulich wrote:
>>>>>> On 16.01.19 at 20:51, <andrew.cooper3@xxxxxxxxxx> 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.
>>> But I'm not asking to omit the information. I'm asking to present it
>>> in a way understandable to anyone, irrespective of their Kconfig
>>> knowledge.
>> You have literally contradicted yourself in your two replies here.
>>
>> Your latest reply suggests that you didn't mean what you actually wrote
>> earlier.  If this is the case, please take more care to get your point
>> across clearly.
> Hmm, apologies, my use CONFIG_* above was indeed ambiguous
> without the context implied by "mentioned elsewhere". As "mentioned
> elsewhere" I'm fine with any form of wording that names the option
> without making it a primary part of the text, and without the CONFIG_
> prefix. As also said elsewhere (but perhaps due to not being a native
> speaker) I also dislike your use of "compiled out" (and its inverse).
> Both parts get addressed by either of Roger's suggestions.

I've switched to phrasing things as enabled/disabled rather than
compiled in/out.

However, the CONFIG_ prefixes are staying, because as said by myself and
others in this thread, they are critical for the understanding of
non-expert users, who won't be aware of implicitly dropping or adding
the prefix depending on circumstance.

~Andrew

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