Re: Adding /machines/labels (was Re: [PATCH v2 18/25] tests/functional: add a pure-Python device-locator resolver)

[Markus Armbruster <armbru@redhat.com>]

Cédric Le Goater <clg@kaod.org> writes:

> On 7/31/26 12:45, Emmanuel Blot wrote:
>> Add DeviceLocator, a helper that addresses a device by its position on
>> the bus -- bus, address, type or index -- rather than by a QOM path. A
>> QOM path locates a device under the object that owns it, by enumeration
>> order, and so says nothing about where the device actually sits in the
>> bus topology. From a QOM anchor DeviceLocator instead walks the bus and
>> device hierarchy, alternating bus and device hops, to reach the target.
>> It relies only on standard QOM queries over QMP, needing no custom
>> commands or changes to QEMU.
>
> Let's recap first :
>
> Several recent threads have touched the same topic: QOM
> composition-tree paths encode ownership, but developers and tests
> regularly need to identify devices by their position in the bus
> topology. The threads in question:
>
>   - "[PATCH v5 0/8] hw/sensor: Add new device emulation for TI ADC128D818" [1]
>   - "Call to clean up QOM onboard devices lacking a parent" [2]
>   - "[PATCH RFC 001/134] qom: Introduce object_new_child()" [3]
>   - "[PATCH RFC v2 0/137] qom: Make composition-tree parenting mandatory" [4]
>   - "[PATCH v2 0/25] hw/arm: Facebook SanMiguel BMC and TMP75-family sensors" [5]
>
>
> * The problem
>
> QEMU has two device hierarchies serving different purposes:
>
>   - The QOM composition tree describes parent/child ownership.  Every
>     object has exactly one parent. Paths look like:
>     /machine/soc/i2c-controller/child-device.
>   - The bus topology describes electrical connectivity (visible
>     through "info qtree"). A device sits on a bus at an address.

Yes.

*Composition* tree means the children are *components* of their parent.
At least that's the intended use.

The qtree predates QOM and is a bit of a relic.  Its design is too
simplistic to match electric reality: it's a *tree*, whereas real wires
form a *graph*.

Tree is fine for ordinary devices plugging into something a hardware
dude would recognize as a bus, say PCI or USB.

Caveat: as long as they plug into exactly one such thing; "multi-master
I2C" was mentiond as a counter-example.

Many (most?) of our devices are sysbus devices.  Sysbus is not a bus,
it's a cop out: it doesn't actually describe electrical connections
beyond "there are some to other parts of 'the system'".

And then there are funny devices like certain PCI VGA devices that plug
into a PCI but also bypass PCI for mapping their frame buffer.

I guess (the saner parts of) qtree may still provide some value.  I'm
curious: do people use it in programs?  Management applications in
particular.

QOM provides a mechanism that is suitable for modeling electrical
connections other than the ones to the parent: links.  These do form a
graph.

> Devices created without an explicit QOM parent fall into
> /machine/unattached/device[N], the "orphanage", with names that depend
> on enumeration order and are therefore unstable. Markus identified
> 380+ such devices across all QEMU machines [2]. Even with a stable QOM
> path, the path says nothing about where the device sits in the bus
> topology or what purpose it serves.

Yes, and that can be a problem.

> * Three approaches on the table
>
>   1. Mandatory QOM parenting (Graf [3][4] / Armbruster [2])
>      object_new_child() and per-bus creators enforce parenting at
>      creation time. Deletes the orphanage. Scope: 440 files, 137
>      patches.
>
>   2. Bus-child parenting (Blot [1], rejected)
>      i2c_slave_create_simple() would parent slaves to their bus,
>      named by hex address (e.g. /machine/i2c[0]/i2c-bus/0x6f).
>
>   3. DeviceLocator (Blot [5])
>      Pure-Python helper that resolves devices by bus-position
>      descriptors like:
>
>        /machine/soc::aspeed.i2c-ast2600[0]~i2c[9]~tmp75@0x4b
>
>      It walks the bus/device hierarchy using only qom-list/qom-get
>      over QMP, no QEMU code changes needed. 600 lines of python.
>
>
> * /machine/labels: DT-style alias container for QOM
>
> The idea: add a flat container /machine/labels under the machine, where
> board code registers link<> properties pointing to devices by
> purpose name. Like device tree /aliases (serial0  > /soc/uart@9000000).

This general idea has been sloshing around in my head for a long time, I
just haven't had a compelling reason to flesh it out.

> Container creation is one line in qemu_create_machine_containers().
> QMP introspection works today: qom-get /machine/labels/rtc returns the
> target's canonical path.
>
> A small helper is all that is needed:
>
>   void machine_add_label(const char *label, Object *target)
>   {
>       object_property_add_const_link(
>           machine_get_container("labels"), label, target);
>   }
>
> Board code registers one label per well-known device:
>
>   machine_add_label("rtc", OBJECT(dev));
>   machine_add_label("tmp75-bus9-0x4b", OBJECT(sensor));
>
> Tests resolve devices with a single QMP call instead of walking
> the bus hierarchy.  For the common case, functional tests targeting
> specific board devices (SanMiguel TMP75s, Catalina PCA9555s, Anacapa
> ADC128D818s), the board author already knows which devices matter.
>
> Thoughts?

To get the most value out of /machine/labels/, we'd want

* Documented naming conventions such as "/machine/label/serial0 always
  refers to the machine's first serial device"

* Reliability, i.e. if /machine/label/ exists, then
  /machine/label/serial0 exists unless the machine has no first serial
  device

* /machine/label/ to exist for the machines we actually care about :)

> Thanks,
>
> C.
>
> [1] https://lore.kernel.org/qemu-devel/20260701-i2c-adc128d818-anacapa-v5-6-fe8292d86b38@free.fr
> [2] https://lore.kernel.org/qemu-devel/87se5scipx.fsf@pond.sub.org
> [3] https://lore.kernel.org/qemu-devel/20260711223707.42139-1-graf@amazon.com
> [4] https://lore.kernel.org/qemu-devel/20260718213652.37673-1-graf@amazon.com
> [5] https://lore.kernel.org/qemu-devel/20260731-sanmiguel-bmc-locator-v2-0-1266926ba769@free.fr