Universal Software Radio Peripheral

usrp_basic.h

Go to the documentation of this file.
00001 /*  -*- c++ -*- */
00002 /*
00003  * Copyright 2005,2009 Free Software Foundation, Inc.
00004  *
00005  * This file is part of GNU Radio
00006  *
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  *
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef INCLUDED_USRP_BASIC_H
00024 #define INCLUDED_USRP_BASIC_H
00025 
00026 #include <usrp/db_base.h>
00027 #include <usrp/usrp_slots.h>
00028 #include <usrp/usrp_subdev_spec.h>
00029 #include <usrp/libusb_types.h>
00030 #include <string>
00031 #include <vector>
00032 #include <boost/utility.hpp>
00033 
00034 class  fusb_devhandle;
00035 class  fusb_ephandle;
00036 
00037 enum txrx_t {
00038   C_RX = 0,
00039   C_TX = 1
00040 };
00041 
00042 /*
00043  * ----------------------------------------------------------------------
00044  * Mid level interface to the Universal Software Radio Peripheral (Rev 1)
00045  *
00046  * These classes implement the basic functionality for talking to the
00047  * USRP.  They try to be as independent of the signal processing code
00048  * in FPGA as possible.  They implement access to the low level
00049  * peripherals on the board, provide a common way for reading and
00050  * writing registers in the FPGA, and provide the high speed interface
00051  * to streaming data across the USB.
00052  *
00053  * It is expected that subclasses will be derived that provide
00054  * access to the functionality to a particular FPGA configuration.
00055  * ----------------------------------------------------------------------
00056  */
00057 
00058 
00063 class usrp_basic : boost::noncopyable
00064 {
00065 protected:
00066   void shutdown_daughterboards();
00067 
00068 protected:
00069   libusb_device_handle          *d_udh;
00070   struct libusb_context         *d_ctx;
00071   int                            d_usb_data_rate;       // bytes/sec
00072   int                            d_bytes_per_poll;      // how often to poll for overruns
00073   bool                           d_verbose;
00074   long                           d_fpga_master_clock_freq;
00075 
00076   static const int               MAX_REGS = 128;
00077   unsigned int                   d_fpga_shadows[MAX_REGS];
00078 
00079   int                            d_dbid[2];             // daughterboard ID's (side A, side B)
00080 
00089   std::vector< std::vector<db_base_sptr> > d_db;
00090 
00092   void init_db(usrp_basic_sptr u);
00093 
00094 
00095   usrp_basic (int which_board,
00096               libusb_device_handle *open_interface (libusb_device *dev),
00097               const std::string fpga_filename = "",
00098               const std::string firmware_filename = "");
00099 
00109   void set_usb_data_rate (int usb_data_rate);
00110   
00121   bool _write_aux_dac (int slot, int which_dac, int value);
00122 
00131   bool _read_aux_adc (int slot, int which_adc, int *value);
00132 
00140   int _read_aux_adc (int slot, int which_adc);
00141 
00142 
00143 public:
00144   virtual ~usrp_basic ();
00145 
00146 
00154   std::vector<std::vector<db_base_sptr> > db() const { return d_db; }
00155 
00165   std::vector<db_base_sptr> db(int which_side);
00166  
00170   bool is_valid(const usrp_subdev_spec &ss);
00171 
00178   db_base_sptr selected_subdev(const usrp_subdev_spec &ss);
00179 
00183   long fpga_master_clock_freq () const { return d_fpga_master_clock_freq; }
00184 
00192   void set_fpga_master_clock_freq (long master_clock) { d_fpga_master_clock_freq = master_clock; }
00193 
00197   int usb_data_rate () const { return d_usb_data_rate; }
00198 
00199   void set_verbose (bool on) { d_verbose = on; }
00200 
00202   static const int READ_FAILED = -99999;
00203 
00211   bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string buf);
00212 
00220   std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
00221 
00229   bool write_i2c (int i2c_addr, const std::string buf);
00230 
00238   std::string read_i2c (int i2c_addr, int len);
00239 
00245   bool set_adc_offset (int which_adc, int offset);
00246 
00254   bool set_dac_offset (int which_dac, int offset, int offset_pin);
00255 
00262   bool set_adc_buffer_bypass (int which_adc, bool bypass);
00263 
00284   bool set_dc_offset_cl_enable(int bits, int mask);
00285 
00291   std::string serial_number();
00292 
00302   virtual int daughterboard_id (int which_side) const = 0;
00303 
00308   bool write_atr_tx_delay(int value);
00309 
00314   bool write_atr_rx_delay(int value);
00315 
00316 
00317   // ================================================================
00318   // Routines to access and control daughterboard specific i/o
00319   //
00320   // Those with a common_ prefix access either the Tx or Rx side depending
00321   // on the txrx parameter.  Those without the common_ prefix are virtual
00322   // and are overriden in usrp_basic_rx and usrp_basic_tx to access the
00323   // the Rx or Tx sides automatically.  We provide the common_ versions
00324   // for those daughterboards such as the WBX and XCVR2450 that share
00325   // h/w resources (such as the LO) between the Tx and Rx sides.
00326 
00327   // ----------------------------------------------------------------
00328   // BEGIN common_  daughterboard control functions
00329 
00343   bool common_set_pga(txrx_t txrx, int which_amp, double gain_in_db);
00344 
00351   double common_pga(txrx_t txrx, int which_amp) const;
00352 
00357   double common_pga_min(txrx_t txrx) const;
00358 
00363   double common_pga_max(txrx_t txrx) const;
00364 
00369   double common_pga_db_per_step(txrx_t txrx) const;
00370 
00387   bool _common_write_oe(txrx_t txrx, int which_side, int value, int mask);
00388 
00397   bool common_write_io(txrx_t txrx, int which_side, int value, int mask);
00398 
00406   bool common_read_io(txrx_t txrx, int which_side, int *value);
00407 
00415   int common_read_io(txrx_t txrx, int which_side);
00416 
00438   bool common_write_refclk(txrx_t txrx, int which_side, int value);
00439 
00468   bool common_write_atr_mask(txrx_t txrx, int which_side, int value);
00469   bool common_write_atr_txval(txrx_t txrx, int which_side, int value);
00470   bool common_write_atr_rxval(txrx_t txrx, int which_side, int value);
00471 
00483   bool common_write_aux_dac(txrx_t txrx, int which_side, int which_dac, int value);
00484 
00494   bool common_read_aux_adc(txrx_t txrx, int which_side, int which_adc, int *value);
00495 
00504   int common_read_aux_adc(txrx_t txrx, int which_side, int which_adc);
00505 
00506   // END common_ daughterboard control functions
00507   // ----------------------------------------------------------------
00508   // BEGIN virtual daughterboard control functions
00509 
00522   virtual bool set_pga (int which_amp, double gain_in_db) = 0;
00523 
00529   virtual double pga (int which_amp) const = 0;
00530 
00534   virtual double pga_min () const = 0;
00535 
00539   virtual double pga_max () const = 0;
00540 
00544   virtual double pga_db_per_step () const = 0;
00545 
00561   virtual bool _write_oe (int which_side, int value, int mask) = 0;
00562 
00570   virtual bool write_io (int which_side, int value, int mask) = 0;
00571 
00578   virtual bool read_io (int which_side, int *value) = 0;
00579 
00586   virtual int read_io (int which_side) = 0;
00587 
00608   virtual bool write_refclk(int which_side, int value) = 0;
00609 
00610   virtual bool write_atr_mask(int which_side, int value) = 0;
00611   virtual bool write_atr_txval(int which_side, int value) = 0;
00612   virtual bool write_atr_rxval(int which_side, int value) = 0;
00613 
00624   virtual bool write_aux_dac (int which_side, int which_dac, int value) = 0;
00625 
00634   virtual bool read_aux_adc (int which_side, int which_adc, int *value) = 0;
00635 
00643   virtual int read_aux_adc (int which_side, int which_adc) = 0;
00644 
00648   virtual int block_size() const = 0;
00649 
00653   virtual long converter_rate() const = 0;
00654 
00655   // END virtual daughterboard control functions
00656 
00657   // ----------------------------------------------------------------
00658   // Low level implementation routines.
00659   // You probably shouldn't be using these...
00660   //
00661 
00662   bool _set_led (int which_led, bool on);
00663 
00670   bool _write_fpga_reg (int regno, int value);  //< 7-bit regno, 32-bit value
00671 
00678   bool _read_fpga_reg (int regno, int *value);  //< 7-bit regno, 32-bit value
00679 
00685   int  _read_fpga_reg (int regno);
00686 
00695   bool _write_fpga_reg_masked (int regno, int value, int mask);
00696 
00704   bool _write_9862 (int which_codec, int regno, unsigned char value);
00705 
00713   bool _read_9862 (int which_codec, int regno, unsigned char *value) const;
00714 
00721   int  _read_9862 (int which_codec, int regno) const;
00722 
00736   bool _write_spi (int optional_header, int enables, int format, std::string buf);
00737 
00738   /*
00739    * \brief Read data from SPI bus peripheral.
00740    *
00741    * \param optional_header     0,1 or 2 bytes to write before buf.
00742    * \param enables             bitmask of peripheral to read. See usrp_spi_defs.h
00743    * \param format              transaction format.  See usrp_spi_defs.h SPI_FMT_*
00744    * \param len                 number of bytes to read.  Must be in [0,64].
00745    * \returns the data read if sucessful, else a zero length string.
00746    *
00747    * Reads are limited to a maximum of 64 bytes.
00748    *
00749    * If \p format specifies that optional_header bytes are present, they
00750    * are written to the peripheral first.  Then \p len bytes are read from
00751    * the peripheral and returned.
00752    */
00753   std::string _read_spi (int optional_header, int enables, int format, int len);
00754 
00759   bool start ();
00760 
00765   bool stop ();
00766 };
00767 
00768 
00772 class usrp_basic_rx : public usrp_basic 
00773 {
00774 private:
00775   fusb_devhandle        *d_devhandle;
00776   fusb_ephandle         *d_ephandle;
00777   int                    d_bytes_seen;          // how many bytes we've seen
00778   bool                   d_first_read;
00779   bool                   d_rx_enable;
00780 
00781 protected:
00790   usrp_basic_rx (int which_board,
00791                  int fusb_block_size=0,
00792                  int fusb_nblocks=0,
00793                  const std::string fpga_filename = "",
00794                  const std::string firmware_filename = ""
00795                  );  // throws if trouble
00796 
00797   bool set_rx_enable (bool on);
00798   bool rx_enable () const { return d_rx_enable; }
00799 
00800   bool disable_rx ();           // conditional disable, return prev state
00801   void restore_rx (bool on);    // conditional set
00802 
00803   void probe_rx_slots (bool verbose);
00804 
00805 public:
00806   ~usrp_basic_rx ();
00807 
00818   static usrp_basic_rx *make (int which_board,
00819                               int fusb_block_size=0,
00820                               int fusb_nblocks=0,
00821                               const std::string fpga_filename = "",
00822                               const std::string firmware_filename = ""
00823                               );
00824 
00834   bool set_fpga_rx_sample_rate_divisor (unsigned int div);
00835 
00844   int read (void *buf, int len, bool *overrun);
00845 
00846 
00848   virtual long converter_rate() const { return fpga_master_clock_freq(); } // 64M
00849   long adc_rate() const { return converter_rate(); }
00850   int daughterboard_id (int which_side) const { return d_dbid[which_side & 0x1]; }
00851 
00852   bool set_pga (int which_amp, double gain_in_db);
00853   double pga (int which_amp) const;
00854   double pga_min () const;
00855   double pga_max () const;
00856   double pga_db_per_step () const;
00857 
00858   bool _write_oe (int which_side, int value, int mask);
00859   bool write_io (int which_side, int value, int mask);
00860   bool read_io (int which_side, int *value);
00861   int read_io (int which_side);
00862   bool write_refclk(int which_side, int value);
00863   bool write_atr_mask(int which_side, int value);
00864   bool write_atr_txval(int which_side, int value);
00865   bool write_atr_rxval(int which_side, int value);
00866 
00867   bool write_aux_dac (int which_side, int which_dac, int value);
00868   bool read_aux_adc (int which_side, int which_adc, int *value);
00869   int  read_aux_adc (int which_side, int which_adc);
00870 
00871   int block_size() const;
00872 
00873   // called in base class to derived class order
00874   bool start ();
00875   bool stop ();
00876 };
00877 
00878 
00882 class usrp_basic_tx : public usrp_basic 
00883 {
00884 private:
00885   fusb_devhandle        *d_devhandle;
00886   fusb_ephandle         *d_ephandle;
00887   int                    d_bytes_seen;          // how many bytes we've seen
00888   bool                   d_first_write;
00889   bool                   d_tx_enable;
00890 
00891  protected:
00900   usrp_basic_tx (int which_board,
00901                  int fusb_block_size=0,
00902                  int fusb_nblocks=0,
00903                  const std::string fpga_filename = "",
00904                  const std::string firmware_filename = ""
00905                  );             // throws if trouble
00906 
00907   bool set_tx_enable (bool on);
00908   bool tx_enable () const { return d_tx_enable; }
00909 
00910   bool disable_tx ();           // conditional disable, return prev state
00911   void restore_tx (bool on);    // conditional set
00912 
00913   void probe_tx_slots (bool verbose);
00914 
00915 public:
00916 
00917   ~usrp_basic_tx ();
00918 
00929   static usrp_basic_tx *make (int which_board, int fusb_block_size=0, int fusb_nblocks=0,
00930                               const std::string fpga_filename = "",
00931                               const std::string firmware_filename = ""
00932                               );
00933 
00943   bool set_fpga_tx_sample_rate_divisor (unsigned int div);
00944 
00954   int write (const void *buf, int len, bool *underrun);
00955 
00956   /*
00957    * Block until all outstanding writes have completed.
00958    * This is typically used to assist with benchmarking
00959    */
00960   void wait_for_completion ();
00961 
00963   virtual long converter_rate() const { return fpga_master_clock_freq () * 2; } // 128M
00964   long dac_rate() const { return converter_rate(); }
00965   int daughterboard_id (int which_side) const { return d_dbid[which_side & 0x1]; }
00966 
00967   bool set_pga (int which_amp, double gain_in_db);
00968   double pga (int which_amp) const;
00969   double pga_min () const;
00970   double pga_max () const;
00971   double pga_db_per_step () const;
00972 
00973   bool _write_oe (int which_side, int value, int mask);
00974   bool write_io (int which_side, int value, int mask);
00975   bool read_io (int which_side, int *value);
00976   int read_io (int which_side);
00977   bool write_refclk(int which_side, int value);
00978   bool write_atr_mask(int which_side, int value);
00979   bool write_atr_txval(int which_side, int value);
00980   bool write_atr_rxval(int which_side, int value);
00981 
00982   bool write_aux_dac (int which_side, int which_dac, int value);
00983   bool read_aux_adc (int which_side, int which_adc, int *value);
00984   int read_aux_adc (int which_side, int which_adc);
00985 
00986   int block_size() const;
00987 
00988   // called in base class to derived class order
00989   bool start ();
00990   bool stop ();
00991 };
00992 
00993 #endif /* INCLUDED_USRP_BASIC_H */