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