* [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt
@ 2021-12-08 16:59 lagarcia
2021-12-08 16:59 ` [PATCH 1/3] " lagarcia
` (3 more replies)
0 siblings, 4 replies; 11+ messages in thread
From: lagarcia @ 2021-12-08 16:59 UTC (permalink / raw)
To: qemu-ppc; +Cc: danielhb413, groug, qemu-devel, clg, Leonardo Garcia, david
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
^ permalink raw reply [flat|nested] 11+ messages in thread* [PATCH 1/3] docs: rSTify ppc-spapr-hcalls.txt 2021-12-08 16:59 [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt lagarcia @ 2021-12-08 16:59 ` lagarcia 2021-12-08 18:54 ` Daniel Henrique Barboza 2021-12-08 16:59 ` [PATCH 2/3] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst lagarcia ` (2 subsequent siblings) 3 siblings, 1 reply; 11+ messages in thread From: lagarcia @ 2021-12-08 16:59 UTC (permalink / raw) To: qemu-ppc; +Cc: danielhb413, groug, qemu-devel, clg, Leonardo Garcia, david 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 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH 1/3] docs: rSTify ppc-spapr-hcalls.txt 2021-12-08 16:59 ` [PATCH 1/3] " lagarcia @ 2021-12-08 18:54 ` Daniel Henrique Barboza 2021-12-09 1:07 ` David Gibson 0 siblings, 1 reply; 11+ messages in thread From: Daniel Henrique Barboza @ 2021-12-08 18:54 UTC (permalink / raw) To: lagarcia, qemu-ppc; +Cc: Leonardo Garcia, groug, david, qemu-devel, clg 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 > ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/3] docs: rSTify ppc-spapr-hcalls.txt 2021-12-08 18:54 ` Daniel Henrique Barboza @ 2021-12-09 1:07 ` David Gibson 2021-12-09 3:51 ` Warner Losh 2021-12-09 7:56 ` Cédric Le Goater 0 siblings, 2 replies; 11+ messages in thread From: David Gibson @ 2021-12-09 1:07 UTC (permalink / raw) To: Daniel Henrique Barboza Cc: lagarcia, groug, qemu-devel, qemu-ppc, clg, Leonardo Garcia [-- 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 --] ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/3] docs: rSTify ppc-spapr-hcalls.txt 2021-12-09 1:07 ` David Gibson @ 2021-12-09 3:51 ` Warner Losh 2021-12-09 7:56 ` Cédric Le Goater 1 sibling, 0 replies; 11+ messages in thread From: Warner Losh @ 2021-12-09 3:51 UTC (permalink / raw) To: David Gibson Cc: Daniel Henrique Barboza, lagarcia, Greg Kurz, QEMU Developers, qemu-ppc, clg, Leonardo Garcia [-- 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 --] ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/3] docs: rSTify ppc-spapr-hcalls.txt 2021-12-09 1:07 ` David Gibson 2021-12-09 3:51 ` Warner Losh @ 2021-12-09 7:56 ` Cédric Le Goater 1 sibling, 0 replies; 11+ messages in thread From: Cédric Le Goater @ 2021-12-09 7:56 UTC (permalink / raw) To: David Gibson, Daniel Henrique Barboza Cc: Leonardo Garcia, lagarcia, qemu-ppc, qemu-devel, groug >>> -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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 2/3] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst. 2021-12-08 16:59 [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt lagarcia 2021-12-08 16:59 ` [PATCH 1/3] " lagarcia @ 2021-12-08 16:59 ` lagarcia 2021-12-08 18:57 ` Daniel Henrique Barboza 2021-12-08 16:59 ` [PATCH 3/3] Link new ppc-spapr-hcalls.rst file to pseries.rst lagarcia 2021-12-15 16:41 ` [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt Cédric Le Goater 3 siblings, 1 reply; 11+ messages in thread From: lagarcia @ 2021-12-08 16:59 UTC (permalink / raw) To: qemu-ppc; +Cc: danielhb413, groug, qemu-devel, clg, Leonardo Garcia, david 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 2/3] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst. 2021-12-08 16:59 ` [PATCH 2/3] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst lagarcia @ 2021-12-08 18:57 ` Daniel Henrique Barboza 0 siblings, 0 replies; 11+ messages in thread From: Daniel Henrique Barboza @ 2021-12-08 18:57 UTC (permalink / raw) To: lagarcia, qemu-ppc; +Cc: Leonardo Garcia, groug, david, qemu-devel, clg 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 > ^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 3/3] Link new ppc-spapr-hcalls.rst file to pseries.rst. 2021-12-08 16:59 [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt lagarcia 2021-12-08 16:59 ` [PATCH 1/3] " lagarcia 2021-12-08 16:59 ` [PATCH 2/3] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst lagarcia @ 2021-12-08 16:59 ` lagarcia 2021-12-08 18:58 ` Daniel Henrique Barboza 2021-12-15 16:41 ` [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt Cédric Le Goater 3 siblings, 1 reply; 11+ messages in thread From: lagarcia @ 2021-12-08 16:59 UTC (permalink / raw) To: qemu-ppc; +Cc: danielhb413, groug, qemu-devel, clg, Leonardo Garcia, david 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 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH 3/3] Link new ppc-spapr-hcalls.rst file to pseries.rst. 2021-12-08 16:59 ` [PATCH 3/3] Link new ppc-spapr-hcalls.rst file to pseries.rst lagarcia @ 2021-12-08 18:58 ` Daniel Henrique Barboza 0 siblings, 0 replies; 11+ messages in thread From: Daniel Henrique Barboza @ 2021-12-08 18:58 UTC (permalink / raw) To: lagarcia, qemu-ppc; +Cc: Leonardo Garcia, groug, david, qemu-devel, clg 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``). > ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt 2021-12-08 16:59 [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt lagarcia ` (2 preceding siblings ...) 2021-12-08 16:59 ` [PATCH 3/3] Link new ppc-spapr-hcalls.rst file to pseries.rst lagarcia @ 2021-12-15 16:41 ` Cédric Le Goater 3 siblings, 0 replies; 11+ messages in thread From: Cédric Le Goater @ 2021-12-15 16:41 UTC (permalink / raw) To: lagarcia, qemu-ppc; +Cc: Leonardo Garcia, groug, danielhb413, qemu-devel, david 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2021-12-15 16:51 UTC | newest] Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-12-08 16:59 [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt lagarcia 2021-12-08 16:59 ` [PATCH 1/3] " lagarcia 2021-12-08 18:54 ` Daniel Henrique Barboza 2021-12-09 1:07 ` David Gibson 2021-12-09 3:51 ` Warner Losh 2021-12-09 7:56 ` Cédric Le Goater 2021-12-08 16:59 ` [PATCH 2/3] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst lagarcia 2021-12-08 18:57 ` Daniel Henrique Barboza 2021-12-08 16:59 ` [PATCH 3/3] Link new ppc-spapr-hcalls.rst file to pseries.rst lagarcia 2021-12-08 18:58 ` Daniel Henrique Barboza 2021-12-15 16:41 ` [PATCH 0/3] docs: rSTify ppc-spapr-hcalls.txt Cédric Le Goater
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.