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 <lagarcia@br.ibm.com>
> >
> > Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
> > ---
> > 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 <danielhb413@gmail.com>
>
>
>
>
> > +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