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

[Markus Armbruster]

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
      address@hidden 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/address@hidden

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

    IDENT in PATH/address@hidden 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.