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

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2008,2009 Free Software Foundation, Inc.
   4  *
   5  * This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation, either version 3 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef INCLUDED_USRP2_H
  20 #define INCLUDED_USRP2_H
  21
  22 #include <boost/shared_ptr.hpp>
  23 #include <boost/utility.hpp>
  24 #include <vector>
  25 #include <complex>
  26 #include <usrp2/rx_sample_handler.h>
  27 #include <usrp2/tune_result.h>
  28 #include <usrp2/mimo_config.h>
  29
  30 /*
  31  * N.B., The interfaces described here are still in flux.
  32  *
  33  * We will keep all the code in the tree up-to-date with regard to changes
  34  * here, but reserve the right to change this on a whim.
  35  */
  36
  37 namespace usrp2 {
  38
  39   /*!
  40    * Structure to hold properties of USRP2 hardware devices.
  41    *
  42    */
  43   struct props
  44   {
  45     std::string addr;
  46     uint16_t hw_rev;
  47     uint8_t fpga_md5sum[16];
  48     uint8_t sw_md5sum[16];
  49   };
  50
  51   typedef std::vector<props> props_vector_t;
  52
  53   /*!
  54    * \brief Search the ethernet for all USRP2s or for a specific USRP2.
  55    *
  56    * \param ifc is the name of the OS ethernet interface (e.g., "eth0")
  57    * \param mac_addr is the MAC address of the desired USRP2, or "" to search for all.
  58    * mac_addr must be either a zero length string, "", or must be of the form
  59    * "01:02:03:04:05:06" or "05:06".
  60    *
  61    * \returns a vector of properties, 1 entry for each matching USRP2 found.
  62    */
  63   props_vector_t find(const std::string &ifc, const std::string &mac_addr="");
  64
  65   class tune_result;
  66
  67   // FIXME: get from firmware include
  68   static const int GPIO_TX_BANK = 0;
  69   static const int GPIO_RX_BANK = 1;
  70
  71   /*!
  72    * \brief standard C++ interface to USRP2
  73    * \ingroup usrp2
  74    */
  75   class usrp2 : boost::noncopyable
  76   {
  77   public:
  78     static const unsigned int MAX_CHAN = 30;
  79
  80     /*!
  81      * Shared pointer to this class
  82      */
  83     typedef boost::shared_ptr<usrp2> sptr;
  84
  85     /*!
  86      * Static function to return an instance of usrp2 as a shared pointer
  87      *
  88      * \param ifc   Network interface name, e.g., "eth0"
  89      * \param addr  Network mac address, e.g., "01:23:45:67:89:ab", "89:ab" or "".
  90      *              If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
  91      *              "" will autoselect a USRP2 if there is only a single one on the local ethernet.
  92      * \param rx_bufsize is the length in bytes of the kernel networking buffer to allocate.
  93      */
  94     static sptr make(const std::string &ifc, const std::string &addr="", size_t rx_bufsize=0);
  95
  96     /*!
  97      * Class destructor
  98      */
  99     ~usrp2();
 100
 101     /*!
 102      * Returns the MAC address associated with this USRP
 103      */
 104     std::string mac_addr();
 105
 106     /*!
 107      * Returns the GbE interface name associated with this USRP
 108      */
 109     std::string interface_name();
 110
 111     /*
 112      * ----------------------------------------------------------------
 113      * Rx configuration and control
 114      * ----------------------------------------------------------------
 115      */
 116
 117     /*!
 118      * Set the rx antenna
 119      */
 120     bool set_rx_antenna(int ant);
 121
 122     /*!
 123      * Set receiver gain
 124      * \param gain in dB (more or less)
 125      */
 126     bool set_rx_gain(double gain);
 127
 128     //! return minimum Rx gain
 129     double rx_gain_min();
 130
 131     //! return maximum Rx gain
 132     double rx_gain_max();
 133
 134     //! return Rx gain db_per_step
 135     double rx_gain_db_per_step();
 136
 137     /*!
 138      * \brief Set receive daughterboard LO offset frequency
 139      */
 140     bool set_rx_lo_offset(double frequency);
 141
 142     /*!
 143      * Set receiver center frequency
 144      */
 145     bool set_rx_center_freq(double frequency, tune_result *result);
 146
 147     //! return minimum Rx center frequency
 148     double rx_freq_min();
 149
 150     //! return maximum Rx center frequency
 151     double rx_freq_max();
 152
 153     /*!
 154      * Set receiver sample rate decimation
 155      */
 156     bool set_rx_decim(int decimation_factor);
 157
 158     //! Return current decimation factor
 159     int rx_decim();
 160
 161     /*!
 162      * Set receiver IQ magnitude scaling
 163      */
 164     bool set_rx_scale_iq(int scale_i, int scale_q);
 165
 166     /*!
 167      * Set received sample format
 168      *
 169      *    domain: complex or real
 170      *      type: floating, fixed point, or raw
 171      *     depth: bits per sample
 172      *
 173      * Sets format over the wire for samples from USRP2.
 174      */
 175     // bool set_rx_format(...);
 176
 177     /*!
 178      * Start streaming receive mode.  USRP2 will send a continuous stream of
 179      * DSP pipeline samples to host.  Call rx_samples(...) to access.
 180      *
 181      * \param channel          Stream channel number (0-30)
 182      * \param items_per_frame  Number of 32-bit items per frame.
 183      */
 184     bool start_rx_streaming(unsigned int channel=0, unsigned int items_per_frame=0);
 185
 186     /*!
 187      * Start streaming receive mode at specified timestamp. USRP2 will send a
 188      * continuous stream of DSP pipeline samples to host. Call rx_samples(...)
 189      * to access.
 190      *
 191      * \param channel          Stream channel number (0-30)
 192      * \param items_per_frame  Number of 32-bit items per frame.
 193      * \param time             Timestamp to start streaming at
 194      */
 195     bool start_rx_streaming_at(unsigned int channel=0, unsigned int items_per_frame=0, unsigned int time=0);
 196
 197     /*!
 198      * Sync to PPS and start streaming receive mode at specified timestamp.
 199      * Just like calling sync_to_pps() and start_rx_streaming_at().
 200      *
 201      * \param channel          Stream channel number (0-30)
 202      * \param items_per_frame  Number of 32-bit items per frame.
 203      * \param time             Timestamp to start streaming at
 204      */
 205     bool sync_and_start_rx_streaming_at(unsigned int channel=0, unsigned int items_per_frame=0, uint32_t time=0);
 206
 207     /*!
 208      * Stop streaming receive mode.
 209      */
 210     bool stop_rx_streaming(unsigned int channel=0);
 211
 212     /*!
 213      * \brief Receive data from the specified channel
 214      * This method is used to receive all data: streaming or discrete.
 215      */
 216     bool rx_samples(unsigned int channel, rx_sample_handler *handler);
 217
 218     /*!
 219      * Returns number of times receive overruns have occurred
 220      */
 221     unsigned int rx_overruns();
 222
 223     /*!
 224      * Returns total number of missing frames from overruns.
 225      */
 226     unsigned int rx_missing();
 227
 228     /*
 229      * ----------------------------------------------------------------
 230      * Tx configuration and control
 231      * ----------------------------------------------------------------
 232      */
 233
 234     /*!
 235      * Set the tx antenna
 236      */
 237     bool set_tx_antenna(int ant);
 238
 239     /*!
 240      * Set transmitter gain
 241      */
 242     bool set_tx_gain(double gain);
 243
 244     //! return minimum Tx gain
 245     double tx_gain_min();
 246
 247     //! return maximum Tx gain
 248     double tx_gain_max();
 249
 250     //! return Tx gain db_per_step
 251     double tx_gain_db_per_step();
 252
 253     /*
 254      * \brief Set transmit daughterboard LO offset frequency
 255      */
 256     bool set_tx_lo_offset(double frequency);
 257
 258     /*!
 259      * Set transmitter center frequency
 260      */
 261     bool set_tx_center_freq(double frequency, tune_result *result);
 262
 263     //! return minimum Tx center frequency
 264     double tx_freq_min();
 265
 266     //! return maximum Tx center frequency
 267     double tx_freq_max();
 268
 269     /*!
 270      * Set transmitter sample rate interpolation
 271      */
 272     bool set_tx_interp(int interpolation_factor);
 273
 274     //! Return current interpolation factor
 275     int tx_interp();
 276
 277     /*
 278      * \brief Calculate default scale_iq for given interpolation rate
 279      */
 280     void default_tx_scale_iq(int interpolation_factor, int *scale_i, int *scale_q);
 281
 282     /*!
 283      * Set transmit IQ magnitude scaling
 284      */
 285     bool set_tx_scale_iq(int scale_i, int scale_q);
 286
 287     /*!
 288      * Set transmit sample format
 289      *
 290      *    domain: complex or real
 291      *      type: floating, fixed point, or raw
 292      *     depth: bits per sample
 293      *
 294      * Sets format over the wire for samples to USRP2.
 295      */
 296     // bool set_tx_format(...);
 297
 298     /*!
 299      * \brief transmit complex<float> samples to USRP2
 300      *
 301      * \param channel specifies the channel to send them to
 302      * \param samples are the samples to transmit.  They should be in the range [-1.0, +1.0]
 303      * \param nsamples is the number of samples to transmit
 304      * \param metadata provides the timestamp and flags
 305      *
 306      * The complex<float> samples are converted to the appropriate
 307      * "on the wire" representation, depending on the current USRP2
 308      * configuration.  Typically, this is big-endian 16-bit I & Q.
 309      */
 310     bool tx_32fc(unsigned int channel,
 311                  const std::complex<float> *samples,
 312                  size_t nsamples,
 313                  const tx_metadata *metadata);
 314
 315     /*!
 316      * \brief transmit complex<int16_t> samples to USRP2
 317      *
 318      * \param channel specifies the channel to send them to
 319      * \param samples are the samples to transmit
 320      * \param nsamples is the number of samples to transmit
 321      * \param metadata provides the timestamp and flags
 322      *
 323      * The complex<int16_t> samples are converted to the appropriate
 324      * "on the wire" representation, depending on the current USRP2
 325      * configuration.  Typically, this is big-endian 16-bit I & Q.
 326      */
 327     bool tx_16sc(unsigned int channel,
 328                  const std::complex<int16_t> *samples,
 329                  size_t nsamples,
 330                  const tx_metadata *metadata);
 331
 332     /*!
 333      * \brief transmit raw uint32_t data items to USRP2
 334      *
 335      * The caller is responsible for ensuring that the items are
 336      * formatted appropriately for the USRP2 and its configuration.
 337      * This method is used primarily by the system itself.  Users
 338      * should call tx_32fc or tx_16sc instead.
 339      *
 340      * \param channel specifies the channel to send them to
 341      * \param items are the data items to transmit
 342      * \param nitems is the number of items to transmit
 343      * \param metadata provides the timestamp and flags
 344      */
 345     bool tx_raw(unsigned int channel,
 346                 const uint32_t *items,
 347                 size_t nitems,
 348                 const tx_metadata *metadata);
 349
 350     /*
 351      * ----------------------------------------------------------------
 352      *  miscellaneous methods
 353      * ----------------------------------------------------------------
 354      */
 355
 356     /*!
 357      * \brief MIMO configuration
 358      *
 359      * \param flags from usrp2_mimo_config.h
 360      *
 361      * <pre>
 362      *   one of these:
 363      *
 364      *     MC_WE_DONT_LOCK
 365      *     MC_WE_LOCK_TO_SMA
 366      *     MC_WE_LOCK_TO_MIMO
 367      *
 368      *   and optionally this:
 369      *
 370      *     MC_PROVIDE_CLK_TO_MIMO
 371      * </pre>
 372      */
 373     bool config_mimo(int flags);
 374
 375
 376     //! Get frequency of master oscillator in Hz
 377     bool fpga_master_clock_freq(long *freq);
 378
 379     // Get Sampling rate of A/D converter in Hz
 380     bool adc_rate(long *rate);
 381
 382     // Get Sampling rate of D/A converter in Hz
 383     bool dac_rate(long *rate);
 384
 385     /*!
 386      * \brief Get Tx daughterboard ID
 387      *
 388      * \param[out] dbid returns the daughterboard id.
 389      *
 390      * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
 391      * -2 if invalid EEPROM on daughterboard.
 392      */
 393     bool tx_daughterboard_id(int *dbid);
 394
 395     /*!
 396      * \brief Get Rx daughterboard ID
 397      *
 398      * \param[out] dbid returns the daughterboard id.
 399      *
 400      * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
 401      * -2 if invalid EEPROM on daughterboard.
 402      */
 403     bool rx_daughterboard_id(int *dbid);
 404
 405     /*
 406      * ----------------------------------------------------------------
 407      *  Low level methods
 408      * ----------------------------------------------------------------
 409      */
 410
 411     /*!
 412      * Burn new mac address into EEPROM on USRP2
 413      *
 414      * \param new_addr  Network mac address, e.g., "01:23:45:67:89:ab" or "89:ab".
 415      *                  If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
 416      */
 417     bool burn_mac_addr(const std::string &new_addr);
 418
 419     /*!
 420      * Reset master time to 0 at next PPS edge
 421      */
 422     bool sync_to_pps();
 423
 424     /*!
 425      * Reset master time to 0 at every PPS edge
 426      */
 427     bool sync_every_pps(bool enable);
 428
 429     /*!
 430      * Read memory from Wishbone bus as 32-bit words.  Handles endian swapping if needed.
 431      *
 432      * \param addr      32-bit aligned address.  Only the lower 16-bits are significant.
 433      * \param words     Number of 32-bit words
 434      *
 435      * \returns         Vector of 32-bit read values
 436      *
 437      * WARNING: Attempts to read memory from addresses that do not correspond to RAM or
 438      * memory-mapped peripherals may cause the USRP2 to hang, requiring a power cycle.
 439      *
 440      */
 441     std::vector<uint32_t> peek32(uint32_t addr, uint32_t words);
 442
 443     /*!
 444      * Write memory to Wishbone bus as 32-bit words.  Handles endian swapping if needed.
 445      *
 446      * \param addr      32-bit aligned address.  Only the lower 16-bits are significant
 447      * \param data      Vector of 32-bit values to write.
 448      *
 449      * \returns true iff successful
 450      *
 451      * WARNING: Attempts to read memory from addresses that do not correspond to RAM or
 452      * memory-mapped peripherals may cause the USRP2 to hang, requiring a power cycle.
 453      *
 454      */
 455     bool poke32(uint32_t addr, const std::vector<uint32_t> &data);
 456
 457     /*!
 458      * Set daughterboard GPIO data direction register.
 459      *
 460      * \param bank      GPIO_TX_BANK or GPIO_RX_BANK
 461      * \param value     16-bits, 0=FPGA input, 1=FPGA output
 462      * \param mask      16-bits, 0=ignore, 1=set
 463      *
 464      * \returns true iff successful
 465      *
 466      * WARNING: Improper usage of this function may result in damage to the USRP2
 467      *
 468      */
 469     bool set_gpio_ddr(int bank, uint16_t value, uint16_t mask);
 470
 471     /*!
 472      * Set daughterboard GPIO output selection register.  For those GPIO pins that
 473      * are configured as outputs in the DDR, this settings configures the source
 474      * of the pin value.
 475      *
 476      * \param bank      GPIO_TX_BANK or GPIO_RX_BANK
 477      * \param sels      Exactly 16 character MSB->LSB string. For each position:
 478      *                    '.' = ignore this bit, i.e., leave current value
 479      *                    'a' = Output ATR value
 480      *                    's' = Output host software controlled value
 481      *                    '0' = Output FPGA debug bus 0 value
 482      *                    '1' = Output FPGA debug bus 1 value
 483      *
 484      * \returns true iff successful
 485      *
 486      * WARNING: Improper usage of this function may result in damage to the USRP2
 487      *
 488      */
 489     bool set_gpio_sels(int bank, std::string sels);
 490
 491     /*!
 492      * Set daughterboard GPIO pin values.
 493      *
 494      * \param bank     GPIO_TX_BANK or GPIO_RX_BANK
 495      * \param value    16 bits, 0=low, 1=high
 496      * \param mask     16 bits, 0=ignore, 1=set
 497      *
 498      * \returns true iff successful
 499      *
 500      * WARNING: Improper usage of this function may result in damage to the USRP2
 501      *
 502      */
 503     bool write_gpio(int bank, uint16_t value, uint16_t mask);
 504
 505     /*!
 506      * Read daughterboard GPIO pin values
 507      *
 508      * \param bank     GPIO_TX_BANK or GPIO_RX_BANK
 509      * \param value    pointer to uint16_t to hold read results
 510      *
 511      * \returns true iff successful
 512      *
 513      */
 514     bool read_gpio(int bank, uint16_t *value);
 515
 516     /*!
 517      * Set GPIO streaming mode
 518      *
 519      * Individually enables streaming GPIO pins through LSBs of DSP
 520      * samples.
 521      *
 522      * On receive, io_rx[15] replaces I[0], io_rx[14] replaces Q[0]
 523      * On transmit, I[0] maps to io_tx[15], Q[0] maps to io_tx[14]
 524      * (Transmit streaming is not yet implemented.)
 525      *
 526      * The selected GPIO pins must have been set as inputs or outputs
 527      * and, for transmit, set to software control.
 528      *
 529      * When enabled, the replaced DSP sample LSBs become 0.
 530      *
 531      * \param bank     GPIO_TX_BANK or GPIO_RX_BANK
 532      * \param enable   enable[0] controls I channel LSB
 533      *                 enable[1] controls Q channel LSB
 534      *
 535      * \returns true iff successful
 536      *
 537      * WARNING: Improper usage of this function may result in damage to the USRP2
 538      *
 539      */
 540     bool enable_gpio_streaming(int bank, int enable);
 541
 542 #if 0   // not yet implemented
 543     /*!
 544      * \brief Write EEPROM on motherboard or any daughterboard.
 545      * \param i2c_addr          I2C bus address of EEPROM
 546      * \param eeprom_offset     byte offset in EEPROM to begin writing
 547      * \param buf               the data to write
 548      * \returns true iff sucessful
 549      */
 550     bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string &buf);
 551
 552     /*!
 553      * \brief Read EEPROM on motherboard or any daughterboard.
 554      * \param i2c_addr          I2C bus address of EEPROM
 555      * \param eeprom_offset     byte offset in EEPROM to begin reading
 556      * \param len               number of bytes to read
 557      * \returns the data read if successful, else a zero length string.
 558      */
 559     std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
 560
 561     /*!
 562      * \brief Write to I2C peripheral
 563      * \param i2c_addr          I2C bus address (7-bits)
 564      * \param buf               the data to write
 565      * \returns true iff successful
 566      * Writes are limited to a maximum of of 64 bytes.
 567      */
 568     bool write_i2c (int i2c_addr, const std::string &buf);
 569
 570     /*!
 571      * \brief Read from I2C peripheral
 572      * \param i2c_addr          I2C bus address (7-bits)
 573      * \param len               number of bytes to read
 574      * \returns the data read if successful, else a zero length string.
 575      * Reads are limited to a maximum of 64 bytes.
 576      */
 577     std::string read_i2c (int i2c_addr, int len);
 578
 579     /*!
 580      * \brief Write data to SPI bus peripheral.
 581      *
 582      * \param optional_header   0,1 or 2 bytes to write before buf.
 583      * \param enables           bitmask of peripherals to write. See usrp_spi_defs.h
 584      * \param format            transaction format.  See usrp_spi_defs.h SPI_FMT_*
 585      * \param buf               the data to write
 586      * \returns true iff successful
 587      * Writes are limited to a maximum of 64 bytes.
 588      *
 589      * If \p format specifies that optional_header bytes are present, they are
 590      * written to the peripheral immediately prior to writing \p buf.
 591      */
 592     bool write_spi (int optional_header, int enables, int format, const std::string &buf);
 593
 594     /*
 595      * \brief Read data from SPI bus peripheral.
 596      *
 597      * \param optional_header   0,1 or 2 bytes to write before buf.
 598      * \param enables           bitmask of peripheral to read. See usrp_spi_defs.h
 599      * \param format            transaction format.  See usrp_spi_defs.h SPI_FMT_*
 600      * \param len               number of bytes to read.  Must be in [0,64].
 601      * \returns the data read if sucessful, else a zero length string.
 602      *
 603      * Reads are limited to a maximum of 64 bytes.
 604      *
 605      * If \p format specifies that optional_header bytes are present, they
 606      * are written to the peripheral first.  Then \p len bytes are read from
 607      * the peripheral and returned.
 608      */
 609     std::string read_spi (int optional_header, int enables, int format, int len);
 610 #endif
 611
 612
 613     class impl;         // implementation details
 614
 615   private:
 616     // Static function to retrieve or create usrp2 instance
 617     static sptr find_existing_or_make_new(const std::string &ifc, props *p, size_t rx_bufsize);
 618
 619     // Only class members can instantiate this class
 620     usrp2(const std::string &ifc, props *p, size_t rx_bufsize);
 621
 622     // All private state is held in opaque pointer
 623     std::auto_ptr<impl> d_impl;
 624   };
 625
 626 };
 627
 628 std::ostream& operator<<(std::ostream &os, const usrp2::props &x);
 629
 630
 631 #endif /* INCLUDED_USRP2_H */