git.gag.com Git - debian/gnuradio/blob - gr-usrp/src/usrp1.i

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2004 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 2, 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 %feature("autodoc", "1");               // generate python docstrings
  24
  25 %include "exception.i"
  26 %import "gnuradio.i"                            // the common stuff
  27
  28 %{
  29
  30 #include "gnuradio_swig_bug_workaround.h"       // mandatory bug fix
  31 #include "usrp1_sink_c.h"
  32 #include "usrp1_sink_s.h"
  33 #include "usrp1_source_c.h"
  34 #include "usrp1_source_s.h"
  35 #include <stdexcept>
  36 #include <usrp_standard.h>
  37 #include <usrp_spi_defs.h>
  38 %}
  39
  40 %include <usrp_spi_defs.h>
  41
  42 %constant int FPGA_MODE_NORMAL   = usrp_standard_rx::FPGA_MODE_NORMAL;
  43 %constant int FPGA_MODE_LOOPBACK = usrp_standard_rx::FPGA_MODE_LOOPBACK;
  44 %constant int FPGA_MODE_COUNTING = usrp_standard_rx::FPGA_MODE_COUNTING;
  45
  46 // ================================================================
  47 //                         abstract classes
  48 // ================================================================
  49
  50 class usrp1_sink_base : public gr_sync_block {
  51 protected:
  52   usrp1_sink_base (const std::string &name,
  53                    gr_io_signature_sptr input_signature,
  54                    int which_board,
  55                    unsigned int interp_rate,
  56                    int nchan,
  57                    int mux,
  58                    int fusb_block_size,
  59                    int fusb_nblocks,
  60                    const std::string fpga_filename,
  61                    const std::string firmware_filename
  62                    ) throw (std::runtime_error);
  63
  64   virtual void copy_to_usrp_buffer (gr_vector_const_void_star &input_items,
  65                                     int  input_index,
  66                                     int  input_items_available,
  67                                     int  &input_items_consumed,
  68                                     void *usrp_buffer,
  69                                     int  usrp_buffer_length,
  70                                     int  &bytes_written) = 0;
  71  public:
  72   ~usrp1_sink_base ();
  73
  74   /*!
  75    * \brief Set interpolator rate.  \p rate must be in [4, 1024] and a multiple of 4.
  76    *
  77    * The final complex sample rate across the USB is
  78    *   dac_freq () * nchannels () / interp_rate ()
  79    */
  80   bool set_interp_rate (unsigned int rate);
  81   bool set_nchannels (int nchan);
  82   bool set_mux (int mux);
  83
  84   /*!
  85    * \brief set the frequency of the digital up converter.
  86    *
  87    * \p channel must be 0 or 1.  \p freq is the center frequency in Hz.
  88    * It must be in the range [-44M, 44M].  The frequency specified is
  89    * quantized.  Use tx_freq to retrieve the actual value used.
  90    */
  91   bool set_tx_freq (int channel, double freq);
  92
  93   void set_verbose (bool verbose);
  94
  95   // ACCESSORS
  96
  97   long fpga_master_clock_freq() const;
  98   long converter_rate() const;      // D/A sample rate
  99   long dac_rate() const;            // alias
 100   long dac_freq () const;           // deprecated name.  Use converter_rate() or dac_rate().
 101
 102   unsigned int interp_rate () const;
 103   double tx_freq (int channel) const;
 104   int nunderruns () const { return d_nunderruns; }
 105
 106   /*!
 107    * \brief Set Programmable Gain Amplifier (PGA)
 108    *
 109    * \param which       which D/A [0,3]
 110    * \param gain_in_db  gain value (linear in dB)
 111    *
 112    * gain is rounded to closest setting supported by hardware.
 113    * Note that DAC 0 and DAC 1 share a gain setting as do DAC 2 and DAC 3.
 114    * Setting DAC 0 affects DAC 1 and vice versa.  Same with DAC 2 and DAC 3.
 115    *
 116    * \returns true iff sucessful.
 117    *
 118    * \sa pga_min(), pga_max(), pga_db_per_step()
 119    */
 120   bool set_pga (int which, double gain_in_db);
 121
 122   /*!
 123    * \brief Return programmable gain amplifier gain in dB.
 124    *
 125    * \param which       which D/A [0,3]
 126    */
 127   double pga (int which) const;
 128
 129   /*!
 130    * \brief Return minimum legal PGA gain in dB.
 131    */
 132   double pga_min () const;
 133
 134   /*!
 135    * \brief Return maximum legal PGA gain in dB.
 136    */
 137   double pga_max () const;
 138
 139   /*!
 140    * \brief Return hardware step size of PGA (linear in dB).
 141    */
 142   double pga_db_per_step () const;
 143
 144   /*!
 145    * \brief Return daughterboard ID for given Tx daughterboard slot [0,1].
 146    *
 147    * \return daughterboard id >= 0 if successful
 148    * \return -1 if no daugherboard
 149    * \return -2 if invalid EEPROM on daughterboard
 150    */
 151   int daughterboard_id (int which_dboard) const;
 152
 153   /*!
 154    * \brief Set ADC offset correction
 155    * \param which       which ADC[0,3]: 0 = RX_A I, 1 = RX_A Q...
 156    * \param offset      16-bit value to subtract from raw ADC input.
 157    */
 158   bool set_adc_offset (int which, int offset);
 159
 160   /*!
 161    * \brief Set DAC offset correction
 162    * \param which       which DAC[0,3]: 0 = TX_A I, 1 = TX_A Q...
 163    * \param offset      10-bit offset value (ambiguous format:  See AD9862 datasheet).
 164    * \param offset_pin  1-bit value.  If 0 offset applied to -ve differential pin;
 165    *                                  If 1 offset applied to +ve differential pin.
 166    */
 167   bool set_dac_offset (int which, int offset, int offset_pin);
 168
 169   /*!
 170    * \brief Control ADC input buffer
 171    * \param which       which ADC[0,3]
 172    * \param bypass      if non-zero, bypass input buffer and connect input
 173    *                    directly to switched cap SHA input of RxPGA.
 174    */
 175   bool set_adc_buffer_bypass (int which, bool bypass);
 176
 177   /*!
 178    * \brief return the usrp's serial number.
 179    *
 180    * \returns non-zero length string iff successful.
 181    */
 182   std::string serial_number();
 183
 184   /*!
 185    * \brief Write direction register (output enables) for pins that go to daughterboard.
 186    *
 187    * \param which_dboard        [0,1] which d'board
 188    * \param value               value to write into register
 189    * \param mask                which bits of value to write into reg
 190    *
 191    * Each d'board has 16-bits of general purpose i/o.
 192    * Setting the bit makes it an output from the FPGA to the d'board.
 193    *
 194    * This register is initialized based on a value stored in the
 195    * d'board EEPROM.  In general, you shouldn't be using this routine
 196    * without a very good reason.  Using this method incorrectly will
 197    * kill your USRP motherboard and/or daughterboard.
 198    */
 199   bool _write_oe (int which_dboard, int value, int mask);
 200
 201   /*!
 202    * \brief Write daughterboard i/o pin value
 203    *
 204    * \param which_dboard        [0,1] which d'board
 205    * \param value               value to write into register
 206    * \param mask                which bits of value to write into reg
 207    */
 208   bool write_io (int which_dboard, int value, int mask);
 209
 210   /*!
 211    * \brief Read daughterboard i/o pin value
 212    *
 213    * \param which_dboard        [0,1] which d'board
 214    * \returns register value if successful, else READ_FAILED
 215    */
 216   int read_io (int which_dboard);
 217
 218   bool write_aux_dac (int which_dboard, int which_dac, int value);
 219   int read_aux_adc (int which_dboard, int which_adc);
 220   bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string buf);
 221   std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
 222   bool write_i2c (int i2c_addr, const std::string buf);
 223   std::string read_i2c (int i2c_addr, int len);
 224
 225   bool _write_fpga_reg (int regno, int value);  //< 7-bit regno, 32-bit value
 226   int  _read_fpga_reg (int regno);
 227   bool _write_9862 (int which_codec, int regno, unsigned char value);
 228   int  _read_9862 (int which_codec, int regno) const;
 229
 230   /*!
 231    * \brief Write data to SPI bus peripheral.
 232    *
 233    * \param optional_header     0,1 or 2 bytes to write before buf.
 234    * \param enables             bitmask of peripherals to write. See usrp_spi_defs.h
 235    * \param format              transaction format.  See usrp_spi_defs.h SPI_FMT_*
 236    * \param buf                 the data to write
 237    * \returns true iff successful
 238    * Writes are limited to a maximum of 64 bytes.
 239    *
 240    * If \p format specifies that optional_header bytes are present, they are
 241    * written to the peripheral immediately prior to writing \p buf.
 242    */
 243   bool _write_spi (int optional_header, int enables, int format, std::string buf);
 244
 245   /*
 246    * \brief Read data from SPI bus peripheral.
 247    *
 248    * \param optional_header     0,1 or 2 bytes to write before buf.
 249    * \param enables             bitmask of peripheral to read. See usrp_spi_defs.h
 250    * \param format              transaction format.  See usrp_spi_defs.h SPI_FMT_*
 251    * \param len                 number of bytes to read.  Must be in [0,64].
 252    * \returns the data read if sucessful, else a zero length string.
 253    *
 254    * Reads are limited to a maximum of 64 bytes.
 255    *
 256    * If \p format specifies that optional_header bytes are present, they
 257    * are written to the peripheral first.  Then \p len bytes are read from
 258    * the peripheral and returned.
 259    */
 260   std::string _read_spi (int optional_header, int enables, int format, int len);
 261 };
 262
 263 // ----------------------------------------------------------------
 264
 265 class usrp1_source_base : public gr_sync_block {
 266  protected:
 267
 268   usrp1_sink_base (const std::string &name,
 269                    gr_io_signature_sptr input_signature,
 270                    int which_board,
 271                    unsigned int interp_rate,
 272                    int nchan,
 273                    int mux,
 274                    int fusb_block_size,
 275                    int fusb_nblocks,
 276                    const std::string fpga_filename,
 277                    const std::string firmware_filename
 278                    ) throw (std::runtime_error);
 279
 280   virtual int ninput_bytes_reqd_for_noutput_items (int noutput_items) = 0;
 281
 282   virtual void copy_from_usrp_buffer (gr_vector_void_star &output_items,
 283                                       int output_index,
 284                                       int output_items_available,
 285                                       int &output_items_produced,
 286                                       const void *usrp_buffer,
 287                                       int usrp_buffer_length,
 288                                       int &bytes_read) = 0;
 289  public:
 290   ~usrp1_source_base ();
 291
 292
 293   /*!
 294    * \brief Set decimator rate.  \p rate must be EVEN and in [8, 256].
 295    *
 296    * The final complex sample rate across the USB is
 297    *   adc_freq () / decim_rate ()
 298    */
 299   bool set_decim_rate (unsigned int rate);
 300   bool set_nchannels (int nchan);
 301   bool set_mux (int mux);
 302
 303   /*!
 304    * \brief set the center frequency of the digital down converter.
 305    *
 306    * \p channel must be 0.  \p freq is the center frequency in Hz.
 307    * It must be in the range [-FIXME, FIXME].  The frequency specified is
 308    * quantized.  Use rx_freq to retrieve the actual value used.
 309    */
 310   bool set_rx_freq (int channel, double freq);
 311
 312   /*!
 313    * \brief set fpga special modes
 314    */
 315   bool set_fpga_mode (int mode);
 316
 317   /*!
 318    * \brief Set the digital down converter phase register.
 319    *
 320    * \param channel     which ddc channel [0, 3]
 321    * \param phase       32-bit integer phase value.
 322    */
 323   bool set_ddc_phase(int channel, int phase);
 324
 325
 326   void set_verbose (bool verbose);
 327
 328   // ACCESSORS
 329
 330   long fpga_master_clock_freq() const;
 331   long converter_rate() const;  // A/D sample rate
 332   long adc_rate() const;        // alias
 333   long adc_freq() const;        // Deprecated name.  Use converter_rate() or adc_rate().
 334
 335   unsigned int decim_rate () const;
 336   double rx_freq (int channel) const;
 337   int noverruns () const { return d_noverruns; }
 338
 339
 340   // PGA stuff
 341   /*!
 342    * \brief Set Programmable Gain Amplifier (PGA)
 343    *
 344    * \param which       which A/D [0,3]
 345    * \param gain_in_db  gain value (linear in dB)
 346    *
 347    * gain is rounded to closest setting supported by hardware.
 348    *
 349    * \returns true iff sucessful.
 350    *
 351    * \sa pga_min(), pga_max(), pga_db_per_step()
 352    */
 353   bool set_pga (int which, double gain_in_db);
 354
 355   /*!
 356    * \brief Return programmable gain amplifier gain setting in dB.
 357    *
 358    * \param which       which A/D [0,3]
 359    */
 360   double pga (int which) const;
 361
 362   /*!
 363    * \brief Return minimum legal PGA setting in dB.
 364    */
 365   double pga_min () const;
 366
 367   /*!
 368    * \brief Return maximum legal PGA setting in dB.
 369    */
 370   double pga_max () const;
 371
 372   /*!
 373    * \brief Return hardware step size of PGA (linear in dB).
 374    */
 375   double pga_db_per_step () const;
 376
 377   /*!
 378    * \brief Return daughterboard ID for given Rx daughterboard slot [0,1].
 379    *
 380    * \return daughterboard id >= 0 if successful
 381    * \return -1 if no daugherboard
 382    * \return -2 if invalid EEPROM on daughterboard
 383    */
 384   int daughterboard_id (int which_dboard) const;
 385
 386   /*!
 387    * \brief Set ADC offset correction
 388    * \param which       which ADC[0,3]: 0 = RX_A I, 1 = RX_A Q...
 389    * \param offset      16-bit value to subtract from raw ADC input.
 390    */
 391   bool set_adc_offset (int which, int offset);
 392
 393   /*!
 394    * \brief Set DAC offset correction
 395    * \param which       which DAC[0,3]: 0 = TX_A I, 1 = TX_A Q...
 396    * \param offset      10-bit offset value (ambiguous format:  See AD9862 datasheet).
 397    * \param offset_pin  1-bit value.  If 0 offset applied to -ve differential pin;
 398    *                                  If 1 offset applied to +ve differential pin.
 399    */
 400   bool set_dac_offset (int which, int offset, int offset_pin);
 401
 402   /*!
 403    * \brief Control ADC input buffer
 404    * \param which       which ADC[0,3]
 405    * \param bypass      if non-zero, bypass input buffer and connect input
 406    *                    directly to switched cap SHA input of RxPGA.
 407    */
 408   bool set_adc_buffer_bypass (int which, bool bypass);
 409
 410   /*!
 411    * \brief return the usrp's serial number.
 412    *
 413    * \returns non-zero length string iff successful.
 414    */
 415   std::string serial_number();
 416
 417   /*!
 418    * \brief Write direction register (output enables) for pins that go to daughterboard.
 419    *
 420    * \param which_dboard        [0,1] which d'board
 421    * \param value               value to write into register
 422    * \param mask                which bits of value to write into reg
 423    *
 424    * Each d'board has 16-bits of general purpose i/o.
 425    * Setting the bit makes it an output from the FPGA to the d'board.
 426    *
 427    * This register is initialized based on a value stored in the
 428    * d'board EEPROM.  In general, you shouldn't be using this routine
 429    * without a very good reason.  Using this method incorrectly will
 430    * kill your USRP motherboard and/or daughterboard.
 431    */
 432   bool _write_oe (int which_dboard, int value, int mask);
 433
 434   /*!
 435    * \brief Write daughterboard i/o pin value
 436    *
 437    * \param which_dboard        [0,1] which d'board
 438    * \param value               value to write into register
 439    * \param mask                which bits of value to write into reg
 440    */
 441   bool write_io (int which_dboard, int value, int mask);
 442
 443   /*!
 444    * \brief Read daughterboard i/o pin value
 445    *
 446    * \param which_dboard        [0,1] which d'board
 447    * \returns register value if successful, else READ_FAILED
 448    */
 449   int read_io (int which_dboard);
 450
 451   /*!
 452    * \brief Enable/disable automatic DC offset removal control loop in FPGA
 453    *
 454    * \param bits  which control loops to enable
 455    * \param mask  which \p bits to pay attention to
 456    *
 457    * If the corresponding bit is set, enable the automatic DC
 458    * offset correction control loop.
 459    *
 460    * <pre>
 461    * The 4 low bits are significant:
 462    *
 463    *   ADC0 = (1 << 0)
 464    *   ADC1 = (1 << 1)
 465    *   ADC2 = (1 << 2)
 466    *   ADC3 = (1 << 3)
 467    * </pre>
 468    *
 469    * By default the control loop is enabled on all ADC's.
 470    */
 471   bool set_dc_offset_cl_enable(int bits, int mask);
 472
 473   /*!
 474    * \brief Specify Rx data format.
 475    *
 476    * \param format      format specifier
 477    *
 478    * Rx data format control register
 479    *
 480    *     3                   2                   1
 481    *   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
 482    *  +-----------------------------------------+-+-+---------+-------+
 483    *  |          Reserved (Must be zero)        |B|Q|  WIDTH  | SHIFT |
 484    *  +-----------------------------------------+-+-+---------+-------+
 485    *
 486    *  SHIFT specifies arithmetic right shift [0, 15]
 487    *  WIDTH specifies bit-width of I & Q samples across the USB [1, 16] (not all valid)
 488    *  Q     if set deliver both I & Q, else just I
 489    *  B     if set bypass half-band filter.
 490    *
 491    * Right now the acceptable values are:
 492    *
 493    *   B  Q  WIDTH  SHIFT
 494    *   0  1    16     0
 495    *   0  1     8     8
 496    *
 497    * More valid combos to come.
 498    *
 499    * Default value is 0x00000300  16-bits, 0 shift, deliver both I & Q.
 500    */
 501   bool set_format(unsigned int format);
 502
 503   /*!
 504    * \brief return current format
 505    */
 506   unsigned int format () const;
 507
 508   static unsigned int make_format(int width=16, int shift=0,
 509                                   bool want_q=true, bool bypass_halfband=false);
 510   static int format_width(unsigned int format);
 511   static int format_shift(unsigned int format);
 512   static bool format_want_q(unsigned int format);
 513   static bool format_bypass_halfband(unsigned int format);
 514
 515
 516
 517
 518   bool write_aux_dac (int which_dboard, int which_dac, int value);
 519   int read_aux_adc (int which_dboard, int which_adc);
 520   bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string buf);
 521   std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
 522   bool write_i2c (int i2c_addr, const std::string buf);
 523   std::string read_i2c (int i2c_addr, int len);
 524   bool _write_fpga_reg (int regno, int value);  //< 7-bit regno, 32-bit value
 525   bool _write_fpga_reg_masked (int regno, int value, int mask); //< 7-bit regno, 16-bit value, 16-bit mask
 526   int  _read_fpga_reg (int regno);
 527   bool _write_9862 (int which_codec, int regno, unsigned char value);
 528   int  _read_9862 (int which_codec, int regno) const;
 529
 530   bool _write_spi (int optional_header, int enables, int format, std::string buf);
 531
 532   /*
 533    * \brief Read data from SPI bus peripheral.
 534    *
 535    * \param optional_header     0,1 or 2 bytes to write before buf.
 536    * \param enables             bitmask of peripheral to read. See usrp_spi_defs.h
 537    * \param format              transaction format.  See usrp_spi_defs.h SPI_FMT_*
 538    * \param len                 number of bytes to read.  Must be in [0,64].
 539    * \returns the data read if sucessful, else a zero length string.
 540    *
 541    * Reads are limited to a maximum of 64 bytes.
 542    *
 543    * If \p format specifies that optional_header bytes are present, they
 544    * are written to the peripheral first.  Then \p len bytes are read from
 545    * the peripheral and returned.
 546    */
 547   std::string _read_spi (int optional_header, int enables, int format, int len);
 548 };
 549
 550
 551 // ================================================================
 552 //                      concrete sinks
 553 // ================================================================
 554
 555
 556 GR_SWIG_BLOCK_MAGIC(usrp1,sink_c)
 557
 558 usrp1_sink_c_sptr
 559 usrp1_make_sink_c (int which_board,
 560                    unsigned int interp_rate,
 561                    int nchan,
 562                    int mux,
 563                    int fusb_block_size,
 564                    int fusb_nblocks,
 565                    const std::string fpga_filename,
 566                    const std::string firmware_filename
 567                    ) throw (std::runtime_error);
 568
 569
 570 class usrp1_sink_c : public usrp1_sink_base {
 571  protected:
 572   usrp1_sink_c (int which_board, unsigned int interp_rate,
 573                 int nchan, int mux);
 574
 575  public:
 576   ~usrp1_sink_c ();
 577 };
 578
 579 // ----------------------------------------------------------------
 580
 581 GR_SWIG_BLOCK_MAGIC(usrp1,sink_s)
 582
 583 usrp1_sink_s_sptr
 584 usrp1_make_sink_s (int which_board,
 585                    unsigned int interp_rate,
 586                    int nchan,
 587                    int mux,
 588                    int fusb_block_size,
 589                    int fusb_nblocks,
 590                    const std::string fpga_filename,
 591                    const std::string firmware_filename
 592                    ) throw (std::runtime_error);
 593
 594
 595 class usrp1_sink_s : public usrp1_sink_base {
 596  protected:
 597   usrp1_sink_s (int which_board, unsigned int interp_rate,
 598                 int nchan, int mux);
 599
 600  public:
 601   ~usrp1_sink_s ();
 602 };
 603
 604 // ================================================================
 605 //                      concrete sources
 606 // ================================================================
 607
 608 GR_SWIG_BLOCK_MAGIC(usrp1,source_c)
 609
 610
 611 usrp1_source_c_sptr
 612 usrp1_make_source_c (int which_board,
 613                      unsigned int decim_rate,
 614                      int nchan,
 615                      int mux,
 616                      int mode,
 617                      int fusb_block_size,
 618                      int fusb_nblocks,
 619                      const std::string fpga_filename,
 620                      const std::string firmware_filename
 621                      ) throw (std::runtime_error);
 622
 623 class usrp1_source_c : public usrp1_source_base {
 624  protected:
 625   usrp1_source_c (int which_board, unsigned int decim_rate,
 626                   int nchan, int mux, int mode);
 627
 628  public:
 629   ~usrp1_source_c ();
 630 };
 631
 632 // ----------------------------------------------------------------
 633
 634 GR_SWIG_BLOCK_MAGIC(usrp1,source_s)
 635
 636 usrp1_source_s_sptr
 637 usrp1_make_source_s (int which_board,
 638                      unsigned int decim_rate,
 639                      int nchan,
 640                      int mux,
 641                      int mode,
 642                      int fusb_block_size,
 643                      int fusb_nblocks,
 644                      const std::string fpga_filename,
 645                      const std::string firmware_filename
 646                      ) throw (std::runtime_error);
 647
 648
 649 class usrp1_source_s : public usrp1_source_base {
 650  protected:
 651   usrp1_source_s (int which_board, unsigned int decim_rate,
 652                   int nchan, int mux, int mode);
 653
 654  public:
 655   ~usrp1_source_s ();
 656 };
 657