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

[BALATON Zoltan]

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

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

> @@ -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?)

> +
> +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. Do you want to send a v2 or want me to take 
over and do it myself?

Regards,
BALATON Zoltan