git.gag.com Git - debian/gnuradio/blob - gr-usrp/src/usrp_base.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2004,2008 Free Software Foundation, Inc.
   4  *
   5  * This file is part of GNU Radio
   6  *
   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)
  10  * any later version.
  11  *
  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.
  16  *
  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.
  20  */
  21 #ifndef INCLUDED_USRP_BASE_H
  22 #define INCLUDED_USRP_BASE_H
  23
  24 #include <gr_sync_block.h>
  25 #include <stdexcept>
  26 #include <boost/shared_ptr.hpp>
  27 #include <db_base.h>
  28 #include <usrp_subdev_spec.h>
  29
  30 class usrp_basic;
  31
  32 /*!
  33  * \brief base class for GNU Radio interface to the USRP
  34  */
  35 class usrp_base : public gr_sync_block {
  36 private:
  37   boost::shared_ptr<usrp_basic> d_usrp_basic;
  38
  39 protected:
  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) {}
  44
  45
  46   void set_usrp_basic(boost::shared_ptr<usrp_basic> u);
  47
  48 public:
  49   virtual ~usrp_base();
  50
  51   /* !
  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.
  56    *
  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
  61    * will work out fine.
  62    */
  63    std::vector<std::vector<db_base_sptr> > db();
  64
  65   /*!
  66    * Return a vector of size 1 or 2 that contains shared pointers
  67    * to the daughterboard instance(s) associated with the specified side.
  68    *
  69    * \param which_side  [0,1] which daughterboard
  70    *
  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
  75    * will work out fine.
  76    */
  77   std::vector<db_base_sptr> db(int which_side);
  78
  79   /*!
  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
  86    * will work out fine.
  87    */
  88   db_base_sptr db(int which_side, int which_dev);
  89
  90   /*!
  91    * \brief given a usrp_subdev_spec, return the corresponding daughterboard object.
  92    * \throws std::invalid_argument if ss is invalid.
  93    *
  94    * \param ss specifies the side and subdevice
  95    */
  96   db_base_sptr selected_subdev(usrp_subdev_spec ss);
  97
  98   /*!
  99    * \brief return frequency of master oscillator on USRP
 100    */
 101   long  fpga_master_clock_freq() const;
 102
 103   void set_verbose (bool on);
 104
 105   //! magic value used on alternate register read interfaces
 106   static const int READ_FAILED = -99999;
 107
 108   /*!
 109    * \brief Write EEPROM on motherboard or any daughterboard.
 110    * \param i2c_addr            I2C bus address of EEPROM
 111    * \param eeprom_offset       byte offset in EEPROM to begin writing
 112    * \param buf                 the data to write
 113    * \returns true iff sucessful
 114    */
 115   bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string buf);
 116
 117   /*!
 118    * \brief Read 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 reading
 121    * \param len                 number of bytes to read
 122    * \returns the data read if successful, else a zero length string.
 123    */
 124   std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
 125
 126   /*!
 127    * \brief Write to I2C peripheral
 128    * \param i2c_addr            I2C bus address (7-bits)
 129    * \param buf                 the data to write
 130    * \returns true iff successful
 131    * Writes are limited to a maximum of of 64 bytes.
 132    */
 133   bool write_i2c (int i2c_addr, const std::string buf);
 134
 135   /*!
 136    * \brief Read from I2C peripheral
 137    * \param i2c_addr            I2C bus address (7-bits)
 138    * \param len                 number of bytes to read
 139    * \returns the data read if successful, else a zero length string.
 140    * Reads are limited to a maximum of 64 bytes.
 141    */
 142   std::string read_i2c (int i2c_addr, int len);
 143
 144   /*!
 145    * \brief Set ADC offset correction
 146    * \param which       which ADC[0,3]: 0 = RX_A I, 1 = RX_A Q...
 147    * \param offset      16-bit value to subtract from raw ADC input.
 148    */
 149   bool set_adc_offset (int which_adc, int offset);
 150
 151   /*!
 152    * \brief Set DAC offset correction
 153    * \param which       which DAC[0,3]: 0 = TX_A I, 1 = TX_A Q...
 154    * \param offset      10-bit offset value (ambiguous format:  See AD9862 datasheet).
 155    * \param offset_pin  1-bit value.  If 0 offset applied to -ve differential pin;
 156    *                                  If 1 offset applied to +ve differential pin.
 157    */
 158   bool set_dac_offset (int which_dac, int offset, int offset_pin);
 159
 160   /*!
 161    * \brief Control ADC input buffer
 162    * \param which_adc   which ADC[0,3]
 163    * \param bypass      if non-zero, bypass input buffer and connect input
 164    *                    directly to switched cap SHA input of RxPGA.
 165    */
 166   bool set_adc_buffer_bypass (int which_adc, bool bypass);
 167
 168   /*!
 169    * \brief Enable/disable automatic DC offset removal control loop in FPGA
 170    *
 171    * \param bits  which control loops to enable
 172    * \param mask  which \p bits to pay attention to
 173    *
 174    * If the corresponding bit is set, enable the automatic DC
 175    * offset correction control loop.
 176    *
 177    * <pre>
 178    * The 4 low bits are significant:
 179    *
 180    *   ADC0 = (1 << 0)
 181    *   ADC1 = (1 << 1)
 182    *   ADC2 = (1 << 2)
 183    *   ADC3 = (1 << 3)
 184    * </pre>
 185    *
 186    * By default the control loop is enabled on all ADC's.
 187    */
 188   bool set_dc_offset_cl_enable(int bits, int mask);
 189
 190   /*!
 191    * \brief return the usrp's serial number.
 192    *
 193    * \returns non-zero length string iff successful.
 194    */
 195   std::string serial_number();
 196
 197   /*!
 198    * \brief Return daughterboard ID for given side [0,1].
 199    *
 200    * \param which_side  [0,1] which daughterboard
 201    *
 202    * \return daughterboard id >= 0 if successful
 203    * \return -1 if no daugherboard
 204    * \return -2 if invalid EEPROM on daughterboard
 205    */
 206   virtual int daughterboard_id (int which_side) const;
 207
 208   /*!
 209    * \brief Clock ticks to delay rising of T/R signal
 210    * \sa write_atr_mask, write_atr_txval, write_atr_rxval
 211    */
 212   bool write_atr_tx_delay(int value);
 213
 214   /*!
 215    * \brief Clock ticks to delay falling edge of T/R signal
 216    * \sa write_atr_mask, write_atr_txval, write_atr_rxval
 217    */
 218   bool write_atr_rx_delay(int value);
 219
 220   /*!
 221    * \brief Set Programmable Gain Amplifier (PGA)
 222    *
 223    * \param which_amp   which amp [0,3]
 224    * \param gain_in_db  gain value (linear in dB)
 225    *
 226    * gain is rounded to closest setting supported by hardware.
 227    *
 228    * \returns true iff sucessful.
 229    *
 230    * \sa pga_min(), pga_max(), pga_db_per_step()
 231    */
 232   bool set_pga (int which_amp, double gain_in_db);
 233
 234   /*!
 235    * \brief Return programmable gain amplifier gain setting in dB.
 236    *
 237    * \param which_amp   which amp [0,3]
 238    */
 239   double pga (int which_amp) const;
 240
 241   /*!
 242    * \brief Return minimum legal PGA gain in dB.
 243    */
 244   double pga_min () const;
 245
 246   /*!
 247    * \brief Return maximum legal PGA gain in dB.
 248    */
 249   double pga_max () const;
 250
 251   /*!
 252    * \brief Return hardware step size of PGA (linear in dB).
 253    */
 254   double pga_db_per_step () const;
 255
 256   /*!
 257    * \brief Write direction register (output enables) for pins that go to daughterboard.
 258    *
 259    * \param which_side  [0,1] which size
 260    * \param value       value to write into register
 261    * \param mask        which bits of value to write into reg
 262    *
 263    * Each d'board has 16-bits of general purpose i/o.
 264    * Setting the bit makes it an output from the FPGA to the d'board.
 265    *
 266    * This register is initialized based on a value stored in the
 267    * d'board EEPROM.  In general, you shouldn't be using this routine
 268    * without a very good reason.  Using this method incorrectly will
 269    * kill your USRP motherboard and/or daughterboard.
 270    */
 271   bool _write_oe (int which_side, int value, int mask);
 272
 273   /*!
 274    * \brief Write daughterboard i/o pin value
 275    *
 276    * \param which_side  [0,1] which d'board
 277    * \param value       value to write into register
 278    * \param mask        which bits of value to write into reg
 279    */
 280   bool write_io (int which_side, int value, int mask);
 281
 282   /*!
 283    * \brief Read daughterboard i/o pin value
 284    *
 285    * \param which_side  [0,1] which d'board
 286    * \returns register value if successful, else READ_FAILED
 287    */
 288   int read_io (int which_side);
 289
 290   /*!
 291    * \brief Write daughterboard refclk config register
 292    *
 293    * \param which_side  [0,1] which d'board
 294    * \param value       value to write into register, see below
 295    *
 296    * <pre>
 297    * Control whether a reference clock is sent to the daughterboards,
 298    * and what frequency.  The refclk is sent on d'board i/o pin 0.
 299    *
 300    *     3                   2                   1
 301    *   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
 302    *  +-----------------------------------------------+-+------------+
 303    *  |             Reserved (Must be zero)           |E|   DIVISOR  |
 304    *  +-----------------------------------------------+-+------------+
 305    *
 306    *  Bit 7  -- 1 turns on refclk, 0 allows IO use
 307    *  Bits 6:0 Divider value
 308    * </pre>
 309    */
 310   bool write_refclk(int which_side, int value);
 311
 312   bool write_atr_mask(int which_side, int value);
 313   bool write_atr_txval(int which_side, int value);
 314   bool write_atr_rxval(int which_side, int value);
 315
 316   /*!
 317    * \brief Write auxiliary digital to analog converter.
 318    *
 319    * \param which_side  [0,1] which d'board
 320    *                    N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's.
 321    *                    SLOT_TX_B and SLOT_RX_B share the same AUX DAC's.
 322    * \param which_dac   [2,3] TX slots must use only 2 and 3.
 323    * \param value       [0,4095]
 324    * \returns true iff successful
 325    */
 326   bool write_aux_dac (int which_side, int which_dac, int value);
 327
 328   /*!
 329    * \brief Read auxiliary analog to digital converter.
 330    *
 331    * \param which_side  [0,1] which d'board
 332    * \param which_adc   [0,1]
 333    * \returns value in the range [0,4095] if successful, else READ_FAILED.
 334    */
 335   int read_aux_adc (int which_side, int which_adc);
 336
 337   /*!
 338    * \brief returns A/D or D/A converter rate in Hz
 339    */
 340   long converter_rate() const;
 341
 342
 343   // ----------------------------------------------------------------
 344   // Low level implementation routines.
 345   // You probably shouldn't be using these...
 346   //
 347
 348   bool _set_led (int which_led, bool on);
 349
 350   /*!
 351    * \brief Write FPGA register.
 352    * \param regno       7-bit register number
 353    * \param value       32-bit value
 354    * \returns true iff successful
 355    */
 356   bool _write_fpga_reg (int regno, int value);  //< 7-bit regno, 32-bit value
 357
 358   /*!
 359    * \brief Read FPGA register.
 360    * \param regno       7-bit register number
 361    * \param value       32-bit value
 362    * \returns true iff successful
 363    */
 364   bool _read_fpga_reg (int regno, int *value);  //< 7-bit regno, 32-bit value
 365
 366   /*!
 367    * \brief Read FPGA register.
 368    * \param regno       7-bit register number
 369    * \returns register value if successful, else READ_FAILED
 370    */
 371   int  _read_fpga_reg (int regno);
 372
 373   /*!
 374    * \brief Write FPGA register with mask.
 375    * \param regno       7-bit register number
 376    * \param value       16-bit value
 377    * \param mask        16-bit value
 378    * \returns true if successful
 379    * Only use this for registers who actually implement a mask in the verilog firmware, like FR_RX_MASTER_SLAVE
 380    */
 381   bool _write_fpga_reg_masked (int regno, int value, int mask);
 382
 383   /*!
 384    * \brief Write AD9862 register.
 385    * \param which_codec 0 or 1
 386    * \param regno       6-bit register number
 387    * \param value       8-bit value
 388    * \returns true iff successful
 389    */
 390   bool _write_9862 (int which_codec, int regno, unsigned char value);
 391
 392   /*!
 393    * \brief Read AD9862 register.
 394    * \param which_codec 0 or 1
 395    * \param regno       6-bit register number
 396    * \returns register value if successful, else READ_FAILED
 397    */
 398   int  _read_9862 (int which_codec, int regno) const;
 399
 400   /*!
 401    * \brief Write data to SPI bus peripheral.
 402    *
 403    * \param optional_header     0,1 or 2 bytes to write before buf.
 404    * \param enables             bitmask of peripherals to write. See usrp_spi_defs.h
 405    * \param format              transaction format.  See usrp_spi_defs.h SPI_FMT_*
 406    * \param buf                 the data to write
 407    * \returns true iff successful
 408    * Writes are limited to a maximum of 64 bytes.
 409    *
 410    * If \p format specifies that optional_header bytes are present, they are
 411    * written to the peripheral immediately prior to writing \p buf.
 412    */
 413   bool _write_spi (int optional_header, int enables, int format, std::string buf);
 414
 415   /*
 416    * \brief Read data from SPI bus peripheral.
 417    *
 418    * \param optional_header     0,1 or 2 bytes to write before buf.
 419    * \param enables             bitmask of peripheral to read. See usrp_spi_defs.h
 420    * \param format              transaction format.  See usrp_spi_defs.h SPI_FMT_*
 421    * \param len                 number of bytes to read.  Must be in [0,64].
 422    * \returns the data read if sucessful, else a zero length string.
 423    *
 424    * Reads are limited to a maximum of 64 bytes.
 425    *
 426    * If \p format specifies that optional_header bytes are present, they
 427    * are written to the peripheral first.  Then \p len bytes are read from
 428    * the peripheral and returned.
 429    */
 430   std::string _read_spi (int optional_header, int enables, int format, int len);
 431
 432   /*!
 433    * Return an existing daughterboard from list of candidate dbids, or the first found
 434    * on side A or side B.
 435    *
 436    * \param candidates          Vector of candidate dbids
 437    *
 438    * Throws std::runtime_error if not found
 439    */
 440   usrp_subdev_spec pick_subdev(std::vector<int> candidates=std::vector<int>(0));
 441 };
 442
 443 #endif /* INCLUDED_USRP_BASE_H */