Add UBLK docs

2025-08-24 16:55:58 +03:00
parent 31b7021330
commit db63e58b3d
13 changed files with 146 additions and 49 deletions
@@ -19,7 +19,7 @@ Vitastor нацелен в первую очередь на SSD и SSD+HDD кл
 TCP и RDMA и на хорошем железе может достигать задержки 4 КБ чтения и записи на уровне ~0.1 мс,
 что примерно в 10 раз быстрее, чем Ceph и другие популярные программные СХД.
-Vitastor поддерживает QEMU-драйвер, протоколы NBD и NFS, драйверы OpenStack, OpenNebula, Proxmox, Kubernetes.
+Vitastor поддерживает QEMU-драйвер, протоколы UBLK, NBD и NFS, драйверы OpenStack, OpenNebula, Proxmox, Kubernetes.
 Другие драйверы могут также быть легко реализованы.
 Подробности смотрите в документации по ссылкам. Можете начать отсюда: [Быстрый старт](docs/intro/quickstart.ru.md).
@@ -64,8 +64,9 @@ Vitastor поддерживает QEMU-драйвер, протоколы NBD и
  - [vitastor-cli](docs/usage/cli.ru.md) (консольный интерфейс)
  - [vitastor-disk](docs/usage/disk.ru.md) (управление дисками)
  - [fio](docs/usage/fio.ru.md) для тестов производительности
-  - [NBD](docs/usage/nbd.ru.md) для монтирования ядром
+  - [UBLK](docs/usage/ublk.ru.md) для монтирования ядром
-  - [QEMU и qemu-img](docs/usage/qemu.ru.md)
+  - [NBD](docs/usage/nbd.ru.md) - старый интерфейс для монтирования ядром
  - [QEMU, qemu-img и VDUSE](docs/usage/qemu.ru.md)
  - [NFS](docs/usage/nfs.ru.md) кластерная файловая система и псевдо-ФС прокси
  - [Администрирование](docs/usage/admin.ru.md)
 - Производительность
@@ -19,7 +19,7 @@ supports TCP and RDMA and may achieve 4 KB read and write latency as low as ~0.1
 with proper hardware which is ~10 times faster than other popular SDS's like Ceph
 or internal systems of public clouds.
-Vitastor supports QEMU, NBD, NFS protocols, OpenStack, OpenNebula, Proxmox, Kubernetes drivers.
+Vitastor supports QEMU, UBLK, NBD, NFS protocols, OpenStack, OpenNebula, Proxmox, Kubernetes drivers.
 More drivers may be created easily.
 Read more details in the documentation. You can start from here: [Quick Start](docs/intro/quickstart.en.md).
@@ -64,8 +64,9 @@ Read more details in the documentation. You can start from here: [Quick Start](d
  - [vitastor-cli](docs/usage/cli.en.md) (command-line interface)
  - [vitastor-disk](docs/usage/disk.en.md) (disk management tool)
  - [fio](docs/usage/fio.en.md) for benchmarks
-  - [NBD](docs/usage/nbd.en.md) for kernel mounts
+  - [UBLK](docs/usage/ublk.en.md) for kernel mounts
-  - [QEMU and qemu-img](docs/usage/qemu.en.md)
+  - [NBD](docs/usage/nbd.en.md) - old interface for kernel mounts
  - [QEMU, qemu-img and VDUSE](docs/usage/qemu.en.md)
  - [NFS](docs/usage/nfs.en.md) clustered file system and pseudo-FS proxy
  - [Administration](docs/usage/admin.en.md)
 - Performance
@@ -25,6 +25,8 @@ affect their interaction with the cluster.
 - [nbd_max_part](#nbd_max_part)
 - [osd_nearfull_ratio](#osd_nearfull_ratio)
 - [hostname](#hostname)
 - [ublk_queue_depth](#ublk_queue_depth)
 - [ublk_max_io_size](#ublk_max_io_size)
 ## client_iothread_count
@@ -225,3 +227,17 @@ without destroying and recreating OSDs.
 Clients use host name to find their distance to OSDs when [localized reads](pool.en.md#local_reads)
 are enabled. By default, standard [gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html)
 function is used to determine host name, but you can also override it with this parameter.
 ## ublk_queue_depth
 - Type: integer
 - Default: 256
 Default queue depth for [Vitastor ublk servers](../usage/ublk.en.md).
 ## ublk_max_io_size
 - Type: integer
 Default maximum I/O size for Vitastor [ublk servers](../usage/ublk.en.md).
 The largest of 1 MB and pool block size multiplied by EC data chunk count is used if not specified.
@@ -25,6 +25,8 @@
 - [nbd_max_part](#nbd_max_part)
 - [osd_nearfull_ratio](#osd_nearfull_ratio)
 - [hostname](#hostname)
 - [ublk_queue_depth](#ublk_queue_depth)
 - [ublk_max_io_size](#ublk_max_io_size)
 ## client_iothread_count
@@ -230,3 +232,18 @@ RDMA и хотите повысить пиковую производитель
 [локальные чтения](pool.ru.md#local_reads). По умолчанию для определения имени
 хоста используется стандартная функция [gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html),
 но вы также можете задать имя хоста вручную данным параметром.
 ## ublk_queue_depth
 - Тип: целое число
 - Значение по умолчанию: 256
 Глубина очереди по умолчанию для [ublk-серверов Vitastor](../usage/ublk.ru.md).
 ## ublk_max_io_size
 - Тип: целое число
 Максимальный размер запроса ввода-вывода для [ublk-серверов Vitastor](../usage/ublk.ru.md).
 Если не задан, используется максимум из 1 МБ и размера блока пула, умноженного на число частей
 данных EC-пула.
@@ -283,3 +283,19 @@
    [локальные чтения](pool.ru.md#local_reads). По умолчанию для определения имени
    хоста используется стандартная функция [gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html),
    но вы также можете задать имя хоста вручную данным параметром.
 - name: ublk_queue_depth
  type: int
  default: 256
  online: false
  info: Default queue depth for [Vitastor ublk servers](../usage/ublk.en.md).
  info_ru: Глубина очереди по умолчанию для [ublk-серверов Vitastor](../usage/ublk.ru.md).
 - name: ublk_max_io_size
  type: int
  online: false
  info: |
    Default maximum I/O size for Vitastor [ublk servers](../usage/ublk.en.md).
    The largest of 1 MB and pool block size multiplied by EC data chunk count is used if not specified.
  info_ru: |
    Максимальный размер запроса ввода-вывода для [ublk-серверов Vitastor](../usage/ublk.ru.md).
    Если не задан, используется максимум из 1 МБ и размера блока пула, умноженного на число частей
    данных EC-пула.
@@ -24,6 +24,8 @@
 {{../../installation/kubernetes.en.md}}
 {{../../installation/s3.en.md}}
 {{../../installation/source.en.md}}
 {{../../config.en.md|indent=1}}
@@ -54,6 +56,8 @@
 {{../../usage/fio.en.md}}
 {{../../usage/ublk.en.md}}
 {{../../usage/nbd.en.md}}
 {{../../usage/qemu.en.md}}
@@ -26,6 +26,8 @@
 {{../../installation/source.ru.md}}
 {{../../installation/s3.ru.md}}
 {{../../config.ru.md|indent=1}}
 {{../../config/common.ru.md|indent=2}}
@@ -54,6 +56,8 @@
 {{../../usage/fio.ru.md}}
 {{../../usage/ublk.ru.md}}
 {{../../usage/nbd.ru.md}}
 {{../../usage/qemu.ru.md}}
@@ -52,7 +52,7 @@
 - Generic user-space client library
 - [Native QEMU driver](../usage/qemu.en.md)
 - [Loadable fio engine for benchmarks](../usage/fio.en.md)
- [NBD proxy for kernel mounts](../usage/nbd.en.md)
+- [UBLK](../usage/ublk.en.md) and [NBD](../usage/nbd.en.md) servers for kernel mounts
 - [Simplified NFS proxy for file-based image access emulation (suitable for VMWare)](../usage/nfs.en.md#pseudo-fs)
 ## Roadmap
@@ -54,7 +54,7 @@
 - Общая пользовательская клиентская библиотека для работы с кластером
 - [Драйвер диска для QEMU](../usage/qemu.ru.md)
 - [Драйвер диска для утилиты тестирования производительности fio](../usage/fio.ru.md)
- [NBD-прокси для монтирования образов ядром](../usage/nbd.ru.md) ("блочное устройство в режиме пользователя")
+- [UBLK](../usage/ublk.ru.md) и [NBD](../usage/nbd.ru.md) серверы для монтирования образов ядром ("блочное устройство в режиме пользователя")
 - [Упрощённая NFS-прокси для эмуляции файлового доступа к образам (подходит для VMWare)](../usage/nfs.ru.md#псевдо-фс)
 ## Планы развития
@@ -130,23 +130,16 @@ Linux kernel, starting with version 5.15, supports a new interface for attaching
 to the host - VDUSE (vDPA Device in Userspace). QEMU, starting with 7.2, has support for
 exporting QEMU block devices over this protocol using qemu-storage-daemon.
-VDUSE is currently the best interface to attach Vitastor disks as kernel devices because:
+VDUSE advantages:
- It avoids data copies and thus achieves much better performance than [NBD](nbd.en.md)
+
- It doesn't have NBD timeout problem - the device doesn't die if an operation executes for too long
+- VDUSE copies memory 1 time instead of 2, and is thus faster than [NBD](nbd.en.md) for linear read/write.
 - It doesn't have NBD timeout problem - the device doesn't die if an operation executes for too long.
 - It doesn't have hung device problem - if the userspace process dies it can be restarted (!)
-  and block device will continue operation
+  and block device will continue operation (UBLK can do it too).
- It doesn't seem to have the device number limit
+- It doesn't seem to have the device number limit (UBLK also doesn't).
-Example performance comparison:
+At the same time, VDUSE may be slower or faster than [UBLK](ublk.en.md) for linear read/write,
-
+and iops-wise it's sometimes even slower than NBD. See performance comparison examples at the page [UBLK](ublk.en.md).
 |                      | direct fio  | NBD         | VDUSE       |
 |----------------------|-------------|-------------|-------------|
 | linear write         | 3.85 GB/s   | 1.12 GB/s   | 3.85 GB/s   |
 | 4k random write Q128 | 240000 iops | 120000 iops | 178000 iops |
 | 4k random write Q1   | 9500 iops   | 7620 iops   | 7640 iops   |
 | linear read          | 4.3 GB/s    | 1.8 GB/s    | 2.85 GB/s   |
 | 4k random read Q128  | 287000 iops | 140000 iops | 189000 iops |
 | 4k random read Q1    | 9600 iops   | 7640 iops   | 7780 iops   |
 To try VDUSE you need at least Linux 5.15, built with VDUSE support
 (CONFIG_VDPA=m, CONFIG_VDPA_USER=m, CONFIG_VIRTIO_VDPA=m).
@@ -132,24 +132,16 @@ qemu-system-x86_64 -enable-kvm -m 2048 -M accel=kvm,memory-backend=mem \
 к системе - VDUSE (vDPA Device in Userspace), а в QEMU, начиная с версии 7.2, есть поддержка
 экспорта блочных устройств QEMU по этому протоколу через qemu-storage-daemon.
-VDUSE - на данный момент лучший интерфейс для подключения дисков Vitastor в виде блочных
+Преимущества VDUSE:
 устройств на уровне ядра, ибо:
 - VDUSE не копирует данные и поэтому достигает значительно лучшей производительности, чем [NBD](nbd.ru.md)
 - Также оно не имеет проблемы NBD-таймаута - устройство не умирает, если операция выполняется слишком долго
 - Также оно не имеет проблемы подвисающих устройств - если процесс-обработчик умирает, его можно
  перезапустить (!) и блочное устройство продолжит работать
 - По-видимому, у него нет предела числа подключаемых в систему устройств
-Пример сравнения производительности:
+- VDUSE копирует данные 1 раз, а не 2, и поэтому он быстрее, чем [NBD](nbd.ru.md) при линейном доступе.
 - VDUSE не имеет проблемы NBD-таймаута - устройство не умирает, если операция выполняется слишком долго.
 - VDUSE не имеет проблемы подвисающих устройств - если процесс-обработчик умирает, его можно
  перезапустить (!) и блочное устройство продолжит работать (в UBLK это тоже поддерживается).
 - По-видимому, у него нет предела числа подключаемых в систему устройств (в UBLK лимита тоже нет).
-|                          | Прямой fio  | NBD         | VDUSE       |
+Однако, при линейном доступе VDUSE может быть медленнее UBLK (а может быть и быстрее), а по iops
-|--------------------------|-------------|-------------|-------------|
+VDUSE иногда даже медленнее NBD. Пример сравнения производительности смотрите на странице [UBLK](ublk.ru.md).
 | линейная запись          | 3.85 GB/s   | 1.12 GB/s   | 3.85 GB/s   |
 | 4k случайная запись Q128 | 240000 iops | 120000 iops | 178000 iops |
 | 4k случайная запись Q1   | 9500 iops   | 7620 iops   | 7640 iops   |
 | линейное чтение          | 4.3 GB/s    | 1.8 GB/s    | 2.85 GB/s   |
 | 4k случайное чтение Q128 | 287000 iops | 140000 iops | 189000 iops |
 | 4k случайное чтение Q1   | 9600 iops   | 7640 iops   | 7780 iops   |
 Чтобы попробовать VDUSE, вам нужно ядро Linux как минимум версии 5.15, собранное с поддержкой
 VDUSE (CONFIG_VDPA=m, CONFIG_VDPA_USER=m, CONFIG_VIRTIO_VDPA=m).
@@ -1,4 +1,4 @@
-[Documentation](../../README.md#documentation) → Usage → ublk
+[Documentation](../../README.md#documentation) → Usage → UBLK
 -----
@@ -9,11 +9,37 @@
 [ublk](https://docs.kernel.org/block/ublk.html) is a new io_uring-based Linux interface
 for user-space block device drivers, available since Linux 6.0.
-It's still not zero-copy, but so far it's the fastest userspace block device interface,
+It's not zero-copy, but it's still a fast implementation, outperforming both [NBD](nbd.en.md)
-outperforming both [NBD](nbd.en.md) and [VDUSE](qemu.en.md#vduse). It also allows to recover
+and [VDUSE](qemu.en.md#vduse) iops-wise and may or may not outperform VDUSE in linear I/O MB/s.
-devices even if the server (vitastor-ublk process) dies.
+ublk also allows to recover devices even if the server (vitastor-ublk process) dies.
-Supports the following commands:
+## Example performance comparison
 TCP (100G), 3 hosts each with 6 NVMe OSDs, 3 replicas, single client
 |                      | direct fio  | NBD         | VDUSE      | UBLK        |
 |----------------------|-------------|-------------|------------|-------------|
 | linear write         | 3807 MB/s   | 1832 MB/s   | 3226 MB/s  | 3027 MB/s   |
 | linear read          | 3067 MB/s   | 1885 MB/s   | 1800 MB/s  | 2076 MB/s   |
 | 4k random write Q128 | 128624 iops | 91060 iops  | 94621 iops | 149450 iops |
 | 4k random read Q128  | 117769 iops | 153408 iops | 93157 iops | 171987 iops |
 | 4k random write Q1   | 8090 iops   | 6442 iops   | 6316 iops  | 7272 iops   |
 | 4k random read Q1    | 9474 iops   | 7200 iops   | 6840 iops  | 8038 iops   |
 RDMA (100G), 3 hosts each with 6 NVMe OSDs, 3 replicas, single client
 |                      | direct fio  | NBD         | VDUSE       | UBLK        |
 |----------------------|-------------|-------------|-------------|-------------|
 | linear write         | 6998 MB/s   | 1878 MB/s   | 4249 MB/s   | 3140 MB/s   |
 | linear read          | 8628 MB/s   | 3389 MB/s   | 5062 MB/s   | 3674 MB/s   |
 | 4k random write Q128 | 222541 iops | 181589 iops | 138281 iops | 218222 iops |
 | 4k random read Q128  | 412647 iops | 239987 iops | 151663 iops | 269583 iops |
 | 4k random write Q1   | 11601 iops  | 8592 iops   | 9111 iops   | 10000 iops  |
 | 4k random read Q1    | 10102 iops  | 7788 iops   | 8111 iops   | 8965 iops   |
 ## Commands
 vitastor-ublk supports the following commands:
 - [map](#map)
 - [unmap](#unmap)
@@ -1,4 +1,4 @@
-[Документация](../../README-ru.md#документация) → Использование → ublk
+[Документация](../../README-ru.md#документация) → Использование → UBLK
 -----
@@ -9,11 +9,38 @@
 [ublk](https://docs.kernel.org/block/ublk.html) - это новый Linux-интерфейс на основе io_uring
 для реализации блочных устройств в пространстве пользователя, доступный, начиная с Linux 6.0.
-ublk тоже копирует память (т.е. не является zero-copy), но всё равно на данный момент является
+ublk тоже копирует память (т.е. не является zero-copy), но по IOPS всё равно обгоняет и
-самым быстрым интерфейсом ядерного блочного устройства и обгоняет и [NBD](nbd.ru.md), и [VDUSE](qemu.ru.md#vduse).
+[NBD](nbd.ru.md), и [VDUSE](qemu.ru.md#vduse), и иногда может даже обгонять VDUSE по
-Также он позволяет оживлять устройства, у которых умер сервер (процесс-обработчик vitastor-ublk).
+скорости линейного доступа. Также ublk позволяет оживлять устройства, у которых умер
 сервер (процесс-обработчик vitastor-ublk).
-Поддерживаются следующие команды:
+## Пример сравнения производительности
 TCP (100G), 3 сервера с 6 NVMe OSD каждый, 3 реплики, один клиент
 |                          | Прямой fio  | NBD         | VDUSE      | UBLK        |
 |--------------------------|-------------|-------------|------------|-------------|
 | линейная запись          | 3807 MB/s   | 1832 MB/s   | 3226 MB/s  | 3027 MB/s   |
 | линейное чтение          | 3067 MB/s   | 1885 MB/s   | 1800 MB/s  | 2076 MB/s   |
 | 4k случайная запись Q128 | 128624 iops | 91060 iops  | 94621 iops | 149450 iops |
 | 4k случайное чтение Q128 | 117769 iops | 153408 iops | 93157 iops | 171987 iops |
 | 4k случайная запись Q1   | 8090 iops   | 6442 iops   | 6316 iops  | 7272 iops   |
 | 4k случайное чтение Q1   | 9474 iops   | 7200 iops   | 6840 iops  | 8038 iops   |
 RDMA (100G), 3 сервера с 6 NVMe OSD каждый, 3 реплики, один клиент
 |                          | Прямой fio  | NBD         | VDUSE       | UBLK        |
 |--------------------------|-------------|-------------|-------------|-------------|
 | линейная запись          | 6998 MB/s   | 1878 MB/s   | 4249 MB/s   | 3140 MB/s   |
 | линейное чтение          | 8628 MB/s   | 3389 MB/s   | 5062 MB/s   | 3674 MB/s   |
 | 4k случайная запись Q128 | 222541 iops | 181589 iops | 138281 iops | 218222 iops |
 | 4k случайное чтение Q128 | 412647 iops | 239987 iops | 151663 iops | 269583 iops |
 | 4k случайная запись Q1   | 11601 iops  | 8592 iops   | 9111 iops   | 10000 iops  |
 | 4k случайное чтение Q1   | 10102 iops  | 7788 iops   | 8111 iops   | 8965 iops   |
 ## Команды
 vitastor-ublk поддерживает следующие команды:
 - [map](#map)
 - [unmap](#unmap)