Add a man page for Chris's firmware uploader, remove the README it replaces.

Merge his patch moving an include.

1 files changed, 92 insertions, 0 deletions

diff --git a/gpsflash.xml b/gpsflash.xml
new file mode 100644
index 00000000..c751ec70
--- /dev/null
+++ b/gpsflash.xml
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC 
+   "-//OASIS//DTD DocBook XML V4.1.2//EN"
+   "docbook/docbookx.dtd">
+<refentry id='gpsflash.1'>
+<refmeta>
+<refentrytitle>gpsflash</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='date'>15 Jul 2005</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>gpsflash</refname>
+<refpurpose>2-stage firmware loader for GPS chipsets</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+
+<cmdsynopsis>
+  <command>gpsflash</command>  
+      <arg choice='opt'>-v</arg>
+      <arg choice='opt'>-l <replaceable>loader-file</replaceable></arg>
+      <arg choice='plain'>-p <replaceable>tty</replaceable></arg>
+      <arg choice='plain'>-f <replaceable>firmware-file</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+
+<para>This program is a firmware loader for GPSes connected to your
+host computer via serial or USB port.  Presently it supports only SiRF
+GPSes.  Other GPSes may be supported in the future if the vendors
+cooperate.</para>
+
+<para>For operation, this program requires a flashloader binary (found
+by default in a file named <filename>dlgsp2.bin</filename>) and a
+firmware image. This program first ships a command that tells the GPS 
+a flashloader image will follow, then gives the GPS time to reboot into the
+flashloader. The flashloader then accepts S-records from the serial
+or USB port until it sees a termination record, at which point it
+writes the new firmware into the GPS's non-volatile memory
+and reboots the chip into the new firmware.</para>
+
+<para>You will need to obtain your own copy of
+<filename>dlgsp2.bin</filename> and your own firmware image.  The GPSD
+project does not yet have permission to distribute these files, so
+don't ask us for copies.</para>
+
+<para>This program makes no attempt to check that the flashloader or
+firmware image is compatible with your GPS.  EXPERIMENT AT YOUR OWN
+RISK.</para>
+
+<para>This loader will only work with firmware images in S-record
+format, which is the form SiRF normally distrubutes then in.  If you
+get a binary firmware image from somewhere, you can use
+<citerefentry><refentrytitle>objdump</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+from the GNU binutils to convert it to S-records.</para>
+
+<para>Realize that we are not kidding around when we say that this
+could very well break your receiver permanently, and if it does, it's
+no one's fault but your own. For this program to operate, you must set
+an environment variable called I_READ_THE_WARNING with the value "why
+oh why didn't i take the blue pill".</para>
+
+<para>The GPS will be reset to 4800bps NMEA after flash.</para>
+
+</refsect1>
+<refsect1 id='bugs'><title>BUGS AND LIMITAIONS</title>
+
+<para>THIS PROGRAM CAN DESTROY YOUR GPS.  A botched firmware upload
+will turn it into a paperweight.  USE AT YOUR OWN RISK.  Maintainers
+are not responsible for direct or incidental damages.  YOU HAVE BEEN
+WARNED.</para>
+
+</refsect1>
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>xgps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>srec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+</para>
+</refsect1>
+
+<refsect1 id='maintainer'><title>AUTHOR</title> 
+
+<para>Chris Kuethe <email>chris.kuethe@gmail.com</email>.  There is a
+project page for <application>gpsd</application> <ulink
+url="http://gpsd.berlios.de/">here</ulink>.</para>
+
+</refsect1>
+
+</refentry>