Re: [PATCH v4 14/16] qapi: deprecate "device" field of DEVICE_* events

[Markus Armbruster]

Philippe Mathieu-Daudé <philmd@linaro.org> writes:

> On 14/2/23 13:17, Markus Armbruster wrote:
>> Philippe Mathieu-Daudé <philmd@linaro.org> writes:
>> 
>>> On 14/2/23 12:49, Markus Armbruster wrote:
>>>> Daniel P. Berrangé <berrange@redhat.com> writes:
>> 
>> [...]
>> 
>>>>> What's the documented way to construct a QOM path, given only an ID  as
>>>>> input ?
>>>>
>>>> QOM paths a gap in our documentation, even though the composition tree
>>>> structure has been stable since day one, and is de facto ABI.
>>>>
>>>> Short answer: "/machine/peripheral/ID".
>>>>
>>>> Long answer follows.
>>>>
>>>> We have three "containers" under /machine that serve as parents for
>>>> devices:
>>>>
>>>> * /machine/peripheral/
>>>>
>>>>    Parent of user-created devices with ID.  Children are named "ID".
>>>>
>>>>    Put there by qdev_set_id(), called from qdev_device_add_from_qdict().
>>>>
>>>>    On "user-created": Nothing stops board code to abuse qdev_set_id() for
>>>>    onboard devices, directly or indirectly, but it really, really
>>>>    shouldn't.
>>>>
>>>> * /machine/peripheral-anon/
>>>>
>>>>    Parent of user-created devices without ID.  Children are named
>>>>    "device[N]", where N counts up from zero.
>>>>
>>>>    Put there by qdev_set_id(), called from qdev_device_add_from_qdict().
>>>>
>>>>    Again, abuse by board code is possible, but would be wrong.
>>>>
>>>>    Beware: a particular device's N changes when the set of devices
>>>>    created before it grows or shrinks.  Messing with the machine type can
>>>>    change it (different onboard devices).
>>>>
>>>> * /machine/unattached/
>>>>
>>>>    Surrogate parent of onboard devices created without a parent.
>>>>
>>>>    Put there by device_set_realized() (general case),
>>>>    qdev_connect_gpio_out_named() (input pins) , memory_region_do_init()
>>>>    (memory regions), qemu_create_machine() (the main sysbus).
>>>>
>>>>    I believe this container was created as a convenience, so we don't
>>>>    have to retrofit parents to existing code.  Probably abused ever
>>>>    since.
>>>
>>> Are you suggesting this is a stable interface and we can not move
>>> devices (like from /machine/unattached/ to /machine/peripheral/)
>>> without going thru the deprecation process?
>> 
>> Difficult question!
>> 
>> The point of not changing interfaces incompatibly without a grace period
>> / deprecation process is not breaking users of the interface.
>> 
>> When an interface has always worked a certain way, its users may well
>> depend on it, whether it's documented or not.
>> 
>> The question to ask is always "will this break users?"
>> 
>> For documented aspects, we generally assume it will.  Doesn't mean we
>> can simply assume "won't" for undocumented aspects.
>> 
>> Does this make sense?
>
> Yes, but I never considered the QOM paths as a stable interface...
> I'm very surprised.

I think it's a gray area.

For a good part of the QMP interface, we make an effort to review and
document, and to spell out what is stable and what isn't.  Sadly, QOM
and qdev are exceptions.

Properties are an essential part of the QMP interface, yet they are
virtually undocumented: closest we have is output of "-device
TYPENAME,help", which is utterly inadequate.  There is no systematic
review.  We've never been quite clear on which properties are part of
the stable interface.

QOM paths are a much less prominent part of the QMP interface, but they
are a part.  The structure of the QOM composition tree is undocumented.
Are they part of the stable interface?  Anybody's guess.  I figure they
weren't intended to be stable interace.  But then a QOM path is the only
way to device_del a device without ID.  Gray area.

Moreover, Hyrum's law[*] can catch up with us any time.

> "Automatically assigned to /machine/unattached/" doesn't seem
> quite stable...

The practical difficulties in (ab)using these push them towards the
unstable end of the gray area.


[*] "With a sufficient number of users of an API, it does not matter
what you promise in the contract: all observable behaviors of your
system will be depended on by somebody."