Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Jack Wang <jinpu.wang@ionos.com>
Signed-off-by: Jason Gunthorpe <jgg@nvidia.com>
authored by
Randy Dunlap
and committed by
Jason Gunthorpe
c1776ccb
6f056117
+36
-20
+21
-11
drivers/infiniband/ulp/rtrs/rtrs-pri.h
+21
-11
drivers/infiniband/ulp/rtrs/rtrs-pri.h
···
150
150
151
151
/**
152
152
* enum rtrs_msg_flags - RTRS message flags.
153
-
* @RTRS_NEED_INVAL: Send invalidation in response.
153
+
* @RTRS_MSG_NEED_INVAL_F: Send invalidation in response.
154
154
* @RTRS_MSG_NEW_RKEY_F: Send refreshed rkey in response.
155
155
*/
156
156
enum rtrs_msg_flags {
···
179
179
* @recon_cnt: Reconnections counter
180
180
* @sess_uuid: UUID of a session (path)
181
181
* @paths_uuid: UUID of a group of sessions (paths)
182
-
*
182
+
* @first_conn: %1 if the connection request is the first for that session,
183
+
* otherwise %0
183
184
* NOTE: max size 56 bytes, see man rdma_connect().
184
185
*/
185
186
struct rtrs_msg_conn_req {
186
-
/* Is set to 0 by cma.c in case of AF_IB, do not touch that.
187
-
* see https://www.spinics.net/lists/linux-rdma/msg22397.html
187
+
/**
188
+
* @__cma_version: Is set to 0 by cma.c in case of AF_IB, do not touch
189
+
* that. See https://www.spinics.net/lists/linux-rdma/msg22397.html
188
190
*/
189
191
u8 __cma_version;
190
-
/* On sender side that should be set to 0, or cma_save_ip_info()
191
-
* extract garbage and will fail.
192
+
/**
193
+
* @__ip_version: On sender side that should be set to 0, or
194
+
* cma_save_ip_info() extract garbage and will fail.
192
195
*/
193
196
u8 __ip_version;
194
197
__le16 magic;
···
202
199
uuid_t sess_uuid;
203
200
uuid_t paths_uuid;
204
201
u8 first_conn : 1;
202
+
/* private: */
205
203
u8 reserved_bits : 7;
206
204
u8 reserved[11];
207
205
};
···
215
211
* @queue_depth: max inflight messages (queue-depth) in this session
216
212
* @max_io_size: max io size server supports
217
213
* @max_hdr_size: max msg header size server supports
214
+
* @flags: RTRS message flags for this message
218
215
*
219
216
* NOTE: size is 56 bytes, max possible is 136 bytes, see man rdma_accept().
220
217
*/
···
227
222
__le32 max_io_size;
228
223
__le32 max_hdr_size;
229
224
__le32 flags;
225
+
/* private: */
230
226
u8 reserved[36];
231
227
};
232
228
233
229
/**
234
-
* struct rtrs_msg_info_req
230
+
* struct rtrs_msg_info_req - client additional info request
235
231
* @type: @RTRS_MSG_INFO_REQ
236
232
* @pathname: Path name chosen by client
237
233
*/
238
234
struct rtrs_msg_info_req {
239
235
__le16 type;
240
236
u8 pathname[NAME_MAX];
237
+
/* private: */
241
238
u8 reserved[15];
242
239
};
243
240
244
241
/**
245
-
* struct rtrs_msg_info_rsp
242
+
* struct rtrs_msg_info_rsp - server additional info response
246
243
* @type: @RTRS_MSG_INFO_RSP
247
244
* @sg_cnt: Number of @desc entries
248
245
* @desc: RDMA buffers where the client can write to server
···
252
245
struct rtrs_msg_info_rsp {
253
246
__le16 type;
254
247
__le16 sg_cnt;
248
+
/* private: */
255
249
u8 reserved[4];
250
+
/* public: */
256
251
struct rtrs_sg_desc desc[];
257
252
};
258
253
259
254
/**
260
-
* struct rtrs_msg_rkey_rsp
255
+
* struct rtrs_msg_rkey_rsp - server refreshed rkey response
261
256
* @type: @RTRS_MSG_RKEY_RSP
262
257
* @buf_id: RDMA buf_id of the new rkey
263
258
* @rkey: new remote key for RDMA buffers id from server
···
273
264
/**
274
265
* struct rtrs_msg_rdma_read - RDMA data transfer request from client
275
266
* @type: always @RTRS_MSG_READ
267
+
* @flags: RTRS message flags (enum rtrs_msg_flags)
276
268
* @usr_len: length of user payload
277
269
* @sg_cnt: number of @desc entries
278
270
* @desc: RDMA buffers where the server can write the result to
···
287
277
};
288
278
289
279
/**
290
-
* struct_msg_rdma_write - Message transferred to server with RDMA-Write
280
+
* struct rtrs_msg_rdma_write - Message transferred to server with RDMA-Write
291
281
* @type: always @RTRS_MSG_WRITE
292
282
* @usr_len: length of user payload
293
283
*/
···
297
287
};
298
288
299
289
/**
300
-
* struct_msg_rdma_hdr - header for read or write request
290
+
* struct rtrs_msg_rdma_hdr - header for read or write request
301
291
* @type: @RTRS_MSG_WRITE | @RTRS_MSG_READ
302
292
*/
303
293
struct rtrs_msg_rdma_hdr {
+15
-9
drivers/infiniband/ulp/rtrs/rtrs.h
+15
-9
drivers/infiniband/ulp/rtrs/rtrs.h
···
24
24
25
25
/**
26
26
* enum rtrs_clt_link_ev - Events about connectivity state of a client
27
-
* @RTRS_CLT_LINK_EV_RECONNECTED Client was reconnected.
28
-
* @RTRS_CLT_LINK_EV_DISCONNECTED Client was disconnected.
27
+
* @RTRS_CLT_LINK_EV_RECONNECTED: Client was reconnected.
28
+
* @RTRS_CLT_LINK_EV_DISCONNECTED: Client was disconnected.
29
29
*/
30
30
enum rtrs_clt_link_ev {
31
31
RTRS_CLT_LINK_EV_RECONNECTED,
···
33
33
};
34
34
35
35
/**
36
-
* Source and destination address of a path to be established
36
+
* struct rtrs_addr - Source and destination address of a path to be established
37
+
* @src: source address
38
+
* @dst: destination address
37
39
*/
38
40
struct rtrs_addr {
39
41
struct sockaddr_storage *src;
···
43
41
};
44
42
45
43
/**
46
-
* rtrs_clt_ops - it holds the link event callback and private pointer.
44
+
* struct rtrs_clt_ops - it holds the link event callback and private pointer.
47
45
* @priv: User supplied private data.
48
46
* @link_ev: Event notification callback function for connection state changes
49
47
* @priv: User supplied data that was passed to rtrs_clt_open()
···
69
67
};
70
68
71
69
/**
72
-
* enum rtrs_clt_con_type() type of ib connection to use with a given
70
+
* enum rtrs_clt_con_type - type of ib connection to use with a given
73
71
* rtrs_permit
74
-
* @ADMIN_CON - use connection reserved for "service" messages
75
-
* @IO_CON - use a connection reserved for IO
72
+
* @RTRS_ADMIN_CON: use connection reserved for "service" messages
73
+
* @RTRS_IO_CON: use a connection reserved for IO
76
74
*/
77
75
enum rtrs_clt_con_type {
78
76
RTRS_ADMIN_CON,
···
87
85
struct rtrs_permit *permit);
88
86
89
87
/**
90
-
* rtrs_clt_req_ops - it holds the request confirmation callback
88
+
* struct rtrs_clt_req_ops - it holds the request confirmation callback
91
89
* and a private pointer.
92
90
* @priv: User supplied private data.
93
91
* @conf_fn: callback function to be called as confirmation
···
107
105
int rtrs_clt_rdma_cq_direct(struct rtrs_clt_sess *clt, unsigned int index);
108
106
109
107
/**
110
-
* rtrs_attrs - RTRS session attributes
108
+
* struct rtrs_attrs - RTRS session attributes
109
+
* @queue_depth: queue_depth saved from rtrs_clt_sess message
110
+
* @max_io_size: max_io_size from rtrs_clt_sess message, capped to
111
+
* @max_segments * %SZ_4K
112
+
* @max_segments: max_segments saved from rtrs_clt_sess message
111
113
*/
112
114
struct rtrs_attrs {
113
115
u32 queue_depth;