On Wed, Dec 8, 2021 at 6:51 PM David Gibson wrote: > On Wed, Dec 08, 2021 at 03:54:40PM -0300, Daniel Henrique Barboza wrote: > > > > > > On 12/8/21 13:59, lagarcia@linux.ibm.com wrote: > > > From: Leonardo Garcia > > > > > > Signed-off-by: Leonardo Garcia > > > --- > > > docs/specs/ppc-spapr-hcalls.txt | 92 > ++++++++++++++++++++------------- > > > 1 file changed, 57 insertions(+), 35 deletions(-) > > > > > > diff --git a/docs/specs/ppc-spapr-hcalls.txt > b/docs/specs/ppc-spapr-hcalls.txt > > > index 93fe3da91b..c69dae535b 100644 > > > --- a/docs/specs/ppc-spapr-hcalls.txt > > > +++ b/docs/specs/ppc-spapr-hcalls.txt > > > @@ -1,9 +1,15 @@ > > > -When used with the "pseries" machine type, QEMU-system-ppc64 > implements > > > -a set of hypervisor calls using a subset of the server "PAPR" > specification > > > -(IBM internal at this point), which is also what IBM's proprietary > hypervisor > > > -adheres too. > > > +sPAPR hypervisor calls > > > +---------------------- > > > -The subset is selected based on the requirements of Linux as a guest. > > > +When used with the ``pseries`` machine type, ``qemu-system-ppc64`` > implements > > > +a set of hypervisor calls (a.k.a. hcalls) defined in the `Linux on > Power > > > +Architecture Reference document (LoPAR) > > > +< > https://cdn.openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf > >`_. > > > +This document is a subset of the Power Architecture Platform > Reference (PAPR+) > > > +specification (IBM internal only), which is what PowerVM, the IBM > proprietary > > > +hypervisor, adheres to. > > > + > > > +The subset in LoPAR is selected based on the requirements of Linux as > a guest. > > > In addition to those calls, we have added our own private hypervisor > > > calls which are mostly used as a private interface between the > firmware > > > @@ -12,13 +18,14 @@ running in the guest and QEMU. > > > All those hypercalls start at hcall number 0xf000 which correspond > > > to an implementation specific range in PAPR. > > > -- H_RTAS (0xf000) > > > +H_RTAS (0xf000) > > > +^^^^^^^^^^^^^^^ > > > -RTAS is a set of runtime services generally provided by the firmware > > > -inside the guest to the operating system. It predates the existence > > > -of hypervisors (it was originally an extension to Open Firmware) and > > > -is still used by PAPR to provide various services that aren't > performance > > > -sensitive. > > > +RTAS stands for Run-Time Abstraction Sercies and is a set of runtime > services > > > +generally provided by the firmware inside the guest to the operating > system. It > > > +predates the existence of hypervisors (it was originally an extension > to Open > > > +Firmware) and is still used by PAPR and LoPAR to provide various > services that > > > +are not performance sensitive. > > > We currently implement the RTAS services in QEMU itself. The actual > RTAS > > > "firmware" blob in the guest is a small stub of a few instructions > which > > > @@ -26,22 +33,25 @@ calls our private H_RTAS hypervisor call to pass > the RTAS calls to QEMU. > > > Arguments: > > > - r3 : H_RTAS (0xf000) > > > - r4 : Guest physical address of RTAS parameter block > > > + ``r3``: ``H_RTAS (0xf000)`` > > > + > > > + ``r4``: Guest physical address of RTAS parameter block. > > > Returns: > > > - H_SUCCESS : Successfully called the RTAS function (RTAS result > > > - will have been stored in the parameter block) > > > - H_PARAMETER : Unknown token > > > + ``H_SUCCESS``: Successfully called the RTAS function (RTAS result > will have > > > + been stored in the parameter block). > > > -- H_LOGICAL_MEMOP (0xf001) > > > + ``H_PARAMETER``: Unknown token. > > > -When the guest runs in "real mode" (in powerpc lingua this means > > > -with MMU disabled, ie guest effective == guest physical), it only > > > -has access to a subset of memory and no IOs. > > > +H_LOGICAL_MEMOP (0xf001) > > > +^^^^^^^^^^^^^^^^^^^^^^^^ > > > -PAPR provides a set of hypervisor calls to perform cacheable or > > > +When the guest runs in "real mode" (in powerpc lingua this means with > MMU > > > > What's up with 'lingua'? As you already know "lingua" is Brazilian > portuguese for "tongue" > > and it's so weird to be used in this context. > > > > The one English word that I can think of that is closer to "lingua" and > would make sense here > > is 'lingo'. But that is a slang for 'jargon' and not appropriate for a > technical document > > either. "langua" as a short form of "language" seems weird as well. I > really believe 'jargon' > > is a more suitable word here. > > As a native speaker: "lingo" would make sense here, though its tone is > a little informal. "jargon" could also work, but "terminology" would > probably better match the tone of the document. > > I expect this hasn't been noticed before, because I think most English > speakers would read "lingua" as a typo for "lingo", maybe only barely > registering that it was not the standard spelling. ("lingo" is, of > course, cognate with lingua and similar words from romance langauges). > My google search turns up exactly 1 other hit for 'powerpc lingua' so it's not a wide spread thing. In fact, it is in our archives when this commit was made to the text file as near as I can tell. As such, the phrase should be 'in powerpc terminology' or 'in powerpc jargon' to make sense to a native English speaker. 'linga' doesn't make sense in English (though we do have the loan phrase 'lingua franca' meaning 'the common language' derived from the common language of the Levant made up of a hodge-podge of other languages. Another phrase that would make sense, but is a bit of an uncommon usage, is 'powerpc parlance' which might capture the right nuance of meaning here better than the other suggestions. > > This was added by c73e3771ea79ab and I really believe this is an > unintended typo/mistake. If > > you're feeling generous feel free to send an extra patch (you can send > an independent patch, > > or another patch on top of this series, your call) changing this > 'lingua' instance to something > > more appropriate. > Yes. The original review for that was the only other place google can find this turn of phrase. I'd thought it might be a pun on lingua franca (eg 'lingua powerpc' was an in joke in that community, but google says no). Warner > > Since this is not this patch fault: > > > > Reviewed-by: Daniel Henrique Barboza > > > > > > > > > > > +disabled, i.e. guest effective address equals to guest physical > address), it > > > +only has access to a subset of memory and no I/Os. > > > + > > > +PAPR and LoPAR provides a set of hypervisor calls to perform > cacheable or > > > non-cacheable accesses to any guest physical addresses that the > > > guest can use in order to access IO devices while in real mode. > > > @@ -58,21 +68,33 @@ is used by our SLOF firmware to invert the screen. > > > Arguments: > > > - r3: H_LOGICAL_MEMOP (0xf001) > > > - r4: Guest physical address of destination > > > - r5: Guest physical address of source > > > - r6: Individual element size > > > - 0 = 1 byte > > > - 1 = 2 bytes > > > - 2 = 4 bytes > > > - 3 = 8 bytes > > > - r7: Number of elements > > > - r8: Operation > > > - 0 = copy > > > - 1 = xor > > > + ``r3 ``: ``H_LOGICAL_MEMOP (0xf001)`` > > > + > > > + ``r4``: Guest physical address of destination. > > > + > > > + ``r5``: Guest physical address of source. > > > + > > > + ``r6``: Individual element size, defined by the binary logarithm of > the > > > + desired size. Supported values are: > > > + > > > + ``0`` = 1 byte > > > + > > > + ``1`` = 2 bytes > > > + > > > + ``2`` = 4 bytes > > > + > > > + ``3`` = 8 bytes > > > + > > > + ``r7``: Number of elements. > > > + > > > + ``r8``: Operation. Supported values are: > > > + > > > + ``0``: copy > > > + > > > + ``1``: xor > > > Returns: > > > - H_SUCCESS : Success > > > - H_PARAMETER : Invalid argument > > > + ``H_SUCCESS``: Success. > > > + ``H_PARAMETER``: Invalid argument. > > > \ No newline at end of file > > > > > > > -- > David Gibson | I'll have my music baroque, and my code > david AT gibson.dropbear.id.au | minimalist, thank you. NOT _the_ > _other_ > | _way_ _around_! > http://www.ozlabs.org/~dgibson >