diff options
author | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | 2023-07-07 04:52:30 +0000 |
---|---|---|
committer | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | 2023-07-07 04:52:30 +0000 |
commit | 11c8c4dfa4d268bef66f636e126725e46624b7a7 (patch) | |
tree | ebe9c872e416346e4b333e5062da32401c8e0a73 /man/io_uring_queue_init.3 | |
parent | d53db6851ea17b2d219d084e1afc683b8b62b105 (diff) | |
parent | 1d27ff1934c5c4292dc00fba7f7f8ae411ed42f5 (diff) | |
download | liburing-android14-mainline-media-swcodec-release.tar.gz |
Snap for 10453563 from 1d27ff1934c5c4292dc00fba7f7f8ae411ed42f5 to mainline-media-swcodec-releaseaml_swc_341711000aml_swc_341619000aml_swc_341513600aml_swc_341312300aml_swc_341312020aml_swc_341111000aml_swc_341011020aml_swc_340922010android14-mainline-media-swcodec-release
Change-Id: I7cca6554b0f16e2b5808963242c9da276f36c14d
Diffstat (limited to 'man/io_uring_queue_init.3')
-rw-r--r-- | man/io_uring_queue_init.3 | 71 |
1 files changed, 58 insertions, 13 deletions
diff --git a/man/io_uring_queue_init.3 b/man/io_uring_queue_init.3 index 1980fa4..086b70f 100644 --- a/man/io_uring_queue_init.3 +++ b/man/io_uring_queue_init.3 @@ -5,40 +5,85 @@ .\" .TH io_uring_queue_init 3 "July 10, 2020" "liburing-0.7" "liburing Manual" .SH NAME -io_uring_queue_init - setup io_uring submission and completion queues +io_uring_queue_init \- setup io_uring submission and completion queues .SH SYNOPSIS .nf -.BR "#include <liburing.h>" +.B #include <liburing.h> .PP -.BI "int io_uring_queue_init(unsigned " entries ", struct io_uring *" ring , -.BI " unsigned " flags ); -.fi +.BI "int io_uring_queue_init(unsigned " entries "," +.BI " struct io_uring *" ring "," +.BI " unsigned " flags ");" .PP +.BI "int io_uring_queue_init_params(unsigned " entries "," +.BI " struct io_uring *" ring "," +.BI " struct io_uring_params *" params ");" +.fi .SH DESCRIPTION .PP -The io_uring_queue_init() function executes the io_uring_setup syscall to -initialize the submission and completion queues in the kernel with at least +The +.BR io_uring_queue_init (3) +function executes the +.BR io_uring_setup (2) +system call to initialize the submission and completion queues in the kernel +with at least .I entries -entries and then maps the resulting file descriptor to memory shared between the -application and the kernel. +entries in the submission queue and then maps the resulting file descriptor to +memory shared between the application and the kernel. -On success io_uring_queue_init() returns 0 and +By default, the CQ ring will have twice the number of entries as specified by +.I entries +for the SQ ring. This is adequate for regular file or storage workloads, but +may be too small networked workloads. The SQ ring entries do not impose a limit +on the number of in-flight requests that the ring can support, it merely limits +the number that can be submitted to the kernel in one go (batch). if the CQ +ring overflows, e.g. more entries are generated than fits in the ring before the +application can reap them, then the ring enters a CQ ring overflow state. This +is indicated by +.B IORING_SQ_CQ_OVERFLOW +being set in the SQ ring flags. Unless the kernel runs out of available memory, +entries are not dropped, but it is a much slower completion path and will slow +down request processing. For that reason it should be avoided and the CQ +ring sized appropriately for the workload. Setting +.I cq_entries +in +.I struct io_uring_params +will tell the kernel to allocate this many entries for the CQ ring, independent +of the SQ ring size in given in +.IR entries . +If the value isn't a power of 2, it will be rounded up to the nearest power of +2. + +On success, +.BR io_uring_queue_init (3) +returns 0 and .I ring will point to the shared memory containing the io_uring queues. On failure --errno is returned. +.BR -errno +is returned. .I flags -will be passed through to the io_uring_setup syscall (see +will be passed through to the io_uring_setup syscall (see .BR io_uring_setup (2)). +If the +.BR io_uring_queue_init_params (3) +variant is used, then the parameters indicated by +.I params +will be passed straight through to the +.BR io_uring_setup (2) +system call. + On success, the resources held by .I ring should be released via a corresponding call to .BR io_uring_queue_exit (3). .SH RETURN VALUE .BR io_uring_queue_init (3) -returns 0 on success and -errno on failure. +returns 0 on success and +.BR -errno +on failure. .SH SEE ALSO .BR io_uring_setup (2), +.BR io_uring_register_ring_fd (3), .BR mmap (2), .BR io_uring_queue_exit (3) |