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/cpuset.h"
  45 #include "spdk/json.h"
  46 #include "spdk/thread.h"
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /**
  53  * Callback for spdk_vhost_init().
  54  *
  55  * \param rc 0 on success, negative errno on failure
  56  */
  57 typedef void (*spdk_vhost_init_cb)(int rc);
  58
  59 /** Callback for spdk_vhost_fini(). */
  60 typedef void (*spdk_vhost_fini_cb)(void);
  61
  62 /**
  63  * Set the path to the directory where vhost sockets will be created.
  64  *
  65  * This function must be called before spdk_vhost_init().
  66  *
  67  * \param basename Path to vhost socket directory
  68  *
  69  * \return 0 on success, negative errno on error.
  70  */
  71 int spdk_vhost_set_socket_path(const char *basename);
  72
  73 /**
  74  * Init vhost environment.
  75  *
  76  * \param init_cb Function to be called when the initialization is complete.
  77  */
  78 void spdk_vhost_init(spdk_vhost_init_cb init_cb);
  79
  80 /**
  81  * Clean up the environment of vhost.
  82  *
  83  * \param fini_cb Function to be called when the cleanup is complete.
  84  */
  85 void spdk_vhost_fini(spdk_vhost_fini_cb fini_cb);
  86
  87
  88 /**
  89  * Write vhost subsystem configuration into provided JSON context.
  90  *
  91  * \param w JSON write context
  92  */
  93 void spdk_vhost_config_json(struct spdk_json_write_ctx *w);
  94
  95 /**
  96  * Deinit vhost application. This is called once by SPDK app layer.
  97  */
  98 void spdk_vhost_shutdown_cb(void);
  99
 100 /**
 101  * SPDK vhost device (vdev).  An equivalent of Virtio device.
 102  * Both virtio-blk and virtio-scsi devices are represented by this
 103  * struct. For virtio-scsi a single vhost device (also called SCSI
 104  * controller) may contain multiple SCSI targets (devices), each of
 105  * which may contain multiple logical units (SCSI LUNs). For now
 106  * only one LUN per target is available.
 107  *
 108  * All vdev-changing functions operate directly on this object.
 109  * Note that \c spdk_vhost_dev cannot be acquired. This object is
 110  * only accessible as a callback parameter via \c
 111  * spdk_vhost_call_external_event and it's derivatives. This ensures
 112  * that all access to the vdev is piped through a single,
 113  * thread-safe API.
 114  */
 115 struct spdk_vhost_dev;
 116
 117 /**
 118  * Lock the global vhost mutex synchronizing all the vhost device accesses.
 119  */
 120 void spdk_vhost_lock(void);
 121
 122 /**
 123  * Lock the global vhost mutex synchronizing all the vhost device accesses.
 124  *
 125  * \return 0 if the mutex could be locked immediately, negative errno otherwise.
 126  */
 127 int spdk_vhost_trylock(void);
 128
 129 /**
 130  * Unlock the global vhost mutex.
 131  */
 132 void spdk_vhost_unlock(void);
 133
 134 /**
 135  * Find a vhost device by name.
 136  *
 137  * \return vhost device or NULL
 138  */
 139 struct spdk_vhost_dev *spdk_vhost_dev_find(const char *name);
 140
 141 /**
 142  * Get the next vhost device. If there's no more devices to iterate
 143  * through, NULL will be returned.
 144  *
 145  * \param vdev vhost device. If NULL, this function will return the
 146  * very first device.
 147  * \return vdev vhost device or NULL
 148  */
 149 struct spdk_vhost_dev *spdk_vhost_dev_next(struct spdk_vhost_dev *vdev);
 150
 151 /**
 152  * Synchronized vhost event used for user callbacks.
 153  *
 154  * \param vdev vhost device.
 155  * \param arg user-provided parameter.
 156  *
 157  * \return 0 on success, -1 on failure.
 158  */
 159 typedef int (*spdk_vhost_event_fn)(struct spdk_vhost_dev *vdev, void *arg);
 160
 161 /**
 162  * Get the name of the vhost device.  This is equal to the filename
 163  * of socket file. The name is constant throughout the lifetime of
 164  * a vdev.
 165  *
 166  * \param vdev vhost device.
 167  *
 168  * \return name of the vdev.
 169  */
 170 const char *spdk_vhost_dev_get_name(struct spdk_vhost_dev *vdev);
 171
 172 /**
 173  * Get cpuset of the vhost device.  The cpuset is constant throughout the lifetime
 174  * of a vdev. It is a subset of SPDK app cpuset vhost was started with.
 175  *
 176  * \param vdev vhost device.
 177  *
 178  * \return cpuset of the vdev.
 179  */
 180 const struct spdk_cpuset *spdk_vhost_dev_get_cpumask(struct spdk_vhost_dev *vdev);
 181
 182 /**
 183  * By default, events are generated when asked, but for high queue depth and
 184  * high IOPS this prove to be inefficient both for guest kernel that have to
 185  * handle a lot more IO completions and for SPDK vhost that need to make more
 186  * syscalls. If enabled, limit amount of events (IRQs) sent to initiator by SPDK
 187  * vhost effectively coalescing couple of completions. This of cource introduce
 188  * IO latency penalty proportional to event delay time.
 189  *
 190  * Actual events delay time when is calculated according to below formula:
 191  * if (delay_base == 0 || IOPS < iops_threshold) {
 192  *   delay = 0;
 193  * } else if (IOPS < iops_threshold) {
 194  *   delay = delay_base * (iops - iops_threshold) / iops_threshold;
 195  * }
 196  *
 197  * \param vdev vhost device.
 198  * \param delay_base_us Base delay time in microseconds. If 0, coalescing is disabled.
 199  * \param iops_threshold IOPS threshold when coalescing is activated.
 200  */
 201 int spdk_vhost_set_coalescing(struct spdk_vhost_dev *vdev, uint32_t delay_base_us,
 202                               uint32_t iops_threshold);
 203
 204 /**
 205  * Get coalescing parameters.
 206  *
 207  * \see spdk_vhost_set_coalescing
 208  *
 209  * \param vdev vhost device.
 210  * \param delay_base_us Optional pointer to store base delay time.
 211  * \param iops_threshold Optional pointer to store IOPS threshold.
 212  */
 213 void spdk_vhost_get_coalescing(struct spdk_vhost_dev *vdev, uint32_t *delay_base_us,
 214                                uint32_t *iops_threshold);
 215
 216 /**
 217  * Construct an empty vhost SCSI device.  This will create a
 218  * Unix domain socket together with a vhost-user slave server waiting
 219  * for a connection on this socket. Creating the vdev does not
 220  * start any I/O pollers and does not hog the CPU. I/O processing
 221  * starts after receiving proper message on the created socket.
 222  * See QEMU's vhost-user documentation for details.
 223  * All physical devices have to be separately attached to this
 224  * vdev via \c spdk_vhost_scsi_dev_add_tgt().
 225  *
 226  * This function is thread-safe.
 227  *
 228  * \param name name of the vhost device. The name will also be used
 229  * for socket name, which is exactly \c socket_base_dir/name
 230  * \param cpumask string containing cpumask in hex. The leading *0x*
 231  * is allowed but not required. The mask itself can be constructed as:
 232  * ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)).
 233  *
 234  * \return 0 on success, negative errno on error.
 235  */
 236 int spdk_vhost_scsi_dev_construct(const char *name, const char *cpumask);
 237
 238 /**
 239  * Construct and attach new SCSI target to the vhost SCSI device
 240  * on given (unoccupied) slot.  The device will be created with a single
 241  * LUN0 associated with given SPDK bdev. Currently only one LUN per
 242  * device is supported.
 243  *
 244  * If the vhost SCSI device has an active connection and has negotiated
 245  * \c VIRTIO_SCSI_F_HOTPLUG feature,  the new SCSI target should be
 246  * automatically detected by the other side.
 247  *
 248  * \param vdev vhost SCSI device.
 249  * \param scsi_tgt_num slot to attach to or negative value to use first free.
 250  * \param bdev_name name of the SPDK bdev to associate with SCSI LUN0.
 251  *
 252  * \return value >= 0 on success - the SCSI target ID, negative errno code:
 253  * -EINVAL - one of the arguments is invalid:
 254  *   - vdev is not vhost SCSI device
 255  *   - SCSI target ID is out of range
 256  *   - bdev name is NULL
 257  *   - can't create SCSI LUN because of other errors e.g.: bdev does not exist
 258  * -ENOSPC - scsi_tgt_num is -1 and maximum targets in vhost SCSI device reached
 259  * -EEXIST - SCSI target ID already exists
 260  */
 261 int spdk_vhost_scsi_dev_add_tgt(struct spdk_vhost_dev *vdev, int scsi_tgt_num,
 262                                 const char *bdev_name);
 263
 264 /**
 265  * Get SCSI target from vhost SCSI device on given slot. Max
 266  * number of available slots is defined by.
 267  * \c SPDK_VHOST_SCSI_CTRLR_MAX_DEVS.
 268  *
 269  * \param vdev vhost SCSI device.
 270  * \param num slot id.
 271  *
 272  * \return SCSI device on given slot or NULL.
 273  */
 274 struct spdk_scsi_dev *spdk_vhost_scsi_dev_get_tgt(struct spdk_vhost_dev *vdev, uint8_t num);
 275
 276 /**
 277  * Detach and destruct SCSI target from a vhost SCSI device.
 278  *
 279  * The device will be deleted after all pending I/O is finished.
 280  * If the driver supports VIRTIO_SCSI_F_HOTPLUG, then a hotremove
 281  * notification will be sent.
 282  *
 283  * \param vdev vhost SCSI device
 284  * \param scsi_tgt_num slot id to delete target from
 285  * \param cb_fn callback to be fired once target has been successfully
 286  * deleted. The first parameter of callback function is the vhost SCSI
 287  * device, the second is user provided argument *cb_arg*.
 288  * \param cb_arg parameter to be passed to *cb_fn*.
 289  *
 290  * \return 0 on success, negative errno on error.
 291  */
 292 int spdk_vhost_scsi_dev_remove_tgt(struct spdk_vhost_dev *vdev, unsigned scsi_tgt_num,
 293                                    spdk_vhost_event_fn cb_fn, void *cb_arg);
 294
 295 /**
 296  * Construct a vhost blk device.  This will create a Unix domain
 297  * socket together with a vhost-user slave server waiting for a
 298  * connection on this socket. Creating the vdev does not start
 299  * any I/O pollers and does not hog the CPU. I/O processing starts
 300  * after receiving proper message on the created socket.
 301  * See QEMU's vhost-user documentation for details. Vhost blk
 302  * device is tightly associated with given SPDK bdev. Given
 303  * bdev can not be changed, unless it has been hotremoved. This
 304  * would result in all I/O failing with virtio \c VIRTIO_BLK_S_IOERR
 305  * error code.
 306  *
 307  * This function is thread-safe.
 308  *
 309  * \param name name of the vhost blk device. The name will also be
 310  * used for socket name, which is exactly \c socket_base_dir/name
 311  * \param cpumask string containing cpumask in hex. The leading *0x*
 312  * is allowed but not required. The mask itself can be constructed as:
 313  * ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)).
 314  * \param dev_name bdev name to associate with this vhost device
 315  * \param readonly if set, all writes to the device will fail with
 316  * \c VIRTIO_BLK_S_IOERR error code.
 317  * \param packed_ring this controller supports packed ring if set.
 318  *
 319  * \return 0 on success, negative errno on error.
 320  */
 321 int spdk_vhost_blk_construct(const char *name, const char *cpumask, const char *dev_name,
 322                              bool readonly, bool packed_ring);
 323
 324 /**
 325  * Remove a vhost device. The device must not have any open connections on it's socket.
 326  *
 327  * \param vdev vhost blk device.
 328  *
 329  * \return 0 on success, negative errno on error.
 330  */
 331 int spdk_vhost_dev_remove(struct spdk_vhost_dev *vdev);
 332
 333 #ifdef __cplusplus
 334 }
 335 #endif
 336
 337 #endif /* SPDK_VHOST_H */