Statistics
| Branch: | Tag: | Revision:

root / host / docs / general.rst @ e8d9b4d9

History | View | Annotate | Download (8.21 KB)

1
========================================================================
2
UHD - General Application Notes
3
========================================================================
4

    
5
.. contents:: Table of Contents
6

    
7
------------------------------------------------------------------------
8
Tuning Notes
9
------------------------------------------------------------------------
10

    
11
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12
Two-stage tuning process
13
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14
A USRP device has two stages of tuning:
15

    
16
* RF front-end: translates bewteen RF and IF
17
* DSP: translates between IF and baseband
18

    
19
In a typical use-case, the user specifies an overall center frequency for the
20
signal chain.  The RF front-end will be tuned as close as possible to the center
21
frequency, and the DSP will account for the error in tuning between target
22
frequency and actual frequency.  The user may also explicitly control both
23
stages of tuning through through the **tune_request_t** object, which allows for
24
more advanced tuning.
25

    
26
In general, Using UHD's advanced tuning is highly recommended as it makes it
27
easy to move the DC component out of your band-of-interest.  This can be done by
28
passing your desired LO offset to the **tune_request_t** object, and letting UHD
29
handle the rest.
30

    
31
Tuning the receive chain:
32
::
33

    
34
    //tuning to a desired center frequency
35
    usrp->set_rx_freq(target_frequency_in_hz);
36

    
37
    --OR--
38

    
39
    //advanced tuning with tune_request_t
40
    uhd::tune_request_t tune_req(target_frequency_in_hz, desired_lo_offset);
41
    //fill in any additional/optional tune request fields...
42
    usrp->set_rx_freq(tune_req);
43

    
44
More information can be fonud in *tune_request.hpp*.
45

    
46
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
47
RF front-end settling time
48
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
49
After tuning, the RF front-end will need time to settle into a usable state.
50
Typically, this means that the local oscillators must be given time to lock
51
before streaming begins.  Lock time is not consistent; it varies depending upon
52
the device and requested settings.  After tuning and before streaming, the user
53
should wait for the **lo_locked** sensor to become true or sleep for
54
a conservative amount of time (perhaps a second).
55

    
56
Pseudo-code for dealing with settling time after tuning on receive:
57
::
58

    
59
    usrp->set_rx_freq(...);
60
    sleep(1);
61
    usrp->issue_stream_command(...);
62

    
63
    --OR--
64

    
65
    usrp->set_rx_freq(...);
66
    while (not usrp->get_rx_sensor("lo_locked").to_bool()){
67
        //sleep for a short time in milliseconds
68
    }
69
    usrp->issue_stream_command(...);
70

    
71
------------------------------------------------------------------------
72
Specifying the Subdevice to Use
73
------------------------------------------------------------------------
74
A subdevice specification string for USRP family devices is composed of:
75

    
76
::
77

    
78
    <motherboard slot name>:<daughterboard frontend name>
79

    
80
Ex: The subdev spec markup string to select a WBX on slot B.
81

    
82
::
83

    
84
    B:0
85

    
86
Ex: The subdev spec markup string to select a BasicRX on slot B.
87

    
88
::
89

    
90
    B:AB
91

    
92
    -- OR --
93

    
94
    B:A
95

    
96
    -- OR --
97

    
98
    B:B
99

    
100
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
101
USRP Family Motherboard Slot Names
102
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
103

    
104
All USRP family motherboards have a first slot named **A:**.  The USRP1 has
105
two daughterboard subdevice slots, known as **A:** and **B:**.  
106

    
107
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
108
Daughterboard Frontend Names
109
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
110

    
111
Daughterboard frontend names can be used to specify which signal path is used
112
from a daughterboard.  Most daughterboards have only one frontend **:0**.  A few
113
daughterboards (Basic, LF and TVRX2) have multiple frontend names available.
114
The frontend names are documented in the 
115
`Daughterboard Application Notes <./dboards.html>`_
116

    
117
------------------------------------------------------------------------
118
Overflow/Underflow Notes
119
------------------------------------------------------------------------
120
**Note:** The following overflow/underflow notes do not apply to USRP1,
121
which does not support the advanced features available in newer products.
122

    
123
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
124
Overflow notes
125
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
126
When receiving, the device produces samples at a constant rate.
127
Overflows occurs when the host does not consume data fast enough.
128
When UHD detects the overflow, it prints an "O" to stdout,
129
and pushes an inline message packet into the receive stream.
130

    
131
**Network-based devices**:
132
The host does not back-pressure the receive stream.
133
When the kernel's socket buffer becomes full, it will drop subsequent packets.
134
UHD detects the overflow as a discontinuity in the packet's sequence numbers,
135
and pushes an inline message packet into the receive stream.
136

    
137
**Other devices**:
138
The host back-pressures the receive stream.
139
Therefore, overflows always occur in the device itself.
140
When the device's internal buffers become full, streaming is shut off,
141
and an inline message packet is sent to the host.
142
If the device was in continuous streaming mode,
143
UHD will automatically restart streaming.
144

    
145
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
146
Underflow notes
147
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
148
When transmitting, the device consumes samples at a constant rate.
149
Underflow occurs when the host does not produce data fast enough.
150
When UHD detects underflow, it prints a "U" to stdout,
151
and pushes a message packet into the async message stream.
152

    
153
------------------------------------------------------------------------
154
Threading Notes
155
------------------------------------------------------------------------
156

    
157
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
158
Thread safety notes
159
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
160
For the most part, UHD is thread-safe.
161
Please observe the following limitations:
162

    
163
**Fast-path thread requirements:**
164
There are three fast-path methods for a device: **send()**, **recv()**, and **recv_async_msg()**.
165
All three methods are thread-safe and can be called from different thread contexts.
166
For performance, the user should call each method from a separate thread context.
167
These methods can also be used in a non-blocking fashion by using a timeout of zero.
168

    
169
**Slow-path thread requirements:**
170
It is safe to change multiple settings simultaneously. However,
171
this could leave the settings for a device in an uncertain state.
172
This is because changing one setting could have an impact on how a call affects other settings.
173
Example: setting the channel mapping affects how the antennas are set.
174
It is recommended to use at most one thread context for manipulating device settings.
175

    
176
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
177
Thread priority scheduling
178
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
179

    
180
When UHD spawns a new thread it may try to boost the thread's scheduling priority.
181
When setting the priority fails, UHD prints out an error.
182
This error is harmless; it simply means that the thread will have a normal scheduling priority.
183

    
184
**Linux Notes:**
185

    
186
Non-privileged users need special permission to change the scheduling priority.
187
Add the following line to **/etc/security/limits.conf**:
188
::
189

    
190
    @<my_group>    -    rtprio    99
191

    
192
Replace **<my_group>** with a group to which your user belongs.
193
Settings will not take effect until the user is in a different login session.
194

    
195
------------------------------------------------------------------------
196
Miscellaneous Notes
197
------------------------------------------------------------------------
198

    
199
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
200
Support for dynamically loadable modules
201
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
202
For a module to be loaded at runtime, it must be:
203

    
204
* found in the **UHD_MODULE_PATH** environment variable,
205
* installed into the **<install-path>/share/uhd/modules** directory,
206
* or installed into **/usr/share/uhd/modules** directory (UNIX only).
207

    
208
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
209
Disabling or redirecting prints to stdout
210
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
211
The user can disable the UHD library from printing directly to stdout by registering a custom message handler.
212
The handler will intercept all messages, which can be dropped or redirected.
213
Only one handler can be registered at a time.
214
Make **register_handler** your first call into UHD:
215

    
216
::
217

    
218
    #include <uhd/utils/msg.hpp>
219

    
220
    void my_handler(uhd::msg::type_t type, const std::string &msg){
221
        //handle the message...
222
    }
223

    
224
    uhd::msg::register_handler(&my_handler);