SPDK vhost. More...

Typedefs
typedef void(*	spdk_vhost_init_cb) (int rc)
	Callback for spdk_vhost_blk\|scsi_init().

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.

Functions
int	spdk_vhost_set_socket_path (const char *basename)
	Set the path to the directory where vhost sockets will be created.

void	spdk_vhost_scsi_init (spdk_vhost_init_cb init_cb)
	Init vhost environment.

void	spdk_vhost_scsi_fini (spdk_vhost_fini_cb fini_cb)
	Clean up the environment of vhost.

void	spdk_vhost_scsi_config_json (struct spdk_json_write_ctx *w)
	Write vhost subsystem configuration into provided JSON context.

void	spdk_vhost_blk_init (spdk_vhost_init_cb init_cb)
	Init vhost environment.

void	spdk_vhost_blk_fini (spdk_vhost_fini_cb fini_cb)
	Clean up the environment of vhost.

void	spdk_vhost_blk_config_json (struct spdk_json_write_ctx *w)
	Write vhost subsystem configuration into provided JSON context.

void	spdk_vhost_shutdown_cb (void)
	Deinit vhost application.

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.

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.

struct spdk_vhost_dev *	spdk_vhost_dev_next (struct spdk_vhost_dev *vdev)
	Get the next vhost device.

const char *	spdk_vhost_dev_get_name (struct spdk_vhost_dev *vdev)
	Get the name of the vhost device.

const struct spdk_cpuset *	spdk_vhost_dev_get_cpumask (struct spdk_vhost_dev *vdev)
	Get cpuset of the vhost device.

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.

void	spdk_vhost_get_coalescing (struct spdk_vhost_dev vdev, uint32_t delay_base_us, uint32_t *iops_threshold)
	Get coalescing parameters.

int	spdk_vhost_scsi_dev_construct (const char name, const char cpumask)
	Construct an empty vhost SCSI device.

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.

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.

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.

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.

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.

int	spdk_vhost_dev_remove (struct spdk_vhost_dev *vdev)
	Remove a vhost device.

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

vdev	vhost device.
arg	user-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

rc	0 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

w	JSON 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

name	name of the vhost blk device. The name will also be used for socket name, which is exactly `socket_base_dir/name`
cpumask	string 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_name	bdev name to associate with this vhost device
transport	virtio blk transport name (default: vhost_user_blk)
params	JSON 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_cb Function 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_cb Function 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

vdev	vhost 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

vdev	vhost 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

vdev	vhost 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

vdev	vhost 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

vdev	vhost device.
delay_base_us	Optional pointer to store base delay time.
iops_threshold	Optional 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

w	JSON 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

vdev	vhost SCSI device.
scsi_tgt_num	slot to attach to or negative value to use first free.
bdev_name	name 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

name	name of the vhost device. The name will also be used for socket name, which is exactly `socket_base_dir/name`
cpumask	string 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

name	name of the vhost device. The name will also be used for socket name, which is exactly `socket_base_dir/name`
cpumask	string 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

vdev	vhost SCSI device.
num	slot 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

vdev	vhost SCSI device
scsi_tgt_num	slot id to delete target from
cb_fn	callback 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_arg	parameter 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_cb Function 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_cb Function 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

vdev	vhost device.
delay_base_us	Base delay time in microseconds. If 0, coalescing is disabled.
iops_threshold	IOPS 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

basename Path 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.

vhost.h File Reference

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ spdk_vhost_event_fn

◆ spdk_vhost_init_cb

Function Documentation

◆ spdk_vhost_blk_config_json()

◆ spdk_vhost_blk_construct()

◆ spdk_vhost_blk_fini()

◆ spdk_vhost_blk_init()

◆ spdk_vhost_dev_find()

◆ spdk_vhost_dev_get_cpumask()

◆ spdk_vhost_dev_get_name()

◆ spdk_vhost_dev_next()

◆ spdk_vhost_dev_remove()

◆ spdk_vhost_get_coalescing()

◆ spdk_vhost_scsi_config_json()

◆ spdk_vhost_scsi_dev_add_tgt()

◆ spdk_vhost_scsi_dev_construct()

◆ spdk_vhost_scsi_dev_construct_no_start()

◆ spdk_vhost_scsi_dev_get_tgt()

◆ spdk_vhost_scsi_dev_remove_tgt()

◆ spdk_vhost_scsi_fini()

◆ spdk_vhost_scsi_init()

◆ spdk_vhost_set_coalescing()

◆ spdk_vhost_set_socket_path()

◆ spdk_vhost_shutdown_cb()

◆ spdk_vhost_trylock()