From de2c505bf29f3d7c9184208ff575cdbe83726a79 Mon Sep 17 00:00:00 2001 From: Runxi Yu Date: Mon, 29 Sep 2025 22:35:43 +0800 Subject: [PATCH] Fix documentation comments --- io_uring/cqe.ha | 2 +- io_uring/register.ha | 8 ++++---- io_uring/sqe.ha | 18 +++++++++--------- io_uring/uring.ha | 8 ++++---- diff --git a/io_uring/cqe.ha b/io_uring/cqe.ha index 57cbde9333bebdb1ebf9e4a2c832f69f629e0a13..da176d2dec373774e554f345e02ba80699393d0f 100644 --- a/io_uring/cqe.ha +++ b/io_uring/cqe.ha @@ -49,7 +49,7 @@ export fn cqe_get_data(cqe: *cqe) nullable *opaque = cqe.user_data: uintptr: nullable *opaque; // Returns the buffer ID used for this [[cqe]] in combination with -// [[set_buffer_select]]. Aborts the program if this CQE was not configured to +// [[sqe_set_buffer_select]]. Aborts the program if this CQE was not configured to // use a buffer pool. export fn cqe_get_buffer_id(cqe: *cqe) u16 = { // TODO: Handle ENOBUFS diff --git a/io_uring/register.ha b/io_uring/register.ha index 9ede690e99d9b70288091550bd154eeab8ae0942..9fa8e193e2dde3c277a5538296a92621dad6d89c 100644 --- a/io_uring/register.ha +++ b/io_uring/register.ha @@ -6,7 +6,7 @@ use rt; use types; // Registers a set of fixed buffers with an [[io_uring]]. Note that you must -// call [[unregister_buffers]] before registering a new set of buffers (even if +// call [[ring_unregister_buffers]] before registering a new set of buffers (even if // some of them have similar addresses to the old set). The buffers must be // anonymous, non-file-backed memory (e.g. the kind returned by alloc or // rt::mmap). @@ -32,7 +32,7 @@ }; // Registers a set of file descriptors with an [[io_uring]]. The set of files // may be sparse, meaning that some are set to -1, to be updated later using -// [[register_files_update]]. +// [[ring_register_files_update]]. export fn ring_register_files(ring: *io_uring, files: []int) (void | error) = { assert(len(files) <= types::UINT_MAX); match (rt::io_uring_register(ring.fd, ring_register_op::REGISTER_FILES, @@ -79,7 +79,7 @@ case int => void; }; }; -// Similar to [[register_eventfd]], but only notifies of events which complet +// Similar to [[ring_register_eventfd]], but only notifies of events which complet // asyncronously. export fn ring_register_eventfd_async(ring: *io_uring, fd: int) (void | error) = { match (rt::io_uring_register(ring.fd, @@ -125,7 +125,7 @@ }; }; // Unregisters a personality previously configured with -// [[register_personality]]. +// [[ring_register_personality]]. export fn ring_unregister_personality(ring: *io_uring, id: int) (void | error) = { match (rt::io_uring_register(ring.fd, ring_register_op::UNREGISTER_PERSONALITY, null, id: uint)) { diff --git a/io_uring/sqe.ha b/io_uring/sqe.ha index 1464db506311534fcfff85a6e3d5489de7e2a1e7..ca028d6b8879fc8e9a68172d401e2fe5010be52d 100644 --- a/io_uring/sqe.ha +++ b/io_uring/sqe.ha @@ -39,7 +39,7 @@ sqe.user_data = user_data: uintptr: u64; }; // Sets the BUFFER_SELECT flag and sets the desired buffer group. See -// [[provide_buffers]] for configuring buffer groups, and [[get_buffer_id]] to +// [[op_provide_buffers]] for configuring buffer groups, and [[cqe_get_buffer_id]] to // retrieve the buffer used from the corresponding [[cqe]]. export fn sqe_set_buffer_select(sqe: *sqe, group: u16) void = { sqe.flags |= sqe_flags::BUFFER_SELECT; @@ -102,7 +102,7 @@ preprw(sqe, sqe_op::WRITE, fd, buf, count: u32, offs, flags...); }; // Prepares a read for a fixed buffer previously registered with -// [[register_buffers]]. The buf and count parameters must refer to an address +// [[ring_register_buffers]]. The buf and count parameters must refer to an address // which falls within the buffer referenced by the index parameter. export fn op_read_fixed( sqe: *sqe, @@ -118,7 +118,7 @@ sqe.buf_index = index; }; // Prepares a write for a fixed buffer previously registered with -// [[register_buffers]]. The buf and count parameters must refer to an address +// [[ring_register_buffers]]. The buf and count parameters must refer to an address // which falls within the buffer referenced by the index parameter. export fn op_write_fixed( sqe: *sqe, @@ -136,7 +136,7 @@ // Prepares an fsync operation for an [[sqe]]. Note that operations are executed // in parallel and not are completed in submission order, so an fsync submitted // after a write may not cause the write to be accounted for by the fsync unless -// [[flags::IO_LINK]] is used. +// [[sqe_flags::IO_LINK]] is used. export fn op_fsync( sqe: *sqe, fd: int, @@ -150,7 +150,7 @@ // Adds a request to poll a file descriptor for the given set of poll events. // This will only happen once, the poll request must be submitted with a new SQE // to re-poll the file descriptor later. The caller must call [[sqe_set_data]] to -// provide a user data field in order to use [[poll_remove]] to remove this poll +// provide a user data field in order to use [[op_poll_remove]] to remove this poll // request later. export fn op_poll_add( sqe: *sqe, @@ -230,7 +230,7 @@ // Prepares a timeout operation for an [[sqe]]. "ts" should be a timespec // describing the desired timeout, and "events" may optionally be used to define // a number of completion events to wake after (or zero to wake only after the // timeout expires). The caller must call [[sqe_set_data]] to provide a user data -// field in order to use [[timeout_remove]] to cancel this timeout later. +// field in order to use [[op_timeout_remove]] to cancel this timeout later. export fn op_timeout( sqe: *sqe, ts: *rt::timespec, @@ -273,7 +273,7 @@ // Prepares a timeout operation for an [[sqe]] which is linked to the previous // SQE, effectively setting an upper limit on how long that SQE can take to // complete. "ts" should be a timespec describing the desired timeout. The // caller must call [[sqe_set_data]] to provide a user data field in order to use -// [[timeout_remove]] to cancel this timeout later. +// [[op_timeout_remove]] to cancel this timeout later. export fn op_link_timeout( sqe: *sqe, ts: *rt::timespec, @@ -318,7 +318,7 @@ preprw(sqe, sqe_op::CLOSE, fd, null, 0, 0, flags...); }; // Prepares an [[sqe]] operation which provides a buffer pool to the kernel. -// len(pool) must be equal to nbuf * bufsz. See [[set_buffer_select]] to use +// len(pool) must be equal to nbuf * bufsz. See [[sqe_set_buffer_select]] to use // the buffer pool for a subsequent request. export fn op_provide_buffers( sqe: *sqe, @@ -335,7 +335,7 @@ bufsz: uint, bufid: uint, flags...); sqe.buf_group = group; }; -// Removes buffers previously registered with [[provide_buffers]]. +// Removes buffers previously registered with [[op_provide_buffers]]. export fn op_remove_buffers( sqe: *sqe, nbuf: size, diff --git a/io_uring/uring.ha b/io_uring/uring.ha index 212e15f3148cf388dba9a948280f6140a938e90a..6e8edeb588113064560abe1fde4260b8cf06633d 100644 --- a/io_uring/uring.ha +++ b/io_uring/uring.ha @@ -21,7 +21,7 @@ return errors::strerror(err); }; }; -// The maximum value for the first parameter of [[queue_init_params]]. +// The maximum value for the first parameter of [[ring_init]]. export def MAX_ENTRIES: uint = 4096; def CQE_BUFFER_SHIFT: u32 = 16; @@ -97,7 +97,7 @@ // If set, the timeout will be "absolute", waiting until CLOCK_MONOTONIC // reaches the time defined by the timespec. If unset, it will be // interpted as a duration relative to the I/O submission. ABS = 1 << 0, - // When combined with [[op::TIMEOUT_REMOVE]], causes the submission to +// When combined with [[sqe_op::TIMEOUT_REMOVE]], causes the submission to // update the timer rather than remove it. UPDATE = 1 << 1, }; @@ -229,7 +229,7 @@ // Start with ring disabled R_DISABLED = 1 << 6, }; -// Parameters for [[setup]]. Partially completed by the kernel. +// Parameters for [[ring_init]]. Partially completed by the kernel. export type ring_params = struct { sq_entries: u32, cq_entries: u32, @@ -322,7 +322,7 @@ resv: u8, resv2: [3]u32, }; -// Opcode for a [[restriction]]. +// Opcode for a [[ring_register_restriction_details]]. export type ring_register_restriction_op = enum u16 { NONE = 0, // Allow an io_uring_register(2) opcode -- 2.48.1