Re: Call to clean up QOM onboard devices lacking a parent

[Markus Armbruster <armbru@redhat.com>]

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

> On Thu, 9 Jul 2026, Markus Armbruster wrote:
>> A QOM object must be the child of exactly one parent.  This defines the
>> QOM composition tree.  The link from parent to child is a property of
>> the parent, and therefore has a name that is unique within its parent.
>> An object's canonical QOM path is these names on the path from root to
>> object in the QOM composition tree separated by '/'.
>>
>> For devices:
>>
>> * If a device is plugged in with -device / device_add, and it has an ID,
>>  we make it a child of /machine/peripheral/ with name ID.  If it
>>  doesn't have an ID, we make it a child of /machine/peripheral-anon/
>>  with name device[N], where N counts up from zero.  The canonical QOM
>>  path /machine/peripheral/ID is stable.  The canonical QOM path
>>  /machine/peripheral-anon/device[N] isn't: it depends on the number of
>>  devices already there.
>>
>> * If a device is part of another device, it should be its child.  The
>>  child's canonical QOM path is the parent's plus '/CHILD-NAME'.  Stable
>>  as long as the parent's path and the child name are.
>>
>> * "Should" because we have a lot of code that fails to pick the parent.
>>  When such a device gets realized, we make it a child of
>>  /machine/unattached/ orphanage with name device[N], where N counts up
>>  from zero.  The canonical QOM path /machine/unattached/device[N]
>>  depends on the number of children already in the orphanage, which
>>  makes it unstable.
>>
>>  Letting code get away with not picking a parent was a mistake.  I
>>  guess it "saved" us some thinking about what's part of what when
>>  converting existing devices to QOM.  In other words, it enabled sloppy
>>  hardware modeling.  We've been "saving" thinking ever since.
>>
>>  I want /machine/unattached/ to be empty.  If an onboard device isn't
>>  part of another device, put it into /machine/ with a sensible name.
>
> The last time this came up I've asked a few questions but did not get an answer:
>
> 1. What's the use of the QOM composition tree? I never needed it and apart from being able to admire it in info qom-tree I don't know if it's used for anything. For a long time I did not even know about info qom-tree because I only needed info qtree and info mtree and rarely if ever need to look at the qom-tree. If it has no real use I'm happy to not think about it.
>
> 2. What is a QOM parent? There were proposals to parent devices to their bus if they have any, that's what qtree shows anyway. If it's something else it should be better defined somewhere.
>
> Without getting answers for these questions I don't think I'm able to fix the machines I maintain.

Unfortunately, I don't have the time to teach a class on QOM basics
today.  The text you quoted explains what QOM parent and canonical QOM
path are, albeit briefly.  It also explains how to pick the QOM parent
properly, what happens when you neglect to pick one, and why that's
undesirable.  I'm going to elaborate a bit.

A fully constructed QOM object is part of the QOM composition tree.
This is a fundamental property of QOM's design.

A QOM object can be composed of sub-objects.  Its sub-objects are its
children in the composition tree.  That's why it's named *composition*
tree.

Canonical QOM paths are visible at external interfaces both as input and
as output.  A few quick examples:

* QMP command query-cpus-fast reports a CPU's canonical QOM path.  For
  some machines, we get something like "/machine/unattached/device[0]".
  Fine as long as the client treats it as an opaque handle.  For other
  machines, we get something like "/machine/soc/cpu", which is clearly
  better.

* Error messages use canonical QOM paths to identify devices.  With
  properly modeled hardware, these paths are actually helpful for
  humans.  Something like "/machine/unattached/device[7]" not so much.

* QMP command device-sync-config accepts a QOM path argument.  With
  properly modeled hardware, you can use a stable canonical QOM path.
  But when the device is in the /machine/unattached orphanage, its
  canonical QOM path is unstable.  A client has to first search the
  orphanage to find today's path.

Further questions?