Re: sysbus_create_simple Vs qdev_create

[Eduardo Habkost]

On Wed, Jul 15, 2020 at 04:37:18PM +0200, Markus Armbruster wrote:
> Pratik Parvati <pratikp@vayavyalabs.com> writes:
> 
> > Hi Markus and Philippe,
> >
> > Thanks for your reply. Now I am pretty clear about Qdev and sysbus helper
> > function.
> >
> > Can you please explain to me in brief on buses and device hierarchies (i.e.
> > BusState and DeviceState) and how they are related to each other? As I can
> > see, the DeviceState class inherits the BusState
> >
> > struct DeviceState {
> >     /*< private >*/
> >     Object parent_obj;
> >     /*< public >*/
> >
> >     const char *id;
> >     char *canonical_path;
> >     bool realized;
> >     bool pending_deleted_event;
> >     QemuOpts *opts;
> >     int hotplugged;
> >     bool allow_unplug_during_migration;
> >     BusState *parent_bus; \\ BusState is inherited here
> >     QLIST_HEAD(, NamedGPIOList) gpios;
> >     QLIST_HEAD(, BusState) child_bus;
> >     int num_child_bus;
> >     int instance_id_alias;
> >     int alias_required_for_version;
> >     ResettableState reset;
> > };
> >
> > and BusState, in turn, inherits the DeviceState as
> >
> > /**
> >  * BusState:
> >  * @hotplug_handler: link to a hotplug handler associated with bus.
> >  * @reset: ResettableState for the bus; handled by Resettable interface.
> >  */struct BusState {
> >     Object obj;
> >     DeviceState *parent; \\ DeviceState is inherited here
> >     char *name;
> >     HotplugHandler *hotplug_handler;
> >     int max_index;
> >     bool realized;
> >     int num_children;
> >     QTAILQ_HEAD(, BusChild) children;
> >     QLIST_ENTRY(BusState) sibling;
> >     ResettableState reset;
> > };
> >
> > I am a bit confused. Can you brief me this relation!
> 
> We sorely lack introductory documentation on both qdev and QOM.  I
> believe most developers are more or less confused about them most of the
> time.  I've done a bit of work on both, so I'm probably less confused
> than average.  I'm cc'ing maintainers in the hope of reducing average
> confusion among participants in this thread.
> 
> DeviceState does not inherit from BusState, and BusState does not
> inherit from DeviceState.  The relation you marked in the code is
> actually "has a".
> 
> A DeviceState may have a BusState, namely the bus the device is plugged
> into.  "May", because some devices are bus-less (their
> DEVICE_GET_CLASS(dev)->bus_type is null), and the others get plugged
> into their bus only at realize time.
> 
> Example: PCI device "pci-serial" plugs into a PCI bus.
> 
> Example: device "serial" does not plug into a bus (its used as component
> device of "pci-serial" and other devices).
> 
> Example: device "pc-dimm" does not plug into a bus.
> 
> A bus has a DeviceState, namely the device providing this bus.
> 
> Example: device "i440FX-pcihost" provides PCI bus "pci.0".
> 
> Both DeviceState and BusState are QOM subtypes of Object.  I prefer to
> avoid use of "inherit" for that, because it can mean different things to
> different people.

I'd also note that the use of "parent" in the code is also
ambiguous.  It can mean:

* QOM parent type, i.e. TypeInfo.parent.  Related fields:
  * parent_class members of class structs
  * parent_obj members of object structs
* QOM composition tree parent object, i.e. Object::parent
* qdev device parent bus, i.e. DeviceState::parent_bus
* parent device of of qdev bus, i.e. BusState::parent

-- 
Eduardo