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
  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   class usrp2 : boost::noncopyable
  68   {
  69   public:
  70     static const unsigned int MAX_CHAN = 30;
  71
  72     /*!
  73      * Shared pointer to this class
  74      */
  75     typedef boost::shared_ptr<usrp2> sptr;
  76
  77     /*!
  78      * Static function to return an instance of usrp2 as a shared pointer
  79      *
  80      * \param ifc   Network interface name, e.g., "eth0"
  81      * \param addr  Network mac address, e.g., "01:23:45:67:89:ab", "89:ab" or "".
  82      *              If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
  83      *              "" will autoselect a USRP2 if there is only a single one on the local ethernet.
  84      */
  85     static sptr make(const std::string &ifc, const std::string &addr="");
  86
  87     /*!
  88      * Class destructor
  89      */
  90     ~usrp2();
  91
  92     /*!
  93      * Returns the MAC address associated with this USRP
  94      */
  95     std::string mac_addr();
  96
  97     /*!
  98      * Returns the GbE interface name associated with this USRP
  99      */
 100     std::string ifc_name();
 101
 102     /*
 103      * ----------------------------------------------------------------
 104      * Rx configuration and control
 105      * ----------------------------------------------------------------
 106      */
 107
 108     /*!
 109      * Set receiver gain
 110      * \param gain in dB (more or less)
 111      */
 112     bool set_rx_gain(double gain);
 113
 114     //! return minimum Rx gain
 115     double rx_gain_min();
 116
 117     //! return maximum Rx gain
 118     double rx_gain_max();
 119
 120     //! return Rx gain db_per_step
 121     double rx_gain_db_per_step();
 122
 123     /*!
 124      * \brief Set receive daughterboard LO offset frequency
 125      */
 126     bool set_rx_lo_offset(double frequency);
 127
 128     /*!
 129      * Set receiver center frequency
 130      */
 131     bool set_rx_center_freq(double frequency, tune_result *result);
 132
 133     //! return minimum Rx center frequency
 134     double rx_freq_min();
 135
 136     //! return maximum Rx center frequency
 137     double rx_freq_max();
 138
 139     /*!
 140      * Set receiver sample rate decimation
 141      */
 142     bool set_rx_decim(int decimation_factor);
 143
 144     //! Return current decimation factor
 145     int rx_decim();
 146
 147     /*!
 148      * Set receiver IQ magnitude scaling
 149      */
 150     bool set_rx_scale_iq(int scale_i, int scale_q);
 151
 152     /*!
 153      * Set received sample format
 154      *
 155      *    domain: complex or real
 156      *      type: floating, fixed point, or raw
 157      *     depth: bits per sample
 158      *
 159      * Sets format over the wire for samples from USRP2.
 160      */
 161     // bool set_rx_format(...);
 162
 163     /*!
 164      * Start streaming receive mode.  USRP2 will send a continuous stream of
 165      * DSP pipeline samples to host.  Call rx_samples(...) to access.
 166      *
 167      * \param channel          Stream channel number (0-30)
 168      * \param items_per_frame  Number of 32-bit items per frame.
 169      */
 170     bool start_rx_streaming(unsigned int channel=0, unsigned int items_per_frame=0);
 171
 172     /*!
 173      * Stop streaming receive mode.
 174      */
 175     bool stop_rx_streaming(unsigned int channel=0);
 176
 177     /*!
 178      * \brief Receive data from the specified channel
 179      * This method is used to receive all data: streaming or discrete.
 180      */
 181     bool rx_samples(unsigned int channel, rx_sample_handler *handler);
 182
 183     /*!
 184      * Returns number of times receive overruns have occurred
 185      */
 186     unsigned int rx_overruns();
 187
 188     /*!
 189      * Returns total number of missing frames from overruns.
 190      */
 191     unsigned int rx_missing();
 192
 193     /*
 194      * ----------------------------------------------------------------
 195      * Tx configuration and control
 196      * ----------------------------------------------------------------
 197      */
 198
 199     /*!
 200      * Set transmitter gain
 201      */
 202     bool set_tx_gain(double gain);
 203
 204     //! return minimum Tx gain
 205     double tx_gain_min();
 206
 207     //! return maximum Tx gain
 208     double tx_gain_max();
 209
 210     //! return Tx gain db_per_step
 211     double tx_gain_db_per_step();
 212
 213     /*
 214      * \brief Set transmit daughterboard LO offset frequency
 215      */
 216     bool set_tx_lo_offset(double frequency);
 217
 218     /*!
 219      * Set transmitter center frequency
 220      */
 221     bool set_tx_center_freq(double frequency, tune_result *result);
 222
 223     //! return minimum Tx center frequency
 224     double tx_freq_min();
 225
 226     //! return maximum Tx center frequency
 227     double tx_freq_max();
 228
 229     /*!
 230      * Set transmitter sample rate interpolation
 231      */
 232     bool set_tx_interp(int interpolation_factor);
 233
 234     //! Return current interpolation factor
 235     int tx_interp();
 236
 237     /*
 238      * \brief Calculate default scale_iq for given interpolation rate
 239      */
 240     void default_tx_scale_iq(int interpolation_factor, int *scale_i, int *scale_q);
 241
 242     /*!
 243      * Set transmit IQ magnitude scaling
 244      */
 245     bool set_tx_scale_iq(int scale_i, int scale_q);
 246
 247     /*!
 248      * Set transmit sample format
 249      *
 250      *    domain: complex or real
 251      *      type: floating, fixed point, or raw
 252      *     depth: bits per sample
 253      *
 254      * Sets format over the wire for samples to USRP2.
 255      */
 256     // bool set_tx_format(...);
 257
 258     /*!
 259      * \brief transmit complex<float> samples to USRP2
 260      *
 261      * \param channel specifies the channel to send them to
 262      * \param samples are the samples to transmit.  They should be in the range [-1.0, +1.0]
 263      * \param nsamples is the number of samples to transmit
 264      * \param metadata provides the timestamp and flags
 265      *
 266      * The complex<float> samples are converted to the appropriate
 267      * "on the wire" representation, depending on the current USRP2
 268      * configuration.  Typically, this is big-endian 16-bit I & Q.
 269      */
 270     bool tx_32fc(unsigned int channel,
 271                  const std::complex<float> *samples,
 272                  size_t nsamples,
 273                  const tx_metadata *metadata);
 274
 275     /*!
 276      * \brief transmit complex<int16_t> samples to USRP2
 277      *
 278      * \param channel specifies the channel to send them to
 279      * \param samples are the samples to transmit
 280      * \param nsamples is the number of samples to transmit
 281      * \param metadata provides the timestamp and flags
 282      *
 283      * The complex<int16_t> samples are converted to the appropriate
 284      * "on the wire" representation, depending on the current USRP2
 285      * configuration.  Typically, this is big-endian 16-bit I & Q.
 286      */
 287     bool tx_16sc(unsigned int channel,
 288                  const std::complex<int16_t> *samples,
 289                  size_t nsamples,
 290                  const tx_metadata *metadata);
 291
 292     /*!
 293      * \brief transmit raw uint32_t data items to USRP2
 294      *
 295      * The caller is responsible for ensuring that the items are
 296      * formatted appropriately for the USRP2 and its configuration.
 297      * This method is used primarily by the system itself.  Users
 298      * should call tx_32fc or tx_16sc instead.
 299      *
 300      * \param channel specifies the channel to send them to
 301      * \param items are the data items to transmit
 302      * \param nitems is the number of items to transmit
 303      * \param metadata provides the timestamp and flags
 304      */
 305     bool tx_raw(unsigned int channel,
 306                 const uint32_t *items,
 307                 size_t nitems,
 308                 const tx_metadata *metadata);
 309
 310     /*
 311      * ----------------------------------------------------------------
 312      *  miscellaneous methods
 313      * ----------------------------------------------------------------
 314      */
 315
 316     /*!
 317      * \brief MIMO configuration
 318      *
 319      * \param flags from usrp2_mimo_config.h
 320      *
 321      * <pre>
 322      *   one of these:
 323      *
 324      *     MC_WE_DONT_LOCK
 325      *     MC_WE_LOCK_TO_SMA
 326      *     MC_WE_LOCK_TO_MIMO
 327      *
 328      *   and optionally this:
 329      *
 330      *     MC_PROVIDE_CLK_TO_MIMO
 331      * </pre>
 332      */
 333     bool config_mimo(int flags);
 334
 335
 336     //! Get frequency of master oscillator in Hz
 337     bool fpga_master_clock_freq(long *freq);
 338
 339     // Get Sampling rate of A/D converter in Hz
 340     bool adc_rate(long *rate);
 341
 342     // Get Sampling rate of D/A converter in Hz
 343     bool dac_rate(long *rate);
 344
 345     /*!
 346      * \brief Get Tx daughterboard ID
 347      *
 348      * \param[out] dbid returns the daughterboard id.
 349      *
 350      * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
 351      * -2 if invalid EEPROM on daughterboard.
 352      */
 353     bool tx_daughterboard_id(int *dbid);
 354
 355     /*!
 356      * \brief Get Rx daughterboard ID
 357      *
 358      * \param[out] dbid returns the daughterboard id.
 359      *
 360      * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
 361      * -2 if invalid EEPROM on daughterboard.
 362      */
 363     bool rx_daughterboard_id(int *dbid);
 364
 365     /*
 366      * ----------------------------------------------------------------
 367      *  Low level methods
 368      * ----------------------------------------------------------------
 369      */
 370
 371     /*!
 372      * Burn new mac address into EEPROM on USRP2
 373      *
 374      * \param new_addr  Network mac address, e.g., "01:23:45:67:89:ab" or "89:ab".
 375      *                  If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
 376      */
 377     bool burn_mac_addr(const std::string &new_addr);
 378
 379     /*!
 380      * Reset master time to 0 at next PPS edge
 381      */
 382     bool sync_to_pps();
 383
 384     /*!
 385      * Reset master time to 0 at every PPS edge
 386      */
 387     bool sync_every_pps(bool enable);
 388
 389     /*!
 390      * Read memory from Wishbone bus as 32-bit words.  Handles endian swapping if needed.
 391      *
 392      * \param addr      32-bit aligned address.  Only the lower 16-bits are significant.
 393      * \param words     Number of 32-bit words
 394      *
 395      * \returns         Vector of 32-bit read values
 396      *
 397      * WARNING: Attempts to read memory from addresses that do not correspond to RAM or
 398      * memory-mapped peripherals may cause the USRP2 to hang, requiring a power cycle.
 399      *
 400      */
 401     std::vector<uint32_t> peek32(uint32_t addr, uint32_t words);
 402
 403     /*!
 404      * Write memory to Wishbone bus as 32-bit words.  Handles endian swapping if needed.
 405      *
 406      * \param addr      32-bit aligned address.  Only the lower 16-bits are significant
 407      * \param data      Vector of 32-bit values to write.
 408      *
 409      * \returns true iff successful
 410      *
 411      * WARNING: Attempts to read memory from addresses that do not correspond to RAM or
 412      * memory-mapped peripherals may cause the USRP2 to hang, requiring a power cycle.
 413      *
 414      */
 415     bool poke32(uint32_t addr, const std::vector<uint32_t> &data);
 416
 417 #if 0   // not yet implemented
 418     /*!
 419      * \brief Write EEPROM on motherboard or any daughterboard.
 420      * \param i2c_addr          I2C bus address of EEPROM
 421      * \param eeprom_offset     byte offset in EEPROM to begin writing
 422      * \param buf               the data to write
 423      * \returns true iff sucessful
 424      */
 425     bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string &buf);
 426
 427     /*!
 428      * \brief Read EEPROM on motherboard or any daughterboard.
 429      * \param i2c_addr          I2C bus address of EEPROM
 430      * \param eeprom_offset     byte offset in EEPROM to begin reading
 431      * \param len               number of bytes to read
 432      * \returns the data read if successful, else a zero length string.
 433      */
 434     std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
 435
 436     /*!
 437      * \brief Write to I2C peripheral
 438      * \param i2c_addr          I2C bus address (7-bits)
 439      * \param buf               the data to write
 440      * \returns true iff successful
 441      * Writes are limited to a maximum of of 64 bytes.
 442      */
 443     bool write_i2c (int i2c_addr, const std::string &buf);
 444
 445     /*!
 446      * \brief Read from I2C peripheral
 447      * \param i2c_addr          I2C bus address (7-bits)
 448      * \param len               number of bytes to read
 449      * \returns the data read if successful, else a zero length string.
 450      * Reads are limited to a maximum of 64 bytes.
 451      */
 452     std::string read_i2c (int i2c_addr, int len);
 453
 454     /*!
 455      * \brief Write data to SPI bus peripheral.
 456      *
 457      * \param optional_header   0,1 or 2 bytes to write before buf.
 458      * \param enables           bitmask of peripherals to write. See usrp_spi_defs.h
 459      * \param format            transaction format.  See usrp_spi_defs.h SPI_FMT_*
 460      * \param buf               the data to write
 461      * \returns true iff successful
 462      * Writes are limited to a maximum of 64 bytes.
 463      *
 464      * If \p format specifies that optional_header bytes are present, they are
 465      * written to the peripheral immediately prior to writing \p buf.
 466      */
 467     bool write_spi (int optional_header, int enables, int format, const std::string &buf);
 468
 469     /*
 470      * \brief Read data from SPI bus peripheral.
 471      *
 472      * \param optional_header   0,1 or 2 bytes to write before buf.
 473      * \param enables           bitmask of peripheral to read. See usrp_spi_defs.h
 474      * \param format            transaction format.  See usrp_spi_defs.h SPI_FMT_*
 475      * \param len               number of bytes to read.  Must be in [0,64].
 476      * \returns the data read if sucessful, else a zero length string.
 477      *
 478      * Reads are limited to a maximum of 64 bytes.
 479      *
 480      * If \p format specifies that optional_header bytes are present, they
 481      * are written to the peripheral first.  Then \p len bytes are read from
 482      * the peripheral and returned.
 483      */
 484     std::string read_spi (int optional_header, int enables, int format, int len);
 485 #endif
 486
 487
 488     class impl;         // implementation details
 489
 490   private:
 491     // Static function to retrieve or create usrp2 instance
 492     static sptr find_existing_or_make_new(const std::string &ifc, props *p);
 493
 494     // Only class members can instantiate this class
 495     usrp2(const std::string &ifc, props *p);
 496
 497     // All private state is held in opaque pointer
 498     std::auto_ptr<impl> d_impl;
 499   };
 500
 501 };
 502
 503 std::ostream& operator<<(std::ostream &os, const usrp2::props &x);
 504
 505
 506 #endif /* INCLUDED_USRP2_H */