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

["Cédric Le Goater" <clg@kaod.org>]

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.

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.


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

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?

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