11.5. Task Management Function Request
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| 0x02 |1| Function | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| Logical Unit Number (LUN) or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Referenced Task Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32| RefCmdSN or Reserved |
+---------------+---------------+---------------+---------------+
36| ExpDataSN or Reserved |
+---------------+---------------+---------------+---------------+
40/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
11.5.1. Function
The task management functions provide an initiator with a way to
explicitly control the execution of one or more tasks (SCSI and iSCSI
tasks). The task management function codes are listed below. For a
more detailed description of SCSI task management, see [SAM2].
1 ABORT TASK - aborts the task identified by the Referenced Task
Tag field.
2 ABORT TASK SET - aborts all tasks issued via this session on
the LU.
3 CLEAR ACA - clears the Auto Contingent Allegiance condition.
4 CLEAR TASK SET - aborts all tasks in the appropriate task set
as defined by the TST field in the Control mode page
(see [SPC3]).
5 LOGICAL UNIT RESET
6 TARGET WARM RESET
7 TARGET COLD RESET
8 TASK REASSIGN - reassigns connection allegiance for the task
identified by the Initiator Task Tag field to this connection,
thus resuming the iSCSI exchanges for the task.
Values 9-12 are assigned in [RFC7144]. All other possible values for
the Function field are unassigned.
For all these functions, the Task Management Function Response MUST
be returned as detailed in Section 11.6. All these functions apply
to the referenced tasks, regardless of whether they are proper SCSI
tasks or tagged iSCSI operations. Task management requests must act
on all the commands from the same session having a CmdSN lower than
the task management CmdSN. LOGICAL UNIT RESET, TARGET WARM RESET,
and TARGET COLD RESET may affect commands from other sessions or
commands from the same session, regardless of their CmdSN value.
If the task management request is marked for immediate delivery, it
must be considered immediately for execution, but the operations
involved (all or part of them) may be postponed to allow the target
to receive all relevant tasks. According to [SAM2], for all the
tasks covered by the task management response (i.e., with a CmdSN
lower than the task management command CmdSN), except for the task
management response to a TASK REASSIGN, additional responses MUST NOT
be delivered to the SCSI layer after the task management response.
The iSCSI initiator MAY deliver to the SCSI layer all responses
received before the task management response (i.e., it is a matter of
implementation if the SCSI responses that are received before the
task management response but after the task management request was
issued are delivered to the SCSI layer by the iSCSI layer in the
initiator). The iSCSI target MUST ensure that no responses for the
tasks covered by a task management function are delivered to the
iSCSI initiator after the task management response, except for a task
covered by a TASK REASSIGN.
For ABORT TASK SET and CLEAR TASK SET, the issuing initiator MUST
continue to respond to all valid Target Transfer Tags (received via
R2T, Text Response, NOP-In, or SCSI Data-In PDUs) related to the
affected task set, even after issuing the task management request.
The issuing initiator SHOULD, however, terminate (i.e., by setting
the F bit to 1) these response sequences as quickly as possible. The
target for its part MUST wait for responses on all affected Target
Transfer Tags before acting on either of these two task management
requests. If all or part of the response sequence is not received
(due to digest errors) for a valid TTT, the target MAY treat it as a
case of a within-command error recovery class (see Section 7.1.4.1)
if it is supporting ErrorRecoveryLevel >= 1 or, alternatively, may
drop the connection to complete the requested task set function.
If an ABORT TASK is issued for a task created by an immediate
command, then the RefCmdSN MUST be that of the task management
request itself (i.e., the CmdSN and RefCmdSN are equal); otherwise,
the RefCmdSN MUST be set to the CmdSN of the task to be aborted
(lower than the CmdSN).
If the connection is still active (i.e., it is not undergoing an
implicit or explicit logout), an ABORT TASK MUST be issued on the
same connection to which the task to be aborted is allegiant at the
time the task management request is issued. If the connection is
implicitly or explicitly logged out (i.e., no other request will be
issued on the failing connection and no other response will be
received on the failing connection), then an ABORT TASK function
request may be issued on another connection. This task management
request will then establish a new allegiance for the command to be
aborted as well as abort it (i.e., the task to be aborted will not
have to be retried or reassigned, and its status, if sent but not
acknowledged, will be resent followed by the task management
response).
At the target, an ABORT TASK function MUST NOT be executed on a task
management request; such a request MUST result in a task management
response of "Function rejected".
For the LOGICAL UNIT RESET function, the target MUST behave as
dictated by the Logical Unit Reset function in [SAM2].
The implementation of the TARGET WARM RESET function and the TARGET
COLD RESET function is OPTIONAL and, when implemented, should act as
described below. The TARGET WARM RESET is also subject to SCSI
access controls on the requesting initiator as defined in [SPC3].
When authorization fails at the target, the appropriate response as
described in Section 11.6.1 MUST be returned by the target. The
TARGET COLD RESET function is not subject to SCSI access controls,
but its execution privileges may be managed by iSCSI mechanisms such
as login authentication.
When executing the TARGET WARM RESET and TARGET COLD RESET functions,
the target cancels all pending operations on all LUs known by the
issuing initiator. Both functions are equivalent to the TARGET RESET
function specified by [SAM2]. They can affect many other initiators
logged in with the servicing SCSI target port.
Additionally, the target MUST treat the TARGET COLD RESET function as
a power-on event, thus terminating all of its TCP connections to all
initiators (all sessions are terminated). For this reason, the
service response (defined by [SAM2]) for this SCSI task management
function may not be reliably delivered to the issuing initiator port.
For the TASK REASSIGN function, the target should reassign the
connection allegiance to this new connection (and thus resume iSCSI
exchanges for the task). TASK REASSIGN MUST ONLY be received by the
target after the connection on which the command was previously
executing has been successfully logged out. The task management
response MUST be issued before the reassignment becomes effective.
For additional usage semantics, see Section 7.2.
At the target, a TASK REASSIGN function request MUST NOT be executed
to reassign the connection allegiance of a Task Management Function
Request, an active text negotiation task, or a Logout task; such a
request MUST result in a task management response of "Function
rejected".
TASK REASSIGN MUST be issued as an immediate command.
11.5.2. TotalAHSLength and DataSegmentLength
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0.
11.5.3. LUN
This field is required for functions that address a specific LU
(ABORT TASK, CLEAR TASK SET, ABORT TASK SET, CLEAR ACA, LOGICAL UNIT
RESET) and is reserved in all others.
11.5.4. Referenced Task Tag
This is the Initiator Task Tag of the task to be aborted for the
ABORT TASK function or reassigned for the TASK REASSIGN function.
For all the other functions, this field MUST be set to the reserved
value 0xffffffff.
11.5.5. RefCmdSN
If an ABORT TASK is issued for a task created by an immediate
command, then the RefCmdSN MUST be that of the task management
request itself (i.e., the CmdSN and RefCmdSN are equal).
For an ABORT TASK of a task created by a non-immediate command, the
RefCmdSN MUST be set to the CmdSN of the task identified by the
Referenced Task Tag field. Targets must use this field as described
in Section 11.6.1 when the task identified by the Referenced Task Tag
field is not with the target.
Otherwise, this field is reserved.
11.5.6. ExpDataSN
For recovery purposes, the iSCSI target and initiator maintain a data
acknowledgment reference number -- the first input DataSN number
unacknowledged by the initiator. When issuing a new command, this
number is set to 0. If the function is TASK REASSIGN, which
establishes a new connection allegiance for a previously issued read
or bidirectional command, the ExpDataSN will contain an updated data
acknowledgment reference number or the value 0; the latter indicates
that the data acknowledgment reference number is unchanged. The
initiator MUST discard any data PDUs from the previous execution that
it did not acknowledge, and the target MUST transmit all Data-In PDUs
(if any) starting with the data acknowledgment reference number. The
number of retransmitted PDUs may or may not be the same as the
original transmission, depending on if there was a change in
MaxRecvDataSegmentLength in the reassignment. The target MAY also
send no more Data-In PDUs if all data has been acknowledged.
The value of ExpDataSN MUST be 0 or higher than the DataSN of the
last acknowledged Data-In PDU, but not larger than DataSN + 1 of the
last Data-IN PDU sent by the target. Any other value MUST be ignored
by the target.
For other functions, this field is reserved.
11.6.1. Response
The target provides a response, which may take on the following
values:
0 - Function complete
1 - Task does not exist
2 - LUN does not exist
3 - Task still allegiant
4 - Task allegiance reassignment not supported
5 - Task management function not supported
6 - Function authorization failed
255 - Function rejected
In addition to the above values, the value 7 is defined by [RFC7144].
For a discussion on the usage of response codes 3 and 4, see
Section 7.2.2.
For the TARGET COLD RESET and TARGET WARM RESET functions, the target
cancels all pending operations across all LUs known to the issuing
initiator. For the TARGET COLD RESET function, the target MUST then
close all of its TCP connections to all initiators (terminates all
sessions).
The mapping of the response code into a SCSI service response code
value, if needed, is outside the scope of this document. However, in
symbolic terms, Response values 0 and 1 map to the SCSI service
response of FUNCTION COMPLETE. Response value 2 maps to the SCSI
service response of INCORRECT LOGICAL UNIT NUMBER. All other
Response values map to the SCSI service response of FUNCTION
REJECTED. If a Task Management Function Response PDU does not arrive
before the session is terminated, the SCSI service response is
SERVICE DELIVERY OR TARGET FAILURE.
The response to ABORT TASK SET and CLEAR TASK SET MUST only be issued
by the target after all of the commands affected have been received
by the target, the corresponding task management functions have been
executed by the SCSI target, and the delivery of all responses
delivered until the task management function completion has been
confirmed (acknowledged through the ExpStatSN) by the initiator on
all connections of this session. For the exact timeline of events,
refer to Sections 4.2.3.3 and 4.2.3.4.
For the ABORT TASK function,
a) if the Referenced Task Tag identifies a valid task leading to a
successful termination, then targets must return the "Function
complete" response.
b) if the Referenced Task Tag does not identify an existing task
but the CmdSN indicated by the RefCmdSN field in the Task
Management Function Request is within the valid CmdSN window
and less than the CmdSN of the Task Management Function Request
itself, then targets must consider the CmdSN as received and
return the "Function complete" response.
c) if the Referenced Task Tag does not identify an existing task
and the CmdSN indicated by the RefCmdSN field in the Task
Management Function Request is outside the valid CmdSN window,
then targets must return the "Task does not exist" response.
For response semantics on function types that can potentially impact
multiple active tasks on the target, see Section 4.2.3.
11.6.2. TotalAHSLength and DataSegmentLength
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0.
The SCSI Data-In PDU for read operations has the following format:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x25 |F|A|0 0 0|O|U|S| Reserved |Status or Rsvd |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| StatSN or Reserved |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| DataSN |
+---------------+---------------+---------------+---------------+
40| Buffer Offset |
+---------------+---------------+---------------+---------------+
44| Residual Count |
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+
Status can accompany the last Data-In PDU if the command did not end
with an exception (i.e., the status is "good status" -- GOOD,
CONDITION MET, or INTERMEDIATE-CONDITION MET). The presence of
status (and of a residual count) is signaled via the S flag bit.
Although targets MAY choose to send even non-exception status in
separate responses, initiators MUST support non-exception status in
Data-In PDUs.
11.7.1. F (Final) Bit
For outgoing data, this bit is 1 for the last PDU of unsolicited data
or the last PDU of a sequence that answers an R2T.
For incoming data, this bit is 1 for the last input (read) data PDU
of a sequence. Input can be split into several sequences, each
having its own F bit. Splitting the data stream into sequences does
not affect DataSN counting on Data-In PDUs. It MAY be used as a
"change direction" indication for bidirectional operations that need
such a change.
DataSegmentLength MUST NOT exceed MaxRecvDataSegmentLength for the
direction it is sent, and the total of all the DataSegmentLength of
all PDUs in a sequence MUST NOT exceed MaxBurstLength (or
FirstBurstLength for unsolicited data). However, the number of
individual PDUs in a sequence (or in total) may be higher than the
ratio of MaxBurstLength (or FirstBurstLength) to
MaxRecvDataSegmentLength (as PDUs may be limited in length by the
capabilities of the sender). Using a DataSegmentLength of 0 may
increase beyond what is reasonable for the number of PDUs and should
therefore be avoided.
For bidirectional operations, the F bit is 1 for both the end of the
input sequences and the end of the output sequences.
11.7.2. A (Acknowledge) Bit
For sessions with ErrorRecoveryLevel=1 or higher, the target sets
this bit to 1 to indicate that it requests a positive acknowledgment
from the initiator for the data received. The target should use the
A bit moderately; it MAY only set the A bit to 1 once every
MaxBurstLength bytes, or on the last Data-In PDU that concludes the
entire requested read data transfer for the task from the target's
perspective, and it MUST NOT do so more frequently. The target MUST
NOT set to 1 the A bit for sessions with ErrorRecoveryLevel=0. The
initiator MUST ignore the A bit set to 1 for sessions with
ErrorRecoveryLevel=0.
On receiving a Data-In PDU with the A bit set to 1 on a session with
ErrorRecoveryLevel greater than 0, if there are no holes in the read
data until that Data-In PDU, the initiator MUST issue a SNACK of type
DataACK, except when it is able to acknowledge the status for the
task immediately via the ExpStatSN on other outbound PDUs if the
status for the task is also received. In the latter case
(acknowledgment through the ExpStatSN), sending a SNACK of type
DataACK in response to the A bit is OPTIONAL, but if it is done, it
must not be sent after the status acknowledgment through the
ExpStatSN. If the initiator has detected holes in the read data
prior to that Data-In PDU, it MUST postpone issuing the SNACK of type
DataACK until the holes are filled. An initiator also MUST NOT
acknowledge the status for the task before those holes are filled. A
status acknowledgment for a task that generated the Data-In PDUs is
considered by the target as an implicit acknowledgment of the Data-In
PDUs if such an acknowledgment was requested by the target.
11.7.3. Flags (Byte 1)
The last SCSI data packet sent from a target to an initiator for a
SCSI command that completed successfully (with a status of GOOD,
CONDITION MET, INTERMEDIATE, or INTERMEDIATE-CONDITION MET) may also
optionally contain the Status for the data transfer. In this case,
Sense Data cannot be sent together with the Command Status. If the
command is completed with an error, then the response and sense data
MUST be sent in a SCSI Response PDU (i.e., MUST NOT be sent in a SCSI
data packet). For bidirectional commands, the status MUST be sent in
a SCSI Response PDU.
bit 2-4 - Reserved.
bit 5-6 - used the same as in a SCSI Response. These
bits are only valid when S is set to 1. For
details, see Section 11.4.1.
bit 7 S (status) - set to indicate that the Command Status field
contains status. If this bit is set to 1, the
F bit MUST also be set to 1.
The fields StatSN, Status, and Residual Count only have meaningful
content if the S bit is set to 1. The values for these fields are
defined in Section 11.4.
11.7.4. Target Transfer Tag and LUN
On outgoing data, the Target Transfer Tag is provided to the target
if the transfer is honoring an R2T. In this case, the Target
Transfer Tag field is a replica of the Target Transfer Tag provided
with the R2T.
On incoming data, the Target Transfer Tag and LUN MUST be provided by
the target if the A bit is set to 1; otherwise, they are reserved.
The Target Transfer Tag and LUN are copied by the initiator into the
SNACK of type DataACK that it issues as a result of receiving a SCSI
Data-In PDU with the A bit set to 1.
The Target Transfer Tag values are not specified by this protocol,
except that the value 0xffffffff is reserved and means that the
Target Transfer Tag is not supplied. If the Target Transfer Tag is
provided, then the LUN field MUST hold a valid value and be
consistent with whatever was specified with the command; otherwise,
the LUN field is reserved.
11.7.5. DataSN
For input (read) or bidirectional Data-In PDUs, the DataSN is the
input PDU number within the data transfer for the command identified
by the Initiator Task Tag.
R2T and Data-In PDUs, in the context of bidirectional commands, share
the numbering sequence (see Section 4.2.2.4).
For output (write) data PDUs, the DataSN is the Data-Out PDU number
within the current output sequence. Either the current output
sequence is identified by the Initiator Task Tag (for unsolicited
data) or it is a data sequence generated for one R2T (for data
solicited through R2T).
11.7.6. Buffer Offset
The Buffer Offset field contains the offset of this PDU payload data
within the complete data transfer. The sum of the buffer offset and
length should not exceed the expected transfer length for the
command.
The order of data PDUs within a sequence is determined by
DataPDUInOrder. When set to Yes, it means that PDUs have to be in
increasing buffer offset order and overlays are forbidden.
The ordering between sequences is determined by DataSequenceInOrder.
When set to Yes, it means that sequences have to be in increasing
buffer offset order and overlays are forbidden.
11.7.7. DataSegmentLength
This is the data payload length of a SCSI Data-In or SCSI Data-Out
PDU. The sending of 0-length data segments should be avoided, but
initiators and targets MUST be able to properly receive 0-length data
segments.
The data segments of Data-In and Data-Out PDUs SHOULD be filled to
the integer number of 4-byte words (real payload), unless the F bit
is set to 1.
11.8. Ready To Transfer (R2T)
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x31 |1| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| R2TSN |
+---------------+---------------+---------------+---------------+
40| Buffer Offset |
+---------------+---------------+---------------+---------------+
44| Desired Data Transfer Length |
+---------------------------------------------------------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
When an initiator has submitted a SCSI command with data that passes
from the initiator to the target (write), the target may specify
which blocks of data it is ready to receive. The target may request
that the data blocks be delivered in whichever order is convenient
for the target at that particular instant. This information is
passed from the target to the initiator in the Ready To Transfer
(R2T) PDU.
In order to allow write operations without an explicit initial R2T,
the initiator and target MUST have negotiated the key InitialR2T to
No during login.
An R2T MAY be answered with one or more SCSI Data-Out PDUs with a
matching Target Transfer Tag. If an R2T is answered with a single
Data-Out PDU, the buffer offset in the data PDU MUST be the same as
the one specified by the R2T, and the data length of the data PDU
MUST be the same as the Desired Data Transfer Length specified in the
R2T. If the R2T is answered with a sequence of data PDUs, the buffer
offset and length MUST be within the range of those specified by the
R2T, and the last PDU MUST have the F bit set to 1. If the last PDU
(marked with the F bit) is received before the Desired Data Transfer
Length is transferred, a target MAY choose to reject that PDU with
the "Protocol Error" reason code. DataPDUInOrder governs the
Data-Out PDU ordering. If DataPDUInOrder is set to Yes, the buffer
offsets and lengths for consecutive PDUs MUST form a continuous
non-overlapping range, and the PDUs MUST be sent in increasing offset
order.
The target may send several R2T PDUs. It therefore can have a number
of pending data transfers. The number of outstanding R2T PDUs is
limited by the value of the negotiated key MaxOutstandingR2T. Within
a task, outstanding R2Ts MUST be fulfilled by the initiator in the
order in which they were received.
R2T PDUs MAY also be used to recover Data-Out PDUs. Such an R2T
(Recovery-R2T) is generated by a target upon detecting the loss of
one or more Data-Out PDUs due to:
- Digest error
- Sequence error
- Sequence reception timeout
A Recovery-R2T carries the next unused R2TSN but requests part of or
the entire data burst that an earlier R2T (with a lower R2TSN) had
already requested.
DataSequenceInOrder governs the buffer offset ordering in consecutive
R2Ts. If DataSequenceInOrder is Yes, then consecutive R2Ts MUST
refer to continuous non-overlapping ranges, except for Recovery-R2Ts.
11.8.1. TotalAHSLength and DataSegmentLength
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0.
11.8.2. R2TSN
R2TSN is the R2T PDU input PDU number within the command identified
by the Initiator Task Tag.
For bidirectional commands, R2T and Data-In PDUs share the input PDU
numbering sequence (see Section 4.2.2.4).
11.8.3. StatSN
The StatSN field will contain the next StatSN. The StatSN for this
connection is not advanced after this PDU is sent.
11.8.4. Desired Data Transfer Length and Buffer Offset
The target specifies how many bytes it wants the initiator to send
because of this R2T PDU. The target may request the data from the
initiator in several chunks, not necessarily in the original order of
the data. The target therefore also specifies a buffer offset that
indicates the point at which the data transfer should begin, relative
to the beginning of the total data transfer. The Desired Data
Transfer Length MUST NOT be 0 and MUST NOT exceed MaxBurstLength.
11.8.5. Target Transfer Tag
The target assigns its own tag to each R2T request that it sends to
the initiator. This tag can be used by the target to easily identify
the data it receives. The Target Transfer Tag and LUN are copied in
the outgoing data PDUs and are only used by the target. There is no
protocol rule about the Target Transfer Tag except that the value
0xffffffff is reserved and MUST NOT be sent by a target in an R2T.
11.9. Asynchronous Message
An Asynchronous Message may be sent from the target to the initiator
without corresponding to a particular command. The target specifies
the reason for the event and sense data.
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x32 |1| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| 0xffffffff |
+---------------+---------------+---------------+---------------+
20| Reserved |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36| AsyncEvent | AsyncVCode | Parameter1 or Reserved |
+---------------+---------------+---------------+---------------+
40| Parameter2 or Reserved | Parameter3 or Reserved |
+---------------+---------------+---------------+---------------+
44| Reserved |
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment - Sense Data and iSCSI Event Data /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+
Some Asynchronous Messages are strictly related to iSCSI, while
others are related to SCSI [SAM2].
The StatSN counts this PDU as an acknowledgeable event (the StatSN is
advanced), which allows for initiator and target state
synchronization.
11.9.1. AsyncEvent
The codes used for iSCSI Asynchronous Messages (events) are:
0 (SCSI Async Event) - a SCSI asynchronous event is reported in
the sense data. Sense Data that accompanies the report, in
the data segment, identifies the condition. The sending of a
SCSI event ("asynchronous event reporting" in SCSI
terminology) is dependent on the target support for SCSI
asynchronous event reporting (see [SAM2]) as indicated in the
standard INQUIRY data (see [SPC3]). Its use may be enabled by
parameters in the SCSI Control mode page (see [SPC3]).
1 (Logout Request) - the target requests Logout. This Async
Message MUST be sent on the same connection as the one
requesting to be logged out. The initiator MUST honor this
request by issuing a Logout as early as possible but no later
than Parameter3 seconds. The initiator MUST send a Logout
with a reason code of "close the connection" OR "close the
session" to close all the connections. Once this message is
received, the initiator SHOULD NOT issue new iSCSI commands on
the connection to be logged out. The target MAY reject any
new I/O requests that it receives after this message with the
reason code "Waiting for Logout". If the initiator does not
log out in Parameter3 seconds, the target should send an Async
PDU with iSCSI event code "Dropped the connection" if possible
or simply terminate the transport connection. Parameter1 and
Parameter2 are reserved.
2 (Connection Drop Notification) - the target indicates that it
will drop the connection.
The Parameter1 field indicates the CID of the connection that
is going to be dropped.
The Parameter2 field (Time2Wait) indicates, in seconds, the
minimum time to wait before attempting to reconnect or
reassign.
The Parameter3 field (Time2Retain) indicates the maximum time
allowed to reassign commands after the initial wait (in
Parameter2).
If the initiator does not attempt to reconnect and/or reassign
the outstanding commands within the time specified by
Parameter3, or if Parameter3 is 0, the target will terminate
all outstanding commands on this connection. In this case, no
other responses should be expected from the target for the
outstanding commands on this connection.
A value of 0 for Parameter2 indicates that reconnect can be
attempted immediately.
3 (Session Drop Notification) - the target indicates that it
will drop all the connections of this session.
The Parameter1 field is reserved.
The Parameter2 field (Time2Wait) indicates, in seconds, the
minimum time to wait before attempting to reconnect.
The Parameter3 field (Time2Retain) indicates the maximum time
allowed to reassign commands after the initial wait (in
Parameter2).
If the initiator does not attempt to reconnect and/or reassign
the outstanding commands within the time specified by
Parameter3, or if Parameter3 is 0, the session is terminated.
In this case, the target will terminate all outstanding
commands in this session; no other responses should be
expected from the target for the outstanding commands in this
session. A value of 0 for Parameter2 indicates that reconnect
can be attempted immediately.
4 (Negotiation Request) - the target requests parameter
negotiation on this connection. The initiator MUST honor this
request by issuing a Text Request (that can be empty) on the
same connection as early as possible, but no later than
Parameter3 seconds, unless a Text Request is already pending
on the connection, or by issuing a Logout Request. If the
initiator does not issue a Text Request, the target may
reissue the Asynchronous Message requesting parameter
negotiation.
5 (Task Termination) - all active tasks for a LU with a matching
LUN field in the Async Message PDU are being terminated. The
receiving initiator iSCSI layer MUST respond to this message
by taking the following steps, in order:
- Stop Data-Out transfers on that connection for all active
TTTs for the affected LUN quoted in the Async Message PDU.
- Acknowledge the StatSN of the Async Message PDU via a
NOP-Out PDU with ITT=0xffffffff (i.e., non-ping flavor),
while copying the LUN field from the Async Message to
NOP-Out.
This value of AsyncEvent, however, MUST NOT be used on an
iSCSI session unless the new TaskReporting text key defined in
Section 13.23 was negotiated to FastAbort on the session.
248-255 (Vendor-unique) - vendor-specific iSCSI event. The
AsyncVCode details the vendor code, and data MAY accompany the
report.
All other event codes are unassigned.
11.9.2. AsyncVCode
AsyncVCode is a vendor-specific detail code that is only valid if the
AsyncEvent field indicates a vendor-specific event. Otherwise, it is
reserved.
11.9.3. LUN
The LUN field MUST be valid if AsyncEvent is 0. Otherwise, this
field is reserved.
11.9.4. Sense Data and iSCSI Event Data
For a SCSI event, this data accompanies the report in the data
segment and identifies the condition.
For an iSCSI event, additional vendor-unique data MAY accompany the
Async event. Initiators MAY ignore the data when not understood,
while processing the rest of the PDU.
If the DataSegmentLength is not 0, the format of the DataSegment is
as follows:
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|SenseLength | Sense Data |
+---------------+---------------+---------------+---------------+
x/ Sense Data /
+---------------+---------------+---------------+---------------+
y/ iSCSI Event Data /
/ /
+---------------+---------------+---------------+---------------+
z|
11.9.4.1. SenseLength
This is the length of Sense Data. When the Sense Data field is empty
(e.g., the event is not a SCSI event), SenseLength is 0.
11.10. Text Request
The Text Request is provided to allow for the exchange of information
and for future extensions. It permits the initiator to inform a
target of its capabilities or request some special operations.
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| 0x04 |F|C| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment (Text) /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+
An initiator MUST NOT have more than one outstanding Text Request on
a connection at any given time.
On a connection failure, an initiator must either explicitly abort
any active allegiant text negotiation task or cause such a task to be
implicitly terminated by the target.
11.10.1. F (Final) Bit
When set to 1, this bit indicates that this is the last or only Text
Request in a sequence of Text Requests; otherwise, it indicates that
more Text Requests will follow.
11.10.2. C (Continue) Bit
When set to 1, this bit indicates that the text (set of key=value
pairs) in this Text Request is not complete (it will be continued on
subsequent Text Requests); otherwise, it indicates that this Text
Request ends a set of key=value pairs. A Text Request with the C bit
set to 1 MUST have the F bit set to 0.
11.10.3. Initiator Task Tag
This is the initiator-assigned identifier for this Text Request. If
the command is sent as part of a sequence of Text Requests and
responses, the Initiator Task Tag MUST be the same for all the
requests within the sequence (similar to linked SCSI commands). The
I bit for all requests in a sequence also MUST be the same.
11.10.4. Target Transfer Tag
When the Target Transfer Tag is set to the reserved value 0xffffffff,
it tells the target that this is a new request, and the target resets
any internal state associated with the Initiator Task Tag (resets the
current negotiation state).
The target sets the Target Transfer Tag in a Text Response to a value
other than the reserved value 0xffffffff whenever it indicates that
it has more data to send or more operations to perform that are
associated with the specified Initiator Task Tag. It MUST do so
whenever it sets the F bit to 0 in the response. By copying the
Target Transfer Tag from the response to the next Text Request, the
initiator tells the target to continue the operation for the specific
Initiator Task Tag. The initiator MUST ignore the Target Transfer
Tag in the Text Response when the F bit is set to 1.
This mechanism allows the initiator and target to transfer a large
amount of textual data over a sequence of text-command/text-response
exchanges or to perform extended negotiation sequences.
If the Target Transfer Tag is not 0xffffffff, the LUN field MUST be
sent by the target in the Text Response.
A target MAY reset its internal negotiation state if an exchange is
stalled by the initiator for a long time or if it is running out of
resources.
Long Text Responses are handled as shown in the following example:
I->T Text SendTargets=All (F = 1, TTT = 0xffffffff)
T->I Text <part 1> (F = 0, TTT = 0x12345678)
I->T Text <empty> (F = 1, TTT = 0x12345678)
T->I Text <part 2> (F = 0, TTT = 0x12345678)
I->T Text <empty> (F = 1, TTT = 0x12345678)
...
T->I Text <part n> (F = 1, TTT = 0xffffffff)
11.10.5. Text
The data lengths of a Text Request MUST NOT exceed the iSCSI target
MaxRecvDataSegmentLength (a parameter that is negotiated per
connection and per direction). The text format is specified in
Section 6.2.
Sections 12 and 13 list some basic Text key=value pairs, some of
which can be used in Login Requests/Responses and some in Text
Requests/Responses.
A key=value pair can span Text Request or Text Response boundaries.
A key=value pair can start in one PDU and continue on the next. In
other words, the end of a PDU does not necessarily signal the end of
a key=value pair.
The target responds by sending its response back to the initiator.
The response text format is similar to the request text format. The
Text Response MAY refer to key=value pairs presented in an earlier
Text Request, and the text in the request may refer to earlier
responses.
Section 6.2 details the rules for the Text Requests and Responses.
Text operations are usually meant for parameter setting/negotiations
but can also be used to perform some long-lasting operations.
Text operations that take a long time should be placed in their own
Text Request.
11.11. Text Response
The Text Response PDU contains the target's responses to the
initiator's Text Request. The format of the Text field matches that
of the Text Request.
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|.| 0x24 |F|C| Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| LUN or Reserved |
+ +
12| |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| Target Transfer Tag or 0xffffffff |
+---------------+---------------+---------------+---------------+
24| StatSN |
+---------------+---------------+---------------+---------------+
28| ExpCmdSN |
+---------------+---------------+---------------+---------------+
32| MaxCmdSN |
+---------------+---------------+---------------+---------------+
36/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
/ DataSegment (Text) /
+/ /
+---------------+---------------+---------------+---------------+
| Data-Digest (optional) |
+---------------+---------------+---------------+---------------+
11.11.1. F (Final) Bit
When set to 1, in response to a Text Request with the Final bit set
to 1, the F bit indicates that the target has finished the whole
operation. Otherwise, if set to 0 in response to a Text Request with
the Final Bit set to 1, it indicates that the target has more work to
do (invites a follow-on Text Request). A Text Response with the
F bit set to 1 in response to a Text Request with the F bit set to 0
is a protocol error.
A Text Response with the F bit set to 1 MUST NOT contain key=value
pairs that may require additional answers from the initiator.
A Text Response with the F bit set to 1 MUST have a Target Transfer
Tag field set to the reserved value 0xffffffff.
A Text Response with the F bit set to 0 MUST have a Target Transfer
Tag field set to a value other than the reserved value 0xffffffff.
11.11.2. C (Continue) Bit
When set to 1, this bit indicates that the text (set of key=value
pairs) in this Text Response is not complete (it will be continued on
subsequent Text Responses); otherwise, it indicates that this Text
Response ends a set of key=value pairs. A Text Response with the
C bit set to 1 MUST have the F bit set to 0.
11.11.3. Initiator Task Tag
The Initiator Task Tag matches the tag used in the initial Text
Request.
11.11.4. Target Transfer Tag
When a target has more work to do (e.g., cannot transfer all the
remaining text data in a single Text Response or has to continue the
negotiation) and has enough resources to proceed, it MUST set the
Target Transfer Tag to a value other than the reserved value
0xffffffff. Otherwise, the Target Transfer Tag MUST be set to
0xffffffff.
When the Target Transfer Tag is not 0xffffffff, the LUN field may be
significant.
The initiator MUST copy the Target Transfer Tag and LUN in its next
request to indicate that it wants the rest of the data.
When the target receives a Text Request with the Target Transfer Tag
set to the reserved value 0xffffffff, it resets its internal
information (resets state) associated with the given Initiator Task
Tag (restarts the negotiation).
When a target cannot finish the operation in a single Text Response
and does not have enough resources to continue, it rejects the Text
Request with the appropriate Reject code.
A target may reset its internal state associated with an Initiator
Task Tag (the current negotiation state) as expressed through the
Target Transfer Tag if the initiator fails to continue the exchange
for some time. The target may reject subsequent Text Requests with
the Target Transfer Tag set to the "stale" value.
11.11.5. StatSN
The target StatSN variable is advanced by each Text Response sent.
11.11.6. Text Response Data
The data lengths of a Text Response MUST NOT exceed the iSCSI
initiator MaxRecvDataSegmentLength (a parameter that is negotiated
per connection and per direction).
The text in the Text Response Data is governed by the same rules as
the text in the Text Request Data (see Section 11.11.2).
Although the initiator is the requesting party and controls the
request-response initiation and termination, the target can offer
key=value pairs of its own as part of a sequence and not only in
response to the initiator.
11.12. Login Request
After establishing a TCP connection between an initiator and a
target, the initiator MUST start a Login Phase to gain further access
to the target's resources.
The Login Phase (see Section 6.3) consists of a sequence of Login
Requests and Login Responses that carry the same Initiator Task Tag.
Login Requests are always considered as immediate.
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|1| 0x03 |T|C|.|.|CSG|NSG| Version-max | Version-min |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------+---------------+---------------+---------------+
8| ISID |
+ +---------------+---------------+
12| | TSIH |
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| CID | Reserved |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN or Reserved |
+---------------+---------------+---------------+---------------+
32| Reserved |
+---------------+---------------+---------------+---------------+
36| Reserved |
+---------------+---------------+---------------+---------------+
40/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48/ DataSegment - Login Parameters in Text Request Format /
+/ /
+---------------+---------------+---------------+---------------+
11.12.1. T (Transit) Bit
When set to 1, this bit indicates that the initiator is ready to
transit to the next stage.
If the T bit is set to 1 and the NSG is set to FullFeaturePhase, then
this also indicates that the initiator is ready for the Login
Final-Response (see Section 6.3).
11.12.2. C (Continue) Bit
When set to 1, this bit indicates that the text (set of key=value
pairs) in this Login Request is not complete (it will be continued on
subsequent Login Requests); otherwise, it indicates that this Login
Request ends a set of key=value pairs. A Login Request with the
C bit set to 1 MUST have the T bit set to 0.
11.12.3. CSG and NSG
Through these fields -- Current Stage (CSG) and Next Stage (NSG) --
the Login negotiation requests and responses are associated with a
specific stage in the session (SecurityNegotiation,
LoginOperationalNegotiation, FullFeaturePhase) and may indicate the
next stage to which they want to move (see Section 6.3). The Next
Stage value is only valid when the T bit is 1; otherwise, it is
reserved.
The stage codes are:
0 - SecurityNegotiation
1 - LoginOperationalNegotiation
3 - FullFeaturePhase
All other codes are reserved.
11.12.4. Version
The version number for this document is 0x00. Therefore, both
Version-min and Version-max MUST be set to 0x00.
11.12.4.1. Version-max
Version-max indicates the maximum version number supported.
All Login Requests within the Login Phase MUST carry the same
Version-max.
The target MUST use the value presented with the first Login Request.
11.12.4.2. Version-min
All Login Requests within the Login Phase MUST carry the same
Version-min. The target MUST use the value presented with the first
Login Request.
