docs: Major revisions and additions

9 files changed, 306 insertions, 52 deletions

diff --git a/host/docs/configuration.dox b/host/docs/configuration.dox
new file mode 100644
index 000000000..e16d1979e
--- /dev/null
+++ b/host/docs/configuration.dox
@@ -0,0 +1,109 @@
+/*! \page page_configuration Configuring Devices and Streamers
+
+\section config_devaddr Device Configuration through address string
+
+The address string for a device is mainly used to identify a device
+(see also \ref page_identification), but it can also be used to propagate
+settings to the device.
+
+As an example, say you run `rx_samples_to_file` with the following settings:
+
+    $ rx_samples_to_file --args type=b200,master_clock_rate=16e6
+
+This will first use the `type` flag to search your system for connected B200
+or B210 devices, as described on \ref page_identification. Once it has found
+one of these, it will connect to it and pass the `master_clock_rate=16e6` option
+to the device initialization (in this case, it will set the master clock rate
+to 16 MHz as described on \ref b200_mcr).
+
+The following table lists the configuration options you can pass as device
+arguments. Also check out the individual device manuals for more information
+and possible more options.
+
+ Key                 | Description                                                                  | Supported Devices | Example Value
+---------------------|------------------------------------------------------------------------------|-------------------|---------------------
+ blank_eeprom        | *Caution!* Having this key will erase the EEPROM and can damage your device! | X3x0              | blank_eeprom=1
+ fpga                | Provide alternative FPGA bitfile                                             | All USB Devices, X3x0 (PCIe only), All embedded devices | fpga=/path/to/bitfile.bit
+ fw                  | Provide alternative firmware                                                 | All USB Devices, X3x0 | fw=/path/to/fw.bin
+ ignore-cal-file     | Ignores existing device calibration files                                    | All Devices with cal-file support| See \ref ignore_cal_file
+ master_clock_rate   | Master Clock Rate in Hz                                                      | X3x0, B2x0, B1x0, E3x0, E1x0 | master_clock_rate=16e6
+ mcr                 | Override master clock rate settings (see \ref usrp1_hw_extclk)               | USRP1              | mcr=52e6
+ niusrprpc_port      | RPC Port for NI USRP RIO                                                     | X3x0               | niusrprpc_port=5445
+ system_ref_rate     | Reference Clock Rate in Hz                                                   | X3x0               | system_ref_rate=10e6
+
+
+In addition, many of the streaming-related options can be set per-device at configuration time.
+See \ref config_stream_args and \ref page_transport for more details.
+
+\section config_subdev Specifying the Subdevice
+
+A subdevice specification (or "subdev spec") string for USRP family devices is composed of:
+
+    <motherboard slot name>:<daughterboard frontend name>
+
+Ex: The subdev spec markup string to select a WBX on slot B.
+
+    B:0
+
+Ex: The subdev spec markup string to select a BasicRX on slot B.
+
+    B:AB
+
+    -- OR --
+
+    B:A
+
+    -- OR --
+
+    B:B
+
+A subdev spec can consist of multiple strings if a motherboard has the option
+for more than one radio device. In the X300, you may have an SBX in slot A and
+a CBX in slot B. Both of these daughterboards have one frontend ("0"), so the
+subdev spec to configure both these radio channels would look like this:
+
+    A:0 B:0
+
+The individual subdev specs are separated by spaces. On some devices, such as the
+X300 or the B200, it is possible to swap these to hint that slot B should be the
+first radio ("channel 0") and slot A should be the second radio ("channel 1"):
+
+    B:0 A:0
+
+On devices with more than one radio, setting the subdev spec to a single value
+declares that the other radio is not used. In a configuration with multiple USRPs,
+this means that this device will only be assigned a single channel.
+
+Note that a subdev spec string always only pertains to a *single* USRP, even if
+multiple USRPs are configured to run together. For such a configuration, you set
+a subdev spec string for every device individually.
+
+\subsection config_subdev_slotnames USRP Family Motherboard Slot Names
+
+All USRP family motherboards have a first slot named **A:**. The USRP1 and X3x0
+have two daughterboard subdevice slots, known as **A:** and **B:**.
+
+The B210 and E310 series have a different configuration, since their two radios
+are logically connected to the same "daughterboard" (which is in reality the
+integrated AD9361), but different frontends.
+To select both radios on a B200 or an E300, use this string:
+
+    A:A A:B
+
+\subsection config_subdev_default USRP Family Motherboard Slot Names
+
+\subsection config_subdev_dbnames Daughterboard Frontend Names
+
+Daughterboard frontend names can be used to specify which signal path is
+used from a daughterboard. Most daughterboards have only one frontend `:0`.
+A few daughterboards (Basic, LF and TVRX2) have multiple
+frontend names available. The frontend names are documented in \ref page_dboards.
+
+\section config_stream_args Streaming Arguments (Stream Args)
+
+When initializing a streamer using uhd::device::get_tx_stream() and/or uhd::device::get_rx_stream(),
+you must specify a uhd::stream_args_t object (see the manual for this struct and an in-depth
+explanation of the individual components).
+
+*/
+// vim:ft=doxygen:
diff --git a/host/docs/devices.dox b/host/docs/devices.dox
index 295cd999f..a494302b1 100644
--- a/host/docs/devices.dox
+++ b/host/docs/devices.dox
@@ -2,8 +2,10 @@
 
 ## General Usage Manuals
 
-\li \subpage page_general "Notes on tuning, subdev specs, overflow/underflow, other miscellaneous topics"
+\li \subpage page_general "Notes on tuning, overflow/underflow and other miscellaneous topics"
 \li \subpage page_identification
+\li \subpage page_configuration
+\li \subpage page_multiple
 \li \subpage page_images
 \li \subpage page_transport
 \li \subpage page_sync
@@ -11,7 +13,7 @@
 
 ## USRP N-Series Devices
 
-\li \subpage page_usrp2
+\li \subpage page_usrp2 "USRP N2x0 Series"
 
 ## USRP B-Series Devices
 
@@ -30,7 +32,7 @@
 
 ## USRP Legacy Series
 
-\li \subpage page_usrp2
+\li \ref page_usrp2 "USRP2 Series"
 
 ## Daughterboards
 
diff --git a/host/docs/general.dox b/host/docs/general.dox
index 1da284057..e4ffcfb6e 100644
--- a/host/docs/general.dox
+++ b/host/docs/general.dox
@@ -78,40 +78,6 @@ second).
     usrp->issue_stream_command(...);
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-\section general_subdev Specifying the Subdevice to Use
-
-A subdevice specification string for USRP family devices is composed of:
-
-    <motherboard slot name>:<daughterboard frontend name>
-
-Ex: The subdev spec markup string to select a WBX on slot B.
-
-    B:0
-
-Ex: The subdev spec markup string to select a BasicRX on slot B.
-
-    B:AB
-
-    -- OR --
-
-    B:A
-
-    -- OR --
-
-    B:B
-
-\subsection general_subdev_slotnames USRP Family Motherboard Slot Names
-
-All USRP family motherboards have a first slot named **A:**. The USRP1, the X3x0
-and the B210 have two daughterboard subdevice slots, known as **A:** and **B:**.
-
-\subsection general_subdev_dbnames Daughterboard Frontend Names
-
-Daughterboard frontend names can be used to specify which signal path is
-used from a daughterboard. Most daughterboards have only one frontend **:0**.
-A few daughterboards (Basic, LF and TVRX2) have multiple
-frontend names available. The frontend names are documented in \ref page_dboards.
-
 \section general_ounotes Overflow/Underflow Notes
 
 <b>Note:</b> The following overflow/underflow notes do not apply to USRP1,
diff --git a/host/docs/identification.dox b/host/docs/identification.dox
index 4ecb5c23d..7bacfea99 100644
--- a/host/docs/identification.dox
+++ b/host/docs/identification.dox
@@ -10,19 +10,23 @@ devices. Most UHD utility applications and examples have an `--args`
 parameter that takes a device address, which is expressed as a delimited
 string.
 
-See device_addr.hpp for reference.
+See uhd::device_addr_t for reference.
+
+Note that the device "address" can also take configuration options.
+See \ref page_configuration for a list of those options.
 
 \subsection id_identifying_common Common device identifiers
 
 Every device has several ways of identifying it on the host system:
 
-Identifier | Key      | Notes                                                     | Example
------------|----------|-----------------------------------------------------------|---------------------------------
-Serial     | serial   | globally unique identifier                                | 12345678
-Address    | addr     | unique identifier on a network                            | 192.168.10.2
-Resource   | resource | unique identifier for USRP RIO devices (over PCI Express) | RIO0
-Name       | name     | optional user-set identifier                              | my_usrp1 (User-defined value)
-Type       | type     | hardware series identifier                                | usrp1, usrp2, b200, x300, ...
+Identifier        | Key      | Notes                                                     | Example
+------------------|----------|-----------------------------------------------------------|---------------------------------
+Serial #          | serial   | globally unique identifier                                | 12345678
+IP Address        | addr     | unique identifier on a network                            | 192.168.10.2
+Resource          | resource | unique identifier for USRP RIO devices (over PCI Express) | RIO0
+Name              | name     | optional user-set identifier                              | my_usrp1 (User-defined value)
+Type              | type     | hardware series identifier                                | usrp1, usrp2, b200, x300, ...
+Vendor/Product ID | vid,pid  | For USB devices. Both must be provided                    | vid=0x04b4,pid=0x8613
 
 \subsection id_identifying_cmdline Device discovery via command line
 
diff --git a/host/docs/multiple.dox b/host/docs/multiple.dox
new file mode 100644
index 000000000..6a07ba8f5
--- /dev/null
+++ b/host/docs/multiple.dox
@@ -0,0 +1,99 @@
+/*! \page page_multiple Multiple USRP configurations
+
+\tableofcontents
+
+\section multiple_intro Introduction
+
+Some USRP devices are capable of being grouped to form a single, virtual device.
+A single uhd::usrp::multi_usrp instantiation can control such a compound of devices.
+
+Currently, the following devices support this capability:
+
+- USRP2 / N2x0 Series
+- X3x0 Series
+
+Note that only USRPs of the same type can be combined.
+
+\section multiple_setup Setting up devices
+
+A description of a multiple-USRP setup can be found on the respective device's manual pages.
+
+Addressing of a compound of devices is done by listing multiple addresses, e.g.:
+
+    addr0=192.168.10.2,addr1=192.168.20.2
+
+\section multiple_channumbers Channel and Device Numbering
+
+Assume we have combined 2 X310 USRPs into a single multi_usrp using the address string
+given above, maybe using the following command:
+
+\code{.cpp}
+uhd::device_addr_t args("addr0=192.168.10.2,addr1=192.168.20.2");
+uhd::usrp::multi_usrp::sptr usrp = uhd::usrp::multi_usrp::make(args);
+\endcode
+Some uhd::usrp::multi_usrp commands require passing a device index. This is simply
+the index in the address list, so say we want to check the master clock rate on both
+devices, this would be valid:
+\code{.cpp}
+double mcr0 = usrp->get_master_clock_rate(0);
+double mcr1 = usrp->get_master_clock_rate(1);
+\endcode
+
+Some methods default to applying to all devices, so the following command
+would set the time on all devices to zero:
+\code{.cpp}
+usrp->set_time_next_pps(uhd::time_spec_t(0));
+\endcode
+
+So, device indexes run from 0 to N-1 where N is the number of devices.
+
+Channels are indexed in a similar way. Channel indexes run from 0 to M-1 where
+M is the total number of channels on all devices.
+
+The number and order of channels per device depends on the subdev spec (see
+also \ref config_subdev). In the current example, assume all the X310 USRPs
+are using their standard configuration, and all have two daughterboards inside.
+
+In this case channels 0 and 1 map to slot A and B of the first USRP, respectively.
+Channels 2 and 3 map to slots A and B of the second USRP, and so on.
+
+However, by changing the subdev spec on individual devices, this can change.
+Say we have this unusual piece of code next:
+
+\code{.cpp}
+usrp->set_rx_subdev_spec("A:0 B:0", 0);
+usrp->set_rx_subdev_spec("A:0", 1);
+usrp->set_rx_subdev_spec("B:0 A:0", 2);
+\endcode
+
+The first device uses the default configuration. The second device artificially
+disables slot B, giving this USRP a single channel only. The third device uses
+both devices, but flips their order.
+
+Now, there's a total of 5 channels, mapped as:
+- Channel 0: Slot A of Device 0
+- Channel 1: Slot B of Device 0
+- Channel 2: Slot A of Device 1
+- Channel 3: Slot A of Device 2
+- Channel 1: Slot B of Device 2
+
+While valid, this kind of configuration is not recommended unless heavily
+documented. It is usually simplest to call `set_rx_subdev_spec()` without
+a device index, which will set the same subdev spec on all devices.
+This assumes all devices have a similar daughterboard configuration
+
+\section multiple_mimo MIMO Operation
+
+When a multi-channel streamer is generated from a compound multi_usrp, and
+a streamer with multiple channels is generated, MIMO operations is automatically
+chosen. This means samples will be aligned between streams automatically.
+
+In order for this to work, all devices must use a common time and frequency
+reference. This can be achieved in different ways, e.g. by daisy-chaining
+devices (for a small number of X-Series devices), using the MIMO cable (when
+only 2 N2x0 devices are used), or using a clock distribution system, e.g. an
+OctoClock. See \ref page_sync and the individual device manuals on more details
+on how to do this.
+
+*/
+// vim:ft=doxygen:
diff --git a/host/docs/transport.dox b/host/docs/transport.dox
index 942fa9509..eb7232f36 100644
--- a/host/docs/transport.dox
+++ b/host/docs/transport.dox
@@ -21,12 +21,15 @@ standard Berkeley sockets API using send()/recv().
 \subsection transport_udp_params Transport parameters
 
 The following parameters can be used to alter the transport's default
-behavior:
+behavior (these options can be passed to a USRP device as arguments
+at initialization time, see also \ref config_devaddr, or to a streamer,
+see uhd::stream_args_t::args):
 
 -   `recv_frame_size:` The size of a single receive buffer in bytes
 -   `num_recv_frames:` The number of receive buffers to allocate
 -   `send_frame_size:` The size of a single send buffer in bytes
 -   `num_send_frames:` The number of send buffers to allocate
+-   `recv_buff_fullness:` The targetted fullness factor of the the buffer (typically around 90%)
 
 <b>Notes:</b>
 - `num_recv_frames` does not affect performance.
diff --git a/host/docs/usrp_e3x0.dox b/host/docs/usrp_e3x0.dox
index 289ea3410..ebe02627a 100644
--- a/host/docs/usrp_e3x0.dox
+++ b/host/docs/usrp_e3x0.dox
@@ -489,8 +489,8 @@ by pinging the USRP and making sure the LEDs start to blink.
 \subsection e3x0 Frequently Asked Questions
 
  - Communication
-  -# How do I enable X forwarding so I can run X apps on the e3x0?\n
-     In the file `/etc/ssh/sshd_config`, unmcomment the line `#X11Forwarding no`
+  -# How do I enable X forwarding so I can run X apps on the E3x0?<br>
+     In the file `/etc/ssh/sshd_config`, uncomment the line \#`X11Forwarding no`
      and change "no" to "yes".
 
 \section e3x0_apps Applications
diff --git a/host/docs/usrp_x3x0.dox b/host/docs/usrp_x3x0.dox
index 847efe74e..a9b31df57 100644
--- a/host/docs/usrp_x3x0.dox
+++ b/host/docs/usrp_x3x0.dox
@@ -378,6 +378,8 @@ Example:
 - Ethernet interface subnet mask: `255.255.255.0`
 - USRP-X Series device IPv4 address: `192.168.110.2`
 
+If all devices are to be used in a compound, see also \ref page_multiple.
+
 \subsection x3x0_setup_change_ip Change the USRP's IP address
 
 You may need to change the USRP's IP address for several reasons:
@@ -436,6 +438,7 @@ Example device address string representation for 2 USRPs with IPv4 addresses **1
 
     addr0=192.168.10.2, addr1=192.168.20.2
 
+See also \ref page_multiple.
 
 \section x3x0_comm_problems Communication Problems
 
@@ -607,6 +610,16 @@ Further information on how to use Chipscope can be found in the Xilinx Chipscope
 
 \section x3x0_misc Miscellaneous
 
+\subsection x3x0_misc_settings Configuring the device in an application
+
+During runtime, the device can be configured in several different ways.
+
+The following pages may shed some light:
+
+- \ref page_configuration
+- uhd::stream_args_t
+- \ref multiple_channumbers
+
 \subsection x3x0_misc_multirx Multiple RX channels
 
 There are two complete DDC and DUC DSP chains in the FPGA. In the single channel case,
diff --git a/host/include/uhd/stream.hpp b/host/include/uhd/stream.hpp
index 75b097ded..ccf961aad 100644
--- a/host/include/uhd/stream.hpp
+++ b/host/include/uhd/stream.hpp
@@ -33,8 +33,25 @@ namespace uhd{
 /*!
  * A struct of parameters to construct a streamer.
  *
- * Note:
- * Not all combinations of CPU and OTW format have conversion support.
+ * Here is an example of how a stream args object could be used in conjunction
+ * with uhd::device::get_rx_stream():
+ *
+ * \code{.cpp}
+ * // 1. Create the stream args object and initialize the data formats to fc32 and sc16:
+ * uhd::stream_args_t stream_args("fc32", "sc16");
+ * // 2. Set the channel list, we want 3 streamers coming from channels
+ * //    0, 1 and 2, in that order:
+ * stream_args.channels = boost::assign::list_of(0)(1)(2);
+ * // 3. Set optional args:
+ * stream_args.args["spp"] = "200"; // 200 samples per packet
+ * // Now use these args to create an rx streamer:
+ * // (We assume that usrp is a valid uhd::usrp::multi_usrp)
+ * uhd::rx_streamer::sptr rx_stream = usrp->get_rx_stream(stream_args);
+ * // Now, any calls to rx_stream must provide a vector of 3 buffers,
+ * // one per channel.
+ * \endcode
+ *
+ * \b Note: Not all combinations of CPU and OTW format have conversion support.
  * You may however write and register your own conversion routines.
  */
 struct UHD_API stream_args_t{
@@ -61,6 +78,8 @@ struct UHD_API stream_args_t{
      *  - f64 - double
      *  - s16 - int16_t
      *  - s8 - int8_t
+     *
+     * The CPU format can be chosen depending on what the application requires.
      */
     std::string cpu_format;
 
@@ -69,10 +88,18 @@ struct UHD_API stream_args_t{
      * The following over-the-wire formats have been implemented:
      *  - sc16 - Q16 I16
      *  - sc8 - Q8_1 I8_1 Q8_0 I8_0
+     *  - sc12 (Only some devices)
      *
      * The following are not implemented, but are listed to demonstrate naming convention:
      *  - s16 - R16_1 R16_0
      *  - s8 - R8_3 R8_2 R8_1 R8_0
+     *
+     * Setting the OTW ("over-the-wire") format is, in theory, transparent to the application,
+     * but changing this can have some side effects. Using less bits for example (e.g. when going
+     * from `otw_format` `sc16` to `sc8`) will reduce the dynamic range, and increases quantization
+     * noise. On the other hand, it reduces the load on the data link and thus allows more bandwidth
+     * (a USRP N210 can work with 25 MHz bandwidth for 16-Bit complex samples, and 50 MHz for 8-Bit
+     * complex samples).
      */
     std::string otw_format;
 
@@ -101,17 +128,48 @@ struct UHD_API stream_args_t{
      * Users should specify this option to request smaller than default
      * packets, probably with the intention of reducing packet latency.
      *
+     * - noclear: Used by tx_dsp_core_200 and rx_dsp_core_200
+     *
      * The following are not implemented, but are listed for conceptual purposes:
      * - function: magnitude or phase/magnitude
      * - units: numeric units like counts or dBm
+     *
+     * In addition, all the transport-related options explained on \ref page_transport can be set here.
+     * These options can be set either when creating the device (see also \ref config_devaddr),
+     * or when creating the streamer (when the options are given both times, the stream args
+     * take precedence):
+     *
+     * - recv_frame_size
+     * - send_frame_size
+     * - num_recv_frames
+     * - num_send_frames
+     * - ups_per_sec
+     * - ups_per_fifo
+     * - recv_buff_fullness
+     *
+     * Other options are device-specific:
+     * - port, addr: Alternative receiver streamer destination.
      */
     device_addr_t args;
 
     /*!
      * The channels is a list of channel numbers.
-     * Leave this blank to default to channel 0.
+     * Leave this blank to default to channel 0 (single-channel application).
      * Set channels for a multi-channel application.
-     * Channel mapping depends on the front-end selection.
+     * Channel mapping depends on the front-end selection (see also \ref config_subdev).
+     *
+     * A very simple example is an X300 with two daughterboards and a subdev spec
+     * of `A:0 B:0`. This means the device has two channels available.
+     *
+     * Setting `stream_args.channels = (0, 1)` therefore configures MIMO streaming
+     * from both channels. By switching the channel indexes, `stream_args.channels = (1, 0)`,
+     * the channels are switched and the first channel of the USRP is mapped to
+     * the second channel in the application.
+     *
+     * If only a single channel is used for streaming, `stream_args.channels = (1,)` would
+     * only select a single channel (in this case, the second one). When streaming
+     * a single channel from the B-side radio of a USRP, this is a more versatile solution
+     * than setting the subdev globally to "B:0".
      */
     std::vector<size_t> channels;
 };