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

+7 -8

Documentation/driver-api/scsi.rst

··· 20 20 out of use, the SCSI command set is more widely used than ever to 21 21 communicate with devices over a number of different busses. 22 22 23 - The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ is a big-endian 23 + The `SCSI protocol <https://www.t10.org/scsi-3.htm>`__ is a big-endian 24 24 peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16 25 25 bytes long, often followed by an associated data payload. 26 26 ··· 28 28 are the default protocol for storage devices attached to USB, SATA, SAS, 29 29 Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also 30 30 commonly exchanged over Infiniband, 31 - `I2O <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP 32 - (`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel 31 + TCP/IP (`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel 33 32 ports <http://cyberelk.net/tim/parport/parscsi.html>`__. 34 33 35 34 Design of the Linux SCSI subsystem ··· 169 170 170 171 Infrastructure to provide async events from transports to userspace via 171 172 netlink, using a single NETLINK_SCSITRANSPORT protocol for all 172 - transports. See `the original patch 173 - submission <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for 174 - more details. 173 + transports. See `the original patch submission 174 + <https://lore.kernel.org/linux-scsi/1155070439.6275.5.camel@localhost.localdomain/>`__ 175 + for more details. 175 176 176 177 .. kernel-doc:: drivers/scsi/scsi_netlink.c 177 178 :internal: ··· 327 328 To be more realistic, the simulated devices have the transport 328 329 attributes of SAS disks. 329 330 330 - For documentation see http://sg.danny.cz/sg/sdebug26.html 331 + For documentation see http://sg.danny.cz/sg/scsi_debug.html 331 332 332 333 todo 333 334 ~~~~ 334 335 335 336 Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel, 336 - FireWire, ATAPI devices, Infiniband, I2O, Parallel ports, 337 + FireWire, ATAPI devices, Infiniband, Parallel ports, 337 338 netlink...

+10 -10

Documentation/scsi/scsi_mid_low_api.rst

··· 42 42 Documentation 43 43 ============= 44 44 There is a SCSI documentation directory within the kernel source tree, 45 - typically Documentation/scsi . Most documents are in plain 46 - (i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be 45 + typically Documentation/scsi . Most documents are in reStructuredText 46 + format. This file is named scsi_mid_low_api.rst and can be 47 47 found in that directory. A more recent copy of this document may be found 48 - at http://web.archive.org/web/20070107183357rn_1/sg.torque.net/scsi/. 49 - Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is 50 - briefly described in scsi.txt which contains a url to a document 51 - describing the SCSI subsystem in the lk 2.4 series. Two upper level 52 - drivers have documents in that directory: st.txt (SCSI tape driver) and 53 - scsi-generic.txt (for the sg driver). 48 + at https://docs.kernel.org/scsi/scsi_mid_low_api.html. Many LLDs are 49 + documented in Documentation/scsi (e.g. aic7xxx.rst). The SCSI mid-level is 50 + briefly described in scsi.rst which contains a URL to a document describing 51 + the SCSI subsystem in the Linux Kernel 2.4 series. Two upper level 52 + drivers have documents in that directory: st.rst (SCSI tape driver) and 53 + scsi-generic.rst (for the sg driver). 54 54 55 - Some documentation (or urls) for LLDs may be found in the C source code 56 - or in the same directory as the C source code. For example to find a url 55 + Some documentation (or URLs) for LLDs may be found in the C source code 56 + or in the same directory as the C source code. For example to find a URL 57 57 about the USB mass storage driver see the 58 58 /usr/src/linux/drivers/usb/storage directory. 59 59

+1 -1

include/scsi/iser.h

··· 63 63 * @rsvd: reserved 64 64 * @write_stag: write rkey 65 65 * @write_va: write virtual address 66 - * @reaf_stag: read rkey 66 + * @read_stag: read rkey 67 67 * @read_va: read virtual address 68 68 */ 69 69 struct iser_ctrl {

+18 -7

include/scsi/libfcoe.h

··· 157 157 158 158 /** 159 159 * fcoe_ctlr_priv() - Return the private data from a fcoe_ctlr 160 - * @cltr: The fcoe_ctlr whose private data will be returned 160 + * @ctlr: The fcoe_ctlr whose private data will be returned 161 + * 162 + * Returns: pointer to the private data 161 163 */ 162 164 static inline void *fcoe_ctlr_priv(const struct fcoe_ctlr *ctlr) 163 165 { ··· 176 174 * struct fcoe_fcf - Fibre-Channel Forwarder 177 175 * @list: list linkage 178 176 * @event_work: Work for FC Transport actions queue 179 - * @event: The event to be processed 180 177 * @fip: The controller that the FCF was discovered on 181 178 * @fcf_dev: The associated fcoe_fcf_device instance 182 179 * @time: system time (jiffies) when an advertisement was last received ··· 189 188 * @flogi_sent: current FLOGI sent to this FCF 190 189 * @flags: flags received from advertisement 191 190 * @fka_period: keep-alive period, in jiffies 191 + * @fd_flags: no need for FKA from ENode 192 192 * 193 193 * A Fibre-Channel Forwarder (FCF) is the entity on the Ethernet that 194 194 * passes FCoE frames on to an FC fabric. This structure represents ··· 224 222 225 223 /** 226 224 * struct fcoe_rport - VN2VN remote port 225 + * @rdata: libfc remote port private data 227 226 * @time: time of create or last beacon packet received from node 228 227 * @fcoe_len: max FCoE frame size, not including VLAN or Ethernet headers 229 228 * @flags: flags from probe or claim ··· 269 266 void fcoe_ctlr_get_lesb(struct fcoe_ctlr_device *ctlr_dev); 270 267 271 268 /** 272 - * is_fip_mode() - returns true if FIP mode selected. 269 + * is_fip_mode() - test if FIP mode selected. 273 270 * @fip: FCoE controller. 271 + * 272 + * Returns: %true if FIP mode is selected 274 273 */ 275 274 static inline bool is_fip_mode(struct fcoe_ctlr *fip) 276 275 { ··· 323 318 * @kthread: The thread context (used by bnx2fc) 324 319 * @work: The work item (used by fcoe) 325 320 * @fcoe_rx_list: The queue of pending packets to process 326 - * @page: The memory page for calculating frame trailer CRCs 321 + * @crc_eof_page: The memory page for calculating frame trailer CRCs 327 322 * @crc_eof_offset: The offset into the CRC page pointing to available 328 323 * memory for a new trailer 324 + * @lock: local lock for members of this struct 329 325 */ 330 326 struct fcoe_percpu_s { 331 327 struct task_struct *kthread; ··· 349 343 * @timer: The queue timer 350 344 * @destroy_work: Handle for work context 351 345 * (to prevent RTNL deadlocks) 352 - * @data_srt_addr: Source address for data 346 + * @data_src_addr: Source address for data 347 + * @get_netdev: function that returns a &net_device from @lport 353 348 * 354 349 * An instance of this structure is to be allocated along with the 355 350 * Scsi_Host and libfc fc_lport structures. ··· 371 364 /** 372 365 * fcoe_get_netdev() - Return the net device associated with a local port 373 366 * @lport: The local port to get the net device from 367 + * 368 + * Returns: the &net_device associated with this @lport 374 369 */ 375 370 static inline struct net_device *fcoe_get_netdev(const struct fc_lport *lport) 376 371 { ··· 392 383 void fcoe_ctlr_set_fip_mode(struct fcoe_ctlr_device *); 393 384 394 385 /** 395 - * struct netdev_list 396 - * A mapping from netdevice to fcoe_transport 386 + * struct fcoe_netdev_mapping - A mapping from &net_device to &fcoe_transport 387 + * @list: list linkage of the mappings 388 + * @netdev: the &net_device 389 + * @ft: the fcoe_transport associated with @netdev 397 390 */ 398 391 struct fcoe_netdev_mapping { 399 392 struct list_head list;

+4 -3

include/scsi/scsi.h

··· 69 69 * @status: the status passed up from the driver (including host and 70 70 * driver components) 71 71 * 72 - * This returns true if the status code is SAM_STAT_CHECK_CONDITION. 72 + * Returns: %true if the status code is SAM_STAT_CHECK_CONDITION. 73 73 */ 74 74 static inline int scsi_status_is_check_condition(int status) 75 75 { ··· 189 189 /* Used to obtain the PCI location of a device */ 190 190 #define SCSI_IOCTL_GET_PCI 0x5387 191 191 192 - /** scsi_status_is_good - check the status return. 192 + /** 193 + * scsi_status_is_good - check the status return. 193 194 * 194 195 * @status: the status passed up from the driver (including host and 195 196 * driver components) 196 197 * 197 - * This returns true for known good conditions that may be treated as 198 + * Returns: %true for known good conditions that may be treated as 198 199 * command completed normally 199 200 */ 200 201 static inline bool scsi_status_is_good(int status)

+2

include/scsi/scsi_cmnd.h

··· 353 353 354 354 /** 355 355 * scsi_msg_to_host_byte() - translate message byte 356 + * @cmd: the SCSI command 357 + * @msg: the SCSI parallel message byte to translate 356 358 * 357 359 * Translate the SCSI parallel message byte to a matching 358 360 * host byte setting. A message of COMMAND_COMPLETE indicates

+2 -3

include/scsi/scsi_transport_fc.h

··· 770 770 /** 771 771 * fc_remote_port_chkready - called to validate the remote port state 772 772 * prior to initiating io to the port. 773 - * 774 - * Returns a scsi result code that can be returned by the LLDD. 775 - * 776 773 * @rport: remote port to be checked 774 + * 775 + * Returns: a scsi result code that can be returned by the LLDD. 777 776 **/ 778 777 static inline int 779 778 fc_remote_port_chkready(struct fc_rport *rport)

+2 -2

include/scsi/scsi_transport_srp.h

··· 74 74 }; 75 75 76 76 /** 77 - * struct srp_function_template 77 + * struct srp_function_template - template for SRP initiator drivers 78 78 * 79 79 * Fields that are only relevant for SRP initiator drivers: 80 80 * @has_rport_state: Whether or not to create the state, fast_io_fail_tmo and ··· 124 124 * srp_chkready() - evaluate the transport layer state before I/O 125 125 * @rport: SRP target port pointer. 126 126 * 127 - * Returns a SCSI result code that can be returned by the LLD queuecommand() 127 + * Returns: a SCSI result code that can be returned by the LLD queuecommand() 128 128 * implementation. The role of this function is similar to that of 129 129 * fc_remote_port_chkready(). 130 130 */

Configure Feed

Configure Feed