From c3bf7774fa24f9c919947cd20dd7211bdf98b113 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:18 -0700 Subject: [PATCH 1/8] scsi: documentation: Clean up scsi_mid_low_api.rst - Update the format (txt to rst) and location of this document (archive.org to docs.kernel.org) - Change url to URL - Spell out "lk" (Linux Kernel) Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20240408025425.18778-2-rdunlap@infradead.org Signed-off-by: Martin K. Petersen --- Documentation/scsi/scsi_mid_low_api.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index 022198c51350..2df29b92e196 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -42,18 +42,18 @@ This version of the document roughly matches linux kernel version 2.6.8 . Documentation ============= There is a SCSI documentation directory within the kernel source tree, -typically Documentation/scsi . Most documents are in plain -(i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be +typically Documentation/scsi . Most documents are in reStructuredText +format. This file is named scsi_mid_low_api.rst and can be found in that directory. A more recent copy of this document may be found -at http://web.archive.org/web/20070107183357rn_1/sg.torque.net/scsi/. -Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is -briefly described in scsi.txt which contains a url to a document -describing the SCSI subsystem in the lk 2.4 series. Two upper level -drivers have documents in that directory: st.txt (SCSI tape driver) and -scsi-generic.txt (for the sg driver). +at https://docs.kernel.org/scsi/scsi_mid_low_api.html. Many LLDs are +documented in Documentation/scsi (e.g. aic7xxx.rst). The SCSI mid-level is +briefly described in scsi.rst which contains a URL to a document describing +the SCSI subsystem in the Linux Kernel 2.4 series. Two upper level +drivers have documents in that directory: st.rst (SCSI tape driver) and +scsi-generic.rst (for the sg driver). -Some documentation (or urls) for LLDs may be found in the C source code -or in the same directory as the C source code. For example to find a url +Some documentation (or URLs) for LLDs may be found in the C source code +or in the same directory as the C source code. For example to find a URL about the USB mass storage driver see the /usr/src/linux/drivers/usb/storage directory. From 293fcea539b5dbfa9d9b73c1e60ae171a393fb9b Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:19 -0700 Subject: [PATCH 2/8] scsi: documentation: Clean up overview - Change http to https where the latter works - Drop references to I2O (Intelligent I/O) - Use lore.kernel.org instead of marc.info for email links - Update the location of the scsi_debug documentation Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20240408025425.18778-3-rdunlap@infradead.org Signed-off-by: Martin K. Petersen --- Documentation/driver-api/scsi.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 64b231d125e0..332c54683006 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -20,7 +20,7 @@ Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen out of use, the SCSI command set is more widely used than ever to communicate with devices over a number of different busses. -The `SCSI protocol `__ is a big-endian +The `SCSI protocol `__ is a big-endian peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16 bytes long, often followed by an associated data payload. @@ -28,8 +28,7 @@ SCSI commands can be transported over just about any kind of bus, and are the default protocol for storage devices attached to USB, SATA, SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also commonly exchanged over Infiniband, -`I2O `__, TCP/IP -(`iSCSI `__), even `Parallel +TCP/IP (`iSCSI `__), even `Parallel ports `__. Design of the Linux SCSI subsystem @@ -170,9 +169,9 @@ drivers/scsi/scsi_netlink.c Infrastructure to provide async events from transports to userspace via netlink, using a single NETLINK_SCSITRANSPORT protocol for all -transports. See `the original patch -submission `__ for -more details. +transports. See `the original patch submission +`__ +for more details. .. kernel-doc:: drivers/scsi/scsi_netlink.c :internal: @@ -328,11 +327,11 @@ the ordinary is seen. To be more realistic, the simulated devices have the transport attributes of SAS disks. -For documentation see http://sg.danny.cz/sg/sdebug26.html +For documentation see http://sg.danny.cz/sg/scsi_debug.html todo ~~~~ Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel, -FireWire, ATAPI devices, Infiniband, I2O, Parallel ports, +FireWire, ATAPI devices, Infiniband, Parallel ports, netlink... From fcf8829fd993348af9f498e486af0a209996f548 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:20 -0700 Subject: [PATCH 3/8] 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(+) 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 From 11d99e91846a1c751173c8f21953bd755e7ae4df Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:21 -0700 Subject: [PATCH 4/8] 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(-) 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 { From d9c91182414524f1fa0f30584eb90f8211724bdb Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:22 -0700 Subject: [PATCH 5/8] 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(-) 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; From 8d523f0f5383a4f6ae74b6ccf3e0ec953a56dec6 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:23 -0700 Subject: [PATCH 6/8] 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(-) 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) From 007c04e535262417f8206b1bc0aaf1744467430c Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:24 -0700 Subject: [PATCH 7/8] 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(-) 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) From a2530eb748fff3966d3b20d1be81393fb403ec51 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 7 Apr 2024 19:54:25 -0700 Subject: [PATCH 8/8] 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(-) 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(). */