Skip to contentSkip to conversation

Tests for absolute timeouts and clockids

PATCH Applied Pavel Begunkov 2 participants 7 messages Aug 18, 2024 io_uring

lore
Share & tools
lore
#0 lore raw

cover Tests for absolute timeouts and clockids

Add definitions, tests and documentation for IORING_ENTER_ABS_TIMER and IORING_REGISTER_CLOCK.

It also adds helpers for registering clocks but not for absolute timeouts. Currently, liburing does't provide a way to pass custom enter flags.

Pavel Begunkov (4):
Sync kernel headers
src/register: add clock id registration helper
test: test clockids and abs timeouts
man: document clock id and IORING_ENTER_ABS_TIMER

 man/io_uring_enter.2            |  12 ++
 man/io_uring_register.2         |  20 +++
 src/include/liburing.h          |   3 +
 src/include/liburing/io_uring.h |  67 +++++---
 src/liburing-ffi.map            |   2 +
 src/liburing.map                |   2 +
 src/register.c                  |   6 +
 test/Makefile                   |   1 +
 test/wait-timeout.c             | 283 ++++++++++++++++++++++++++++++++
 9 files changed, 369 insertions(+), 27 deletions(-)
 create mode 100644 test/wait-timeout.c
Signature · 1 line
2.45.2
#1 lore raw

PATCH 1/4 Sync kernel headers

Synchronise io_uring.h with kernel, pull IORING_REGISTER_CLOCK and all other changes.

---
 src/include/liburing/io_uring.h | 67 ++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 27 deletions(-)
src/include/liburing/io_uring.h +40 -27
index 01c36a8..48c440e 100644
@@ -116,7 +116,7 @@ struct io_uring_sqe {
  */
 #define IORING_FILE_INDEX_ALLOC		(~0U)
 
-enum {
+enum io_uring_sqe_flags_bit {
 	IOSQE_FIXED_FILE_BIT,
 	IOSQE_IO_DRAIN_BIT,
 	IOSQE_IO_LINK_BIT,
@@ -184,7 +184,7 @@ enum {
 #define IORING_SETUP_DEFER_TASKRUN	(1U << 13)
 
 /*
- * Application provides ring memory
+ * Application provides the memory for the rings
  */
 #define IORING_SETUP_NO_MMAP		(1U << 14)
 
@@ -265,11 +265,12 @@ enum io_uring_op {
 };
 
 /*
- * sqe->uring_cmd_flags
+ * sqe->uring_cmd_flags		top 8bits aren't available for userspace
  * IORING_URING_CMD_FIXED	use registered buffer; pass this flag
  *				along with setting sqe->buf_index.
  */
 #define IORING_URING_CMD_FIXED	(1U << 0)
+#define IORING_URING_CMD_MASK	IORING_URING_CMD_FIXED
 
 
 /*
@@ -317,15 +318,19 @@ enum io_uring_op {
  * ASYNC_CANCEL flags.
  *
  * IORING_ASYNC_CANCEL_ALL	Cancel all requests that match the given key
- * IORING_ASYNC_CANCEL_FD	  Key off 'fd' for cancelation rather than the
+ * IORING_ASYNC_CANCEL_FD	Key off 'fd' for cancelation rather than the
  *				request 'user_data'
  * IORING_ASYNC_CANCEL_ANY	Match any request
  * IORING_ASYNC_CANCEL_FD_FIXED	'fd' passed in is a fixed descriptor
+ * IORING_ASYNC_CANCEL_USERDATA	Match on user_data, default for no other key
+ * IORING_ASYNC_CANCEL_OP	Match request based on opcode
  */
 #define IORING_ASYNC_CANCEL_ALL	(1U << 0)
 #define IORING_ASYNC_CANCEL_FD	(1U << 1)
 #define IORING_ASYNC_CANCEL_ANY	(1U << 2)
 #define IORING_ASYNC_CANCEL_FD_FIXED	(1U << 3)
+#define IORING_ASYNC_CANCEL_USERDATA	(1U << 4)
+#define IORING_ASYNC_CANCEL_OP	(1U << 5)
 
 /*
  * send/sendmsg and recv/recvmsg flags (sqe->ioprio)
@@ -350,13 +355,13 @@ enum io_uring_op {
  *				IORING_NOTIF_USAGE_ZC_COPIED if data was copied
  *				(at least partially).
  *
- * IORING_RECVSEND_BUNDLE	Used with IOSQE_BUFFER_SELECT. If set, send wil
- *				grab as many buffers from the buffer group ID
- *				given and send them all. The completion result
- *				will be the number of buffers send, with the
- *				starting buffer ID in cqe->flags as per usual
- *				for provided buffer usage. The buffers will be
- *				contigious from the starting buffer ID.
+ * IORING_RECVSEND_BUNDLE	Used with IOSQE_BUFFER_SELECT. If set, send or
+ *				recv will grab as many buffers from the buffer
+ *				group ID given and send them all. The completion
+ *				result 	will be the number of buffers send, with
+ *				the starting buffer ID in cqe->flags as per
+ *				usual for provided buffer usage. The buffers
+ *				will be	contigious from the starting buffer ID.
  */
 #define IORING_RECVSEND_POLL_FIRST	(1U << 0)
 #define IORING_RECV_MULTISHOT		(1U << 1)
@@ -383,7 +388,7 @@ enum io_uring_op {
 /*
  * IORING_OP_MSG_RING command types, stored in sqe->addr
  */
-enum {
+enum io_uring_msg_ring_flags {
 	IORING_MSG_DATA,	/* pass sqe->len as 'res' and off as user_data */
 	IORING_MSG_SEND_FD,	/* send a registered fd to another ring */
 };
@@ -416,7 +421,7 @@ enum {
  * IO completion data structure (Completion Queue Entry)
  */
 struct io_uring_cqe {
-	__u64	user_data;	/* sqe->user_data value passed back */
+	__u64	user_data;	/* sqe->data submission passed back */
 	__s32	res;		/* result code for this event */
 	__u32	flags;
 
@@ -441,9 +446,7 @@ struct io_uring_cqe {
 #define IORING_CQE_F_SOCK_NONEMPTY	(1U << 2)
 #define IORING_CQE_F_NOTIF		(1U << 3)
 
-enum {
-	IORING_CQE_BUFFER_SHIFT		= 16,
-};
+#define IORING_CQE_BUFFER_SHIFT		16
 
 /*
  * Magic offsets for the application to mmap the data it needs
@@ -504,6 +507,7 @@ struct io_cqring_offsets {
 #define IORING_ENTER_SQ_WAIT		(1U << 2)
 #define IORING_ENTER_EXT_ARG		(1U << 3)
 #define IORING_ENTER_REGISTERED_RING	(1U << 4)
+#define IORING_ENTER_ABS_TIMER		(1U << 5)
 
 /*
  * Passed in for io_uring_setup(2). Copied back with updated info on success
@@ -543,7 +547,7 @@ struct io_uring_params {
 /*
  * io_uring_register(2) opcodes and arguments
  */
-enum {
+enum io_uring_register_op {
 	IORING_REGISTER_BUFFERS			= 0,
 	IORING_UNREGISTER_BUFFERS		= 1,
 	IORING_REGISTER_FILES			= 2,
@@ -592,6 +596,8 @@ enum {
 	IORING_REGISTER_NAPI			= 27,
 	IORING_UNREGISTER_NAPI			= 28,
 
+	IORING_REGISTER_CLOCK			= 29,
+
 	/* this goes last */
 	IORING_REGISTER_LAST,
 
@@ -600,7 +606,7 @@ enum {
 };
 
 /* io-wq worker categories */
-enum {
+enum io_wq_type {
 	IO_WQ_BOUND,
 	IO_WQ_UNBOUND,
 };
@@ -672,6 +678,11 @@ struct io_uring_restriction {
 	__u32 resv2[3];
 };
 
+struct io_uring_clock_register {
+	__u32	clockid;
+	__u32	__resv[3];
+};
+
 struct io_uring_buf {
 	__u64	addr;
 	__u32	len;
@@ -691,7 +702,7 @@ struct io_uring_buf_ring {
 			__u16	resv3;
 			__u16	tail;
 		};
-		struct io_uring_buf	bufs[0];
+		__DECLARE_FLEX_ARRAY(struct io_uring_buf, bufs);
 	};
 };
 
@@ -705,7 +716,7 @@ struct io_uring_buf_ring {
  *			IORING_OFF_PBUF_RING | (bgid << IORING_OFF_PBUF_SHIFT)
  *			to get a virtual mapping for the ring.
  */
-enum {
+enum io_uring_register_pbuf_ring_flags {
 	IOU_PBUF_RING_MMAP	= 1,
 };
 
@@ -727,16 +738,16 @@ struct io_uring_buf_status {
 
 /* argument for IORING_(UN)REGISTER_NAPI */
 struct io_uring_napi {
-	__u32   busy_poll_to;
-	__u8    prefer_busy_poll;
-	__u8    pad[3];
-	__u64   resv;
+	__u32	busy_poll_to;
+	__u8	prefer_busy_poll;
+	__u8	pad[3];
+	__u64	resv;
 };
 
 /*
  * io_uring_restriction->opcode values
  */
-enum {
+enum io_uring_register_restriction_op {
 	/* Allow an io_uring_register(2) opcode */
 	IORING_RESTRICTION_REGISTER_OP		= 0,
 
@@ -767,7 +778,9 @@ struct io_uring_sync_cancel_reg {
 	__s32				fd;
 	__u32				flags;
 	struct __kernel_timespec	timeout;
-	__u64				pad[4];
+	__u8				opcode;
+	__u8				pad[7];
+	__u64				pad2[3];
 };
 
 /*
@@ -790,7 +803,7 @@ struct io_uring_recvmsg_out {
 /*
  * Argument for IORING_OP_URING_CMD when file is a socket
  */
-enum {
+enum io_uring_socket_op {
 	SOCKET_URING_OP_SIOCINQ		= 0,
 	SOCKET_URING_OP_SIOCOUTQ,
 	SOCKET_URING_OP_GETSOCKOPT,
Signature · 1 line
2.45.2
#2 lore raw

PATCH 2/4 src/register: add clock id registration helper

In reply to Pavel Begunkov
---
 src/include/liburing.h | 3 +++
 src/liburing-ffi.map   | 2 ++
 src/liburing.map       | 2 ++
 src/register.c         | 6 ++++++
 4 files changed, 13 insertions(+)
src/include/liburing.h +3 -0
index 1092f3b..53c94c4 100644
@@ -241,6 +241,9 @@ int io_uring_register_file_alloc_range(struct io_uring *ring,
 int io_uring_register_napi(struct io_uring *ring, struct io_uring_napi *napi);
 int io_uring_unregister_napi(struct io_uring *ring, struct io_uring_napi *napi);
 
+int io_uring_register_clock(struct io_uring *ring,
+			    struct io_uring_clock_register *arg);
+
 int io_uring_get_events(struct io_uring *ring);
 int io_uring_submit_and_get_events(struct io_uring *ring);
 
src/liburing-ffi.map +2 -0
index 476d7fd..a0bea31 100644
@@ -206,4 +206,6 @@ LIBURING_2.7 {
 } LIBURING_2.6;
 
 LIBURING_2.8 {
+	global:
+		io_uring_register_clock;
 } LIBURING_2.7;
src/liburing.map +2 -0
index fa096bb..79f6068 100644
@@ -97,4 +97,6 @@ LIBURING_2.7 {
 } LIBURING_2.6;
 
 LIBURING_2.8 {
+	global:
+		io_uring_register_clock;
 } LIBURING_2.7;
src/register.c +6 -0
index 9acc36f..c0690a8 100644
@@ -366,3 +366,9 @@ int io_uring_unregister_napi(struct io_uring *ring, struct io_uring_napi *napi)
 {
 	return do_register(ring, IORING_UNREGISTER_NAPI, napi, 1);
 }
+
+int io_uring_register_clock(struct io_uring *ring,
+			    struct io_uring_clock_register *arg)
+{
+	return do_register(ring, IORING_REGISTER_CLOCK, arg, 0);
+}
Signature · 1 line
2.45.2
#3 lore raw

PATCH 3/4 test: test clockids and abs timeouts

In reply to Pavel Begunkov
---
 test/Makefile       |   1 +
 test/wait-timeout.c | 283 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 284 insertions(+)
 create mode 100644 test/wait-timeout.c
test/Makefile +1 -0
index 0538a75..f4fccd7 100644
@@ -213,6 +213,7 @@ test_srcs := \
 	unlink.c \
 	version.c \
 	waitid.c \
+	wait-timeout.c \
 	wakeup-hang.c \
 	wq-aff.c \
 	xattr.c \
test/wait-timeout.c new file +283 -0

283 lines not on this page · raw message

Signature · 1 line
2.45.2
#4 lore raw

PATCH 4/4 man: document clock id and IORING_ENTER_ABS_TIMER

In reply to Pavel Begunkov
---
 man/io_uring_enter.2    | 12 ++++++++++++
 man/io_uring_register.2 | 20 ++++++++++++++++++++
 2 files changed, 32 insertions(+)
man/io_uring_enter.2 +12 -0
index 5e4121b..8c79771 100644
@@ -105,6 +105,18 @@ then setting this flag will tell the kernel that the
 .I ring_fd
 passed in is the registered ring offset rather than a normal file descriptor.
 
+.TP
+.B IORING_ENTER_ABS_TIMER
+
+When this flag is set, the timeout argument passed in
+.I struct io_uring_getevents_arg
+will be interpreted as an absolute
+time of the registered clock (see
+.B IORING_REGISTER_CLOCK
+) until which the waiting should end.
+
+Available since 6.12
+
 .PP
 .PP
 If the io_uring instance was configured for polling, by specifying
man/io_uring_register.2 +20 -0
index 4590588..c8521b7 100644
@@ -720,6 +720,26 @@ The application must have registered a file table first.
 
 Available since 6.0.
 
+.TP
+.B IORING_REGISTER_CLOCK
+Specifies which clock id io_uring will use for timers while waiting for
+completion events with
+.B IORING_ENTER_GETEVENTS.
+It's only effective if the timeout argument in
+.I struct io_uring_getevents_arg
+is passed, ignored otherwise.
+When used in conjunction with
+.B IORING_ENTER_ABS_TIMER,
+interprets the timeout argument as absolute time of the specified clock.
+
+The default clock is
+.B CLOCK_MONOTONIC.
+
+Available since 6.12 and supports
+.B CLOCK_MONOTONIC
+and
+.B CLOCK_BOOTTIME.
+
 .SH RETURN VALUE
 
 On success,
Signature · 1 line
2.45.2
maintainer Applied
#5 lore raw
In reply to Pavel Begunkov
Quoted 8 lines · Pavel Begunkov

Add definitions, tests and documentation for IORING_ENTER_ABS_TIMER and IORING_REGISTER_CLOCK.

It also adds helpers for registering clocks but not for absolute timeouts. Currently, liburing does't provide a way to pass custom enter flags.

[...]

Applied, thanks!

[1/4] Sync kernel headers

      commit: 2fce7b7067a2443dcba8c94254efc3b1c6f84235
[2/4] src/register: add clock id registration helper
      commit: eed5cab0138531ff308c975825d01654644f0b42
[3/4] test: test clockids and abs timeouts
      commit: 050dd942acd02362299bde09ba794681052e1ebe
[4/4] man: document clock id and IORING_ENTER_ABS_TIMER
      commit: fa347092fac1b28bd9100e617974708af379ac44

Best regards,

Signature · 1 line
Jens Axboe
maintainer Applied
#6 lore raw
In reply to Pavel Begunkov
Quoted 6 lines · Pavel Begunkov

Add definitions, tests and documentation for IORING_ENTER_ABS_TIMER and IORING_REGISTER_CLOCK.

It also adds helpers for registering clocks but not for absolute timeouts. Currently, liburing does't provide a way to pass custom enter flags.

Applied, and then I wrote a quick io_uring_register_clock.3 man page for it as well. Please double check it...

Signature · 1 line
Jens Axboe