From 75c65a5edaa8b815c1428314eaf696788f1ebbdb Mon Sep 17 00:00:00 2001 From: Douglas Gilbert Date: Thu, 23 Dec 2010 21:40:37 -0500 Subject: [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 Signed-off-by: James Bottomley --- Documentation/scsi/scsi_mid_low_api.txt | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'Documentation/scsi/scsi_mid_low_api.txt') diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index df322c103466..5f17d29c59b5 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -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 -- cgit v1.2.3