org.jscsi.parser.snack

Class SNACKRequestParser

java.lang.Object

org.jscsi.parser.AbstractMessageParser

org.jscsi.parser.InitiatorMessageParser

org.jscsi.parser.snack.SNACKRequestParser

public final class SNACKRequestParser
extends InitiatorMessageParser

SNACKRequestParser

This class parses a SNACK Request message defined in the iSCSI Standard (RFC3720).

If the implementation supports ErrorRecoveryLevel greater than zero, it MUST support all SNACK types.

The SNACK is used by the initiator to request the retransmission of numbered-responses, data, or R2T PDUs from the target. The SNACK request indicates the numbered-responses or data "runs" whose retransmission is requested by the target, where the run starts with the first StatSN, DataSN, or R2TSN whose retransmission is requested and indicates the number of Status, Data, or R2T PDUs requested including the first. 0 has special meaning when used as a starting number and length:

• When used in RunLength, it means all PDUs starting with the initial.
• When used in both BegRun and RunLength, it means all unacknowledged PDUs.

The numbered-response(s) or R2T(s), requested by a SNACK, MUST be delivered as exact replicas of the ones that the target transmitted originally except for the fields ExpCmdSN, MaxCmdSN, and ExpDataSN, which MUST carry the current values. R2T(s)requested by SNACK MUST also carry the current value of StatSN.

The numbered Data-In PDUs, requested by a Data SNACK MUST be delivered as exact replicas of the ones that the target transmitted originally except for the fields ExpCmdSN and MaxCmdSN, which MUST carry the current values and except for resegmentation (see Section 10.16.3 Resegmentation).

Any SNACK that requests a numbered-response, Data, or R2T that was not sent by the target or was already acknowledged by the initiator, MUST be rejected with a reason code of "Protocol error".

Data Acknowledgement

If an initiator operates at ErrorRecoveryLevel 1 or higher, it MUST issue a SNACK of type DataACK after receiving a Data-In PDU with the A bit set to 1. However, if the initiator has detected holes in the input sequence, it MUST postpone issuing the SNACK of type DataACK until the holes are filled. An initiator MAY ignore the A bit if it deems that the bit is being set aggressively by the target (i.e., before the MaxBurstLength limit is reached).

The DataACK is used to free resources at the target and not to request or imply data retransmission.

An initiator MUST NOT request retransmission for any data it had already acknowledged.

Resegmentation

If the initiator MaxRecvDataSegmentLength changed between the original transmission and the time the initiator requests retransmission, the initiator MUST issue a R-Data SNACK (see Section 10.16.1 Type). With R-Data SNACK, the initiator indicates that it discards all the unacknowledged data and expects the target to resend it. It also expects resegmentation. In this case, the retransmitted Data-In PDUs MAY be different from the ones originally sent in order to reflect changes in MaxRecvDataSegmentLength. Their DataSN starts with the BegRun of the last DataACK received by the target if any was received; otherwise it starts with 0 and is increased by 1 for each resent Data-In PDU.

A target that has received a R-Data SNACK MUST return a SCSI Response that contains a copy of the SNACK Tag field from the R-Data SNACK in the SCSI Response SNACK Tag field as its last or only Response. For example, if it has already sent a response containing another value in the SNACK Tag field or had the status included in the last Data-In PDU, it must send a new SCSI Response PDU. If a target sends more than one SCSI Response PDU due to this rule, all SCSI responses must carry the same StatSN (see Section 10.4.4 SNACK Tag). If an initiator attempts to recover a lost SCSI Response (with a Status SNACK, see Section 10.16.1 Type) when more than one response has been sent, the target will send the SCSI Response with the latest content known to the target, including the last SNACK Tag for the command.

For considerations in allegiance reassignment of a task to a connection with a different MaxRecvDataSegmentLength, refer to Section 6.2.2 Allegiance Reassignment.

Initiator Task Tag

For Status SNACK and DataACK, the Initiator Task Tag MUST be set to the reserved value 0xffffffff. In all other cases, the Initiator Task Tag field MUST be set to the Initiator Task Tag of the referenced command.

Author:

Volker Wildi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SNACKRequestParser.SNACKType This enumeration defines all valid SNACK types.

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
SNACKRequestParser(ProtocolDataUnit initProtocolDataUnit) Default constructor, creates a new, empty SNACKRequestParser 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	deserializeBytes40to43(int line) Parse the bytes 40 till 43 in the Basic Header Segment.
protected void	deserializeBytes44to47(int line) Parse the bytes 44 till 47 in the Basic Header Segment.
int	getBegRun() The DataSN, R2TSN, or StatSN of the first PDU whose retransmission is requested (Data/R2T and Status SNACK), or the next expected DataSN (DataACK SNACK).
DataSegmentFactory.DataSegmentFormat	getDataSegmentFormat() If this method returns true, hen it indicates that the data segment data is interpreted as binary data.
int	getRunLength() The number of PDUs whose retransmission is requested.
int	getTargetTransferTag() For an R-Data SNACK, this field MUST contain a value that is different from 0 or 0xffffffff and is unique for the task (identified by the Initiator Task Tag).
SNACKRequestParser.SNACKType	getType() Returns the SNACK Function Code of this SNACKRequestParser object.
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	serializeBytes24to27() Serializes the bytes 24 till 27 in the Basic Header Segment.
protected int	serializeBytes40to43() Serializes the bytes 40 till 43 in the Basic Header Segment.
protected int	serializeBytes44to47() Serializes the bytes 44 till 47 in the Basic Header Segment.
void	setBegRun(int newBegRun) Sets the begRun variable to the given new value.
void	setRunLength(int newRunLength) Sets the Run Length to the given value.
void	setTargetTransferTag(int newTargetTransferTag) Sets the Target Transfer Tag to the given value.
void	setType(SNACKRequestParser.SNACKType newType) Sets the type of this SNACKRequest to the given value.
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, deserializeBytes32to35, deserializeBytes36to39, getCommandSequenceNumber, getExpectedStatusSequenceNumber, getShortInfo, incrementSequenceNumber, serializeBytes28to31, serializeBytes32to35, serializeBytes36to39, 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

SNACKRequestParser

public SNACKRequestParser(ProtocolDataUnit initProtocolDataUnit)

Default constructor, creates a new, empty SNACKRequestParser object.

Parameters:

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

Method Detail

getBegRun

public final int getBegRun()

The DataSN, R2TSN, or StatSN of the first PDU whose retransmission is requested (Data/R2T and Status SNACK), or the next expected DataSN (DataACK SNACK).

BegRun 0 when used in conjunction with RunLength 0 means resend all unacknowledged Data-In, R2T or Response PDUs.

BegRun MUST be 0 for a R-Data SNACK.

Returns:

The BegRun of this SNACKRequestParser obejct.

getRunLength

public final int getRunLength()

The number of PDUs whose retransmission is requested.

RunLength 0 signals that all Data-In, R2T, or Response PDUs carrying the numbers equal to or greater than BegRun have to be resent.

The RunLength MUST also be 0 for a DataACK SNACK in addition to R-Data SNACK.

Returns:

The RunLength of this SNACKRequestParser object.

getTargetTransferTag

public final int getTargetTransferTag()

For an R-Data SNACK, this field MUST contain a value that is different from 0 or 0xffffffff and is unique for the task (identified by the Initiator Task Tag). This value MUST be copied by the iSCSI target in the last or only SCSI Response PDU it issues for the command.

For DataACK, the Target Transfer Tag MUST contain a copy of the Target Transfer Tag and LUN provided with the SCSI Data-In PDU with the A bit set to 1.

In all other cases, the Target Transfer Tag field MUST be set to the reserved value of 0xffffffff.

Returns:

The target transfer tag of this SNACKRequestParser object.

getType

public final SNACKRequestParser.SNACKType getType()

Returns the SNACK Function Code of this SNACKRequestParser object.

Returns:

The SNACK Function code of this SNACKRequestParser object.

See Also:

SNACKRequestParser.SNACKType

setBegRun

public final void setBegRun(int newBegRun)

Sets the begRun variable to the given new value.

Parameters:

newBegRun - The new value.

setRunLength

public final void setRunLength(int newRunLength)

Sets the Run Length to the given value.

Parameters:

newRunLength - The new value.

setTargetTransferTag

public final void setTargetTransferTag(int newTargetTransferTag)

Sets the Target Transfer Tag to the given value.

Parameters:

newTargetTransferTag - The new value.

setType

public final void setType(SNACKRequestParser.SNACKType newType)

Sets the type of this SNACKRequest to the given value.

Parameters:

newType - The new value.

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

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.

deserializeBytes40to43

protected final void deserializeBytes40to43(int line)
                                     throws InternetSCSIException

Parse the bytes 40 till 43 in the Basic Header Segment.

Overrides:

deserializeBytes40to43 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

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

deserializeBytes44to47

protected final void deserializeBytes44to47(int line)
                                     throws InternetSCSIException

Parse the bytes 44 till 47 in the Basic Header Segment.

Overrides:

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

serializeBytes24to27

protected final int serializeBytes24to27()

Serializes the bytes 24 till 27 in the Basic Header Segment.

Overrides:

serializeBytes24to27 in class InitiatorMessageParser

Returns:

The serialized byte representation.

serializeBytes40to43

protected final int serializeBytes40to43()

Serializes the bytes 40 till 43 in the Basic Header Segment.

Overrides:

serializeBytes40to43 in class InitiatorMessageParser

Returns:

The serialized byte representation.

serializeBytes44to47

protected final int serializeBytes44to47()

Serializes the bytes 44 till 47 in the Basic Header Segment.

Overrides:

serializeBytes44to47 in class InitiatorMessageParser

Returns:

The serialized byte representation.