On Fri, 16 Oct 2026 at 10:09, Mark Cave-Ayland <[email protected]> wrote: > > On 15/10/2026 17:33, Peter Maydell wrote: > > > The documentation for device_class_set_parent_realize() suggests that > > the parent realize function pointer is "usually in the instance > > structure". This is definitely wrong, because the function pointer > > is a class thing, and should live in a class struct, not an instance > > struct. Update the documentation to correct this, instead > > recommending that it should be placed in the class struct for the > > child class. > > > > At time of writing, of the 75 or so uses of this function, about 50 > > put the parent_realize pointer in the child class struct, and about > > 25 in the parent class struct. We recommend the former both because > > it is the more common choice, and also because it makes more logical > > sense: it's the child that knows (a) that it exists at all and that > > (b) it wants to have a realize method that will mean it needs to > > chain back to the parent, and we shouldn't need to edit the parent's > > class struct because we want to add a child class that chains to its > > realize method. > > > > Signed-off-by: Peter Maydell <[email protected]> > > --- > > include/hw/core/qdev.h | 15 ++++++++++++--- > > 1 file changed, 12 insertions(+), 3 deletions(-) > > > > diff --git a/include/hw/core/qdev.h b/include/hw/core/qdev.h > > index 8e91e2fcb08..1330e0153d4 100644 > > --- a/include/hw/core/qdev.h > > +++ b/include/hw/core/qdev.h > > @@ -953,9 +953,18 @@ void device_class_set_props_n(DeviceClass *dc, const > > Property *props, size_t n); > > * > > * This is intended to be used when the new realize function will > > * eventually call its parent realization function during creation. > > - * This requires storing the function call somewhere (usually in the > > - * instance structure) so you can eventually call > > - * dc->parent_realize(dev, errp) > > + * @parent_realize should be where you want to save the pointer to > > + * the parent class realize function; the recommended location is a > > Do we need something stronger than "recommended location" if we want to > encourage people to always do it this way in future?
I think the discussion here suggests we want to get rid of this function entirely in the future, so being stronger than "recommended" is probably a bit moot. > > + * field named "parent_realize" in your class's class struct. > > + * (Some existing code puts the field in the parent class's class > > + * struct; this will work but is not the preferred thing for new code.) > > + * > > + * In your realize function you should chain to your parent's > > + * realize function using something like:: > > + * > > + * MyThingClass *mc = MY_THING_GET_CLASS(dev); > > + * (do your child class realize actions here) > > + * mc->parent_realize(dev, errp); > > */ > > void device_class_set_parent_realize(DeviceClass *dc, > > DeviceRealize dev_realize, > > Otherwise: > > Reviewed-by: Mark Cave-Ayland <[email protected]> Thanks. I'm going to queue this patch as a fix for this API doc for the moment, because we clearly aren't going to get to Daniel's better way of doing this for the 11.2 release. -- PMM
