diff mbox series

[v2,02/13] include/hw: document the device_class_set_parent_* fns

Message ID 20230418162140.373219-3-alex.bennee@linaro.org
State New
Headers show
Series virtio: add vhost-user-generic and reduce copy and paste | expand

Commit Message

Alex Bennée April 18, 2023, 4:21 p.m. UTC 
These are useful functions for when you want proper inheritance of
functionality across realize/unrealize calls.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 include/hw/qdev-core.h | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

Comments

Mark Cave-Ayland April 20, 2023, 9:24 a.m. UTC | #1 
On 18/04/2023 17:21, Alex Bennée wrote:

> These are useful functions for when you want proper inheritance of
> functionality across realize/unrealize calls.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>   include/hw/qdev-core.h | 27 +++++++++++++++++++++++++++
>   1 file changed, 27 insertions(+)
> 
> diff --git a/include/hw/qdev-core.h b/include/hw/qdev-core.h
> index d4bbc30c92..b1d194b561 100644
> --- a/include/hw/qdev-core.h
> +++ b/include/hw/qdev-core.h
> @@ -795,9 +795,36 @@ void device_class_set_props(DeviceClass *dc, Property *props);
>   void device_class_set_parent_reset(DeviceClass *dc,
>                                      DeviceReset dev_reset,
>                                      DeviceReset *parent_reset);
> +
> +/**
> + * device_class_set_parent_realize(): set up for chaining realize fns
> + * @dc: The device class
> + * @dev_realize: the device realize function
> + * @parent_realize: somewhere to save the parents realize function
> + *
> + * 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:

I think this should be the class structure, since it is the only possible location 
for the parent realize() function to exist given that these functions are called from 
the .class_init function.

> + *   my_dev->parent_realize(dev, errp);
> + */
>   void device_class_set_parent_realize(DeviceClass *dc,
>                                        DeviceRealize dev_realize,
>                                        DeviceRealize *parent_realize);
> +
> +
> +/**
> + * device_class_set_parent_unrealize(): set up for chaining unrealize fns
> + * @dc: The device class
> + * @dev_unrealize: the device realize function
> + * @parent_unrealize: somewhere to save the parents unrealize function
> + *
> + * This is intended to be used when the new unrealize function will
> + * eventually call its parent unrealization function during the
> + * unrealize phase. This requires storing the function call somewhere
> + * (usually in the instance structure) so you can eventually call:
> + *   my_dev->parent_unrealize(dev);

And same here of course.

> + */
>   void device_class_set_parent_unrealize(DeviceClass *dc,
>                                          DeviceUnrealize dev_unrealize,
>                                          DeviceUnrealize *parent_unrealize);


ATB,

Mark.
diff mbox series

Patch

diff --git a/include/hw/qdev-core.h b/include/hw/qdev-core.h
index d4bbc30c92..b1d194b561 100644
--- a/include/hw/qdev-core.h
+++ b/include/hw/qdev-core.h
@@ -795,9 +795,36 @@  void device_class_set_props(DeviceClass *dc, Property *props);
 void device_class_set_parent_reset(DeviceClass *dc,
                                    DeviceReset dev_reset,
                                    DeviceReset *parent_reset);
+
+/**
+ * device_class_set_parent_realize(): set up for chaining realize fns
+ * @dc: The device class
+ * @dev_realize: the device realize function
+ * @parent_realize: somewhere to save the parents realize function
+ *
+ * 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:
+ *   my_dev->parent_realize(dev, errp);
+ */
 void device_class_set_parent_realize(DeviceClass *dc,
                                      DeviceRealize dev_realize,
                                      DeviceRealize *parent_realize);
+
+
+/**
+ * device_class_set_parent_unrealize(): set up for chaining unrealize fns
+ * @dc: The device class
+ * @dev_unrealize: the device realize function
+ * @parent_unrealize: somewhere to save the parents unrealize function
+ *
+ * This is intended to be used when the new unrealize function will
+ * eventually call its parent unrealization function during the
+ * unrealize phase. This requires storing the function call somewhere
+ * (usually in the instance structure) so you can eventually call:
+ *   my_dev->parent_unrealize(dev);
+ */
 void device_class_set_parent_unrealize(DeviceClass *dc,
                                        DeviceUnrealize dev_unrealize,
                                        DeviceUnrealize *parent_unrealize);