[SCSI] scsi_mid_low_api.txt recommend resid usage

As discussed in a thread on this list titled:
    "RFC: short reads on block devices"
this patch adds recommendations for LLDs to set resid
when there might be uncertainty about how much data
has been returned by a device.

This patch inline and attached] is against scsi-misc-2.6.git

Signed-off-by: Douglas Gilbert <dgilbert@interlog.com>
Signed-off-by: James Bottomley <James.Bottomley@suse.de>
This commit is contained in:
Douglas Gilbert 2010-12-23 21:40:37 -05:00 committed by James Bottomley
parent 4977c82504
commit 75c65a5eda

View File

@ -1343,7 +1343,7 @@ Members of interest:
underruns (overruns should be rare). If possible an LLD
should set 'resid' prior to invoking 'done'. The most
interesting case is data transfers from a SCSI target
device device (i.e. READs) that underrun.
device (e.g. READs) that underrun.
underflow - LLD should place (DID_ERROR << 16) in 'result' if
actual number of bytes transferred is less than this
figure. Not many LLDs implement this check and some that
@ -1351,6 +1351,18 @@ Members of interest:
report a DID_ERROR. Better for an LLD to implement
'resid'.
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
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
been received. For example: to indicate that no valid data has been received
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:
scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
The scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h