git.gag.com Git - debian/gnuradio/blob - usrp/host/include/usrp/usrp_basic.h

   1 /*  -*- c++ -*- */
   2 /*
   3  * Copyright 2005,2009 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
  18  * along with GNU Radio; see the file COPYING.  If not, write to
  19  * the Free Software Foundation, Inc., 51 Franklin Street,
  20  * Boston, MA 02110-1301, USA.
  21  */
  22
  23 #ifndef INCLUDED_USRP_BASIC_H
  24 #define INCLUDED_USRP_BASIC_H
  25
  26 #include <usrp/db_base.h>
  27 #include <usrp/usrp_slots.h>
  28 #include <usrp/usrp_subdev_spec.h>
  29 #include <usrp/libusb_types.h>
  30 #include <string>
  31 #include <vector>
  32 #include <boost/utility.hpp>
  33
  34 class  fusb_devhandle;
  35 class  fusb_ephandle;
  36
  37 enum txrx_t {
  38   C_RX = 0,
  39   C_TX = 1
  40 };
  41
  42 /*
  43  * ----------------------------------------------------------------------
  44  * Mid level interface to the Universal Software Radio Peripheral (Rev 1)
  45  *
  46  * These classes implement the basic functionality for talking to the
  47  * USRP.  They try to be as independent of the signal processing code
  48  * in FPGA as possible.  They implement access to the low level
  49  * peripherals on the board, provide a common way for reading and
  50  * writing registers in the FPGA, and provide the high speed interface
  51  * to streaming data across the USB.
  52  *
  53  * It is expected that subclasses will be derived that provide
  54  * access to the functionality to a particular FPGA configuration.
  55  * ----------------------------------------------------------------------
  56  */
  57
  58
  59 /*!
  60  * \brief abstract base class for usrp operations
  61  * \ingroup usrp
  62  */
  63 class usrp_basic : boost::noncopyable
  64 {
  65 protected:
  66   void shutdown_daughterboards();
  67
  68 protected:
  69   libusb_device_handle          *d_udh;
  70   struct libusb_context         *d_ctx;
  71   int                            d_usb_data_rate;       // bytes/sec
  72   int                            d_bytes_per_poll;      // how often to poll for overruns
  73   bool                           d_verbose;
  74   long                           d_fpga_master_clock_freq;
  75
  76   static const int               MAX_REGS = 128;
  77   unsigned int                   d_fpga_shadows[MAX_REGS];
  78
  79   int                            d_dbid[2];             // daughterboard ID's (side A, side B)
  80
  81   /*!
  82    * Shared pointers to subclasses of db_base.
  83    *
  84    * The outer vector is of length 2 (0 = side A, 1 = side B).  The
  85    * inner vectors are of length 1, 2 or 3 depending on the number of
  86    * subdevices implemented by the daugherboard.  At this time, only
  87    * the Basic Rx and LF Rx implement more than 1 subdevice.
  88    */
  89   std::vector< std::vector<db_base_sptr> > d_db;
  90
  91   //! One time call, made only only from usrp_standard_*::make after shared_ptr is created.
  92   void init_db(usrp_basic_sptr u);
  93
  94
  95   usrp_basic (int which_board,
  96               libusb_device_handle *open_interface (libusb_device *dev),
  97               const std::string fpga_filename = "",
  98               const std::string firmware_filename = "");
  99
 100   /*!
 101    * \brief advise usrp_basic of usb data rate (bytes/sec)
 102    *
 103    * N.B., this doesn't tweak any hardware.  Derived classes
 104    * should call this to inform us of the data rate whenever it's
 105    * first set or if it changes.
 106    *
 107    * \param usb_data_rate       bytes/sec
 108    */
 109   void set_usb_data_rate (int usb_data_rate);
 110
 111   /*!
 112    * \brief Write auxiliary digital to analog converter.
 113    *
 114    * \param slot        Which Tx or Rx slot to write.
 115    *                    N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's.
 116    *                    SLOT_TX_B and SLOT_RX_B share the same AUX DAC's.
 117    * \param which_dac   [0,3] RX slots must use only 0 and 1.  TX slots must use only 2 and 3.
 118    * \param value       [0,4095]
 119    * \returns true iff successful
 120    */
 121   bool _write_aux_dac (int slot, int which_dac, int value);
 122
 123   /*!
 124    * \brief Read auxiliary analog to digital converter.
 125    *
 126    * \param slot        2-bit slot number. E.g., SLOT_TX_A
 127    * \param which_adc   [0,1]
 128    * \param value       return 12-bit value [0,4095]
 129    * \returns true iff successful
 130    */
 131   bool _read_aux_adc (int slot, int which_adc, int *value);
 132
 133   /*!
 134    * \brief Read auxiliary analog to digital converter.
 135    *
 136    * \param slot        2-bit slot number. E.g., SLOT_TX_A
 137    * \param which_adc   [0,1]
 138    * \returns value in the range [0,4095] if successful, else READ_FAILED.
 139    */
 140   int _read_aux_adc (int slot, int which_adc);
 141
 142
 143 public:
 144   virtual ~usrp_basic ();
 145
 146
 147   /*!
 148    * Return a vector of vectors that contain shared pointers
 149    * to the daughterboard instance(s) associated with the specified side.
 150    *
 151    * It is an error to use the returned objects after the usrp_basic
 152    * object has been destroyed.
 153    */
 154   std::vector<std::vector<db_base_sptr> > db() const { return d_db; }
 155
 156   /*!
 157    * Return a vector of size >= 1 that contains shared pointers
 158    * to the daughterboard instance(s) associated with the specified side.
 159    *
 160    * \param which_side  [0,1] which daughterboard
 161    *
 162    * It is an error to use the returned objects after the usrp_basic
 163    * object has been destroyed.
 164    */
 165   std::vector<db_base_sptr> db(int which_side);
 166
 167   /*!
 168    * \brief is the subdev_spec valid?
 169    */
 170   bool is_valid(const usrp_subdev_spec &ss);
 171
 172   /*!
 173    * \brief given a subdev_spec, return the corresponding daughterboard object.
 174    * \throws std::invalid_ argument if ss is invalid.
 175    *
 176    * \param ss specifies the side and subdevice
 177    */
 178   db_base_sptr selected_subdev(const usrp_subdev_spec &ss);
 179
 180   /*!
 181    * \brief return frequency of master oscillator on USRP
 182    */
 183   long fpga_master_clock_freq () const { return d_fpga_master_clock_freq; }
 184
 185   /*!
 186    * Tell API that the master oscillator on the USRP is operating at a non-standard
 187    * fixed frequency. This is only needed for custom USRP hardware modified to
 188    * operate at a different frequency from the default factory configuration. This
 189    * function must be called prior to any other API function.
 190    * \param master_clock USRP2 FPGA master clock frequency in Hz (10..64 MHz)
 191    */
 192   void set_fpga_master_clock_freq (long master_clock) { d_fpga_master_clock_freq = master_clock; }
 193
 194   /*!
 195    * \returns usb data rate in bytes/sec
 196    */
 197   int usb_data_rate () const { return d_usb_data_rate; }
 198
 199   void set_verbose (bool on) { d_verbose = on; }
 200
 201   //! magic value used on alternate register read interfaces
 202   static const int READ_FAILED = -99999;
 203
 204   /*!
 205    * \brief Write EEPROM on motherboard or any daughterboard.
 206    * \param i2c_addr            I2C bus address of EEPROM
 207    * \param eeprom_offset       byte offset in EEPROM to begin writing
 208    * \param buf                 the data to write
 209    * \returns true iff sucessful
 210    */
 211   bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string buf);
 212
 213   /*!
 214    * \brief Read EEPROM on motherboard or any daughterboard.
 215    * \param i2c_addr            I2C bus address of EEPROM
 216    * \param eeprom_offset       byte offset in EEPROM to begin reading
 217    * \param len                 number of bytes to read
 218    * \returns the data read if successful, else a zero length string.
 219    */
 220   std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
 221
 222   /*!
 223    * \brief Write to I2C peripheral
 224    * \param i2c_addr            I2C bus address (7-bits)
 225    * \param buf                 the data to write
 226    * \returns true iff successful
 227    * Writes are limited to a maximum of of 64 bytes.
 228    */
 229   bool write_i2c (int i2c_addr, const std::string buf);
 230
 231   /*!
 232    * \brief Read from I2C peripheral
 233    * \param i2c_addr            I2C bus address (7-bits)
 234    * \param len                 number of bytes to read
 235    * \returns the data read if successful, else a zero length string.
 236    * Reads are limited to a maximum of 64 bytes.
 237    */
 238   std::string read_i2c (int i2c_addr, int len);
 239
 240   /*!
 241    * \brief Set ADC offset correction
 242    * \param which_adc   which ADC[0,3]: 0 = RX_A I, 1 = RX_A Q...
 243    * \param offset      16-bit value to subtract from raw ADC input.
 244    */
 245   bool set_adc_offset (int which_adc, int offset);
 246
 247   /*!
 248    * \brief Set DAC offset correction
 249    * \param which_dac   which DAC[0,3]: 0 = TX_A I, 1 = TX_A Q...
 250    * \param offset      10-bit offset value (ambiguous format:  See AD9862 datasheet).
 251    * \param offset_pin  1-bit value.  If 0 offset applied to -ve differential pin;
 252    *                                  If 1 offset applied to +ve differential pin.
 253    */
 254   bool set_dac_offset (int which_dac, int offset, int offset_pin);
 255
 256   /*!
 257    * \brief Control ADC input buffer
 258    * \param which_adc   which ADC[0,3]
 259    * \param bypass      if non-zero, bypass input buffer and connect input
 260    *                    directly to switched cap SHA input of RxPGA.
 261    */
 262   bool set_adc_buffer_bypass (int which_adc, bool bypass);
 263
 264   /*!
 265    * \brief Enable/disable automatic DC offset removal control loop in FPGA
 266    *
 267    * \param bits  which control loops to enable
 268    * \param mask  which \p bits to pay attention to
 269    *
 270    * If the corresponding bit is set, enable the automatic DC
 271    * offset correction control loop.
 272    *
 273    * <pre>
 274    * The 4 low bits are significant:
 275    *
 276    *   ADC0 = (1 << 0)
 277    *   ADC1 = (1 << 1)
 278    *   ADC2 = (1 << 2)
 279    *   ADC3 = (1 << 3)
 280    * </pre>
 281    *
 282    * By default the control loop is enabled on all ADC's.
 283    */
 284   bool set_dc_offset_cl_enable(int bits, int mask);
 285
 286   /*!
 287    * \brief return the usrp's serial number.
 288    *
 289    * \returns non-zero length string iff successful.
 290    */
 291   std::string serial_number();
 292
 293   /*!
 294    * \brief Return daughterboard ID for given side [0,1].
 295    *
 296    * \param which_side  [0,1] which daughterboard
 297    *
 298    * \return daughterboard id >= 0 if successful
 299    * \return -1 if no daugherboard
 300    * \return -2 if invalid EEPROM on daughterboard
 301    */
 302   virtual int daughterboard_id (int which_side) const = 0;
 303
 304   /*!
 305    * \brief Clock ticks to delay rising of T/R signal
 306    * \sa write_atr_mask, write_atr_txval, write_atr_rxval
 307    */
 308   bool write_atr_tx_delay(int value);
 309
 310   /*!
 311    * \brief Clock ticks to delay falling edge of T/R signal
 312    * \sa write_atr_mask, write_atr_txval, write_atr_rxval
 313    */
 314   bool write_atr_rx_delay(int value);
 315
 316
 317 \f  // ================================================================
 318   // Routines to access and control daughterboard specific i/o
 319   //
 320   // Those with a common_ prefix access either the Tx or Rx side depending
 321   // on the txrx parameter.  Those without the common_ prefix are virtual
 322   // and are overriden in usrp_basic_rx and usrp_basic_tx to access the
 323   // the Rx or Tx sides automatically.  We provide the common_ versions
 324   // for those daughterboards such as the WBX and XCVR2450 that share
 325   // h/w resources (such as the LO) between the Tx and Rx sides.
 326
 327   // ----------------------------------------------------------------
 328   // BEGIN common_  daughterboard control functions
 329
 330   /*!
 331    * \brief Set Programmable Gain Amplifier(PGA)
 332    *
 333    * \param txrx        Tx or Rx?
 334    * \param which_amp   which amp [0,3]
 335    * \param gain_in_db  gain value(linear in dB)
 336    *
 337    * gain is rounded to closest setting supported by hardware.
 338    *
 339    * \returns true iff sucessful.
 340    *
 341    * \sa pga_min(), pga_max(), pga_db_per_step()
 342    */
 343   bool common_set_pga(txrx_t txrx, int which_amp, double gain_in_db);
 344
 345   /*!
 346    * \brief Return programmable gain amplifier gain setting in dB.
 347    *
 348    * \param txrx        Tx or Rx?
 349    * \param which_amp   which amp [0,3]
 350    */
 351   double common_pga(txrx_t txrx, int which_amp) const;
 352
 353   /*!
 354    * \brief Return minimum legal PGA gain in dB.
 355    * \param txrx        Tx or Rx?
 356    */
 357   double common_pga_min(txrx_t txrx) const;
 358
 359   /*!
 360    * \brief Return maximum legal PGA gain in dB.
 361    * \param txrx        Tx or Rx?
 362    */
 363   double common_pga_max(txrx_t txrx) const;
 364
 365   /*!
 366    * \brief Return hardware step size of PGA(linear in dB).
 367    * \param txrx        Tx or Rx?
 368    */
 369   double common_pga_db_per_step(txrx_t txrx) const;
 370
 371   /*!
 372    * \brief Write direction register(output enables) for pins that go to daughterboard.
 373    *
 374    * \param txrx        Tx or Rx?
 375    * \param which_side  [0,1] which size
 376    * \param value       value to write into register
 377    * \param mask        which bits of value to write into reg
 378    *
 379    * Each d'board has 16-bits of general purpose i/o.
 380    * Setting the bit makes it an output from the FPGA to the d'board.
 381    *
 382    * This register is initialized based on a value stored in the
 383    * d'board EEPROM.  In general, you shouldn't be using this routine
 384    * without a very good reason.  Using this method incorrectly will
 385    * kill your USRP motherboard and/or daughterboard.
 386    */
 387   bool _common_write_oe(txrx_t txrx, int which_side, int value, int mask);
 388
 389   /*!
 390    * \brief Write daughterboard i/o pin value
 391    *
 392    * \param txrx        Tx or Rx?
 393    * \param which_side  [0,1] which d'board
 394    * \param value       value to write into register
 395    * \param mask        which bits of value to write into reg
 396    */
 397   bool common_write_io(txrx_t txrx, int which_side, int value, int mask);
 398
 399   /*!
 400    * \brief Read daughterboard i/o pin value
 401    *
 402    * \param txrx        Tx or Rx?
 403    * \param which_side  [0,1] which d'board
 404    * \param value       output
 405    */
 406   bool common_read_io(txrx_t txrx, int which_side, int *value);
 407
 408   /*!
 409    * \brief Read daughterboard i/o pin value
 410    *
 411    * \param txrx        Tx or Rx?
 412    * \param which_side  [0,1] which d'board
 413    * \returns register value if successful, else READ_FAILED
 414    */
 415   int common_read_io(txrx_t txrx, int which_side);
 416
 417   /*!
 418    * \brief Write daughterboard refclk config register
 419    *
 420    * \param txrx        Tx or Rx?
 421    * \param which_side  [0,1] which d'board
 422    * \param value       value to write into register, see below
 423    *
 424    * <pre>
 425    * Control whether a reference clock is sent to the daughterboards,
 426    * and what frequency.  The refclk is sent on d'board i/o pin 0.
 427    *
 428    *     3                   2                   1
 429    *   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
 430    *  +-----------------------------------------------+-+------------+
 431    *  |             Reserved (Must be zero)           |E|   DIVISOR  |
 432    *  +-----------------------------------------------+-+------------+
 433    *
 434    *  Bit 7  -- 1 turns on refclk, 0 allows IO use
 435    *  Bits 6:0 Divider value
 436    * </pre>
 437    */
 438   bool common_write_refclk(txrx_t txrx, int which_side, int value);
 439
 440   /*!
 441    * \brief Automatic Transmit/Receive switching
 442    * <pre>
 443    *
 444    * If automatic transmit/receive (ATR) switching is enabled in the
 445    * FR_ATR_CTL register, the presence or absence of data in the FPGA
 446    * transmit fifo selects between two sets of values for each of the 4
 447    * banks of daughterboard i/o pins.
 448    *
 449    * Each daughterboard slot has 3 16-bit registers associated with it:
 450    *   FR_ATR_MASK_*, FR_ATR_TXVAL_* and FR_ATR_RXVAL_*
 451    *
 452    * FR_ATR_MASK_{0,1,2,3}:
 453    *
 454    *   These registers determine which of the daugherboard i/o pins are
 455    *   affected by ATR switching.  If a bit in the mask is set, the
 456    *   corresponding i/o bit is controlled by ATR, else it's output
 457    *   value comes from the normal i/o pin output register:
 458    *   FR_IO_{0,1,2,3}.
 459    *
 460    * FR_ATR_TXVAL_{0,1,2,3}:
 461    * FR_ATR_RXVAL_{0,1,2,3}:
 462    *
 463    *   If the Tx fifo contains data, then the bits from TXVAL that are
 464    *   selected by MASK are output.  Otherwise, the bits from RXVAL that
 465    *   are selected by MASK are output.
 466    * </pre>
 467    */
 468   bool common_write_atr_mask(txrx_t txrx, int which_side, int value);
 469   bool common_write_atr_txval(txrx_t txrx, int which_side, int value);
 470   bool common_write_atr_rxval(txrx_t txrx, int which_side, int value);
 471
 472   /*!
 473    * \brief Write auxiliary digital to analog converter.
 474    *
 475    * \param txrx        Tx or Rx?
 476    * \param which_side  [0,1] which d'board
 477    *                    N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's.
 478    *                    SLOT_TX_B and SLOT_RX_B share the same AUX DAC's.
 479    * \param which_dac   [2,3] TX slots must use only 2 and 3.
 480    * \param value       [0,4095]
 481    * \returns true iff successful
 482    */
 483   bool common_write_aux_dac(txrx_t txrx, int which_side, int which_dac, int value);
 484
 485   /*!
 486    * \brief Read auxiliary analog to digital converter.
 487    *
 488    * \param txrx        Tx or Rx?
 489    * \param which_side  [0,1] which d'board
 490    * \param which_adc   [0,1]
 491    * \param value       return 12-bit value [0,4095]
 492    * \returns true iff successful
 493    */
 494   bool common_read_aux_adc(txrx_t txrx, int which_side, int which_adc, int *value);
 495
 496   /*!
 497    * \brief Read auxiliary analog to digital converter.
 498    *
 499    * \param txrx        Tx or Rx?
 500    * \param which_side  [0,1] which d'board
 501    * \param which_adc   [0,1]
 502    * \returns value in the range [0,4095] if successful, else READ_FAILED.
 503    */
 504   int common_read_aux_adc(txrx_t txrx, int which_side, int which_adc);
 505
 506   // END common_ daughterboard control functions\f
 507   // ----------------------------------------------------------------
 508   // BEGIN virtual daughterboard control functions
 509
 510   /*!
 511    * \brief Set Programmable Gain Amplifier (PGA)
 512    *
 513    * \param which_amp   which amp [0,3]
 514    * \param gain_in_db  gain value (linear in dB)
 515    *
 516    * gain is rounded to closest setting supported by hardware.
 517    *
 518    * \returns true iff sucessful.
 519    *
 520    * \sa pga_min(), pga_max(), pga_db_per_step()
 521    */
 522   virtual bool set_pga (int which_amp, double gain_in_db) = 0;
 523
 524   /*!
 525    * \brief Return programmable gain amplifier gain setting in dB.
 526    *
 527    * \param which_amp   which amp [0,3]
 528    */
 529   virtual double pga (int which_amp) const = 0;
 530
 531   /*!
 532    * \brief Return minimum legal PGA gain in dB.
 533    */
 534   virtual double pga_min () const = 0;
 535
 536   /*!
 537    * \brief Return maximum legal PGA gain in dB.
 538    */
 539   virtual double pga_max () const = 0;
 540
 541   /*!
 542    * \brief Return hardware step size of PGA (linear in dB).
 543    */
 544   virtual double pga_db_per_step () const = 0;
 545
 546   /*!
 547    * \brief Write direction register (output enables) for pins that go to daughterboard.
 548    *
 549    * \param which_side  [0,1] which size
 550    * \param value       value to write into register
 551    * \param mask        which bits of value to write into reg
 552    *
 553    * Each d'board has 16-bits of general purpose i/o.
 554    * Setting the bit makes it an output from the FPGA to the d'board.
 555    *
 556    * This register is initialized based on a value stored in the
 557    * d'board EEPROM.  In general, you shouldn't be using this routine
 558    * without a very good reason.  Using this method incorrectly will
 559    * kill your USRP motherboard and/or daughterboard.
 560    */
 561   virtual bool _write_oe (int which_side, int value, int mask) = 0;
 562
 563   /*!
 564    * \brief Write daughterboard i/o pin value
 565    *
 566    * \param which_side  [0,1] which d'board
 567    * \param value       value to write into register
 568    * \param mask        which bits of value to write into reg
 569    */
 570   virtual bool write_io (int which_side, int value, int mask) = 0;
 571
 572   /*!
 573    * \brief Read daughterboard i/o pin value
 574    *
 575    * \param which_side  [0,1] which d'board
 576    * \param value       output
 577    */
 578   virtual bool read_io (int which_side, int *value) = 0;
 579
 580   /*!
 581    * \brief Read daughterboard i/o pin value
 582    *
 583    * \param which_side  [0,1] which d'board
 584    * \returns register value if successful, else READ_FAILED
 585    */
 586   virtual int read_io (int which_side) = 0;
 587
 588   /*!
 589    * \brief Write daughterboard refclk config register
 590    *
 591    * \param which_side  [0,1] which d'board
 592    * \param value       value to write into register, see below
 593    *
 594    * <pre>
 595    * Control whether a reference clock is sent to the daughterboards,
 596    * and what frequency.  The refclk is sent on d'board i/o pin 0.
 597    *
 598    *     3                   2                   1
 599    *   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
 600    *  +-----------------------------------------------+-+------------+
 601    *  |             Reserved (Must be zero)           |E|   DIVISOR  |
 602    *  +-----------------------------------------------+-+------------+
 603    *
 604    *  Bit 7  -- 1 turns on refclk, 0 allows IO use
 605    *  Bits 6:0 Divider value
 606    * </pre>
 607    */
 608   virtual bool write_refclk(int which_side, int value) = 0;
 609
 610   virtual bool write_atr_mask(int which_side, int value) = 0;
 611   virtual bool write_atr_txval(int which_side, int value) = 0;
 612   virtual bool write_atr_rxval(int which_side, int value) = 0;
 613
 614   /*!
 615    * \brief Write auxiliary digital to analog converter.
 616    *
 617    * \param which_side  [0,1] which d'board
 618    *                    N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's.
 619    *                    SLOT_TX_B and SLOT_RX_B share the same AUX DAC's.
 620    * \param which_dac   [2,3] TX slots must use only 2 and 3.
 621    * \param value       [0,4095]
 622    * \returns true iff successful
 623    */
 624   virtual bool write_aux_dac (int which_side, int which_dac, int value) = 0;
 625
 626   /*!
 627    * \brief Read auxiliary analog to digital converter.
 628    *
 629    * \param which_side  [0,1] which d'board
 630    * \param which_adc   [0,1]
 631    * \param value       return 12-bit value [0,4095]
 632    * \returns true iff successful
 633    */
 634   virtual bool read_aux_adc (int which_side, int which_adc, int *value) = 0;
 635
 636   /*!
 637    * \brief Read auxiliary analog to digital converter.
 638    *
 639    * \param which_side  [0,1] which d'board
 640    * \param which_adc   [0,1]
 641    * \returns value in the range [0,4095] if successful, else READ_FAILED.
 642    */
 643   virtual int read_aux_adc (int which_side, int which_adc) = 0;
 644
 645   /*!
 646    * \brief returns current fusb block size
 647    */
 648   virtual int block_size() const = 0;
 649
 650   /*!
 651    * \brief returns A/D or D/A converter rate in Hz
 652    */
 653   virtual long converter_rate() const = 0;
 654
 655   // END virtual daughterboard control functions\f
 656
 657   // ----------------------------------------------------------------
 658   // Low level implementation routines.
 659   // You probably shouldn't be using these...
 660   //
 661
 662   bool _set_led (int which_led, bool on);
 663
 664   /*!
 665    * \brief Write FPGA register.
 666    * \param regno       7-bit register number
 667    * \param value       32-bit value
 668    * \returns true iff successful
 669    */
 670   bool _write_fpga_reg (int regno, int value);  //< 7-bit regno, 32-bit value
 671
 672   /*!
 673    * \brief Read FPGA register.
 674    * \param regno       7-bit register number
 675    * \param value       32-bit value
 676    * \returns true iff successful
 677    */
 678   bool _read_fpga_reg (int regno, int *value);  //< 7-bit regno, 32-bit value
 679
 680   /*!
 681    * \brief Read FPGA register.
 682    * \param regno       7-bit register number
 683    * \returns register value if successful, else READ_FAILED
 684    */
 685   int  _read_fpga_reg (int regno);
 686
 687   /*!
 688    * \brief Write FPGA register with mask.
 689    * \param regno       7-bit register number
 690    * \param value       16-bit value
 691    * \param mask        16-bit value
 692    * \returns true if successful
 693    * Only use this for registers who actually implement a mask in the verilog firmware, like FR_RX_MASTER_SLAVE
 694    */
 695   bool _write_fpga_reg_masked (int regno, int value, int mask);
 696
 697   /*!
 698    * \brief Write AD9862 register.
 699    * \param which_codec 0 or 1
 700    * \param regno       6-bit register number
 701    * \param value       8-bit value
 702    * \returns true iff successful
 703    */
 704   bool _write_9862 (int which_codec, int regno, unsigned char value);
 705
 706   /*!
 707    * \brief Read AD9862 register.
 708    * \param which_codec 0 or 1
 709    * \param regno       6-bit register number
 710    * \param value       8-bit value
 711    * \returns true iff successful
 712    */
 713   bool _read_9862 (int which_codec, int regno, unsigned char *value) const;
 714
 715   /*!
 716    * \brief Read AD9862 register.
 717    * \param which_codec 0 or 1
 718    * \param regno       6-bit register number
 719    * \returns register value if successful, else READ_FAILED
 720    */
 721   int  _read_9862 (int which_codec, int regno) const;
 722
 723   /*!
 724    * \brief Write data to SPI bus peripheral.
 725    *
 726    * \param optional_header     0,1 or 2 bytes to write before buf.
 727    * \param enables             bitmask of peripherals to write. See usrp_spi_defs.h
 728    * \param format              transaction format.  See usrp_spi_defs.h SPI_FMT_*
 729    * \param buf                 the data to write
 730    * \returns true iff successful
 731    * Writes are limited to a maximum of 64 bytes.
 732    *
 733    * If \p format specifies that optional_header bytes are present, they are
 734    * written to the peripheral immediately prior to writing \p buf.
 735    */
 736   bool _write_spi (int optional_header, int enables, int format, std::string buf);
 737
 738   /*
 739    * \brief Read data from SPI bus peripheral.
 740    *
 741    * \param optional_header     0,1 or 2 bytes to write before buf.
 742    * \param enables             bitmask of peripheral to read. See usrp_spi_defs.h
 743    * \param format              transaction format.  See usrp_spi_defs.h SPI_FMT_*
 744    * \param len                 number of bytes to read.  Must be in [0,64].
 745    * \returns the data read if sucessful, else a zero length string.
 746    *
 747    * Reads are limited to a maximum of 64 bytes.
 748    *
 749    * If \p format specifies that optional_header bytes are present, they
 750    * are written to the peripheral first.  Then \p len bytes are read from
 751    * the peripheral and returned.
 752    */
 753   std::string _read_spi (int optional_header, int enables, int format, int len);
 754
 755   /*!
 756    * \brief Start data transfers.
 757    * Called in base class to derived class order.
 758    */
 759   bool start ();
 760
 761   /*!
 762    * \brief Stop data transfers.
 763    * Called in base class to derived class order.
 764    */
 765   bool stop ();
 766 };
 767
 768 \f/*!
 769  * \brief class for accessing the receive side of the USRP
 770  * \ingroup usrp
 771  */
 772 class usrp_basic_rx : public usrp_basic
 773 {
 774 private:
 775   fusb_devhandle        *d_devhandle;
 776   fusb_ephandle         *d_ephandle;
 777   int                    d_bytes_seen;          // how many bytes we've seen
 778   bool                   d_first_read;
 779   bool                   d_rx_enable;
 780
 781 protected:
 782   /*!
 783    * \param which_board      Which USRP board on usb (not particularly useful; use 0)
 784    * \param fusb_block_size  fast usb xfer block size.  Must be a multiple of 512.
 785    *                         Use zero for a reasonable default.
 786    * \param fusb_nblocks     number of fast usb URBs to allocate.  Use zero for a reasonable default.
 787    * \param fpga_filename    name of the rbf file to load
 788    * \param firmware_filename name of ihx file to load
 789    */
 790   usrp_basic_rx (int which_board,
 791                  int fusb_block_size=0,
 792                  int fusb_nblocks=0,
 793                  const std::string fpga_filename = "",
 794                  const std::string firmware_filename = ""
 795                  );  // throws if trouble
 796
 797   bool set_rx_enable (bool on);
 798   bool rx_enable () const { return d_rx_enable; }
 799
 800   bool disable_rx ();           // conditional disable, return prev state
 801   void restore_rx (bool on);    // conditional set
 802
 803   void probe_rx_slots (bool verbose);
 804
 805 public:
 806   ~usrp_basic_rx ();
 807
 808   /*!
 809    * \brief invokes constructor, returns instance or 0 if trouble
 810    *
 811    * \param which_board      Which USRP board on usb (not particularly useful; use 0)
 812    * \param fusb_block_size  fast usb xfer block size.  Must be a multiple of 512.
 813    *                         Use zero for a reasonable default.
 814    * \param fusb_nblocks     number of fast usb URBs to allocate.  Use zero for a reasonable default.
 815    * \param fpga_filename    name of file that contains image to load into FPGA
 816    * \param firmware_filename   name of file that contains image to load into FX2
 817    */
 818   static usrp_basic_rx *make (int which_board,
 819                               int fusb_block_size=0,
 820                               int fusb_nblocks=0,
 821                               const std::string fpga_filename = "",
 822                               const std::string firmware_filename = ""
 823                               );
 824
 825   /*!
 826    * \brief tell the fpga the rate rx samples are coming from the A/D's
 827    *
 828    * div = fpga_master_clock_freq () / sample_rate
 829    *
 830    * sample_rate is determined by a myriad of registers
 831    * in the 9862.  That's why you have to tell us, so
 832    * we can tell the fpga.
 833    */
 834   bool set_fpga_rx_sample_rate_divisor (unsigned int div);
 835
 836   /*!
 837    * \brief read data from the D/A's via the FPGA.
 838    * \p len must be a multiple of 512 bytes.
 839    *
 840    * \returns the number of bytes read, or -1 on error.
 841    *
 842    * If overrun is non-NULL it will be set true iff an RX overrun is detected.
 843    */
 844   int read (void *buf, int len, bool *overrun);
 845
 846
 847   //! sampling rate of A/D converter
 848   virtual long converter_rate() const { return fpga_master_clock_freq(); } // 64M
 849   long adc_rate() const { return converter_rate(); }
 850   int daughterboard_id (int which_side) const { return d_dbid[which_side & 0x1]; }
 851
 852   bool set_pga (int which_amp, double gain_in_db);
 853   double pga (int which_amp) const;
 854   double pga_min () const;
 855   double pga_max () const;
 856   double pga_db_per_step () const;
 857
 858   bool _write_oe (int which_side, int value, int mask);
 859   bool write_io (int which_side, int value, int mask);
 860   bool read_io (int which_side, int *value);
 861   int read_io (int which_side);
 862   bool write_refclk(int which_side, int value);
 863   bool write_atr_mask(int which_side, int value);
 864   bool write_atr_txval(int which_side, int value);
 865   bool write_atr_rxval(int which_side, int value);
 866
 867   bool write_aux_dac (int which_side, int which_dac, int value);
 868   bool read_aux_adc (int which_side, int which_adc, int *value);
 869   int  read_aux_adc (int which_side, int which_adc);
 870
 871   int block_size() const;
 872
 873   // called in base class to derived class order
 874   bool start ();
 875   bool stop ();
 876 };
 877
 878 \f/*!
 879  * \brief class for accessing the transmit side of the USRP
 880  * \ingroup usrp
 881  */
 882 class usrp_basic_tx : public usrp_basic
 883 {
 884 private:
 885   fusb_devhandle        *d_devhandle;
 886   fusb_ephandle         *d_ephandle;
 887   int                    d_bytes_seen;          // how many bytes we've seen
 888   bool                   d_first_write;
 889   bool                   d_tx_enable;
 890
 891  protected:
 892   /*!
 893    * \param which_board      Which USRP board on usb (not particularly useful; use 0)
 894    * \param fusb_block_size  fast usb xfer block size.  Must be a multiple of 512.
 895    *                         Use zero for a reasonable default.
 896    * \param fusb_nblocks     number of fast usb URBs to allocate.  Use zero for a reasonable default.
 897    * \param fpga_filename    name of file that contains image to load into FPGA
 898    * \param firmware_filename   name of file that contains image to load into FX2
 899    */
 900   usrp_basic_tx (int which_board,
 901                  int fusb_block_size=0,
 902                  int fusb_nblocks=0,
 903                  const std::string fpga_filename = "",
 904                  const std::string firmware_filename = ""
 905                  );             // throws if trouble
 906
 907   bool set_tx_enable (bool on);
 908   bool tx_enable () const { return d_tx_enable; }
 909
 910   bool disable_tx ();           // conditional disable, return prev state
 911   void restore_tx (bool on);    // conditional set
 912
 913   void probe_tx_slots (bool verbose);
 914
 915 public:
 916
 917   ~usrp_basic_tx ();
 918
 919   /*!
 920    * \brief invokes constructor, returns instance or 0 if trouble
 921    *
 922    * \param which_board      Which USRP board on usb (not particularly useful; use 0)
 923    * \param fusb_block_size  fast usb xfer block size.  Must be a multiple of 512.
 924    *                         Use zero for a reasonable default.
 925    * \param fusb_nblocks     number of fast usb URBs to allocate.  Use zero for a reasonable default.
 926    * \param fpga_filename    name of file that contains image to load into FPGA
 927    * \param firmware_filename   name of file that contains image to load into FX2
 928    */
 929   static usrp_basic_tx *make (int which_board, int fusb_block_size=0, int fusb_nblocks=0,
 930                               const std::string fpga_filename = "",
 931                               const std::string firmware_filename = ""
 932                               );
 933
 934   /*!
 935    * \brief tell the fpga the rate tx samples are going to the D/A's
 936    *
 937    * div = fpga_master_clock_freq () * 2
 938    *
 939    * sample_rate is determined by a myriad of registers
 940    * in the 9862.  That's why you have to tell us, so
 941    * we can tell the fpga.
 942    */
 943   bool set_fpga_tx_sample_rate_divisor (unsigned int div);
 944
 945   /*!
 946    * \brief Write data to the A/D's via the FPGA.
 947    *
 948    * \p len must be a multiple of 512 bytes.
 949    * \returns number of bytes written or -1 on error.
 950    *
 951    * if \p underrun is non-NULL, it will be set to true iff
 952    * a transmit underrun condition is detected.
 953    */
 954   int write (const void *buf, int len, bool *underrun);
 955
 956   /*
 957    * Block until all outstanding writes have completed.
 958    * This is typically used to assist with benchmarking
 959    */
 960   void wait_for_completion ();
 961
 962   //! sampling rate of D/A converter
 963   virtual long converter_rate() const { return fpga_master_clock_freq () * 2; } // 128M
 964   long dac_rate() const { return converter_rate(); }
 965   int daughterboard_id (int which_side) const { return d_dbid[which_side & 0x1]; }
 966
 967   bool set_pga (int which_amp, double gain_in_db);
 968   double pga (int which_amp) const;
 969   double pga_min () const;
 970   double pga_max () const;
 971   double pga_db_per_step () const;
 972
 973   bool _write_oe (int which_side, int value, int mask);
 974   bool write_io (int which_side, int value, int mask);
 975   bool read_io (int which_side, int *value);
 976   int read_io (int which_side);
 977   bool write_refclk(int which_side, int value);
 978   bool write_atr_mask(int which_side, int value);
 979   bool write_atr_txval(int which_side, int value);
 980   bool write_atr_rxval(int which_side, int value);
 981
 982   bool write_aux_dac (int which_side, int which_dac, int value);
 983   bool read_aux_adc (int which_side, int which_adc, int *value);
 984   int read_aux_adc (int which_side, int which_adc);
 985
 986   int block_size() const;
 987
 988   // called in base class to derived class order
 989   bool start ();
 990   bool stop ();
 991 };
 992
 993 #endif /* INCLUDED_USRP_BASIC_H */