Merge branch 'master' into ashish/register_api

6 files changed, 221 insertions, 5 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index 79488e373..063bfd901 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -75,6 +75,8 @@ IF(ENABLE_DOXYGEN)
     SET(ENABLE_MANUAL_OR_DOXYGEN true)
     #make doxygen directory depend on the header files
     FILE(GLOB_RECURSE header_files ${CMAKE_SOURCE_DIR}/include/*.hpp)
+    FILE(GLOB_RECURSE h_files ${CMAKE_SOURCE_DIR}/include/*.h)
+    LIST(APPEND header_files ${h_files})
     SET(DOXYGEN_DEPENDENCIES ${DOXYGEN_DEPENDENCIES} ${header_files})
     IF(ENABLE_DOXYGEN_FULL)
         SET(DOXYGEN_INPUT_DIRS "${DOXYGEN_INPUT_DIRS} ${CMAKE_SOURCE_DIR}/include ${CMAKE_SOURCE_DIR}/lib")
diff --git a/host/docs/c_api.dox b/host/docs/c_api.dox
new file mode 100644
index 000000000..5b5790f21
--- /dev/null
+++ b/host/docs/c_api.dox
@@ -0,0 +1,86 @@
+/*! \page page_c_api UHD - C API
+
+\tableofcontents
+
+\section c_api_intro Introduction
+
+Alongside its C++ API, UHD provides a C API wrapper for the uhd::usrp::multi_usrp and
+uhd::usrp_clock::multi_usrp_clock classes, as well as their associated classes and
+structs. Other important UHD functions are also included in this API. To use this
+API, simply:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
+#include <uhd.h>
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+...and all UHD C-level structs and functions will be available to you. The sections below
+give more detail on the key features of the C API.
+
+\subsection c_api_handles C-Level Handles
+
+Most of the UHD classes that can be accessed on the C level are done so through handles,
+which internally store the C++ representation and allow access to internal values
+through helper functions.
+
+All handles have associated *_make() and *_free() functions. After creating a handle, it must
+be passed through its make() function before it can be used in your program. Before the program
+terminates, you must pass the handle into its free() function, or your program will have a memory
+leak. The example below shows the proper usage of an RX metadata handle over the course of its
+lifetime, from instantiation to destruction.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+uhd_rx_metadata_handle md;
+uhd_rx_metadata_make(&md);
+
+// Streaming here puts useful information into metadata
+time_t full_secs;
+double frac_secs;
+uhd_rx_metadata_time_spec(md, &full_secs, &frac_secs);
+
+uhd_rx_metadata_free(&md);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Again, make sure to pass your handle into a make() function before using it, or you will
+run into undefined behavior. Also be careful not to use the handle after passing it into
+a free() function, or your program will segfault.
+
+\subsection c_api_errorcode Error Codes
+
+As C cannot handle C++ runtime exceptions, UHD's C wrapper functions catch all exceptions
+and translate them into error codes, which are returned by each function. Any output variables
+are passed in as pointers into the function, which will set them internally.
+
+Each uhd::runtime_error has a corresponding ::uhd_error value. Separate error codes indicate
+that a boost::exception or std::exception has been thrown, and any other exceptions are
+indicated by a catch-all ::UHD_ERROR_UNKNOWN code.
+
+All UHD C-level handles store the string representation of the last C++ exception thrown internally.
+These handles have corresponding *_get_last_error() functions that will place the error string into a
+supplied string buffer.
+
+For example, if a USRP device's handle throws an exception internally, the following code can access
+its error info:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+char err_msg[256];
+uhd_usrp_handle usrp;
+double gain;
+// USRP configuration done here
+uhd_error error_code = uhd_usrp_get_rx_gain(usrp, 0, "", &gain);
+if(error_code){
+    uhd_usrp_get_last_error(usrp, err_msg, 256);
+    fprintf(stderr, "Error code %d: %s\n", error_code, err_msg);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All error codes can be found in <uhd/error.h>.
+
+\subsection c_api_examples Example Code
+
+UHD provides two examples that demonstrate the typical use case of the C API: RX and TX streaming.
+The <b>rx_samples_c</b> example is a simplified C version of <b>rx_samples_to_file</b>,
+and the <b>tx_samples_c</b> example is a simplified C version of <b>tx_waveforms</b>. These examples
+can be easily adapted or serve as a starting point for your own UHD C applications.
+
+*/
+// vim:ft=doxygen:
diff --git a/host/docs/coding.dox b/host/docs/coding.dox
index 32dbe944a..6a15098d7 100644
--- a/host/docs/coding.dox
+++ b/host/docs/coding.dox
@@ -16,6 +16,11 @@ The Multi-USRP-Clock class provides a high-level interface to a single clock
 device or set of clock devices, from which the time can be queried. See the
 documentation for uhd::usrp_clock::multi_usrp_clock.
 
+\subsection coding_api_hilevelc High-Level: The C API
+
+Both USRP and clock devices can be interacted with using a C API wrapper included
+by default in all UHD builds. More information can be found \subpage page_c_api "here".
+
 \subsection coding_api_lowlevel Low-Level: The device API
 
 A device is an abstraction for hardware that is connected to the host
diff --git a/host/docs/general.dox b/host/docs/general.dox
index e4ffcfb6e..3e9dfc63a 100644
--- a/host/docs/general.dox
+++ b/host/docs/general.dox
@@ -34,6 +34,8 @@ support this functionality are:
 - SBX-120
 - CBX
 - CBX-120
+- UBX
+- UBX-160
 
 \subsubsection general_tuning_rxchain Tuning the receive chain:
 
@@ -78,6 +80,45 @@ second).
     usrp->issue_stream_command(...);
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+\section general_sampleratenotes Sample rate notes
+
+Sample rates as delivered to the host computer for USRP devices are constrained to follow several important rules.
+
+It is important to understand that strictly-integer <b>decimation</b> and <b>interpolation</b> are used within USRP
+hardware to meet the requested sample-rate requirements of the application at hand.  That means that the desired
+sample rate must meet the requirement that master-clock-rate/desired-sample-rate be an integer ratio.  Further, it is
+strongly desirable for that ratio to be <b>even</b>.
+
+There are further constraints on the desired sample rate, such that if the required decimation or interpolation exceeds 128,
+then the resulting decimation <b>must</b> be evenly divisible by 2, and that if the required decimation exceeds 256, the
+resulting decimation \b must be evenly divisible by 4.
+
+For USRP devices with fixed master clocks (notably: USRP1, USRP2, N2xx), there are fewer effective sample rates available than
+on USRP hardware that provides some flexibility in selecting a master clock.  Several USRP devices support flexible master
+clock selection, allowing a broader range of sample rate selections by applications. See the individual devices' manual
+pages for more details.
+
+In many cases using USRPs with flexible master-clock rates, it is possible to achieve lower sample rates without running into
+the constraints of higher decimations, simply by choosing a lower master-clock rate to keep required decimation below 128.
+
+\subsection general_sampleratenotes_automatic Automatic master-clock selection
+
+In recent versions of UHD software (3.8.5 and newer), and on some devices (currently: B2xx and E3xx series),
+the master clock rate is chosen automatically (unless specified by the user).
+UHD will select a master clock rate that is consistent with the desired sample rate indicated by the application.
+
+\subsection general_sampleratenotes_nyquist Master clock rate and Nyquist
+
+In selecting a master clock rate on certain USRP hardware (X3xx and B1xx), it is important to select a rate that still provides
+correct alias suppression by the analog hardware.  For daughtercards with a 40 MHz analog bandwidth, this means the clock rate 
+must be <b>at least</b> 40 MHz, with better performance to be expected with a higher clock rate.  For daughtercards
+with 160 MHz bandwidth, it must be <b>at least</b> 160 MHz, again, better performance is to expected with a higher clock rate.
+
+For hardware with fixed master clock rates, of course, this isn't a consideration.
+
+For B2xx and E3xx hardware, the alias suppression is handled differently by the AD936x RFIC, and master clock rate
+is significantly more flexible as a result.
+
 \section general_ounotes Overflow/Underflow Notes
 
 <b>Note:</b> The following overflow/underflow notes do not apply to USRP1,
diff --git a/host/docs/usrp_e3x0.dox b/host/docs/usrp_e3x0.dox
index b175cc201..e6a574a51 100644
--- a/host/docs/usrp_e3x0.dox
+++ b/host/docs/usrp_e3x0.dox
@@ -1,4 +1,4 @@
-/*! \page page_usrp_e3x0 USRP-E3x0 Series
+/*! \page page_usrp_e3x0 USRP-E3xx Series
 
 \tableofcontents
 
@@ -35,7 +35,7 @@ There are two different methods to connect to the device
 - using the gigabit ethernet connector and a ssh client on your host computer
 
 For the first boot, booting with the serial cable connected to the device
-is recommended, as it allows to review and modify the network configuration,
+is recommended, as it allows to review and modify the \ref e3xx_network_configuration
 and allows to enter the bootloader in case of issues during the boot.
 
 
@@ -134,6 +134,8 @@ which should return 'arm-oe-linux-gnueabi'.
         $ cmake -DCMAKE_TOOLCHAIN_FILE=<youruhdsrc>/host/cmake/Toolchains/oe-sdk_cross.cmake -DCMAKE_INSTALL_PREFIX=/usr -DENABLE_E300=ON ..
         $ make
 
+For instructions on building UHD on a PC to interact with your E-Series device, follow these instructions: \ref e3x0_uhd_build
+
 \subsubsection e3x0_sdk_usage_gnuradio Building GNU Radio
 
 -# Obtain the gnuradio source code via git.
@@ -248,8 +250,7 @@ You may need to change the USRP's IP address for several reasons:
 - to use multiple USRP-E Series devices with the same host computer
 - to set a known IP address into USRP (in case you forgot)
 
-
-
+For examples refer to the \ref e3xx_network_configuration section.
 
 \section e3x0_hw Hardware Notes
 
@@ -626,6 +627,51 @@ TRX-B   | >= 2940.0       | 11            | 10             | XXX
 _Note: Although the transmit filters are low pass, the following table describes UHD's tuning range for selecting each filter path.
 The table also includes the required transmit enable states._
 
+\section e3xx_network_configuration Network configuration
+
+Your USRP E3XX Series device can be configured by editing the /etc/network/interfaces.<br>
+The device defaults to *DHCP*, meaning it will query the local network's DHCP server for an address.
+
+\subsection e3xx_network_dhcp DHCP
+
+The default configuration should look similar to, instructing your device to query
+local DHCP servers for an IP address, gateway, etc.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+auto eth0
+iface eth0 inet dhcp
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to change the hostname used to obtain an IP address via DHCP change
+
+    /etc/hostname
+
+and edit:
+
+    /etc/network/interfaces
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+auto eth0
+iface eth0 inet dhcp
+    hostname your-hostname
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+\subsection e3xx_network_static Static IP
+
+To configure a static IP address edit
+
+    /etc/hostname
+
+to look like
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+auto eth0
+iface eth0 inet static
+    address your-ip
+    netmask your-netmask
+    gateway your-gateway
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 \section e3x0_misc Miscellaneous
 
 \subsection e3x0_misc_multirx Multiple RX channels
@@ -655,10 +701,22 @@ they can be queried through the API.
 
 \subsection e3x0_network_mode Network Mode
 
-Your USRP-E series device can be used in network mode for narrow band signal observation, evaluation and debugging purposes.
+Your USRP-E series device can be used in network mode for narrow band signal observation, evaluation and debugging purposes. See the instructions below for how to use network mode.
 
 Please note that when compared with normal operation as a standalone device the usable bandwidth is limited and therefore Network Mode is not the recommended mode of operation.
 
+\subsubsection e3x0_uhd_build Building UHD
+
+To work with your E-Series device in network mode, you will need to build UHD on your PC with extra CMake flags. Assuming you are in the host/build directory,
+see below:
+
+        $ cmake -DENABLE_E300=ON -DE300_FORCE_NETWORK=ON ..
+        $ make
+
+Once UHD is installed on your device, it will be able to interact with an E-Series device with network mode active (see below).
+
+\subsubsection e3x0_activating_network Activating Network Mode on the Device
+
 In order to use the device in network mode it is necessary to start the *usrp_e3x0_network_mode* executable on the device.
 In order to start the executable please log into your device either via SSH or serial console(see \ref e3x0_first_boot) and type
 
diff --git a/host/docs/usrp_x3x0.dox b/host/docs/usrp_x3x0.dox
index 7183efc04..bf2323b71 100644
--- a/host/docs/usrp_x3x0.dox
+++ b/host/docs/usrp_x3x0.dox
@@ -609,6 +609,30 @@ The +3.3V is for ESD clamping purposes only and not designed to deliver high cur
 
 Please see the \ref page_gpio_api for information on configuring and using the GPIO bus.
 
+\subsection x3x0_hw_on_board_leds On-Board LEDs
+
+|LED	| 	 	| Description			|
+|-------|---------------|-------------------------------|
+|DS1	|1.2V		|power				|
+|DS2	|TXRX1		|Red: TX,  Green: RX		|
+|DS3	|RX1		|Green: RX			|
+|DS4	|REF		|reference lock			|
+|DS5	|PPS		|flashes on edge		|
+|DS6	|GPS		|GPS lock			|
+|DS7	|SFP0		|link				|
+|DS8	|SFP0		|link activity			|
+|DS10	|TXRX2		|Red: TX Green: RX		|
+|DS11	|RX2		|Green: RX			|
+|DS12	|6V		|daughterboard power		|
+|DS13	|3.8V		|power				|
+|DS14	|3.3V		|management power		|
+|DS15	|3.3V		|auxiliary management power	|
+|DS16	|1.8V		|FPGA power			|
+|DS16	|3.3V		|FPGA power			|
+|DS19	|SFP1		|link				|
+|DS20	|SFP1		|link active			|
+|DS21	|LINK		|link activity			|
+
 \subsection x3x0_hw_chipscope Debugging custom FPGA designs with Xilinx Chipscope
 
 Xilinx chipscope allows for debugging custom FPGA designs similar to a logic analyzer.