tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

scsi: libfc: Add some kernel-doc comments

Complete the kernel-doc notation for enum fc_lport_state. This fixes 7
kernel-doc warnings.

- In struct fc_rport_priv, change 'event_callback' to 'lld_event_callback'
to match the struct member name.

- In struct fc_fcp_pkt, add a description for 'timer_delay' to eliminate
one kernel-doc warning.

- Add return value notation for 3 functions. This fixes 3 kernel-doc
warnings.

There are still 12 warnings for struct members not described in struct
fc_rport_priv and struct fc_lport, e.g:

libfc.h:218: warning: Function parameter or struct member 'event' not described in 'fc_rport_priv'
libfc.h:760: warning: Function parameter or struct member 'vlan' not described in 'fc_lport'

Warnings that are fixed in this patch:

libfc.h:75: warning: Enum value 'LPORT_ST_RNN_ID' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_RSNN_NN' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_RSPN_ID' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_RPA' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_DHBA' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_DPRT' not described in enum 'fc_lport_state'
libfc.h:75: warning: Excess enum value 'LPORT_ST_RPN_ID' description in 'fc_lport_state'

libfc.h:218: warning: Excess struct member 'event_callback' description in 'fc_rport_priv'

libfc.h:793: warning: No description found for return value of 'fc_lport_test_ready'
libfc.h:835: warning: No description found for return value of 'fc_lport_init_stats'
libfc.h:856: warning: No description found for return value of 'lport_priv'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20240424050038.31403-1-rdunlap@infradead.org
Cc: Hannes Reinecke <hare@suse.de>
Cc: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
Cc: Martin K. Petersen <martin.petersen@oracle.com>
Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>

authored by

Randy Dunlap and committed by
Martin K. Petersen 9cef74a9 2a7177a8

+15 -3
+15 -3
include/scsi/libfc.h
··· 44 44 * @LPORT_ST_DISABLED: Disabled 45 45 * @LPORT_ST_FLOGI: Fabric login (FLOGI) sent 46 46 * @LPORT_ST_DNS: Waiting for name server remote port to become ready 47 - * @LPORT_ST_RPN_ID: Register port name by ID (RPN_ID) sent 47 + * @LPORT_ST_RNN_ID: Register port name by ID (RNN_ID) sent 48 + * @LPORT_ST_RSNN_NN: Waiting for host symbolic node name 49 + * @LPORT_ST_RSPN_ID: Waiting for host symbolic port name 48 50 * @LPORT_ST_RFT_ID: Register Fibre Channel types by ID (RFT_ID) sent 49 51 * @LPORT_ST_RFF_ID: Register FC-4 Features by ID (RFF_ID) sent 50 52 * @LPORT_ST_FDMI: Waiting for mgmt server rport to become ready 51 - * @LPORT_ST_RHBA: 53 + * @LPORT_ST_RHBA: Register HBA 54 + * @LPORT_ST_RPA: Register Port Attributes 55 + * @LPORT_ST_DHBA: Deregister HBA 56 + * @LPORT_ST_DPRT: Deregister Port 52 57 * @LPORT_ST_SCR: State Change Register (SCR) sent 53 58 * @LPORT_ST_READY: Ready for use 54 59 * @LPORT_ST_LOGO: Local port logout (LOGO) sent ··· 188 183 * @r_a_tov: Resource allocation timeout value (in msec) 189 184 * @rp_mutex: The mutex that protects the remote port 190 185 * @retry_work: Handle for retries 191 - * @event_callback: Callback when READY, FAILED or LOGO states complete 186 + * @lld_event_callback: Callback when READY, FAILED or LOGO states complete 192 187 * @prli_count: Count of open PRLI sessions in providers 193 188 * @rcu: Structure used for freeing in an RCU-safe manner 194 189 */ ··· 294 289 * @timer: The command timer 295 290 * @tm_done: Completion indicator 296 291 * @wait_for_comp: Indicator to wait for completion of the I/O (in jiffies) 292 + * @timer_delay: FCP packet timer delay in jiffies 297 293 * @data_len: The length of the data 298 294 * @cdb_cmd: The CDB command 299 295 * @xfer_len: The transfer length ··· 794 788 /** 795 789 * fc_lport_test_ready() - Determine if a local port is in the READY state 796 790 * @lport: The local port to test 791 + * 792 + * Returns: %true if local port is in the READY state, %false otherwise 797 793 */ 798 794 static inline int fc_lport_test_ready(struct fc_lport *lport) 799 795 { ··· 838 830 /** 839 831 * fc_lport_init_stats() - Allocate per-CPU statistics for a local port 840 832 * @lport: The local port whose statistics are to be initialized 833 + * 834 + * Returns: %0 on success, %-ENOMEM on failure 841 835 */ 842 836 static inline int fc_lport_init_stats(struct fc_lport *lport) 843 837 { ··· 861 851 /** 862 852 * lport_priv() - Return the private data from a local port 863 853 * @lport: The local port whose private data is to be retrieved 854 + * 855 + * Returns: the local port's private data pointer 864 856 */ 865 857 static inline void *lport_priv(const struct fc_lport *lport) 866 858 {