Re: [Xen-devel] [PATCH 2/2] docs: Introduce some hypercall page documentation

["Jan Beulich" <JBeulich@xxxxxxxx>]

>>> On 23.05.19 at 14:02, <andrew.cooper3@xxxxxxxxxx> wrote:
> On 23/05/2019 12:41, Jan Beulich wrote:
>>>>> On 23.05.19 at 13:01, <andrew.cooper3@xxxxxxxxxx> wrote:
>>> On 23/05/2019 11:56, Jan Beulich wrote:
>>>>>>> On 23.05.19 at 12:20, <andrew.cooper3@xxxxxxxxxx> wrote:
>>>>> This also introduced the top-level Guest Documentation section.
>>>>>
>>>>> Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
>>>> Large parts of this are entirely x86-centric, yet hypercalls exist
>>>> for Arm as well. If this is intentional, then I think you should say
>>>> so above.
>>> It is all x86 specific, which is why it is grouped under "x86 guest
>>> documentation".
>> Neither the path nor anything near the top of the added file suggest
>> this is "x86 guest documentation". How is one to make this
>> connection? Or are you referring to the sole entry that ends up in
>> docs/guest-guide/index.rst?
> 
> Yes, and by the way you ask this question, I presume you haven't seen
> how sphinx renders it.

Nor do I think I should need to, for the purpose of reviewing
the change. I'm in particular concerned about further additions
here down the road, when it would then be even less visible
that this is x86-specific documentation.

> Nevertheless, the observation below does warrant some changes here.

Right - hence me mentioning "path" in my original reply.

>> People
>> writing code targeting the hypercall interface, I assume. This
>> includes people who may not at all be familiar with the AT&T
>> peculiarities of the assembly language used (mainly for
>> naming registers). It's easy for the to understand what is
>> meant nevertheless, but to be honest I'd prefer if the SDM /
>> PM register names were used instead, i.e. in particular
>> without the % prefixes (but also omitting the $ on the INT
>> operand).
> 
> While this case is, dropping the AT&T-isms is easy, I'm not convinced
> that will be the case elsewhere.
> 
> Also, I don't want us to be in a case where we develop exclusively with
> AT&T, but have our documentation written in Intel syntax.

For one I don't think documentation and source need to be
aligned in this regard. Aligning our documentation to that
of the CPU vendors seems more important to me. (That
said, in example code I think at least one of the two have
started mixing Intel and AT&T syntax.)

And then - can't we get away without using any assembly
syntax at all in documentation? Surely things can be worded
in a more abstract way (like "INT instruction with an immediate
of 0x82).

Jan



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