[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Xen-devel] [PATCH 2/2] docs: Introduce some hypercall page documentation
>>> 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
|
Lists.xenproject.org is hosted with RackSpace, monitoring our |