---

overview

io_uring通过使用先进的IO特性，以及内核支持下的各种免拷贝、免context switch特性，成为kernel下一代高性能异步IO接口，不同于libaio，io_uring支持direct和非direct IO。

Fundamentally, io_uring is just ring based communication channel. ---- Jens

IO请求通过submission queue SQ下发到内核中，内核完成IO之后通过completion queue CQ放回IO result。两个队列在用户态和内核态之间通过共享内存的方式沟通，从而免拷贝，每个SQE（submission queue entry）的大小为64byte，正好容纳近一个cache line。内核通过memory ordering、fense等技巧保证整个IO链路是不出错且高效的。

设计目标

作者Jens在文章中明确列出了io_uring的设计目标：

1. 易用 Easy to use。从笔者的角度来看，与现有的IO接口相比，io_uring相关syscall接口其实并不算易用，甚至理解起来也不算容易。作者自己也说，这些设计目标之间是有冲突的，特性丰富、高效还可伸缩的接口必然是很难用的。为了解决这个问题，作者为io_uring开发了一个配套的库liburing。既然支持全部需求的接口对于一般开发者来说使用难度过高，那就对其中最常用的部分再封装一层，提供一个更简单易用的接口。使用liburing无法使用io_uring全部的功能，特别是一些为高性能目标设计的功能，但能够使用一套风格与io_uring类似，但简单的多的接口来使用io_uring的基本功能，这对于大部分开发者来说也已经足够了。对于需要高级特性的开发者来说，也可以在使用liburing的基础上调用io_uring syscall接口来获取自己需要的特性，因为这类开发者一般也不会同时需要所有高级特性，而只是使用其中很小的一部分。这个设计方式值得我们学习，如何解决功能强大和接口易用之间的矛盾，“加一个中间层”永远是一个有效的思路。
2. 可扩展 Extendable。这里的可扩展指的是io_uring操作的IO设备类型是可扩展的，io_uring实现的异步接口不止能够用于块设备，也能够支持socket网络IO等非块设备，后续还可能支持更多fd类型，从接口语义方面没有限制。
3. 特性丰富 Feature rich。这一项是针对linux aio机制的局限性而来的。aio机制由于支持的特性不多，使用限制却很多，因此使用场景非常有限。作者的目标是在所有需要异步IO的场景都能够使用io_uring接口，并且不需要程序本身做架构级别的调整。
4. 高效 Efficiency。这里的高效主要体现在两个方面：
   1. 一是每次调用io_uring系统调用接口的开销要小，这里主要是和aio相比减少了每次调度传递的参数大小；
   2. 二是减少io_uring系统调用的次数，这是io_uring最重要的设计之一，通过一次系统调用提交多个IO请求的方式，io_uring可以大幅减少系统调用次数，这在spectre/meltdown修复导致系统调用开销显著上涨的背景下更加重要。
5. 可拓展性 Scalability。这里的Scalability不同于上文的Extendable，Scalability主要指随着使用IO使用系统资源的增多（主要指cpu计算之资源），IO性能会得到线性增长。因此io_uring占用系统资源是可调的。

io_uring系统调用

io_uring_setup

创建并配置io_uring

#include <linux/io_uring.h>
int io_uring_setup(u32 entries, struct io_uring_params *p);

通过io_uring_params设置申请uring的参数：

struct io_uring_params {
  __u32 sq_entries;  // 指定分配多少个sqe
  __u32 cq_entries;  // 指定分配多少个cqe
  __u32 flags;  // io_uring各种参数，包括IORING_SETUP_IOPOLL设置用户态polling，IORING_SETUP_SQPOLL设置内核态polling，IORING_SETUP_SQ_AFF设置内核态polling的绑核等等
  __u32 sq_thread_cpu;  // 内核态绑核
  __u32 sq_thread_idle;  // 内核态polling 如果idle超过sq_thread_idle milliseconds会进入休眠，进入休眠后用户态进程必须通过调用io_uring_enter设置IORING_SQ_NEED_WAKEUP 来唤醒内核polling线程
  __u32 features;  // 由内核填写，表明内核支持那些io_uring特性
  __u32 wq_fd;  // 可以指定一个已经存在的io_uring，而不重新创建
  __u32 resv[3];
  struct io_sqring_offsets sq_off;  // 指定sq的一些特性
  struct io_cqring_offsets cq_off;
};

ring创建好之后是以fd的形式呈现的，用户可以通过mmap的方式访问特定的ring

#define IORING_OFF_SQ_RING 0ULL
#define IORING_OFF_CQ_RING 0x8000000ULL
#define IO_RING_OFF_SQES   0x10000000ULL
// 通过以上三个flag来mmap对应的三片IOring的区域
// 下面举例：

sq->ring_ptr = mmap(0, sq->ring_sz, PROT_READ | PROT_WRITE,
    MAP_SHARED | MAP_POPULATE, fd, IORING_OFF_SQ_RING);
if (sq->ring_ptr == MAP_FAILED)
  return -errno;

sq->khead = sq->ring_ptr + p->sq_off.head;  // p就是之前设置的io_uring_params
sq->ktail = sq->ring_ptr + p->sq_off.tail;

// sq配置好之后，用户态进程作为生产者在sq tail追加sqe，kernel作为消费者从head获取待处理的sqe

上述讲解的是io_uring系统调用的方法，我们也可以使用上层封装liburinginclude/liburing.h中的函数进行初始化和下发IO

特性

我们可以通过io_uring_params配置io_uring不同的特性

1. hipri模式，通过配置flag参数IORING_SETUP_IOPOLL，可以使用用户态poll模式处理IO。这种场景下适配的硬件的completion事件不会中断上来更改uring的cq。用户需要自己收割查看硬件队列。这样可以带来更低是时延和更好的性能，经典的场景有如下两种：
   1. 通过poll模式降低系统context switch、中断开销，降低单个IO的时延，提高IOPS。
   2. 如果当前系统IO负载特别繁重（例如600K+ IOPS），传统的中断irq模式就会占用特别多的系统资源且变得低效，这时poll模式的优势就体现出来了。
2. polled IO submission，通过配置flag参数IORING_SETUP_SQPOLL，启动内核态poll，这意味着用户提交IO不用进入内核态通知内核，内核会持续的poll sq，
   1. 该场景下我们也可以通过IORING_SETUP_SQ_AFF绑定内核态polling的核
   2. 也可以配置参数sq_thread_idle控制内核的polling线程（某cpu core 的sys cpu会跑到100%）在空闲多少时间之后可以进入休眠。
   3. 也可以配置submit/complete IO在不同的code上。
3. 如果不设置以上两个参数，上层业务在调用io_uring_enter收割IO的时候会进入sleep（min>0），等待cq中有完成时entry，目前spdk uring_bdev 使用min=0的模式轮询查看CQ队列。 fio使用min>0阻塞等待cq返回。

io_uring_enter

int io_uring_enter(unsigned int fd, unsigned int to_submit, unsigned int min_complete, unsigned int flags, sigset_t sig);

在程序向sq，即请求队列中插入了IO请求后（可以通过io_uring_get_sqe插入），需要通知内核开始处理，这时就需要调用io_uring_enter。参数中的fd是io_uring的fd，to_submit是提交的IO请求数。

min_complete可以用来阻塞等待内核完成特定数量的请求，前提是flags中设置IORING_ENTER_GETEVENTS。这个功能可以单独调用来等待内核处理完成。需要注意的是由于采用共享内存队列的方式来同步请求完成情况，因此程序也可以不使用这个接口而是直接判断cqring的状态来获取IO完成情况并处理cqring中的完成事件（使用liburing中的io_uring_peek_cqe）。

io_uring_register

int io_uring_register(unsigned int fd, unsigned int opcode, void *arg, unsigned int nr_args);

这个syscall用于支持一些高级的优化用法，主要有两种模式，opcode分别为：

1. IORING_REGISTER_FILES。内核异步处理sqe请求时，需要保证fd不会在处理过程中被关闭，因此需要在开始处理前增加fd引用计数，结束后再减少。而调用这个接口后就可以避免这种反复的引用计数操作。在调用后指定的文件fd的引用计数会增加，后续提交请求时只要在sqe的flags中指定IOSQE_FIXED_FILE就不会再修改引用计数。如果不再需要操作这个fd，可以用IORING_UNREGISTER_FILES这个opcode解除注册。
2. IORING_REGISTER_BUFFERS。在使用O_DIRECT模式时，内核在处理IO时需要先映射用户态的页面，处理完后再解除映射（When O_DIRECT is used, the kernel must map the application pages into the kernel before it can do IO to them, and subsequently unmap those same pages when IO is done）（这意味着directIO应该是免拷贝的），这也是一种重复开销。使用这个opcode后，就可以把指定的buffer页面固定映射到内核中，处理请求时就不需要反复映射、解除映射。用户可以在下发IO的时候使用IORING_OP_READ_FIXED和IORING_OP_WRITE_FIXED指定当前IO使用fixed buffer中的空间。
3. IOURING_REGISTER_EVENTFD。和libaio类似，io_uring也可以注册一个eventfd，用户随后可以poll这个eventfd获取相关事件通知。

liburing

op code

IO entry中不同的opcode可指示kernel做不同的事情：

1. IORING_OP_NOP不做任何事，测试系统开销。
2. IORING_OP_READV常规读
3. IORING_OP_WRITEV常规写
4. IORING_OP_READ_FIXED使用fixed buffer进行读
5. IORING_OP_WRITE_FIXED使用fixed buffer进行写
6. IORING_OP_FSYNC类似fsync()系统调用，只不过是以异步的形式。
7. IORING_OP_POLL_ADD和IORING_OP_POLL_REMOVE可以使用io_uring poll特定的fd，只不过每次poll完成之后需要重新添加。
8. IORING_OP_TIMEOUT和IORING_OP_TIMEOUT_REMOVE，使用该OP下发的entry会在特定的timeout时间之后才会返回。
9. 还有一些网络相关OP

feature

使用io_uring_get_sqe获取一个新的sqe之后，可以通过sqe->flages设置特性，一些比较重要的特性列述如下：

1. IOSQE_IO_DRAIN，同步等待之前下发的io_uring command全部返回
2. IOSQE_IO_LINK，linked commands，设置在中，设置feature的command会在IO_uring中顺序完成，liburingexamples/link-cp.c

IO interfaces 比较

SW overhead	synchronous I/O	libaio	io_uring
system calls	at least 1 per I/O	2 per I/O batch	1 per patch, zero when using SQ submission thread
memory copy	yes	yes - SQE & CEQ	zero-copy for SQE&CQE
context switches	yes	yes	minimal context switching polling
interrupts	Interupt driven	Interupt driven	supports both interrupts and polling I/O
Blocking I/O	synchronous	asynchronous	asynchronous
buffer I/O	yes	no	yes

spdk+io_uring

目前spdk已经支持了io_uring，具体代码可见pdk/module/bdev/uring/bdev_uring.c，由于目前有一些远程挂载设备不支持IORING_SETUP_IOPOLL特性，spdk为了维护模块的通用性，目前的spdk实现也没有启用IORING_SETUP_IOPOLL特性，当然定制添加的工作量并不大。

使用如下命令可以在spdk中测试io_uring

./scripts/rpc.py -s /var/tmp/spdk.sock bdev_uring_create /dev/nvme0n1 nvme0n1 512  # 创建uring_bdev
LD_PRELOAD=/root/spdk_bdev ./fio ./example_config.fio  # 使用fio_plugin测试io_uring，需要更改对应的bdev参数配置。

参考链接

1. liburing github
2. IO_URING_SETUP
3. Faster IO through io_uring Jens讲io_uring以及liburing
4. Improved Storage Performance Using the New Linux Kernel I O Interface (SDC 2019)
5. io_uring技术的分析与思考
6. The rapid growth of io_uring
7. An Introduction to the io_uring Asynchronous I/O Framework