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

> For the global machine options, I don't think we have a place where we
> document those. If we did, we should perhaps have each board's page
> also link to the global-options page.

We should do this.