plugins/blkio/nbdkit-blkio-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-blkio-plugin - libblkio plugin for NVMe, vhost-user, vDPA, VFIO
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit blkio [driver=]DRIVER [path=FILENAME] [num-queues=N] ...
   8
   9 =head1 DESCRIPTION
  10
  11 nbdkit-blkio-plugin is an L<nbdkit(1)> plugin for using
  12 L<libblkio|https://libblkio.gitlab.io/libblkio> to access various disk
  13 sources used for high performance applications and virtualization.
  14 These include: NVMe, vhost-user, vDPA and VFIO.
  15
  16 The first parameter after the plugin name should be the L<libblkio
  17 driver|https://libblkio.gitlab.io/libblkio/blkio.html#drivers>.  For
  18 example:
  19
  20  nbdkit blkio virtio-blk-vhost-user path=vhost.sock
  21           │              │               │
  22         plugin         driver       other parameters
  23
  24 =head2 Driver: C<nvme-io_uring>
  25
  26  nbdkit blkio nvme-io_uring path=/dev/ng0n1
  27
  28 Connect to an NVMe device, issuing commands through Linux io_uring
  29 (requires Linux E<ge> 5.19).
  30
  31 =head2 Driver: C<virtio-blk-vfio-pci>
  32
  33  nbdkit blkio virtio-blk-vfio-pci path=/sys/bus/pci/devices/0000:00:01.0
  34
  35 Connect to a PCI device which implements virtio-blk using VFIO.  The
  36 path is the path to the device's sysfs directory (see L<lspci(8)>).
  37
  38 =head2 Driver: C<virtio-blk-vhost-user>
  39
  40  nbdkit blkio virtio-blk-vhost-user path=vhost.sock
  41
  42 Connect to a vhost-user block device, such as one exported by
  43 L<qemu-storage-daemon(1)>.  The path is the vhost-user Unix domain
  44 socket.  For example:
  45
  46  qemu-storage-daemon \
  47     --blockdev driver=file,node-name=file,filename=disk.qcow2 \
  48     --blockdev driver=qcow2,node-name=qcow2,file=file \
  49     --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost.sock,node-name=qcow2,writable=on
  50
  51 =head2 Driver: C<virtio-blk-vhost-vdpa>
  52
  53  nbdkit blkio virtio-blk-vhost-vdpa path=chardev
  54
  55 Connect to a vDPA device which might be implemented in software
  56 (eg. VDUSE) or hardware.  The path is the vhost-vdpa character device.
  57
  58 =head2 Driver: C<io_uring>
  59
  60  nbdkit blkio io_uring path=FILENAME
  61
  62 You can use this driver to access local files and block devices
  63 through the libblkio C<io_uring> driver, but it is usually faster and
  64 easier to use L<nbdkit-file-plugin(1)>.
  65
  66 =head1 PARAMETERS
  67
  68 =over 4
  69
  70 =item [B<driver=>]DRIVER
  71
  72 The name of the libblkio driver to use.
  73
  74 This parameter is required.
  75
  76 C<driver=> is a magic config key and may be omitted in most cases.
  77 See L<nbdkit(1)/Magic parameters>.
  78
  79 =item PROPERTYB<=>VALUE
  80
  81 Properties such as C<path>, C<num-entries> etc are translated to
  82 libblkio properties.  Consult the L<libblkio
  83 documentation|https://libblkio.gitlab.io/libblkio/blkio.html> for a
  84 complete list.
  85
  86 =item B<get=>PROPERTY
  87
  88 Get (print) the value of a property after connecting.  The property is
  89 fetched and printed in nbdkit debug output, so you will need to use
  90 the I<--verbose> flag.  This is useful for debugging.
  91
  92 =back
  93
  94 =head1 FILES
  95
  96 =over 4
  97
  98 =item F<$plugindir/nbdkit-blkio-plugin.so>
  99
 100 The plugin.
 101
 102 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 103
 104 =back
 105
 106 =head1 VERSION
 107
 108 C<nbdkit-blkio-plugin> first appeared in nbdkit 1.34.
 109
 110 =head1 SEE ALSO
 111
 112 L<nbdkit-file-plugin(1)>,
 113 L<lspci(8)>,
 114 L<qemu-storage-daemon(1)>,
 115 L<https://libblkio.gitlab.io/libblkio>,
 116 L<https://libblkio.gitlab.io/libblkio/blkio.html>.
 117
 118 =head1 AUTHORS
 119
 120 Richard W.M. Jones
 121
 122 =head1 COPYRIGHT
 123
 124 Copyright Red Hat