Commit c1776ccb authored by Randy Dunlap's avatar Randy Dunlap Committed by Jason Gunthorpe
Browse files

RTRS/rtrs: clean up rtrs headers kernel-doc 

Fix all (30+) kernel-doc warnings in rtrs.h and rtrs-pri.h.  The changes
are:

- add ending ':' to enum member names
- change enum description separators from '-' to ':'
- add "struct" keyword to kernel-doc for structs where missing
- fix enum names in enum rtrs_clt_con_type
- add a '-' separator and drop the "()" in enum rtrs_clt_con_type
- convert struct rtrs_addr to kernel-doc format
- add missing struct member descriptions for struct rtrs_attrs

Link: https://patch.msgid.link/r/20251129022146.1498273-1-rdunlap@infradead.org


Signed-off-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Acked-by: default avatarJack Wang <jinpu.wang@ionos.com>
Signed-off-by: default avatarJason Gunthorpe <jgg@nvidia.com>
parent 6f056117

drivers/infiniband/ulp/rtrs/rtrs-pri.h

+21 −11
Original line number Diff line number Diff line
@@ -150,7 +150,7 @@ enum rtrs_msg_types { 


/**

 * enum rtrs_msg_flags - RTRS message flags.

 * @RTRS_NEED_INVAL:	Send invalidation in response.

 * @RTRS_MSG_NEED_INVAL_F: Send invalidation in response.

 * @RTRS_MSG_NEW_RKEY_F: Send refreshed rkey in response.

 */

enum rtrs_msg_flags {
@@ -179,16 +179,19 @@ struct rtrs_sg_desc { 
 * @recon_cnt:	   Reconnections counter

 * @sess_uuid:	   UUID of a session (path)

 * @paths_uuid:	   UUID of a group of sessions (paths)

 *

 * @first_conn:    %1 if the connection request is the first for that session,

 *			otherwise %0

 * NOTE: max size 56 bytes, see man rdma_connect().

 */

struct rtrs_msg_conn_req {

	/* Is set to 0 by cma.c in case of AF_IB, do not touch that.

	 * see https://www.spinics.net/lists/linux-rdma/msg22397.html

	/**

	 * @__cma_version: Is set to 0 by cma.c in case of AF_IB, do not touch

	 * that. See https://www.spinics.net/lists/linux-rdma/msg22397.html

	 */

	u8		__cma_version;

	/* On sender side that should be set to 0, or cma_save_ip_info()

	 * extract garbage and will fail.

	/**

	 * @__ip_version: On sender side that should be set to 0, or

	 * cma_save_ip_info() extract garbage and will fail.

	 */

	u8		__ip_version;

	__le16		magic;
@@ -199,6 +202,7 @@ struct rtrs_msg_conn_req { 
	uuid_t		sess_uuid;

	uuid_t		paths_uuid;

	u8		first_conn : 1;

	/* private: */

	u8		reserved_bits : 7;

	u8		reserved[11];

};
@@ -211,6 +215,7 @@ struct rtrs_msg_conn_req { 
 * @queue_depth:   max inflight messages (queue-depth) in this session

 * @max_io_size:   max io size server supports

 * @max_hdr_size:  max msg header size server supports

 * @flags:	   RTRS message flags for this message

 *

 * NOTE: size is 56 bytes, max possible is 136 bytes, see man rdma_accept().

 */
@@ -222,22 +227,24 @@ struct rtrs_msg_conn_rsp { 
	__le32		max_io_size;

	__le32		max_hdr_size;

	__le32		flags;

	/* private: */

	u8		reserved[36];

};



/**

 * struct rtrs_msg_info_req

 * struct rtrs_msg_info_req - client additional info request

 * @type:		@RTRS_MSG_INFO_REQ

 * @pathname:		Path name chosen by client

 */

struct rtrs_msg_info_req {

	__le16		type;

	u8		pathname[NAME_MAX];

	/* private: */

	u8		reserved[15];

};



/**

 * struct rtrs_msg_info_rsp

 * struct rtrs_msg_info_rsp - server additional info response

 * @type:		@RTRS_MSG_INFO_RSP

 * @sg_cnt:		Number of @desc entries

 * @desc:		RDMA buffers where the client can write to server
@@ -245,12 +252,14 @@ struct rtrs_msg_info_req { 
struct rtrs_msg_info_rsp {

	__le16		type;

	__le16          sg_cnt;

	/* private: */

	u8              reserved[4];

	/* public: */

	struct rtrs_sg_desc desc[];

};



/**

 * struct rtrs_msg_rkey_rsp

 * struct rtrs_msg_rkey_rsp - server refreshed rkey response

 * @type:		@RTRS_MSG_RKEY_RSP

 * @buf_id:		RDMA buf_id of the new rkey

 * @rkey:		new remote key for RDMA buffers id from server
@@ -264,6 +273,7 @@ struct rtrs_msg_rkey_rsp { 
/**

 * struct rtrs_msg_rdma_read - RDMA data transfer request from client

 * @type:		always @RTRS_MSG_READ

 * @flags:		RTRS message flags (enum rtrs_msg_flags)

 * @usr_len:		length of user payload

 * @sg_cnt:		number of @desc entries

 * @desc:		RDMA buffers where the server can write the result to
@@ -277,7 +287,7 @@ struct rtrs_msg_rdma_read { 
};



/**

 * struct_msg_rdma_write - Message transferred to server with RDMA-Write

 * struct rtrs_msg_rdma_write - Message transferred to server with RDMA-Write

 * @type:		always @RTRS_MSG_WRITE

 * @usr_len:		length of user payload

 */
@@ -287,7 +297,7 @@ struct rtrs_msg_rdma_write { 
};



/**

 * struct_msg_rdma_hdr - header for read or write request

 * struct rtrs_msg_rdma_hdr - header for read or write request

 * @type:		@RTRS_MSG_WRITE | @RTRS_MSG_READ

 */

struct rtrs_msg_rdma_hdr {

drivers/infiniband/ulp/rtrs/rtrs.h

+15 −9
Original line number Diff line number Diff line
@@ -24,8 +24,8 @@ struct rtrs_srv_op; 


/**

 * enum rtrs_clt_link_ev - Events about connectivity state of a client

 * @RTRS_CLT_LINK_EV_RECONNECTED	Client was reconnected.

 * @RTRS_CLT_LINK_EV_DISCONNECTED	Client was disconnected.

 * @RTRS_CLT_LINK_EV_RECONNECTED:	Client was reconnected.

 * @RTRS_CLT_LINK_EV_DISCONNECTED:	Client was disconnected.

 */

enum rtrs_clt_link_ev {

	RTRS_CLT_LINK_EV_RECONNECTED,
@@ -33,7 +33,9 @@ enum rtrs_clt_link_ev { 
};



/**

 * Source and destination address of a path to be established

 * struct rtrs_addr - Source and destination address of a path to be established

 * @src:	source address

 * @dst:	destination address

 */

struct rtrs_addr {

	struct sockaddr_storage *src;
@@ -41,7 +43,7 @@ struct rtrs_addr { 
};



/**

 * rtrs_clt_ops - it holds the link event callback and private pointer.

 * struct rtrs_clt_ops - it holds the link event callback and private pointer.

 * @priv: User supplied private data.

 * @link_ev: Event notification callback function for connection state changes

 *	@priv: User supplied data that was passed to rtrs_clt_open()
@@ -67,10 +69,10 @@ enum wait_type { 
};



/**

 * enum rtrs_clt_con_type() type of ib connection to use with a given

 * enum rtrs_clt_con_type - type of ib connection to use with a given

 * rtrs_permit

 * @ADMIN_CON - use connection reserved for "service" messages

 * @IO_CON - use a connection reserved for IO

 * @RTRS_ADMIN_CON: use connection reserved for "service" messages

 * @RTRS_IO_CON: use a connection reserved for IO

 */

enum rtrs_clt_con_type {

	RTRS_ADMIN_CON,
@@ -85,7 +87,7 @@ void rtrs_clt_put_permit(struct rtrs_clt_sess *sess, 
			 struct rtrs_permit *permit);



/**

 * rtrs_clt_req_ops - it holds the request confirmation callback

 * struct rtrs_clt_req_ops - it holds the request confirmation callback

 * and a private pointer.

 * @priv: User supplied private data.

 * @conf_fn:	callback function to be called as confirmation
@@ -105,7 +107,11 @@ int rtrs_clt_request(int dir, struct rtrs_clt_req_ops *ops, 
int rtrs_clt_rdma_cq_direct(struct rtrs_clt_sess *clt, unsigned int index);



/**

 * rtrs_attrs - RTRS session attributes

 * struct rtrs_attrs - RTRS session attributes

 * @queue_depth:	queue_depth saved from rtrs_clt_sess message

 * @max_io_size:	max_io_size from rtrs_clt_sess message, capped to

 *			  @max_segments * %SZ_4K

 * @max_segments:	max_segments saved from rtrs_clt_sess message

 */

struct rtrs_attrs {

	u32		queue_depth;