virtio: document virtio_reset_device

mainline inclusion
from mainline-v5.17-rc8
commit c46eccda
category: feature
bugzilla: https://gitee.com/openeuler/kernel/issues/I5WXCZ
CVE: NA

Reference: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=c46eccdaadabb7822080a04e633f81b2ad37f358

----------------------------------------------------------------------

Looks like most callers get driver/device removal wrong.
Document what's expected of callers.
Signed-off-by: NMichael S. Tsirkin <mst@redhat.com>
Signed-off-by: NPengyuan Zhao <zhaopengyuan@hisilicon.com>

drivers/virtio/virtio.c

@@ -203,6 +203,22 @@ static int virtio_features_ok(struct virtio_device *dev)
 	return 0;
 }
 
+/**
+ * virtio_reset_device - quiesce device for removal
+ * @dev: the device to reset
+ *
+ * Prevents device from sending interrupts and accessing memory.
+ *
+ * Generally used for cleanup during driver / device removal.
+ *
+ * Once this has been invoked, caller must ensure that
+ * virtqueue_notify / virtqueue_kick are not in progress.
+ *
+ * Note: this guarantees that vq callbacks are not in progress, however caller
+ * is responsible for preventing access from other contexts, such as a system
+ * call/workqueue/bh.  Invoking virtio_break_device then flushing any such
+ * contexts is one way to handle that.
+ * */
 void virtio_reset_device(struct virtio_device *dev)
 {
 	dev->config->reset(dev);