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