diff options
author | Eric S. Raymond <esr@thyrsus.com> | 2006-11-08 01:03:35 +0000 |
---|---|---|
committer | Eric S. Raymond <esr@thyrsus.com> | 2006-11-08 01:03:35 +0000 |
commit | ebe6b9afe2495a6a136cab6f24c36a670ed901a9 (patch) | |
tree | fb20064d00fbe21c7fd2c1062e1d331865679976 /www | |
parent | 97ab3f706c24369a3c862af22a9f6417f3fea4ed (diff) | |
download | gpsd-ebe6b9afe2495a6a136cab6f24c36a670ed901a9.tar.gz |
Various small markup fixes.
Diffstat (limited to 'www')
-rw-r--r-- | www/writing-a-driver.xml | 86 |
1 files changed, 41 insertions, 45 deletions
diff --git a/www/writing-a-driver.xml b/www/writing-a-driver.xml index da765e14..60e31d6b 100644 --- a/www/writing-a-driver.xml +++ b/www/writing-a-driver.xml @@ -346,8 +346,8 @@ regression testing or dummy traffic generation. Finally, I concluded that I needed to make mention of my driver in the following files:</para> -<informaltable> -<tgroup cols='3'> +<informaltable frame='none'> +<tgroup cols='2'> <tbody> <row> <entry><filename>Makefile.am</filename></entry> @@ -522,39 +522,38 @@ of the function or the default value of the data. What follows is a list of each of the table entries with a short description of what it is expected to do or contain.</para> -<para><structfield>.typename</structfield>is a simple string that +<para><structfield>.typename</structfield> is a simple string that uniquely identifies your driver. The first few characters are also output in some of the monitor output as generated by cgps or xgps.</para> -<para><structfield>.trigger</structfield>is the unique string that, +<para><structfield>.trigger</structfield> is the unique string that, when seen, will confirm our device is present. This will be detected in <filename>drivers.c</filename>and will probably be the same value as that provoked by sending the command mentioned in <filename>.probe_detect</filename>below.</para> -<para><structfield>.channels</structfield>is the number of channels your +<para><structfield>.channels</structfield> is the number of channels your GPS uses. Typically this will be 12 for a consumer grade device.</para> -<para><structfield>.probe_detect</structfield>points to a block of code -that generates a command to send to the device that will -provoke a response if our device is present. The code should -then detect and recognise the response, signalling if -detection was successful or not. Successful detection results -in this driver claiming the attached device. It may also do -some more exotic things like set the port to different -operation modes (e.g. raw mode) from the default. If it makes -the changes to the port permanently, it should store the -original settings for later restoration, probably by +<para><structfield>.probe_detect</structfield> points to a block of +code that generates a command to send to the device that will provoke +a response if our device is present. The code should then detect and +recognise the response, signalling if detection was successful or +not. Successful detection results in this driver claiming the attached +device. It may also do some more exotic things like set the port to +different operation modes (e.g. raw mode) from the default. If it +makes the changes to the port permanently, it should store the +original settings for later restoration, probably by <structfield>.wrapup</structfield>mentioned below. Later in this document I discuss my work to implement this function.</para> -<para><structfield>.probe_wakeup</structfield>points to a block of code +<para><structfield>.probe_wakeup</structfield> points to a block of code that wakes up the device when the main auto-baud hunt loop in the daemon offers a new speed to probe at.</para> -<para><structfield>.probe_subtype</structfield>points to a block of +<para><structfield>.probe_subtype</structfield> points to a block of code that will be executed whenever the device-driver type is switched (with second argument 0) or whenever a full packet is received (with second argument being the sequence number of the packet. It is @@ -565,22 +564,22 @@ store information about the software version in member <filename>subtype</filename>of the driver data structure <userinput>struct gps_device_t *session</userinput>.</para> -<para><structfield>.configurator</structfield>points to a block of code +<para><structfield>.configurator</structfield> points to a block of code that sets up the device to deliver the correct set of sentences to supply the parser with the data needed by <filename>gpsd</filename>.</para> -<para><structfield>.get_packet</structfield>points to a block of code +<para><structfield>.get_packet</structfield> points to a block of code that actually gets the packets from the serial stream. You will almost certainly use the generic routine <function>packet_get</function>. If you know this won't do, you already know enough not to need this explaining.</para> -<para><structfield>.parse_packet</structfield>points to a block of code +<para><structfield>.parse_packet</structfield> points to a block of code which parses a packet. This will be the main part of your driver.</para> -<para><structfield>.rtcm_writer</structfield>points to a block of code +<para><structfield>.rtcm_writer</structfield> points to a block of code used if the GPS type is capable of accepting differential-GPS corrections in RTCM-104 format. This is the routine needed to ship the data to the device. Usually it is a straight binary @@ -588,24 +587,24 @@ write of the data, which is provided by the default routine <function>pass_rtcm</function>. If the device does not accept differential data, the value is NULL.</para> -<para><structfield>.speed_switcher</structfield>points to a block of +<para><structfield>.speed_switcher</structfield> points to a block of code to change baud rate (if supported).</para> -<para><structfield>.mode_switcher</structfield>points to a block of code +<para><structfield>.mode_switcher</structfield> points to a block of code to change the mode (if supported) between NMEA (mode 0) and our binary mode (1).</para> -<para><structfield>.rate_switcher</structfield>points to a block of code +<para><structfield>.rate_switcher</structfield> points to a block of code to change the maximum number of fixes our device can generate in 1 second.</para> -<para><structfield>.cycle_chars</structfield>is explained in +<para><structfield>.cycle_chars</structfield> is explained in <quote>Throughput computation for baud rate changes</quote> in the <quote>Hacker's Guide to GPSD</quote> in the general documentation. It's only necessary to fill this in if you have <filename>.rate_switcher</filename>capability</para> -<para><structfield>.wrapup</structfield>points to a block of code +<para><structfield>.wrapup</structfield> points to a block of code which is run each time the device is to be closed. This happens when all clients have disconnected and the <option>-n</option>switch is not active. The premise is that there may be a special mode you @@ -615,7 +614,7 @@ otherwise. It allows for changing the device to a low power mode, for instance. This is also where you should undo any port parameter changes you made in <filename>.probe_detect</filename>above.</para> -<para><structfield>.cycle</structfield>is a number giving the number of +<para><structfield>.cycle</structfield> is a number giving the number of fixes per second we can get. Gets updated if we can rate-switch and user gives a gpsd 'C' command.</para> @@ -626,11 +625,11 @@ Raymond as follows.</para> <para>The inter-relationship between <structfield>.cycle_chars</structfield>and <structfield>.cycle</structfield>is:-</para> <para>If we can change baud rate ( <structfield>.speed_switcher</structfield>) and we can -alter the rate at which fixes are delivered ( -<structfield>.rate_switcher</structfield>), then we need to know the -number of characters in a fix string ( -<structfield>.cycle_chars</structfield>) so that we can compute the -number of fixes/second ( <structfield>.cycle</structfield>) we can ask +alter the rate at which fixes are delivered +(<structfield>.rate_switcher</structfield>), then we need to know the +number of characters in a fix string +(<structfield>.cycle_chars</structfield>) so that we can compute the +number of fixes/second (<structfield>.cycle</structfield>) we can ask for.</para> </sect1> @@ -695,8 +694,7 @@ someone trying to follow your code later <rant mode off></para> </sect1> -<sect1><title>Implementing the -<structfield>.probe_detect</structfield>function</title> +<sect1><title>Implementing the <structfield>.probe_detect</structfield> function</title> <para>As I mentioned earlier, my GPS device needed to be <quote>woken up</quote>, @@ -771,18 +769,16 @@ milliseconds. Unfortunately, in the probing code, we have to allow for the worst case, so once the code issues a command, it has then to wait a full 2 seconds before scanning for output.</para> -<para>The only port setting which was not immediately -obvious to me (although present in both -<filename>serial.c</filename>an -<filename>sirfmon.c</filename>) was +<para>The only port setting which was not immediately obvious to me +(although present in both <filename>serial.c</filename> and +<filename>sirfmon.c</filename>) was <userinput>session->ttyset.c_cflag |= CREAD | -CLOCAL;</userinput>. This is needed to enable the port and cause it -to ignore any modem control lines. If you are using a binary -protocol, you will also need to issue a -<userinput>cfmakeraw(struct termios *termios_p);</userinput>to -quickly set the most important flags correctly. I was bitten by -this and found that <CR/LF> sequences were being modified -to <CR/CR/LF> by the tty port driver.</para> +CLOCAL;</userinput>. This is needed to enable the port and cause it to +ignore any modem control lines. If you are using a binary protocol, +you will also need to issue a <userinput>cfmakeraw(struct termios +*termios_p);</userinput>to quickly set the most important flags +correctly. I was bitten by this and found that <CR/LF> sequences +were being modified to <CR/CR/LF> by the tty port driver.</para> </sect1> <sect1><title>Sign off</title> |