pub/scm/linux/kernel/git/axboe/liburing.git  about / heads / tags
io_uring library
$ git log --pretty=format:'%h %s (%cs)%d'
e06369f Merge branch 'recvsend-bundle' (2024-05-17)
	(HEAD -> master)
184e6ec test/accept-non-empty: add accept IORING_CQE_F_SOCK_NONEMPTY test (2024-05-14)
0a0ceba io_uring.h: sync with 6.10 kernel (2024-05-14)
cc61897 Merge branch 'pu/test-clean' of https://github.com/guillemj/liburing (2024-05-05)
eaaf471 Merge branch 'pu/libffi-symbols' of https://github.com/guillemj/liburing (2024-05-05)
20e99f6 test: Remove the coredump if coredump.t managed to generate one (2024-05-05)
222b46d liburing-ffi.map: Add comments for symbols added in wrong version node (2024-05-05)
eb267a6 man: fix IORING_REGISTER_RING_FDS docs (2024-05-03)
c0b1662 test/buf-ring: skip on older kernels that don't support mmap'ed rings (2024-05-01)
149c7e1 test: skip test case if underlying filesystem doesn't support O_DIRECT (2024-05-01)
...

$ git cat-file blob HEAD:README
liburing
--------

This is the io_uring library, liburing. liburing provides helpers to setup and
teardown io_uring instances, and also a simplified interface for
applications that don't need (or want) to deal with the full kernel
side implementation.

For more info on io_uring, please see:

https://kernel.dk/io_uring.pdf

Subscribe to io-uring@vger.kernel.org for io_uring related discussions
and development for both kernel and userspace. The list is archived here:

https://lore.kernel.org/io-uring/


kernel version dependency
--------------------------

liburing itself is not tied to any specific kernel release, and hence it's
possible to use the newest liburing release even on older kernels (and vice
versa). Newer features may only be available on more recent kernels,
obviously.


ulimit settings
---------------

io_uring accounts memory it needs under the rlimit memlocked option, which
can be quite low on some setups (64K). The default is usually enough for
most use cases, but bigger rings or things like registered buffers deplete
it quickly. root isn't under this restriction, but regular users are. Going
into detail on how to bump the limit on various systems is beyond the scope
of this little blurb, but check /etc/security/limits.conf for user specific
settings, or /etc/systemd/user.conf and /etc/systemd/system.conf for systemd
setups. This affects 5.11 and earlier, new kernels are less dependent
on RLIMIT_MEMLOCK as it is only used for registering buffers.


Regressions tests
-----------------

The bulk of liburing is actually regression/unit tests for both liburing and
the kernel io_uring support. Please note that this suite isn't expected to
pass on older kernels, and may even crash or hang older kernels!


Building liburing
-----------------

    #
    # Prepare build config (optional).
    #
    #  --cc  specifies the C   compiler.
    #  --cxx specifies the C++ compiler.
    #
    ./configure --cc=gcc --cxx=g++;

    #
    # Build liburing.
    #
    make -j$(nproc);

    #
    # Install liburing (headers, shared/static libs, and manpage).
    #
    sudo make install;

See './configure --help' for more information about build config options.


FFI support
-----------

By default, the build results in 4 lib files:

    2 shared libs:

        liburing.so
        liburing-ffi.so

    2 static libs:

        liburing.a
        liburing-ffi.a

Languages and applications that can't use 'static inline' functions in
liburing.h should use the FFI variants.

liburing's main public interface lives in liburing.h as 'static inline'
functions. Users wishing to consume liburing purely as a binary dependency
should link against liburing-ffi. It contains definitions for every 'static
inline' function.


License
-------

All software contained within this repo is dual licensed LGPL and MIT, see
COPYING and LICENSE, except for a header coming from the kernel which is
dual licensed GPL with a Linux-syscall-note exception and MIT, see
COPYING.GPL and <https://spdx.org/licenses/Linux-syscall-note.html>.

Jens Axboe 2022-05-19

# heads (aka `branches'):
$ git for-each-ref --sort=-creatordate refs/heads \
	--format='%(HEAD) %(refname:short) %(subject) (%(creatordate:short))'
* master       Merge branch 'recvsend-bundle' (2024-05-17)
  recvsend-bundle test/recvsend_bundle: add UDP tests as well (2024-03-11)
  send-mshot   Add man page references to provided buffers (2024-02-26)
  proxy        Add example proxy (2024-02-16)
  min-wait     test/min-timeout-wait: 2nd min time tester (2024-02-13)
  napi         examples/napi-busy-poll-{client,server}: cleanups and doc (2024-02-02)
  pbuf-status  Add support for IORING_REGISTER_PBUF_STATUS (2023-12-21)
  next         test/socket-getsetsock-cmd: return T_EXIT_SKIP if argument passed (2023-10-20)
  futex        futex man: add note on using linked timeouts (2023-10-18)
  waitid       waitid: add io_uring flags parameter (2023-10-18)
...

# tags:
$ git for-each-ref --sort=-creatordate refs/tags \
	--format='%(refname:short) %(subject) (%(creatordate:short))'
liburing-2.3 liburing-2.3 (2022-11-01) tar.gz
liburing-2.2 liburing-2.2 (2022-06-25) tar.gz
liburing-2.1 liburing-2.1 (2021-09-09) tar.gz
liburing-2.0 liburing-2.0 (2021-03-03) tar.gz
liburing-0.7 liburing-0.7 (2020-07-10) tar.gz
liburing-0.6 liburing-0.6 (2020-04-17) tar.gz
liburing-0.5 liburing-0.5 (2020-02-25) tar.gz
liburing-0.4 liburing-0.4 (2020-02-23) tar.gz
liburing-0.3 liburing-0.3 (2019-12-21) tar.gz
liburing-0.2 liburing-0.2 (2019-10-24) tar.gz
...

# associated public inboxes:
# (number on the left is used for dev purposes)
        851 io-uring
        131 lkml
         99 linux-block
         16 netdev
         13 linux-fsdevel
         13 fio
         12 qemu-devel
         10 u-boot
          9 stable
          9 linux-arm-kernel
          7 linux-devicetree
          7 linux-arch
          6 dpdk-dev
          5 linux-mm
          5 dri-devel
          4 linux-wireless
          4 xen-devel
          4 linux-gpio
          4 linux-rdma
          4 linuxppc-dev
          4 git
          4 linux-api
          4 buildroot
          3 bpf
          3 linux-nfs
          3 netfilter-devel
          3 linux-arm-msm
          3 linux-iio
          3 linux-leds
          3 kvm
          3 intel-gfx
          3 linux-omap
          3 linux-pwm
          3 linux-can
          3 linux-rockchip
          3 dm-devel
          3 openembedded-devel
          2 linux-riscv
          2 linux-xfs
          2 linux-mediatek
          2 linux-acpi
          2 linux-amlogic
          2 linux-iommu
          2 linux-media
          2 linux-mips
          2 fstests
          2 linux-hwmon
          2 linux-rtc
          2 linux-input
          2 alsa-devel
          2 linux-btrfs
          2 linux-usb
          2 linux-next
          2 linux-parisc
          2 linux-security-module
          2 linux-bluetooth
          2 linux-ide
          2 linux-trace-devel
          2 util-linux
          2 linux-spdx
          2 linux-mmc
          2 cip-dev
          2 linux-i2c
          2 linux-tegra
          2 ceph-devel
          2 platform-driver-x86
          2 ocfs2-devel
          2 nouveau
          2 linux-s390
          2 ofono
          2 linux-patches
          2 xenomai
          2 damon
          2 batman
          2 poky
          2 cluster-devel
          2 kvm-ppc
          1 linux-samsung-soc
          1 linux-fscrypt
          1 linux-mtd
          1 cocci
          1 linux-nvme
          1 live-patching
          1 linux-crypto
          1 linux-efi
          1 linux-integrity
          1 linux-edac
          1 linux-cifs
          1 linux-erofs
          1 linux-nvdimm
          1 linux-snps-arc
          1 linux-pm
          1 linux-scsi
          1 kvmarm
          1 driverdev-devel
          1 linux-renesas-soc
          1 linux-kselftest
          1 selinux
          1 kernel-hardening
          1 linux-clk
          1 dmaengine
          1 linux-ext4
          1 linux-pci
          1 linux-f2fs-devel
          1 linux-modules
          1 kernelnewbies
          1 linux-rt-users
          1 linux-sgx
          1 linux-serial
          1 linux-watchdog
          1 linux-hyperv
          1 workflows
          1 rcu
          1 linux-m68k
          1 linux-i3c
          1 linux-wpan
          1 ksummit-discuss
          1 wireguard
          1 backports
          1 linux-kernel-mentees
          1 linux-doc
          1 linux-csky
          1 linux-man
          1 amd-gfx
          1 tpmdd-devel
          1 linux-unionfs
          1 linux-firmware
          1 linux-audit
          1 linux-spi
          1 linux-remoteproc
          1 linux-dash
          1 linux-bcache
          1 linux-sparse
          1 mm-commits
          1 lttng-dev
          1 virtualization
          1 linux-kbuild
          1 linux-fpga
          1 containers
          1 linux-raid
          1 xdp-newbies
          1 phone-devel
          1 openbmc
          1 linux-hardening
          1 dash
          1 keyrings
          1 linux-fbdev
          1 linux-sctp
          1 linux-cxl
          1 linux-perf-users
          1 target-devel
          1 lustre-devel
          1 linux-sh
          1 soc
          1 rust-for-linux
          1 ath10k
          1 ath11k
          1 linux-phy
          1 kernel-janitors
          1 sparclinux
          1 linux-staging
          1 linux-sunxi
          1 mptcp
          1 linux-coco
          1 regressions
          1 ksummit
          1 b43-dev
          1 nvdimm
          1 linux-nfc
          1 linux-bcachefs
          1 ath9k-devel
          1 ntfs3
          1 llvm
          1 iwd
          1 ell
          1 ltp
          1 yocto
          1 yocto-meta-freescale
          1 openembedded-core
          1 yocto-toaster
          1 yocto-meta-arm
          1 yocto-docs
          1 bitbake-devel
          1 yocto-meta-virtualization
          1 chrome-platform
          1 ntb
          1 yocto-meta-ti
          1 yocto-meta-arago
          1 outreachy
          1 asahi
          1 openrisc
          1 intel-wired-lan
          1 kexec
          1 loongarch
          1 imx
          1 ath12k
          1 b4-sent
          1 linux-trace-kernel
          1 oe-linux-nfc
          1 oe-kbuild-all
          1 oe-chipsec
          1 intel-xe
          1 linux-um
          1 virtio-dev
          1 virtio-comment
          1 v9fs
          1 ecryptfs
          1 qemu-riscv
          1 linux-ia64
          1 grub-devel
          1 kbd
          1 autofs
          1 cpufreq
          1 dccp
          1 cgroups
          1 devicetree-spec
          1 devicetree-compiler
          1 initramfs
          1 hail-devel
          1 kvm-ia64
          1 linux-8086
          1 kernel-testers
          1 linux-alpha
          1 linux-btrace
          1 linux-embedded
          1 linux-hams
          1 linux-hexagon
          1 linux-hotplug
          1 linux-laptop
          1 linux-sound
          1 trinity
          1 reiserfs-devel
          1 linux-metag
          1 linux-x25
          1 linux-nilfs
          1 lvs-devel
          1 netfilter
          1 linux-oxnas
          1 u-boot-amlogic
          1 lm-sensors
          1 lvm-devel
          1 acpica-devel
          1 perfbook
          1 virtio-fs
          1 smatch
          1 ../../../../../../../fuego
          1 ../../../../../../../accel-config
          1 ../../../../../../../wireless-regdb
          1 ../../../../../../../igt-dev
          1 ../../../../../../../powertop

git clone https://yhbt.net/lore/pub/scm/linux/kernel/git/axboe/liburing.git