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
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Author" content="Eric S. Raymond">
<meta name="Description" content="Essay for the Alliance for Code Excellence.">
<meta name="Keywords" content="GPS, gpsd, code, excellence">
<meta name="Revised" content="9 April 2015">
<meta name="robots" content="index,follow">
<link rel="stylesheet" href="main.css" type="text/css">
<title>GPSD and Code Excellence</title>
</head>
<body>
<div id="Header">
GPSD and Code Excellence
</div>
<div id="Menu">
<img src="gpsd-logo-small.png" alt="Small gpsd Logo"><br>
<a href="index.html">Home</a><br>
<a href="index.html#news">News</a><br>
<a href="index.html#downloads">Downloads</a><br>
<a href="index.html#mailing-lists">Mailing lists</a><br>
<a href="index.html#documentation">Documentation</a><br>
<a href="faq.html">FAQ</a><br>
<a href="xgps-sample.html">Screenshots</a><br>
<a href="index.html#recipes">Recipes</a><br>
<a href="index.html#others">Other GPSDs</a><br>
<a href="hardware.html">Hardware</a><br>
<a href="for-vendors.html">For GPS Vendors</a><br>
<a href="wishlist.html">Wish List</a><br>
<a href="hall-of-shame.html">Hall of Shame</a><br>
<a href="troubleshooting.html">Troubleshooting Guide</a><br>
<a href="hacking.html">Hacker's Guide</a><br>
<a href="protocol-transition.html">Application Compatibility</a>
<a href="references.html">References</a><br>
<a href="history.html">History</a><br>
<a href="future.html">Future</a><br>
<div> </div>
<a href='http://www.catb.org/hacker-emblem/'><img
src='http://www.catb.org/hacker-emblem/glider.png'
alt='hacker emblem'></a><br>
<script type="text/javascript" src="http://www.ohloh.net/p/3944/widgets/project_thin_badge.js"></script>
<hr>
<script type="text/javascript"><!--
google_ad_client = "pub-1458586455084261";
google_ad_width = 160;
google_ad_height = 600;
google_ad_format = "160x600_as";
google_ad_type = "text";
google_ad_channel = "";
//--></script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
<hr>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401"
alt="Valid HTML 4.01!" height="31" width="88"></a>
</div>
<div id="Content">
<p>There's a wonderfully tongue-in-cheek project called the
<a href="http://codeoffsets.com/">The Alliance for Code Excellence</a>
("Building a better tomorrow — one line of code at a time.") that
sells Bad Code Offset certificates. They fund open source projects to
produce good code that will, in theory, offset all the bad code out
there and mitigate the environmental harm it does. They've asked
software authors to write essays on how their projects drive out
bad code, offering $500 dollar prizes.</p>
<p>I sat down to write an essay about GPSD in the same vein of high
drollery as the Alliance's site, then realized that GPSD actually has
a serious case to make. We really do drive out bad code, in both
direct and indirect ways, and we supply examples of good practice for
emulation.</p>
<p>GPSD is a service daemon and device multiplexer that is the
open-source world's basic piece of infrastructure for communicating
with GPS receivers, and it's everywhere Linux is - running on PCs, on
embedded systems, and on both OpenMoko and the entire line of Maemo
cellphones. We're directly relied on by dozens of applications,
including <a href="http://www.pygps.org">pyGPS</a>, <a
href="http://www.kismetwireless.net/">Kismet</a>, <a
href="http://www.gpsdrive.de/">GPSdrive</a>, <a
href="http://qpegps.sourceforge.net/">gpeGPS</a>, <a
href="http://www.gnustep.it/enrico/position/">position</a>, <a
href="http://roadmap.digitalomaha.net/index.html">roadmap</a>, <a
href="http://roadnav.sourceforge.net/">roadnav</a>, <a
href="http://www.navit-project.org/">navit</a>, <a
href="http://viking.sf.net">viking</a>, and <a
href="http://gaia.serezhkin.com/">gaia</a>. If you're doing anything
with GPSes on an open-source operating system, GPSD is your
indispensable tool.</p>
<p>GPSD's quality is up to the standard required when you're that
ubiquitous. In March 2007 a <a href='http://coverity.com'>Coverity</a>
scan turned up only two errors in over 22,000 LLOC. In more detail: it
flagged only 4 potential problems, and two of those were false
positives. This is <a href='http://lwn.net/Articles/115530/'>three
orders of magnitude cleaner</a> than typical commercial software, and
about half the defect density of the Linux kernel itself at the
time.</p>
<p>We get, on average, about one defect report every 90 days, and
there are just five on our tracker as I write. Given what we know
about the size of our user base, our low rate of incoming bug reports
tells us we've maintained a similar level of code quality since the
Coverity audit. This hasn't happened by accident. Good practice
matters, and I'll describe how we systematize ours in a bit.</p>
<p>First, though, I want to explain how we drive out bad code. The
reporting protocols used by GPS sensors are a <a
href="http://esr.ibiblio.org/?p=801">hideous mess</a> — the kind
of mess that tends to nucleate layers of bad code around it as
programmers with insufficient domain knowledge try to compensate for
the deficiencies at application level and wind up snarling themselves
up in ever-nastier hairballs. Part of what GPSD does is firewall all
this stuff away; we know everything about the mess so you don't have
to, and we present clean data on a well-known port in a
well-documented wire format. We then provide client-side service
libraries that will unpack GPS reports into native C, C++, Python, or
Perl structures so you don't even have to know about our wire
format.</p>
<p>If our client applications had to deal with the back-end mess of
poorly-specified NMEA 0183 and seventeen different vendor-specific
binary protocols, I for dead certain <em>guarantee</em> that the total
community bug load from GPS-related problems would go up by an order
of magnitude. And I'd bet more than any of the $500 prizes the Alliance is
offering on the bug count going up by <em>two</em> orders of
magnitude.</p>
<p>We also try to drive out bad code indirectly in the same way we
keep our defect level low — by providing an example of good
practice that extends all the way up from our development habits to
the zero-configuration design of the gpsd daemon.</p>
<p>The most important thing we do to ensure code quality is maintain a
rigorous test suite. Our "make testregress" runs just shy of sixty
regression and unit tests. Forty-six of those exercise the daemon's
logic for recognizing and processing device reports; the remaining ten
to a dozen exercise the rest of the code, all the way out to the
application service libraries.</p>
<p>We actively collect device logs and metadata from users through <a
href="https://www.mainframe.cx/cgi-bin/gps_report.cgi">this form</a>,
which we use to update a device-capability database and our collection
of test logs. Almost every time a user fills out one of these, the
number of devices for which we can guarantee good performance in the
future goes up. Currently it's 87 devices from 39 vendors.</p>
<!-- splint was dropped in March 2015 --> <p>We also used to routinely
audit our code with <a href="http://www.splint.org/">splint</a>. Not
many people do this, because splint is very finicky and a pain in the
ass to use and requires you to litter your code with cryptic
annotations. We stopped doing this because splint gave us randomly
variable warnings across different Linux distributions, and has been
obsolesced by newer static analyzers. But I believe accepting that
discipline was the main reason the Coverity scan went so well. After
hacking through the underbrush of false positives, I generally find
that splint heads off about two potentially serious bugs per release
cycle, averaging out to about one every 17 weeks.</p>
<p>We have a policy of not using C where a scripting language will do.
Python is what we mostly use, but not the actual point here (though I
do like it a lot and use it in preference to other scripting languages).
The point is to get away from the fertile source of bugs that is
memory-management in a fixed-extent language. The core daemon is
written in C because it has to be; a significant part of our customer
base is embedded and SBC developers who need to run lean and mean.
But our test tools and some of our test clients are Python, and we're
gradually working to retire as much of the C as possible from outside
the daemon in favor of scripting languages.</p>
<p>We have copious documentation, not just of the <a
href="libgps.html">interfaces to the code</a> and the <a
href="gpsd.html">wire protocol</a> but also to the internals and of
our project practices. We have a <a href="hacking.html">Hacker's
Guide</a> to the project philosophy, design, and code internals. We
have <a href="writing-a-driver.html">Notes on Writing a GPSD
Driver</a> by someone who did it. Because everything is documented,
the project doesn't forget things even if the individual members
do.</p>
<p>No account of good practice can leave out the human element. In
the best open-source tradition, GPSD combines the benefits of a small,
highly capable core group (three developers: Chris Kuethe, Gary
Miller, and myself) with about a half dozen other semi-regular
contributors and a halo of casual contributors numbering in the
hundreds. GPSD teaches by example about the kinds of specialization
that produce good code. Here is what the core group looks like...</p>
<p>Chris Kuethe is our GPS domain expert. He knows the devices, the
mathematics of geodesy, and where all the bodies are buried in this
application area to a nearly insane level of detail. I am the systems
architect — I neither match Chris's depth of domain knowledge
nor want to, but it's been my role to give the GPSD codebase a
strong modular architecture, design and implement our test suites and
tools, design and implement our wire protocols, and push
autoconfiguration as far as it could go. Gary Miller is more of a
generalist who owns some particularly tricky areas of the core code
and device drivers, and is extremely good at detecting bad smells in
other code; he backstops Chris and myself admirably.</p>
<p>If this sounds like a description of a classic "surgical team"
organization straight out of Fred Brooks, that's because it is. Open
source changes a lot of things, and the outer circle of contributors
brings huge value to the GPSD project — but some things about
software development never change, and the power of teams that include
a domain expert, a master architect, and a bogon detector is one of
them. GPSD reinforces a lesson that is old but never stale; if you
want the kind of good code that improves the whole software ecology
around it, that kind of human constellation is a great place to
start.</p>
<p>Finally, we drive out a lot of potentially bad code by eliminating
configuration options. The <cite>gpsd</cite> daemon is designed to
autobaud and recognize GPS or AIS reporting packets on any serial or
USB device that it's handed, no questions asked. And normally, at
least on Linux systems, those devices are handed to it by udev when a
hotplug event fires. Though arranging this took a lot of work, there
are many fewer combinations of code paths in <cite>gpsd</cite> to test
(and to accumulate bugs) than there would be if the daemon had the
usual semi-infinite array of knobs, switches, and config files.
Because client applications don't have to give users any access to
those nonexistent knobs and switches, thousands of lines of
application code have never had to be written either; the simplifying
effects of autoconfiguration ripple through dozens of
application-development groups and all the way up the software stack
to the end-user.</p>
<p>The RFP for these essays asked software authors to explain what
they'd do with a $500 prize. That's easy; we'd use it to <a
href="wishlist.html">buy test hardware</a>. Because GPSes are wacky,
idiosyncratic devices with poorly documented interfaces, testing on
real hardware is vital to fully learn their quirks.</p>
<hr>
<script src="datestamp.js" type='text/javascript'></script>
</div>
</body>
</html>
|
