More about parsing, and a reference.
[toils-of-ais:toils-of-ais.git] / toils.txt
1 = The Toils of AIS: A Case Study in Application Protocol Design And Analysis =
2 Eric S. Raymond <esr@thyrsus.com>, Kurt Schwehr <kurt@ccom.unh.edu>
3
4 == Introduction ==
5
6 The authors have written several decoders for the rather complex AIS
7 protocol used by marine safety and navigation systems.  Based on this
8 experience, we put forward some lessons learned and design principles
9 that we think should be heeded in the extension of AIS and the design
10 of future application protocols.  We also offer pragmatic advice to
11 those implementing decoders for AIS and similar application
12 protocols.
13
14 == Overview of AIS ==
15
16 The Marine Automatic Identification System (AIS) is a software,
17 hardware, and radio coding protocol that allows ships to broadcast
18 navigational and other status information for use in collision
19 avoidance, navigation, and traffic management.  Early design work on
20 it was done primarily by the Sweden; the International Association of
21 Lighthouse Authorities (IALA) proposed the concept to the
22 International Maritime Organization (IMO) in 1995 <<IALA2004>>.  The
23 core AIS standard is now maintained by the International
24 Telecommunications Union (ITU) in association with IMO <<ITU1374>>.
25
26 Both the design of AIS and the process by which it evolved are
27 representative of a large class of application protocols in the real
28 world, especially those concerned with geolocation and geographic
29 information systems. A marked feature of AIS, however, is that due to
30 the hazards of operation at sea the information it handles can be
31 immediately life-critical.  This gives software defects in decoders a
32 special significance and raises the stakes in our design analysis.
33
34 The physical layer of AIS uses a self organizing (SO) variant of Time
35 Division Multiple Access (TDMA) packet radio to avoid collisions among
36 AIS transmitters serving either of two operating frequencies
37 <<LANS1996>>.  For the discussions in this paper, the physical layer
38 can be largely ignored and AIS viewed as a mechanism for passing
39 around binary datagrams in either an addressed or broadcast mode.  For
40 AIS purposes an "address" is a Maritime Mobile Service Identity
41 (MMSI), a 9-digit numeric tag associated with a ship or shore
42 station.
43
44 The binary datagrams have a fixed header containing a dispatch field
45 (the type) followed by information that varies by type in complex ways.
46 Payload information is encoded mainly as packed numeric bitfields
47 of lengths varying from 1 to 30; these may be interpreted as
48 boolean flags, unsigned or signed two's-complement big-endian integers,
49 indices into controlled vocabularies, or (implicitly, via scaling
50 formulas) as fixed-point real numbers.  Some messages have longer
51 regions that are interpreted as character strings or treated as
52 opaque binary blobs to be passed to from or to helper applications.
53
54 Typical data items to be extracted from AIS bitfields include
55 latitudes, longitudes, vessel course and speed, capabilities
56 of the transmitting vessel or station, and weather or 
57 safety conditions. Some message fields are passed solely for the
58 AIS system's own housekeeping functions.
59
60 In practice, software engineers are unlikely to encounter AIS
61 datagrams in raw binary form. AIS receivers commonly make them
62 available over RS422, RS232 and USB ports in an ASCII-armored
63 byte-stream form called AIVDM/AIVDO, a profile or variant of the NMEA
64 format commonly used in shipboard navigation and control systems.
65
66 The design of AIS is optimized to make efficient use of scarce radio
67 bandwidth. In this it resembles a great many application protocols
68 which tight-pack every bit - either out of rational economy or (more
69 commonly) because the designer's mental habits were formed in a time
70 when bandwidth was far more more expensive than it is today.
71
72 Raymond maintains a programmer's-eye view of the details of
73 AIS/AIVDM/AIVDO is <<RAYMOND1>>.  Since that document is available
74 from any browser, we choose not to burden this paper with duplicative
75 details about datagram formats (but see the layout of the Common
76 Navigation Block in the next section for a representative example, the
77 payload of the three most common message types).  We will refer to
78 <<RAYMOND1>> frequently, and readers are assumed to be familiar with
79 it before proceeding.
80
81 == Complexity kills ==
82
83 // FIX: reference for scaling of bugs with ^2 of LOC
84
85 It is hardly news that software defect rates rise with the complexity
86 of the software.  Software bugs frequently arise from unplanned
87 interactions between different parts of a codebase.  It follows that
88 defect rates scale roughly as the square of codebase size. Raymond
89 <<CATB>> amplified previous observations in <<MMM>> that bugs tend
90 to cluster at the interfaces between code written by different people;
91 thus, defects also rise as the square of the number of coders on a
92 project.
93
94 In life-critical systems such as AIS, software defects can kill people. 
95 Software complexity should therefore be viewed as an actual danger, 
96 a cause of avoidable deaths.  Simplicity saves lives.
97
98 The benefits of software simplicity in non-life-critical systems,
99 while less dramatic, are no less real.  Defects incur downstream
100 problems and maintainance costs; thus, software complexity should be
101 viewed as a burden that does not end when the project ships, but
102 which continues to incur costs over the entire service life of the
103 software.
104
105 Complex application protocols require complex software to interpret
106 them.  Thus, application protocol complexity entails software complexity, 
107 which entails quadratically rising defect rates, which in life-critical
108 systems implies avoidable deaths.
109
110 Accordingly, a central problem with AIS - and many other application
111 protocols resembling it - is that it is exceedingly complex.
112
113 The problem is well indicated by the bulk of the base specification,
114 <<ITU1371>>.  In the current Version 4 there are 27 message types with
115 lengths varying from 72 to 1008 bits, described by 142 pages of dense
116 standarsese. It is supplemented by two International Marine
117 Organization circulars (<<IMO236>> and <<IMO289>>) defining 24
118 additional message subtypes in 78 additional pages of standardsese.
119 The AIVDM/AIVDO ASCII packet format is described in yet another
120 standard, <<IEC-PAS>>.  When taking into account the sub messages, the
121 specifications allow for more than 262K message types.
122
123 // FIX: Kurt needs to calculate the total number of possible messages
124 // in the existing design.
125
126 There is a common paraphrase of a quote by Albert Einstein that
127 advises us to "Make everything as simple as possible, but not
128 simpler." Some part of AIS's complexity is essential to its function.
129 (For example, any application protocol that conveys numeric data has
130 to have rules about how it is represented in the bits.)  Other parts
131 of its complexity are accidental, simply a result of unfortunate
132 design decisions.
133
134 // This next paragraph is repetitive here.  Suggest moving it to conclusion.
135
136 Again, life-critical systems concentrate the mind wonderfully.  In an
137 application domain like AIS's, bad protocol-design decisions are not
138 merely annoying but (because of the way they feed through into
139 increased code complexity and defect rates) actually dangerous.
140
141 The most prevalent cause of bad protocol-design decisions is not
142 individual incompetence, but rather various sorts of cultural
143 blindness and the design process.  Experienced software engineers
144 learn to recognize - and dread - the signs of an application protocol
145 designed by domain specialists in a closed environment who do not
146 understand how to avoid accidental complexity, or gravely underweight
147 its costs.
148
149 We will anatomize in detail the accidental complexity of AIS.  In so
150 doing, we intend to illustrate by inversion how application-protocol 
151 designers can avoid costly and dangerous mistakes.
152
153 == How complexity rises ==
154
155 Analyzing datagrams in a protocol like AIS is formally similar to
156 parsing a context-free grammar (CFG).  The goal, in both cases, is to
157 digest a serial stream of incoming bits from an external source into
158 an internal representation that uses the native data formats of the
159 interpreting computer. This internal representation may then be used
160 in any number of ways (e.g. visualization, report generation, and
161 interpretation as a command sequence leap to mind).
162
163 Parsing techniques for CFGs found in textual formats such as computer
164 languages and document markups are a much-studied area of computer
165 science, well-described in classics such as <<ASU>>.  Though it is
166 less practiced, application of these same techniques to binary
167 datagrams and streams remains valid for practical purposes and for
168 estimations of algorithmic complexity.  What specifically concerns us
169 in this paper is to understand how to hold the complexity of the
170 parsing stage to a minimum.
171
172 A CFG's complexity (and the complexity associated parsers) is
173 proportional to the number of productions (a.k.a. parsing rules)
174 required to describe it.  The analog of a terminal symbol in the
175 grammar is a bitfield length and type, where 'type' in this context
176 inclues not just numeric kind but associated interpretive data like
177 offsets, scaling constants, and controlled-vocabulary lists.
178
179 Furger, complexity in CFGs tends to have have a Pareto's-law-like
180 distribution: small irregularities and exception cases in some 20% 
181 of the language produces large ripple effects in the difficulty of
182 parsing the other 80%.  Accordingly, another class of problem to look
183 out for is exception cases to general rules.
184
185 With this model in mind, let us tour the AIS message types in sequence,
186 as an implementor generally would, looking at the specific ways they
187 add complexity to the implied CFG.  For the moment, ignore the many
188 issues about the inventory of terminal symbols (bitfield types and
189 interpretations), just as we would normally ignore most lexical issues 
190 in estimating the parse complexity of a conventional CFG. The boundaries
191 among terminal symbol types are disputable, and the counts we give 
192 below should be considered approximations for scale-estimation purposes.
193
194 === Types 1 through 4: Fixed-length felicity ===
195
196 Begin by considering the first three AIS message types, grouped as
197 "Position Report Class A", but ignore the trailing communication
198 state. These differ only in type number and its interpretation, which
199 is outside the parser's scope.  They can therefore be regarded as one
200 production in the grammar; in <<RAYMOND1>> it is called the Common
201 Navigation Block or CNB.
202
203 .Common Navigation Block
204 [frame="topbot",options="header"]
205 |==============================================================================
206 |Field   |Len |Description             |Type         |Units and Meaning
207 |0-5     | 6  |Message Type            |unsigned int |Constant: 1-3
208 |6-7     | 2  |Repeat Indicator        |unsigned int |Message repeat count
209 |8-37    |30  |MMSI                    |unsigned int |9 decimal digits
210 |38-41   | 4  |Navigation Status       |enumerated   |Moored, under way, etc.
211 |42-49   | 8  |Rate of Turn (ROT)      |signed real  |Degrees per minute
212 |50-59   |10  |Speed Over Ground (SOG) |unsigned real|Meters per second
213 |60-60   | 1  |Position Accuracy       |boolean      |High-accuracy flag
214 |61-88   |28  |Longitude               |signed real  |Minutes/10000
215 |89-115  |27  |Latitude                |signed real  |Minutes/10000
216 |116-127 |12  |Course Over Ground (COG)|unsigned real|Degrees from true north.
217 |128-136 | 9  |True Heading (HDG)      |unsigned int |Degrees from true north.
218 |137-142 | 6  |Time Stamp              |unsigned int |Second of UTC timestamp
219 |143-144 | 2  |Maneuver Indicator      |enumerated   |
220 |145-147 | 3  |Spare                   |             |Not used
221 |148-148 | 1  |RAIM flag               |boolean      |Receiver Autonomous 
222                                                       Integrity Monitoring 
223                                                       in use?
224 |149-167 |19  |Radio status            |bitmask      |Status bits for cell radio
225 |==============================================================================
226
227 The CNB is fixed-length and has a fixed sequence of sixteen fields,
228 spanning sixteen types, in 160 bits.  It is thus dead-simple to parse.
229 In C, one could easily decode the bits with no moving parts (formally, no
230 control logic) by reading the entire datagram into memory (where it
231 would take up a grand total of 20 bytes) and casting it into a
232 structure full of bitfields (which, on a little-endian machine, would
233 alas have to be flipped end-to-end).  From a reliability-engineering
234 point of view, this is a best case scenario and a very promising start.
235
236 Message type 4, "Base Station Report", is also fixed-length and
237 fixed-sequence and can thus also be parsed with no moving parts.
238 While it introduces nine new field types (including our first controlled
239 vocabulary index) the increase in overall complexity is low.
240
241 === Type 5: The six-bit blunder ===
242
243 With message type 5, "Ship static and voyage related data", complexity
244 begins to rise.  This type is still fixed-length with a fixed sequence
245 of 21 fields, and introduces only five new types. One of the new types
246 is, however, dramatically more complex to decode than the fixed-length
247 numerics and flag bits we've been dealing with so far. Three of the
248 Type 5 fields (Call Sign, Vessel Name, and Destination) are
249 character-string data in a 64-bit subset of ASCII packed as 6-bit
250 nybbles.
251
252 This is a paradigm for the sort of fixation on tightest-possible bit
253 packing that makes software engineers blanch.  Before this 6-bit data
254 can be used, it needs to be unpacked into conventional 8-bit bytes.
255 Not only have we lost the simplicity of being able to decode the
256 message just by statically slicing it into fixed-length bitfields, the
257 moving parts of the unpacking logic turn out to be easy to get wrong
258 in ways that are tricky to diagnose.  Note this is not a merely
259 theoretical criticism; Raymond found a longstanding bug in a
260 preexisting AIS decoder exactly here.
261
262 The fact that these strings aren't coded in byte-aligned 8-bit ASCII
263 or UTF-8 is the first serious blob of accidental complexity in AIS.
264 The 6-bit data occupies 262 bits of a 424-bit message format in 47
265 nybbles. The cost of 8-bit-ASCII would have been a 22% increase in
266 message length.  At the type 5 transmission interval and data rates
267 prescribed in <<ITU1371>> this implies an additional transmission cost
268 on the close order of a tenth of a second every six minutes.
269
270 // FIX: Kurt needs to calculate out the bit rate as a double check
271
272 Thus, the designers of AIS incurred a substantial increase in the
273 complexity of decoders in order to save the equivalent of two tenths
274 of one percent of a duty cycle.  This is our first "Never, *ever* do
275 this!"  It is a blunder that could only arise from being fixated on
276 hardware-layer economy while ignoring the defect-rate implications and
277 testing costs for the software layer.
278
279 Furthermore, over time bandwidth tends to become less expensive while defect-
280 and maintainance-related costs in software tend to remain steady or
281 rising.  Thus, the choice that was a bad tradeoff in 2001 when <<ITU1371>>
282 first issued looks worse today, ten years later.  It will look still
283 worse ten years from now.
284
285 // They standards folks are even more worried about the bandwidth
286 // today compared to back then.
287 // The assumption is that there may be other data channels to ships,
288 // but critical AIS hardware on ships will be these same two pathetic
289 // data channels for the next 20-30 years. -kurt
290 // FIX: Kurt: Am I correct about that 2001 issue date?
291
292 === Type 6 and 8: Dynamic allocation is not your friend ===
293
294 With type 6, "Addressed binary message", two more forms of complexity
295 are introduced. One is minor and arguably essential; the other is
296 major and completely accidental. We'll consider types 6 and 8
297 together, as type 8 is structured in essentially the same way as 6
298 except for omitting destination information and housekeeping
299 information for point-to-point trasnsmission; it is instead designed
300 for broadcast messages.
301
302 The minor increment is that message types 6 and 8 have a bit length
303 that is variable rather than fixed.  These messages are a wrapper
304 around a binary payload of up to 920 (type 6) or 952 (type 8) bits,
305 which is the last field.
306
307 In the specific context of AIS, this sort of variable-length payload
308 poses no special difficulty.  Because the message length tops out at
309 1008 bits = 126 bytes, it is feasible to unpack it in a static buffer 
310 of maximum size and ignore the tiny amount of waste space.
311
312 This is not in general true of application protocols with bulkier
313 payloads, for which handling variable-length datagrams often requires
314 dynamic memory allocation.  And, in languages like C or C++ without
315 automatic garbage collection, dynamic-memory allocation is a notorious
316 source of defects.  Indeed, many audits of large C/C++ codebases have
317 found it to be the single worst source of data corruption, security 
318 problems, and crash bugs.
319
320 // ^ Perhaps cite something like Deep C Secrets (someone stole my
321 // copy) assuming Peter talks about memory alloc problems, which
322 // I am pretty sure he does.
323
324 Application-protocol designers should therefore think twice before
325 incurring this complexity as a side effect of their designs.  But at
326 least this is often essential complexity, a kind that is entailed
327 in the application requirements.
328
329 Unfortunately, interpretation of types 6 and 8 introduces another kind of
330 complexity that is completely accidental and (in the AIS context) far
331 worse.  Interpretation of the binary payload is both variable and
332 ambiguous.
333
334 Early versions of the base AIS specification reserved 16 bits before
335 the actual payload as an "application identifier".  The intention for
336 types 6 and 8 at that time appears to have been as a conduit for
337 private and encrypted data.  The world's Coast Guards and Navies are
338 known to use AIS this way ("blue force AIS" or E-AIS) .
339
340 // FIX: The IAI was always two separate numbers.    Kurt will double
341 // check this
342
343 A later annex (the history of this development is murky, as revisions
344 below ITU1371-4 were paywalled and there is no publicly accessible
345 history or rationale) subdivided the "application identifier" into a
346 10-bit "designated area code" (DAC) and a six-bit "functional
347 identifier" (FID).
348
349 Messages 6 and 8 then bacame an extension mechanism that controlling
350 authorities for a designated area could use to define their own
351 payload formats without extending or revising the base standard.  The
352 St. Lawrence Seaway (DACs 366 and 316) and the International Maritime
353 Authority (DAC 1) promptly did so.
354
355 // FIX: The community suffers from no official central registry of
356 // numbers.  And no requirement to internationally publish message defs
357 // cite ref of Alexander and Schwehr proposing said registry
358
359 While this may have been bureacratically convenient, the result was a
360 confusing proliferation of message subtypes, some pushed through
361 without adequate review (for example, <<IMO236>> contains obvious
362 signs of drafting errors in the FID=12 "Number of persons on board"
363 specification). As of early 2011 there are 24 such subtypes in the
364 internatianal DAC alone, requiring approximately as much additional
365 complexity as the entirety of <<ITU1371>>.
366
367 If the result had been to preserve fixed-field simplicity for each
368 message type while merely bloating the overall volume of decoders, the
369 implications for complexity and defect loads would have been worrying
370 but readily manageable.  But the damage did not end there.
371
372 Before, the only field of an AIS message that could act as a dispatch
373 to different bitfield sequences was the message-type field in the
374 header.  Under the new rules, the payload part in these so-called
375 "functional" messages of type 6 and 8 could have any number of
376 different bitfield sequences depending on the joint value of of two
377 more dispatch fields, DAC and FID.
378
379 In one particularly egregious example of misdesign, the IMO289
380 "Weather Observation From Ship" (DAC = 1, FID = 21) sprouted two
381 variants and a *fourth* dispatch field, a flag at bit offset 56 ("Type
382 of weather report")!
383
384 The increment to the minimum complexity of decoders was quite large,
385 larger in fact than the jump from the packed-sixbit blunder.  But the damage
386 didn't even end there, as ships under the jurisdiction of some
387 Designated Areas began sending IMO extension messages with IMO236 or
388 IMO289 FIDs paired with local DACs other than 1.  It became impossible to
389 reliably distinguish IMO special messages from poorly-documented
390 local conventions without a growing exception list. 
391
392 The confusion had become complete. And  this is before we even enter
393 into the additional compexity of the actual special-message payload,
394 which we shall not attempt to describe here.  Sufficiently masochistic
395 readers can find the details in <<RAYMONd1>>
396
397 All this complexity appears, quite understandably, to have  stalled
398 out adoption of the IMO special-message types.  One of us (Raymond)
399 has access to [[AISHUB]], which pools AIS reports for over 150 AIS
400 receivers scattered all over the world, but has yet to unambiguously
401 detect any of the IMO specials in two years of trying.  It is highly
402 doubtful that there is enough volume to motivate vendors of AIS
403 receivers to undertake the expensive task of upgrading their firmware
404 and display applications.
405
406 So all this complexity - and the increased defect rate it implies -
407 may have been self-defeating, loaded on to little or no purpose and
408 reqiring decoder implementations to include essentially useless code
409 in order to check off standards-conformance boxes. 
410
411 Had the ITU stuck with its single original extension mechanism (the
412 type field in the header) and added only new message types with a 
413 fixed bitfield sequence, it seems far more likely that these messages
414 would have achieved useful deployment.
415
416 === Types 7-19: Keeping it simple again ===
417
418 After the spectacular efflorescence of misdesign we saw in types 6 and
419 8, the simplicity of type 7 "Binary acknowledge" is a relief.  It adds
420 no new field types.
421
422 More importantly: this type has a variable bitfield sequence, but
423 only because the payload is a list of MMSIs that may vary from one
424 MMSI to four in length.  This adds almost no complexity in practice as
425 the message is a maximum of 168 bits = 21 bytes long.  With a little
426 care in intializing empty MMSI slots with the out-of-band value of
427 zero, it can usually be treated as fixed-length.
428
429 This sort of case - a fixed bitfield sequence that may be truncated
430 to omit unused fields at the end - will come up again.  As a shorthand
431 we will refer to these layout as "tail-variable".
432
433 Type 9 "Standard SAR Aircraft Position Report" is also very simple;
434 fixed-length, fixed fields, and adding no new field types (with
435 the arguable exception of different scaling for speed over ground).
436
437 Type 10 "UTC/Date Inquiry" is a 72-bit fixed-field message that 
438 introduces no new field types.  Type 11 has a layout identical to
439 type 4 and introduces no new complexity.
440
441 Types 12 "Addressed safety-related message" and 14 "Broadcast
442 safety-related message" are basically the common header followed by a
443 variable-length text field, again of packed-sixbit nybbles.  Maximum
444 message length is 1008 bits = 126 bytes in both cases, so dealing with
445 the variable length doesn't require dynamic allocation.  Since any
446 implementation will have coped with the 6-bit blunder by this point
447 these messages add no significant additional complexity.
448
449 Type 13 "Safety-related acknowledgment" is an acknowledge for a binary
450 broadcast message, identical in layout to type 7 and adding no
451 additional complexity.
452
453 Types 15 "Interrogation" and 16 "Assigned mode command" are used for 
454 housekeeping functions of the AIS network and contain no navigational,
455 ship-status or station-status information. The payload consists of
456 MMSIs and three new field types, slot/offset/increment numbers describing
457 timing and radio paramters.  Both are tail-variable.
458
459 Type 17 "DGNSS Broadcast Binary Message" contains housekeeping information,
460 a latitude-longitude pair, and a trailing binary blob containing differenial-GPS
461 corrections. It introduces no new field types or decoding issues. 
462
463 Type 18 "Standard Class B CS position report" and type 19: Extended
464 Class B CS position report are subsets of the Common Navigation Block
465 for vessels with a less sophisticated navigation and sensor suites.  They
466 introduce no new field types or decoding issues.
467
468 Type 20 "Data link management message" is another housekeeping message
469 type similar to 15 and 16; like them, it is tail-variable and introduces
470 no new decvoding issues.
471
472 === Type 21: Aide to Navigation ===
473
474 Complexity begins to rise again with type 21, the "Aid-to-Navigation report". 
475 This is intended to be broadcast by navigation  markers such as buoys, 
476 lighthouses, and beacons.  
477
478 It is largely unexceptional, introducing no new field types other than
479 a controlled-vocabulary description of the broadcast and a boolean
480 off-position flag, except for one curious detail.  There is a
481 packed-sixbit field available for the name of the navigation mark -
482 but it is split in two.  The first 20 packed-sixbit characters begin
483 after bit 43; a trailing 14 characters, if required, end the message after
484 bit 272.
485
486 This is not of a magnitude with the packed-sixbit blunder or the even
487 worse bureaucratic snafu around the type 6 and 8 messages, but it is
488 careless and annoying.  Why not a single variable-length text field at
489 message end?  The bit of extra code required to glue those segments 
490 together is yet another avoidable failure point.
491
492 Alas, there is much worse to come.
493
494 === Type 22: Channel Management ===
495
496 The "much worse" arrives with message type 22.  It is a fixed-length 
497 housekeeping message introducing five new field types which are neither
498 difficult to understand nor very interesting once understood.  It is
499 likely to be of interest only top those auditing or trobleshooting the
500 AIS network itself.
501
502 But the type 22 message layout has one rather shocking design bug.
503 The span from bit 69 to bit 138 has two different possible
504 interpretations depending on one-bit broacast/addressed flag, a
505 dispatch field which is located at bit 139 *after* the variant fields.
506
507 This means that if you are stream-parsing the datagram, you don't have
508 the information required to interpret the variant fields when you get
509 to them.  The message *must* be entirely buffered in memory to be
510 interpreted.  An entire class of elegant, lightweight analysis
511 techniques resembling stateless LL(1) parsing in a compiler hit this
512 wall and drop dead.  The code complexity of the entire decoder, and
513 its expected defect rate, are pushed upwards substantially.
514
515 When we discuss analyzer implementation in a later section, we will
516 show how this irregularity in the AIS design scuppered the smallest
517 and most lightweight AIS decoder either of us knows to exist.
518
519 === Type 23: Group Assignment Command ===
520
521 Type 23 is similar in structure and function to type 22, a fixed-length
522 housekeeping message introducing a few new field types concerned with
523 AIS administrative functions.  Unlike message type 22, it poses no new
524 decoding issues.
525
526 === Type 24: Class B CS Static Data Report  ===
527
528 AIS has only one more serious botch awaiting us, at least before the
529 set of ITU1371 message types is extended again.  It's in message 24, which
530 not only has two internal dispatch fields and variant sections, but
531 has to be assembled from two datagrams.
532
533 The dispatch fields are "part number" and vessel MMSI.  Part number 0
534 identifies the A datagram of the pair, which will contain common
535 header information and up to 20 packed-sixbit characters of the ship's name.  
536 Part number 1 identifies the B datagram of the pair, which may contain
537 either ship type and dimensions or a parent vessel MMSI, depending
538 on the format of the MMSI in the common header.  (The second format 
539 is intended for use by small auxiliary craft.)
540
541 As usual, multiple dispatch fields and variant sections are defect
542 attractors.  But this design attracts whole new classes of bugs
543 because the message spans two datagrams.  What if the standard's bland
544 assurances that they are expected to be transmitted as an adjacent
545 pair go unfulfilled due to equipment failure, or reception as an
546 adjacent pair is foiled by interference?  What edge casees are
547 possible, and how can we verify that a decoder will cope with them
548 sanely?  What are the potential consequences of different decoders
549 choosing different ways to resolve edge cases?
550
551 More generally, the the split-datagram design implies that a decoder 
552 must retain parsing state between datagrams and be prepared to merge 
553 Part B information into stored Part A information.  This introduces
554 a whole level of data-management complexity that the protocol
555 did not previously require.  Expected defect rates will rise as
556 a direct result.
557
558 === Types 25, 26, and 27: Anticlimax ===
559
560 Type 25, "Binary message, single slot", is a binary message wrapper
561 that combines the capabilities of types 6 and 8.  It differs from 6
562 and 8 in that an acknowledgement is not expected.  It is limited to
563 occupying a single packet-radio slot of at most 168 bits.
564
565 Type 25 introduces no new field types, but has two dispatch flags
566 immediately after the common header that indicate whether the message
567 is broadcast or has a destination MMSI preceding the payload, and
568 whether or not the payload is preceded by a DAC/FID pair.
569
570 Type 25 violates the rule implied in previous message layouts that if
571 a particular bitfield (such as DAC, FID, or destination MMSI) is
572 present, it is always present at the same bit offset.  This might be
573 considered a design defect, but the additional complexity imposed by
574 it on on decoders is fairly small and it is thus at worst a minor one.
575
576 Message type 26, "Binary message, single slot", is an extension of
577 type 25 that can wrap longer binary messages. It introduces one minor
578 new parsing difficulty; the variable-length binary payload is followed
579 by a radio-status field.  This breaks the assumption of all previous
580 message layouts that if a message type has a variable-length paylod
581 section, it is the last field and a stream parser reaching it can
582 consume the rest of the message.  This, too, imposes additional
583 complexity on the parsing machinery and may be considered a minor
584 design defect.
585
586 Message 27 "Long range AIS broadcast message" is a simple subset of the
587 Common Navigation Block intended for satellite reception.  It introduces
588 no new field types nor any new parsing difficulties.
589
590 This completes the analysis of message types in version 4 of the AIS
591 specification.
592
593 == Drawing lessons from the defects ==
594
595 We have so far identified four major and three minor defects in the
596 design of the AIS protocol, each one of which forces higher code
597 complexity - and therefore higher expected defect rates - in
598 conforming decoders.  Each error implies a bit of normative advice
599 for application-protocol designers.
600
601 1. AIS's decision to use packed-sixbit nybbles indexing a 64-bit subset of
602 ASCII chased tiny gains in physical-layer economy for significantly
603 higher decoder complexity.  It is worth mentioning that it also
604 forecloses the use of UTF-8 and proper internationalization of the
605 protocol.
606
607 Lesson: Supposing you must design a packed-binary protocol that
608 contains embedded string data, don't try to get cute with character
609 encodings to save space. You can't squeeze out enough bits to be worth
610 the downstream pain you will cause.
611
612 Each of the other design defects in the AIS protocol violates a
613 regularity that was implicitly present in all datagram layouts
614 previous to the one in which it first occured, escalating parsing
615 complexity for *all* message types.
616
617 2. Message types 6 and 8 broke the rule that the protocol has exactly one
618 dispatch field and each type has a fixed (though possibly
619 tail-variable) bitfield sequence. In doing this, they added a 
620 second extension mechanism to the protocol, and handed off control
621 of various portions of the extension space.  The resulting mess teaches 
622 several important lessons:
623
624 Lesson: Dispatch fields (those which change the logic flow of the
625 parse) are complexity and defect attractors. The complexity cost of
626 having multiple dispatch fields rises not additively but
627 multiplicatively. Well-designed application protocols have just one,
628 period.
629
630 Lesson: One protocol-extension mechanism may be just right, but two is 
631 certainly too many.
632
633 Lesson: Beware especially of extension mechanisms that encourage local
634 options and do not enforce a common namespace in their dispatch
635 fields. Such mechanisms are likely to turn your protocol into an
636 unmanageable hairball in short order.
637
638 Lesson: Suffer not thy protocol design to fall into the hands of
639 bureacrats, for they will smother it in features.
640
641 3. Message type 21 pointlessly split a string field in two. This is a
642 minor defect compared to the other infelicities.  
643
644 Lesson: Don't do this. It adds defect-attracting moving parts to
645 the code and complicates testing.
646
647 4. Message type 22 not only contained a second dispatch field, it
648 located that field *after* the payload section it controlled.
649
650 Lesson: Dispatch fields should always *precede* any payload for which
651 they modify the bitfield sequence. Otherwise you will foreclose entire
652 classes of simple and lightweight stream-parsing techniques.
653
654 5. Message type 24 has two internal dispatch fields controlling variant
655 sections, and is split across two datagrams.  In addition to the
656 normal complexity costs of handling variant sections, this requires
657 a conforming parser to maintain fragile state between datagrams and
658 introduces lots of tricky edge cases.
659
660 Lesson: Never do this! The amount of statefulness that the network
661 layers underneath your application protocol imposes on you will be a
662 severe enough source of bugs and edge cases; deliberately fragmenting
663 your application protocol's units of meaning to invite *more* is
664 asking for trouble.
665
666 6. Message type 25 contains optional fields that are not at fixed
667 offsets, adding complexity that might be considered a minor design
668 defect.
669
670 7. Message type 26 contains a variable-length payload field that is not
671 the last one in the message, complicating the handling of variable-length
672 fields in stream parsers. This might be considered a minor design
673 defect.
674
675 To these defects could be added another large one that in a sense
676 precedes all of them.  At the tiny data volumes of AIS, the style of
677 packed-bit binary protocols of which AIS is an example is a colossal
678 error of misdirected and premature optimization, leading to rigidity
679 and unnecessary overcomplexity.  See <<TEXTUALITY>> for a more
680 detailed argument of this position.
681
682 == A tale of four decoders ==
683
684 We shall next examine the ways in which AIS's design defects hindered the
685 development of actual AIS decoders, and how the authors coped. 
686
687 The authors have written four AIS decoders in three different languages.
688 We describe them here in historical order.
689
690 // Kurt: We might want to add Neil Arundale's to this list.
691
692 To put this list in perspective, it should be noted that AIS decoders
693 are a rare species of software.  Web searches turn up few hits, and
694 most of those only interpret a subset of the navigational message
695 types rather than covering the full ITU1371 standard and extensions.
696 It is likely that these represent a substantial fraction of all the 
697 decoders in existence that are at or near full conformance.
698
699 === noaadata ==
700
701 // Kurt: yours
702
703 === GPSD ==
704
705 GPSD is an open-source monitoring daemon for GPSes and other
706 kinematic/geodetic sensors. It turns the raw take from sensors into
707 JSON messages on a well-known TCP/IP port, insulating client
708 applications from the grubby details of vendor protocols and hardware
709 quirks. Besides being a stock piece of infrastructure on Linux and
710 *BSD laptops running location-aware applications, it is extremely
711 widely deployed in embedded systems including cellphones, scientific
712 telemetry packages, and autonomous robotic vehicles including a DARPA
713 Grand Challenge entry and the Woods Hole Institute's deep-diving
714 Nereus submarine.
715
716 One of us (Raymond) developed an interest in AIS through GPSD, for
717 which he is the project lead.  He began work on supporting sensors
718 reporting AIVDM/IVDO in GPSD in 2009, and compiled <<RAYMOND1>> as
719 part of his effort to pull together enough information to do a proper
720 implementation. Schwehr contributed advice and test loads, and the
721 authors became acquainted through cooperating to improve this
722 software. 
723
724 The GPSD AIVDM driver is implemented in approximately a thousand lines
725 of C. At time of writing it has tested support for AIS message types
726 1-15, 18-21, and 24. It has untested support for types 16-17, 22-23,
727 25-27 and most of the IMO extension messages, many of which have not
728 yet been observed in the wild. Conformance was tested by comparison
729 with reports from Schwehr's noaadata driver operating on samples from
730 <<AISHUB>> and elsewhere.
731
732 Most of the driver is hand-coded, because at the time it was constructed
733 the author believed AIS was too irregular for an attempt at driver 
734 code generation based on a protocol specification to work.
735
736 However, in early 2011 Raymond built a small suite of code generators
737 that take any message-layout table from <<RAYMOND1>> as input and
738 generate snippets of C and Python code as output. These snippets
739 include a C structure declaration for the unpacked message data, and
740 driver code to extract the bits into the structure. While these code
741 generators cannot produce all of the the high-level logic required for
742 the AIVDM driver, they do reliably automate the most fiddly and
743 defect-prone parts of datagram analysis.
744
745 The design problems of AIS have not prevented this driver from parsing
746 the full range of message types, mainly because hand-coded C allows an
747 approach of using brute force to overpower those problems.  The
748 resulting code is hardly elegant, but it works for production uses.
749
750 === ais.py ===
751
752 ais.py is an undistributed developer tool in the repository of the
753 GPSD project.  Raymond wrote it as a check on the project's C decoder,
754 using as different an implementation strategy as he could imagine.
755
756 ais.py is approximately a thousand lines of Python code, which includes
757 extensive report-generation features as well as the datagram analysis.
758 Most of the code consists of lists of declarations in a tiny
759 domain-specific language adapted for describing the layout of AIS
760 datagrams; these are interpreted by 250 lines of a relatively simple
761 execution loop.
762
763 While this approach is far more elegant than ad-hoc C code, it runs
764 headlong into AIS's design errors.  The execution loop is essentially
765 a recursive stream parser and cannot handle the post-positioned dispatch 
766 field in message type 22.  It cannot merge the A and B parts of message
767 type 24.  It cannot handle the embedded variable-length string field in
768 message type 26 (though this could be fixed relatively easily by
769 extending the minilanguage). It handles the split string field in message
770 type 21 only via a rather embarassing kluge.  And it does not handle the
771 IMO specials of type 6 and 8 at all.
772
773 As with noaadata, ais.py shows that in a collision between declarative
774 specification and the ugly realities of AIS, declarative specification
775 does not fare very well.
776
777 ==== libais ====
778
779 // Kurt: yours
780
781 == Drawing lessons from the implementations ==
782
783 Lesson: Do a reference implementation *before* you publish an application 
784 protocol as a standard.
785
786 No application protocol with as many design problems as AIS has would
787 have made it out of committee if a reference decoder had been
788 in development in parallel with the specification; implementation
789 problems would have thrown them into sharp relief.
790
791 The IETF (Internet Engineering Task Force) has a custom of not
792 allowing a network protocol design to be published as a proposed
793 standard until it has at least two conforming implementations.  This
794 would be a good practice for everyone else to emulate.
795
796 We would go even further and say that as a best practice, the
797 reference implementation should be open source. In this way, third
798 parties can see exactly what degree of complexity is required ti
799 implement the standard, exerting a valuable pressure towards simplicity.
800
801 Lesson: Design your protocol with a small and consistent set of idioms
802
803 Both of the authors had plans to generate an AIS decoder with at least
804 conditionally provable correctness from a declarative
805 specification. Both efforts (the noaadata decoder and ais.py) failed
806 because AIS is just plain too irregular to be captured this way.
807
808 We recommend that application-protocol designers should, as a routine
809 part of their process, render the design as a specification in <<ASN.1>> or 
810 <<BDEC>>.  If this process is painful and complex, writing a decoder 
811 will also be painful and complex, and the design should be considered
812 broken until that is fixed.
813
814 Lesson: Ship your standard with test pairs.
815
816 Both authors find that, even as mis-designed as parts of AIS are, the
817 single most frustrating thing about writing AIS decoders is not any
818 one of those design problems or even all of them together.  The worst
819 problem is our inability to verify that the code we write is correct.
820
821 This problem could be quite easily be fixed by attaching to the
822 standard a set of test pairs - that is, an example binary datagram
823 in each of every possible variation of message shape together
824 with a textual, human-readable decode of that datagram.
825
826 Shipping test pairs with a standard has particular importance in
827 application protocols for life-critical software, where mistakes can
828 easily kill. But it's good practice everywhere.  The combination
829 of official test pairs with an open-source reference implementation
830 is the most effective means we know of to ensure that a standard
831 is implemented correctly and completely.
832
833 Lesson: Closed, paywalled standards endanger lives.
834
835 While writing our decoders we had occasion to evaluate about a dozen others.
836 For some, such as <<GNU_AIS>>, we could read source code; for others, we could
837 only see sample results and read documentation.
838
839 The completeness and correctness of these implementations was generally poor.
840 Most could handle only a small subset of the AIS messages - typically 1, 2,
841 3, and 5.  We found bugs on even the most superficial examination. It quickly
842 became evident that these limitations were a result of the actual standards
843 being relatively expensive and inaccessible; implementers had been reduced to
844 trying to reverse-engineer the standard from information that had leaked
845 out about it, and not uncommonly made errors in doing so.
846
847 While that situation was alleviated by the publication of <<RAYMOND1>>
848 and later by an ITU policy change that mode <<ITU1371>> available as a
849 free download, those poor implementations are still with us.  Someday,
850 incautious use of one of them might well kill somebody.
851
852 The lesson is clear.  Making a standard expensive to get damages the
853 quality of attempted implementations. This is flat-out unacceptable
854 when the standard is life-critical. Even when it is not, we can expect 
855 the costs and damages imposed by paywalling to greatly exceed the maximum 
856 revenue anyone can ever expect to collect from it; the economist's
857 concept of "deadweight loss" applies with particular force here.
858
859 == Ways forward for AIS ==
860
861 FIX: how do we provide guidance for people who are writing new
862 messages.  Perhaps a paragraph plus a bulleted list of how to approach
863 new messages.
864
865 == References ==
866
867 [bibliography]
868 - [[[RAYMOND1]]] http://gpsd.berlios.de/standards/NMEA.txt[AIVDM/AIVDO 
869   Protocol Decoding]
870
871 - [[[ITU1371]]]
872   http://www.itu.int/rec/R-REC-M.1371-4-201004-I/en[ITU 
873   Recommendation on the Technical Characteristics for a Universal
874   Shipborne Automatic Identification System (AIS) using Time Division
875   Multiple Access in the Maritime Mobile Band]. 
876
877 - [[[IMO236]]] http://www.imo.org/includes/blastData.asp/doc_id=4503/236.pdf[IMO
878    Circular 236: Guidance on the Application of AIS Binary Messages (May 2004)]
879
880 - [[[IMO289]]]
881   http://vislab-ccom.unh.edu/~schwehr/papers/2010-IMO-SN.1-Circ.289.pdf[IMO
882   SN.1/Circ.289 Guidance on the Use of AIS Application-Specific Messages
883   (June 2010)]
884
885 - [[[CATB]]]
886   http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s05.html[The Cathedral and the Bazaar]
887
888 - [[[IEC-PAS]]] IEC-PAS 61162-100, "Maritime navigation and
889   radiocommunication equipment and systems"  The ASCII armoring
890   is described on page 26 of Annex C, Table C-1.
891
892 - [[[AISHUB]]] http://www.aishub.net/[AIS Hub, the AIS data sharing center]
893
894 - [[[TEXTUALITY]]]
895   http://www.catb.org/esr/writings/taoup/html/ch05s01.html[The
896   Importance of Being Textual].
897
898 - [[[ASN.1]]] http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One[ASN.1]
899
900 - [[[bdec]]] http://www.protocollogic.com/[bdec]
901
902 - [[[GNU AIS]]] http://gnuais.sourceforge.net/[GNU AIS - Automatic 
903   Identification System for Linux]
904
905 - [[[MMM]]] Brooks, J. Fred (1995) "The Mythical Man-Month: Essays in Software 
906   Engineering", Addison-Wesley, ISBN 0-201-83595-9
907
908 - [[[ASU]]] Aho, A.V., Sethi, R. and Ullman ,J.D. (1986) "Compilers:
909   principles, techniques, and tools." Addison-Wesley Longman, ISBN
910   0-201-10088-6.
911
912 - [[[IALA2004]]] FIX
913
914 - [[[LANS1996]]] FIX