ceph/src/spdk/include/spdk/vhost.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright (c) Intel Corporation.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /**
  35  *  \file
  36  *  SPDK vhost
  37  */
  38
  39 #ifndef SPDK_VHOST_H
  40 #define SPDK_VHOST_H
  41
  42 #include "spdk/stdinc.h"
  43
  44 #include "spdk/event.h"
  45 #include "spdk/json.h"
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 /**
  52  * Callback funcion for spdk_vhost_fini().
  53  */
  54 typedef void (*spdk_vhost_fini_cb)(void);
  55
  56 /**
  57  * Set the path to the directory where vhost sockets will be created.
  58  *
  59  * This function must be called before spdk_vhost_init().
  60  *
  61  * \param basename Path to vhost socket directory
  62  *
  63  * \return 0 on success, negative errno on error.
  64  */
  65 int spdk_vhost_set_socket_path(const char *basename);
  66
  67 /**
  68  * Init vhost environment.
  69  *
  70  * \return 0 on success, -1 on failure.
  71  */
  72 int spdk_vhost_init(void);
  73
  74 /**
  75  * Clean up the environment of vhost after finishing the vhost application.
  76  *
  77  * \param fini_cb Called when the cleanup operation completes.
  78  */
  79 void spdk_vhost_fini(spdk_vhost_fini_cb fini_cb);
  80
  81
  82 /**
  83  * Write vhost subsystem configuration into provided JSON context.
  84  *
  85  * \param w JSON write context
  86  * \param done_ev call this event when done.
  87  */
  88 void spdk_vhost_config_json(struct spdk_json_write_ctx *w, struct spdk_event *done_ev);
  89
  90 /**
  91  * Deinit vhost application. This is called once by SPDK app layer.
  92  */
  93 void spdk_vhost_shutdown_cb(void);
  94
  95 /**
  96  * SPDK vhost device (vdev).  An equivalent of Virtio device.
  97  * Both virtio-blk and virtio-scsi devices are represented by this
  98  * struct. For virtio-scsi a single vhost device (also called SCSI
  99  * controller) may contain multiple SCSI targets (devices), each of
 100  * which may contain multiple logical units (SCSI LUNs). For now
 101  * only one LUN per target is available.
 102  *
 103  * All vdev-changing functions operate directly on this object.
 104  * Note that \c spdk_vhost_dev cannot be acquired. This object is
 105  * only accessible as a callback parameter via \c
 106  * spdk_vhost_call_external_event and it's derivatives. This ensures
 107  * that all access to the vdev is piped through a single,
 108  * thread-safe API.
 109  */
 110 struct spdk_vhost_dev;
 111
 112 /**
 113  * Synchronized vhost event used for user callbacks.
 114  *
 115  * \param vdev vhost device.
 116  * \param arg user-provided parameter.
 117  *
 118  * \return 0 on success, -1 on failure.
 119  */
 120 typedef int (*spdk_vhost_event_fn)(struct spdk_vhost_dev *vdev, void *arg);
 121
 122 /**
 123  * Get the name of the vhost device.  This is equal to the filename
 124  * of socket file. The name is constant throughout the lifetime of
 125  * a vdev.
 126  *
 127  * \param vdev vhost device.
 128  *
 129  * \return name of the vdev.
 130  */
 131 const char *spdk_vhost_dev_get_name(struct spdk_vhost_dev *vdev);
 132
 133 /**
 134  * Get cpuset of the vhost device.  The cpuset is constant throughout the lifetime
 135  * of a vdev. It is a subset of SPDK app cpuset vhost was started with.
 136  *
 137  * \param vdev vhost device.
 138  *
 139  * \return cpuset of the vdev.
 140  */
 141 const struct spdk_cpuset *spdk_vhost_dev_get_cpumask(struct spdk_vhost_dev *vdev);
 142
 143 /**
 144  * By default, events are generated when asked, but for high queue depth and
 145  * high IOPS this prove to be inefficient both for guest kernel that have to
 146  * handle a lot more IO completions and for SPDK vhost that need to make more
 147  * syscalls. If enabled, limit amount of events (IRQs) sent to initiator by SPDK
 148  * vhost effectively coalescing couple of completions. This of cource introduce
 149  * IO latency penalty proportional to event delay time.
 150  *
 151  * Actual events delay time when is calculated according to below formula:
 152  * if (delay_base == 0 || IOPS < iops_threshold) {
 153  *   delay = 0;
 154  * } else if (IOPS < iops_threshold) {
 155  *   delay = delay_base * (iops - iops_threshold) / iops_threshold;
 156  * }
 157  *
 158  * \param vdev vhost device.
 159  * \param delay_base_us Base delay time in microseconds. If 0, coalescing is disabled.
 160  * \param iops_threshold IOPS threshold when coalescing is activated.
 161  */
 162 int spdk_vhost_set_coalescing(struct spdk_vhost_dev *vdev, uint32_t delay_base_us,
 163                               uint32_t iops_threshold);
 164
 165 /**
 166  * Get coalescing parameters.
 167  *
 168  * \see spdk_vhost_set_coalescing
 169  *
 170  * \param vdev vhost device.
 171  * \param delay_base_us Optional pointer to store base delay time.
 172  * \param iops_threshold Optional pointer to store IOPS threshold.
 173  */
 174 void spdk_vhost_get_coalescing(struct spdk_vhost_dev *vdev, uint32_t *delay_base_us,
 175                                uint32_t *iops_threshold);
 176
 177 /**
 178  * Construct an empty vhost SCSI device.  This will create a
 179  * Unix domain socket together with a vhost-user slave server waiting
 180  * for a connection on this socket. Creating the vdev does not
 181  * start any I/O pollers and does not hog the CPU. I/O processing
 182  * starts after receiving proper message on the created socket.
 183  * See QEMU's vhost-user documentation for details.
 184  * All physical devices have to be separately attached to this
 185  * vdev via \c spdk_vhost_scsi_dev_add_tgt().
 186  *
 187  * This function is thread-safe.
 188  *
 189  * \param name name of the vhost device. The name will also be used
 190  * for socket name, which is exactly \c socket_base_dir/name
 191  * \param cpumask string containing cpumask in hex. The leading *0x*
 192  * is allowed but not required. The mask itself can be constructed as:
 193  * ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)).
 194  *
 195  * \return 0 on success, negative errno on error.
 196  */
 197 int spdk_vhost_scsi_dev_construct(const char *name, const char *cpumask);
 198
 199 /**
 200  * Construct and attach new SCSI target to the vhost SCSI device
 201  * on given (unoccupied) slot.  The device will be created with a single
 202  * LUN0 associated with given SPDK bdev. Currently only one LUN per
 203  * device is supported.
 204  *
 205  * If the vhost SCSI device has an active connection and has negotiated
 206  * \c VIRTIO_SCSI_F_HOTPLUG feature,  the new SCSI target should be
 207  * automatically detected by the other side.
 208  *
 209  * \param vdev vhost SCSI device.
 210  * \param scsi_tgt_num slot to attach to.
 211  * \param bdev_name name of the SPDK bdev to associate with SCSI LUN0.
 212  *
 213  * \return 0 on success, negative errno on error.
 214  */
 215 int spdk_vhost_scsi_dev_add_tgt(struct spdk_vhost_dev *vdev, unsigned scsi_tgt_num,
 216                                 const char *bdev_name);
 217
 218 /**
 219  * Get SCSI target from vhost SCSI device on given slot. Max
 220  * number of available slots is defined by.
 221  * \c SPDK_VHOST_SCSI_CTRLR_MAX_DEVS.
 222  *
 223  * \param vdev vhost SCSI device.
 224  * \param num slot id.
 225  *
 226  * \return SCSI device on given slot or NULL.
 227  */
 228 struct spdk_scsi_dev *spdk_vhost_scsi_dev_get_tgt(struct spdk_vhost_dev *vdev, uint8_t num);
 229
 230 /**
 231  * Detach and destruct SCSI target from a vhost SCSI device.
 232  *
 233  * If vhost SCSI device has an active socket connection, it is
 234  * required that it has negotiated \c VIRTIO_SCSI_F_HOTPLUG feature
 235  * flag.Otherwise an -ENOTSUP error code is returned. If the flag has
 236  * been negotiated, the device will be marked to be deleted. Actual
 237  * deletion is deferred until after all pending I/O to this device
 238  * has finished.
 239  *
 240  * Once the target has been deleted (whether or not vhost SCSI
 241  * device is in use) given callback will be called.
 242  *
 243  * \param vdev vhost SCSI device
 244  * \param scsi_tgt_num slot id to delete target from
 245  * \param cb_fn callback to be fired once target has been successfully
 246  * deleted. The first parameter of callback function is the vhost SCSI
 247  * device, the second is user provided argument *cb_arg*.
 248  * \param cb_arg parameter to be passed to *cb_fn*.
 249  *
 250  * \return 0 on success, negative errno on error.
 251  */
 252 int spdk_vhost_scsi_dev_remove_tgt(struct spdk_vhost_dev *vdev, unsigned scsi_tgt_num,
 253                                    spdk_vhost_event_fn cb_fn, void *cb_arg);
 254
 255 /**
 256  * Construct a vhost blk device.  This will create a Unix domain
 257  * socket together with a vhost-user slave server waiting for a
 258  * connection on this socket. Creating the vdev does not start
 259  * any I/O pollers and does not hog the CPU. I/O processing starts
 260  * after receiving proper message on the created socket.
 261  * See QEMU's vhost-user documentation for details. Vhost blk
 262  * device is tightly associated with given SPDK bdev. Given
 263  * bdev can not be changed, unless it has been hotremoved. This
 264  * would result in all I/O failing with virtio \c VIRTIO_BLK_S_IOERR
 265  * error code.
 266  *
 267  * This function is thread-safe.
 268  *
 269  * \param name name of the vhost blk device. The name will also be
 270  * used for socket name, which is exactly \c socket_base_dir/name
 271  * \param cpumask string containing cpumask in hex. The leading *0x*
 272  * is allowed but not required. The mask itself can be constructed as:
 273  * ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)).
 274  * \param dev_name bdev name to associate with this vhost device
 275  * \param readonly if set, all writes to the device will fail with
 276  * \c VIRTIO_BLK_S_IOERR error code.
 277  *
 278  * \return 0 on success, negative errno on error.
 279  */
 280 int spdk_vhost_blk_construct(const char *name, const char *cpumask, const char *dev_name,
 281                              bool readonly);
 282
 283 /**
 284  * Remove a vhost device. The device must not have any open connections on it's socket.
 285  *
 286  * \param vdev vhost blk device.
 287  *
 288  * \return 0 on success, negative errno on error.
 289  */
 290 int spdk_vhost_dev_remove(struct spdk_vhost_dev *vdev);
 291
 292 /**
 293  * Get underlying SPDK bdev from vhost blk device. The bdev might be NULL, as it
 294  * could have been hotremoved.
 295  *
 296  * \param ctrlr vhost blk device.
 297  *
 298  * \return SPDK bdev associated with given vdev.
 299  */
 300 struct spdk_bdev *spdk_vhost_blk_get_dev(struct spdk_vhost_dev *ctrlr);
 301
 302 /**
 303  * Call function on reactor of given vhost device. If device is not in use, the
 304  * event will be called right away on the caller's thread.
 305  *
 306  * This function is thread safe.
 307  *
 308  * \param vdev_name name of the vhost device to run this event on.
 309  * \param fn function to be called. The first parameter of callback function is
 310  * either actual spdk_vhost_dev pointer or NULL in case vdev with given name doesn't
 311  * exist. The second param is user provided argument *arg*.
 312  * \param arg parameter to be passed to *fn*.
 313  */
 314 void spdk_vhost_call_external_event(const char *vdev_name, spdk_vhost_event_fn fn, void *arg);
 315
 316 /**
 317  * Call function for each available vhost device on
 318  * it's reactor.  This will call given function in a chain,
 319  * meaning that each callback will be called after the
 320  * previous one has finished. After given function has
 321  * been called for all vdevs, it will be called once
 322  * again with first param - vhost device- set to NULL.
 323  *
 324  * This function is thread safe.
 325  *
 326  * \param fn function to be called for each vdev. The first param will be
 327  * either vdev pointer or NULL. The second param is user provided argument *arg*.
 328  * \param arg parameter to be passed to *fn*.
 329  */
 330 void spdk_vhost_call_external_event_foreach(spdk_vhost_event_fn fn, void *arg);
 331
 332 #ifdef __cplusplus
 333 }
 334 #endif
 335
 336 #endif /* SPDK_VHOST_H */