[Qemu-devel] Re: RFC qdev path semantics

[Jan Kiszka <jan.kiszka@siemens.com>]

Markus Armbruster wrote:
> 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.

Another aspect: A path may start with an arbitrary bus name, not only
the system bus. Although this is ambiguous, we need to keep it for
addressing the bus itself due to existing client use. But, IMO, we
should at least start deprecating this for addressing elements below
that bus (e.g. "pci.0/e1000").

And besides specifying devices via absolute qdev paths, we also support
addressing them via their ID if present. I checked if ID/BUS[/...] was
supported so far, but it wasn't. So I did not propose this yet although
it might be a useful abbreviation.

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

I would be fine with this scheme, but I assume we still need instance
numbers as fallback for buses without any usable addressing. Example: I
have a patch queued that uses this for internal addressing of all hpet
devices on the system bus (to connect them to the ISA IRQs).

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

PATH/IDENT[.INSTANCE] would resolve the addressability.

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

Thanks for this summary!

Jan

-- 
Siemens AG, Corporate Technology, CT T DE IT 1
Corporate Competence Center Embedded Linux