iSCSI: v8 concordance

[Michael Smith <msmith@corp.iready.com>]

Title: iSCSI: v8 concordance

There have been several comments recently on this reflector about the use of terms and definitions in the current iSCSI Internet draft.

I have created a concordance for the iSCSI v8 Internet draft. You may download the concordance at
http://www.iready.org/iscsi/iscsi8concordanceV5.doc

This is a very large file (10MB).

A concordance is like an amplified index. A concordance is an ordered list of the occurence of every single word, term, and character in the iSCSI v8 spec together with it's context (the context being a certain number of words around each occurence).

Why is this useful? Let's take an example from the iSCSI Internet draft concordance file. Take the term "barrier". It often occurs as the term "barrier list" in the current Internet draft. But how is this term used exactly? First, look up "barrier (exactly as I have shown it here) in the concordance and you will see the following:

"BARRIER................................................................5
                                                          layer.  The "barrier list" described in the following sections is a                  7370 

                                                                      "barrier list";                                                          7382 

                                                            a) if the "barrier list" is empty or ExpCmdSN is less than                         7392 

                                                                    a "barrier list" including the referenced LUN (or an ALL                   7420 

                                                            a) if the "barrier list" is empty or ExpCmdSN is less than                         7428 

This means the characters "barrier appear five times (lines 7370, 7382, 7392, 7420, 7428 as numbered from the .txt version). Each time the characters "barrier occur as "barrier list". Continue now to look up just the characters barrier in the concordance. You will find:

BARRIER.................................................................5
                                               Note: for clarity, the barrier list contains "items" and the                                    7387 

                                  the CmdSN of the oldest item in the barrier list then                                                        7393 

                                                 b) remove the oldest barrier list item, and remove and                                        7395 

                                               the oldest item in the barrier list then skip to step d;                                        7429 

                                                 b) remove the oldest barrier list item and evaluate all                                       7430 

Thus barrier also occurs five times (lines 7387, 7393, 7395, 7429, 7430).

So what?

The concordance has told us:

1. If the term "barrier list" is defined the first time that it is used. (It is, sort of.)
2. If the term "barrier list" is used consistently each time.
3. That the use of quotes around barrier list is inconsistent and therefore perhaps misleading.

I hope that, from this small example, you may easily extrapolate to other uses of a concordance in reading, understanding, and editing the current iSCSI Internet draft. I have found this technique useful in the past.

Aloha

Mike Smith
CTO
iReady