uhd: C API wrapper

* multi_usrp, multi_usrp_clock, and associated classes accessible through C
* Added Doxygen documentation explaining structure and API
* Simple RX and TX streaming examples
* Unit tests for different parts of C interface and C++ error conversion

3 files changed, 92 insertions, 1 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index 79488e373..3ad2ef37c 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -74,7 +74,7 @@ ENDIF(LIBUHDDEV_PKG)
 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 header_files ${CMAKE_SOURCE_DIR}/include/*.h*)
     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