1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
/*! \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 uhd::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 uhd::tune_request_t object, and letting the UHD software handle the
rest.
The uhd::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
- UBX
- UBX-160
\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_sampleratenotes Sample rate notes
Sample rates as delivered to the host computer for USRP devices are constrained to follow several important rules.
It is important to understand that strictly-integer <b>decimation</b> and <b>interpolation</b> are used within USRP
hardware to meet the requested sample-rate requirements of the application at hand. That means that the desired
sample rate must meet the requirement that master-clock-rate/desired-sample-rate be an integer ratio. Further, it is
strongly desirable for that ratio to be <b>even</b>.
There are further constraints on the desired sample rate, such that if the required decimation or interpolation exceeds 128,
then the resulting decimation <b>must</b> be evenly divisible by 2, and that if the required decimation exceeds 256, the
resulting decimation \b must be evenly divisible by 4.
For USRP devices with fixed master clocks (notably: USRP1, USRP2, N2xx), there are fewer effective sample rates available than
on USRP hardware that provides some flexibility in selecting a master clock. Several USRP devices support flexible master
clock selection, allowing a broader range of sample rate selections by applications. See the individual devices' manual
pages for more details.
In many cases using USRPs with flexible master-clock rates, it is possible to achieve lower sample rates without running into
the constraints of higher decimations, simply by choosing a lower master-clock rate to keep required decimation below 128.
\subsection general_sampleratenotes_automatic Automatic master-clock selection
In recent versions of UHD software (3.8.5 and newer), and on some devices (currently: B2xx and E3xx series),
the master clock rate is chosen automatically (unless specified by the user).
UHD will select a master clock rate that is consistent with the desired sample rate indicated by the application.
\subsection general_sampleratenotes_nyquist Master clock rate and Nyquist
In selecting a master clock rate on certain USRP hardware (X3xx and B1xx), it is important to select a rate that still provides
correct alias suppression by the analog hardware. For daughtercards with a 40 MHz analog bandwidth, this means the clock rate
must be <b>at least</b> 40 MHz, with better performance to be expected with a higher clock rate. For daughtercards
with 160 MHz bandwidth, it must be <b>at least</b> 160 MHz, again, better performance is to expected with a higher clock rate.
For hardware with fixed master clock rates, of course, this isn't a consideration.
For B2xx and E3xx hardware, the alias suppression is handled differently by the AD936x RFIC, and master clock rate
is significantly more flexible as a result.
\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: uhd::tx_streamer::send(), uhd::rx_streamer::recv(), and uhd::tx_streamer::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. If setting the new priority fails, the UHD software
prints a warning to the console, as shown below. This warning is harmless;
it simply means that the thread will retain a normal or default scheduling priority.
UHD Warning:
Unable to set the thread priority. Performance may be negatively affected.
Please see the general application notes in the manual for instructions.
EnvironmentError: OSError: error in pthread_setschedparam
<b>Linux Notes:</b>
Non-privileged users need special permission to change the scheduling
priority. Add the following line to the file `/etc/security/limits.conf`:
@GROUP - rtprio 99
Replace `GROUP` with a group in which your user is a member. You may need
to log out and log back into the account for the settings to take effect.
In most Linux distributions, a list of groups and group members can be found in the file `/etc/group`.
\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:
|
