Fix documentation errors detected by kernel-doc

homa_api.c

@@ -21,13 +21,13 @@
 /**
  * homa_reply() - Send a response message for an RPC previously received
  * with a call to recvmsg.
- * @sockfd:     File descriptor for the socket on which to send the message.
- * @response:   First byte of buffer containing the response message.
- * @resplen:    Number of bytes at @response.
- * @dest_addr:  Address of the RPC's client (returned by recvmsg when
- *              the message was received).
- * @id:         Unique identifier for the request, as returned by recvmsg
- *              when the request was received.
+ * @sockfd:       File descriptor for the socket on which to send the message.
+ * @message_buf:  First byte of buffer containing the response message.
+ * @length:       Number of bytes in the message at @message_buf.
+ * @dest_addr:    Address of the RPC's client (returned by recvmsg when
+ *                the message was received).
+ * @id:           Unique identifier for the request, as returned by recvmsg
+ *                when the request was received.
  *
  * @dest_addr and @id must correspond to a previously-received request
  * for which no reply has yet been sent; if there is no such active request,

homa_grant.c

@@ -12,8 +12,8 @@
  * homa_grant_outranks() - Returns nonzero if rpc1 should be considered
  * higher priority for grants than rpc2, and zero if the two RPCS are
  * equivalent or rpc2 is higher priority.
- * @rpc1     First RPC to consider.
- * @rpc2     Second RPC to consider.
+ * @rpc1:     First RPC to consider.
+ * @rpc2:     Second RPC to consider.
  */
 int inline homa_grant_outranks(struct homa_rpc *rpc1, struct homa_rpc *rpc2)
 {
@@ -143,8 +143,8 @@ void homa_grant_add_rpc(struct homa_rpc *rpc)
 }
 
 /**
- * homa_remove_rpc() - Unlink an RPC from the grantable lists, so it will no
- * longer be considered for grants. The caller must hold the grantable lock.
+ * homa_grant_remove_rpc() - Unlink an RPC from the grantable lists, so it will
+ * no longer be considered for grants. The caller must hold the grantable lock.
  * @rpc:     RPC to remove from grantable lists.  Must currently be in
  *           a grantable list.
  */
@@ -205,6 +205,7 @@ void homa_grant_remove_rpc(struct homa_rpc *rpc)
  * homa_grant_send() - See if it is appropriate to send a grant to an RPC;
  * if so, create the grant and send it.
  * @rpc:   The RPC to check for possible grant. Must be locked by the caller.
+ * @homa:  Overall information about the Homa transport.
  * Return: Nonzero if a grant was sent, 0 if not.
  */
 int homa_grant_send(struct homa_rpc *rpc, struct homa *homa)
@@ -665,6 +666,7 @@ int homa_grantable_lock_slow(struct homa *homa, int recalc)
 /**
  * homa_grant_log_tt() - Generate timetrace records describing all of
  * the active RPCs (those we are currently granting to).
+ * @homa:  Overall information about the Homa transport.
  */
 void homa_grant_log_tt(struct homa *homa)
 {

homa_incoming.c

@@ -52,7 +52,7 @@ int homa_message_in_init(struct homa_rpc *rpc, int length, int unsched)
 }
 
 /**
- * homa_new_gap() - Create a new gap and add it to a list.
+ * homa_gap_new() - Create a new gap and add it to a list.
  * @next:   Add the new gap just before this list element.
  * @start:  Offset of first byte covered by the gap.
  * @end:    Offset of byte just after the last one covered by the gap.
@@ -1180,7 +1180,7 @@ int homa_register_interests(struct homa_interest *interest,
 }
 
 /**
- * @homa_wait_for_message() - Wait for receipt of an incoming message
+ * homa_wait_for_message() - Wait for receipt of an incoming message
  * that matches the parameters. Various other activities can occur while
  * waiting, such as reaping dead RPCs and copying data to user space.
  * @hsk:          Socket where messages will arrive.
@@ -1372,7 +1372,7 @@ struct homa_rpc *homa_wait_for_message(struct homa_sock *hsk, int flags,
 }
 
 /**
- * @homa_choose_interest() - Given a list of interests for an incoming
+ * homa_choose_interest() - Given a list of interests for an incoming
  * message, choose the best one to handle it (if any).
  * @homa:        Overall information about the Homa transport.
  * @head:        Head pointers for the list of interest: either
@@ -1408,7 +1408,7 @@ struct homa_interest *homa_choose_interest(struct homa *homa,
 }
 
 /**
- * @homa_rpc_handoff() - This function is called when the input message for
+ * homa_rpc_handoff() - This function is called when the input message for
  * an RPC is ready for attention from a user thread. It either notifies
  * a waiting reader or queues the RPC.
  * @rpc:                RPC to handoff; must be locked. The caller must

homa_offload.c

@@ -98,6 +98,9 @@ void homa_gro_unhook_tcp(void)
  * homa_tcp_gro_receive() - Invoked instead of TCP's normal gro_receive function
  * when hooking is enabled. Identifies Homa-over-TCP packets and passes them
  * to Homa; sends real TCP packets to TCP's gro_receive function.
+ * @held_list:  Pointer to header for list of packets that are being
+ *              held for possible GRO merging.
+ * @skb:        The newly arrived packet.
  */
 struct sk_buff *homa_tcp_gro_receive(struct list_head *held_list,
 		struct sk_buff *skb)

homa_peertab.c

@@ -254,7 +254,7 @@ void homa_dst_refresh(struct homa_peertab *peertab, struct homa_peer *peer,
 }
 
 /**
- * homa_peer_unsched_priority() - Returns the priority level to use for
+ * homa_unsched_priority() - Returns the priority level to use for
  * unscheduled packets of a message.
  * @homa:     Overall data about the Homa protocol implementation.
  * @peer:     The destination of the message.

homa_plumbing.c

@@ -714,7 +714,7 @@ void homa_close(struct sock *sk, long timeout) {
 
 /**
  * homa_shutdown() - Implements the shutdown system call for Homa sockets.
- * @sk:      Socket to shut down.
+ * @sock:    Socket to shut down.
  * @how:     Ignored: for other sockets, can independently shut down
  *           sending and receiving, but for Homa any shutdown will
  *           shut down everything.
@@ -883,10 +883,10 @@ int homa_getsockopt(struct sock *sk, int level, int optname,
 
 /**
  * homa_sendmsg() - Send a request or response message on a Homa socket.
- * @sk:    Socket on which the system call was invoked.
- * @msg:   Structure describing the message to send; the msg_control
- *         field points to additional information.
- * @len:   Number of bytes of the message.
+ * @sk:     Socket on which the system call was invoked.
+ * @msg:    Structure describing the message to send; the msg_control
+ *          field points to additional information.
+ * @length: Number of bytes of the message.
  * Return: 0 on success, otherwise a negative errno.
  */
 int homa_sendmsg(struct sock *sk, struct msghdr *msg, size_t length) {
@@ -1478,8 +1478,12 @@ int homa_err_handler_v4(struct sk_buff *skb, u32 info)
 /**
  * homa_err_handler_v6() - Invoked by IP to handle an incoming error
  * packet, such as ICMP UNREACHABLE.
- * @skb:   The incoming packet.
- * @info:  Information about the error that occurred?
+ * @skb:    The incoming packet.
+ * @opt:    Not used.
+ * @type:   Type of ICMP packet.
+ * @code:   Additional information about the error.
+ * @offset: Not used.
+ * @info:   Information about the error that occurred?
  *
  * Return: zero, or a negative errno if the error couldn't be handled here.
  */

homa_pool.c

@@ -27,6 +27,7 @@
  * set_bpages_needed() - Set the bpages_needed field of @pool based
  * on the length of the first RPC that's waiting for buffer space.
  * The caller must own the lock for @pool->hsk.
+ * @pool: Pool to update.
  */
 static void inline set_bpages_needed(struct homa_pool *pool) {
 	struct homa_rpc *rpc = list_first_entry(&pool->hsk->waiting_for_bufs,
@@ -41,7 +42,7 @@ static void inline set_bpages_needed(struct homa_pool *pool) {
  * @hsk:          Socket containing the pool to initialize.
  * @region:       First byte of the memory region for the pool, allocated
  *                by the application; must be page-aligned.
- * @region_size   Total number of bytes available at @buf_region.
+ * @region_size:  Total number of bytes available at @buf_region.
  * Return: Either zero (for success) or a negative errno for failure.
  */
 int homa_pool_init(struct homa_sock *hsk, void *region, __u64 region_size)

homa_skb.c

@@ -16,7 +16,7 @@ extern int mock_max_skb_frags;
 /**
  * homa_skb_page_pool_init() - Invoked when a struct homa is created to
  * initialize a page pool.
- * @homa:         Overall data about the Homa protocol implementation.
+ * @pool:         Pool to initialize.
  */
 void homa_skb_page_pool_init(struct homa_page_pool *pool)
 {
@@ -28,6 +28,7 @@ void homa_skb_page_pool_init(struct homa_page_pool *pool)
 /**
  * homa_skb_cleanup() - Invoked when a struct homa is deleted; cleans
  * up information related to skb allocation.
+ * @homa:  Overall inforamtion about the Homa transport.
  */
 void homa_skb_cleanup(struct homa *homa)
 {
@@ -183,7 +184,7 @@ void *homa_skb_extend_frags(struct homa *homa, struct sk_buff *skb, int *length)
  * given core. Any existing page is released.
  * @homa:         Overall data about the Homa protocol implementation.
  * @core:         Allocate page in this core.
- * @Return:       True if successful, false if memory not available.
+ * Return:       True if successful, false if memory not available.
  */
 bool homa_skb_page_alloc(struct homa *homa, struct homa_core * core)
 {
@@ -516,6 +517,7 @@ void homa_skb_get(struct sk_buff *skb, void *dest, int offset, int length)
  * homa_skb_release_pages() - This function is invoked occasionally; it's
  * job is to gradually release pages from the sk_buff page pools back to
  * Linux, based on sysctl parameters such as skb_page_frees_per_sec.
+ * @homa:  Overall information about the Homa transport.
  */
 void homa_skb_release_pages(struct homa *homa)
 {

homa_socktab.c

@@ -66,7 +66,7 @@ struct homa_sock *homa_socktab_start_scan(struct homa_socktab *socktab,
 }
 
 /**
- * homa_starttab_next() - Return the next socket in an iteration over a socktab.
+ * homa_socktab_next() - Return the next socket in an iteration over a socktab.
  * @scan:      State of the scan.
  *
  * Return:     The next socket in the table, or NULL if the iteration has

timetrace.c

@@ -9,7 +9,7 @@
  * timetrace stubs; we will then connect the timetrace mechanism here with
  * those stubs to allow the rest of the kernel to log in our buffers.
  */
-//#define TT_KERNEL 1
+#define TT_KERNEL 1
 #endif
 #ifdef TT_KERNEL
 extern int        tt_linux_buffer_mask;
@@ -158,7 +158,7 @@ int tt_init(char *proc_file, int *temp)
 }
 
 /**
- * @tt_destroy(): Disable time tracing and disable the /proc file for
+ * tt_destroy(): Disable time tracing and disable the /proc file for
  * reading traces.
  */
 void tt_destroy(void)
@@ -198,8 +198,8 @@ void tt_destroy(void)
 }
 
 /**
- * Stop recording timetrace events until the trace has been read
- * using the /proc file. When recording resumes after reading the
+ * tt_freeze() - Stop recording timetrace events until the trace has been
+ * read using the /proc file. When recording resumes after reading the
  * file, the buffers will be cleared.
  */
 void tt_freeze(void)
@@ -230,10 +230,10 @@ void tt_freeze(void)
  *             to this method. This pointer is stored in the buffer, so
  *             the caller must ensure that its contents will not change
  *             over its lifetime in the trace.
- * @arg0       Argument to use when printing a message about this event.
- * @arg1       Argument to use when printing a message about this event.
- * @arg2       Argument to use when printing a message about this event.
- * @arg3       Argument to use when printing a message about this event.
+ * @arg0:      Argument to use when printing a message about this event.
+ * @arg1:      Argument to use when printing a message about this event.
+ * @arg2:      Argument to use when printing a message about this event.
+ * @arg3:      Argument to use when printing a message about this event.
  */
 void tt_record_buf(struct tt_buffer *buffer, __u64 timestamp,
 		const char* format, __u32 arg0, __u32 arg1, __u32 arg2,
@@ -353,12 +353,12 @@ int tt_proc_open(struct inode *inode, struct file *file)
 /**
  * tt_proc_read() - This function is invoked to handle read kernel calls on
  * /proc/timetrace.
- * @file:    Information about the file being read.
- * @buffer:  Address in user space of the buffer in which data from the file
- *           should be returned.
- * @length:  Number of bytes available at @buffer.
- * @offset:  Current read offset within the file. For now, we assume I/O
- *           is done sequentially, so we ignore this.
+ * @file:     Information about the file being read.
+ * @user_buf: Address in user space of the buffer in which data from the file
+ *            should be returned.
+ * @length:   Number of bytes available at @buffer.
+ * @offset:   Current read offset within the file. For now, we assume I/O
+ *            is done sequentially, so we ignore this.
  *
  * Return: the number of bytes returned at @buffer. 0 means the end of the
  * file was reached, and a negative number indicates an error (-errno).
@@ -540,7 +540,7 @@ int tt_proc_release(struct inode *inode, struct file *file)
  * As of 2/2024, this function is not reliable in situations where the machine
  * is about to crash.  It seems to print the trace, but after reboot the
  * file isn't there.
- * @file:  Name of the file in which to print the timetrace; should be
+ * @path:  Name of the file in which to print the timetrace; should be
  *         an absolute file name.
  */
 void tt_print_file(char *path)
@@ -800,6 +800,7 @@ void tt_get_messages(char *buffer, size_t length)
 /**
  * tt_dbg1() - Invoked by the Linux kernel for various temporary debugging
  * purposes. Arguments are defined as needed for a specific situation.
+ * @msg:   String message providing useful debugging information.
  */
 void tt_dbg1(char *msg, ...)
 {
@@ -808,6 +809,7 @@ void tt_dbg1(char *msg, ...)
 /**
  * tt_dbg2() - Invoked by the Linux kernel for various temporary debugging
  * purposes. Arguments are defined as needed for a specific situation.
+ * @msg:   String message providing useful debugging information.
  */
 void tt_dbg2(char *msg, ...)
 {
@@ -816,6 +818,7 @@ void tt_dbg2(char *msg, ...)
 /**
  * tt_dbg3() - Invoked by the Linux kernel for various temporary debugging
  * purposes. Arguments are defined as needed for a specific situation.
+ * @msg:   String message providing useful debugging information.
  */
 void tt_dbg3(char *msg, ...)
 {