A Tour of the GPSD Internals

Handle a $GPRMC sentence stored in an array of strings, one member per field.

Check if the message is stamped valid or not.

If it is invalid, set the status and fix mode to NO_FIX and save the corresponding flags locally; also save the online flag to indicate we have handled a known sentence.

If the fix is autonomous and valid, start to decode the fields.

First, test if there are enough fields available; then handle the date and time via merge_ddmmyy() and merge_hhmmss(), storing the TIME_SET flag and storing the fix time as a UNIX-epoch relative value.

If the sentence time and this fix time are different, we have started a new cycle of observation, so update the sentence time and the store the CYCLE_START_SET flag.

Whatever the number of fields, store the fix coordinates via do_lat_lon(), store the speed and the track and save the corresponding flags.

Return the local aggregated flags to allow the main copy in the session data to be updated.

Preload the local flag with the ERROR_SET flag.

Check that the sentence is usable, exiting with the preset error flag if it is not.

If it is usable, clear the local flags and start processing the fields, updating any local flag fields on the way.

If the year is already known, update the time and check for the start of cycle (see processGPRMC() above).

Handle the fix location and, if the number of received fixes is more than 8 and set fix status.

If the present mode is less than 2D_FIX, update it to 2D_FIX.

Write the stashed value of newstatus into the session status and return all the locally aggregated flags.

Stash the last fix time. Set the status to the value in the message and update the local flag variable.

If the status is STATUS_UNK, exit immediately, returning the locally aggregated flags. If there is a fix, process it.

Handle the time as in processGPGLL() above. Handle the latitiude and longitude with a call to do_lat_lon() above and set the local flag.

Update the satellites_used field and stash the altitude.

If the altitude is empty, force the fix mode and status to 2D if it was 3D previously.

If it is not empty, stash the old value of altitude and replace it with the new value stashed earlier and set the local flag variable. If the mode is presently less than 3D, update it to 3D and set the local flag.

If the stashed old altitude is NaN or the stashed fix time and current fix time are equal, set the climb rate to 0 otherwise calculate it by dividing the altitude difference by the time difference and set the local flag.

If the geoid separation is available, store it, otherwise store the value from wgs84_separation() that depends on current location.

Finally, return all the locally aggregated flags.

Start with a simple validity check on the number of fields (for i.Trek M3) and bail out with a simple indication of on-line status if it fails.

Set the fix mode from the sentence and either clear the local flag variable (if an Antaris chipset says we are in dead-reckoning mode) or set the MODE_SET flag.

Update all the DOP fields from the sentence, clear the count of used satellites, then scan all the satellite data.

If any satellite is good (prn != 0), store the prn and increment the count of used satellites.

Finally, set the local flags to indicate that DOPs are available and return all the locally aggregated flags.

Check if the sentence has too few fields or the wrong number of fields. In this case, clear the data for all satellites and return with an error indication.

Start to parse the sentence. First, note how many sentences are to be expected to complete the data transfer.

If the sentence number is invalid, clear the data for all satellites and return with an error indication.

If this is the first sentence of the sequence, clear the data for all satellites.

Loop through the sentence fields, updating the session’s satellite data.

If any satellite number is higher than the number of channels, clear all satellite data and break out of the loop.

Assuming this is not a buggy chipset (e.g. Motorola Oncore GT+), update the satellite count and loop again.

If this was the last sentence of the block and the number of satellites seen is not the same as the number reported, generate an error log.

If this is not the last sentence of the block, exit early and return an error flag as a guard.

Finally, on the last sentence, carry out a sanity check and either return an error flag or a SATELLITE_SET flag.

Check that the error estimate data is good. If not, set all error estimate fields to 100m and return an error flag.

If they are good, calculate the error value and store it. Return the appropriate flag values.

Set the local flag variable to indicate that the time is available.

Store the actual time by a call to merge_hhmmss() and fill in the other fields from the sentence data.

If the sentence is not timestamped the same as the fixtime, set the CYCLE_START_SET flag.

Update the fixtime to the sentence timestamp.

Finally, return all the locally aggregated flags.

Set the local variable to indicate the unit is on-line.

Fill all appropriate fields from the sentence and set the associated flags in the local flag variable.

Set the fix status and return all the locally aggregated flags.

Test that the length of the NMEA sentence is acceptable, simply returning an on-line indication if it is too long to handle.

If it is within limits, make a local copy and split it on the commas into an array, one field per element.

Use the first element to match the command to the table of decodable commands.

Check if it is supported and the number of fields is reasonable, invoke the correct decoder and return the value from that call.

If it fails the check, simply return an on-line status.

This function is also responsible for performing adaptive end-of-cycle detection.

If the packet is a comment packet, ignore it and return 0.

If it is one of several binary packets, issue a warning to that effect.

If the relevant driver exists, switch to that driver and get it to parse the packet. The return value is that of the binary parser.

If the driver does not exist, ignore the packet and return 0.

If after all this, it is likely to be an NMEA packet, so try to parse it with the NMEA parser. If that returns a 0 (unsuccessful), then check if it is a trigger packet for one of the triggerable drivers.

If this succeeds, return 1, otherwise issue an unrecognised packet error.

Finally checks are made against openBSD’s NMEA Line Discipline to make use of timestamping and if ntpd synchronising is active, the time is passed to the ntp daemon.

Try to fork() a child process. The parent will get a return value of either -1 (on a failure to fork()) or non-zero (the child’s PID). The parent routine will use this information to either return -1 or exit with an exit code of 0 (i.e. the parent terminates, leaving the child running).

The child instance gets a return value of 0 (on an unsuccessful fork() there is no child), so this value is used as the trigger to do the following useful stuff.

First, the child tries to create a new session, returning -1 if unable to do so. If successful, it will have inherited the exiting parent’s session.

Next switch to the root directory and try to open “/dev/null”. If that succeeds, force stdin, stdout and stderr to duplicate the fd of “/dev/null”. If the fd being used for the operation is >2, release it.

Finally, set the flag which indicates the process is in the background and return a value of 0.

Initialise an Internet socket address structure and preload the family and address fields to accept Internet Protocol and any address.

Test to see if the incoming service and protocol exist in /etc/services. If they do, store the port number in the structure (massaging byte order as needed); if they don’t, exit with a -1.

Test to see if the protocol is listed in /etc/services, exiting with -1 if it is not.

Test if the protocol is udp or not, setting the type accordingly.

Try to open a socket with the accumulated settings, exiting with -1 if it fails.

Try to set the socket options correctly, again exiting with -1 if it fails.

Try to bind to the open socket; if it fails exit with -1 as earlier, but give a special warning if the error indicates that gpsd may already be active on the socket.

If we are using a stream type socket and we are unable to listen to the port we exit with -1.

The last possibility is a successful set of operations which is signalled by returning the socket fd number.

Open a passive socket for each supported address family; presently the supported families are IPV4 and IPv6. This socket will be used to listen for client command connections. Sockets are left in the final array argument, and the number successfully opened is returned.

Try and open a socket for Local (UNIX) communications in streaming mode. If the open fails, return with a -1.

If it opens, copy the incoming filename into the socket control structure, bind to the socket and try to listen on it.

Signal a failure by returning -1 and success by returning the socket fd number.

If the incoming boolean flag is active, check if the fd number passed is greater than the highest seen so far. If so, save it as the new highest value.

If the boolean is passive we can take some further action, depending if we are interested in limiting the maximum number of devices and client fds (set by compile time options).

If we are not limiting ourselves, then we check for the case when we are actually at the highest fd seen so far. In that case, scan through all fds available to the system and store the highest active fd number in our allocation set as the new highest value.

Scan through all the client file descriptors, looking for one which does not have a device allocated to it.

On a match, exit early, returning this fd.

If none are available, return a NULL.

Close the given fd and remove it from our allocation set.

Make a call to adjust_max_fd() to housekeep the highest fd marker if needed.

Set important fields in the client’s datablock to safe values for the next re-use, then return.

Check if we have a high enough debug level active to warrant printing out the information we are about to send to the client.

Make the actual write() call and if that was successful, return the counter value from that operation.

If we have suffered some kind of failure, try to analyse it.

On a short write, detach the client and return a 0.

Trap EAGAIN or EINTR and return a 0.

Trap EBADF or a EWOULDBLOCK where the client has not read data for more than a reasonable amount of time and generate a suitable report.

For all other errors, generate a general error. In these last several cases, call detach_cient().

Finally, return the status (-1 in this case).

For every possible subscriber, check if the subscriber is in watcher mode and is interested in the gps device indicated in the calling parameter gps_device_t.

If so, send the data via a call to throttled_write().

For every possible channel, check if the channel is allocated and if the device on the channel is the one passed to us.

If it is so, exit early and return the channel number.

If there is no match, return a NULL.

Try to activate the device via a call to gpsd_activate().

If this fails return “false”.

If it succeeds, add the fd to our list of active fds, housekeep the highest fd number and return “true”.

If the device is not initialized, attempt to open the specified device on behalf of the specified user. If you succeed and the device has an active fd, you’re done. If it does not, make a call to gpsd_activate().

If this fails, return “false”, if not, add the fd to our list of active fds and housekeep the highest fd.

Check if the user is in watcher mode but not tied to a specific device.

This code is similar in function to handle_gpsd_request() in that it parses user input. It expects the commands to be one per line and despatches them according to the leading character, which is limited to one of '-', '+' or '!'.

In the first case, the body of the command is assumed to be a device to remove from the search list. If found, it is removed, any clients are advised and “OK” is written to the calling socket fd. If the device is not found “ERROR” is written to the calling socket fd.

In the second case, the body of the command is assumed to be a device to be used by the daemon. If the device is already known, or does not respond to open_device(), “ERROR” is written to the calling socket fd, otherwise “OK” is written.

In the third case, the command is assumed to be a device-specific control string in the form “!device_name=control_string”. If the string is ill-formed or the device is not found “ERROR” is written to the calling socket fd. If all is well, the control string is written to the device and “OK” is written to the calling socket fd.

If the 1PPS function is compiled in, initialise the local mutex structure for use by the program.

A while() loop reads in any command line arguments which are options and handles the options. Most set an internal variable to control action when running, either to a fixed value or to the associated option’s parameter.

Carry out a series of calls to routines to set things up ready for the main task (e.g. opening a control socket if one is needed). We also take care of tasks such as daemonizing when appropriate. The last piece of preparation is to set the permissions of the default devices correctly if we are daemonizing and are presently running as root.

Switch to the compiled in user name (typically “nobody”) and the group used by the tty devices.

Now we clear important data for all the records in the subscriber list.

Use setjmp() to prepare things for when the daemon terminates.

Clear the semaphore variable which will contain the signal number if one arrives and set some important signals so they are trapped by the stub handler in onsig().

Add the command and RTCM sockets (if active) to the list of active fds, housekeeping the highest fd number and pre-clear the list of control fds.

Process the remaining parameter on the command line which should be the device name and try to open the specified device.

Enter the main execution loop, a while() loop which terminates if a signal sets the semaphore variable. What follows will repeat over and over until an external termination happens.

First we make a working copy of the active fds and then we make a time-limited (1 second time limit) call to select() using the working copy of the fds. This means that when the select() returns, we will either have returned on timeout or because some fd became ready to read.

First we check if any new clients have come active and (if we have resources) allocate a subscriber slot to it, doing housekeeping such as adding it to the main list of active fds and removing it from the local copy of the list. If RTCM support is compiled in, the last operation is repeated for any new RTCM client. The operation is then repeated for any new control socket clients.

If we are expecting DGPS reports, make a call to netgnss_poll() and if there are no ready reports, clear the fd from the main and local active fd lists.

Check if any of the active control sockets has sent one or more commands.

For every one which has sent commands, make calls to handle_control() to process them and remove the associated fd from the main and control lists of active fds.

Poll every active gps device and send RTCM data to it (if needed), followed by reading its output (if any). If the device returns an error, disable the device. If it has gone off-line, disable the device.

If we get here, we have something to handle, so we take care of a device which we know about, but do not have a subtype for.

We send the available data to all subscribers who are connected to this device. If the data is RTCM information, pass it to all GPS devices that can accept the data.

Handle any subscribers who are in watcher mode building up an appropriate set of requests, depending on the available data and passing the requests to handle_gpsd_request().

If we care about DBUS, send the fix to the DBUS.

Note that this small section of code is presently disabled pending development of the DGNSS function. If DGNSS is available and we have a fix, we poll a DGNSS report via dgnss_autoconnect().

Loop round all clients and process active ones. We check for input from them and if the read fails, the client is released with detach_client(). If it succeeds, any data is handled via handle_rtc_request() or handle_gpsd_request().

If the transaction fails, the client is released with detach_client().

If the client has timed out with no device assigned, it is released with detach_client().

If the client has a device, but has timed out on no response (when not in raw or watcher modes) it is released with detach_client().

If we are not running in “nowait” mode, we are supposed to go idle after a timeout when there are no clients.

If a device (with a known type) has no active clients, then we can actually make it idle via gpsd_deactivate().

If we reach here, we are out of the endless while loop. We check if the signal was SIGHUP and restart the program if it was. If it is any other signal, we deallocate all channels and wrap up any devices. Finally we check for the existence of a control socket or a pid file and delete them.

This code is used for error reporting, but is dependant on SQUELCH_DISABLE so that embedded systems (for example) are not burdened with unnecessary noise. The first thing to check is if the error level offered is high enough to be of interest (controlled by the debug level we are running at).

If we are interested, the first step is to protect the code with a mutex if we are using the 1PPS input.

Now we build a message buffer which has a fixed header ("`gpsd: `") and the incoming data. The output buffer is prepared (load the start with a NULL) and then the input buffer is scanned, byte-by-byte, up to its terminating NULL. The scanned data is transferred on the fly to the output buffer subject to the following tests:

If the character is printable, it passes through unchanged.

If it is a space and either of the next two bytes is NULL it will also pass through unchanged.

In any other case, it is copied across as a hexadecimal string like “x09”.

The completed output buffer is then either sent to the system logger if we are in background mode (daemon) or to the stderr file if we are in foreground mode.

Test if the function is called with the same name as the active driver.

If it is, test if the driver has a configurator function and is able to be reconfigured. A good result here will call the driver event hook with type 'driver_switch', and return a 0.

For an entry with a different driver name, scan all available drivers to see if the wanted one is there. An unmatched name exits, returning 0.

If we got a match, get the baudrate for the device with gpsd_assert_sync(), probe for the subtype if we have one.

If the device has a configurator and is reconfigurable, trigger the configurator.

Return a 1 to indicate a device switch.

All actions below, except the last one are conditional on the ntpd interface being compiled in.

Release the ntpd resources, including the 1PPS resources if they are active.

If the device has a revert function, trigger it.

If it has an NMEA mode switcher, invoke it.

If it has a wrapup routine, invoke it.

Finally, close the device.

An ioctl() call is made which returns either 0 if the status of the port changed, or an error.

If we got a change, we read the modem control bits and extract the 1PPS information.

We check the returned value and see if it has changed recently. A counter of 10 unchanged events will disable further testing.

If we are still hanging in there, we now see if we already have had more than 4 good fixes, otherwise we can’t trust the 1PPS.

We then finally test the pulse duration. If it is either a genuine 1PPS or a 2Hz square wave, we call ntpshm_pps().

Short or long PPS pulses are dropped with an error report.

If the devicename matches an NTRIP or DGNSS URI, hand off to special code for opening a socket to that source over the network.

Try and open the device, returning -1 if we fail.

Probe all possible drivers to see if one recognises the device.

Set some fundamental data to a clean value.

Handle the initialisation of NTP and 1PPS functions if needed.

If we did succeed in probing some device type, try and get the subtype.

If we need to do so, we now configure the device.

Finally, signal success by returning the file descriptor given by the device open call.

Check we have a 2D fix (or better) and if the gps didn’t provide an eph value, use the HDOP to calculate one or fail to NAN.

Do the same with epv/VDOP if we have a 3D or better fix.

Do the same with epe/PDOP.

Consider speed error; check if we have two fixes with differing timestamps and use their times and eph values to calculate the speed.

If we have two valid 3D fixes, we can calculate the climb/sink rate.

Finally, just before exiting, save this fix as the old fix for the next comparison round.

Make a call to gps_clear_fix() to prepare the newdata structure to receive data from an incoming packet.

Check if we know the device type. If we do, stash the count of of characters we are able to get from it.

If the read has given a full packet, we can call the subtype probing method, if the device supports it.

If we don’t know the device type, try and figure out what it is, exiting if we can’t.

Make some checks if the device is offline or the packet is incomplete, using the stashed count of characters and the full packet indicator.

If a full packet is available, we try to get the fix data and update the main data structure. We also compute the DOPs so we can fill them in if they are not included in the gps device output.

Mopst of the possible driver events are called from somewhere in here.

Check the validity of the ISGPS word tag (incoming data unsigned int c) and exit with an error if it is not valid.

If the session has not already locked with the datastream, loop through the data and try and sync up. If sync is achieved, exit early with an indication of sync, or fall through still marked unsynced.

If the session is already locked to the datastream, read the data into the session buffer. All the while, take care that the datastream is not corrupted. Any error will result in an early return with an appropriate error code. At the end of this section, return the status of the operations.

Finally, if the above two sections failed, exit with an error indicating that lock was not achieved.

Open a connection to a gps daemon.

Try to get a gps_data_t structure. If it fails, return a NULL.

Test for a specified host and/or port number, using defaults if nothing is specified in the command line invocation.

Try to connect to the now defined socket; on error, release the resources and return NULL. On success, initialise an internal struct gps_data_t and return the pointer to it.

Close the fd associated with the gps_data_t structure and stash the result.

If there is a device id stored, NULL it and the associated path.

If the device list has any data in it, free this and mark the number of available devices as invalid.

Free the gps_data_t structure itself and return the stashed close() result.

Keep looping through the data in buf for JSON objects. Each time one is found, analyze it and unpack it into the struct pointed at by gpsdata, setting the gpsdata→set mask appropriately to indicate which data is valid

This function is intended for GPSD internal use only and should not be considered a stable part oof the API.

Poll the daemon and if there is no data or an error, return -1.

If there is something to read, clear the buffer, note the time as the received data time and the online time, then unpack the data.

If profiling is active, use the received data time, the fix time and the present time to calculate the decode time and the client receipt time.

Gather up the instructions to a gpsd instance for information to return and write them to the device.

If the write fails, return -1. This entry point is deprecated in favor of gps_stream()

Convert the absolute value of double degrees to a static string and return a pointer to it.

Makes a simple check on invalid degree values (not more than 360) and returns "nan" on error.

For valid values, it generates the appropriate string according to the string type enumeration: dd, ddmm or ddmmss.

Warning: not thread safe.

Convert the absolute value of double degrees to a string and place in the buffer "buf". Return a pointer to the buffer. "buf_size" is the size of the buffer.

Makes a simple check on invalid degree values (not more than 360) and returns "nan" on error.

For valid values, it generates the appropriate string according to the string type enumeration: dd, ddmm or ddmmss. If the degrees are positive, append "suffix_pos", else append "suffix_neg".

Parse a block of ntrip data by passing the STR data to ntrip_str_parse().

Return a 0 on success or -1 on any of the many possible failures.

Check the authorisation of the stream and if successful, try to connect.

On connection, try to read data and test for various errors.

On success, return the socket number, on error return -1.

This tries to allocate a free ntp shared memory segment.

If one is available, initialise it for use and flag it as in use.

Returns the segment number on success or -1 on failure.

If the shared memory index allocated to the session is valid and the shmTime structure of the session is valid, store the time of the fix.

Success is indicated by a return value of 1 and errors are indicated by a return value of 0.

This code is only available if the 1PPS function is compiled in.

The shared memory structures are checked for validity and if not valid, a 0 is returned.

The time received is then checked to be within 100 milliseconds of the PC’s internal time and if not, a -1 is returned.

The time received is then checked to be within 500 milliseconds of the second boundary and if not, the shared memory structure is advised that lock is lost and a -1 is returned.

If good, the time is stored in the shared memory and 1 is returned.

This is the main packet-sniffer loop. It scans the character against the definitions of all the packet structures known to gpsd and, if possible, sets a new packet state.

If the state is “xxx_RECOGNIZED”, the packet_parse routine will dispatch the packet to the appropriate driver.

This is called if the nextstate() function returns “GROUND_STATE”.

In this case the character does not match any pattern, so to discard it, the input buffer is shifted back by one character to overwrite the “bad” character.

Call the nextstate() function to process the available data and set the recognition state correctly.

When a packet is matched to a driver, call packet_accept() and packet_discard() to handle the packet. If it is not matched, call packet_discard() and set the state to “GROUND_STATE”

Return the number of characters handled.

Reads raw data from the input port.

Returns the number of characters read (0 or more) or BAD_PACKET if there was an error in reading.

Errors EAGAIN and EINTR are not classed as failures and cause a return of 0.

In case of a good read of more than 0 characters, the return value is the output from a call to packet_parse().

Create a $GPGSA message taking care that if any xDOP is not valid, we substitute a “0.0” value.

If any of the error estimates is available, generate a $PGRME message again taking care about possibly invalid values.

To be called on allocating a device. Mark GPS fd closed and its baud rate unknown.

If we are supporting ntpd shared memory segments, ensure they are initially unused.

Sets the speed, parity and stopbits.

Lots of black magic fiddling goes on to ensure the port is flushed on the baud rate change and wakeup strings are fired off just in case the device needs prodding into life.

READ THE CODE AND COMMENTS!!!

Prior to exit, a call is made to packet_reset() to ensure the packet state machine is initialised.

Test the device and flag it as R/W if it is a character device, or R/O if it isn’t.

Try to open it in non-blocking and no-control mode.

If that fails, try again, adding read-only mode. If that also fails, exit with an error.

On no error, force the saved baudrate if we have a fixed port speed (typically embedded devices). Check if we have a saved baudrate and if so, activate it.

Preset the packet type to BAD_PACKET.

Check if the device we have opened is a tty. If it is a tty, read the original terminal parameters.

Exit with an error code -1 on failure to do so.

Save the old parameters, set important control flags, then set the speed.

Finally, return the allocated fd.

If the device is read-only, simply return 0.

If not, try to write len characters to the device. Waiting until all data has been sent.

Return the number of bytes written.

Check if we have had SNIFF_RETRIES attempts at current baudrate. If not, return “true”.

If we have exceeded the limit, reset the counter and see if there are any more rates to try at.

If no (fixed baudrate or all attempts exhausted), return “false”, otherwise, set the next speed and return “true”.

If there is an active fd, check if it is a tty device. If it is, force the baudrate to 0 (should terminate the connection and de-assert control lines).

Set the HUPCL flag in the original data, write the old data to the port, close the fd and clear that fd number from the session data.