Re: How to mark internal properties

[Markus Armbruster <armbru@redhat.com>]

BALATON Zoltan <balaton@eik.bme.hu> writes:

> On Tue, 13 May 2025, Markus Armbruster wrote:
>> Mark Cave-Ayland <mark.caveayland@nutanix.com> writes:
>>> On a related note this also brings us back to the discussion as to the relationship between qdev and QOM: at one point I was under the impression that qdev properties were simply QOM properties that were exposed externally, i.e on the commmand line for use with -device.
>>>
>>> Can you provide an update on what the current thinking is in this area, in particular re: scoping of qdev vs QOM properties?
>>
>> qdev is a leaky layer above QOM.
>>
>> qdev properties are also QOM properties.
>>
>> All device properties are exposed externally.
>
> That was clear but the question was if QOM properties (that are not qdev properties) exist and if so are they also exposed? If not exposed it may be used for internal properties (where simpler solutions aren't convenient) but maybe qdev also adds easier definition of properties that's why they used instead of QOM properties?
>
>> We use device properties for:
>>
>> * Letting users configure pluggable devices, with -device or device_add
>>
>> * Letting code configure onboard devices
>>
>>  For onboard devices that are also pluggable, everything exposed to
>>  code is also exposed externally.  This might be a mistake in places.
>
> If a device is pluggable, theoretically a user could create a machine from them declaratively, e.g. starting from a "none" machine or like plugging cards in a motherboard so their properties should be exposed as long as those properties correspond to the device pins they model or configurable options. Only properties that are implementation details should not be exposed because setting them can break the device. There are a few places where we have such properties. But you say "in places" so I think you meant the same.

Building machines declaratively has been the dream for many years.

I chose to write "might be in places", because I can't point to examples
offhand to support a stronger claim :)

External interfaces should be intentional, i.e. carefully curated to
serve actual use cases.  They should also be stable and documented.

The QOM parts of our external interfaces are largely accidental,
unstable, and undocumented.  We have some internal need, we create
something to serve it, and expose it externally simply because we lack
the means not to.

>> * Letting the machine versioning machinery adjust device configuration
>>
>>  Some properties are meant to be used just for this.  They're exposed
>>  externally regardless, which is a mistake.
>
> Question is if we want to allow users to tweak these compatibility options, like selectively enable/disable when migrating between QEMU versions or for testing. It might have some uses and maybe that's the reason why people would like these to go through deprecation instead of just dropping them. Marking some properties not exposed would get the same resistance then so may not solve the issue.

If you need to mess with properties to make migration work, that's a
bug.  That's versioning machinery's job.

External interfaces just for testing can be okay.  We should not promise
stability there.  We should still be intentional, and we should still
document.

Attempts to get rid of external interfaces always draw resistance, even
when they're accidental.