RegisterOpCode

arg points to a struct iovec array of nr_args entries. The buffers associated with the iovecs will be locked in memory and charged against the user's RLIMIT_MEMLOCK resource limit. See getrlimit(2) for more informa‐ tion. Additionally, there is a size limit of 1GiB per buffer. Currently, the buffers must be anonymous, non-file-backed memory, such as that returned by malloc(3) or mmap(2) with the MAP_ANONYMOUS flag set. It is expected that this limitation will be lifted in the future. Huge pages are supported as well. Note that the entire huge page will be pinned in the kernel, even if only a portion of it is used.

After a successful call, the supplied buffers are mapped into the kernel and eligible for I/O. To make use of them, the application must specify the IORING_OP_READ_FIXED or IORING_OP_WRITE_FIXED opcodes in the submis‐ sion queue entry (see the struct io_uring_sqe definition in io_uring_enter(2)), and set the buf_index field to the desired buffer index. The memory range described by the submission queue entry's addr and len fields must fall within the indexed buffer.

It is perfectly valid to setup a large buffer and then only use part of it for an I/O, as long as the range is within the originally mapped region.

An application can increase or decrease the size or number of registered buffers by first unregistering the existing buffers, and then issuing a new call to io_uring_register() with the new buffers.

An application need not unregister buffers explicitly before shutting down the io_uring instance.

IORING_REGISTER_BUFFERS

This operation takes no argument, and arg must be passed as NULL. All previously registered buffers associated with the io_uring instance will be released.

IORING_UNREGISTER_BUFFERS

Register files for I/O. arg contains a pointer to an array of nr_args file descriptors (signed 32 bit integers).

To make use of the registered files, the IOSQE_FIXED_FILE flag must be set in the flags member of the struct io_uring_sqe, and the fd member is set to the index of the file in the file descriptor array.

Files are automatically unregistered when the io_uring instance is torn down. An application need only unregister if it wishes to register a new set of fds.

IORING_REGISTER_FILES

This operation requires no argument, and arg must be passed as NULL. All previously registered files associated with the io_uring instance will be unregistered.

IORING_UNREGISTER_FILES

IORING_REGISTER_EVENTFD

Registers eventfd that would be used to notify about completions on io_uring itself.

Note: available from Linux 5.2

IORING_UNREGISTER_EVENTFD

Unregisters previously registered eventfd.

Note: available from Linux 5.2

IORING_REGISTER_FILES_UPDATE (from Linux 5.5)

IORING_REGISTER_EVENTFD_ASYNC (from Linux 5.6)

If an application is using eventfd notifications with poll to know when new SQEs can be issued, it's expecting the following read/writes to complete inline. And with that, it knows that there are events available, and don't want spurious wakeups on the eventfd for those requests.

This adds IORING_REGISTER_EVENTFD_ASYNC, which works just like IORING_REGISTER_EVENTFD, except it only triggers notifications for events that happen from async completions (IRQ, or io-wq worker completions). Any completions inline from the submission itself will not trigger notifications.

IORING_REGISTER_PROBE (from Linux 5.6)

The application currently has no way of knowing if a given opcode is supported or not without having to try and issue one and see if we get -EINVAL or not. And even this approach is fraught with peril, as maybe we're getting -EINVAL due to some fields being missing, or maybe it's just not that easy to issue that particular command without doing some other leg work in terms of setup first.

This adds IORING_REGISTER_PROBE, which fills in a structure with info on what it supported or not. This will work even with sparse opcode fields, which may happen in the future or even today if someone backports specific features to older kernels.

IORING_REGISTER_PERSONALITY (from Linux 5.6)

If an application wants to use a ring with different kinds of credentials, it can register them upfront. We don't lookup credentials, the credentials of the task calling IORING_REGISTER_PERSONALITY is used.

An 'id' is returned for the application to use in subsequent personality support.

IORING_UNREGISTER_PERSONALITY (from Linux 5.6)