Re: [Xen-devel] [PATCH v3 04/15] argo: init, destroy and soft-reset, with enable command line opt

["Jan Beulich" <JBeulich@xxxxxxxx>]

>>> On 15.01.19 at 10:06, <andrew.cooper3@xxxxxxxxxx> wrote:
> On 15/01/2019 09:01, Jan Beulich wrote:
>>>>> On 15.01.19 at 08:21, <christopher.w.clark@xxxxxxxxx> wrote:
>>> On Mon, Jan 14, 2019 at 6:58 AM Andrew Cooper <andrew.cooper3@xxxxxxxxxx> 
> wrote:
>>>> On 07/01/2019 07:42, Christopher Clark wrote:
>>>>> --- a/docs/misc/xen-command-line.pandoc
>>>>> +++ b/docs/misc/xen-command-line.pandoc
>>>>> @@ -182,6 +182,17 @@ Permit Xen to use "Always Running APIC Timer" 
>>>>> support 
> on compatible hardware
>>>>>  in combination with cpuidle.  This option is only expected to be useful 
>>>>> for
>>>>>  developers wishing Xen to fall back to older timing methods on newer 
> hardware.
>>>>>
>>>>> +### argo
>>>>> +> `= <boolean>`
>>>>> +
>>>>> +> Default: `false`
>>>>> +
>>>>> +Enable the Argo hypervisor-mediated interdomain communication mechanism.
>>>>> +
>>>>> +This allows domains access to the Argo hypercall, which supports 
> registration
>>>>> +of memory rings with the hypervisor to receive messages, sending 
>>>>> messages 
> to
>>>>> +other domains by hypercall and querying the ring status of other domains.
>>>> Please do include a note about CONFIG_ARGO.  I know this doc is
>>>> inconsistent on the matter (as Kconfig postdates the written entries
>>>> here), but I have been trying to fix up, and now about half of the
>>>> documentation does mention appropriate Kconfig information.
>>> Ack, note added.
>> Just to voice my view here: While I agree that some form of indication
>> should be added, I don't think CONFIG_ARGO should be mentioned.
>> CONFIG_* in general are likely meaningless to the main audience of
>> this file (admins rather than developers). Hence the wording should be
>> mostly independent of the precise config option name; there may then
>> be an annotation naming the option. Omitting the option name, otoh,
>> has the benefit of not bearing the risk of going stale.
> 
> I completely disagree.  The exact CONFIG_ name is very important for the
> end user who is looking at the documentation wondering "why can't I seem
> to enable ARGO?"
> 
> "This option is only available when CONFIG_ARGO is compiled in" isn't
> going to put anyone off reading the document, but is useful for some who
> are reading it.

But what's wrong with e.g. "The functionality this option controls is
dependent on a build time condition (the ARGO config option)"? This
avoids the technical detail in the main part of the statement. In
addition I'm also deliberately leaving out the CONFIG_ part of the
option name, as that's entirely an implementation detail.

In no case is "CONFIG_ARGO is compiled in" a sensible statement to
me - "CONFIG_ARGO" simply can't be "compiled in", it can only be
enabled or disabled, whereas what can be compiled in is the code
controlled by CONFIG_ARGO. (Caveat: I may wrongly apply too
much German interpretation here.)

Jan



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