system/linux
system/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux synced 2024-10-04 18:33:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse source 
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>
This commit is contained in:
Martin K. Petersen 2024-04-08 22:16:25 -04:00
parent eab302e89f a2530eb748
commit a0c25d66b1
8 changed files with 46 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
Documentation/driver-api/scsi.rst
View file

@ -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 <http://www.t10.org/scsi-3.htm>`__ is a big-endian
The `SCSI protocol <https://www.t10.org/scsi-3.htm>`__ 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 <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP
(`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel
TCP/IP (`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel
ports <http://cyberelk.net/tim/parport/parscsi.html>`__.
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 <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for
more details.
transports. See `the original patch submission
<https://lore.kernel.org/linux-scsi/1155070439.6275.5.camel@localhost.localdomain/>`__
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...

20
Documentation/scsi/scsi_mid_low_api.rst
View file

@ -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.

2
include/scsi/iser.h
View file

@ -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 {

25
include/scsi/libfcoe.h
View file

@ -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;

7
include/scsi/scsi.h
View file

@ -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)

2
include/scsi/scsi_cmnd.h
View file

@ -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

5
include/scsi/scsi_transport_fc.h
View file

@ -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)

4
include/scsi/scsi_transport_srp.h
View file

@ -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().
*/