Merge branch 'master' into next

4 files changed, 75 insertions, 19 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index 88afb9c98..be00a6655 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -24,6 +24,7 @@ SET(manual_sources
     build.rst
     coding.rst
     dboards.rst
+    gpsdo.rst
     general.rst
     images.rst
     sync.rst
diff --git a/host/docs/gpsdo.rst b/host/docs/gpsdo.rst
new file mode 100644
index 000000000..a0f2d67da
--- /dev/null
+++ b/host/docs/gpsdo.rst
@@ -0,0 +1,66 @@
+========================================================================
+UHD - Internal GPSDO Application Notes
+========================================================================
+
+.. contents:: Table of Contents
+
+This application note describes the use of integrated GPS-disciplined
+oscillators with Ettus Research USRP devices. It pertains specifically
+to the Jackson Labs Firefly-1A device unless noted otherwise.
+
+------------------------------------------------------------------------
+Specifications
+------------------------------------------------------------------------
+Receiver type: 50 channel with WAAS, EGNOS, MSAS
+10MHz ADEV: 1e-11 over >24h
+1PPS RMS jitter: <50ns 1-sigma
+Holdover: <11us over 3h
+Phase noise: 1Hz: -80dBc/Hz, 10Hz: -110dBc/Hz, 100Hz: -135dBc/Hz, 1kHz: -145dBc/Hz, 10kHz: <-145dBc/Hz
+
+------------------------------------------------------------------------
+Installation
+------------------------------------------------------------------------
+See the documentation for your device for specifics on installing the GPSDO.
+
+------------------------------------------------------------------------
+Configuring the USRP to use the GPSDO
+------------------------------------------------------------------------
+This is necessary if you require absolute GPS time in your application,
+or need to communicate with the GPSDO to obtain location, satellite info, etc.
+If you only require 10MHz and PPS signals for reference or MIMO use,
+(see the Synchronization application note), it is not necessary to perform
+this step.
+
+To configure the USRP to communicate with the GPSDO, use the
+usrp_burn_mb_eeprom utility:
+
+::
+   $ cd <install-path>/share/uhd/utils
+   $ ./usrp_burn_mb_eeprom --key=gpsdo --val=internal
+
+This will configure the driver to communicate with the GPSDO on startup.
+
+------------------------------------------------------------------------
+Using the GPSDO in your application
+------------------------------------------------------------------------
+By default, if a GPSDO is detected at startup, the USRP will be configured
+to use it as a frequency and time reference. The internal VITA timestamp
+will be initialized to the GPS time, and the internal oscillator will be
+phase-locked to the 10MHz GPSDO reference. If the GPSDO is not locked to
+satellites, the VITA time will not be initialized.
+
+GPS data is obtained through the mboard_sensors interface. To retrieve
+the current GPS time, use the "gps_time" sensor:
+
+::
+    usrp->get_mboard_sensor("gps_time");
+
+The returned value will be the current epoch time, in seconds since
+January 1, 1970. This value is readily converted into human-readable
+format using the time.h library in C, boost::posix_time in C++, etc.
+
+Other information can be fetched as well. You can query the lock status
+with the "gps_locked" sensor, as well as obtain raw NMEA sentences using
+the "gps_gpgsa", "gps_gprmc", and "gps_gpgga" sensors. Location
+information can be parsed out of the "gps_gpgga" sensor by using gpsd or
+another NMEA parser.
diff --git a/host/docs/sync.rst b/host/docs/sync.rst
index 9284d8e33..3cb13fbf3 100644
--- a/host/docs/sync.rst
+++ b/host/docs/sync.rst
@@ -102,22 +102,11 @@ and the user can also parse this string to determine GPS time:
     usrp->set_time_next_pps(uhd::time_spec_t(gps_time+1));
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Method 3 - query the gps_time sensor
+Method 3 - internal GPSDO
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This is a variant of method 2 for USRPs with internal GPSDOs.
-The user can query the gps_time sensor to wait for the NMEA string.
-
-::
-
-    //wait for NMEA string from internal GPSDO
-    usrp->get_mboard_sensor("gps_time");
-    usrp->set_time_next_pps(uhd::time_spec_t(0.0));
-
-    -- OR --
-
-    //wait for the NMEA string and set GPS time
-    const time_t gps_time = usrp->get_mboard_sensor("gps_time").to_int();
-    usrp->set_time_next_pps(uhd::time_spec_t(gps_time+1));
+USRPs with internal GPSDOs properly configured will automatically
+configure themselves to set the VITA time to current UTC time. See the
+GPSDO application note for more details.
 
 ------------------------------------------------------------------------
 Synchronizing channel phase
diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst
index 189f937de..1b243656f 100644
--- a/host/docs/usrp2.rst
+++ b/host/docs/usrp2.rst
@@ -349,9 +349,8 @@ Test the PPS input with the following app:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Internal GPSDO
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-USRP-N2XX models can have an optional internal GPSDO.
-To use the GPSDO with UHD, you must burn an EEPROM setting
-so that UHD knows that the internal GPSDO was installed.
+Please see the GPSDO application note for information on configuring and
+using the internal GPSDO.
 
 **Installation instructions:**
 
@@ -396,7 +395,8 @@ they can be queried through the API.
 
 * mimo_locked - clock reference locked over the MIMO cable
 * ref_locked - clock reference locked (internal/external)
-* gps_time - GPS seconds (available when GPSDO installed)
+* gps_time - GPS epoch seconds (available when GPSDO installed)
+* gps_locked - GPS lock status
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Multiple RX channels