Re: [PATCH 08/11] arm: virt: create GWDT watchdog paired with WDAT ACPI table

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Fri, 27 Feb 2026 at 14:51, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > On Fri, 27 Feb 2026 at 12:10, Markus Armbruster <armbru@redhat.com> wrote:
>> >> The larger problem is that we generally fail at documenting device and
>> >> machine properties.  I'm not asking you to boil that ocean :)
>> >>
>> >> The narrow problem is providing guidance on watchdog configuration.
>> >> What and where?
>> >>
>> >> Regarding where: you proposed to add a machine property of QAPI enum
>> >> type.
>> >>
>> >> The property can have a description, and you give it one.  Sadly, it's
>> >> basically invisible.  As far as I know, the only way you can get at it
>> >> is qom-list-properties and such.  I doubt anybody is going to read the
>> >> description there.
>> >
>> > I think it also will appear if you run e.g.
>> >  qemu-system-arm -M virt,help
>> >
>> > (which produces a list of all properties with their short descriptions)
>>
>> You're right!
>>
>> > For board-specific properties, we should be documenting these in
>> > the manual page for the board. For instance "virt" does that here:
>> >  https://www.qemu.org/docs/master/system/arm/virt.html#machine-specific-options
>>
>> Every board should have such a page.  Even if it's just a placeholder.
>> Placeholders would remind us where the gaps are.
>
> I agree. For Arm I believe every board should already have a docs page,
> even if a very minimal one. (Some closely related boards get
> described on a single page that covers that whole family of boards.)
> The full list of pages is here:
>  https://www.qemu.org/docs/master/system/target-arm.html
>
> We follow the same pattern (but not always with complete coverage)
> in most but not all the other target architectures.
>
> I don't think there's currently any automatic way to get a list
> of undocumented boards, because there isn't any tagging of the
> boards that are documented except in as much as the board names
> are listed in the title of the relevant pages.

Alright, here's a first and incomplete attempt at the manual way.

docs/system/targets.rst "QEMU System Emulator Targets" lists target
pages docs/system/target-ARCH:

    target-arm
    target-avr
    target-loongarch
    target-m68k
    target-mips
    target-or1k
    target-ppc
    target-riscv
    target-rx
    target-s390x
    target-sparc
    target-sparc64
    target-i386
    target-xtensa

These appear to be mostly per "arch", not per target, i.e. there's just
target-mips, not -mips, -mipsel, -mips64, mips64el.  Exception: -sparc
and -sparc64.

Checking against include/system/arch_init.h...  We're missing

    target-alpha
    target-hexagon
    target-hppa
    target-microblaze
    target-sh4
    target-tricore

Some target pages list board pages under a "Board-specific
documentation" heading:

    target-arm
        arm/max78000
        arm/integratorcp
        arm/mps2
        arm/musca
        arm/realview
        arm/sbsa
        arm/versatile
        arm/vexpress
        arm/aspeed
        arm/bananapi_m2u.rst
        arm/b-l475e-iot01a.rst
        arm/sabrelite
        arm/highbank
        arm/digic
        arm/cubieboard
        arm/emcraft-sf2
        arm/exynos
        arm/fby35
        arm/musicpal
        arm/kzm
        arm/nrf
        arm/nuvoton
        arm/imx25-pdk
        arm/mcimx6ul-evk
        arm/mcimx7d-sabre
        arm/imx8mp-evk
        arm/orangepi
        arm/raspi
        arm/collie
        arm/sx1
        arm/stellaris
        arm/stm32
        arm/virt
        arm/vmapple
        arm/xenpvh
        arm/xlnx-versal-virt
        arm/xlnx-zynq
        arm/xlnx-zcu102
    target-i386
        i386/pc
        i386/microvm
        i386/nitro-enclave
    target-loongarch
        loongarch/virt
    target-or1k
        or1k/or1k-sim
        or1k/virt
    target-ppc
        ppc/amigang
        ppc/embedded
        ppc/powermac
        ppc/powernv
        ppc/ppce500
        ppc/prep
        ppc/pseries
    target-riscv
        riscv/microblaze-v-generic
        riscv/microchip-icicle-kit
        riscv/mips
        riscv/shakti-c
        riscv/sifive_u
        riscv/virt
        riscv/xiangshan-kunminghu

Pages may cover multiple machine types (e.g. ppc/amigang covers
amigaone, pegasos1, pegasos2, sam460ex).  We might want to tweak titles
to help us find the board names more easily, so we can check for
completeness.

Target pages without a "Board-specific documentation" heading:

    target-avr
    target-m68k
    target-mips
    target-rx
    target-s390x
    target-sparc
    target-sparc64
    target-xtensa

Some of these do talk about boards, just in less greppable ways.  We
might want to adjust them to better support completeness checking.

Worth pursuing this further?