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

[Markus Armbruster]

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

> On 14/2/23 12:49, Markus Armbruster wrote:
>> Daniel P. Berrangé <berrange at 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?