3 * Copyright 2004,2008 Free Software Foundation, Inc.
5 * This file is part of GNU Radio
7 * GNU Radio is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 3, or (at your option)
12 * GNU Radio is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License along
18 * with this program; if not, write to the Free Software Foundation, Inc.,
19 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
21 #ifndef INCLUDED_USRP_BASE_H
22 #define INCLUDED_USRP_BASE_H
24 #include <gr_sync_block.h>
26 #include <boost/shared_ptr.hpp>
28 #include <usrp_subdev_spec.h>
33 * \brief base class for GNU Radio interface to the USRP
35 class usrp_base : public gr_sync_block {
37 boost::shared_ptr<usrp_basic> d_usrp_basic;
40 usrp_base(const std::string &name,
41 gr_io_signature_sptr input_signature,
42 gr_io_signature_sptr output_signature)
43 : gr_sync_block(name, input_signature, output_signature) {}
46 void set_usrp_basic(boost::shared_ptr<usrp_basic> u);
52 * Return a vector of vectors of daughterboard instances associated with
53 * the USRP source or sink. The first dimension of the returned vector
54 * corresponds to the side of the USRP, the second dimension, the subdevice
55 * on the particular daughterboard.
57 * N.B. To ensure proper lifetime management, the caller should
58 * continue to hold these as weak pointers, not shared pointers.
59 * As long as the caller does not attempt to directly use the weak
60 * pointers after this usrp object has been destroyed, everything
63 std::vector<std::vector<db_base_sptr> > db();
66 * Return a vector of size 1 or 2 that contains shared pointers
67 * to the daughterboard instance(s) associated with the specified side.
69 * \param which_side [0,1] which daughterboard
71 * N.B. To ensure proper lifetime management, the caller should
72 * continue to hold these as weak pointers, not shared pointers.
73 * As long as the caller does not attempt to directly use the weak
74 * pointers after this usrp object has been destroyed, everything
77 std::vector<db_base_sptr> db(int which_side);
80 * Return the daughterboard instance corresponding to the selected
81 * side of the USRP and selected daughterboard subdevice.
82 * N.B. To ensure proper lifetime management, the caller should
83 * continue to hold these as weak pointers, not shared pointers.
84 * As long as the caller does not attempt to directly use the weak
85 * pointers after this usrp object has been destroyed, everything
88 db_base_sptr db(int which_side, int which_dev);
91 * \brief given a usrp_subdev_spec, return the corresponding daughterboard object.
92 * \throws std::invalid_argument if ss is invalid.
94 * \param ss specifies the side and subdevice
96 db_base_sptr selected_subdev(usrp_subdev_spec ss);
99 * \brief return frequency of master oscillator on USRP
101 long fpga_master_clock_freq() const;
104 * Tell API that the master oscillator on the USRP is operating at a non-standard
105 * fixed frequency. This is only needed for custom USRP hardware modified to
106 * operate at a different frequency from the default factory configuration. This
107 * function must be called prior to any other API function.
108 * \param master_clock USRP2 FPGA master clock frequency in Hz (10..64 MHz)
110 void set_fpga_master_clock_freq (long master_clock);
112 void set_verbose (bool on);
114 //! magic value used on alternate register read interfaces
115 static const int READ_FAILED = -99999;
118 * \brief Write EEPROM on motherboard or any daughterboard.
119 * \param i2c_addr I2C bus address of EEPROM
120 * \param eeprom_offset byte offset in EEPROM to begin writing
121 * \param buf the data to write
122 * \returns true iff sucessful
124 bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string buf);
127 * \brief Read EEPROM on motherboard or any daughterboard.
128 * \param i2c_addr I2C bus address of EEPROM
129 * \param eeprom_offset byte offset in EEPROM to begin reading
130 * \param len number of bytes to read
131 * \returns the data read if successful, else a zero length string.
133 std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
136 * \brief Write to I2C peripheral
137 * \param i2c_addr I2C bus address (7-bits)
138 * \param buf the data to write
139 * \returns true iff successful
140 * Writes are limited to a maximum of of 64 bytes.
142 bool write_i2c (int i2c_addr, const std::string buf);
145 * \brief Read from I2C peripheral
146 * \param i2c_addr I2C bus address (7-bits)
147 * \param len number of bytes to read
148 * \returns the data read if successful, else a zero length string.
149 * Reads are limited to a maximum of 64 bytes.
151 std::string read_i2c (int i2c_addr, int len);
154 * \brief Set ADC offset correction
155 * \param which_adc which ADC[0,3]: 0 = RX_A I, 1 = RX_A Q...
156 * \param offset 16-bit value to subtract from raw ADC input.
158 bool set_adc_offset (int which_adc, int offset);
161 * \brief Set DAC offset correction
162 * \param which_dac which DAC[0,3]: 0 = TX_A I, 1 = TX_A Q...
163 * \param offset 10-bit offset value (ambiguous format: See AD9862 datasheet).
164 * \param offset_pin 1-bit value. If 0 offset applied to -ve differential pin;
165 * If 1 offset applied to +ve differential pin.
167 bool set_dac_offset (int which_dac, int offset, int offset_pin);
170 * \brief Control ADC input buffer
171 * \param which_adc which ADC[0,3]
172 * \param bypass if non-zero, bypass input buffer and connect input
173 * directly to switched cap SHA input of RxPGA.
175 bool set_adc_buffer_bypass (int which_adc, bool bypass);
178 * \brief Enable/disable automatic DC offset removal control loop in FPGA
180 * \param bits which control loops to enable
181 * \param mask which \p bits to pay attention to
183 * If the corresponding bit is set, enable the automatic DC
184 * offset correction control loop.
187 * The 4 low bits are significant:
195 * By default the control loop is enabled on all ADC's.
197 bool set_dc_offset_cl_enable(int bits, int mask);
200 * \brief return the usrp's serial number.
202 * \returns non-zero length string iff successful.
204 std::string serial_number();
207 * \brief Return daughterboard ID for given side [0,1].
209 * \param which_side [0,1] which daughterboard
211 * \return daughterboard id >= 0 if successful
212 * \return -1 if no daugherboard
213 * \return -2 if invalid EEPROM on daughterboard
215 virtual int daughterboard_id (int which_side) const;
218 * \brief Clock ticks to delay rising of T/R signal
219 * \sa write_atr_mask, write_atr_txval, write_atr_rxval
221 bool write_atr_tx_delay(int value);
224 * \brief Clock ticks to delay falling edge of T/R signal
225 * \sa write_atr_mask, write_atr_txval, write_atr_rxval
227 bool write_atr_rx_delay(int value);
230 * \brief Set Programmable Gain Amplifier (PGA)
232 * \param which_amp which amp [0,3]
233 * \param gain_in_db gain value (linear in dB)
235 * gain is rounded to closest setting supported by hardware.
237 * \returns true iff sucessful.
239 * \sa pga_min(), pga_max(), pga_db_per_step()
241 bool set_pga (int which_amp, double gain_in_db);
244 * \brief Return programmable gain amplifier gain setting in dB.
246 * \param which_amp which amp [0,3]
248 double pga (int which_amp) const;
251 * \brief Return minimum legal PGA gain in dB.
253 double pga_min () const;
256 * \brief Return maximum legal PGA gain in dB.
258 double pga_max () const;
261 * \brief Return hardware step size of PGA (linear in dB).
263 double pga_db_per_step () const;
266 * \brief Write direction register (output enables) for pins that go to daughterboard.
268 * \param which_side [0,1] which size
269 * \param value value to write into register
270 * \param mask which bits of value to write into reg
272 * Each d'board has 16-bits of general purpose i/o.
273 * Setting the bit makes it an output from the FPGA to the d'board.
275 * This register is initialized based on a value stored in the
276 * d'board EEPROM. In general, you shouldn't be using this routine
277 * without a very good reason. Using this method incorrectly will
278 * kill your USRP motherboard and/or daughterboard.
280 bool _write_oe (int which_side, int value, int mask);
283 * \brief Write daughterboard i/o pin value
285 * \param which_side [0,1] which d'board
286 * \param value value to write into register
287 * \param mask which bits of value to write into reg
289 bool write_io (int which_side, int value, int mask);
292 * \brief Read daughterboard i/o pin value
294 * \param which_side [0,1] which d'board
295 * \returns register value if successful, else READ_FAILED
297 int read_io (int which_side);
300 * \brief Write daughterboard refclk config register
302 * \param which_side [0,1] which d'board
303 * \param value value to write into register, see below
306 * Control whether a reference clock is sent to the daughterboards,
307 * and what frequency. The refclk is sent on d'board i/o pin 0.
310 * 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
311 * +-----------------------------------------------+-+------------+
312 * | Reserved (Must be zero) |E| DIVISOR |
313 * +-----------------------------------------------+-+------------+
315 * Bit 7 -- 1 turns on refclk, 0 allows IO use
316 * Bits 6:0 Divider value
319 bool write_refclk(int which_side, int value);
321 bool write_atr_mask(int which_side, int value);
322 bool write_atr_txval(int which_side, int value);
323 bool write_atr_rxval(int which_side, int value);
326 * \brief Write auxiliary digital to analog converter.
328 * \param which_side [0,1] which d'board
329 * N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's.
330 * SLOT_TX_B and SLOT_RX_B share the same AUX DAC's.
331 * \param which_dac [2,3] TX slots must use only 2 and 3.
332 * \param value [0,4095]
333 * \returns true iff successful
335 bool write_aux_dac (int which_side, int which_dac, int value);
338 * \brief Read auxiliary analog to digital converter.
340 * \param which_side [0,1] which d'board
341 * \param which_adc [0,1]
342 * \returns value in the range [0,4095] if successful, else READ_FAILED.
344 int read_aux_adc (int which_side, int which_adc);
347 * \brief returns A/D or D/A converter rate in Hz
349 long converter_rate() const;
352 // ----------------------------------------------------------------
353 // Low level implementation routines.
354 // You probably shouldn't be using these...
357 bool _set_led (int which_led, bool on);
360 * \brief Write FPGA register.
361 * \param regno 7-bit register number
362 * \param value 32-bit value
363 * \returns true iff successful
365 bool _write_fpga_reg (int regno, int value); //< 7-bit regno, 32-bit value
368 * \brief Read FPGA register.
369 * \param regno 7-bit register number
370 * \param value 32-bit value
371 * \returns true iff successful
373 bool _read_fpga_reg (int regno, int *value); //< 7-bit regno, 32-bit value
376 * \brief Read FPGA register.
377 * \param regno 7-bit register number
378 * \returns register value if successful, else READ_FAILED
380 int _read_fpga_reg (int regno);
383 * \brief Write FPGA register with mask.
384 * \param regno 7-bit register number
385 * \param value 16-bit value
386 * \param mask 16-bit value
387 * \returns true if successful
388 * Only use this for registers who actually implement a mask in the verilog firmware, like FR_RX_MASTER_SLAVE
390 bool _write_fpga_reg_masked (int regno, int value, int mask);
393 * \brief Write AD9862 register.
394 * \param which_codec 0 or 1
395 * \param regno 6-bit register number
396 * \param value 8-bit value
397 * \returns true iff successful
399 bool _write_9862 (int which_codec, int regno, unsigned char value);
402 * \brief Read AD9862 register.
403 * \param which_codec 0 or 1
404 * \param regno 6-bit register number
405 * \returns register value if successful, else READ_FAILED
407 int _read_9862 (int which_codec, int regno) const;
410 * \brief Write data to SPI bus peripheral.
412 * \param optional_header 0,1 or 2 bytes to write before buf.
413 * \param enables bitmask of peripherals to write. See usrp_spi_defs.h
414 * \param format transaction format. See usrp_spi_defs.h SPI_FMT_*
415 * \param buf the data to write
416 * \returns true iff successful
417 * Writes are limited to a maximum of 64 bytes.
419 * If \p format specifies that optional_header bytes are present, they are
420 * written to the peripheral immediately prior to writing \p buf.
422 bool _write_spi (int optional_header, int enables, int format, std::string buf);
425 * \brief Read data from SPI bus peripheral.
427 * \param optional_header 0,1 or 2 bytes to write before buf.
428 * \param enables bitmask of peripheral to read. See usrp_spi_defs.h
429 * \param format transaction format. See usrp_spi_defs.h SPI_FMT_*
430 * \param len number of bytes to read. Must be in [0,64].
431 * \returns the data read if sucessful, else a zero length string.
433 * Reads are limited to a maximum of 64 bytes.
435 * If \p format specifies that optional_header bytes are present, they
436 * are written to the peripheral first. Then \p len bytes are read from
437 * the peripheral and returned.
439 std::string _read_spi (int optional_header, int enables, int format, int len);
442 * Return an existing daughterboard from list of candidate dbids, or the first found
443 * on side A or side B.
445 * \param candidates Vector of candidate dbids
447 * Throws std::runtime_error if not found
449 usrp_subdev_spec pick_subdev(std::vector<int> candidates=std::vector<int>(0));
452 #endif /* INCLUDED_USRP_BASE_H */