aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMartin Braun <martin.braun@ettus.com>2017-07-19 17:43:48 -0700
committerMartin Braun <martin.braun@ettus.com>2017-07-19 17:47:46 -0700
commitf19440e2141811ad0866022946110aa815ff6e7d (patch)
tree0a11f3bb7f268a78d2d73725cbfd072fd4ff12d9
parent4b4576b06bd2c209d29c4fd2afd61e0485d91b0c (diff)
downloaduhd-f19440e2141811ad0866022946110aa815ff6e7d.tar.gz
uhd-f19440e2141811ad0866022946110aa815ff6e7d.tar.bz2
uhd-f19440e2141811ad0866022946110aa815ff6e7d.zip
docs: Minor updates regarding C API
-rw-r--r--host/docs/c_api.dox31
-rw-r--r--host/docs/uhd.dox1
2 files changed, 25 insertions, 7 deletions
diff --git a/host/docs/c_api.dox b/host/docs/c_api.dox
index 5b5790f21..b37b81aae 100644
--- a/host/docs/c_api.dox
+++ b/host/docs/c_api.dox
@@ -4,17 +4,34 @@
\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:
+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.
+...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.
+
+Keep in mind that the C-API is a wrapper around the C++ API, so performance can
+never exceed that of the C++ API.
+
+\subsection c_api_philosophy API Philosophy
+
+The C API was designed to mirror the C++ API as closely as possible. This means
+that most API calls are mapped 1:1 from C++ to C, and the documentation for the
+C++ API can still be useful and should be considered when using the C API.
+For example, the uhd_usrp_set_rx_antenna() and
+uhd::multi_usrp::set_rx_antenna() calls do the same thing under the hood, and
+thus, if the behaviour of the C API call is unclear, consulting the
+corresponding C++ API call documentation can be helpful.
+
+There are some C++ concepts that don't map into C easily, though. Among those
+are object storage, which is solved by using handles (see \ref c_api_handles)
+and exceptions, which are translated into error codes (see \ref c_api_errorcode).
\subsection c_api_handles C-Level Handles
@@ -28,7 +45,7 @@ terminates, you must pass the handle into its free() function, or your program w
leak. The example below shows the proper usage of an RX metadata handle over the course of its
lifetime, from instantiation to destruction.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
uhd_rx_metadata_handle md;
uhd_rx_metadata_make(&md);
diff --git a/host/docs/uhd.dox b/host/docs/uhd.dox
index 5474d42e2..320a4dd18 100644
--- a/host/docs/uhd.dox
+++ b/host/docs/uhd.dox
@@ -10,6 +10,7 @@ publically available symbol in the UHD namespace.
Some additional pages on developing UHD are also available here:
\li \subpage page_coding
+\li \subpage page_c_api
\li \subpage page_converters
\li \subpage page_stream
\li \subpage page_rtp