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

From: Andrew Cooper <andrew.cooper3@citrix.com>
To: Jan Beulich <JBeulich@suse.com>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
	Wei Liu <wei.liu2@citrix.com>,
	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>,
	George Dunlap <George.Dunlap@eu.citrix.com>,
	Tim Deegan <tim@xen.org>, Julien Grall <julien.grall@arm.com>,
	xen-devel <xen-devel@lists.xenproject.org>,
	Ian Jackson <ian.jackson@citrix.com>
Subject: Re: [PATCH 2/2] docs: Introduce some hypercall page documentation
Date: Thu, 23 May 2019 13:02:30 +0100	[thread overview]
Message-ID: <e6814c96-cf1c-d28e-4a37-4a0072baa7e7@citrix.com> (raw)
In-Reply-To: <5CE686ED0200007800231AC4@prv1-mh.provo.novell.com>

On 23/05/2019 12:41, Jan Beulich wrote:
>>>> On 23.05.19 at 13:01, <andrew.cooper3@citrix.com> wrote:
>> On 23/05/2019 11:56, Jan Beulich wrote:
>>>>>> On 23.05.19 at 12:20, <andrew.cooper3@citrix.com> wrote:
>>>> This also introduced the top-level Guest Documentation section.
>>>>
>>>> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
>>> 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.

Nevertheless, the observation below does warrant some changes here.

>
> One other remark: Who's the intended audience?

Citing the patch:

> This documentation concerns the APIs and ABIs available to guests.  It is
> intended for OS developers trying to use a Xen feature, and for Xen
> developers
> to avoid breaking things.

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

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

That belongs in ARM's hypercall-abi.rst, not x86's, and it is this
observation which demonstrates that a path distinction is necessary.

~Andrew

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