public review comments on CAM

Lansing J Sloan ljsloan at anduin.ocf.llnl.gov
Thu Apr 6 10:34:41 PDT 1995


To:     Membership of X3T10 (via SCSI reflector)

LLNL's public review comments on CAM Rev 11 are appended.
This is a summary.  Of 186 comments, 141 are editorial and
45 are (slightly) technical.

On the whole, our interest is more in CAM-3 than in CAM-1.
Therefore, to the extent that acting on these comments would
delay CAM-3, we would be sympathetic to rejection.

It is not our intent to change CAM or to break any implementations.

The 45 technical comments can be summarized in various ways,
one of these ways follows.

Fourteen comments say in effect that path IDs should identify
SCSI ports within a CAM environment.  Since SCSI-2 does not
have provisions for multiple ports, it may be reasonable to
defer action on these comments until CAM-3.  Those are comments
10, 31, 33, 36, 54, 56, 57, 82, 86, 88, 99, 110, 111, and 126.

Eleven comments discuss areas where more information may be
appropriate or necessary: 68, 89, 91, 117, 130, 137, 144, 154,
172, 173, and 175.

Seven may primarily be a matter of clarity: 45, 47, 48, 73, 95,
147, and 160.

Eight are thought to be trivial: 52, 141, 142, 151, 161, 165,
170, and 179.

Four appear to be bugs in that one part of a document disagrees
with another or that one part of a document discusses a
requirement that seems unneeded in view of the rest of the
document: 101, 128, 129, and 138.

One is kind of miscellaneous: 58.

Some of the "technical" comments may be simple typos in the
document.  Some may be a consequence of misunderstandings.
I apologize in advance for any typos or bugs that may have
occurred in the comments or in this summary.  Anyone having
problems understanding a comment should feel free to ask me
what the heck I mean.

I hope this summary reduces the effort most of you would
otherwise make.

-- Lance

------------- Public Review comments follow -----------
                                                                 
                                                   x3t10/95-193R0



Lansing J. Sloan
M/S L-60
Lawrence Livermore National Laboratory
7000 East Avenue
Livermore, CA 94550-9900  USA

Telephone:     1-510-422-4356
FAX:           1-510-423-8715
E-mail:        ljsloan at llnl.gov

                                                    April 4, 1995



X3 Secretariat
Attn.:  Lynn Barra
1250 Eye Street N.W., Suite 200
Washington, D.C.  20005-3922

Membership of X3:
     
     Here  are  Lawrence Livermore National Laboratory's comments
to  the  second  public review of X3.232:199x, the SCSI-2  Common
Access Method Transport and SCSI Interface Module (Revision  11).
We consider this to be a "yes" vote with comments.
     
     Comments are organized as follows:
     
     #xxx (?) Comment on y.y.y

where
     
     xxx is the comment number,
     
     ? is the type (E: Editorial, T: Technical), and
     
     y.y.y is the referenced section number.
                                
                        SPECIFIC COMMENTS

#001 (E) Comment on list of Tables in Table of Contents
     
     Should Table 18 be listed twice?
     
     Tables 19 and 20 are out of order.

#002 (E) Comment on 1, first paragraph, first sentence
     
     Change "SCSI Small" to "the Small".

#003 (E) Comment on 3.1.1
     
     As defined, "block" seems to be a noun instead of a verb.
Is that the intent?

#004 (E) Comment on 3.1.7
     
     Move the right parenthesis to follow "queue" instead of
"freeze".

#005 (E) Comment on 3.1.11
     
     Insert "that" before "depends".

#006 (E) Comment on 3.1
     
     A definition of "path" seems warranted.  Having the
definition point to clause 9.1.5 seems wise.

#007 (E) Comment on 3.1.14
     
     Change "between" to "among" before "vendors."

#008 (E) Comment on 3
     
     A clause listing mnemonics and what they stand for would be
useful.

#009 (E) Comment on 5, second paragraph, second sentence
     
     Delete the sentence, or replace it with one extolling the
benefits of providing a common way to provide access to SCSI
peripherals.

#010 (T) Comment on 5.1
     
     If the CAM document should say that only one port in a CAM
environment can be on a given bus, this clause is one of the best
places to say it.  Clause 9.1.5 is another good place.  Since CAM-
3 probably will not have such an assumption or requirement, the
rest of the CAM document should minimize dependence on such an
assumption.
     
     It seems preferable that CAM make no such statement or
assumption.

#011 (E) Comment on 5.1, Figure 1
     
     Consider showing ports on HBAs.

#012 (E) Comment on 5.2, item j)
     
     Change "pass" to "passing".

#013 (E) Comment on 5.3, item e)
     
     Make "driver" plural.

#014 (E) Comment on 5.4, item d)
     
     After "Manage", delete "of".

#015 (E) Comment on 6.2, paragraph under XPT, second sentence
     
     Make "responsibility" plural.

#016 (E) Comment on 6.4, third paragraph, second sentence
     
     What are the officially blessed spelling and pronunciation:
"A XPT" or "An XPT"?

#017 (E) Comment on 6.4, fifth paragraph, third sentence
     
     Is UNIX still a trademark of AT&T, or did AT&T sell the
trademark when they sold the rights to UNIX?

#018 (E) Comment on 6.4, sixth paragraph, first sentence
     
     Should "Operating" be included inside the parentheses
following "LANOS"?

#019 (E) Comment on 6.4, item d) in list of requirements
     
     The current words seem convoluted.  Consider: "Allow the
calling driver or program to interpret sense data returned by
SCSI devices."

#020 (E) Comment on 6.4, item g) in list of requirements
     
     Does "determine" mean "learn" or does "determine" mean
"control".  The word "determine" is quite ambiguous here, and
should be replaced with an unambiguous term.
     
     A global electronic search for other ambiguous uses of
"determine" may be worth while.

#021 (E) Comment on 7.3.2, first paragraph, last sentence
     
     Insert blanks after "9," and "10,".

#022 (E) Comment on 7.3.2, second paragraph, first sentence
     
     Change "using 1 of" to "using one of".

#023 (E) Comment on 7.3.2, paragraph in last bullet
     
     In "of an completed", change "an" to "a".

#024 (E) Comment on 7.4, fourth paragraph
     
     In "Unit may keep", change "may" to "to".

#025 (E) Comment on 7.4.2.1, first paragraph, last sentence
     
     A period is needed after the sentence.

#026 (E) Comment on 7.4.2.2, second paragraph, first sentence
     
     Delete "is" from "driver is shall".

#027 (E) Comment on 7.4.2.3, first paragraph, first sentence
     
     In "a EXECUTE", change "a" to "an".

#028 (E) Comment on 7.4.2.3, first paragraph, second sentence
     
     Delete "is" from "... queue is shall ...".

#029 (E) Comment on 7.4.2.3, fourth paragraph, first sentence
     
     In "When a SIMs Logical Unit's", change "SIMs" to "SIM's"
(possessive).

#030 (E) Comment on 7.4.2.3, last paragraph, first sentence
     
     Replace "indicating" with "an indication of".

#031 (T) Comment on 7.5, second paragraph
     
     In step a), "to the reset bus" should be "for the port on
the reset bus" or "for the reset port".
     
     In steps a) and b), "for this bus" should be "for this
port".
     
     In step c), path_id should be "port that was reset" or "port
attached to bus that was reset".
     
     In step d), "for the bus" should be "for the port".

#032 (E) Comment on 7.5, third paragraph, first bullet
     
     Change "shall ensure that" to "shall check whether".

#033 (T) Comment on 7.5, third paragraph, third bullet
     
     Change "detection" to "detecting".
     
     In step b), "bus" probably should be "port".

#034 (E) Comment on 7.5, last paragraph, first sentence and first
bullet
     
     Are "SCSI BUS DEVICE RESET" and "SCSI DEVICE RESET" supposed
to be different (only one has "BUS") or supposed to be the same?

#035 (E) Comment on 7.5, last paragraph, first bullet
     
     Append "ly" to the word "successful".

#036 (T) Comment on 7.5, last paragraph
     
     In step a), should "bus" be "path" or "port attached to the
bus"?
     
     In step b), should "SIM/HBA for this bus" be "SIM/HBA for
this target"?  If "target" is not correct, should "bus" be
"port"?
     
     In step c), should path_id be set to "port used to issue the
SCSI ... RESET"?
     
     In step d), should "bus" be "path" or "port attached to the
bus"?

#037 (E) Comment on 7.6, third paragraph, second sentence
     
     The second sentence might be clearer if replaced by: "For
registration with Logical Units, the following Asynchronous
Events are possible:".

#038 (E) Comment on 7.6, third and fourth paragraph
     
     For each list of possible events, the last event listed
should be ended with a period instead of a semicolon.

#039 (E) Comment on 7.6, fourth paragraph, first sentence
     
     Change "is" to "are" before "the following".

#040 (E) Comment on 7.6, fifth paragraph, last sentence
     
     Delete "a" from "The use of a wildcards".

#041 (E) Comment on 7.6
     
     In the paragraph that starts "The peripheral driver can
deregister ... ", the end of the first sentence should be
"registered values", so append "ed" to "register".

#042 (E) Comment on 7.6
     
     In the paragraph that starts "The XPT shall be responsible
for ensuring ... serial fashion", the last sentence is
incomplete.  Before "the SIM" insert "in" or "within" or rewrite
the sentence to state that the SIM is responsible for
serialization.

#043 (E) Comment on 7.7, second paragraph, second sentence
     
     Before "specified", "is" should be "are".

#044 (E) Comment on 7.8, second and third paragraphs
     
     In the first sentence of each, "it's" should be "its"
(possessive).

#045 (T) Comment on 7.8
     
     The next-to-last paragraph, which starts with "When the XPT
is called it will update ...", should be moved so it occurs as
part of the xpt_bus_register() function, and before any
discussion of xpt_bus_deregister().
     
     Probably in that paragraph "the XPT is called" should be
replaced by "xpt_bus_register is called" to reduce confusion as
to what is called.
     
     Possibly a paragraph should be added to say what
xpt_bus_deregister shall do when it is called.

#046 (E) Comment on 8.1.6.1, case b), second sentence
     
     The word "it's" should be "its" (possessive).

#047 (T) Comment on 8.1.6.1
     
     In the descriptions of xpt_init() and xpt_action(CCB *), the
descriptions appear to fail to discuss the values returned when
the function returns.  Probably the term "CAM Status" should be
replaced by "return value".

#048 (T) Comment on 8.1.7
     
     The return values for sim_init() and sim_action(CCB *) are
never described -- or, more likely, they are called CAM Status
instead of return values.  The document should be clear what is
returned from these function calls.

#049 (E) Comment on 9, first paragraph after table 2
     
     The character before "i.e." should be a left parenthesis.

#050 (E) Comment on 9, second paragraph after table 2
     
     In "vary between operating", change "between" to "among".

#051 (E) Comment on 9, paragraph above table 3
     
     Is the first line of this paragraph supposed to be a
separate paragraph?  If so, insert a blank line.

#052 (T) Comment on 9.1.4, Table 5
     
     The reserved range 1B-33h should be 1B-32h.

#053 (E) Comment on 9.1.4, status 38h
     
     Should "... range of the SCSI bus" be "... range of the
SIM/HBA"?

#054 (T) Comment on 9.1.5
     
     If the CAM document should say that only one port in a CAM
environment can be on a given bus, this clause is one of the best
places to say it.  Clause 5.1 is another good place.  Since CAM-3
probably will not have such an assumption or requirement, the
rest of the CAM document should minimize dependence on such an
assumption.
     
     It seems preferable that CAM make no such statement or
assumption.

#055 (E) Comment on 9.2.2, 9.2.3, 9.2.4, 9.2.7 and 9.2.8
     
     In many of the bullets listing CAM Status values,
"indicates" is followed by an unneeded comma.  This occurs 3
times in 9.2.2, 3 times in 9.2.3, 1 time in 9.2.4, 2 times in
9.2.7, and 2 times in 9.2.8.

#056 (T) Comment on 9.2.3, first paragraph, first sentence
     
     In "number of HBAs installed", "HBAs" should be ports.  (See
9.1.5.)
     
     Probably there should be text to mention that there can be
multiple SIMs, each with multiple HBAs, each with multiple SCSI
ports, and that the XPT is responsible for assigning a path ID
for each of the ports.  Perhaps a pointer to 9.1.5 would suffice.

#057 (T) Comment on 9.2.3, first paragraph below table 8
     
     In the parentheses, "SCSI buses" should be "SCSI ports".

#058 (T) Comment on 9.2.3, second paragraph below table 8
     
     In the second paragraph below table 8, it's not clear how
the revision number for a standard would be determined.  (Annex C
has the value corresponding to revision 11, but is not normative.
And the revision number for the standard clearly could change.)

#059 (E) Comment on 9.2.3, last paragraph
     
     In the second bullet, "nolonger" should be two words.

#060 (E) Comment on 9.2.4, first paragraph
     
     The first sentence is awkward since it is hard to figure out
what "for the selected Logical Unit" refers to.

#061 (E) Comment on 9.2.4, first paragraph
     
     Start the second sentence with "Determining" rather than "To
determine".

#062 (E) Comment on 9.2.4, second paragraph
     
     In the first sentence, change "determine" to "be
determined".

#063 (E) Comment on 9.2.4, second paragraph
     
     In each bullet, insert "if the" before "CAM Flag".
     
     In each bullet, insert "is" between "bit" and "set".
     
     In each bullet, replace "places" with "shall place".
     
     In the second bullet, replace "decrements" with "shall
decrement".

#064 (E) Comment on 9.2.5 and 9.12.6, first paragraph below table
     
     A sentence (fifth in 9.2.5, third in 9.2.6) begins with
"Further more", which should be a single word.

#065 (E) Comment on 9.3.1, fourth paragraph
     
     In "CCB may be a one", change "a" to "in".

#066 (E) Comment on 9.3.4, second paragraph after table 17
     
     In "CCB may be a one", change "a" to "in".

#067 (E) Comment on 10
     
     It would be useful to point to the tables illustrating the
CCBs.  It would be especially helpful to point to the Execute
SCSI I/O table.

#068 (T) Comment on 10.1
     
     Should a description of the Autosense Residual Length field
be added?  If so, should two's-complement be mentioned (see Annex
C)?

#069 (E) Comment on 10.1.2, Table 18, part 1
     
     In the subtable for bits 3 and 2, in the line for bit 3 = 0
and bit 2 = 1, "Cam" should be "CAM".  Possibly a global
electronic search of the document would find more such cases.

#070 (E) Comment on 10.1.2.1, description of bit 4, second
sentence
     
     In "list of addresses and length", make "length" plural.

#071 (E) Comment on 10.1.2.4, description of bit 0, second
sentence
     
     Delete the second "to" from "to automatically to".

#072 (E) Comment on 10.1.2.5, description of bit 5
     
     Insert "that" before "the Host Target Mode".

#073 (T) Comment on 10.1.8
     
     Must the message buffer be able to hold more than one
message?  If so, how are the boundaries between messages
specified?  If not, consider rewording 10.1.8 to state that
multiple messages are impossible or are outside the scope or are
vendor unique, or whatever.

#074 (E) Comment on 10.1.9, first sentence
     
     Insert "a" before "buffer".

#075 (E) Comment on 10.2
     
     Should the CAM status "SCSI device not installed" be added
to the list of possible status values?

#076 (E) Comment on 10.3, probably the third paragraph
     
     In the last sentence, "CCBs" should be "CCB's" (possessive).

#077 (E) Comment on 10.3, third-from-last paragraph (driver
shall)
     
     In the last bullet, change the verb "is was" to "was" or
"is".

#078 (E) Comment on 10.3, next-to-last paragraph (driver may)
     
     In the last bullet, "with in" should be one word, "within".

#079 (E) Comment on 10.3, last paragraph (SIM/HBA shall)
     
     In the second bullet, "a" should be inserted before "LINKED"
in both places, and "the" should be inserted before the first
"CCB".

#080 (E) Comment on 10.3, last paragraph
     
     In the fifth bullet, delete "shall" and place a comma after
"completes".

#081 (E) Comment on 10.3, last paragraph
     
     In the sixth bullet, place a comma after "broken", change
the verb "callback" to "call back", and insert "driver" after
"peripheral".
     
     If the verb "callback" should be split into two words, an
electronic global search should help.

#082 (T) Comment on 11, first paragraph, first sentence
     
     After "specified SCSI", "bus" should be "port".  (See
9.1.5.)

#083 (E) Comment on 11.1, seventh paragraph, first sentence
     
     Consider changing "once for each command received" to "once
when the command is received".

#084 (E) Comment on 11.2
     
     In the list of messages to be handled transparently by the
SIM/HBA, two have the parenthetical remark "for specified
conditions".  Where are the specifications for the conditions?

#085 (E) Comment on 11.2.1
     
     It might be helpful to create three subclauses.
Possibilities are 11.2.1.1 (Enabling and Disabling LUNs);
11.2.1.2 (Initializing and Maintaining Target CCBs), 11.2.1.3
(Receiving CDBs for non-enabled LUNs).
     
     If this is done, the seventh and eighth paragraphs after
Table 22 (which discuss VU CDBs and disabling LUNs) should be in
11.2.1.1, and the list of CAM Status values should be in
11.2.1.1.

#086 (T) Comment on 11.2.1, first paragraph, first sentence
     
     The end of the sentence, "for the HBA", should probably be
"for the SCSI port."  (See 9.1.5.)

#087 (E) Comment on 11.2.1, Table 22
     
     If Table 22 will be used to describe lists of IMMEDIATE
NOTIFY CCBs, then "TARGET" should be deleted from the title of
the table.
     
     In the title, probably "LIST" should be "List" and "TARGET"
should be "Target" if it is retained.

#088 (T) Comment on 11.2.1, second paragraph after Table 22
     
     "SCSI bus specified" should be "SCSI port specified".  (See
9.1.5.)

#089 (T) Comment on 11.2.1, second paragraph after Table 22
     
     Should this paragraph specify that the driver set the CAM
Status value to "Request Completed by target peripheral driver",
as is shown in B.1.2?

#090 (E) Comment on 11.2.1, fifth paragraph after Table 22
     
     If the intent of the second bullet is to require that the
values of CAM flags in each Target CCB shall be set to the values
of the flags in the ENABLE LUN CCB, then the wording should be
more clear, perhaps: "CAM flags shall be set to the values of the
CAM Flags in the ENABLE LUN CCB".

#091 (T) Comment on 11.2.1
     
     Text should be added to specify whether the SIM/HBA is
expected to free Target CCBs when a specific LUN is disabled or
whether the driver is responsible for the CCBs after the LUN is
disabled.  The eighth paragraph following Table 22 (the paragraph
that begins "To disable the selection of a specific LUN ...) may
be one good place for such text.

#092 (E) Comment on 11.2.2, fourth paragraph
     
     Consider adding a new sentence after the second sentence,
perhaps: "Otherwise, the SIM/HBA shall select a CCB with the
TARGET CCB Available flag set."

#093 (E) Comment on 11.2.3, fourth paragraph, first sentence
     
     "Data Valid bit" should be "Data Buffer Valid bit",
according to Table 18.

#094 (E) Comment on 11.2.3, fourth paragraph, third sentence
     
     Insert "be" between "shall" and "interpreted".

#095 (T) Comment on 11.2.3, fourth paragraph
     
     Should it be an error for the Data Buffer Valid bit to be
set and for bits 7 and 6 both to be set to indicate "No data
transfer"?

#096 (E) Comment on 11.2.4, first five paragraphs
     
     Each paragraph should end with a period, not a semicolon.

#097 (E) Comment on 11.2.4, first paragraph (ABORT message)
     
     In the first sentence, "ABORT" and "initiator" should each
be preceded by "an" rather than "a".  In the second bullet, "I/O"
should be preceded by "an" rather than "a".

#098 (E) Comment on 11.2.4, second paragraph (BUS DEVICE RESET)

In the first sentence, "initiator" should be preceded by "an"
rather than "a".

#099 (T) Comment on 11.2.4, second paragraph (BUS DEVICE RESET)
     
     Assuming that a BUS DEVICE RESET message is directed to a
device rather than to a LUN, it seems the first sentence should
be rewritten perhaps as follows: "When the SIM/HBA receives a BUS
DEVICE RESET message from an initiator, it shall perform the
following actions for each phase-cognizant LUN that uses the port
over which the message was received:".

#100 (E) Comment on 11.2.4, second paragraph (BUS DEVICE RESET)
     
     The second bullet seems to have two independent ideas.
     
     Probably the second bullet should discuss only the
asynchronous event callback.
     
     The material in parentheses should become a separate bullet,
with parentheses and "e.g." deleted.

#101 (T) Comment on 11.2.4, third paragraph (TERMINATE I/O)
     
     The first outermost bullet applies when the SIM/HBA has no
EXECUTE TARGET I/O CCBs. The bullet specifies disconnecting
(conditionally) and rejecting the next EXECUTE TARGET I/O CCB.
     
     The third outermost bullet seems to discuss an almost
identical case, except the SIM/HBA has a CCB that is so close to
being finished that its processing should complete normally.  It
would seem that this bullet should also specify disconnecting
(again conditionally) and rejecting the next EXECUTE TARGET I/O
CCB, at least if the I/O process still exists after the CCB is
completed.  Presently it does not do so.

#102 (E) Comment on 11.2.4, third paragraph (TERMINATE I/O)
     
     In the first sentence, "initiator" should be preceded by
"an" rather than "a".
     
     In the second outermost bullet, "that" should precede "have
a CAM Status".
     
     In the first sub-bullet under the second outermost bullet,
insert "is" after "bus" and before "allowed".

#103 (E) Comment on 11.2.4, fourth paragraph (INIT DETECTED
ERROR)
     
     In the first sentence, "INITIATOR" and "initiator" should
each be preceded by "an" rather than "a".
     
     In the first bullet, "I/O" should be preceded by "an" rather
than "a".
     
     In the second outermost bullet, "that" should precede "have
a CAM Status".
     
     In the first sub-bullet under the second outermost bullet,
insert "is" after "bus" and before "allowed".

#104 (E) Comment on 11.2.4, fifth paragraph (BUS RESET)
     
     The first bullet seems to have two independent ideas.
     
     Probably the first bullet should discuss only the
asynchronous event callback.
     
     The material in parentheses should become a separate bullet,
with parentheses and "e.g." deleted.

#105 (E) Comment on 11.2.4, last paragraph, last sentence
     
     Change "drivers" to "driver's" (possessive).

#106 (E) Comment on 11.3.3, first paragraph, fourth sentence
     
     Preceding "DISABLE", "an" should be "a".

#107 (E) Comment on 11.3.3, sixth paragraph, first two sentences
     
     These sentences appear to say the same thing, but differ
enough that it's not clear.  If they are saying the same thing,
please delete one of them.

#108 (E) Comment on 11.3.3.1.1
     
     In this clause (in contrast to 11.3.3.1.2, 11.3.3.1.3.x,
11.3.3.1.4, and 11.3.3.1,5) most of the steps begin with "The
SIM/HBA shall ...".  If 11.3.3.1.1 is to keep its current style,
then step A) should also start with "The SIM/HBA shall ..." and
the text before step A) should end with a period instead of a
semicolon.
     
     Note: It would probably be better if clauses 11.3.3.1.2
through 11.3.3.1.5 were more like 11.3.3.1.1 in this respect.
Several of the steps are complex enough that lists of complete
sentences are more manageable than sentences that contain entire
lists.  (The comments on those clauses are written assuming the
later clauses will *not* be made like 11.3.3.1.1, however.)

#109 (E) Comment on 11.3.3.1.1, step A)
     
     Probably "pathid" should be "path ID".

#110 (T) Comment on various including 11.3.3.1.1, step A)
     
     Taking into account the possibility of multiple ports on the
same bus, the path ID should be set to identify the port, rather
than the bus.  Consider replacing "the bus number of this bus"
with something like "the specifier of the SCSI port".
     
     Whatever is done should be done also in 11.3.3.1.2.1 B);
11.3.3.1.3.2 C); 11.3.3.1.3.3 B); 11.3.3.1.3.5 D); and 11.3.3.1.4
A).

#111 (T) Comment on 11.3.3.1.1, step A)
     
     If reasonable, a global check of the document should be made
to look for other places where a path ID is said to identify a
bus.  (Clause 9.1.5 is assumed to be correct.)  If CAM expects
only one port of a CAM environment model (Figure 1) is on a
particular bus, that should be stated, preferably only once.
That minimizes future changes needed in CAM if later versions
allow for multiple ports on the same bus or same SCSI domain.

#112 (E) Comment on various including 11.3.3.1.1, step E)
     
     Before "unique," change "an" to "a".  Change "CCBs" to
"CCB's" since it is possessive.
     
     Make similar changes in 11.3.3.1.2.1 D), 11.3.3.1.3.2 F),
11.3.3.1.3.3 E), 11.3.3.1.3.5 E), 11.3.3.1.4 C), and 11.3.3.1.5
C).

#113 (E) Comment on various including 11.3.3.1.1, step F)
     
     Consider changing the verb "callback" (one word) to "call
back" (two words).
     
     Before "IMMEDIATE," the word "available" should be deleted.
     
     Make similar changes in 11.3.3.1.2.1 G), 11.3.3.1.3.2 H),
11.3.3.1.3.3 G), 11.3.3.1.4 D), and 11.3.3.1.5 F).

#114 (E) Comment on 11.3.3.1.1, next to last paragraph
     
     Before "NOTIFY," "an" should be "a".

#115 (E) Comment on 11.3.3.1.2, first paragraph
     
     For clarity, append "via the IMMEDIATE NOTIFY CCB" at the
end of the sentence.

#116 (E) Comment on various including 11.3.3.1.2.1, step G)
     
     Consider deleting "The SIM/HBA shall" from the beginning of
each of the first two sentences and capitalizing the following
word.
     
     Make similar changes in 11.3.3.1.3.2 H), 11.3.3.1.3.3 G),
11.3.3.1.4 D), and the one sentence in 11.3.3.1.5 F).

#117 (T) Comment on various including 11.3.3.1.2.1
     
     Consider adding text at the end of the clause to specify
what the Host Target Mode peripheral driver shall do to complete
processing.
     
     Consider similarly adding text at the end of 11.3.3.1.3.2,
11.3.3.1.3.3, and 11.3.3.1.4 (probably nothing to be done in this
last case).

#118 (E) Comment on 11.3.3.1.3.2, steps F) and G)
     
     Consider deleting "The SIM/HBA shall" from the beginning of
the first sentence and capitalizing the following word.

#119 (E) Comment on 11.3.3.1.3.2, step G), second sentence
     
     Delete "is" from before "found".  Change "CCBs" to "CCB's"
(possessive).

#120 (E) Comment on 11.3.3.1.3.3, step E)
     
     Consider deleting "The SIM/HBA shall" from the beginning of
the first sentence and capitalizing the following word.

#121 (E) Comment on 11.3.3.1.3.5, step A)
     
     Consider deleting "the SIM/HBA shall" from the first
sentence.

#122 (E) Comment on 11.3.3.1.3.5, step E)
     
     Consider deleting "The SIM/HBA shall" from the beginning of
the first sentence and capitalizing the following word.

#123 (E) Comment on 11.3.3.1.3.5, step H)
     
     The first sentence should end with a period, not with a
comma (not sure if I have a dirty copy).

#124 (E) Comment on 11.3.3.1.4, step C)
     
     Consider deleting "The SIM/HBA shall" from the beginning of
the first sentence and capitalizing the following word.

#125 (E) Comment on 11.3.3.1.4, step E)
     
     Delete the second instance of "events".

#126 (T) Comment on 11.3.3.1.5, step A)
     
     The words "the bus number of this HBA" are inappropriate,
since an HBA can have multiple ports, and each port would have
its own path ID.  There is a possible complication if a LUN was
used with more than one port on the failed HBA.  If a LUN were
used with only one port, then replacement text might be "the
specifier of the SCSI port used with this LUN."

#127 (E) Comment on 11.3.3.1.5, step C)
     
     Consider deleting "The SIM/HBA shall" from the beginning of
the first sentence and capitalizing the following word.

#128 (T) Comment on 11.3.4, first paragraph after Table 24
     
     The first paragraph discusses possible CAM Status values
when a driver passes IMMEDIATE NOTIFY CCBs to a SIM/HBA.  Does
the document specify any circumstance when a driver passes such
CCBs to a SIM/HBA other than for the purpose of providing or
adding to a list of such CCBs?  If there is no other
circumstance, why would a driver provide any of those status
values?
     
     Probably this paragraph should be deleted or else text added
somewhere to explain a circumstance where passage of such CCBs
with such status values makes sense.

#129 (T) Comment on 11.3.5, second paragraph after Table 25
     
     The paragraph discusses possible CAM Status values for a
NOTIFY ACK CCB passed from the SIM/HBA to the driver.  Does the
document specify any circumstance where a NOTIFY ACK is passed
|from SIM/HBA to driver?  If not, either delete this paragraph or
add text somewhere explaining the circumstances.

#130 (T) Comment on 11.3.5, second paragraph after Table 25
     
     The paragraph discusses possible CAM Status values for a
NOTIFY ACK CCB passed from the SIM/HBA to the driver but does not
list any possible values.  If the paragraph is not deleted,
values should be listed.

#131 (E) Comment on 11.3.5, last paragraph
     
     In "is delivered buy", "is" should be "are" and "buy" should
be "by".

#132 (E) Comment on 11.3.6, Step D) 4) a) for drivers
     
     Change "Length, shall" to "Length.  These fields shall" to
be consistent with step D) 5) a).

#133 (E) Comment on 11.3.6, step D) 5) e) for drivers
     
     The first sentence ends with two periods.  Delete the extra.

#134 (E) Comment on 11.3.6, step D) 6) for drivers
     
     In the last sentence, change "is greater" to "larger".

#135 (E) Comment on 11.3.6, paragraph for SIM/HBA
     
     In the paragraph that starts "When the SIM/HBA receives
...", insert "a" after "receives".

#136 (E) Comment on 11.3.7
     
     For the CAM status value "Cannot Provide Requested
Capability," for reason C) the text is not indented consistently
with A) and B).

#137 (T) Comment on 11.3.7
     
     The descriptions of the fields "Pointer to Target CCB list"
and "Pointer to Immediate Notify CCB list" both fail to describe
the format of a list.  A pointer to Table 22 is nearly
sufficient.  The title of Table 22 appears inappropriate for a
list of Notify CCBs.  Perhaps the title of Table 22 should be
simply "CCB List".

#138 (T) Comment on 11.3.8.2, step A)
     
     Change "not set" to "set" following "If the disconnect
privilege bit is".  (Currently step A is inconsistent with text
in 11.2.2 on page 55 and 11.2.4 on page 58).

#139 (E) Comment on 11.3.8.2, step A)
     
     In the note, clause 11.3.3 seems to be a poor cross-
reference.  Clauses 11.2.2 and 11.2.4 seem to have clearer text.
     
     The solution is probably to put clear text into 11.3.3 or
some other place and have the note reference the clear text.

#140 (E) Comment on 11.3.8.2, step F)
     
     The first sentence of this step seems to specify the same
action that step A) would already have performed.  Should this
sentence be deleted?  Should step A) be deleted?

#141 (T) Comment on 11.3.8.2, step G)
     
     "CDB completion" should be "CDB received".

#142 (T) Comment on 11.3.8.3
     
     In the title of this clause and in the first sentence, "CDB
completion" should be "CDB received" in both places.  In the
title, capitalize "Received".

#143 (E) Comment on 11.3.8.3
     
     In step A), it may be helpful to spell out how to fill in
some of the fields, particularly the callback completion
function.  Perhaps after "the callback completion function" add
(which shall be the Host Target Mode peripheral driver's Continue
Target I/O callback completion function)".

#144 (T) Comment on 11.3.8.3
     
     After step A), consider inserting text to say that, whether
the Accept Target I/O CCB is re-used or not, the SIM/HBA does not
use it again until it is reissued by the driver.

#145 (E) Comment on 11.3.8.4, step G) 2)
     
     The sentence should end with one period, not two.

#146 (E) Comment on 11.3.8.4, step G) 4)
     
     After "the CCB", change "has" to "have".

#147 (T) Comment on 11.3.8.6
     
     In step B) for command reception errors, the words "in
incoming the CDB" do not make sense.  Probably the two middle
words were transposed.
     
     Even with that correction, it is not clear from the text
whether these words are intended to cover the cases of a CDB
length error or of an unsupported command Group code.  If both of
these cases are intended to be covered, then perhaps the words
"If the condition was an error in incoming the CDB" should all be
simply deleted, since this set of steps already assumes some kind
of error in the CDB or its reception.

#148 (E) Comment on 11.3.8.6
     
     In the paragraph that starts "If the SIM/HBA detects Data
phase, ...", delete "or" before "Message Phase" and delete the
comma that follows "errors".

#149 (E) Comment on 11.3.8.6
     
     There are two paragraphs that begin "The Host Target Mode
peripheral driver shall be ...".  In each of these, insert "for"
before "the creation" and insert "of the" after "preservation".

#150 (E) Comment on 11.3.8.7
     
     In the second bullet under "initial connection," change
"messages" to "message" (singular) and change "has" to "have"
(plural).

#151 (T) Comment on 11.3.9 and 11.3.10, Tables 27 and 28
     
     In each table, the autosense residual length field should be
"1", not "2".

#152 (E) Comment on 11.3.11, step A) for a driver
     
     Delete the comma.

#153 (E) Comment on 11.3.11, step D) for a driver
     
     Inside the parentheses, change "if" to "of".

#154 (T) Comment on 11.3.11, step C) for a SIM
     
     Either in this step or in a new step, state that the ENABLE
LUN CCB shall be returned with a CAM Status of Request Completed
without Error.

#155 (E) Comment on 11.3.12
     
     Clause 11.3.2.1 step A) 6) talks about "registered" LUNs
whereas clause 11.3.2.2 step A) 6) talks about "enabled" LUNs.
The same word should be used in both places.  Probably "enabled"
is better.

#156 (E) Comment on 11.3.12.2
     
     In step A) 1) b) "SIM" should be "SIM/HBA".  (Like in
11.3.2.1.)

#157 (E) Comment on 11.3.12.2
     
     In step A) 5) change "an" to "a" before "NOTIFY".  (Like in
11.3.2.1.)

#158 (E) Comment on 11.3.12.2
     
     In step A) 6), insert "be" into "shall cleared".  (Like in
11.3.2.1.)

#159 (E) Comment on 11.3.13, last paragraph
     
     Case C should be "All other commands" (plural).

#160 (T) Comment on 12
     
     It is unclear how engines are told to process data.  The
last paragraph, which talks about the destination data length,
destination data maximum length, and source residual length,
implies that EXECUTE ENGINE CCBs are used.  By contrast, the
second and third paragraphs imply that data is first submitted by
entirely unspecified means, only after which the EXECUTE ENGINE
REQUEST CCB is used for actual transmission.
     
     However, if EXECUTE ENGINE CCBs can be used both to submit
data to an engine and also to tell the SIM/HBA to send processed
data, there should be a way to specify which of these uses is
intended.
     
     The CAM document should be more explicit either on how
EXECUTE ENGINE CCBs are filled in for the two different purposes,
or else on the fact that the document describes only one of these
purposes.

#161 (T) Comment on 12.1, Table 29
     
     The table should specify the size of the CCB Length as "2".

#162 (E) Comment on 12 and 12.2
     
     Clause 12 mentions "EXECUTE ENGINE REQUEST CCB" twice.
Clause 12.2 (third paragraph) mentions "execute engine CCB" once.
Table 30 is headed "EXECUTE ENGINE CCB".
     
     These should be consistent as to whether "request" is
present or not.
     
     These should be usually consistent regarding whether all
upper case, all lower case, or first letter upper case should be
used.

#163 (E) Comment on Annex A
     
     The title should start "Annex", not "ANNEX".

#164 (E) Comment on Annex B, first sentence
     
     Change clause "17" to "11".

#165 (T) Comment on Annex B.1.1 and B.1.2
     
     Clause B.1.2 (two times out of three) and B.1.1 (zero times
out of one) shows the driver setting targetCCB.camStatus.  For
consistency, either delete the two or add two more.

#166 (E) Comment on Annex B.1.1
     
     The first assignment should be to "target1CCB" rather than
"targetCCB1", for consistency with the rest of B.1.1 and B.1.2.

#167 (E) Comment on Annex B.1.1
     
     Following the note, "3nable" should be corrected.

#168 (E) Comment on Annex B.1.1 and B.1.2
     
     For the third from last statement in each of these clauses,
"enableCb" should be "enableCCB".

#169 (E) Comment on Annex B.1.2
     
     In the assignment immediately above the Note, "[n]" should
be "[n-1]".

#170 (T) Comment on Annex B.1.3
     
     If camStatus should be set in B.1.1 and B.1.2, probably it
should be set in B.1.3.

#171 (E) Comment on Annex C, second sentence
     
     The sentence, which starts with "The contents ...", should
be deleted or updated for a real standard.

#172 (T) Comment on Annex C
     
     There appear to be no definitions for the IMMEDIATE NOTIFY
CCB and the NOTIFY ACKNOWLEDGE CCB.

#173 (T) Comment on Annex C
     
     The definition of structure ccb_en_lun lacks the pointer and
count for the IMMEDIATE NOTIFY CCBs and the SIM private area.

#174 (E) Comment on Annex C
     
     The Defines for the CAM Flags field in the CCB header appear
to be specific to one endian vs. the other.  Consider changing
the definitions to be a byte each rather than 32 bits, or
consider adding a comment that these definitions may have to
change for some architectures.

#175 (T) Comment on Annex C
     
     The define for the CAM Flag with value 0x00010000 (perhaps
CAM_SG_List_Phys) is missing.  Consider adding it.

#176 (E) Comment on Annex C
     
     The last two defines belong with the Phase cognizant mode
flags and should not be separated.  Consider moving them.

#177 (E) Comment on Annex C
     
     In the comments of the last three defines for asynch
callback CCB fields, "A" should be "An".  For example, "A
unsolicited" should be "An unsolicited".

#178 (E) Comment on Annex C
     
     In the third define for engine inquiry, "lossly" should be
corrected.

#179 (T) Comment on Annex C
     
     The defines for engine inquiry algorithms all have value
0x00.  The last three should be corrected to 0x01, 0x02, and 0x03
respectively.

#180 (E) Comment on Annex C
     
     If the list of CCB definitions changes (e.g., add IMMED
NOTIFY or NOTIFY ACK), the definition of ccb_size_union should
change to match.
     
     GENERAL COMMENTS
     
     General comments are those that are not easily limited to a
single clause.

#181 (E) Alignment of clause titles
     
     In the Table of Contents, most clause numbers appear to be
followed by two blanks but some are followed by one.  Clause
numbers apparently followed by a single blank are 1, 2, 4, 5.2,
6, 6.3, 6.4, 7, 7.4.1, 7.4.2.1, 7.5, 8.2.1 through 8.2.5, 9.2.1,
9.2.6, 10.1, 10.1.2.5, 10.1.7, 10.1.20, and all of clause 11
except for 11.3.3.1.3.4 and clause 11 itself.  Number 10.2
appears to be followed by 3 blanks.  The clause headings appear
to have the same number of blanks where they appear in the body
of the document.  It seems preferable to use the same number of
blanks consistently.

#182 (E) Alignment of clause titles
     
     There are no clauses B.2 or 11.3.3.1.2.2, so there should
not be clauses numbered B.1 or 11.3.3.1.2.1.

#183 (E) Comment on word usage
     
     In general, "shall be responsible for <verb>ing" can be
replaced with "shall <verb>".

#184 (E) "NULL" vs. "zero" for pointers
     
     In the third and second from last paragraphs of 11.3.6
(steps E) and F) that a SIM/HBA performs upon receipt of a Host
Target Mode ENABLE LUN CCB), usually a pointer is checked to see
if it is non NULL.  However, in the first line of step E), "non
zero" is used instead.
     
     In 11.3.7, when the pointer to Target CCB list field is
described, for a disable LUN request this field shall be "zero".
     
     If it makes a difference whether NULL or zero is used for
pointers, probably the document should be electronically scanned
to check for cases where "zero" or "NULL" is used incorrectly.

#185 (E) Formatting and punctuation
     
     There were instances, not noted above, of unneeded or
missing commas, of extra blanks, of missing blank lines, and of
extra blank lines.

#186 (E) Comma-delimited lists
     
     Sometimes the document has lists such as "A, B and C" with
no comma after B.  An example is in 3.1.14  Other times, there is
a comma after "B", for example the end of the first paragraph in
7.3.2.  Consistency would be desirable.

END OF COMMENTS
     
     
                         Sincerely,



                         Lansing J. Sloan






More information about the T10 mailing list