bdev/virtio: cleanup public API

Cleaned up and expanded documentation
of virtio bdev module.

Change-Id: I4b989ed8b4d5e0bc66c0f0706e61219daf4e2869
Signed-off-by: Dariusz Stojaczyk <dariuszx.stojaczyk@intel.com>
Reviewed-on: https://review.gerrithub.io/390107
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>

lib/bdev/virtio/bdev_virtio.c

@@ -92,7 +92,7 @@ struct virtio_scsi_scan_base {
 	/** Virtqueue used for the scan I/O. */
 	struct virtqueue		*vq;
 
-	virtio_create_device_cb		cb_fn;
+	bdev_virtio_create_cb		cb_fn;
 	void				*cb_arg;
 
 	/* Currently queried target */
@@ -568,7 +568,7 @@ bdev_virtio_ctrlq_poll(void *arg)
 }
 
 static int
-bdev_virtio_create_cb(void *io_device, void *ctx_buf)
+bdev_virtio_scsi_ch_create_cb(void *io_device, void *ctx_buf)
 {
 	struct virtio_dev *vdev = io_device;
 	struct bdev_virtio_io_channel *ch = ctx_buf;
@@ -592,7 +592,7 @@ bdev_virtio_create_cb(void *io_device, void *ctx_buf)
 }
 
 static void
-bdev_virtio_destroy_cb(void *io_device, void *ctx_buf)
+bdev_virtio_scsi_ch_destroy_cb(void *io_device, void *ctx_buf)
 {
 	struct bdev_virtio_io_channel *io_channel = ctx_buf;
 	struct virtio_dev *vdev = io_channel->vdev;
@@ -669,7 +669,8 @@ scan_target_finish(struct virtio_scsi_scan_base *base)
 	ctrlq->poller_ctx = ctrlq_ring;
 	ctrlq->poller = spdk_poller_register(bdev_virtio_ctrlq_poll, base->vdev, CTRLQ_POLL_PERIOD_US);
 
-	spdk_io_device_register(base->vdev, bdev_virtio_create_cb, bdev_virtio_destroy_cb,
+	spdk_io_device_register(base->vdev, bdev_virtio_scsi_ch_create_cb,
+				bdev_virtio_scsi_ch_destroy_cb,
 				sizeof(struct bdev_virtio_io_channel));
 
 	while ((disk = TAILQ_FIRST(&base->found_disks))) {
@@ -1244,7 +1245,7 @@ bdev_virtio_scsi_free(struct virtio_dev *vdev)
 }
 
 static int
-bdev_virtio_scsi_scan(struct virtio_dev *vdev, virtio_create_device_cb cb_fn, void *cb_arg)
+bdev_virtio_scsi_scan(struct virtio_dev *vdev, bdev_virtio_create_cb cb_fn, void *cb_arg)
 {
 	struct virtio_scsi_scan_base *base = spdk_dma_zmalloc(sizeof(struct virtio_scsi_scan_base), 64,
 					     NULL);
@@ -1388,8 +1389,8 @@ bdev_virtio_finish(void)
 }
 
 int
-create_virtio_user_scsi_device(const char *base_name, const char *path, unsigned num_queues,
-			       unsigned queue_size, virtio_create_device_cb cb_fn, void *cb_arg)
+bdev_virtio_scsi_dev_create(const char *base_name, const char *path, unsigned num_queues,
+			    unsigned queue_size, bdev_virtio_create_cb cb_fn, void *cb_arg)
 {
 	struct virtio_dev *vdev;
 	int rc;

lib/bdev/virtio/bdev_virtio.h

@@ -36,31 +36,41 @@
 
 #include "spdk/bdev.h"
 
-typedef void (*virtio_create_device_cb)(void *, int, struct spdk_bdev **, size_t size);
+/**
+ * Callback for creating virtio bdevs.
+ *
+ * \param ctx opaque context set by the user
+ * \param errnum error code. 0 on success, negative errno on error.
+ * \param bdevs contiguous array of created bdevs
+ * \param bdev_cnt number of bdevs in the `bdevs` array
+ */
+typedef void (*bdev_virtio_create_cb)(void *ctx, int errnum,
+				      struct spdk_bdev **bdevs, size_t bdev_cnt);
 
 /**
- * Add new Virtio SCSI device and scan it. When LUN is found bdev is automaticly
- * added to point this LUN.
+ * Connect to a vhost-user Unix domain socket and create a Virtio SCSI device.
+ * If the connection is successful, the device will be automatically scanned.
+ * The scan consists of probing the targets on the device and will result in
+ * creating possibly multiple Virtio SCSI bdevs - one for each target. Currently
+ * only one LUN per target is detected - LUN0. Note that the bdev creation is
+ * run asynchronously in the background. After it's finished, the `cb_fn`
+ * callback is called.
  *
- * \param path
- *   Path to socket.
- * \param base_name
- *   Name to used for all bdevs created from this device.
- * \param vq_size
- *   Max queue size.
- * \param cb_fn
- *   An optional callback to be called after scanning all targets on the controller.
- *   First parameter is \c cb_arg
- *   Second parameter is error code. Zero on succes or negative error code.
- *   Third parameter is bdevs array found on created device. NULL in case of error.
- *   Fourth is number of bdevs in array. Zero in case of error.
- * \param cb_arg1
- *   First argument of \c cb_fn
- * \return
- *   Zero on success (device scan is started) or negative error code.
- *   In case of error \c done_cb is not called.
+ * \param name name for the virtio device. It will be inherited by all created
+ * bdevs, which are named in the following format: <name>t<target_id>
+ * \param path path to the socket
+ * \param num_queues max number of request virtqueues (I/O queues) to use.
+ * If given value exceeds a hard limit of the physical (host) device, this
+ * function will return with error.
+ * \param queue_size depth of each queue
+ * \param cb_fn function to be called after scanning all targets on the virtio
+ * device. It's optional, can be NULL. See \c bdev_virtio_create_cb.
+ * \param cb_arg argument for the `cb_fn`
+ * \return zero on success (device scan is started) or negative error code.
+ * In case of error the \c cb_fn is not called.
  */
-int create_virtio_user_scsi_device(const char *base_name, const char *path, unsigned num_queues,
-				   unsigned queue_size, virtio_create_device_cb cb_fn, void *cb_arg);
+int bdev_virtio_scsi_dev_create(const char *name, const char *path,
+				unsigned num_queues, unsigned queue_size,
+				bdev_virtio_create_cb cb_fn, void *cb_arg);
 
 #endif /* SPDK_BDEV_VIRTIO_H */

lib/bdev/virtio/bdev_virtio_rpc.c

@@ -124,7 +124,7 @@ spdk_rpc_create_virtio_user_scsi_bdev(struct spdk_jsonrpc_request *request,
 	}
 
 	req->request = request;
-	rc = create_virtio_user_scsi_device(req->name, req->path, req->vq_count, req->vq_size,
+	rc = bdev_virtio_scsi_dev_create(req->name, req->path, req->vq_count, req->vq_size,
 					 rpc_create_virtio_user_scsi_bdev_cb, req);
 	if (rc < 0) {
 		goto invalid;