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 #include <usrp2/rx_sample_handler.h>
  30
  31
  32 namespace usrp2 {
  33
  34   /*!
  35    * Structure to hold properties of USRP2 hardware devices.
  36    *
  37    */
  38   struct props
  39   {
  40     std::string addr;
  41     uint16_t hw_rev;
  42     uint8_t fpga_md5sum[16];
  43     uint8_t sw_md5sum[16];
  44   };
  45
  46   typedef std::vector<props> props_vector_t;
  47
  48   /*!
  49    * \brief Search the ethernet for all USRP2s or for a specific USRP2.
  50    *
  51    * \param ifc is the name of the OS ethernet interface (e.g., "eth0")
  52    * \param mac_addr is the MAC address of the desired USRP2, or "" to search for all.
  53    * mac_addr must be either a zero length string, "", or must be of the form
  54    * "01:02:03:04:05:06" or "05:06".
  55    *
  56    * \returns a vector of properties, 1 entry for each matching USRP2 found.
  57    */
  58   props_vector_t find(const std::string &ifc, const std::string &mac_addr="");
  59
  60   class tune_result;
  61
  62   class usrp2 : boost::noncopyable
  63   {
  64   public:
  65     static const unsigned int MAX_CHAN = 30;
  66
  67     /*!
  68      * Shared pointer to this class
  69      */
  70     typedef boost::shared_ptr<usrp2> sptr;
  71
  72     /*!
  73      * Static function to return an instance of usrp2 as a shared pointer
  74      *
  75      * \param ifc   Network interface name, e.g., "eth0"
  76      * \param addr  Network mac address, e.g., "01:23:45:67:89:ab", "89:ab" or "".
  77      *              If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
  78      *              "" will autoselect a USRP2 if there is only a single one on the local ethernet.
  79      */
  80     static sptr make(const std::string &ifc, const std::string &addr="");
  81
  82     /*!
  83      * Class destructor
  84      */
  85     ~usrp2();
  86
  87     /*!
  88      * Returns the MAC address associated with this USRP
  89      */
  90     std::string mac_addr();
  91
  92     /*!
  93      * Burn new mac address into EEPROM on USRP2
  94      *
  95      * \param new_addr  Network mac address, e.g., "01:23:45:67:89:ab" or "89:ab".
  96      *                  If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
  97      */
  98     bool burn_mac_addr(const std::string &new_addr);
  99
 100     /*
 101      * ----------------------------------------------------------------
 102      * Rx configuration and control
 103      * ----------------------------------------------------------------
 104      */
 105
 106     /*!
 107      * Set receiver gain
 108      */
 109     bool set_rx_gain(double gain);
 110
 111     /*!
 112      * Set receiver center frequency
 113      */
 114     bool set_rx_center_freq(double frequency, tune_result *result);
 115
 116     /*!
 117      * Set receiver sample rate decimation
 118      */
 119     bool set_rx_decim(int decimation_factor);
 120
 121     /*!
 122      * Set receiver IQ magnitude scaling
 123      */
 124     bool set_rx_scale_iq(int scale_i, int scale_q);
 125
 126     /*!
 127      * Set received sample format
 128      *
 129      *    domain: complex or real
 130      *      type: floating, fixed point, or raw
 131      *     depth: bits per sample
 132      *
 133      * Sets format over the wire for samples from USRP2.
 134      */
 135     // bool set_rx_format(...);
 136
 137     /*!
 138      * Start streaming receive mode.  USRP2 will send a continuous stream of
 139      * DSP pipeline samples to host.  Call rx_samples(...) to access.
 140      *
 141      * \param channel          Stream channel number (0-30)
 142      * \param items_per_frame  Number of 32-bit items per frame.
 143      */
 144     bool start_rx_streaming(unsigned int channel=0, unsigned int items_per_frame=0);
 145
 146     /*!
 147      * Stop streaming receive mode.
 148      */
 149     bool stop_rx_streaming(unsigned int channel=0);
 150
 151     /*!
 152      * \brief Receive data from the specified channel
 153      * This method is used to receive all data: streaming or discrete.
 154      */
 155     bool rx_samples(unsigned int channel, rx_sample_handler *handler);
 156
 157     /*!
 158      * Returns number of times receive overruns have occurred
 159      */
 160     unsigned int rx_overruns();
 161
 162     /*!
 163      * Returns total number of missing frames from overruns.
 164      */
 165     unsigned int rx_missing();
 166
 167     /*
 168      * ----------------------------------------------------------------
 169      * Tx configuration and control
 170      * ----------------------------------------------------------------
 171      */
 172
 173     /*!
 174      * Set transmitter gain
 175      */
 176     bool set_tx_gain(double gain);
 177
 178     /*!
 179      * Set transmitter center frequency
 180      */
 181     bool set_tx_center_freq(double frequency, tune_result *result);
 182
 183     /*!
 184      * Set transmitter sample rate interpolation
 185      */
 186     bool set_tx_interp(int interpolation_factor);
 187
 188     /*!
 189      * Set transmit IQ magnitude scaling
 190      */
 191     bool set_tx_scale_iq(int scale_i, int scale_q);
 192
 193     /*!
 194      * Set transmit sample format
 195      *
 196      *    domain: complex or real
 197      *      type: floating, fixed point, or raw
 198      *     depth: bits per sample
 199      *
 200      * Sets format over the wire for samples to USRP2.
 201      */
 202     // bool set_tx_format(...);
 203
 204     /*!
 205      * \brief transmit complex<float> samples to USRP2
 206      *
 207      * \param channel specifies the channel to send them to
 208      * \param samples are the samples to transmit.  They should be in the range [-1.0, +1.0]
 209      * \param nsamples is the number of samples to transmit
 210      * \param metadata provides the timestamp and flags
 211      *
 212      * The complex<float> samples are converted to the appropriate
 213      * "on the wire" representation, depending on the current USRP2
 214      * configuration.  Typically, this is big-endian 16-bit I & Q.
 215      */
 216     bool tx_32fc(unsigned int channel,
 217                  const std::complex<float> *samples,
 218                  size_t nsamples,
 219                  const tx_metadata *metadata);
 220
 221     /*!
 222      * \brief transmit complex<int16_t> samples to USRP2
 223      *
 224      * \param channel specifies the channel to send them to
 225      * \param samples are the samples to transmit
 226      * \param nsamples is the number of samples to transmit
 227      * \param metadata provides the timestamp and flags
 228      *
 229      * The complex<int16_t> samples are converted to the appropriate
 230      * "on the wire" representation, depending on the current USRP2
 231      * configuration.  Typically, this is big-endian 16-bit I & Q.
 232      */
 233     bool tx_16sc(unsigned int channel,
 234                  const std::complex<int16_t> *samples,
 235                  size_t nsamples,
 236                  const tx_metadata *metadata);
 237
 238     /*!
 239      * \brief transmit raw uint32_t data items to USRP2
 240      *
 241      * The caller is responsible for ensuring that the items are
 242      * formatted appropriately for the USRP2 and its configuration.
 243      * This method is used primarily by the system itself.  Users
 244      * should call tx_32fc or tx_16sc instead.
 245      *
 246      * \param channel specifies the channel to send them to
 247      * \param items are the data items to transmit
 248      * \param nitems is the number of items to transmit
 249      * \param metadata provides the timestamp and flags
 250      */
 251     bool tx_raw(unsigned int channel,
 252                 const uint32_t *items,
 253                 size_t nitems,
 254                 const tx_metadata *metadata);
 255
 256     // ----------------------------------------------------------------
 257
 258     /*!
 259      * \brief MIMO configuration
 260      *
 261      * \param flags from usrp2_mimo_config.h
 262      *
 263      * <pre>
 264      *   one of these:
 265      *
 266      *     MC_WE_DONT_LOCK
 267      *     MC_WE_LOCK_TO_SMA
 268      *     MC_WE_LOCK_TO_MIMO
 269      *
 270      *   and optionally this:
 271      *
 272      *     MC_PROVIDE_CLK_TO_MIMO
 273      * </pre>
 274      */
 275     bool config_mimo(int flags);
 276
 277     class impl;         // implementation details
 278
 279   private:
 280     // Static function to retrieve or create usrp2 instance
 281     static sptr find_existing_or_make_new(const std::string &ifc, props *p);
 282
 283     // Only class members can instantiate this class
 284     usrp2(const std::string &ifc, props *p);
 285
 286     // All private state is held in opaque pointer
 287     std::auto_ptr<impl> d_impl;
 288   };
 289
 290 };
 291
 292 std::ostream& operator<<(std::ostream &os, const usrp2::props &x);
 293
 294
 295 #endif /* INCLUDED_USRP2_H */