-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathConventions.html
218 lines (218 loc) · 11.2 KB
/
Conventions.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>OpenLCB Specification Conventions</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.4 (Unix)">
<META NAME="CREATED" CONTENT="0;0">
<META NAME="CHANGEDBY" CONTENT="Bob Jacobsen">
<META NAME="CHANGED" CONTENT="20120917;10530400">
<META NAME="CHANGEDBY" CONTENT="Bob Jacobsen">
<META NAME="CHANGEDBY" CONTENT="Bob Jacobsen">
<STYLE TYPE="text/css">
<!--
H3.cjk { font-family: "SimSun" }
H3.ctl { font-family: "Lucida Sans" }
H4.cjk { font-family: "SimSun" }
H4.ctl { font-family: "Lucida Sans" }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<H1><FONT COLOR="#000000"><IMG SRC="../web/logo-ajs-dph.png" NAME="OpenLCB" ALIGN=RIGHT WIDTH=337 HEIGHT=135 BORDER=2></FONT>OpenLCB
OpenLCB Specification Conventions</H1>
<P>OpenLCB is not a formal standards-making body, but we are
interested in making it clear what's required and not required for
interoperation between OpenLCB nodes. Therefore, we are creating a
series documents that are intended to form a stable basis for OpenLCB
implementors.</P>
<P>At the same time, we're interested in forwarding the NMRA's effort
to create a common standard, so we're proposing documents to them and
cooperating in those discussions. More information on that effort can
be found on a <A HREF="../srpdrafts/index.html">separate page</A>.</P>
<P>We're creating three general types of documents:</P>
<DL>
<DT><I>Standards </I>
</DT><DD>
Standards are agreed to be normative, to the extent that anything
this bunch of happy campers does can be proscriptive. A statement
should be included in a standard when it's "clearly necessary"
and "clearly correct".
</DD><DT>
<I>Technical Notes</I></DT><DD>
These are agreed-to documents that explain a standard and provide
stable information useful to implementors. Statements should be
included in a technical note when they are "likely to be
useful" and "not clearly wrong"; this is a lower
standard than the one for standards. Opinions and less-desirable
options are OK when clearly labelled as such.
</DD><DT>
<I>Development documents </I>
</DT><DD STYLE="margin-bottom: 0.5cm">
These are things that are in significant flux, but still useful to
developers and implementers. One formal type is “Working Notes”,
which are one step below Technical Notes and Standards. They are
intended as the last step before writing the more formal documents.
Others are less formal and can be found in the “<A HREF="../documents">documents</A>”
section of the web site.</DD></DL>
<P>
The first two can appear in "preliminary", "draft"
or "adopted" form. Adopted documents have received
extensive review, and one can rely on their content. "Draft"
documents are complete, but still under discussion. "Preliminary"
documents are still being written, will certainly change very much
during that process, and in general are only of interest to the
people actively working to advance the protocol in that particular
area.</P>
<P>Generally, an implementer should start with the relevant adopted
standards and be sure to understand what's really required for the
implementation to work well. Then, the implementor should move on to
the adopted technical notes to make sure the background is
understood, learn about issues to be considered and decisions to be
made, and get information about possible approaches. Finally, the
implementer may want to spend time on the draft and development
documents to get an idea of what the future might bring.</P>
<P>The work to date is available <A HREF="index.html">here</A> for
Standards and Technical Notes, and <A HREF="../documents/index.html">here</A>
for development documents.</P>
<P>OpenLCB is loosely versioned. Documents can be referenced via
their last change date, which is displayed at the upper right of the
first page of every document. Older versions can be retrieved by date
from SVN. The collection of documents is given a version number, such
as 0.5, on the specification index page. That number is updated when
the specifications (and associated implementations) are changed in a
way that breaks compatibility with existing adopted documents and/or
shipped code. The pre-decimal digit(s) represent fundamental
structures such as basic state machines and protocols; the
post-decimal digit(s) represent minor changes to values and field
sizes.</P>
<H3 CLASS="western">Implementation Points:</H3>
<P>We write stuff in bog-standard Open Office .odf format by
convention. The <A HREF="drafts/Template.odt">drafts/Template.odt</A>
file is a starting point. Leave change tracking on, because that
helps handle collisions between two people who might be editing at
overlapping times. Commit back to SVN early and often to avoid
collisions.</P>
<P>(We have considered DocBook and other formats in the past, may
still go that way, but don't want to invest in the infrastructure
now)</P>
<P>To make direct access easier, the file naming convention is
(wire)(topic)(type).html, in Pascal case (leading-capital camel
case). For example, "CanMessageTransportS.html" vs
"CanMessageTransportTN.html" vs
"TcpMessageTransportS.html". Use "Gen" for the
general case, true for any wire protocol.</P>
<P>"Shall" should get used in standards in preference to
"must". The reason for this is that "The board shall
be flat..." reads as a statement about the board, but using
"must" makes it seem a statement about what you, the
designer or manufacturer, must do. "Must" is OK in
technical notes, which are more information and non-normative:
"Designers must remember that wires get hot..."
</P>
<P>Standards can describe options using "Devices may, but are
not required to, ...", but they can also just be silent about
options.</P>
<P>The various parts of standards should be identified as normative
or informative, because there are always non-normative parts of
standards. Try to keep the informative parts in the explanation
technical note, but when they need to be present so the standard can
be read by itself, be sure to label them clearly.</P>
<P>Generally, standards should use short paragraphs focused on a
single point. Think of the paragraphs as unit tests, which should be
individually satisfied (or not).</P>
<P>Make the status of "reserved" things clear: "Shall
be set to 1 on creation and shall not checked upon reception"
and "Shall be set to 1 on creation, and shall be received as 1
to be considered valid" are different. One works for a bit
that's reserved for some orthogonal future expansion; the other is
needed to define an exclusive (hence non-orthogonal) future option.</P>
<P>Make numbers clear instead of using "large" or "small".
(One web page referred to OpenLCB being usable unchanged on "up
to huge modular layouts", which engendered a long discussion in
July 2011; we decided that meant "up to 4999 nodes" and at
5000 or above you might have to do special things to handle traffic)</P>
<H4 CLASS="western">Considerations</H4>
<P>When designing or documenting a protocol, please address the
following points (note that these aren't goals, but rather possible
problems/complexities that should be addressed):</P>
<UL>
<LI><P>What happens if N nodes want to do this at once? Either
independently or all trying to act in concert with a single target
node.</P>
<LI><P>What happens when a node joins late and wants to take part?
How does the day start?</P>
<LI><P>Are there any critical resources, e.g. single nodes that have
to be present and working?</P>
<LI><P>Where can this be expanded later? Not be expanded later?
How will original (unmodified nodes) interact with expanded ones?</P>
<LI><P>How much buffering does the protocol require? What bounds
that? How are buffer shortages handled?</P>
<LI><P>How are the message priorities allocated? What does this
protocol block? What does it defer to? How does priority order the
various messages in overlapping interactions?</P>
<LI><P>How does the protocol map to CAN, or other limited-size-frame
wire protocols?</P>
<LI><P>Do participant nodes have to have full node IDs for their
targets, or can everything be done with already-known aliases? If
node IDs are needed, how are they acquired?</P>
<LI><P>How much traffic does this generate on a very large layout?
Is that commensurate with the provided function?</P>
<LI><P>Do the protocols respect the “Simple Node” concept? Do
any new MTIs have their simple-node bit set properly?</P>
</UL>
<H4 CLASS="western">Promoting a Document</H4>
<P STYLE="margin-bottom: 0cm">When a document has been judged to be
“adopted”, the technical steps are:</P>
<OL>
<LI><P STYLE="margin-bottom: 0cm">Copy (or if the 1<SUP>st</SUP>
time, <code>svn copy</code>) the .odt file from the specs/drafts/ directory to
the specs/ directory</P>
<LI><P STYLE="margin-bottom: 0cm">Change the specs/ document to say
“Adopted” in the header. Remove “Draft” watermark. Turn on
“Track changes” if it was off. Turn off “show changes”, if
it was on. Make a PDF version.</P>
<LI><P STYLE="margin-bottom: 0cm">Add the specs/ document and .pdf
to the index.html file if needed. Color it green (#00ff00).</P>
<LI><P STYLE="margin-bottom: 0cm">Change the specs/drafts document
to say “Preliminary” in the header. Accept all changes to remove
them from the log. Turn on “Track changes” if it was off. Make a
PDF version.
</P>
<LI><P STYLE="margin-bottom: 0cm">Add the specs/drafts document and
.pdf to the index.html file as "future version" if needed. Reset its color to the
default.</P>
<LI><P STYLE="margin-bottom: 0cm">If the document includes any
figures from the images/ directory, <code>svn cp</code> them
from specs/drafts/images to specs/images/.</P>
<LI><P STYLE="margin-bottom: 0cm">If the document includes any
message state diagrams from the mscgen/ directory, <code>svn cp</code> them
from specs/drafts/images to specs/images/. Run <code>make</code>
in the mscgen/ directory and <code>svn add</code> any new files.</P>
<LI><P STYLE="margin-bottom: 0cm">Commit all to SVN with a common
comment.</P>
</OL>
<P STYLE="margin-bottom: 0cm"><BR>
</P>
<P STYLE="margin-bottom: 0cm"><BR>
</P>
<P STYLE="margin-bottom: 0cm"><!-- ........................................................................ ->
<P STYLE="margin-bottom: 0cm"><!-- The following used to be in the document, and perhaps can
go back, but it's not true now. Commented out until that
is sorted.
<H2>Structure</H2>
<P STYLE="margin-bottom: 0cm">The primary documents in this directory
are in XML DocBook format under SVN control. Each time these are
updated, the HTML and PDF versions linked above are automatically
created from the primary documents. The HTML and PDF files are not
kept in SVN.</P>
--><BR>
</P>
<HR>
<P>Site hosted by <FONT COLOR="#000080">
<A HREF="http://sourceforge.net/projects/openlcb"><FONT COLOR="#000080"><IMG SRC="http://sflogo.sourceforge.net/sflogo.php?group_id=286373&type=13" NAME="graphics1" ALIGN=ABSMIDDLE WIDTH=120 HEIGHT=30 BORDER=2></FONT></A></FONT>
</P>
<P>This is SVN $Revision$
</P>
</BODY>
</HTML>