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

[Daniel Henrique Barboza <danielhb413@gmail.com>]

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

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


Thanks,


Daniel

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