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   /*!
 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)
 109    */
 110   void set_fpga_master_clock_freq (long master_clock);
 111
 112   void set_verbose (bool on);
 113
 114   //! magic value used on alternate register read interfaces
 115   static const int READ_FAILED = -99999;
 116
 117   /*!
 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
 123    */
 124   bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string buf);
 125
 126   /*!
 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.
 132    */
 133   std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
 134
 135   /*!
 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.
 141    */
 142   bool write_i2c (int i2c_addr, const std::string buf);
 143
 144   /*!
 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.
 150    */
 151   std::string read_i2c (int i2c_addr, int len);
 152
 153   /*!
 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.
 157    */
 158   bool set_adc_offset (int which_adc, int offset);
 159
 160   /*!
 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.
 166    */
 167   bool set_dac_offset (int which_dac, int offset, int offset_pin);
 168
 169   /*!
 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.
 174    */
 175   bool set_adc_buffer_bypass (int which_adc, bool bypass);
 176
 177   /*!
 178    * \brief Enable/disable automatic DC offset removal control loop in FPGA
 179    *
 180    * \param bits  which control loops to enable
 181    * \param mask  which \p bits to pay attention to
 182    *
 183    * If the corresponding bit is set, enable the automatic DC
 184    * offset correction control loop.
 185    *
 186    * <pre>
 187    * The 4 low bits are significant:
 188    *
 189    *   ADC0 = (1 << 0)
 190    *   ADC1 = (1 << 1)
 191    *   ADC2 = (1 << 2)
 192    *   ADC3 = (1 << 3)
 193    * </pre>
 194    *
 195    * By default the control loop is enabled on all ADC's.
 196    */
 197   bool set_dc_offset_cl_enable(int bits, int mask);
 198
 199   /*!
 200    * \brief return the usrp's serial number.
 201    *
 202    * \returns non-zero length string iff successful.
 203    */
 204   std::string serial_number();
 205
 206   /*!
 207    * \brief Return daughterboard ID for given side [0,1].
 208    *
 209    * \param which_side  [0,1] which daughterboard
 210    *
 211    * \return daughterboard id >= 0 if successful
 212    * \return -1 if no daugherboard
 213    * \return -2 if invalid EEPROM on daughterboard
 214    */
 215   virtual int daughterboard_id (int which_side) const;
 216
 217   /*!
 218    * \brief Clock ticks to delay rising of T/R signal
 219    * \sa write_atr_mask, write_atr_txval, write_atr_rxval
 220    */
 221   bool write_atr_tx_delay(int value);
 222
 223   /*!
 224    * \brief Clock ticks to delay falling edge of T/R signal
 225    * \sa write_atr_mask, write_atr_txval, write_atr_rxval
 226    */
 227   bool write_atr_rx_delay(int value);
 228
 229   /*!
 230    * \brief Set Programmable Gain Amplifier (PGA)
 231    *
 232    * \param which_amp   which amp [0,3]
 233    * \param gain_in_db  gain value (linear in dB)
 234    *
 235    * gain is rounded to closest setting supported by hardware.
 236    *
 237    * \returns true iff sucessful.
 238    *
 239    * \sa pga_min(), pga_max(), pga_db_per_step()
 240    */
 241   bool set_pga (int which_amp, double gain_in_db);
 242
 243   /*!
 244    * \brief Return programmable gain amplifier gain setting in dB.
 245    *
 246    * \param which_amp   which amp [0,3]
 247    */
 248   double pga (int which_amp) const;
 249
 250   /*!
 251    * \brief Return minimum legal PGA gain in dB.
 252    */
 253   double pga_min () const;
 254
 255   /*!
 256    * \brief Return maximum legal PGA gain in dB.
 257    */
 258   double pga_max () const;
 259
 260   /*!
 261    * \brief Return hardware step size of PGA (linear in dB).
 262    */
 263   double pga_db_per_step () const;
 264
 265   /*!
 266    * \brief Write direction register (output enables) for pins that go to daughterboard.
 267    *
 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
 271    *
 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.
 274    *
 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.
 279    */
 280   bool _write_oe (int which_side, int value, int mask);
 281
 282   /*!
 283    * \brief Write daughterboard i/o pin value
 284    *
 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
 288    */
 289   bool write_io (int which_side, int value, int mask);
 290
 291   /*!
 292    * \brief Read daughterboard i/o pin value
 293    *
 294    * \param which_side  [0,1] which d'board
 295    * \returns register value if successful, else READ_FAILED
 296    */
 297   int read_io (int which_side);
 298
 299   /*!
 300    * \brief Write daughterboard refclk config register
 301    *
 302    * \param which_side  [0,1] which d'board
 303    * \param value       value to write into register, see below
 304    *
 305    * <pre>
 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.
 308    *
 309    *     3                   2                   1
 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    *  +-----------------------------------------------+-+------------+
 314    *
 315    *  Bit 7  -- 1 turns on refclk, 0 allows IO use
 316    *  Bits 6:0 Divider value
 317    * </pre>
 318    */
 319   bool write_refclk(int which_side, int value);
 320
 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);
 324
 325   /*!
 326    * \brief Write auxiliary digital to analog converter.
 327    *
 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
 334    */
 335   bool write_aux_dac (int which_side, int which_dac, int value);
 336
 337   /*!
 338    * \brief Read auxiliary analog to digital converter.
 339    *
 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.
 343    */
 344   int read_aux_adc (int which_side, int which_adc);
 345
 346   /*!
 347    * \brief returns A/D or D/A converter rate in Hz
 348    */
 349   long converter_rate() const;
 350
 351
 352   // ----------------------------------------------------------------
 353   // Low level implementation routines.
 354   // You probably shouldn't be using these...
 355   //
 356
 357   bool _set_led (int which_led, bool on);
 358
 359   /*!
 360    * \brief Write FPGA register.
 361    * \param regno       7-bit register number
 362    * \param value       32-bit value
 363    * \returns true iff successful
 364    */
 365   bool _write_fpga_reg (int regno, int value);  //< 7-bit regno, 32-bit value
 366
 367   /*!
 368    * \brief Read FPGA register.
 369    * \param regno       7-bit register number
 370    * \param value       32-bit value
 371    * \returns true iff successful
 372    */
 373   bool _read_fpga_reg (int regno, int *value);  //< 7-bit regno, 32-bit value
 374
 375   /*!
 376    * \brief Read FPGA register.
 377    * \param regno       7-bit register number
 378    * \returns register value if successful, else READ_FAILED
 379    */
 380   int  _read_fpga_reg (int regno);
 381
 382   /*!
 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
 389    */
 390   bool _write_fpga_reg_masked (int regno, int value, int mask);
 391
 392   /*!
 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
 398    */
 399   bool _write_9862 (int which_codec, int regno, unsigned char value);
 400
 401   /*!
 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
 406    */
 407   int  _read_9862 (int which_codec, int regno) const;
 408
 409   /*!
 410    * \brief Write data to SPI bus peripheral.
 411    *
 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.
 418    *
 419    * If \p format specifies that optional_header bytes are present, they are
 420    * written to the peripheral immediately prior to writing \p buf.
 421    */
 422   bool _write_spi (int optional_header, int enables, int format, std::string buf);
 423
 424   /*
 425    * \brief Read data from SPI bus peripheral.
 426    *
 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.
 432    *
 433    * Reads are limited to a maximum of 64 bytes.
 434    *
 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.
 438    */
 439   std::string _read_spi (int optional_header, int enables, int format, int len);
 440
 441   /*!
 442    * Return an existing daughterboard from list of candidate dbids, or the first found
 443    * on side A or side B.
 444    *
 445    * \param candidates          Vector of candidate dbids
 446    *
 447    * Throws std::runtime_error if not found
 448    */
 449   usrp_subdev_spec pick_subdev(std::vector<int> candidates=std::vector<int>(0));
 450 };
 451
 452 #endif /* INCLUDED_USRP_BASE_H */