Re: [Qemu-devel] [RFC] Plan for moving forward with QOM

[Anthony Liguori <anthony@codemonkey.ws>]

On 09/14/2011 02:30 PM, Jan Kiszka wrote:
> On 2011-09-14 20:04, Anthony Liguori wrote:
>> Hi,
>>
>> I spent a couple hours today writing up some comparisons and an initial
>> task list for converting qdev to QOM.  The main location of this is the
>> wiki[1] but I thought I would inline it here for easier commenting.
>>
>> I decided to do this because I wanted to avoid a massively long 00 patch
>> explaining the rationale for the first batch of changes that I'm going
>> to send out.
>>
>> There is so much complexity in qdev and the device model in general that
>> it's hard to come up with a concise document.  I'd really appreciate
>> suggestions for topics to write up more rationale as that would help me
>> avoid writing a book on the topic :-)
>>
>> [1] http://wiki.qemu.org/Features/QOM
>>
>> == Device Relationships ==
>>
>> === Device Relationships in QDev ===
>>
>> The two main concepts in QDev are devices and busses.  A device is
>> represented
>> by a DeviceState and a bus is represented by a BusState.  They do not
>> share a
>> common base class.  Devices can have properties but busses cannot.  A device
>> has no direct relationship with other devices.  The only relationship is
>> indirect through busses.
>>
>> A device may have zero or more busses associated with it via a has-a
>> relationship.  Each child bus may have multiple devices associated with
>> it via
>> a reference.  All devices have a single parent bus and all busses have a
>> single
>> parent device.  These relationships form a strict tree where every
>> alternating
>> level is a bus level followed by a device level.  The root of the tree
>> is the
>> main system bus often referred to as SysBus.
>>
>> === Device Relationships in QOM ===
>>
>> Everything in QOM is a device.  The concept of busses are implemented as an
>> interface that a device implements.  Devices can have two types of
>> relationships
>> with other devices: device composition or device backlinks.
>
> "Backlink" somehow implies to me that there is also a forward link. Why
> "back"?

Because I prefer to use confusing terminology :-)  link is definitely better. 
I'll s/backlink/link/g

>>
>> === Naming in QOM ===
>>
>> In QOM, there are only two namespaces, the device namespace and the property
>> namespace.
>>
>> All devices have unique names.
>
> Globally unique?

Yes.  It's also unique for all backends too (or will be eventually).

>>   There are no exceptions.  Devices created
>> through composition are given unique names by deriving the name based on the
>> parent device name and a special separator, "::", that cannot be used in
>> user
>> supplied names.
>
> That must be specified in more details. First of all, we likely need to
> add a '::' prefix to reflect the root device so that no user can
> override any auto-generated first-level device name.

Heh, I ended up doing this in my patch series as it turns out :-)

>
> What will be the unique name of some, say, smbus-eeprom?
> ::i440fx::PIIX4_PM::smbus-eeprom<something>?

The PIIX4_PM appears as a function on the PIIX4 device.  That means it will 
appear like:

::i440fx::piix4::pm::smbus-eeprom[N]

 > Will that something be
> derived from its bus address? Or a counter that ran while all sibling
> eeproms were created?

It's derived during creation.

> Such names can get fairly long I'm afraid...

A user should never even see these names.  A user probably will always interact 
with devices via paths.

We can also look at doing things like user-defined aliases or something like that.

>> Since a bus is-a device in QOM, there is no notion of having multiple busses
>> under the same device.  A device can implement multiple bus interfaces,
>> but can
>> only be a single bus of any given bus interface.
>>
>> Device names are completely independent of pathnames.  For devices that
>> are no
>> user created, device names should be treated as opaque blobs with
>> absolutely no
>> semantic meaning.
>>
>> All device relationships are identified as named properties.  A QOM path
>> name
>> consists of a named device,
>
> With a system root device called '/'. So '/' is another
> character(-sequence) that is forbidden in device names.

Yes, but there is no system root device.

In normal scenarios, the main device would be something like the i440fx.  That's 
a device that's explicitly created by the user.

>> followed by a series of properties which may
>> or may
>> not refer to other devices.  For instance, all of the following are
>> valid paths:
>>
>>    /i440fx/piix3/i8042/aux
>>    /i440fx/slot[1.0]/i8042/aux
>>    /i440fx/slot[1.0]/bus/piix3/i8042/aux
>
> Navigating along the properties sounds like a good idea. The properties
> (hopefully) have telling names so that it is (generally) also user-friendly.

Exactly.

> Nevertheless, I guess we should also establish and enforce some naming
> rules for properties to avoid inconsistencies like "i2c" vs.
> "my_i2c_devices" or just "d", ie. completely meaningless names. In the
> end, variable (property) names now become part of the user interface.

Indeed.

> This scheme also avoids having to merge the device namespace completely
> into the path namespace, which would cause all kinds of conflicts again.
>
> <snip>
> So far for now.

Thanks for taking a look!

Regards,

Anthony Liguori

> Jan
>