Re: [RFC PATCH qemu] spapr/docs: Add a few words about x-vof

[Alexey Kardashevskiy]

On 5/12/22 23:40, Daniel Henrique Barboza wrote:
> On 5/12/22 00:10, Alexey Kardashevskiy wrote:
> > On 5/12/22 06:42, Daniel Henrique Barboza wrote:
> > > On 5/6/22 02:51, Alexey Kardashevskiy wrote:
> > > > The alternative small firmware needs a few words of what it can and
> > > > absolutely cannot do; this adds those words.
> > > >
> > > > Signed-off-by: Alexey Kardashevskiy <aik@ozlabs.ru>
> > > > ---
> > > >   docs/system/ppc/pseries.rst | 28 ++++++++++++++++++++++++++++
> > > >   1 file changed, 28 insertions(+)
> > > >
> > > > diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst
> > > > index d9b65ad4e850..4c98a94f9add 100644
> > > > --- a/docs/system/ppc/pseries.rst
> > > > +++ b/docs/system/ppc/pseries.rst
> > > > @@ -32,14 +32,42 @@ Missing devices
> > > >   Firmware
> > > >   ========
> > > > +The pSeries platform in QEMU comes with 2 firmwares:
> > > > +
> > > >   `SLOF <https://github.com/aik/SLOF>`_ (Slimline Open Firmware) is an
> > > >   implementation of the `IEEE 1275-1994, Standard for Boot 
> > > > (Initialization
> > > >   Configuration) Firmware: Core Requirements and Practices
> > > >   <https://standards.ieee.org/standard/1275-1994.html>`_.
> > > > +SLOF performs bus scanning, PCI resource allocation, provides the 
> > > > client
> > > > +interface to boot from block devices and network.
> > > > +
> > > >   QEMU includes a prebuilt image of SLOF which is updated when a 
> > > > more recent
> > > >   version is required.
> > > > +VOF (Virtual Open Firmware) is a minimalistic firmware to work with
> > > > +``-machine pseries,x-vof=on``. When enabled, the firmware acts as a 
> > > > slim
> > > > +shim and QEMU implements parts of the IEEE 1275 Open Firmware 
> > > > interface.
> > > > +
> > > > +VOF does not have device drivers, does not do PCI resource 
> > > > allocation and
> > > > +relies on ``-kernel`` used with Linux kernels recent enough (v5.4+)
> > > > +to PCI resource assignment. It is ideal to use with petitboot.
> > > > +
> > > > +Booting via ``-kernel`` supports the following:
> > > > ++-------------------+-------------------+------------------+
> > > > +| kernel            | pseries,x-vof=off | pseries,x-vof=on |
> > > > ++===================+===================+==================+
> > > > +| vmlinux BE        |     ✓             |     ✓            |
> > > > ++-------------------+-------------------+------------------+
> > > > +| vmlinux LE        |     ✓             |     ✓            |
> > > > ++-------------------+-------------------+------------------+
> > > > +| zImage.pseries BE |     x             |     ✓¹           |
> > > > ++-------------------+-------------------+------------------+
> > > > +| zImage.pseries LE |     ✓             |     ✓            |
> > > > ++-------------------+-------------------+------------------+
> > >
> > > You need an empty line at the start and at the end of the table. 
> > > Otherwise it'll
> > > be rendered as regular text.
> >
> > How do you build htmls from these btw?
>
> Had to do this yesterday because I changed machines recently. In a 
> Fedora 35
> system I did this:
>
>
> sudo dnf install python3-sphinx
> sudo dnf install python-sphinx_rtd_theme-doc
> pip install sphinx_rtd_theme


I only needed the last one, compiles htmls now. I was trying to figure 
out in Makefiles where is that "html" target and I just could not :)


> (not sure if all steps are needed)
>
> Then the generated docs will be under build/docs/manual .
>
>
> > > > +Notes:
> > >
> > > I also don't believe you need the "Notes:" addendum here. It's clear 
> > > that you're
> > > making an observation about the zImage.pseries BE and x-vof=on case.
> >
> > But only this combination needs kernel-addr=0, other images do not 
> > need that with SLOF or VOF.
>
>
> I mentioned about the "Notes:" string. We can remove it and leave just the
>
> +¹ must set kernel-addr=0
>
>
> Since it's clear that you're making a note about that item in the table.
>
>
>
> > > Everything else LGTM. If no one else has any comment, and you're ok 
> > > with these
> > > changes I mentioned, I can amend it myself with my R-b.
> >
> > I'll probably repost after the other patch with kernel-addr is merged 
> > into your tree. Thanks,
>
> I already picked it (just waiting some tests to finish). But feel free to
> send a v2 if you want to play around generating the docs to see how
> your patch looks like in the finished HTML.


Nah, the changes you made are fine so I am not planning on posting 
another version. Thanks for fixing it up.


> Thanks,
>
>
> Daniel
>
> > > Thanks,
> > >
> > >
> > > Daniel
> > >
> > >
> > > > +¹ must set kernel-addr=0
> > > > +
> > > >   Build directions
> > > >   ================

--
Alexey