org.jscsi.parser.tmf

Class TaskManagementFunctionRequestParser

java.lang.Object

org.jscsi.parser.AbstractMessageParser

org.jscsi.parser.InitiatorMessageParser

org.jscsi.parser.tmf.TaskManagementFunctionRequestParser

public final class TaskManagementFunctionRequestParser
extends InitiatorMessageParser

TaskManagementFunctionRequestParser

This class parses a Task Management Function Request message defined in the iSCSI Standard (RFC3720).

TotalAHSLength and DataSegmentLength

For this PDU TotalAHSLength and DataSegmentLength MUST be 0.

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.

Author:

Volker Wildi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TaskManagementFunctionRequestParser.FunctionCode This enumeration defines all valid function codes, which are defined in the iSCSI standard (RFC3720).

Field Summary

Fields inherited from class org.jscsi.parser.InitiatorMessageParser

commandSequenceNumber, expectedStatusSequenceNumber

Fields inherited from class org.jscsi.parser.AbstractMessageParser

logicalUnitNumber, protocolDataUnit

Constructor Summary

Constructors

Constructor and Description
TaskManagementFunctionRequestParser(ProtocolDataUnit initProtocolDataUnit) Default constructor, creates a new, empty TaskManagementFunctionRequestParser object.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	checkIntegrity() This method checks, if all parsed fields are valid.
void	clear() This method sets all settings to their initial values.
protected void	deserializeBytes1to3(int line) Parse the bytes 1 till 3 in the Basic Header Segment.
protected void	deserializeBytes20to23(int line) Parse the bytes 20 till 23 in the Basic Header Segment.
protected void	deserializeBytes32to35(int line) Parse the bytes 32 till 35 in the Basic Header Segment.
protected void	deserializeBytes36to39(int line) Parse the bytes 36 till 39 in the Basic Header Segment.
DataSegmentFactory.DataSegmentFormat	getDataSegmentFormat() If this method returns true, hen it indicates that the data segment data is interpreted as binary data.
int	getExpDataSN() For recovery purposes, the iSCSI target and initiator maintain a data acknowledgement reference number - the first input DataSN number unacknowledged by the initiator.
TaskManagementFunctionRequestParser.FunctionCode	getFunction() The Task Management functions provide an initiator with a way to explicitly control the execution of one or more Tasks (SCSI and iSCSI tasks).
int	getRefCmdSN() If an ABORT TASK is issued for a task created by an immediate command then RefCmdSN MUST be that of the Task Management request itself (i.e., CmdSN and RefCmdSN are equal).
int	getReferencedTaskTag() The Initiator Task Tag of the task to be aborted for the ABORT TASK function or reassigned for the TASK REASSIGN function.
protected int	serializeBytes1to3() Serializes the bytes 1 till 3 in the Basic Header Segment.
protected int	serializeBytes20to23() Serializes the bytes 20 till 23 in the Basic Header Segment.
protected int	serializeBytes32to35() Serializes the bytes 32 till 35 in the Basic Header Segment.
protected int	serializeBytes36to39() Serializes the bytes 36 till 39 in the Basic Header Segment.
String	toString() This method concatenate all the fields of a derived parser to allow an easy generation of debug informations.

Methods inherited from class org.jscsi.parser.InitiatorMessageParser

deserializeBytes24to27, deserializeBytes28to31, deserializeBytes40to43, deserializeBytes44to47, getCommandSequenceNumber, getExpectedStatusSequenceNumber, getShortInfo, incrementSequenceNumber, serializeBytes24to27, serializeBytes28to31, serializeBytes40to43, serializeBytes44to47, setCommandSequenceNumber, setExpectedStatusSequenceNumber

Methods inherited from class org.jscsi.parser.AbstractMessageParser

canContainAdditionalHeaderSegments, canHaveDigests, deserializeBytes12to15, deserializeBytes8to11, getLogicalUnitNumber, serializeBytes12to15, serializeBytes8to11, setLogicalUnitNumber

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TaskManagementFunctionRequestParser

public TaskManagementFunctionRequestParser(ProtocolDataUnit initProtocolDataUnit)

Default constructor, creates a new, empty TaskManagementFunctionRequestParser object.

Parameters:

initProtocolDataUnit - The reference ProtocolDataUnit instance, which contains this TaskManagementFunctionRequestParser subclass object.

Method Detail

toString

public final String toString()

This method concatenate all the fields of a derived parser to allow an easy generation of debug informations.

Overrides:

toString in class InitiatorMessageParser

Returns:

The debug formatted string.

getDataSegmentFormat

public final DataSegmentFactory.DataSegmentFormat getDataSegmentFormat()

If this method returns true, hen it indicates that the data segment data is interpreted as binary data. Else the data segment data must be interpreted as Text Format.

Specified by:

getDataSegmentFormat in class AbstractMessageParser

Returns:

Returns a format defined by the DataSegmentFormat enumeration.

See Also:

DataSegmentFactory.DataSegmentFormat

clear

public final void clear()

This method sets all settings to their initial values.

Overrides:

clear in class InitiatorMessageParser

getExpDataSN

public final int getExpDataSN()

For recovery purposes, the iSCSI target and initiator maintain a data acknowledgement 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, ExpDataSN will contain an updated data acknowledgement reference number or the value 0; the latter indicating that the data acknowledgement 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 acknowledgement 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.

Returns:

The expected data sequence number of this TaskManagementFunctionRequestParser object.

getFunction

public final TaskManagementFunctionRequestParser.FunctionCode getFunction()

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].

Function Code	Description
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 logical unit.
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 Referenced Task Tag field to this connection, thus resuming the iSCSI exchanges for the task.

For all these functions, the Task Management function response MUST be returned as detailed in Section 10.6 Task Management Function Response. 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 with CmdSN equal or exceeding CmdSN.

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 CmdSN lower than the task management command CmdSN) but except 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, 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 on its part MUST wait for responses on all affected target transfer tags before acting on either of these two task management requests. In case 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 within-command error recovery class (see Section 6.1.4.1 Recovery Within-command) 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 RefCmdSN MUST be that of the Task Management request itself (i.e., CmdSN and RefCmdSN are equal); otherwise RefCmdSN MUST be set to the CmdSN of the task to be aborted (lower than CmdSN).

If the connection is still active (it is not undergoing an implicit or explicit logout), 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 issued but not acknowledged, will be reissued 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 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 10.6 Task Management Function Response 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 Logical Units 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.

The target MUST treat the TARGET COLD RESET function additionally 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 6.2 Retry and Reassign in Recovery.

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 Task Management response of "Function rejected".

TASK REASSIGN MUST be issued as an immediate command.

Returns:

The function code of this TaskManagementFunctionRequestParser object.

getRefCmdSN

public final int getRefCmdSN()

If an ABORT TASK is issued for a task created by an immediate command then RefCmdSN MUST be that of the Task Management request itself (i.e., CmdSN and RefCmdSN are equal).

For an ABORT TASK of a task created by non-immediate command 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 10.6.1 when the task identified by the Referenced Task Tag field is not with the target.

Otherwise, this field is reserved.

Returns:

The referenced command sequence number of this TaskManagementFunctionRequestParser object.

getReferencedTaskTag

public final int getReferencedTaskTag()

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.

Returns:

The referenced task tag of this TaskManagementFunctionRequestParser object.

deserializeBytes1to3

protected final void deserializeBytes1to3(int line)
                                   throws InternetSCSIException

Parse the bytes 1 till 3 in the Basic Header Segment.

Overrides:

deserializeBytes1to3 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

deserializeBytes20to23

protected final void deserializeBytes20to23(int line)
                                     throws InternetSCSIException

Parse the bytes 20 till 23 in the Basic Header Segment.

Overrides:

deserializeBytes20to23 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

deserializeBytes32to35

protected final void deserializeBytes32to35(int line)
                                     throws InternetSCSIException

Parse the bytes 32 till 35 in the Basic Header Segment.

Overrides:

deserializeBytes32to35 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

deserializeBytes36to39

protected final void deserializeBytes36to39(int line)
                                     throws InternetSCSIException

Parse the bytes 36 till 39 in the Basic Header Segment.

Overrides:

deserializeBytes36to39 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

checkIntegrity

protected final void checkIntegrity()
                             throws InternetSCSIException

This method checks, if all parsed fields are valid. Because there are several fields, which are reserved for future versions, and these must be zero. Is this the case an exception will be thrown.

Specified by:

checkIntegrity in class AbstractMessageParser

Throws:

InternetSCSIException - If the integrity is violated.

serializeBytes1to3

protected final int serializeBytes1to3()

Serializes the bytes 1 till 3 in the Basic Header Segment.

Overrides:

serializeBytes1to3 in class InitiatorMessageParser

Returns:

The serialized byte representation.

serializeBytes20to23

protected final int serializeBytes20to23()

Serializes the bytes 20 till 23 in the Basic Header Segment.

Overrides:

serializeBytes20to23 in class InitiatorMessageParser

Returns:

The serialized byte representation.

serializeBytes32to35

protected final int serializeBytes32to35()

Serializes the bytes 32 till 35 in the Basic Header Segment.

Overrides:

serializeBytes32to35 in class InitiatorMessageParser

Returns:

The serialized byte representation.

serializeBytes36to39

protected final int serializeBytes36to39()

Serializes the bytes 36 till 39 in the Basic Header Segment.

Overrides:

serializeBytes36to39 in class InitiatorMessageParser

Returns:

The serialized byte representation.