From 1ce0368f99ab05716e50e11474b84dedb203218c Mon Sep 17 00:00:00 2001 From: Dariusz Stojaczyk Date: Thu, 30 Nov 2017 11:09:23 +0100 Subject: [PATCH] bdev/virtio: cleanup public API Cleaned up and expanded documentation of virtio bdev module. Change-Id: I4b989ed8b4d5e0bc66c0f0706e61219daf4e2869 Signed-off-by: Dariusz Stojaczyk Reviewed-on: https://review.gerrithub.io/390107 Tested-by: SPDK Automated Test System Reviewed-by: Daniel Verkamp Reviewed-by: Jim Harris --- lib/bdev/virtio/bdev_virtio.c | 15 +++++---- lib/bdev/virtio/bdev_virtio.h | 54 ++++++++++++++++++------------- lib/bdev/virtio/bdev_virtio_rpc.c | 4 +-- 3 files changed, 42 insertions(+), 31 deletions(-) diff --git a/lib/bdev/virtio/bdev_virtio.c b/lib/bdev/virtio/bdev_virtio.c index 0ab2fe307..e0b883d74 100644 --- a/lib/bdev/virtio/bdev_virtio.c +++ b/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; diff --git a/lib/bdev/virtio/bdev_virtio.h b/lib/bdev/virtio/bdev_virtio.h index c360ae9f9..6baf7c81a 100644 --- a/lib/bdev/virtio/bdev_virtio.h +++ b/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: t + * \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 */ diff --git a/lib/bdev/virtio/bdev_virtio_rpc.c b/lib/bdev/virtio/bdev_virtio_rpc.c index bd28c0a54..4c830c324 100644 --- a/lib/bdev/virtio/bdev_virtio_rpc.c +++ b/lib/bdev/virtio/bdev_virtio_rpc.c @@ -124,8 +124,8 @@ 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, - rpc_create_virtio_user_scsi_bdev_cb, req); + 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; }