niansa-misc/linux
1
0
Fork 0
mirror of synced 2025-03-06 20:59:54 +01:00
Code Issues Projects Releases Packages Wiki Activity

scsi: documentation: Corrections for struct updates

Browse source 
Update scsi_mid_low_api.rst for changes to struct scsi_host and
struct scsi_cmnd.

struct scsi_host:

 - no_async_abort is gone

 - drop sh_list w/ no replacement

 - change my_devices to __devices

struct scsi_cmnd:

 - removed 'done' (now in struct scsi_driver); use scsi_done() or
   scsi_done_direct() callbacks

 - change previous request_bufflen to scsi_bufflen()

 - change previous use_sg field to scsi_dma_map() or scsi_sg_count()

 - change previous request_buffer field to reference to 'usg_sg' text

[mkp: removed more obsolete stuff]

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20241221212539.1314560-1-rdunlap@infradead.org
Cc: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
Cc: Martin K. Petersen <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>
This commit is contained in:
Randy Dunlap 2024-12-21 13:25:39 -08:00 • committed by Martin K. Petersen
parent defb7541da
commit d102c6d589
1 changed files with 18 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
Documentation/scsi/scsi_mid_low_api.rst
View file

@ -683,11 +683,7 @@ Details::
*
* Calling context: kernel thread
*
* Notes: If 'no_async_abort' is defined this callback
* will be invoked from scsi_eh thread. No other commands
* will then be queued on current host during eh.
* Otherwise it will be called whenever scsi_timeout()
* is called due to a command timeout.
* Notes: This is called only for a command that has timed out.
*
* Optionally defined in: LLD
**/
@ -990,7 +986,7 @@ struct scsi_host_template
There is one "struct scsi_host_template" instance per LLD [#]_. It is
typically initialized as a file scope static in a driver's header file. That
way members that are not explicitly initialized will be set to 0 or NULL.
Member of interest:
Members of interest:
name
- name of driver (may contain spaces, please limit to
@ -1006,6 +1002,13 @@ Member of interest:
- primary callback that the mid level uses to inject
SCSI commands into an LLD.
vendor_id
- a unique value that identifies the vendor supplying
the LLD for the Scsi_Host. Used most often in validating
vendor-specific message requests. Value consists of an
identifier type and a vendor-specific value.
See scsi_netlink.h for a description of valid formats.
The structure is defined and commented in include/scsi/scsi_host.h
.. [#] In extreme situations a single driver may have several instances
@ -1046,9 +1049,6 @@ of interest:
- maximum number of commands that can be queued on devices
controlled by the host. Overridden by LLD calls to
scsi_change_queue_depth().
no_async_abort
- 1=>Asynchronous aborts are not supported
- 0=>Timed-out commands will be aborted asynchronously
hostt
- pointer to driver's struct scsi_host_template from which
this struct Scsi_Host instance was spawned
@ -1057,22 +1057,10 @@ of interest:
transportt
- pointer to driver's struct scsi_transport_template instance
(if any). FC and SPI transports currently supported.
sh_list
- a double linked list of pointers to all struct Scsi_Host
instances (currently ordered by ascending host_no)
my_devices
- a double linked list of pointers to struct scsi_device
instances that belong to this host.
hostdata[0]
- area reserved for LLD at end of struct Scsi_Host. Size
is set by the second argument (named 'xtr_bytes') to
is set by the second argument (named 'privsize') to
scsi_host_alloc().
vendor_id
- a unique value that identifies the vendor supplying
the LLD for the Scsi_Host. Used most often in validating
vendor-specific message requests. Value consists of an
identifier type and a vendor-specific value.
See scsi_netlink.h for a description of valid formats.
The scsi_host structure is defined in include/scsi/scsi_host.h
@ -1094,30 +1082,11 @@ Members of interest:
cmnd
- array containing SCSI command
cmnd_len
cmd_len
- length (in bytes) of SCSI command
sc_data_direction
- direction of data transfer in data phase. See
"enum dma_data_direction" in include/linux/dma-mapping.h
request_bufflen
- number of data bytes to transfer (0 if no data phase)
use_sg
- ==0 -> no scatter gather list, hence transfer data
to/from request_buffer
- >0 -> scatter gather list (actually an array) in
request_buffer with use_sg elements
request_buffer
- either contains data buffer or scatter gather list
depending on the setting of use_sg. Scatter gather
elements are defined by 'struct scatterlist' found
in include/linux/scatterlist.h .
done
- function pointer that should be invoked by LLD when the
SCSI command is completed (successfully or otherwise).
Should only be called by an LLD if the LLD has accepted
the command (i.e. queuecommand() returned or will return
0). The LLD may invoke 'done' prior to queuecommand()
finishing.
result
- should be set by LLD prior to calling 'done'. A value
of 0 implies a successfully completed command (and all
@ -1140,13 +1109,13 @@ Members of interest:
device
- pointer to scsi_device object that this command is
associated with.
resid
resid_len (access by calling scsi_set_resid() / scsi_get_resid())
- an LLD should set this unsigned integer to the requested
transfer length (i.e. 'request_bufflen') less the number
of bytes that are actually transferred. 'resid' is
of bytes that are actually transferred. 'resid_len' is
preset to 0 so an LLD can ignore it if it cannot detect
underruns (overruns should not be reported). An LLD
should set 'resid' prior to invoking 'done'. The most
should set 'resid_len' prior to invoking 'done'. The most
interesting case is data transfers from a SCSI target
device (e.g. READs) that underrun.
underflow
@ -1155,10 +1124,10 @@ Members of interest:
figure. Not many LLDs implement this check and some that
do just output an error message to the log rather than
report a DID_ERROR. Better for an LLD to implement
'resid'.
'resid_len'.
It is recommended that a LLD set 'resid' on data transfers from a SCSI
target device (e.g. READs). It is especially important that 'resid' is set
It is recommended that a LLD set 'resid_len' on data transfers from a SCSI
target device (e.g. READs). It is especially important that 'resid_len' is set
when such data transfers have sense keys of MEDIUM ERROR and HARDWARE ERROR
(and possibly RECOVERED ERROR). In these cases if a LLD is in doubt how much
data has been received then the safest approach is to indicate no bytes have
@ -1168,7 +1137,7 @@ a LLD might use these helpers::
scsi_set_resid(SCpnt, scsi_bufflen(SCpnt));
where 'SCpnt' is a pointer to a scsi_cmnd object. To indicate only three 512
bytes blocks has been received 'resid' could be set like this::
bytes blocks have been received 'resid_len' could be set like this::
scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));