Re: [PATCH] docs/devel: add doc about device life cycles

[Peter Maydell]

On Tue, 21 Jun 2022 at 15:50, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Fri, 22 Apr 2022 at 15:29, Damien Hedde <damien.hedde@greensocs.com> wrote:
> >
> > Document the 3 life cycles cases that can happen with devices.
> >
> > Signed-off-by: Damien Hedde <damien.hedde@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