|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] RE: iSCSI 4.1 & 4.2Julian, Please change "All negotiations are stateless and explicit..." to "All negotiations are explicit..." as has been discussed. Also, since a key-value pair can span request or response boundaries, the null-separator should be used to terminate every value and not just a value that is followed by another key. Otherwise, one won't know if the last key-value in a PDU is complete or has a value that will continue in the next PDU and one won't be able to respond to the key until one gets the next key (or maybe a PDU with no parameters if we assume that sending PDU with an empty parameter field means that the last value is complete). Pat -----Original Message----- From: Julian Satran [mailto:Julian_Satran@il.ibm.com] Sent: Saturday, April 27, 2002 12:39 PM To: ips@ece.cmu.edu Subject: iSCSI 4.1 & 4.2 Here are the rephrased 4.1 & 4.2 for better context: Text Format The initiator and target send a set of key=value pairs encoded in UTF-8 Unicode. All the text keys and text values specified in this docu-ment are to be presented and interpreted in the case they appear in this document. They are case sensitive. The following character symbols are used in this document for text items: (a-z, A-Z) - letters (0-9) - digits " " (0x20) - space "." (0x2e) - point "-" (0x2d) - minus "+" (0x2b) - plus "@" (0x40) - commercial at "_" (0x5f) - underscore "=" (0x3d) - equal ":" (0x3a) - colon "/" (0x2f) - solidus or slash "[" (0x5b) - left bracket "]" (0x5d) - right bracket null(0x00) - null separator "," (0x2c) - comma "~" (0x7e) - tilde DLB> It would be good to say at this point that at least space, colon, DLB> comma, tilde, and null are reserved characters that cannot appear DLB> in key names or values. It's also worth saying that any character DLB> not in the above list is reserved for future use and MUST NOT be used. A key is key-name followed by "=". The term key is used frequently in this document with the meaning of key-name. DLB> Really? Including the "=" in the definition of key is counter-intuitive, DLB> and the second sentence is an invitation to serious confusion. DLB> It would be better to introduce this as the separator in a definition DLB> of key-value-expression or key-value-pair. A value is whatever follows the = that follows the key-name up to a null separator - that separates one key value from the next The following definitions will be used in the rest of this document: key-name: a string defined by the regular expression "[A-Z][a-zA-Z0-9.-+@_]*" DLB> Need to explain the regular expression syntax. Also the last DLB> occurrence of minus needs a \ prefix to indicate that it's character DLB> rather than a regular expression syntax element. DLB> Starting here, I'd add a sentence to explain each regular expression. DLB> For example, "A key-name is a string consisting of letters, numbers, DLB> and/or the characters .-+@_ ; it MUST begin with a capital letter. text-value: a string defined by the regular expression "[][a-zA-Z0-9.-+@_/\[\]=]*" DLB> This appears to allow equal to occur in a text-value. I'd DLB> recommend against that, as it has obvious potential for confusion. DLB> It has the same issue with minus as the previous expression. boolean-value: a string defined by the regular expression "Yes|No" DLB> What about "yes" and "no", "YES" and "NO"? Weirder things like DLB> "yEs and "nO" don't seem useful, though. hex-constant: unsigned hexadecimal constant described by regu-lar expression "0[xX][0-9a-zA-Z]+" DLB> That should be "[0-9a-fA-F]" with a note that the letters are case- DLB> insensitive, and a through f (A through F) represent the decimal DLB> values 10 through 16 as hex digits. base-64-constant: unsigned base-64 constant described by regu-lar expression "0b[A-Za-z0-9+/=]+" DLB> Occurrence of "=" in the constants is a potential problem, similar to DLB> allowing it in the text values. Also, similar to hex, describe what DLB> the characters other than digits denote, and in addition DLB> how possible letter "O" vs. number "0" and letter "l" vs. number "1" DLB> confusion is avoided. regular-numerical-value : an unsigned integer less than 2**64 encoded as a decimal constant, hex constant, or base-64 con-stant large-numerical-value : an unsigned integer larger than 2**64-1 encoded as a hex constant, or base-64 constant DLB> Add an explicit statement that decimal representation MUST NOT be used DLB> for numbers >= 2^64. I realize that any mathematician or logician DLB> can figure this out, but we're dealing with implementers who can use DLB> all the help they can get ... numerical-value: a regular-numerical-value or a large numeri-cal-value numeric-range: two numerical-values separated by a tilde simple-value: text-value, boolean-value, numeric-value or a numeric range. list-of-values: a sequence of text-values separated by comma Key names MUST NOT exceed 63 bytes. If not otherwise specified, the maximum length of a simple-value (not its encoded representation) is 255 bytes not including the delimiter (comma or null). Any iSCSI target or initiator MUST support receiving at least 16384 bytes of key=value data in a negotiation sequence except when indicat-ing support for very long authentication items such as public key cer-tificates in which case they MUST support receiving at least 64 kilobytes of key=value data. DLB> Say how that "support for very long authentication items" is indicated. Text Mode Negotiation During login, and thereafter, some session or connection parameters are negotiated through an exchange of textual information. The initiator starts the negotiation through a Text/Login request and indicates when it is ready for completion (by setting to 1 and keeping to 1 the F bit in a Text Request or the T bit in the Login Request). The general format of text negotiation is: Originator-> <key>=<valuex> Responder-> <key>=<valuey>|NotUnderstood|Irrelevant|Reject The originator can either be the initiator or the target and the responder can either be the target or initiator, respectively. Target requests are not limited to respond to key=value pairs as offered by the initiator. The target may offer key=value pairs of its own. All negotiations are stateless and explicit (i.e., the result MUST be based only on newly exchanged values). There is no such thing as implicit offers. If an explicit offer is not made then a reply cannot be expected. DLB> Delete "stateless and", as there is state retained (e.g., is the response DLB> the same as what was offered). Is this the place to put in the requirement DLB> that any value that has a significant affect on the correct operation or DLB> performance of an implementation MUST be negotiated? In other words, a DLB> default value MUST NOT be relied upon when use of some other value by the DLB> other party has serious consequences - implementers are free to decide DLB> which consequences are serious, but we need this requirement to prevent DLB> "It's not my fault, that other implementation didn't use the default" DLB> interoperability/finger-pointing problems. The value offered can be an numerical-value, a numerical-range defined by lower and upper value - both integers separated by tilde, a text-value, a boolean-value (Yes or No), or a list of comma sepa-rated text-values. A range MAY ONLY be offered if it is explicitly allowed for a key. A selected value can be an numerical-value, a text-value or a boolean-value. In list negotiation, the originator sends a list of values (which may include "None") for each key in its order of preference. The responding party answers with the first value that it supports and is allowed to use for the specific originator selected from the orig-inator list. DLB> "first" is a potential problem. If this was intended, it needs to DLB> come with a warning that when larger numeric values are preferred, DLB> numeric lists need to be listed in descending order rather than DLB> ascending order ... but this convention does not apply to ranges, DLB> which is peculiar. I'm not sure about this priority order convention. The constant "None" MUST always be used to indicate a missing func-tion. However, None is a valid selection only if it is explicitly offered. If a responder does not understand any particular value in a list it MUST ignore it. If a responder does not support, does not understand or is not allowed to use all of the offered options with a specific originator, it MAY use the constant "Reject". The selection of a value not admissible under the selection rules is considered a negoti-ation failure and is handled accordingly. DLB> That "MAY" is a problem. It should be a MUST, possibly with some DLB> rephrasing. If the "MAY" remains, a sentence explaining the alternative(s) DLB> needs to be added. For simple-value negotiations, the responding party MUST respond with the required key. The value it selects, based on the selection rule specific to the key, becomes the negotiation result. For a numerical range the value selected must be an integer within the offered range or "Reject" (if the range is unacceptable). An offer of a value not admissible MAY be answered with the constant "Reject". The selection of a value not admissible under the selection rules is considered a negotiation failure and is handled accordingly. DLB> Use upper case MUST in "value selected must", Also the MAY for "Reject" DLB> has the same problem as the previous MAY compounded by the need for DLB> an explanation of "value not admissible". For boolean negotiations (keys taking the values Yes or No), the responding party MUST respond with the required key and the result of the negotiation when the received value does not determine that result by itself. The last value transmitted becomes the negotiation result. The rules for selecting the value with which to respond are expressed as Boolean functions of the value received and the value that the responding party would select in the absence of knowledge of the received value. Specifically, the two cases in which responses are OPTIONAL are: - The boolean function is "AND" and the value "No" is received. The outcome of the negotiation is "No". - The boolean function is "OR" and the value "Yes" is received. The outcome of the negotiation is "Yes". DLB> On further reflection, this seems a bit on the clever side and a minor DLB> optimization. Does anyone else care? The alternative would be to DLB> always require explicit responses (even when there is only one DLB> acceptable response) at the possible cost of an extra negotiation DLB> round trip. Responses are REQUIRED in all other cases, and the value chosen and sent by the responder becomes the outcome of the negotiation. An offer of a value not admissible MAY be answered with the constant "Reject". The selection of a value not admissible under the selection rules is considered a negotiation failure and is handled accordingly. DLB> Need to define "offer of a value not admissible". If a specific key is not relevant for the current negotiation, the responder may answer with the constant "Irrelevant" for all types of negotiation. However the negotiation is not considered as failed if the response is Irrelevant. DLB> But, but ... if the Initiator considers the key important, the negotiation DLB> may fail. Implementers should (lower case) be cautious and conservative DLB> in using "Irrelevant", as humoring the other party to the negotiation DLB> when it behaves in a somewhat clue-impaired fashion improves inter- DLB> operability. Any other key not understood by the responder may be ignored by the responder without affecting the basic function. However, the Text Response for a key not understood MUST be key=NotUnderstood. The constants "None", "Reject", "Irrelevant", and "NotUnderstood" are reserved and must only be used as described here. DLB> Do we want to reserve any other strings for future use? Some basic key=value pairs are described in Chapter 11. All keys in Chapter 11, except for the X- extension format, MUST be supported by iSCSI initiators and targets and MUST NOT be answered with NotUnder-stood. Manufacturers may introduce new keys by prefixing them with X- fol-lowed by their (reversed) domain name. For example the company owning the domain acme.com can issue: X-com.acme.bar.foo.do_something=3 DLB> Change "Manufacturers" to "Implementers" and "company" to "entity" for DLB> generality.
Home Last updated: Fri May 03 02:18:32 2002 9943 messages in chronological order |