Re: [PATCH 1/3] docs: rSTify ppc-spapr-hcalls.txt

[David Gibson <david@gibson.dropbear.id.au>]

[-- Attachment #1: Type: text/plain, Size: 7204 bytes --]

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

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]