lk/linux-kernel-test
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[SCSI] fix up documentation for change in ->queuecommand to lockless calling

Browse Source 
The current doc still says we call it with the host lock held, which is
going to cause confusion.

Signed-off-by: James Bottomley <James.Bottomley@suse.de>
This commit is contained in:
James Bottomley
2010-12-16 09:22:24 -05:00
parent 8816624222
commit 29687512c0
1 changed files with 30 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
Documentation/scsi/scsi_mid_low_api.txt
View File

@@ -1044,9 +1044,9 @@ Details:
/** /**
* queuecommand - queue scsi command, invoke 'done' on completion * queuecommand - queue scsi command, invoke scp->scsi_done on completion
* @shost: pointer to the scsi host object
* @scp: pointer to scsi command object * @scp: pointer to scsi command object
* @done: function pointer to be invoked on completion
* *
* Returns 0 on success. * Returns 0 on success.
* *
@@ -1074,42 +1074,45 @@ Details:
* *
* Other types of errors that are detected immediately may be * Other types of errors that are detected immediately may be
* flagged by setting scp->result to an appropriate value, * flagged by setting scp->result to an appropriate value,
* invoking the 'done' callback, and then returning 0 from this * invoking the scp->scsi_done callback, and then returning 0
* function. If the command is not performed immediately (and the * from this function. If the command is not performed
* LLD is starting (or will start) the given command) then this * immediately (and the LLD is starting (or will start) the given
* function should place 0 in scp->result and return 0. * command) then this function should place 0 in scp->result and
* return 0.
* *
* Command ownership. If the driver returns zero, it owns the * Command ownership. If the driver returns zero, it owns the
* command and must take responsibility for ensuring the 'done' * command and must take responsibility for ensuring the
* callback is executed. Note: the driver may call done before * scp->scsi_done callback is executed. Note: the driver may
* returning zero, but after it has called done, it may not * call scp->scsi_done before returning zero, but after it has
* return any value other than zero. If the driver makes a * called scp->scsi_done, it may not return any value other than
* non-zero return, it must not execute the command's done * zero. If the driver makes a non-zero return, it must not
* callback at any time. * execute the command's scsi_done callback at any time.
* *
* Locks: struct Scsi_Host::host_lock held on entry (with "irqsave") * Locks: up to and including 2.6.36, struct Scsi_Host::host_lock
* and is expected to be held on return. * held on entry (with "irqsave") and is expected to be
* held on return. From 2.6.37 onwards, queuecommand is
* called without any locks held.
* *
* Calling context: in interrupt (soft irq) or process context * Calling context: in interrupt (soft irq) or process context
* *
* Notes: This function should be relatively fast. Normally it will * Notes: This function should be relatively fast. Normally it
* not wait for IO to complete. Hence the 'done' callback is invoked * will not wait for IO to complete. Hence the scp->scsi_done
* (often directly from an interrupt service routine) some time after * callback is invoked (often directly from an interrupt service
* this function has returned. In some cases (e.g. pseudo adapter * routine) some time after this function has returned. In some
* drivers that manufacture the response to a SCSI INQUIRY) * cases (e.g. pseudo adapter drivers that manufacture the
* the 'done' callback may be invoked before this function returns. * response to a SCSI INQUIRY) the scp->scsi_done callback may be
* If the 'done' callback is not invoked within a certain period * invoked before this function returns. If the scp->scsi_done
* the SCSI mid level will commence error processing. * callback is not invoked within a certain period the SCSI mid
* If a status of CHECK CONDITION is placed in "result" when the * level will commence error processing. If a status of CHECK
* 'done' callback is invoked, then the LLD driver should * CONDITION is placed in "result" when the scp->scsi_done
* perform autosense and fill in the struct scsi_cmnd::sense_buffer * callback is invoked, then the LLD driver should perform
* autosense and fill in the struct scsi_cmnd::sense_buffer
* array. The scsi_cmnd::sense_buffer array is zeroed prior to * array. The scsi_cmnd::sense_buffer array is zeroed prior to
* the mid level queuing a command to an LLD. * the mid level queuing a command to an LLD.
* *
* Defined in: LLD * Defined in: LLD
**/ **/
int queuecommand(struct scsi_cmnd * scp, int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp)
void (*done)(struct scsi_cmnd *))
/** /**