[GIT PULL] src/register: add query/zcrx_ctrl helpers and document them

man/io_uring_register_query.3

@@ -0,0 +1,130 @@
+.\" Copyright (C) 2026 Yitang Yang <yi1tang.yang@gmail.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_query 3 "March 26, 2026" "liburing-2.15" "liburing Manual"
+.SH NAME
+io_uring_register_query \- query io_uring capabilities and feature support
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_query(struct io_uring *" ring ","
+.BI "                            struct io_uring_query_hdr *" query ");"
+.PP
+.BI "int io_uring_register_query_task(struct io_uring_query_hdr *" query ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_query (3)
+function queries io_uring capabilities and feature support for the ring
+specified by
+.IR ring .
+It provides information about supported opcodes, flags, and subsystem-specific
+capabilities.
+
+The
+.BR io_uring_register_query_task (3)
+variant does not require an io_uring ring and can be called without one. This
+is useful for querying capabilities before creating a ring.
+
+The
+.I query
+argument must point to a
+.I struct io_uring_query_hdr
+structure that describes the query to perform:
+
+.PP
+.in +4n
+.EX
+struct io_uring_query_hdr {
+    __u64 next_entry;
+    __u64 query_data;
+    __u32 query_op;
+    __u32 size;
+    __s32 result;
+    __u32 __resv[3];
+};
+.EE
+.in
+.PP
+
+The
+.I next_entry
+field can be used to chain multiple queries together. It should point to the
+next
+.I struct io_uring_query_hdr
+structure, or be set to 0 for the last entry in the chain.
+
+The
+.I query_data
+field must point to a data structure appropriate for the query type specified in
+.IR query_op .
+
+The
+.I query_op
+field specifies the type of query to perform and can be one of:
+
+.TP
+.B IO_URING_QUERY_OPCODES
+Returns information about supported opcodes and flags. The
+.I query_data
+field must point to a
+.I struct io_uring_query_opcode
+structure, which will be filled with information about supported request
+opcodes, register opcodes, feature flags, setup flags, enter flags, and SQE
+flags.
+
+.TP
+.B IO_URING_QUERY_ZCRX
+Returns information about zero-copy receive support. The
+.I query_data
+field must point to a
+.I struct io_uring_query_zcrx
+structure, which will be filled with information about supported zero-copy
+receive flags, features, and configuration details.
+
+.TP
+.B IO_URING_QUERY_SCQ
+Returns information about the SQ/CQ ring layout. The
+.I query_data
+field must point to a
+.I struct io_uring_query_scq
+structure, which will be filled with information about ring header size and
+alignment requirements.
+
+.PP
+The
+.I size
+field should be set to the size of the data structure pointed to by
+.IR query_data .
+
+Upon return, the
+.I result
+field will contain 0 on success, or a negative error code on failure.
+
+The reserved
+.I __resv
+fields must be cleared to zero.
+
+.SH RETURN VALUE
+Returns 0 on success. On error, a negative errno value is returned.
+
+.SH NOTES
+This function is available since Linux kernel 6.15.
+
+The
+.BR io_uring_register_query_task (3)
+variant is particularly useful for capability detection before ring creation,
+allowing applications to check for feature support without the overhead of
+creating an io_uring instance.
+
+Multiple queries can be efficiently performed in a single system call by
+chaining them together using the
+.I next_entry
+field.
+
+.SH SEE ALSO
+.BR io_uring_register (2),
+.BR io_uring_setup (2)

man/io_uring_register_query_task.3

@@ -0,0 +1 @@
+io_uring_register_query.3

man/io_uring_register_zcrx_ctrl.3

@@ -0,0 +1,84 @@
+.\" Copyright (C) 2026 Yitang Yang <yi1tang.yang@gmail.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_zcrx_ctrl 3 "March 26, 2026" "liburing-2.15" "liburing Manual"
+.SH NAME
+io_uring_register_zcrx_ctrl \- perform control operations on a zero-copy receive context
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_zcrx_ctrl(struct io_uring *" ring ","
+.BI "                                struct zcrx_ctrl *" ctrl ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_zcrx_ctrl (3)
+function performs control operations on a previously registered zero-copy
+receive context. This function allows managing zero-copy receive contexts
+that were previously registered with
+.BR io_uring_register_ifq (3).
+
+The
+.I ctrl
+argument must point to a
+.I struct zcrx_ctrl
+structure that describes the control operation to perform:
+
+.PP
+.in +4n
+.EX
+struct zcrx_ctrl {
+    __u32 zcrx_id;
+    __u32 op;
+    __u64 __resv[2];
+    union {
+        struct zcrx_ctrl_export     zc_export;
+        struct zcrx_ctrl_flush_rq   zc_flush;
+    };
+};
+.EE
+.in
+.PP
+
+The
+.I zcrx_id
+field must be set to the ID of the zero-copy receive context returned from
+.BR io_uring_register_ifq (3).
+The
+.I op
+field specifies the control operation to perform and can be one of:
+
+.TP
+.B ZCRX_CTRL_FLUSH_RQ
+Flushes pending buffers from the refill queue. Uses the
+.I zc_flush
+member of the union.
+
+.TP
+.B ZCRX_CTRL_EXPORT
+Exports the zero-copy receive context for use by other rings. Uses the
+.I zc_export
+member of the union. Upon successful export, the
+.I zcrx_fd
+field in
+.I zc_export
+will contain the file descriptor that can be used to share this context
+with other io_uring instances.
+
+.PP
+The reserved
+.I __resv
+fields must be cleared to zero.
+
+.SH RETURN VALUE
+Returns 0 on success. On error, a negative errno value is returned.
+
+.SH NOTES
+This function is available since Linux kernel 6.15.
+
+.SH SEE ALSO
+.BR io_uring_register (2),
+.BR io_uring_register_ifq (3)

src/include/liburing.h

@@ -354,6 +354,8 @@ int io_uring_unregister_napi(struct io_uring *ring, struct io_uring_napi *napi)
 	LIBURING_NOEXCEPT;
 int io_uring_register_ifq(struct io_uring *ring,
 			  struct io_uring_zcrx_ifq_reg *reg) LIBURING_NOEXCEPT;
+int io_uring_register_zcrx_ctrl(struct io_uring *ring, struct zcrx_ctrl *ctrl)
+	LIBURING_NOEXCEPT;
 
 int io_uring_register_clock(struct io_uring *ring,
 			    struct io_uring_clock_register *arg)
@@ -363,6 +365,10 @@ int io_uring_register_bpf_filter(struct io_uring *ring,
 int io_uring_register_bpf_filter_task(struct io_uring_bpf *bpf)
 				 LIBURING_NOEXCEPT;
 
+int io_uring_register_query(struct io_uring *ring, struct io_uring_query_hdr *query)
+	LIBURING_NOEXCEPT;
+int io_uring_register_query_task(struct io_uring_query_hdr *query) LIBURING_NOEXCEPT;
+
 int io_uring_get_events(struct io_uring *ring) LIBURING_NOEXCEPT;
 int io_uring_submit_and_get_events(struct io_uring *ring) LIBURING_NOEXCEPT;
 

src/liburing-ffi.map

@@ -272,4 +272,7 @@ LIBURING_2.15 {
 		io_uring_cqe_iter_init;
 		io_uring_cqe_iter_next;
 		__io_uring_peek_cqe;
+		io_uring_register_zcrx_ctrl;
+		io_uring_register_query;
+		io_uring_register_query_task;
 } LIBURING_2.14;

src/liburing.map

@@ -143,4 +143,7 @@ LIBURING_2.15 {
 	global:
 		io_uring_register_bpf_filter;
 		io_uring_register_bpf_filter_task;
+		io_uring_register_zcrx_ctrl;
+		io_uring_register_query;
+		io_uring_register_query_task;
 } LIBURING_2.14;

src/register.c

@@ -449,6 +449,11 @@ int io_uring_register_ifq(struct io_uring *ring,
 	return do_register(ring, IORING_REGISTER_ZCRX_IFQ, reg, 1);
 }
 
+int io_uring_register_zcrx_ctrl(struct io_uring *ring, struct zcrx_ctrl *ctrl)
+{
+	return do_register(ring, IORING_REGISTER_ZCRX_CTRL, ctrl, 0);
+}
+
 int io_uring_resize_rings(struct io_uring *ring, struct io_uring_params *p)
 {
 	unsigned sq_head, sq_tail;
@@ -526,3 +531,13 @@ int io_uring_register_bpf_filter_task(struct io_uring_bpf *bpf)
 {
 	return __sys_io_uring_register(-1, IORING_REGISTER_BPF_FILTER, bpf, 1);
 }
+
+int io_uring_register_query(struct io_uring *ring, struct io_uring_query_hdr *query)
+{
+	return do_register(ring, IORING_REGISTER_QUERY, query, 0);
+}
+
+int io_uring_register_query_task(struct io_uring_query_hdr *query)
+{
+	return __sys_io_uring_register(-1, IORING_REGISTER_QUERY, query, 0);
+}