From cf5a45b140163ae330f0017a85c0a9fd9a29cc0c Mon Sep 17 00:00:00 2001
From: Josh Blum <josh@joshknows.com>
Date: Tue, 20 Apr 2010 16:18:39 -0700
Subject: added coding docs

---
 host/docs/CMakeLists.txt |  1 +
 host/docs/coding.rst     | 63 ++++++++++++++++++++++++++++++++++++++++++++++++
 host/docs/index.rst      |  1 +
 3 files changed, 65 insertions(+)
 create mode 100644 host/docs/coding.rst

(limited to 'host/docs')

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index 476023a1e..1bbd52fee 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -21,6 +21,7 @@
 SET(manual_sources
     index.rst
     build.rst
+    coding.rst
     usrp2.rst
 )
 
diff --git a/host/docs/coding.rst b/host/docs/coding.rst
new file mode 100644
index 000000000..689667f30
--- /dev/null
+++ b/host/docs/coding.rst
@@ -0,0 +1,63 @@
+========================================================================
+UHD - Coding to the API
+========================================================================
+
+.. contents:: Table of Contents
+
+------------------------------------------------------------------------
+Low-Level: The device API
+------------------------------------------------------------------------
+A device is an abstraction for hardware that is connected to the host system.
+For a USRP, this means that the motherboard and everything on it would be considered to be a "device".
+The device API provides ways to:
+
+* Discover devices that are physical connected to the host system.
+* Create a device object for a particular physical device identified by address.
+* Register a device driver into the discovery and factory sub-system.
+* Streaming samples with metadata into and out of the device.
+* Set and get properties on the device object.
+
+See the documentation in device.hpp for reference.
+
+------------------------------------------------------------------------
+High-Level: The simple usrp
+------------------------------------------------------------------------
+The goal of the simple usrp is to wrap high level functions around the device properties.
+The simple usrp provides a fat interface to access the most common properties.
+The simple usrp provides ways to:
+
+* Set and get daughterboard gains.
+* Set and get daughterboard antennas.
+* Set and get the streaming rates.
+* Tune the DSPs and daughterboards.
+* Issue stream commands.
+* Set the clock configuration.
+* Set the usrp time registers.
+* Get the underlying device (as discussed above).
+
+It is recommended that users code to the simple_usrp api when possible.
+See the documentation in usrp/simple_usrp.hpp for reference.
+
+------------------------------------------------------------------------
+Integrating custom hardware
+------------------------------------------------------------------------
+Creators of custom hardware can create drivers that use the UHD API.
+These drivers can be built as dynamically lodable modules that the UHD will load at runtime.
+For a module to be loaded at runtime, it must be found in the UHD_MODULE_PATH environment variable.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Custom motherboard
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Create a new device driver when the driver in lib/usrp/
+cannot support your custom FPGA or hardware modifications.
+Make a copy of the relevant driver code in lib/usrp/, make mods, and rename the class.
+The new device code should register itself into the discovery and factory system. 
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Custom daughterboard
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Use code from an existing daughterboard in lib/usrp/dboard/* as an example.
+Your daughterboard code should subclass an rx dboard, rx dboard, or xcvr dboard;
+and it should respond to calls to get and set properties.
+The new daughterboard code should register itself into the dboard manager
+with a unique rx and/or tx 16 bit identification number.
diff --git a/host/docs/index.rst b/host/docs/index.rst
index 51dba26b5..37853b0b6 100644
--- a/host/docs/index.rst
+++ b/host/docs/index.rst
@@ -16,6 +16,7 @@ Contents
 API Documentation
 ^^^^^^^^^^^^^^^^^^^^^
 * `Doxygen <./../../doxygen/html/index.html>`_
+* `Using the API <./coding.html>`_
 
 ^^^^^^^^^^^^^^^^^^^^^
 Supported Devices
-- 
cgit v1.2.3