RFC qdev path semantics (was: [Qemu-devel] [RFC PATCH 0/5] Introduce canonical device hierarchy string)

Markus Armbruster
2010-06-16T09:46:27Z

A number of changes to qdev paths have been proposed in various threads.
It's becoming harder to keep track of them, so let me sum them up in one
place. Please correct me if I misrepresent your ideas.

I'm going to describe the current state of things, and the proposed
changes (marked with ###).

The device tree has the main system bus as root. A child of a bus is a
device. A child of a device is a bus.

A qdev path consists of qdev path components separated by '/'. It
resolves to a node in the device tree, either bus or device.

The qdev path "/" resolves to the root, i.e. the main system bus.

The qdev path IDENT, where IDENT is an identifier, resolves to the
device whose id is IDENT.

If PATH resolves to device DEV, and a child of DEV has the name IDENT,
then we resolve to that bus.

Bus names are chosen by the system as follows:

* If the driver of the parent device model provides a name, use that.

* Else, if the parent device has id ID, use ID.NUM, where NUM is the bus
number, counting from zero in creation order.

* Else, use TYPE.NUM, where TYPE is derived from the bus type, and NUM
is the bus number, as above.

### Paul proposes to drop ID.NUM.

### Paul proposes to either drop TYPE.NUM (and require drivers to
provide bus names), or make NUM count separately for each bus type.

If PATH resolves to bus BUS, then we resolve PATH/IDENT as follows:

* If a child of BUS has id IDENT, then we resolve to that device.

### Jan proposes to drop this rule.

* Else, if a child of BUS has a driver with name IDENT, then we resolve
to that device.

If more than one exist, resolve to the first one. This assumes
children are ordered. Order is the same as in "info qtree".
Currently, it's reverse creation order.

This is *not* a stable address.

* Else, if a child of BUS has a driver with alias name IDENT, then we
resolve to that device.

If more than one exist, resolve to the first one. This assumes
children are ordered. Order is the same as in "info qtree".
Currently, it's reverse creation order.

This is *not* a stable address.

### I propose: we resolve PATH/@BUS-ADDR to the child of BUS with bus
address BUS-ADDR, if devices on this type of bus have bus addresses.
The format of BUS-ADDR depends on the bus.

### Paul proposes to require all buses to define bus addresses. Make
one up if necessary.

### Jan proposes: we resolve PATH/IDENT.NUM as follows:

* If a child of BUS has a driver with name IDENT and an instance
number NUM, then we resolve to that device.

Need a suitable definition of "instance number".

Jan proposes to number devices with the same driver on the same
bus. This assumes children are ordered, see above.

This is *not* a stable address if the bus supports hot-plug.

I propose to us bus-address as instance number. Works best
together with Paul's proposal to define bus addresses. Syntax
IDENT@BUS-ADDR makes more sense then.

* Else, same with driver alias name.

### Here's a possible synthesis of the above three proposals: require
bus addresses, and permit any of

PATH/IDENT
PATH/@BUS-ADDR
PATH/IDENT@BUS-ADDR

PATH/IDENT can't address instances that don't come first.

IDENT in PATH/IDENT@BUS-ADDR is redundant. Therefore, it can't be
the canonical qdev path. That's fine, PATH/@BUS-ADDR serves.

If the above rules resolve PATH to a device in a context where we expect
a bus, and the device has exactly one bus, resolve it to that bus
instead.

### Jan and I propose to drop this rule.