From fcf8829fd993348af9f498e486af0a209996f548 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:20 -0700 Subject: scsi: core: Add kernel-doc for scsi_msg_to_host_byte() Add entries for missing documentation to prevent kernel-doc warnings: scsi_cmnd.h:365: warning: Function parameter or struct member 'cmd' not described in 'scsi_msg_to_host_byte' scsi_cmnd.h:365: warning: Function parameter or struct member 'msg' not described in 'scsi_msg_to_host_byte' Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20240408025425.18778-4-rdunlap@infradead.org Reviewed-by: Bart Van Assche Signed-off-by: Martin K. Petersen --- include/scsi/scsi_cmnd.h | 2 ++ 1 file changed, 2 insertions(+) (limited to 'include/scsi') diff --git a/include/scsi/scsi_cmnd.h b/include/scsi/scsi_cmnd.h index 526def14e7fb..45c40d200154 100644 --- a/include/scsi/scsi_cmnd.h +++ b/include/scsi/scsi_cmnd.h @@ -353,6 +353,8 @@ static inline u8 get_host_byte(struct scsi_cmnd *cmd) /** * scsi_msg_to_host_byte() - translate message byte + * @cmd: the SCSI command + * @msg: the SCSI parallel message byte to translate * * Translate the SCSI parallel message byte to a matching * host byte setting. A message of COMMAND_COMPLETE indicates -- cgit v1.2.3 From 11d99e91846a1c751173c8f21953bd755e7ae4df Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:21 -0700 Subject: scsi: iser: Fix @read_stag kernel-doc warning Correct kernel-doc comments for struct iser_ctrl to prevent warnings: iser.h:76: warning: Function parameter or struct member 'read_stag' not described in 'iser_ctrl' iser.h:76: warning: Excess struct member 'reaf_stag' description in 'iser_ctrl' Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20240408025425.18778-5-rdunlap@infradead.org Acked-by: Sagi Grimberg Reviewed-by: Max Gurtovoy Signed-off-by: Martin K. Petersen --- include/scsi/iser.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/scsi') diff --git a/include/scsi/iser.h b/include/scsi/iser.h index 2e678fa74eca..07a83bfa2b8e 100644 --- a/include/scsi/iser.h +++ b/include/scsi/iser.h @@ -63,7 +63,7 @@ struct iser_cm_hdr { * @rsvd: reserved * @write_stag: write rkey * @write_va: write virtual address - * @reaf_stag: read rkey + * @read_stag: read rkey * @read_va: read virtual address */ struct iser_ctrl { -- cgit v1.2.3 From d9c91182414524f1fa0f30584eb90f8211724bdb Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:22 -0700 Subject: scsi: libfcoe: Fix a slew of kernel-doc warnings Fix all kernel-doc warnings in : libfcoe.h:163: warning: Function parameter or struct member 'ctlr' not described in 'fcoe_ctlr_priv' libfcoe.h:163: warning: Excess function parameter 'cltr' description in 'fcoe_ctlr_priv' libfcoe.h:163: warning: No description found for return value of 'fcoe_ctlr_priv' libfcoe.h:218: warning: Function parameter or struct member 'fd_flags' not described in 'fcoe_fcf' libfcoe.h:218: warning: Excess struct member 'event' description in 'fcoe_fcf' libfcoe.h:240: warning: Function parameter or struct member 'rdata' not described in 'fcoe_rport' libfcoe.h:273: warning: No description found for return value of 'is_fip_mode' libfcoe.h:332: warning: Function parameter or struct member 'crc_eof_page' not described in 'fcoe_percpu_s' libfcoe.h:332: warning: Function parameter or struct member 'lock' not described in 'fcoe_percpu_s' libfcoe.h:332: warning: Excess struct member 'page' description in 'fcoe_percpu_s' libfcoe.h:362: warning: Function parameter or struct member 'data_src_addr' not described in 'fcoe_port' libfcoe.h:362: warning: Function parameter or struct member 'get_netdev' not described in 'fcoe_port' libfcoe.h:362: warning: Excess struct member 'data_srt_addr' description in 'fcoe_port' libfcoe.h:369: warning: No description found for return value of 'fcoe_get_netdev' libfcoe.h:386: warning: missing initial short description on line: * struct netdev_list libfcoe.h:393: warning: expecting prototype for struct netdev_list. Prototype was for struct fcoe_netdev_mapping instead Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20240408025425.18778-6-rdunlap@infradead.org Signed-off-by: Martin K. Petersen --- include/scsi/libfcoe.h | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'include/scsi') diff --git a/include/scsi/libfcoe.h b/include/scsi/libfcoe.h index 8300ef1a982e..3c5899290aed 100644 --- a/include/scsi/libfcoe.h +++ b/include/scsi/libfcoe.h @@ -157,7 +157,9 @@ struct fcoe_ctlr { /** * fcoe_ctlr_priv() - Return the private data from a fcoe_ctlr - * @cltr: The fcoe_ctlr whose private data will be returned + * @ctlr: The fcoe_ctlr whose private data will be returned + * + * Returns: pointer to the private data */ static inline void *fcoe_ctlr_priv(const struct fcoe_ctlr *ctlr) { @@ -174,7 +176,6 @@ static inline void *fcoe_ctlr_priv(const struct fcoe_ctlr *ctlr) * struct fcoe_fcf - Fibre-Channel Forwarder * @list: list linkage * @event_work: Work for FC Transport actions queue - * @event: The event to be processed * @fip: The controller that the FCF was discovered on * @fcf_dev: The associated fcoe_fcf_device instance * @time: system time (jiffies) when an advertisement was last received @@ -188,6 +189,7 @@ static inline void *fcoe_ctlr_priv(const struct fcoe_ctlr *ctlr) * @flogi_sent: current FLOGI sent to this FCF * @flags: flags received from advertisement * @fka_period: keep-alive period, in jiffies + * @fd_flags: no need for FKA from ENode * * A Fibre-Channel Forwarder (FCF) is the entity on the Ethernet that * passes FCoE frames on to an FC fabric. This structure represents @@ -222,6 +224,7 @@ struct fcoe_fcf { /** * struct fcoe_rport - VN2VN remote port + * @rdata: libfc remote port private data * @time: time of create or last beacon packet received from node * @fcoe_len: max FCoE frame size, not including VLAN or Ethernet headers * @flags: flags from probe or claim @@ -266,8 +269,10 @@ void fcoe_get_lesb(struct fc_lport *, struct fc_els_lesb *); void fcoe_ctlr_get_lesb(struct fcoe_ctlr_device *ctlr_dev); /** - * is_fip_mode() - returns true if FIP mode selected. + * is_fip_mode() - test if FIP mode selected. * @fip: FCoE controller. + * + * Returns: %true if FIP mode is selected */ static inline bool is_fip_mode(struct fcoe_ctlr *fip) { @@ -318,9 +323,10 @@ struct fcoe_transport { * @kthread: The thread context (used by bnx2fc) * @work: The work item (used by fcoe) * @fcoe_rx_list: The queue of pending packets to process - * @page: The memory page for calculating frame trailer CRCs + * @crc_eof_page: The memory page for calculating frame trailer CRCs * @crc_eof_offset: The offset into the CRC page pointing to available * memory for a new trailer + * @lock: local lock for members of this struct */ struct fcoe_percpu_s { struct task_struct *kthread; @@ -343,7 +349,8 @@ struct fcoe_percpu_s { * @timer: The queue timer * @destroy_work: Handle for work context * (to prevent RTNL deadlocks) - * @data_srt_addr: Source address for data + * @data_src_addr: Source address for data + * @get_netdev: function that returns a &net_device from @lport * * An instance of this structure is to be allocated along with the * Scsi_Host and libfc fc_lport structures. @@ -364,6 +371,8 @@ struct fcoe_port { /** * fcoe_get_netdev() - Return the net device associated with a local port * @lport: The local port to get the net device from + * + * Returns: the &net_device associated with this @lport */ static inline struct net_device *fcoe_get_netdev(const struct fc_lport *lport) { @@ -383,8 +392,10 @@ void fcoe_fcf_get_selected(struct fcoe_fcf_device *); void fcoe_ctlr_set_fip_mode(struct fcoe_ctlr_device *); /** - * struct netdev_list - * A mapping from netdevice to fcoe_transport + * struct fcoe_netdev_mapping - A mapping from &net_device to &fcoe_transport + * @list: list linkage of the mappings + * @netdev: the &net_device + * @ft: the fcoe_transport associated with @netdev */ struct fcoe_netdev_mapping { struct list_head list; -- cgit v1.2.3 From 8d523f0f5383a4f6ae74b6ccf3e0ec953a56dec6 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:23 -0700 Subject: scsi: core: Add function return kernel-doc for 2 functions Add missing function return values to prevent kernel-doc warnings: scsi.h:75: warning: No description found for return value of 'scsi_status_is_check_condition' scsi.h:202: warning: No description found for return value of 'scsi_status_is_good' Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20240408025425.18778-7-rdunlap@infradead.org Reviewed-by: Bart Van Assche Signed-off-by: Martin K. Petersen --- include/scsi/scsi.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'include/scsi') diff --git a/include/scsi/scsi.h b/include/scsi/scsi.h index 4498f845b112..d90645f06a3a 100644 --- a/include/scsi/scsi.h +++ b/include/scsi/scsi.h @@ -69,7 +69,7 @@ static inline int scsi_is_wlun(u64 lun) * @status: the status passed up from the driver (including host and * driver components) * - * This returns true if the status code is SAM_STAT_CHECK_CONDITION. + * Returns: %true if the status code is SAM_STAT_CHECK_CONDITION. */ static inline int scsi_status_is_check_condition(int status) { @@ -189,12 +189,13 @@ enum scsi_disposition { /* Used to obtain the PCI location of a device */ #define SCSI_IOCTL_GET_PCI 0x5387 -/** scsi_status_is_good - check the status return. +/** + * scsi_status_is_good - check the status return. * * @status: the status passed up from the driver (including host and * driver components) * - * This returns true for known good conditions that may be treated as + * Returns: %true for known good conditions that may be treated as * command completed normally */ static inline bool scsi_status_is_good(int status) -- cgit v1.2.3 From 007c04e535262417f8206b1bc0aaf1744467430c Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:24 -0700 Subject: scsi: scsi_transport_fc: Add kernel-doc for function return Add function return value to prevent a kernel-doc warning: scsi_transport_fc.h:780: warning: No description found for return value of 'fc_remote_port_chkready' Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20240408025425.18778-8-rdunlap@infradead.org Signed-off-by: Martin K. Petersen --- include/scsi/scsi_transport_fc.h | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'include/scsi') diff --git a/include/scsi/scsi_transport_fc.h b/include/scsi/scsi_transport_fc.h index 483513c57597..ebb1bd565103 100644 --- a/include/scsi/scsi_transport_fc.h +++ b/include/scsi/scsi_transport_fc.h @@ -770,10 +770,9 @@ struct fc_function_template { /** * fc_remote_port_chkready - called to validate the remote port state * prior to initiating io to the port. - * - * Returns a scsi result code that can be returned by the LLDD. - * * @rport: remote port to be checked + * + * Returns: a scsi result code that can be returned by the LLDD. **/ static inline int fc_remote_port_chkready(struct fc_rport *rport) -- cgit v1.2.3 From a2530eb748fff3966d3b20d1be81393fb403ec51 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:25 -0700 Subject: scsi: scsi_transport_srp: Fix a couple of kernel-doc warnings Add a struct short description and a function return value to prevent kernel-doc warnings: scsi_transport_srp.h:77: warning: missing initial short description on line: * struct srp_function_template scsi_transport_srp.h:132: warning: No description found for return value of 'srp_chkready' Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20240408025425.18778-9-rdunlap@infradead.org Reviewed-by: Bart Van Assche Signed-off-by: Martin K. Petersen --- include/scsi/scsi_transport_srp.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'include/scsi') diff --git a/include/scsi/scsi_transport_srp.h b/include/scsi/scsi_transport_srp.h index dfc78aa112ad..5b70b538447e 100644 --- a/include/scsi/scsi_transport_srp.h +++ b/include/scsi/scsi_transport_srp.h @@ -74,7 +74,7 @@ struct srp_rport { }; /** - * struct srp_function_template + * struct srp_function_template - template for SRP initiator drivers * * Fields that are only relevant for SRP initiator drivers: * @has_rport_state: Whether or not to create the state, fast_io_fail_tmo and @@ -124,7 +124,7 @@ enum scsi_timeout_action srp_timed_out(struct scsi_cmnd *scmd); * srp_chkready() - evaluate the transport layer state before I/O * @rport: SRP target port pointer. * - * Returns a SCSI result code that can be returned by the LLD queuecommand() + * Returns: a SCSI result code that can be returned by the LLD queuecommand() * implementation. The role of this function is similar to that of * fc_remote_port_chkready(). */ -- cgit v1.2.3