diff options
Diffstat (limited to 'host/docs/general.rst')
| -rw-r--r-- | host/docs/general.rst | 242 |
1 files changed, 0 insertions, 242 deletions
diff --git a/host/docs/general.rst b/host/docs/general.rst deleted file mode 100644 index 930c18188..000000000 --- a/host/docs/general.rst +++ /dev/null @@ -1,242 +0,0 @@ -=============================== -UHD - General Application Notes -=============================== - -.. contents:: Table of Contents - ------------- -Tuning Notes ------------- - -^^^^^^^^^^^^^^^^^^^^^^^^ -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 - -Tuning the receive chain: -::::::::::::::::::::::::: - - //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 `tune_request.hpp <./../../doxygen/html/structuhd_1_1tune__request__t.html>`_. - -^^^^^^^^^^^^^^^^^^^^^^^^^^ -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). - -Pseudo-code for dealing with settling time after tuning on receive: -::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: - -:: - - 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(...); - - -------------------------------- -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 - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -USRP Family Motherboard Slot Names -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -All USRP family motherboards have a first slot named **A:**. The USRP1 has -two daughterboard subdevice slots, known as **A:** and **B:**. - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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 the -`Daughterboard Application Notes <./dboards.html>`_ - ------------------------- -Overflow/Underflow Notes ------------------------- -**Note:** The following overflow/underflow notes do not apply to USRP1, -which does not support the advanced features available in newer products. - -^^^^^^^^^^^^^^ -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. - -**Network-based devices**: -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. - -**Other devices**: -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. - -^^^^^^^^^^^^^^^ -Underflow 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. - ---------------- -Threading Notes ---------------- - -^^^^^^^^^^^^^^^^^^^ -Thread safety notes -^^^^^^^^^^^^^^^^^^^ -For the most part, UHD software is thread-safe. -Please observe the following limitations: - -**Fast-path thread requirements:** -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. - -**Slow-path thread requirements:** -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. - -^^^^^^^^^^^^^^^^^^^^^^^^^^ -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. - -**Linux Notes:** - -Non-privileged users need special permission to change the scheduling priority. -Add the following line to **/etc/security/limits.conf**: -:::::::::::::::::::::::::::::::::::::::::::::::::::::::: - - @<my_group> - rtprio 99 - -Replace **<my_group>** with a group to which your user belongs. -Settings will not take effect until the user is in a different login session. - -------------------- -Miscellaneous Notes -------------------- - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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). - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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: - -:: - - #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); |