Merge branch 'sync_docs'

5 files changed, 240 insertions, 1 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index 1a2738647..5926e062e 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -26,6 +26,7 @@ SET(manual_sources
     dboards.rst
     general.rst
     images.rst
+    sync.rst
     transport.rst
     usrp1.rst
     usrp2.rst
diff --git a/host/docs/general.rst b/host/docs/general.rst
index 73b820c84..ff85fb0f9 100644
--- a/host/docs/general.rst
+++ b/host/docs/general.rst
@@ -5,7 +5,63 @@ UHD - General Application Notes
 .. contents:: Table of Contents
 
 ------------------------------------------------------------------------
-Misc notes
+Tuning notes
+------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Two-stage tuning process
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A USRP device has two stages of tuning:
+
+* RF front-end: translates bewteen RF and IF
+* DSP: translates between IF and baseband
+
+In a typical use-case, the user specifies an overall center frequency for the signal chain.
+The RF front-end will be tuned as close as possible to the center frequency,
+and the DSP will account for the error in tuning between target frequency and actual frequency.
+The user may also explicitly control both stages of tuning through the tune_request_t object.
+
+Pseudo-code for tuning the receive chain:
+::
+
+    //tuning to a desired center frequency
+    usrp->set_rx_freq(my_frequency_in_hz);
+
+    --OR--
+
+    //advanced tuning with tune_request_t
+    uhd::tune_request_t tune_req;
+    tune_req.target_freq = my_frequency_in_hz;
+    //fill in tune request fields...
+    usrp->set_rx_freq(tune_req);
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+RF front-end settling time
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+After tuning, the RF front-end will need time to settle into a usable state.
+Typically, this means that the local oscillators must be given time to lock before streaming begins.
+Lock time is not consistent; it varies depending upon the device and requested settings.
+After tuning and before streaming, the user should
+wait for the "lo_locked" sensor to become true,
+or sleep for a conservative amount of time (perhaps a second).
+
+Pseudo-code for dealing with settling time after tuning on receive:
+::
+
+    usrp->set_rx_freq(...);
+    sleep(1);
+    usrp->issue_stream_command(...);
+
+    --OR--
+
+    usrp->set_rx_freq(...);
+    while (not usrp->get_rx_sensor("lo_locked").to_bool()){
+        //sleep for a short time in milliseconds
+    }
+    usrp->issue_stream_command(...);
+
+------------------------------------------------------------------------
+Threading notes
 ------------------------------------------------------------------------
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -46,6 +102,10 @@ Add the following line to */etc/security/limits.conf*:
 Replace <my_group> with a group to which your user belongs.
 Settings will not take effect until the user has logged in and out.
 
+------------------------------------------------------------------------
+Misc notes
+------------------------------------------------------------------------
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Support for dynamically loadable modules
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/host/docs/index.rst b/host/docs/index.rst
index 467d5f385..40fe64599 100644
--- a/host/docs/index.rst
+++ b/host/docs/index.rst
@@ -27,6 +27,7 @@ Application Notes
 * `USRP-E1XX Series Application Notes <./usrp_e1xx.html>`_
 * `Daughterboard Application Notes <./dboards.html>`_
 * `Transport Application Notes <./transport.html>`_
+* `Synchronization Application Notes <./sync.html>`_
 
 ^^^^^^^^^^^^^^^^^^^^^
 API Documentation
diff --git a/host/docs/sync.rst b/host/docs/sync.rst
new file mode 100644
index 000000000..7e9ea11f4
--- /dev/null
+++ b/host/docs/sync.rst
@@ -0,0 +1,160 @@
+========================================================================
+UHD - Synchronization Application Notes
+========================================================================
+
+.. contents:: Table of Contents
+
+The following application notes explain how to synchronize multiple USRPs
+with the goal of transmitting or receiving time-aligned samples for MIMO
+or other applications requiring multiple USRPs operating synchronously.
+
+**Note:** The following synchronization notes do not apply to USRP1,
+which does not support the advanced features available in newer products.
+
+------------------------------------------------------------------------
+Common reference signals
+------------------------------------------------------------------------
+USRPs take two reference signals in order to synchronize clocks and time:
+
+* A 10MHz reference to provide a single frequency reference for both devices, and
+* A pulse-per-second (1PPS) to synchronize the sample time across devices.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Provide reference signals
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Most USRPs have front panel SMA connectors to source these reference signals.
+Typically, these signals are provided by an external GPSDO.
+Some USRP models can provide these signals from an optional internal GPSDO.
+For users generating their own signals,
+the pulse-per-second should be clocked from the 10MHz reference.
+See the application notes for your device for specific signal requirements.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Set the clock configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In order to synchronize to an external clock, configure the USRP device
+using the "external" clock configuration:
+
+::
+
+    usrp->set_clock_config(uhd::clock_config_t::external());
+
+------------------------------------------------------------------------
+Synchronizing the device time
+------------------------------------------------------------------------
+The purpose of the PPS signal is to synchronously latch a time into the device.
+You can use the set_time_next_pps(...) function to either initialize the sample time to 0,
+or to an absolute time such as GPS time or UTC time.
+For the purposes of synchronizing devices,
+it doesn't matter what time you initialize to when using set_time_next_pps(...).
+
+Some GPSDOs synchronize their PPS with the rising edge of the 10MHz clock,
+and some synchronize with the falling edge of the clock.
+You should find out which edge your GPSDO uses,
+and then pass that in as an argument to set_time_next_pps(...).
+
+Here are two examples of how to set the PPS time to synchronize USRPs
+to a clock source.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Method 1 - poll the USRP time registers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+One way to initialize the PPS edge is to poll the "last PPS" time from the USRP device.
+When the last PPS time increments, the user can determine that a PPS has occurred:
+
+::
+
+    const uhd::time_spec_t last_pps_time = usrp->get_time_last_pps();
+    while (last_pps_time != usrp->get_time_last_pps()){
+        //sleep 100 milliseconds (give or take)
+    }
+    usrp->set_time_next_pps(uhd::time_spec_t(0.0));
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Method 2 - query the GPSDO for seconds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Most GPSDO can be configured to output a NMEA string over the serial port once every PPS.
+The user can wait for this string to determine the PPS edge,
+and the user can also parse this string to determine GPS time:
+
+::
+
+    //call user's function to wait for NMEA message...
+    usrp->set_time_next_pps(uhd::time_spec_t(0.0));
+
+    -- OR --
+
+    //call user's function to wait for NMEA message...
+    //call user's function to parse the NMEA message...
+    usrp->set_time_next_pps(uhd::time_spec_t(gps_time+1));
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Method 3 - query the gps_time sensor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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));
+
+------------------------------------------------------------------------
+Synchronizing channel phase
+------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Align CORDICs in the DSP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In order to achieve phase alignment between USRPs, the CORDICS in both
+devices must be aligned with respect to each other. This is easily achieved
+by issuing stream commands with a time spec property, which instructs the
+streaming to begin at a specified time. Since the devices are already
+synchronized via the 10MHz and PPS inputs, the streaming will start at exactly
+the same time on both devices. The CORDICs are reset at each start-of-burst
+command, so users should ensure that every start-of-burst also has a time spec set.
+
+For receive, a burst is started when the user issues a stream command. This stream command should have a time spec set.
+
+::
+
+    uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE);
+    stream_cmd.num_samps = spb;
+    stream_cmd.stream_now = false;
+    stream_cmd.time_spec = uhd::time_spec_t(seconds_in_future);
+    usrp->issue_stream_cmd(stream_cmd);
+
+For transmit, a burst is started when the user calls send(). The metadata should have a time spec and start of burst set.
+
+::
+
+    uhd::tx_metadata_t md;
+    md.start_of_burst = true;
+    md.end_of_burst = false;
+    md.has_time_spec = true;
+    md.time_spec = uhd::time_spec_t(time_to_send);
+
+    //send a single packet
+    size_t num_tx_samps = usrp->get_device()->send(
+        buffs, samps_to_send, md,
+        uhd::io_type_t::COMPLEX_FLOAT32,
+        uhd::device::SEND_MODE_ONE_PACKET, timeout
+    );
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Align LOs in the front-end
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+After tuning the RF front-ends,
+each local oscillator may have a random phase offset due to the dividers
+in the VCO/PLL chains. This offset will remain constant after the device
+has been initialized, and will remain constant until the device is closed
+or re-tuned. This phase offset is typically removed by the user in MIMO
+applications, using a training sequence to estimate the offset. It will
+be necessary to re-align the LOs after each tune command.
diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst
index aaae79792..88b217f1b 100644
--- a/host/docs/usrp2.rst
+++ b/host/docs/usrp2.rst
@@ -397,3 +397,20 @@ 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)
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Multiple RX channels
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are two complete DDC chains in the FPGA.
+In the single channel case, only one chain is ever used.
+To receive from both channels,
+the user must set the RX subdevice specification.
+This hardware has only one daughterboard slot,
+which has been aptly named slot "0".
+
+In the following example, a TVRX2 is installed.
+Channel 0 is sourced from subdevice RX1,
+channel 1 is sourced from subdevice RX2:
+::
+
+    usrp->set_rx_subdev_spec("0:RX1 0:RX2");