3 * Copyright 2008,2009 Free Software Foundation, Inc.
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 #ifndef INCLUDED_USRP2_H
20 #define INCLUDED_USRP2_H
22 #include <boost/shared_ptr.hpp>
23 #include <boost/utility.hpp>
24 #include <boost/bind.hpp>
27 #include <usrp2/rx_sample_handler.h>
28 #include <usrp2/tune_result.h>
29 #include <usrp2/mimo_config.h>
32 * N.B., The interfaces described here are still in flux.
34 * We will keep all the code in the tree up-to-date with regard to changes
35 * here, but reserve the right to change this on a whim.
41 * Structure to hold properties of USRP2 hardware devices.
48 uint8_t fpga_md5sum[16];
49 uint8_t sw_md5sum[16];
52 typedef std::vector<props> props_vector_t;
55 * \brief Search the ethernet for all USRP2s or for a specific USRP2.
57 * \param ifc is the name of the OS ethernet interface (e.g., "eth0")
58 * \param mac_addr is the MAC address of the desired USRP2, or "" to search for all.
59 * mac_addr must be either a zero length string, "", or must be of the form
60 * "01:02:03:04:05:06" or "05:06".
62 * \returns a vector of properties, 1 entry for each matching USRP2 found.
64 props_vector_t find(const std::string &ifc, const std::string &mac_addr="");
68 // FIXME: get from firmware include
69 static const int GPIO_TX_BANK = 0;
70 static const int GPIO_RX_BANK = 1;
73 * \brief standard C++ interface to USRP2
76 class usrp2 : boost::noncopyable
79 static const unsigned int MAX_CHAN = 30;
82 * Shared pointer to this class
84 typedef boost::shared_ptr<usrp2> sptr;
87 * Static function to return an instance of usrp2 as a shared pointer
89 * \param ifc Network interface name, e.g., "eth0"
90 * \param addr Network mac address, e.g., "01:23:45:67:89:ab", "89:ab" or "".
91 * If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
92 * "" will autoselect a USRP2 if there is only a single one on the local ethernet.
93 * \param rx_bufsize is the length in bytes of the kernel networking buffer to allocate.
95 static sptr make(const std::string &ifc, const std::string &addr="", size_t rx_bufsize=0);
103 * Returns the MAC address associated with this USRP
105 std::string mac_addr();
108 * Returns the GbE interface name associated with this USRP
110 std::string interface_name();
113 * ----------------------------------------------------------------
114 * Rx configuration and control
115 * ----------------------------------------------------------------
121 bool set_rx_antenna(int ant);
125 * \param gain in dB (more or less)
127 bool set_rx_gain(double gain);
129 //! return minimum Rx gain
130 double rx_gain_min();
132 //! return maximum Rx gain
133 double rx_gain_max();
135 //! return Rx gain db_per_step
136 double rx_gain_db_per_step();
139 * \brief Set receive daughterboard LO offset frequency
141 bool set_rx_lo_offset(double frequency);
144 * Set receiver center frequency
146 bool set_rx_center_freq(double frequency, tune_result *result);
148 //! return minimum Rx center frequency
149 double rx_freq_min();
151 //! return maximum Rx center frequency
152 double rx_freq_max();
155 * Set receiver sample rate decimation
157 bool set_rx_decim(int decimation_factor);
159 //! Return current decimation factor
163 * Set receiver IQ magnitude scaling
165 bool set_rx_scale_iq(int scale_i, int scale_q);
168 * Set received sample format
170 * domain: complex or real
171 * type: floating, fixed point, or raw
172 * depth: bits per sample
174 * Sets format over the wire for samples from USRP2.
176 // bool set_rx_format(...);
179 * Start streaming receive mode. USRP2 will send a continuous stream of
180 * DSP pipeline samples to host. Call rx_samples(...) to access.
182 * \param channel Stream channel number (0-30)
183 * \param items_per_frame Number of 32-bit items per frame.
185 bool start_rx_streaming(unsigned int channel=0, unsigned int items_per_frame=0);
188 * Start streaming receive mode at specified timestamp. USRP2 will send a
189 * continuous stream of DSP pipeline samples to host. Call rx_samples(...)
192 * \param channel Stream channel number (0-30)
193 * \param items_per_frame Number of 32-bit items per frame.
194 * \param time Timestamp to start streaming at
196 bool start_rx_streaming_at(unsigned int channel=0, unsigned int items_per_frame=0, unsigned int time=0);
199 * Sync to PPS and start streaming receive mode at specified timestamp.
200 * Just like calling sync_to_pps() and start_rx_streaming_at().
202 * \param channel Stream channel number (0-30)
203 * \param items_per_frame Number of 32-bit items per frame.
204 * \param time Timestamp to start streaming at
206 bool sync_and_start_rx_streaming_at(unsigned int channel=0, unsigned int items_per_frame=0, uint32_t time=0);
209 * Stop streaming receive mode.
211 bool stop_rx_streaming(unsigned int channel=0);
214 * \brief Receive data from the specified channel
215 * This method is used to receive all data: streaming or discrete.
217 bool rx_samples(unsigned int channel, rx_sample_handler *handler);
220 * Returns number of times receive overruns have occurred
222 unsigned int rx_overruns();
225 * Returns total number of missing frames from overruns.
227 unsigned int rx_missing();
230 * ----------------------------------------------------------------
231 * Tx configuration and control
232 * ----------------------------------------------------------------
238 bool set_tx_antenna(int ant);
241 * Set transmitter gain
243 bool set_tx_gain(double gain);
245 //! return minimum Tx gain
246 double tx_gain_min();
248 //! return maximum Tx gain
249 double tx_gain_max();
251 //! return Tx gain db_per_step
252 double tx_gain_db_per_step();
255 * \brief Set transmit daughterboard LO offset frequency
257 bool set_tx_lo_offset(double frequency);
260 * Set transmitter center frequency
262 bool set_tx_center_freq(double frequency, tune_result *result);
264 //! return minimum Tx center frequency
265 double tx_freq_min();
267 //! return maximum Tx center frequency
268 double tx_freq_max();
271 * Set transmitter sample rate interpolation
273 bool set_tx_interp(int interpolation_factor);
275 //! Return current interpolation factor
279 * \brief Calculate default scale_iq for given interpolation rate
281 void default_tx_scale_iq(int interpolation_factor, int *scale_i, int *scale_q);
284 * Set transmit IQ magnitude scaling
286 bool set_tx_scale_iq(int scale_i, int scale_q);
289 * Set transmit sample format
291 * domain: complex or real
292 * type: floating, fixed point, or raw
293 * depth: bits per sample
295 * Sets format over the wire for samples to USRP2.
297 // bool set_tx_format(...);
300 * \brief transmit complex<float> samples to USRP2
302 * \param channel specifies the channel to send them to
303 * \param samples are the samples to transmit. They should be in the range [-1.0, +1.0]
304 * \param nsamples is the number of samples to transmit
305 * \param metadata provides the timestamp and flags
307 * The complex<float> samples are converted to the appropriate
308 * "on the wire" representation, depending on the current USRP2
309 * configuration. Typically, this is big-endian 16-bit I & Q.
311 bool tx_32fc(unsigned int channel,
312 const std::complex<float> *samples,
314 const tx_metadata *metadata);
317 * \brief transmit complex<int16_t> samples to USRP2
319 * \param channel specifies the channel to send them to
320 * \param samples are the samples to transmit
321 * \param nsamples is the number of samples to transmit
322 * \param metadata provides the timestamp and flags
324 * The complex<int16_t> samples are converted to the appropriate
325 * "on the wire" representation, depending on the current USRP2
326 * configuration. Typically, this is big-endian 16-bit I & Q.
328 bool tx_16sc(unsigned int channel,
329 const std::complex<int16_t> *samples,
331 const tx_metadata *metadata);
334 * \brief transmit raw uint32_t data items to USRP2
336 * The caller is responsible for ensuring that the items are
337 * formatted appropriately for the USRP2 and its configuration.
338 * This method is used primarily by the system itself. Users
339 * should call tx_32fc or tx_16sc instead.
341 * \param channel specifies the channel to send them to
342 * \param items are the data items to transmit
343 * \param nitems is the number of items to transmit
344 * \param metadata provides the timestamp and flags
346 bool tx_raw(unsigned int channel,
347 const uint32_t *items,
349 const tx_metadata *metadata);
352 * ----------------------------------------------------------------
353 * miscellaneous methods
354 * ----------------------------------------------------------------
358 * \brief MIMO configuration
360 * \param flags from usrp2_mimo_config.h
369 * and optionally this:
371 * MC_PROVIDE_CLK_TO_MIMO
374 bool config_mimo(int flags);
377 //! Get frequency of master oscillator in Hz
378 bool fpga_master_clock_freq(long *freq);
380 // Get Sampling rate of A/D converter in Hz
381 bool adc_rate(long *rate);
383 // Get Sampling rate of D/A converter in Hz
384 bool dac_rate(long *rate);
387 * \brief Get Tx daughterboard ID
389 * \param[out] dbid returns the daughterboard id.
391 * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
392 * -2 if invalid EEPROM on daughterboard.
394 bool tx_daughterboard_id(int *dbid);
397 * \brief Get Rx daughterboard ID
399 * \param[out] dbid returns the daughterboard id.
401 * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
402 * -2 if invalid EEPROM on daughterboard.
404 bool rx_daughterboard_id(int *dbid);
407 * ----------------------------------------------------------------
409 * ----------------------------------------------------------------
413 * Burn new mac address into EEPROM on USRP2
415 * \param new_addr Network mac address, e.g., "01:23:45:67:89:ab" or "89:ab".
416 * If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
418 bool burn_mac_addr(const std::string &new_addr);
421 * Reset master time to 0 at next PPS edge
426 * Reset master time to 0 at every PPS edge
428 bool sync_every_pps(bool enable);
431 * Read memory from Wishbone bus as 32-bit words. Handles endian swapping if needed.
433 * \param addr 32-bit aligned address. Only the lower 16-bits are significant.
434 * \param words Number of 32-bit words
436 * \returns Vector of 32-bit read values
438 * WARNING: Attempts to read memory from addresses that do not correspond to RAM or
439 * memory-mapped peripherals may cause the USRP2 to hang, requiring a power cycle.
442 std::vector<uint32_t> peek32(uint32_t addr, uint32_t words);
445 * Write memory to Wishbone bus as 32-bit words. Handles endian swapping if needed.
447 * \param addr 32-bit aligned address. Only the lower 16-bits are significant
448 * \param data Vector of 32-bit values to write.
450 * \returns true iff successful
452 * WARNING: Attempts to read memory from addresses that do not correspond to RAM or
453 * memory-mapped peripherals may cause the USRP2 to hang, requiring a power cycle.
456 bool poke32(uint32_t addr, const std::vector<uint32_t> &data);
459 * Set daughterboard GPIO data direction register.
461 * \param bank GPIO_TX_BANK or GPIO_RX_BANK
462 * \param value 16-bits, 0=FPGA input, 1=FPGA output
463 * \param mask 16-bits, 0=ignore, 1=set
465 * \returns true iff successful
467 * WARNING: Improper usage of this function may result in damage to the USRP2
470 bool set_gpio_ddr(int bank, uint16_t value, uint16_t mask);
473 * Set daughterboard GPIO output selection register. For those GPIO pins that
474 * are configured as outputs in the DDR, this settings configures the source
477 * \param bank GPIO_TX_BANK or GPIO_RX_BANK
478 * \param sels Exactly 16 character MSB->LSB string. For each position:
479 * '.' = ignore this bit, i.e., leave current value
480 * 'a' = Output ATR value
481 * 's' = Output host software controlled value
482 * '0' = Output FPGA debug bus 0 value
483 * '1' = Output FPGA debug bus 1 value
485 * \returns true iff successful
487 * WARNING: Improper usage of this function may result in damage to the USRP2
490 bool set_gpio_sels(int bank, std::string sels);
493 * Set daughterboard GPIO pin values.
495 * \param bank GPIO_TX_BANK or GPIO_RX_BANK
496 * \param value 16 bits, 0=low, 1=high
497 * \param mask 16 bits, 0=ignore, 1=set
499 * \returns true iff successful
501 * WARNING: Improper usage of this function may result in damage to the USRP2
504 bool write_gpio(int bank, uint16_t value, uint16_t mask);
507 * Read daughterboard GPIO pin values
509 * \param bank GPIO_TX_BANK or GPIO_RX_BANK
510 * \param value pointer to uint16_t to hold read results
512 * \returns true iff successful
515 bool read_gpio(int bank, uint16_t *value);
518 * Set GPIO streaming mode
520 * Individually enables streaming GPIO pins through LSBs of DSP
523 * On receive, io_rx[15] replaces I[0], io_rx[14] replaces Q[0]
524 * On transmit, I[0] maps to io_tx[15], Q[0] maps to io_tx[14]
525 * (Transmit streaming is not yet implemented.)
527 * The selected GPIO pins must have been set as inputs or outputs
528 * and, for transmit, set to software control.
530 * When enabled, the replaced DSP sample LSBs become 0.
532 * \param bank GPIO_TX_BANK or GPIO_RX_BANK
533 * \param enable enable[0] controls I channel LSB
534 * enable[1] controls Q channel LSB
536 * \returns true iff successful
538 * WARNING: Improper usage of this function may result in damage to the USRP2
541 bool enable_gpio_streaming(int bank, int enable);
543 #if 0 // not yet implemented
545 * \brief Write EEPROM on motherboard or any daughterboard.
546 * \param i2c_addr I2C bus address of EEPROM
547 * \param eeprom_offset byte offset in EEPROM to begin writing
548 * \param buf the data to write
549 * \returns true iff sucessful
551 bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string &buf);
554 * \brief Read EEPROM on motherboard or any daughterboard.
555 * \param i2c_addr I2C bus address of EEPROM
556 * \param eeprom_offset byte offset in EEPROM to begin reading
557 * \param len number of bytes to read
558 * \returns the data read if successful, else a zero length string.
560 std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
563 * \brief Write to I2C peripheral
564 * \param i2c_addr I2C bus address (7-bits)
565 * \param buf the data to write
566 * \returns true iff successful
567 * Writes are limited to a maximum of of 64 bytes.
569 bool write_i2c (int i2c_addr, const std::string &buf);
572 * \brief Read from I2C peripheral
573 * \param i2c_addr I2C bus address (7-bits)
574 * \param len number of bytes to read
575 * \returns the data read if successful, else a zero length string.
576 * Reads are limited to a maximum of 64 bytes.
578 std::string read_i2c (int i2c_addr, int len);
581 * \brief Write data to SPI bus peripheral.
583 * \param optional_header 0,1 or 2 bytes to write before buf.
584 * \param enables bitmask of peripherals to write. See usrp_spi_defs.h
585 * \param format transaction format. See usrp_spi_defs.h SPI_FMT_*
586 * \param buf the data to write
587 * \returns true iff successful
588 * Writes are limited to a maximum of 64 bytes.
590 * If \p format specifies that optional_header bytes are present, they are
591 * written to the peripheral immediately prior to writing \p buf.
593 bool write_spi (int optional_header, int enables, int format, const std::string &buf);
596 * \brief Read data from SPI bus peripheral.
598 * \param optional_header 0,1 or 2 bytes to write before buf.
599 * \param enables bitmask of peripheral to read. See usrp_spi_defs.h
600 * \param format transaction format. See usrp_spi_defs.h SPI_FMT_*
601 * \param len number of bytes to read. Must be in [0,64].
602 * \returns the data read if sucessful, else a zero length string.
604 * Reads are limited to a maximum of 64 bytes.
606 * If \p format specifies that optional_header bytes are present, they
607 * are written to the peripheral first. Then \p len bytes are read from
608 * the peripheral and returned.
610 std::string read_spi (int optional_header, int enables, int format, int len);
614 class impl; // implementation details
617 // Static function to retrieve or create usrp2 instance
618 static sptr find_existing_or_make_new(const std::string &ifc, props *p, size_t rx_bufsize);
620 // Only class members can instantiate this class
621 usrp2(const std::string &ifc, props *p, size_t rx_bufsize);
623 // All private state is held in opaque pointer
624 std::auto_ptr<impl> d_impl;
629 std::ostream& operator<<(std::ostream &os, const usrp2::props &x);
632 #endif /* INCLUDED_USRP2_H */