OctoClock firmware upgrade, added host driver

* OctoClock can communicate with UHD over Ethernet
* Can read NMEA strings from GPSDO and send to host
* Added multi_usrp_clock class for clock devices
* uhd::device can now filter to return only USRP devices or clock devices
* New OctoClock bootloader can accept firmware download over Ethernet
* Added octoclock_burn_eeprom,octoclock_firmware_burner utilities
* Added test_clock_synch example to show clock API

9 files changed, 205 insertions, 19 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index cd061975b..84ed88281 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -94,6 +94,7 @@ ENDIF(ENABLE_MANUAL_OR_DOXYGEN)
 ########################################################################
 
 SET(man_page_sources
+    octoclock_firmware_burner.1
     uhd_cal_rx_iq_balance.1
     uhd_cal_tx_dc_offset.1
     uhd_cal_tx_iq_balance.1
diff --git a/host/docs/mainpage.dox b/host/docs/mainpage.dox
index 535a00e22..47be99411 100644
--- a/host/docs/mainpage.dox
+++ b/host/docs/mainpage.dox
@@ -2,7 +2,7 @@
 
 \tableofcontents
 
-Welcome to the manual pages for the Universal Software Radio Peripherals (USRP) and their driver suite, the USRP Hardware Driver (UHD). Here, you will find information on how to use the USRPs and how to use the API to connect to them through your own software.
+Welcome to the manual pages for the USRP Hardware Driver (UHD), the host driver for Ettus Research devices. Here, you will find information on how to use the devices and how to use the API to connect to them through your own software.
 
 # Building and Installing UHD
 
@@ -50,6 +50,10 @@ Welcome to the manual pages for the Universal Software Radio Peripherals (USRP)
 
 \li \subpage page_usrp2
 
+## OctoClock
+
+\li \subpage page_octoclock
+
 # API Documentation
 
 \li \subpage page_coding
diff --git a/host/docs/octoclock.dox b/host/docs/octoclock.dox
new file mode 100644
index 000000000..d4c6161a1
--- /dev/null
+++ b/host/docs/octoclock.dox
@@ -0,0 +1,126 @@
+/*! \page page_octoclock OctoClock Device Manual
+
+\tableofcontents
+
+\section octoclock_features Feature list
+
+- Hardware Capabilities:
+    -   Fully integrated timing source with 8-Way distribution (10 MHz and 1 PPS)
+    -   User selection between internal GPSDO (when present) or external 10 MHz/1 PPS source
+    -   Source detection with automatic switch over in case of failure or disconnect
+    -   Streaming GPS time and NMEA strings over Ethernet (OctoClock-G only)
+
+\section octoclock_load Loading Firmware onto the Octoclock
+
+\subsection bootloader OctoClock bootloader
+
+If you purchased your OctoClock device before Ethernet functionality was introduced, or if your unit's
+bootloader has somehow become corrupted, you must burn the bootloader onto the device before you can load
+the primary firmware.
+
+To load the bootloader onto the OctoClock, two things are needed:
+
+- AVR programmer
+- AVRdude software
+
+Connect the AVR programmer to J108, as specified on the <a href="http://files.ettus.com/schematics/octoclock/octoclock.pdf">
+schematics</a>. Once you verify that the programmer is properly connected, run the following commands to burn the firmware:
+
+    cd <install path>/share/uhd/images
+    avrdude -p atmega128 -c <programmer name> -P usb -U efuse:w:0xFF:m -U hfuse:w:0x80:m -U lfuse:w:0xFF:m -U flash:w:octoclock_bootloader.hex:i
+
+**Note:** On Linux, **sudo** must be used with the **avrdude** command.
+
+Once the bootloader has been burned, power-cycle your OctoClock device and refer to the below instructions on burning the OctoClock's
+primary firmware.
+
+\subsection application Primary Octoclock firmware
+
+To load firmware onto the OctoClock, you must use the *octoclock_firmware_burner* utility, specifying the IP
+address of the OctoClock device, as follows:
+
+    octoclock_firmware_burner --addr=192.168.10.3
+
+\section octoclock_network Setting Up Networking
+
+\subsection host_interface Setting up the host interface
+
+The OctoClock communicates with the host machine at the UDP layer over Gigabit Ethernet. The default device
+of the OctoClock is **192.168.10.3**. You will need to configure the host machine's Ethernet interface with
+a static IP address to enable communication. An address of **192.168.10.1** and a subnet mask of
+**255.255.255.0** is recommended.
+
+**Note:** When using UHD software, if an IP address for the OctoClock is not specified, the software will
+use UDP broadcast packets to locate the OctoClock. On some systems, the firewall will block UDP broadcast
+packets. It is recommended that you change your firewall settings.
+
+\subsection changing_ip Changing the OctoClock's IP address
+
+You may need to change the OctoClock's IP address for various reasons.
+
+- To satisfy your particular network configuration
+- To use multiple OctoClocks on the same host computer
+
+To change the OctoClock's IP address, run the following commands (using the default IP address as an example):
+
+    cd <install path>/lib/uhd/utils
+    ./octoclock_burn_eeprom --args="<optional device args>" --values="ip-addr=192.168.10.3"
+
+\section addressing Addressing the Device
+
+There are two ways to address the OctoClock from UHD software: the IP address, and the serial.
+
+To use the IP address, address it as follows:
+
+    "addr=<ip address>"
+
+If you want to use multiple OctoClock devices, address it as follows:
+
+    "addr0=<ip address 1>,addr1=<ip address 2>"
+
+To use the serial, address it as follows:
+
+    "serial=<serial>"
+
+\section hardware_setup Hardware Setup Notes
+
+\subsection front_panel_leds Front Panel LEDs
+
+The LEDs on the front panel show the current status of the device. Each LED is described below:
+
+- **Internal:** the device is using the internal GPSDO
+- **External:** the device is using an external reference
+- **Status:** the device is successfully distributing a 10 MHz and PPS signal
+- **PPS:** lights up when a PPS signal is detected
+- **GPS Lock:** the internal GPSDO has achieved a lock (not necessary to distribute the signals)
+- **Power:** the device is receiving power
+
+\subsection front_panel_switch Front Panel Switch
+
+The front panel switch, marked **Primary Ref** determines which reference the OctoClock will prefer to use. If it is receiving
+both an internal and external reference, the device will use whichever one the switch specifies.
+
+However, if it is only receiving an internal reference, it will use this reference no matter what position the switch is in.
+The same applies for an external signal.
+
+\section misc Miscellaneous
+
+\subsection available_sensors Available Sensors
+
+The following sensors are available on both the OctoClock and Octoclock-G; these can be queried through the
+<a href="classuhd_1_1octoclock.html">API</a>.
+
+- **ext_ref_detected:** whether or not the device detects an external reference
+- **gps_detected:** whether or not the device detects an internal GPSDO
+- **using_ref:** which reference the device is using (internal or external)
+- **switch_pos:** the position of the front switch (internal or external)
+
+On the OctoClock-G, the following sensors are added:
+
+- **gps_gpgga:** the latest GPGGA string sent by the GPSDO
+- **gps_gprmc:** the latest GPRMC string sent by the GPSDO
+- **gps_time:** the time reported by the GPSDO
+- **gps_locked:** whether or not the GPSDO is locked (true/false)
+- **gps_servo:** the latest debug trace information sent by the GPSDO
+
+*/
diff --git a/host/docs/octoclock_firmware_burner.1 b/host/docs/octoclock_firmware_burner.1
new file mode 100644
index 000000000..0494b3b37
--- /dev/null
+++ b/host/docs/octoclock_firmware_burner.1
@@ -0,0 +1,45 @@
+.TH "octoclock_firmware_burner" 1 "3.7.1" UHD "User Commands"
+.SH NAME
+octoclock_firmware_burner - OctoClock Firmware Burner
+.SH DESCRIPTION
+Burn firmware images onto an Ettus Research OctoClock device over Ethernet.
+.SH SYNOPSIS
+.B  octoclock_firmware_burner [OPTIONS]
+.SH OPTIONS
+This program works best when only an IP address is specified.
+.IP "Device IP Address:"
+--addr=\fI"Address"\fR
+.IP "This help information:"
+--help
+.IP "Custom Firmware Filepath:"
+--fw-path=\fI"filepath"\fR
+.IP "List all OctoClock devices without burning"
+--list
+.SH EXAMPLES
+.SS Selecting a custom firmware path
+.sp
+octoclock_firmware_burner --addr=192.168.10.3 --fw-path=~/custom_octoclock_image.bin
+.ft
+.fi
+.SH SEE ALSO
+UHD documentation:
+.B http://files.ettus.com/uhd_docs/manual/html/index.html
+.LP
+Other UHD programs:
+.sp
+uhd_images_downloader(1) usrp2_card_burner(1) usrp_n2xx_simple_net_burner(1) usrp_x3xx_fpga_burner(1)
+.SH AUTHOR
+This manual page was written by Nicholas Corgan
+for the Debian project (but may be used by others).
+.SH COPYRIGHT
+Copyright (c) 2014 Ettus Research LLC
+.LP
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+.LP
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
diff --git a/host/docs/uhd_find_devices.1 b/host/docs/uhd_find_devices.1
index 416f807b9..7f92966be 100644
--- a/host/docs/uhd_find_devices.1
+++ b/host/docs/uhd_find_devices.1
@@ -2,7 +2,7 @@
 .SH NAME
 uhd_find_devices \- USRP Hardware Driver Discovery Utility
 .SH DESCRIPTION
-Find UHD-supporting Software Radio Peripherals attached by USB,
+Find UHD-supporting Ettus Research products attached by USB,
 network or embedded configuration.
 .LP
 The UHD package is the universal hardware driver for Ettus Research
@@ -16,7 +16,7 @@ the UHD driver standalone or with 3rd party applications.
 --args \fIarg\fR
 .IP "This help information:"
 --help
-.SH IDENTIFYING USRP DEVICES
+.SH IDENTIFYING DEVICES
 .sp
 Devices are addressed through key/value string pairs.
 These string pairs can be used to narrow down the search for a specific device or group of devices.
@@ -28,36 +28,42 @@ Every device has several ways of identifying it on the host system.
 .SS Identifying by hardware identifier
 .sp
 
-All USRP devices can be found through their hardware series identifier, which match to USRP
+All Ettus Research devices can be found through their hardware series identifier, which match to
 devices as follows:
 
-Argument    |  Device
+Argument       |  Device
 
-type=usrp1  |  USRP1
+type=usrp1     |  USRP1
 
-type=usrp2  |  USRP2, USRP N200, USRP N210
+type=usrp2     |  USRP2, USRP N200, USRP N210
 
-type=b100   |  USRP B100
+type=b100      |  USRP B100
 
-type=e100   |  USRP E100, USRP E110
+type=b200      |  USRP B200, USRP B210
+
+type=e100      |  USRP E100, USRP E110
+
+type=x300      |  USRP X300, USRP X310
+
+type=octoclock |  OctoClock
 
 .SS Identifying by serial number
 
-All USRP devices are given a unique serial number, which can be used to identify a device as follows:
+All Ettus Research devices are given a unique serial number, which can be used to identify a device as follows:
 
 serial=12345678
 
 .SS Identifying by IP address
 
-USRP2, USRP N200, and USRP N210 devices connected to the host machine can all be found through their
+USRP2, USRP N200, USRP N210, USRP X300, USRP X310, and OctoClock devices connected to the host machine can all be found through their
 IP addresses, as follows:
 
 addr=192.168.10.2
 
 .SS Identifying by name
 
-Users have the option of giving their USRP devices short names using the usrp_burn_mb_eeprom utility
-in lib/uhd/utils. Devices that have been given a name can be identified as follows:
+Users have the option of giving their devices short names using the usrp_burn_mb_eeprom and octoclock_burn_eeprom
+utilities in lib/uhd/utils. Devices that have been given a name can be identified as follows:
 
 name=foo
 
diff --git a/host/docs/uhd_images_downloader.1 b/host/docs/uhd_images_downloader.1
index dd0fe208d..cbdc5c26e 100644
--- a/host/docs/uhd_images_downloader.1
+++ b/host/docs/uhd_images_downloader.1
@@ -33,7 +33,7 @@ GR-UHD documentation:
 .LP
 Other UHD programs:
 .sp
-usrp2_card_burner(1) usrp_n2xx_simple_net_burner(1)
+usrp2_card_burner(1) usrp_n2xx_simple_net_burner(1) usrp_x3xx_fpga_burner(1) octoclock_firmware_burner(1)
 .SH AUTHOR
 This manual page was written by Maitland Bottoms and Nicholas Corgan
 for the Debian project (but may be used by others).
diff --git a/host/docs/uhd_usrp_probe.1 b/host/docs/uhd_usrp_probe.1
index ee30b2350..50ecab5c1 100644
--- a/host/docs/uhd_usrp_probe.1
+++ b/host/docs/uhd_usrp_probe.1
@@ -47,8 +47,12 @@ type=usrp2  |  USRP2, USRP N200, USRP N210
 
 type=b100   |  USRP B100
 
+type=b200   |  USRP B200, USRP B210
+
 type=e100   |  USRP E100, USRP E110
 
+type=x300   |  USRP X300, USRP X310
+
 .SS Identifying by serial number
 
 All USRP devices are given a unique serial number, which can be used to identify a device as follows:
@@ -57,7 +61,7 @@ serial=12345678
 
 .SS Identifying by IP address
 
-USRP2, USRP N200, and USRP N210 devices connected to the host machine can all be found through their
+USRP2, USRP N200, USRP N210, USRP X300, and USRP X310 devices connected to the host machine can all be found through their
 IP addresses, as follows:
 
 addr=192.168.10.2
diff --git a/host/docs/usrp_n2xx_simple_net_burner.1 b/host/docs/usrp_n2xx_simple_net_burner.1
index 8df38b7bd..d32b88fae 100644
--- a/host/docs/usrp_n2xx_simple_net_burner.1
+++ b/host/docs/usrp_n2xx_simple_net_burner.1
@@ -19,9 +19,9 @@ This program works best when only an IP address is specified.
 .IP "Custom FPGA Filepath:"
 --fpga=\fI"filepath"\fR
 .IP "Don't burn firmware:"
---no_fw
+--no-fw
 .IP "Don't burn FPGA:"
---no_fpga
+--no-fpga
 .IP "Automatically reboot USRP device after burning"
 --auto_reboot
 .IP "List all USRP devices without burning"
@@ -41,7 +41,7 @@ GR-UHD documentation:
 .LP
 Other UHD programs:
 .sp
-uhd_images_downloader(1) usrp2_card_burner(1) usrp_x3xx_fpga_burner(1)
+uhd_images_downloader(1) usrp2_card_burner(1) usrp_x3xx_fpga_burner(1) octoclock_firmware_burner(1)
 .SH AUTHOR
 This manual page was written by Nicholas Corgan
 for the Debian project (but may be used by others).
diff --git a/host/docs/usrp_x3xx_fpga_burner.1 b/host/docs/usrp_x3xx_fpga_burner.1
index 3a8a27e69..4ca6fd6dc 100644
--- a/host/docs/usrp_x3xx_fpga_burner.1
+++ b/host/docs/usrp_x3xx_fpga_burner.1
@@ -47,7 +47,7 @@ GR-UHD documentation:
 .LP
 Other UHD programs:
 .sp
-uhd_images_downloader(1) usrp2_card_burner(1) usrp_n2xx_simple_net_burner(1)
+uhd_images_downloader(1) usrp2_card_burner(1) usrp_n2xx_simple_net_burner(1) octoclock_firmware_burner(1)
 .SH AUTHOR
 This manual page was written by Nicholas Corgan
 for the Debian project (but may be used by others).