Peter Maydell <[email protected]> writes:
> On Fri, 27 Feb 2026 at 14:51, Markus Armbruster <[email protected]> wrote:
>>
>> Peter Maydell <[email protected]> writes:
>>
>> > On Fri, 27 Feb 2026 at 12:10, Markus Armbruster <[email protected]> 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?
