Commit 29687512c0b084957112cc2c0743ce34cd0d5055
1 parent
8816624222
Exists in
master
and in
7 other branches
[SCSI] fix up documentation for change in ->queuecommand to lockless calling
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>
Showing 1 changed file with 31 additions and 28 deletions Side-by-side Diff
Documentation/scsi/scsi_mid_low_api.txt
| ... | ... | @@ -1044,9 +1044,9 @@ |
| 1044 | 1044 | |
| 1045 | 1045 | |
| 1046 | 1046 | /** |
| 1047 | - * queuecommand - queue scsi command, invoke 'done' on completion | |
| 1047 | + * queuecommand - queue scsi command, invoke scp->scsi_done on completion | |
| 1048 | + * @shost: pointer to the scsi host object | |
| 1048 | 1049 | * @scp: pointer to scsi command object |
| 1049 | - * @done: function pointer to be invoked on completion | |
| 1050 | 1050 | * |
| 1051 | 1051 | * Returns 0 on success. |
| 1052 | 1052 | * |
| 1053 | 1053 | |
| 1054 | 1054 | |
| 1055 | 1055 | |
| 1056 | 1056 | |
| ... | ... | @@ -1074,42 +1074,45 @@ |
| 1074 | 1074 | * |
| 1075 | 1075 | * Other types of errors that are detected immediately may be |
| 1076 | 1076 | * flagged by setting scp->result to an appropriate value, |
| 1077 | - * invoking the 'done' callback, and then returning 0 from this | |
| 1078 | - * function. If the command is not performed immediately (and the | |
| 1079 | - * LLD is starting (or will start) the given command) then this | |
| 1080 | - * function should place 0 in scp->result and return 0. | |
| 1077 | + * invoking the scp->scsi_done callback, and then returning 0 | |
| 1078 | + * from this function. If the command is not performed | |
| 1079 | + * immediately (and the LLD is starting (or will start) the given | |
| 1080 | + * command) then this function should place 0 in scp->result and | |
| 1081 | + * return 0. | |
| 1081 | 1082 | * |
| 1082 | 1083 | * Command ownership. If the driver returns zero, it owns the |
| 1083 | - * command and must take responsibility for ensuring the 'done' | |
| 1084 | - * callback is executed. Note: the driver may call done before | |
| 1085 | - * returning zero, but after it has called done, it may not | |
| 1086 | - * return any value other than zero. If the driver makes a | |
| 1087 | - * non-zero return, it must not execute the command's done | |
| 1088 | - * callback at any time. | |
| 1084 | + * command and must take responsibility for ensuring the | |
| 1085 | + * scp->scsi_done callback is executed. Note: the driver may | |
| 1086 | + * call scp->scsi_done before returning zero, but after it has | |
| 1087 | + * called scp->scsi_done, it may not return any value other than | |
| 1088 | + * zero. If the driver makes a non-zero return, it must not | |
| 1089 | + * execute the command's scsi_done callback at any time. | |
| 1089 | 1090 | * |
| 1090 | - * Locks: struct Scsi_Host::host_lock held on entry (with "irqsave") | |
| 1091 | - * and is expected to be held on return. | |
| 1091 | + * Locks: up to and including 2.6.36, struct Scsi_Host::host_lock | |
| 1092 | + * held on entry (with "irqsave") and is expected to be | |
| 1093 | + * held on return. From 2.6.37 onwards, queuecommand is | |
| 1094 | + * called without any locks held. | |
| 1092 | 1095 | * |
| 1093 | 1096 | * Calling context: in interrupt (soft irq) or process context |
| 1094 | 1097 | * |
| 1095 | - * Notes: This function should be relatively fast. Normally it will | |
| 1096 | - * not wait for IO to complete. Hence the 'done' callback is invoked | |
| 1097 | - * (often directly from an interrupt service routine) some time after | |
| 1098 | - * this function has returned. In some cases (e.g. pseudo adapter | |
| 1099 | - * drivers that manufacture the response to a SCSI INQUIRY) | |
| 1100 | - * the 'done' callback may be invoked before this function returns. | |
| 1101 | - * If the 'done' callback is not invoked within a certain period | |
| 1102 | - * the SCSI mid level will commence error processing. | |
| 1103 | - * If a status of CHECK CONDITION is placed in "result" when the | |
| 1104 | - * 'done' callback is invoked, then the LLD driver should | |
| 1105 | - * perform autosense and fill in the struct scsi_cmnd::sense_buffer | |
| 1098 | + * Notes: This function should be relatively fast. Normally it | |
| 1099 | + * will not wait for IO to complete. Hence the scp->scsi_done | |
| 1100 | + * callback is invoked (often directly from an interrupt service | |
| 1101 | + * routine) some time after this function has returned. In some | |
| 1102 | + * cases (e.g. pseudo adapter drivers that manufacture the | |
| 1103 | + * response to a SCSI INQUIRY) the scp->scsi_done callback may be | |
| 1104 | + * invoked before this function returns. If the scp->scsi_done | |
| 1105 | + * callback is not invoked within a certain period the SCSI mid | |
| 1106 | + * level will commence error processing. If a status of CHECK | |
| 1107 | + * CONDITION is placed in "result" when the scp->scsi_done | |
| 1108 | + * callback is invoked, then the LLD driver should perform | |
| 1109 | + * autosense and fill in the struct scsi_cmnd::sense_buffer | |
| 1106 | 1110 | * array. The scsi_cmnd::sense_buffer array is zeroed prior to |
| 1107 | 1111 | * the mid level queuing a command to an LLD. |
| 1108 | 1112 | * |
| 1109 | 1113 | * Defined in: LLD |
| 1110 | 1114 | **/ |
| 1111 | - int queuecommand(struct scsi_cmnd * scp, | |
| 1112 | - void (*done)(struct scsi_cmnd *)) | |
| 1115 | + int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp) | |
| 1113 | 1116 | |
| 1114 | 1117 | |
| 1115 | 1118 | /** |