README
1liburing
2--------
3
4This is the io_uring library, liburing. liburing provides helpers to setup and
5teardown io_uring instances, and also a simplified interface for
6applications that don't need (or want) to deal with the full kernel
7side implementation.
8
9For more info on io_uring, please see:
10
11https://kernel.dk/io_uring.pdf
12
13Subscribe to io-uring@vger.kernel.org for io_uring related discussions
14and development for both kernel and userspace. The list is archived here:
15
16https://lore.kernel.org/io-uring/
17
18
19kernel version dependency
20--------------------------
21
22liburing itself is not tied to any specific kernel release, and hence it's
23possible to use the newest liburing release even on older kernels (and vice
24versa). Newer features may only be available on more recent kernels,
25obviously.
26
27
28ulimit settings
29---------------
30
31io_uring accounts memory it needs under the rlimit memlocked option, which
32can be quite low on some setups (64K). The default is usually enough for
33most use cases, but bigger rings or things like registered buffers deplete
34it quickly. root isn't under this restriction, but regular users are. Going
35into detail on how to bump the limit on various systems is beyond the scope
36of this little blurb, but check /etc/security/limits.conf for user specific
37settings, or /etc/systemd/user.conf and /etc/systemd/system.conf for systemd
38setups. This affects 5.11 and earlier, new kernels are less dependent
39on RLIMIT_MEMLOCK as it is only used for registering buffers.
40
41
42Regressions tests
43-----------------
44
45The bulk of liburing is actually regression/unit tests for both liburing and
46the kernel io_uring support. Please note that this suite isn't expected to
47pass on older kernels, and may even crash or hang older kernels!
48
49
50Building liburing
51-----------------
52
53 #
54 # Prepare build config (optional).
55 #
56 # --cc specifies the C compiler.
57 # --cxx specifies the C++ compiler.
58 #
59 ./configure --cc=gcc --cxx=g++;
60
61 #
62 # Build liburing.
63 #
64 make -j$(nproc);
65
66 #
67 # Install liburing (headers, shared/static libs, and manpage).
68 #
69 sudo make install;
70
71See './configure --help' for more information about build config options.
72
73
74FFI support
75-----------
76
77By default, the build results in 4 lib files:
78
79 2 shared libs:
80
81 liburing.so
82 liburing-ffi.so
83
84 2 static libs:
85
86 liburing.a
87 liburing-ffi.a
88
89Languages and applications that can't use 'static inline' functions in
90liburing.h should use the FFI variants.
91
92liburing's main public interface lives in liburing.h as 'static inline'
93functions. Users wishing to consume liburing purely as a binary dependency
94should link against liburing-ffi. It contains definitions for every 'static
95inline' function.
96
97
98License
99-------
100
101All software contained within this repo is dual licensed LGPL and MIT, see
102COPYING and LICENSE, except for a header coming from the kernel which is
103dual licensed GPL with a Linux-syscall-note exception and MIT, see
104COPYING.GPL and <https://spdx.org/licenses/Linux-syscall-note.html>.
105
106Jens Axboe 2022-05-19
107
README.OpenSource
1[
2 {
3 "Name": "liburing",
4 "License": "MIT",
5 "License File": "LICENSE",
6 "Version Number": "2.7",
7 "Owner": "mailto:maojingjing1@huawei.com",
8 "Upstream URL": "https://github.com/axboe/liburing",
9 "Description": "liburing provides helpers to setup and reardown io_uring instances, and also a simplified interface for applications that don't need (or want) to deal with the full kernel side implementation."
10 }
11]
12
README_zh.md
1# liburing
2
3由于直接使用系统调用较为复杂，Jens Axboe 还提供了封装好的用户态库liburing，简化了io_uring的使用。
4liburing提供了初始化和释放io_uring实例的帮助程序，以及为不需要（或不希望）处理完整内核端实现的应用程序提供简化的接口。
5
6## 目录结构
7
8```
9debian/
10example/ #样例代码
11man/
12src/liburing #库源代码
13test/ #测试脚本代码
14```
15
16
17## OpenHarmony如何使用liburing
18
19OpenHarmony中系统部件需要在BUILD.gn中引用liburing部件以使用liburing。
20
21```
22// BUILD.gn
23external_deps += [ "liburing:liburing" ]
24```
25
26## 使用liburing库开发步骤
27
281. 初始化
29 ```
30 extern int io_uring_queue_init_params(unsigned entries, struct io_uring ring,struct io_uring_params p);
31 extern int io_uring_queue_init(unsigned entries, struct io_uring ring, unsigned flags);
32 entries 表示队列大小
33 ring 就是需要初始化的io_uring结构指针
34 flags是标志参数，此值会改变io_uring_params p->flags
35 io_uring_params *p更多的设置
36 ```
372. 创建请求（获取一个sqe请求并初始化）
38 ```
39 extern struct io_uring_sqe io_uring_get_sqe(struct io_uring ring);
40 static inline void io_uring_prep_readv(struct io_uring_sqe sqe,int fd, const struct iovec iovecs, unsigned nr_vecs,off_t offset);
41 static inline void io_uring_prep_writev(struct io_uring_sqe sqe,int fd, const struct iovec iovecs, unsigned nr_vecs,off_t offset);
42 sqe即前面获取的sqe结构指针
43 fd为需要读写的文件描述符，可以是磁盘文件也可以是socket
44 iovecs为iovec数组，具体使用请参照readv和writev
45 nr_vecs 为iovecs数组元素个数
46 offset 为文件操作的偏移量
47 ```
483. 传入用户数据
49 ```
50 static inline void io_uring_sqe_set_data(struct io_uring_sqe *sqe, void *data);
51 ```
524. 提交请求
53 ```
54 extern int io_uring_submit(struct io_uring *ring);
55 extern int io_uring_submit_and_wait(struct io_uring *ring, unsigned wait_nr);
56 wait_nr 等待事件数量
57 ```
585. 获取结果（提取完成事件）
59 ```
60 static inline int io_uring_peek_cqe(struct io_uring *ring, struct io_uring_cqe **cqe_ptr);
61 static inline int io_uring_wait_cqe(struct io_uring *ring, struct io_uring_cqe **cqe_ptr);
62
63 cqe_ptr 输出参数，是cqe指针变量的地址
64 注意：io_uring_peek_cqe如果没有已完成的IO操作时，也会立即返回，cqe_ptr被置空；而io_uring_wait_cqe会阻塞线程，等待IO操作完成。
65 ```
666. 获取数据
67 ```
68 static inline void *io_uring_cqe_get_data(const struct io_uring_cqe *cqe);
69 ```
707. 清理处理完成的结果
71 ```
72 static inline void io_uring_cqe_seen(struct io_uring *ring, struct io_uring_cqe *cqe);
73 ```
748. 释放
75 ```
76 extern void io_uring_queue_exit(struct io_uring *ring);
77 ```
78
79## 相关仓<a name="section178mcpsimp"></a>
80
81- [**基础文件访问接口**](https://gitee.com/openharmony/filemanagement_file_api)
82