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

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2008 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 <iosfwd>
  27 #include <usrp2/rx_sample_handler.h>
  28 #include <usrp2/tune_result.h>
  29
  30
  31 /*
  32  * N.B., The interfaces described here are still in flux.
  33  *
  34  * We will keep all the code in the tree up-to-date with regard to changes
  35  * here, but reserve the right to change this on a whim.
  36  */
  37
  38 namespace usrp2 {
  39
  40   /*!
  41    * Structure to hold properties of USRP2 hardware devices.
  42    *
  43    */
  44   struct props
  45   {
  46     std::string addr;
  47     uint16_t hw_rev;
  48     uint8_t fpga_md5sum[16];
  49     uint8_t sw_md5sum[16];
  50   };
  51
  52   typedef std::vector<props> props_vector_t;
  53
  54   /*!
  55    * \brief Search the ethernet for all USRP2s or for a specific USRP2.
  56    *
  57    * \param ifc is the name of the OS ethernet interface (e.g., "eth0")
  58    * \param mac_addr is the MAC address of the desired USRP2, or "" to search for all.
  59    * mac_addr must be either a zero length string, "", or must be of the form
  60    * "01:02:03:04:05:06" or "05:06".
  61    *
  62    * \returns a vector of properties, 1 entry for each matching USRP2 found.
  63    */
  64   props_vector_t find(const std::string &ifc, const std::string &mac_addr="");
  65
  66   class tune_result;
  67
  68   class usrp2 : boost::noncopyable
  69   {
  70   public:
  71     static const unsigned int MAX_CHAN = 30;
  72
  73     /*!
  74      * Shared pointer to this class
  75      */
  76     typedef boost::shared_ptr<usrp2> sptr;
  77
  78     /*!
  79      * Static function to return an instance of usrp2 as a shared pointer
  80      *
  81      * \param ifc   Network interface name, e.g., "eth0"
  82      * \param addr  Network mac address, e.g., "01:23:45:67:89:ab", "89:ab" or "".
  83      *              If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
  84      *              "" will autoselect a USRP2 if there is only a single one on the local ethernet.
  85      */
  86     static sptr make(const std::string &ifc, const std::string &addr="");
  87
  88     /*!
  89      * Class destructor
  90      */
  91     ~usrp2();
  92
  93     /*!
  94      * Returns the MAC address associated with this USRP
  95      */
  96     std::string mac_addr();
  97
  98     /*
  99      * ----------------------------------------------------------------
 100      * Rx configuration and control
 101      * ----------------------------------------------------------------
 102      */
 103
 104     /*!
 105      * Set receiver gain
 106      * \param gain in dB (more or less)
 107      */
 108     bool set_rx_gain(double gain);
 109
 110     //! return minimum Rx gain
 111     double rx_gain_min();
 112
 113     //! return maximum Rx gain
 114     double rx_gain_max();
 115
 116     //! return Rx gain db_per_step
 117     double rx_gain_db_per_step();
 118
 119     /*!
 120      * Set receiver center frequency
 121      */
 122     bool set_rx_center_freq(double frequency, tune_result *result);
 123
 124     //! return minimum Rx center frequency
 125     double rx_freq_min();
 126
 127     //! return maximum Rx center frequency
 128     double rx_freq_max();
 129
 130     /*!
 131      * Set receiver sample rate decimation
 132      */
 133     bool set_rx_decim(int decimation_factor);
 134
 135     /*!
 136      * Set receiver IQ magnitude scaling
 137      */
 138     bool set_rx_scale_iq(int scale_i, int scale_q);
 139
 140     /*!
 141      * Set received sample format
 142      *
 143      *    domain: complex or real
 144      *      type: floating, fixed point, or raw
 145      *     depth: bits per sample
 146      *
 147      * Sets format over the wire for samples from USRP2.
 148      */
 149     // bool set_rx_format(...);
 150
 151     /*!
 152      * Start streaming receive mode.  USRP2 will send a continuous stream of
 153      * DSP pipeline samples to host.  Call rx_samples(...) to access.
 154      *
 155      * \param channel          Stream channel number (0-30)
 156      * \param items_per_frame  Number of 32-bit items per frame.
 157      */
 158     bool start_rx_streaming(unsigned int channel=0, unsigned int items_per_frame=0);
 159
 160     /*!
 161      * Stop streaming receive mode.
 162      */
 163     bool stop_rx_streaming(unsigned int channel=0);
 164
 165     /*!
 166      * \brief Receive data from the specified channel
 167      * This method is used to receive all data: streaming or discrete.
 168      */
 169     bool rx_samples(unsigned int channel, rx_sample_handler *handler);
 170
 171     /*!
 172      * Returns number of times receive overruns have occurred
 173      */
 174     unsigned int rx_overruns();
 175
 176     /*!
 177      * Returns total number of missing frames from overruns.
 178      */
 179     unsigned int rx_missing();
 180
 181     /*
 182      * ----------------------------------------------------------------
 183      * Tx configuration and control
 184      * ----------------------------------------------------------------
 185      */
 186
 187     /*!
 188      * Set transmitter gain
 189      */
 190     bool set_tx_gain(double gain);
 191
 192     //! return minimum Tx gain
 193     double tx_gain_min();
 194
 195     //! return maximum Tx gain
 196     double tx_gain_max();
 197
 198     //! return Tx gain db_per_step
 199     double tx_gain_db_per_step();
 200
 201     /*!
 202      * Set transmitter center frequency
 203      */
 204     bool set_tx_center_freq(double frequency, tune_result *result);
 205
 206     //! return minimum Tx center frequency
 207     double tx_freq_min();
 208
 209     //! return maximum Tx center frequency
 210     double tx_freq_max();
 211
 212     /*!
 213      * Set transmitter sample rate interpolation
 214      */
 215     bool set_tx_interp(int interpolation_factor);
 216
 217     /*!
 218      * Set transmit IQ magnitude scaling
 219      */
 220     bool set_tx_scale_iq(int scale_i, int scale_q);
 221
 222     /*!
 223      * Set transmit sample format
 224      *
 225      *    domain: complex or real
 226      *      type: floating, fixed point, or raw
 227      *     depth: bits per sample
 228      *
 229      * Sets format over the wire for samples to USRP2.
 230      */
 231     // bool set_tx_format(...);
 232
 233     /*!
 234      * \brief transmit complex<float> samples to USRP2
 235      *
 236      * \param channel specifies the channel to send them to
 237      * \param samples are the samples to transmit.  They should be in the range [-1.0, +1.0]
 238      * \param nsamples is the number of samples to transmit
 239      * \param metadata provides the timestamp and flags
 240      *
 241      * The complex<float> samples are converted to the appropriate
 242      * "on the wire" representation, depending on the current USRP2
 243      * configuration.  Typically, this is big-endian 16-bit I & Q.
 244      */
 245     bool tx_32fc(unsigned int channel,
 246                  const std::complex<float> *samples,
 247                  size_t nsamples,
 248                  const tx_metadata *metadata);
 249
 250     /*!
 251      * \brief transmit complex<int16_t> samples to USRP2
 252      *
 253      * \param channel specifies the channel to send them to
 254      * \param samples are the samples to transmit
 255      * \param nsamples is the number of samples to transmit
 256      * \param metadata provides the timestamp and flags
 257      *
 258      * The complex<int16_t> samples are converted to the appropriate
 259      * "on the wire" representation, depending on the current USRP2
 260      * configuration.  Typically, this is big-endian 16-bit I & Q.
 261      */
 262     bool tx_16sc(unsigned int channel,
 263                  const std::complex<int16_t> *samples,
 264                  size_t nsamples,
 265                  const tx_metadata *metadata);
 266
 267     /*!
 268      * \brief transmit raw uint32_t data items to USRP2
 269      *
 270      * The caller is responsible for ensuring that the items are
 271      * formatted appropriately for the USRP2 and its configuration.
 272      * This method is used primarily by the system itself.  Users
 273      * should call tx_32fc or tx_16sc instead.
 274      *
 275      * \param channel specifies the channel to send them to
 276      * \param items are the data items to transmit
 277      * \param nitems is the number of items to transmit
 278      * \param metadata provides the timestamp and flags
 279      */
 280     bool tx_raw(unsigned int channel,
 281                 const uint32_t *items,
 282                 size_t nitems,
 283                 const tx_metadata *metadata);
 284
 285     /*
 286      * ----------------------------------------------------------------
 287      *  miscellaneous methods
 288      * ----------------------------------------------------------------
 289      */
 290
 291     /*!
 292      * \brief MIMO configuration
 293      *
 294      * \param flags from usrp2_mimo_config.h
 295      *
 296      * <pre>
 297      *   one of these:
 298      *
 299      *     MC_WE_DONT_LOCK
 300      *     MC_WE_LOCK_TO_SMA
 301      *     MC_WE_LOCK_TO_MIMO
 302      *
 303      *   and optionally this:
 304      *
 305      *     MC_PROVIDE_CLK_TO_MIMO
 306      * </pre>
 307      */
 308     bool config_mimo(int flags);
 309
 310
 311     //! Get frequency of master oscillator in Hz
 312     bool fpga_master_clock_freq(long *freq);
 313
 314     // Get Sampling rate of A/D converter in Hz
 315     bool adc_rate(long *rate);
 316
 317     // Get Sampling rate of D/A converter in Hz
 318     bool dac_rate(long *rate);
 319
 320     /*!
 321      * \brief Get Tx daughterboard ID
 322      *
 323      * \param[out] dbid returns the daughterboard id.
 324      *
 325      * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
 326      * -2 if invalid EEPROM on daughterboard.
 327      */
 328     bool tx_daughterboard_id(int *dbid);
 329
 330     /*!
 331      * \brief Get Rx daughterboard ID
 332      *
 333      * \param[out] dbid returns the daughterboard id.
 334      *
 335      * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
 336      * -2 if invalid EEPROM on daughterboard.
 337      */
 338     bool rx_daughterboard_id(int *dbid);
 339
 340     /*
 341      * ----------------------------------------------------------------
 342      *  Low level methods
 343      * ----------------------------------------------------------------
 344      */
 345
 346     /*!
 347      * Burn new mac address into EEPROM on USRP2
 348      *
 349      * \param new_addr  Network mac address, e.g., "01:23:45:67:89:ab" or "89:ab".
 350      *                  If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
 351      */
 352     bool burn_mac_addr(const std::string &new_addr);
 353
 354
 355 #if 0   // not yet implemented
 356     /*!
 357      * \brief Write EEPROM on motherboard or any daughterboard.
 358      * \param i2c_addr          I2C bus address of EEPROM
 359      * \param eeprom_offset     byte offset in EEPROM to begin writing
 360      * \param buf               the data to write
 361      * \returns true iff sucessful
 362      */
 363     bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string &buf);
 364
 365     /*!
 366      * \brief Read EEPROM on motherboard or any daughterboard.
 367      * \param i2c_addr          I2C bus address of EEPROM
 368      * \param eeprom_offset     byte offset in EEPROM to begin reading
 369      * \param len               number of bytes to read
 370      * \returns the data read if successful, else a zero length string.
 371      */
 372     std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
 373
 374     /*!
 375      * \brief Write to I2C peripheral
 376      * \param i2c_addr          I2C bus address (7-bits)
 377      * \param buf               the data to write
 378      * \returns true iff successful
 379      * Writes are limited to a maximum of of 64 bytes.
 380      */
 381     bool write_i2c (int i2c_addr, const std::string &buf);
 382
 383     /*!
 384      * \brief Read from I2C peripheral
 385      * \param i2c_addr          I2C bus address (7-bits)
 386      * \param len               number of bytes to read
 387      * \returns the data read if successful, else a zero length string.
 388      * Reads are limited to a maximum of 64 bytes.
 389      */
 390     std::string read_i2c (int i2c_addr, int len);
 391
 392     /*!
 393      * \brief Write data to SPI bus peripheral.
 394      *
 395      * \param optional_header   0,1 or 2 bytes to write before buf.
 396      * \param enables           bitmask of peripherals to write. See usrp_spi_defs.h
 397      * \param format            transaction format.  See usrp_spi_defs.h SPI_FMT_*
 398      * \param buf               the data to write
 399      * \returns true iff successful
 400      * Writes are limited to a maximum of 64 bytes.
 401      *
 402      * If \p format specifies that optional_header bytes are present, they are
 403      * written to the peripheral immediately prior to writing \p buf.
 404      */
 405     bool write_spi (int optional_header, int enables, int format, const std::string &buf);
 406
 407     /*
 408      * \brief Read data from SPI bus peripheral.
 409      *
 410      * \param optional_header   0,1 or 2 bytes to write before buf.
 411      * \param enables           bitmask of peripheral to read. See usrp_spi_defs.h
 412      * \param format            transaction format.  See usrp_spi_defs.h SPI_FMT_*
 413      * \param len               number of bytes to read.  Must be in [0,64].
 414      * \returns the data read if sucessful, else a zero length string.
 415      *
 416      * Reads are limited to a maximum of 64 bytes.
 417      *
 418      * If \p format specifies that optional_header bytes are present, they
 419      * are written to the peripheral first.  Then \p len bytes are read from
 420      * the peripheral and returned.
 421      */
 422     std::string read_spi (int optional_header, int enables, int format, int len);
 423 #endif
 424
 425
 426     class impl;         // implementation details
 427
 428   private:
 429     // Static function to retrieve or create usrp2 instance
 430     static sptr find_existing_or_make_new(const std::string &ifc, props *p);
 431
 432     // Only class members can instantiate this class
 433     usrp2(const std::string &ifc, props *p);
 434
 435     // All private state is held in opaque pointer
 436     std::auto_ptr<impl> d_impl;
 437   };
 438
 439 };
 440
 441 std::ostream& operator<<(std::ostream &os, const usrp2::props &x);
 442
 443
 444 #endif /* INCLUDED_USRP2_H */