[qemu-xen staging] qdev: Document qdev_unrealize()

[patchbot@xxxxxxx]

commit 46ea1be1ee72b778043e60c8a59cbcb53fb8be34
Author:     Peter Maydell <peter.maydell@xxxxxxxxxx>
AuthorDate: Sat Jul 11 15:24:24 2020 +0100
Commit:     Peter Maydell <peter.maydell@xxxxxxxxxx>
CommitDate: Mon Jul 20 11:35:17 2020 +0100

    qdev: Document qdev_unrealize()
    
    Add a doc comment for qdev_unrealize(), to go with the new
    documentation for the realize part of the qdev lifecycle.
    
    Signed-off-by: Peter Maydell <peter.maydell@xxxxxxxxxx>
    Reviewed-by: Richard Henderson <richard.henderson@xxxxxxxxxx>
    Message-id: 20200711142425.16283-3-peter.maydell@xxxxxxxxxx
---
 include/hw/qdev-core.h | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/include/hw/qdev-core.h b/include/hw/qdev-core.h
index 2d441d1fb2..1d2bf5f37d 100644
--- a/include/hw/qdev-core.h
+++ b/include/hw/qdev-core.h
@@ -381,6 +381,25 @@ bool qdev_realize(DeviceState *dev, BusState *bus, Error 
**errp);
  * would be incorrect. For that use case you want qdev_realize().
  */
 bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp);
+/**
+ * qdev_unrealize: Unrealize a device
+ * @dev: device to unrealize
+ *
+ * This function will "unrealize" a device, which is the first phase
+ * of correctly destroying a device that has been realized. It will:
+ *
+ *  - unrealize any child buses by calling qbus_unrealize()
+ *    (this will recursively unrealize any devices on those buses)
+ *  - call the the unrealize method of @dev
+ *
+ * The device can then be freed by causing its reference count to go
+ * to zero.
+ *
+ * Warning: most devices in QEMU do not expect to be unrealized.  Only
+ * devices which are hot-unpluggable should be unrealized (as part of
+ * the unplugging process); all other devices are expected to last for
+ * the life of the simulation and should not be unrealized and freed.
+ */
 void qdev_unrealize(DeviceState *dev);
 void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id,
                                  int required_for_version);
--
generated by git-patchbot for /home/xen/git/qemu-xen.git#staging