io_uring: add some more source code comments/docs

Change-Id: I8ba77a18b51f67a9edbd1fa488b9791f8bf6e40a

3 files changed, 21 insertions, 1 deletions

diff --git a/src/core/osmo_io.c b/src/core/osmo_io.c
index f23986fb..649bf736 100644
--- a/src/core/osmo_io.c
+++ b/src/core/osmo_io.c
@@ -323,6 +323,10 @@ void iofd_handle_segmented_read(struct osmo_io_fd *iofd, struct msgb *msg, int r
 	iofd->pending = pending;
 }
 
+/*! completion handler: Called by osmo_io backend after a given I/O operation has completed
+ *  \param[in] iofd I/O file-descriptor on which I/O has completed
+ *  \param[in] msg message buffer containing data related to completed I/O
+ *  \param[in] hdr serialized msghdr containing state of completed I/O */
 void iofd_handle_recv(struct osmo_io_fd *iofd, struct msgb *msg, int rc, struct iofd_msghdr *hdr)
 {
 	talloc_steal(iofd->msgb_alloc.ctx, msg);
diff --git a/src/core/osmo_io_internal.h b/src/core/osmo_io_internal.h
index 5b7ab908..73a81e1f 100644
--- a/src/core/osmo_io_internal.h
+++ b/src/core/osmo_io_internal.h
@@ -111,16 +111,24 @@ enum iofd_msg_action {
 };
 
 
-/* serialized version of 'struct msghdr' employed by sendmsg/recvmsg */
+/*! serialized version of 'struct msghdr' employed by sendmsg/recvmsg */
 struct iofd_msghdr {
+	/*! entry into osmo_io_fd.tx_queue.msg_queue */
 	struct llist_head list;
 	enum iofd_msg_action action;
+	/*! the 'struct msghdr' we are wrapping/ecapsulating here */
 	struct msghdr hdr;
+	/*! socket address of the remote peer */
 	struct osmo_sockaddr osa;
+	/*! io-vector we need to pass as argument to sendmsg/recvmsg; is set up
+	 * to point into msg below */
 	struct iovec iov[1];
+	/*! flags we pass as argument to sendmsg / recvmsg */
 	int flags;
 
+	/*! message-buffer containing data for this I/O operation */
 	struct msgb *msg;
+	/*! I/O file descriptor on which we perform this I/O operation */
 	struct osmo_io_fd *iofd;
 };
 
diff --git a/src/core/osmo_io_uring.c b/src/core/osmo_io_uring.c
index a6395fea..abeea798 100644
--- a/src/core/osmo_io_uring.c
+++ b/src/core/osmo_io_uring.c
@@ -59,6 +59,8 @@ struct osmo_io_uring {
 static __thread struct osmo_io_uring g_ring;
 
 static void iofd_uring_cqe(struct io_uring *ring);
+
+/*! read call-back for eventfd notifying us if entries are in the completion queue */
 static int iofd_uring_poll_cb(struct osmo_fd *ofd, unsigned int what)
 {
 	struct io_uring *ring = ofd->data;
@@ -157,6 +159,7 @@ static void iofd_uring_submit_recv(struct osmo_io_fd *iofd, enum iofd_msg_action
 	iofd->u.uring.read_msghdr = msghdr;
 }
 
+/*! completion call-back for READ/RECVFROM */
 static void iofd_uring_handle_recv(struct iofd_msghdr *msghdr, int rc)
 {
 	struct osmo_io_fd *iofd = msghdr->iofd;
@@ -179,6 +182,7 @@ static void iofd_uring_handle_recv(struct iofd_msghdr *msghdr, int rc)
 
 static int iofd_uring_submit_tx(struct osmo_io_fd *iofd);
 
+/*! completion call-back for WRITE/SENDTO */
 static void iofd_uring_handle_tx(struct iofd_msghdr *msghdr, int rc)
 {
 	struct osmo_io_fd *iofd = msghdr->iofd;
@@ -220,10 +224,12 @@ out_free:
 
 out:
 	iofd->u.uring.write_msghdr = NULL;
+	/* submit the next to-be-transmitted message for this file descriptor */
 	if (iofd->u.uring.write_enabled && !IOFD_FLAG_ISSET(iofd, IOFD_FLAG_CLOSED))
 		iofd_uring_submit_tx(iofd);
 }
 
+/*! handle completion of a single I/O message */
 static void iofd_uring_handle_completion(struct iofd_msghdr *msghdr, int res)
 {
 	struct osmo_io_fd *iofd = msghdr->iofd;
@@ -250,6 +256,7 @@ static void iofd_uring_handle_completion(struct iofd_msghdr *msghdr, int res)
 		talloc_free(iofd);
 }
 
+/*! process all pending completion queue entries in given io_uring */
 static void iofd_uring_cqe(struct io_uring *ring)
 {
 	int rc;
@@ -274,6 +281,7 @@ static void iofd_uring_cqe(struct io_uring *ring)
 	}
 }
 
+/*! will submit the next to-be-transmitted message for given iofd */
 static int iofd_uring_submit_tx(struct osmo_io_fd *iofd)
 {
 	struct io_uring_sqe *sqe;