Re: [PATCH] docs/system: Document running Linux on amigaone machine

[BALATON Zoltan <balaton@eik.bme.hu>]

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

On Sat, 16 Dec 2023, Bernhard Beschow wrote:
> Am 16. Dezember 2023 12:53:55 UTC schrieb BALATON Zoltan <balaton@eik.bme.hu>:
>> On Sat, 16 Dec 2023, Bernhard Beschow wrote:
>>> Documentation on how to run Linux on the amigaone machine is currently burried
>>> in the depths of the qemu-devel mailing list [1] and in the source code. Let's
>>> collect the information in the QEMU handbook for a one stop solution.
>>
>> Thanks for collecting this info and adding it as documentation.
>
> You're welcome!
>
>> A few small comments bellow.
>>
>>> [1] https://lore.kernel.org/qemu-devel/dafc407d-3749-e6f4-3a66-750fde8965f9@eik.bme.hu/
>>
>> Do we want to keep an URL in the commit log? kernel.org is quite stable but not sure it would need to be in the commit message.
>
> Let's drop it.
>
>>
>>> Co-authored-by: BALATON Zoltan <balaton@eik.bme.hu>
>>> Signed-off-by: Bernhard Beschow <shentey@gmail.com>
>>> ---
>>> MAINTAINERS                  |  1 +
>>> docs/system/ppc/amigaone.rst | 53 ++++++++++++++++++++++++++++++++++++
>>> docs/system/target-ppc.rst   |  1 +
>>> hw/ppc/amigaone.c            |  9 ------
>>> 4 files changed, 55 insertions(+), 9 deletions(-)
>>> create mode 100644 docs/system/ppc/amigaone.rst
>>>
>>> diff --git a/MAINTAINERS b/MAINTAINERS
>>> index 695e0bd34f..a2dd1407e2 100644
>>> --- a/MAINTAINERS
>>> +++ b/MAINTAINERS
>>> @@ -1560,6 +1560,7 @@ amigaone
>>> M: BALATON Zoltan <balaton@eik.bme.hu>
>>> L: qemu-ppc@nongnu.org
>>> S: Maintained
>>> +F: docs/system/ppc/amigaone.rst
>>> F: hw/ppc/amigaone.c
>>> F: hw/pci-host/articia.c
>>> F: include/hw/pci-host/articia.h
>>> diff --git a/docs/system/ppc/amigaone.rst b/docs/system/ppc/amigaone.rst
>>> new file mode 100644
>>> index 0000000000..c3f11a7bb2
>>> --- /dev/null
>>> +++ b/docs/system/ppc/amigaone.rst
>>
>> Maybe call it amigang.rst so it can be a place for docs on other PPC AmigaNG machines such as pegasos2 and sam460ex in the future to collect them in one place.
>
> Having everything in one place seems like creating a lot of complexity 
> if one were to elaborate on the various pros and cons for each machine: 
> AmigaOne needs a custom vgabios, the others do not.

All of these need real mode VGA BIOS as the BIOS emulator in all three 
machines choke on the gcc compiled QEMU VGA BIOS so this isn't uinque to 
amigaone.

> MorpOS can be run on 
> the other machines but not on AmigaOne. Sometimes a bootloader is needed 
> and sometimes not, the circumstances may vary.

MorphOS does not support amigaone, boot loader is optional and alternative 
to using firmware.

Other docs seem to combine similar machines like powermac and embedded and 
ppce500 in a single doc file so the convention seems to not have one file 
for each machine but it's not a big deal.

> I suggest to have a separate doc on each machine.

I could also rename it later if more docs is added for other machines.

>>> @@ -0,0 +1,53 @@
>>> +Eyetech AmigaOne/Mai Logic Teron (``amigaone``)
>>> +===============================================
>>> +
>>> +The ``amigaone`` model emulates an AmigaOne XE mainboard developed by Eyetech. Use
>>> +the executable ``qemu-system-ppc`` to simulate a complete system.
>>
>> QEMU is not a simulator so even if that's repeating this should say emulate. (Should this doc be formatted with 80 chars line too like sources?)
>
> I took heavy inspiration from the cupieboard machine. Feel free to change.

docs/system/arm/cubieboard.rst:
"The ``cubieboard`` model emulates the Cubietech Cubieboard,"
also says emulate not simulate.

>>> +
>>> +Emulated devices
>>> +----------------
>>> +
>>> + *  PowerPC 7457 v1.2 CPU
>>> + *  Articia S north bridge
>>> + *  VT82C686B south bridge
>>> + *  PCI VGA compatible card
>>> +
>>> +
>>> +Preparation
>>> +-----------
>>> +
>>> +A firmware binary is necessary for the boot process and is available at
>>> +https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=28.
>>> +It needs to be extracted with the following command:
>>> +
>>> +.. code-block:: bash
>>> +
>>> +  $ tail -c 524288 updater.image > u-boot-amigaone.bin
>>> +
>>> +The firmware binary is unable to run QEMU‘s standard vgabios and
>>> +``VGABIOS-lgpl-latest.bin`` is needed instead. It can be downloaded from
>>> +http://www.nongnu.org/vgabios.
>>> +
>>> +
>>> +Running Linux
>>> +-------------
>>> +
>>> +There are some Linux images under the following link that work on the
>>> +``amigaone`` machine:
>>> +https://sourceforge.net/projects/amigaone-linux/files/debian-installer/. To boot
>>> +the system run:
>>> +
>>> +.. code-block:: bash
>>> +
>>> +  $ qemu-system-ppc -M amigaone -bios u-boot-amigaone.bin \
>>> +                    -cdrom "A1 Linux Net Installer.iso" \
>>> +                    -device ati-vga,model=rv100,romfile=VGABIOS-lgpl-latest.bin
>>> +
>>> +From the firmware menu that appears select ``Boot sequence`` →
>>> +``Amiga Multiboot Options`` and set ``Boot device 1`` to
>>> +``Onboard VIA IDE CDROM``. Then hit escape until the main screen appears again,
>>> +hit escape once more and from the exit menu that appears select either
>>> +``Save settings and exit`` or ``Use settings for this session only``. It may
>>> +take a long time loading the kernel into memory but eventually it boots and the
>>> +installer becomes visible.
>>> diff --git a/docs/system/target-ppc.rst b/docs/system/target-ppc.rst
>>> index 4f6eb93b17..c1daa463cf 100644
>>> --- a/docs/system/target-ppc.rst
>>> +++ b/docs/system/target-ppc.rst
>>> @@ -18,6 +18,7 @@ help``.
>>>    :maxdepth: 1
>>>
>>>    ppc/embedded
>>> +   ppc/amigaone
>>>    ppc/powermac
>>>    ppc/powernv
>>>    ppc/ppce500
>>> diff --git a/hw/ppc/amigaone.c b/hw/ppc/amigaone.c
>>> index ddfa09457a..4f680a5bdd 100644
>>> --- a/hw/ppc/amigaone.c
>>> +++ b/hw/ppc/amigaone.c
>>> @@ -27,15 +27,6 @@
>>>
>>> #define BUS_FREQ_HZ 100000000
>>>
>>> -/*
>>> - * Firmware binary available at
>>> - * https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=28
>>> - * then "tail -c 524288 updater.image >u-boot-amigaone.bin"
>>> - *
>>> - * BIOS emulator in firmware cannot run QEMU vgabios and hangs on it, use
>>> - * -device VGA,romfile=VGABIOS-lgpl-latest.bin
>>> - * from http://www.nongnu.org/vgabios/ instead.
>>> - */
>>
>> Maybe it's worth keeping the comment here in case somebody reads the source but not documentation.
>
> Maybe change the comment to point at the doc to avoid duplication?

That could work too.

>> Do you want to send a v2 or want me to take over and do it myself?
>
> Sure, feel free to take over!

OK, I'll try to make a v2 then.

Regards,
BALATON Zoltan