[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 1/3] docs: rSTify ppc-spapr-hcalls.txt
From: |
David Gibson |
Subject: |
Re: [PATCH 1/3] docs: rSTify ppc-spapr-hcalls.txt |
Date: |
Thu, 9 Dec 2021 12:07:56 +1100 |
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
signature.asc
Description: PGP signature