docs: Moved manual to Doxygen

1 files changed, 220 insertions, 0 deletions

diff --git a/host/docs/general.dox b/host/docs/general.dox
new file mode 100644
index 000000000..14f017d04
--- /dev/null
+++ b/host/docs/general.dox
@@ -0,0 +1,220 @@
+/*! \page page_general General Application Notes
+
+\tableofcontents
+
+\section general_tuning Tuning Notes
+
+\subsection general_tuning_process Two-stage tuning process
+
+A USRP device has two stages of tuning:
+
+- RF front-end: translates bewteen RF and IF
+- DSP: translates between IF and baseband
+
+In a typical use-case, the user specifies an overall center frequency
+for the signal chain. The RF front-end will be tuned as close as
+possible to the center frequency, and the DSP will account for the error
+in tuning between target frequency and actual frequency. The user may
+also explicitly control both stages of tuning through through the **tune_request_t** object, which allows for more advanced tuning.
+
+In general, Using UHD software's advanced tuning is highly recommended
+as it makes it easy to move the DC component out of your
+band-of-interest. This can be done by passing your desired LO offset to
+the **tune_request_t** object, and letting the UHD software handle the
+rest.
+
+The **tune_request_t** object can also be used with certain
+daughterboards to use Integer-N tuning instead of the default fractional
+tuning, allowing for better spur performance. The daughterboards that
+support this functionality are:
+
+- WBX (all revisions)
+- WBX-120
+- SBX (all revisions)
+- SBX-120
+- CBX
+- CBX-120
+
+\subsubsection general_tuning_rxchain Tuning the receive chain:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+//tuning to a desired center frequency
+usrp->set_rx_freq(target_frequency_in_hz);
+
+--OR--
+
+//advanced tuning with tune_request_t uhd::tune_request_t
+tune_req(target_frequency_in_hz, desired_lo_offset);
+tune_req.args = uhd::device_addr_t("mode_n=integer"); //to use Int-N tuning
+//fill in any additional/optional tune request fields...
+usrp->set_rx_freq(tune_req);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+More information can be found in uhd::tune_request_t.
+
+\subsection general_tuning_rfsettling RF front-end settling time
+
+After tuning, the RF front-end will need time to settle into a usable
+state. Typically, this means that the local oscillators must be given
+time to lock before streaming begins. Lock time is not consistent; it
+varies depending upon the device and requested settings. After tuning
+and before streaming, the user should wait for the **lo_locked** sensor
+to become true or sleep for a conservative amount of time (perhaps a
+second).
+
+\subsubsection general_tuning_waitcode Pseudo-code for dealing with settling time after tuning on receive:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+    usrp->set_rx_freq(...);
+    sleep(1);
+    usrp->issue_stream_command(...);
+
+    --OR--
+
+    usrp->set_rx_freq(...);
+    while (not usrp->get_rx_sensor("lo_locked").to_bool()){
+        //sleep for a short time in milliseconds
+    }
+    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 and the X3x0
+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,
+which does not support the advanced features available in newer
+products.
+
+\subsection general_ounotes_overflow Overflow notes
+
+When receiving, the device produces samples at a constant rate.
+Overflows occurs when the host does not consume data fast enough. When
+UHD software detects the overflow, it prints an "O" or "D" to stdout,
+and pushes an inline message packet into the receive stream.
+
+<b>Network-based devices</b>: The host does not back-pressure the receive
+stream. When the kernel's socket buffer becomes full, it will drop
+subsequent packets. UHD software detects the overflow as a discontinuity
+in the packet's sequence numbers, and pushes an inline message packet
+into the receive stream. In this case the character "D" is printed to
+stdout as an indication.
+
+<b>Other devices</b>: The host back-pressures the receive stream.
+Therefore, overflows always occur in the device itself. When the
+device's internal buffers become full, streaming is shut off, and an
+inline message packet is sent to the host. In this case the character
+"O" is printed to stdout as an indication. If the device was in
+continuous streaming mode, the UHD software will automatically restart
+streaming when the buffer has space again.
+
+\subsection general_ounotes_underrun Underrun notes
+
+When transmitting, the device consumes samples at a constant rate.
+Underflow occurs when the host does not produce data fast enough. When
+UHD software detects the underflow, it prints a "U" to stdout, and
+pushes a message packet into the async message stream.
+
+<b>Note:</b> "O" and "U" message are generally harmless, and just mean the host machine can't keep up with the requested rates.
+
+\section general_threading Threading Notes
+
+\subsection general_threading_safety Thread safety notes
+
+For the most part, UHD software is thread-safe. Please observe the
+following limitations:
+
+<b>Fast-path thread requirements:</b> There are three fast-path methods for
+a device: `send()`, `recv()`, and `recv_async_msg()`. All three
+methods are thread-safe and can be called from different thread
+contexts. For performance, the user should call each method from a
+separate thread context. These methods can also be used in a
+non-blocking fashion by using a timeout of zero.
+
+<b>Slow-path thread requirements:</b> It is safe to change multiple
+settings simultaneously. However, this could leave the settings for a
+device in an uncertain state. This is because changing one setting could
+have an impact on how a call affects other settings. Example: setting
+the channel mapping affects how the antennas are set. It is recommended
+to use at most one thread context for manipulating device settings.
+
+\subsection general_threading_prio Thread priority scheduling
+
+When UHD software spawns a new thread it may try to boost the thread's
+scheduling priority. When setting the priority fails, the UHD software
+prints out an error. This error is harmless; it simply means that the
+thread will have a normal scheduling priority.
+
+<b>Linux Notes:</b>
+
+Non-privileged users need special permission to change the scheduling
+priority. Add the following line to `/etc/security/limits.conf`:
+
+    @GROUP    - rtprio    99
+
+Replace `GROUP` with a group to which your user belongs.
+Settings will not take effect until the user is in a different login
+session.
+
+\section general_misc Miscellaneous Notes
+
+\subsection general_misc_dynamic Support for dynamically loadable modules
+
+For a module to be loaded at runtime, it must be:
+
+- found in the `UHD_MODULE_PATH` environment variable,
+- installed into the `\<install-path\>/share/uhd/modules` directory,
+- or installed into `/usr/share/uhd/modules` directory (UNIX only).
+
+\subsection general_misc_prints Disabling or redirecting prints to stdout
+
+The user can disable the UHD library from printing directly to stdout by
+registering a custom message handler. The handler will intercept all
+messages, which can be dropped or redirected. Only one handler can be
+registered at a time. Make **register_handler** your first call into
+the UHD library:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+#include <uhd/utils/msg.hpp>
+
+void my_handler(uhd::msg::type_t type, const std::string &msg){
+//handle the message...
+}
+
+uhd::msg::register_handler(&my_handler);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*/
+// vim:ft=doxygen: