Merge patch series "scsi: documentation: clean up docs and fix kernel-doc"

Randy Dunlap <rdunlap@infradead.org> says: Clean up some SCSI doc files and fix kernel-doc in 6 header files in include/scsi/. Link: https://lore.kernel.org/r/20240408025425.18778-1-rdunlap@infradead.org Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>
2024-04-08 22:16:25 -04:00
parent eab302e89f a2530eb748
commit a0c25d66b1
8 changed files with 46 additions and 34 deletions
@@ -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 {
@@ -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;
@@ -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)
@@ -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
@@ -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)
@@ -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().
 */