On Tue, 21 Jun 2022 at 15:50, Peter Maydell <peter.mayd...@linaro.org> wrote: > > On Fri, 22 Apr 2022 at 15:29, Damien Hedde <damien.he...@greensocs.com> wrote: > > > > Document the 3 life cycles cases that can happen with devices. > > > > Signed-off-by: Damien Hedde <damien.he...@greensocs.com> > > Firstly, sorry it's taken me two months to get to this patch. > The underlying reason for this is that I'm not myself 100% > certain about how the QOM/qdev device lifecycle works and what > things should go in what lifecycle methods, so I didn't really > feel very confident about reviewing it... > > To start with, I think we should definitely have some documentation > for this, and I like the structure you have here with: > (1) the various ways devices are created and deleted > (2) what the corresponding lifecycles are in terms of which > methods get called > (3) the concrete consequences for what a device should and > should not do in each method > > I'll try to get into some more detailed review below. > > > diff --git a/docs/devel/device.rst b/docs/devel/device.rst > > new file mode 100644 > > index 0000000000..80e3016e80 > > --- /dev/null > > +++ b/docs/devel/device.rst > > I think we should name the file device-lifecycle.rst -- we're > (hopefully) going to accumulate a bunch of documentation on devices > generally and we don't want it all to end up in this one file. > > > @@ -0,0 +1,111 @@ > > +QEMU device life-cycle > > +====================== > > + > > +This document details the specifics of devices. > > + > > +Devices can be created in two ways: either internally by code or through a > > +user interface: > > + > > ++ command line interface provides ``-device`` option > > ++ QAPI interface provides ``device_add`` command > > I think this bulleted list should list all the ways that devices > get created (and destroyed), so: > > Devices can be created in several ways: > + programmatically, by the C code that implements board and SoC models > + on the command line, via the -device option > + via the QMP and HMP device_add monitor commands > + temporarily as part of the introspection of device objects > when the user asks for help on a device type or about what > properties it implements > In some cases, devices will also be destroyed: > + if a device is hot-unpluggable then after an 'unplug' it will > be destroyed > + the temporary objects created for introspection are destroyed > after they have been examined > > To do this, devices must implement at least some of these methods > which are present on all QOM objects: > + instance_init > + instance_post_init > + unparent
...actually, do devices themselves really need to implement unparent? If they don't we shouldn't list it here, that's confusing. > + instance_finalize > and these which are specific to devices: > + realize > + unrealize -- PMM
