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

["Jan Beulich" <JBeulich@xxxxxxxx>]

>>> 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?

One other remark: Who's the intended audience? 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).

> As for future plans, the actual hypercalls will live in the architecture
> neutral guest documentation section.
> 
> ARM doesn't actually use anything here, because they have a single
> spec-defined instruction for making hypercalls which exists in all
> virt-capable hardware.

But register usage would still be relevant to describe, even if
it may just be by stating that it matches a certain ABI defined
elsewhere.

Jan



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