vhost.h File Reference

SPDK vhost. More...

Typedefs

typedef void(* spdk_vhost_init_cb) (int rc)
 Callback for spdk_vhost_blk|scsi_init(). More...
 
typedef void(* spdk_vhost_fini_cb) (void)
 Callback for spdk_vhost_blk|scsi_fini().
 
typedef int(* spdk_vhost_event_fn) (struct spdk_vhost_dev *vdev, void *arg)
 Synchronized vhost event used for user callbacks. More...
 

Functions

int spdk_vhost_set_socket_path (const char *basename)
 Set the path to the directory where vhost sockets will be created. More...
 
void spdk_vhost_scsi_init (spdk_vhost_init_cb init_cb)
 Init vhost environment. More...
 
void spdk_vhost_scsi_fini (spdk_vhost_fini_cb fini_cb)
 Clean up the environment of vhost. More...
 
void spdk_vhost_scsi_config_json (struct spdk_json_write_ctx *w)
 Write vhost subsystem configuration into provided JSON context. More...
 
void spdk_vhost_blk_init (spdk_vhost_init_cb init_cb)
 Init vhost environment. More...
 
void spdk_vhost_blk_fini (spdk_vhost_fini_cb fini_cb)
 Clean up the environment of vhost. More...
 
void spdk_vhost_blk_config_json (struct spdk_json_write_ctx *w)
 Write vhost subsystem configuration into provided JSON context. More...
 
void spdk_vhost_shutdown_cb (void)
 Deinit vhost application. More...
 
void spdk_vhost_lock (void)
 Lock the global vhost mutex synchronizing all the vhost device accesses.
 
int spdk_vhost_trylock (void)
 Lock the global vhost mutex synchronizing all the vhost device accesses. More...
 
void spdk_vhost_unlock (void)
 Unlock the global vhost mutex.
 
struct spdk_vhost_dev * spdk_vhost_dev_find (const char *name)
 Find a vhost device by name. More...
 
struct spdk_vhost_dev * spdk_vhost_dev_next (struct spdk_vhost_dev *vdev)
 Get the next vhost device. More...
 
const char * spdk_vhost_dev_get_name (struct spdk_vhost_dev *vdev)
 Get the name of the vhost device. More...
 
const struct spdk_cpusetspdk_vhost_dev_get_cpumask (struct spdk_vhost_dev *vdev)
 Get cpuset of the vhost device. More...
 
int spdk_vhost_set_coalescing (struct spdk_vhost_dev *vdev, uint32_t delay_base_us, uint32_t iops_threshold)
 By default, events are generated when asked, but for high queue depth and high IOPS this prove to be inefficient both for guest kernel that have to handle a lot more IO completions and for SPDK vhost that need to make more syscalls. More...
 
void spdk_vhost_get_coalescing (struct spdk_vhost_dev *vdev, uint32_t *delay_base_us, uint32_t *iops_threshold)
 Get coalescing parameters. More...
 
int spdk_vhost_scsi_dev_construct (const char *name, const char *cpumask)
 Construct an empty vhost SCSI device. More...
 
int spdk_vhost_scsi_dev_construct_no_start (const char *name, const char *cpumask)
 Create an empty vhost SCSI device like spdk_vhost_scsi_dev_construct but do not start the controller. More...
 
int spdk_vhost_scsi_dev_add_tgt (struct spdk_vhost_dev *vdev, int scsi_tgt_num, const char *bdev_name)
 Construct and attach new SCSI target to the vhost SCSI device on given (unoccupied) slot. More...
 
struct spdk_scsi_dev * spdk_vhost_scsi_dev_get_tgt (struct spdk_vhost_dev *vdev, uint8_t num)
 Get SCSI target from vhost SCSI device on given slot. More...
 
int spdk_vhost_scsi_dev_remove_tgt (struct spdk_vhost_dev *vdev, unsigned scsi_tgt_num, spdk_vhost_event_fn cb_fn, void *cb_arg)
 Detach and destruct SCSI target from a vhost SCSI device. More...
 
int spdk_vhost_blk_construct (const char *name, const char *cpumask, const char *dev_name, const char *transport, const struct spdk_json_val *params)
 Construct a vhost blk device. More...
 
int spdk_vhost_dev_remove (struct spdk_vhost_dev *vdev)
 Remove a vhost device. More...
 

Detailed Description

SPDK vhost.

Typedef Documentation

◆ spdk_vhost_event_fn

typedef int(* spdk_vhost_event_fn) (struct spdk_vhost_dev *vdev, void *arg)

Synchronized vhost event used for user callbacks.

Parameters
vdevvhost device.
arguser-provided parameter.
Returns
0 on success, -1 on failure.

◆ spdk_vhost_init_cb

typedef void(* spdk_vhost_init_cb) (int rc)

Callback for spdk_vhost_blk|scsi_init().

Parameters
rc0 on success, negative errno on failure

Function Documentation

◆ spdk_vhost_blk_config_json()

void spdk_vhost_blk_config_json ( struct spdk_json_write_ctx *  w)

Write vhost subsystem configuration into provided JSON context.

Parameters
wJSON write context

◆ spdk_vhost_blk_construct()

int spdk_vhost_blk_construct ( const char *  name,
const char *  cpumask,
const char *  dev_name,
const char *  transport,
const struct spdk_json_val params 
)

Construct a vhost blk device.

This will create a Unix domain socket together with a vhost-user slave server waiting for a connection on this socket. Creating the vdev does not start any I/O pollers and does not hog the CPU. I/O processing starts after receiving proper message on the created socket. See QEMU's vhost-user documentation for details. Vhost blk device is tightly associated with given SPDK bdev. Given bdev can not be changed, unless it has been hotremoved. This would result in all I/O failing with virtio VIRTIO_BLK_S_IOERR error code.

This function is thread-safe.

Parameters
namename of the vhost blk device. The name will also be used for socket name, which is exactly socket_base_dir/name
cpumaskstring containing cpumask in hex. The leading 0x is allowed but not required. The mask itself can be constructed as: ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)).
dev_namebdev name to associate with this vhost device
transportvirtio blk transport name (default: vhost_user_blk)
paramsJSON value object containing variables: readonly if set, all writes to the device will fail with VIRTIO_BLK_S_IOERR error code. packed_ring this controller supports packed ring if set.
Returns
0 on success, negative errno on error.

◆ spdk_vhost_blk_fini()

void spdk_vhost_blk_fini ( spdk_vhost_fini_cb  fini_cb)

Clean up the environment of vhost.

Parameters
fini_cbFunction to be called when the cleanup is complete.

◆ spdk_vhost_blk_init()

void spdk_vhost_blk_init ( spdk_vhost_init_cb  init_cb)

Init vhost environment.

Parameters
init_cbFunction to be called when the initialization is complete.

◆ spdk_vhost_dev_find()

struct spdk_vhost_dev* spdk_vhost_dev_find ( const char *  name)

Find a vhost device by name.

Returns
vhost device or NULL

◆ spdk_vhost_dev_get_cpumask()

const struct spdk_cpuset* spdk_vhost_dev_get_cpumask ( struct spdk_vhost_dev *  vdev)

Get cpuset of the vhost device.

The cpuset is constant throughout the lifetime of a vdev. It is a subset of SPDK app cpuset vhost was started with.

Parameters
vdevvhost device.
Returns
cpuset of the vdev.

◆ spdk_vhost_dev_get_name()

const char* spdk_vhost_dev_get_name ( struct spdk_vhost_dev *  vdev)

Get the name of the vhost device.

This is equal to the filename of socket file. The name is constant throughout the lifetime of a vdev.

Parameters
vdevvhost device.
Returns
name of the vdev.

◆ spdk_vhost_dev_next()

struct spdk_vhost_dev* spdk_vhost_dev_next ( struct spdk_vhost_dev *  vdev)

Get the next vhost device.

If there's no more devices to iterate through, NULL will be returned.

Parameters
vdevvhost device. If NULL, this function will return the very first device.
Returns
vdev vhost device or NULL

◆ spdk_vhost_dev_remove()

int spdk_vhost_dev_remove ( struct spdk_vhost_dev *  vdev)

Remove a vhost device.

The device must not have any open connections on it's socket.

Parameters
vdevvhost blk device.
Returns
0 on success, negative errno on error.

◆ spdk_vhost_get_coalescing()

void spdk_vhost_get_coalescing ( struct spdk_vhost_dev *  vdev,
uint32_t *  delay_base_us,
uint32_t *  iops_threshold 
)

Get coalescing parameters.

See also
spdk_vhost_set_coalescing
Parameters
vdevvhost device.
delay_base_usOptional pointer to store base delay time.
iops_thresholdOptional pointer to store IOPS threshold.

◆ spdk_vhost_scsi_config_json()

void spdk_vhost_scsi_config_json ( struct spdk_json_write_ctx *  w)

Write vhost subsystem configuration into provided JSON context.

Parameters
wJSON write context

◆ spdk_vhost_scsi_dev_add_tgt()

int spdk_vhost_scsi_dev_add_tgt ( struct spdk_vhost_dev *  vdev,
int  scsi_tgt_num,
const char *  bdev_name 
)

Construct and attach new SCSI target to the vhost SCSI device on given (unoccupied) slot.

The device will be created with a single LUN0 associated with given SPDK bdev. Currently only one LUN per device is supported.

If the vhost SCSI device has an active connection and has negotiated VIRTIO_SCSI_F_HOTPLUG feature, the new SCSI target should be automatically detected by the other side.

Parameters
vdevvhost SCSI device.
scsi_tgt_numslot to attach to or negative value to use first free.
bdev_namename of the SPDK bdev to associate with SCSI LUN0.
Returns
value >= 0 on success - the SCSI target ID, negative errno code: -EINVAL - one of the arguments is invalid:
  • vdev is not vhost SCSI device
  • SCSI target ID is out of range
  • bdev name is NULL
  • can't create SCSI LUN because of other errors e.g.: bdev does not exist -ENOSPC - scsi_tgt_num is -1 and maximum targets in vhost SCSI device reached -EEXIST - SCSI target ID already exists

◆ spdk_vhost_scsi_dev_construct()

int spdk_vhost_scsi_dev_construct ( const char *  name,
const char *  cpumask 
)

Construct an empty vhost SCSI device.

This will create a Unix domain socket together with a vhost-user slave server waiting for a connection on this socket. Creating the vdev does not start any I/O pollers and does not hog the CPU. I/O processing starts after receiving proper message on the created socket. See QEMU's vhost-user documentation for details. All physical devices have to be separately attached to this vdev via spdk_vhost_scsi_dev_add_tgt().

This function is thread-safe.

Parameters
namename of the vhost device. The name will also be used for socket name, which is exactly socket_base_dir/name
cpumaskstring containing cpumask in hex. The leading 0x is allowed but not required. The mask itself can be constructed as: ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)).
Returns
0 on success, negative errno on error.

◆ spdk_vhost_scsi_dev_construct_no_start()

int spdk_vhost_scsi_dev_construct_no_start ( const char *  name,
const char *  cpumask 
)

Create an empty vhost SCSI device like spdk_vhost_scsi_dev_construct but do not start the controller.

This function is thread-safe.

Parameters
namename of the vhost device. The name will also be used for socket name, which is exactly socket_base_dir/name
cpumaskstring containing cpumask in hex. The leading 0x is allowed but not required. The mask itself can be constructed as: ((1 << cpu0) | (1 << cpu1) | ... | (1 << cpuN)).
Returns
0 on success, negative errno on error.

◆ spdk_vhost_scsi_dev_get_tgt()

struct spdk_scsi_dev* spdk_vhost_scsi_dev_get_tgt ( struct spdk_vhost_dev *  vdev,
uint8_t  num 
)

Get SCSI target from vhost SCSI device on given slot.

Max number of available slots is defined by. SPDK_VHOST_SCSI_CTRLR_MAX_DEVS.

Parameters
vdevvhost SCSI device.
numslot id.
Returns
SCSI device on given slot or NULL.

◆ spdk_vhost_scsi_dev_remove_tgt()

int spdk_vhost_scsi_dev_remove_tgt ( struct spdk_vhost_dev *  vdev,
unsigned  scsi_tgt_num,
spdk_vhost_event_fn  cb_fn,
void *  cb_arg 
)

Detach and destruct SCSI target from a vhost SCSI device.

The device will be deleted after all pending I/O is finished. If the driver supports VIRTIO_SCSI_F_HOTPLUG, then a hotremove notification will be sent.

Parameters
vdevvhost SCSI device
scsi_tgt_numslot id to delete target from
cb_fncallback to be fired once target has been successfully deleted. The first parameter of callback function is the vhost SCSI device, the second is user provided argument cb_arg.
cb_argparameter to be passed to cb_fn.
Returns
0 on success, negative errno on error.

◆ spdk_vhost_scsi_fini()

void spdk_vhost_scsi_fini ( spdk_vhost_fini_cb  fini_cb)

Clean up the environment of vhost.

Parameters
fini_cbFunction to be called when the cleanup is complete.

◆ spdk_vhost_scsi_init()

void spdk_vhost_scsi_init ( spdk_vhost_init_cb  init_cb)

Init vhost environment.

Parameters
init_cbFunction to be called when the initialization is complete.

◆ spdk_vhost_set_coalescing()

int spdk_vhost_set_coalescing ( struct spdk_vhost_dev *  vdev,
uint32_t  delay_base_us,
uint32_t  iops_threshold 
)

By default, events are generated when asked, but for high queue depth and high IOPS this prove to be inefficient both for guest kernel that have to handle a lot more IO completions and for SPDK vhost that need to make more syscalls.

If enabled, limit amount of events (IRQs) sent to initiator by SPDK vhost effectively coalescing couple of completions. This of course introduce IO latency penalty proportional to event delay time.

Actual events delay time when is calculated according to below formula: if (delay_base == 0 || IOPS < iops_threshold) { delay = 0; } else if (IOPS < iops_threshold) { delay = delay_base * (iops - iops_threshold) / iops_threshold; }

Parameters
vdevvhost device.
delay_base_usBase delay time in microseconds. If 0, coalescing is disabled.
iops_thresholdIOPS threshold when coalescing is activated.

◆ spdk_vhost_set_socket_path()

int spdk_vhost_set_socket_path ( const char *  basename)

Set the path to the directory where vhost sockets will be created.

This function must be called before spdk_vhost_init().

Parameters
basenamePath to vhost socket directory
Returns
0 on success, negative errno on error.

◆ spdk_vhost_shutdown_cb()

void spdk_vhost_shutdown_cb ( void  )

Deinit vhost application.

This is called once by SPDK app layer.

◆ spdk_vhost_trylock()

int spdk_vhost_trylock ( void  )

Lock the global vhost mutex synchronizing all the vhost device accesses.

Returns
0 if the mutex could be locked immediately, negative errno otherwise.