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

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

[lagarcia]

From: Leonardo Garcia <lagarcia@br.ibm.com>

Along with this change, hook the new rst file into the pseries
documentation.

Leonardo Garcia (3):
  docs: rSTify ppc-spapr-hcalls.txt
  docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst.
  Link new ppc-spapr-hcalls.rst file to pseries.rst.

 docs/specs/ppc-spapr-hcalls.rst | 100 ++++++++++++++++++++++++++++++++
 docs/specs/ppc-spapr-hcalls.txt |  78 -------------------------
 docs/system/ppc/pseries.rst     |   2 +-
 3 files changed, 101 insertions(+), 79 deletions(-)
 create mode 100644 docs/specs/ppc-spapr-hcalls.rst
 delete mode 100644 docs/specs/ppc-spapr-hcalls.txt

-- 
2.33.1

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

[lagarcia]

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
+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
-- 
2.33.1

[PATCH 2/3] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst.

[lagarcia]

From: Leonardo Garcia <lagarcia@br.ibm.com>

Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
---
 docs/specs/{ppc-spapr-hcalls.txt => ppc-spapr-hcalls.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/specs/{ppc-spapr-hcalls.txt => ppc-spapr-hcalls.rst} (100%)

diff --git a/docs/specs/ppc-spapr-hcalls.txt b/docs/specs/ppc-spapr-hcalls.rst
similarity index 100%
rename from docs/specs/ppc-spapr-hcalls.txt
rename to docs/specs/ppc-spapr-hcalls.rst
-- 
2.33.1

[PATCH 3/3] Link new ppc-spapr-hcalls.rst file to pseries.rst.

[lagarcia]

From: Leonardo Garcia <lagarcia@br.ibm.com>

Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
---
 docs/system/ppc/pseries.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst
index e46f09d4c8..56f5942e13 100644
--- a/docs/system/ppc/pseries.rst
+++ b/docs/system/ppc/pseries.rst
@@ -113,12 +113,12 @@ can  also be found in QEMU documentation:
 .. toctree::
    :maxdepth: 1
 
+   ../../specs/ppc-spapr-hcalls.rst
    ../../specs/ppc-spapr-numa.rst
    ../../specs/ppc-spapr-xive.rst
 
 Other documentation available in QEMU docs directory:
 
-* Hypervisor calls (a.k.a. hcalls) (``docs/specs/ppc-spapr-hcalls.txt``).
 * Hot plug (``/docs/specs/ppc-spapr-hotplug.txt``).
 * Hypervisor calls needed by the Ultravisor
   (``/docs/specs/ppc-spapr-uv-hcalls.txt``).
-- 
2.33.1

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

[Daniel Henrique Barboza]

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.

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
> 

Re: [PATCH 2/3] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst.

[Daniel Henrique Barboza]

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

Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>


>   docs/specs/{ppc-spapr-hcalls.txt => ppc-spapr-hcalls.rst} | 0
>   1 file changed, 0 insertions(+), 0 deletions(-)
>   rename docs/specs/{ppc-spapr-hcalls.txt => ppc-spapr-hcalls.rst} (100%)
> 
> diff --git a/docs/specs/ppc-spapr-hcalls.txt b/docs/specs/ppc-spapr-hcalls.rst
> similarity index 100%
> rename from docs/specs/ppc-spapr-hcalls.txt
> rename to docs/specs/ppc-spapr-hcalls.rst
> 

Re: [PATCH 3/3] Link new ppc-spapr-hcalls.rst file to pseries.rst.

[Daniel Henrique Barboza]

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

Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>

>   docs/system/ppc/pseries.rst | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst
> index e46f09d4c8..56f5942e13 100644
> --- a/docs/system/ppc/pseries.rst
> +++ b/docs/system/ppc/pseries.rst
> @@ -113,12 +113,12 @@ can  also be found in QEMU documentation:
>   .. toctree::
>      :maxdepth: 1
>   
> +   ../../specs/ppc-spapr-hcalls.rst
>      ../../specs/ppc-spapr-numa.rst
>      ../../specs/ppc-spapr-xive.rst
>   
>   Other documentation available in QEMU docs directory:
>   
> -* Hypervisor calls (a.k.a. hcalls) (``docs/specs/ppc-spapr-hcalls.txt``).
>   * Hot plug (``/docs/specs/ppc-spapr-hotplug.txt``).
>   * Hypervisor calls needed by the Ultravisor
>     (``/docs/specs/ppc-spapr-uv-hcalls.txt``).
> 

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

[David Gibson]

[-- 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 --]

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

[Warner Losh]

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

On Wed, Dec 8, 2021 at 6:51 PM David Gibson <david@gibson.dropbear.id.au>
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 <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
>

[-- Attachment #2: Type: text/html, Size: 11475 bytes --]

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

[Cédric Le Goater]

>>> -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 changed it to terminology. No need to resend !

Thanks,

C.

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

[Cédric Le Goater]

On 12/8/21 17:59, lagarcia@linux.ibm.com wrote:
> From: Leonardo Garcia <lagarcia@br.ibm.com>
> 
> Along with this change, hook the new rst file into the pseries
> documentation.
> 
Applied to ppc-next.

Thanks,

C.