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

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