Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 75c65a5e authored by Douglas Gilbert's avatar Douglas Gilbert Committed by James Bottomley
Browse files

[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: default avatarDouglas Gilbert <dgilbert@interlog.com>
Signed-off-by: default avatarJames Bottomley <James.Bottomley@suse.de>
parent 4977c825

Documentation/scsi/scsi_mid_low_api.txt

+13 −1
Original line number Original line Diff line number Diff line
@@ -1343,7 +1343,7 @@ Members of interest: 
                   underruns (overruns should be rare). If possible an LLD

                   underruns (overruns should be rare). If possible an LLD

                   should set 'resid' prior to invoking 'done'. The most

                   should set 'resid' prior to invoking 'done'. The most

                   interesting case is data transfers from a SCSI target

                   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

    underflow    - LLD should place (DID_ERROR << 16) in 'result' if

                   actual number of bytes transferred is less than this

                   actual number of bytes transferred is less than this

                   figure. Not many LLDs implement this check and some that

                   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

                   report a DID_ERROR. Better for an LLD to implement

                   'resid'.

                   '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

The scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h