git.gag.com Git - debian/gnuradio/blob - usrp/host/lib/usrp_prims.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2003,2004,2006 Free Software Foundation, Inc.
   4  *
   5  * This file is part of GNU Radio
   6  *
   7  * GNU Radio is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 3, or (at your option)
  10  * any later version.
  11  *
  12  * GNU Radio is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with GNU Radio; see the file COPYING.  If not, write to
  19  * the Free Software Foundation, Inc., 51 Franklin Street,
  20  * Boston, MA 02110-1301, USA.
  21  */
  22
  23 /*
  24  * Low level primitives for directly messing with USRP hardware.
  25  *
  26  * If you're trying to use the USRP, you'll probably want to take a look
  27  * at the usrp_rx and usrp_tx classes.  They hide a bunch of low level details
  28  * and provide high performance streaming i/o.
  29  *
  30  * This interface is built on top of libusb, which allegedly works under
  31  * Linux, *BSD and Mac OS/X.  http://libusb.sourceforge.net
  32  */
  33
  34 #ifndef _USRP_PRIMS_H_
  35 #define _USRP_PRIMS_H_
  36
  37 #include <usrp_slots.h>
  38 #include <string>
  39
  40 static const int USRP_HASH_SIZE = 16;
  41
  42 enum usrp_load_status_t { ULS_ERROR = 0, ULS_OK, ULS_ALREADY_LOADED };
  43
  44 struct usb_dev_handle;
  45 struct usb_device;
  46
  47 /*!
  48  * \brief initialize libusb; probe busses and devices.
  49  * Safe to call more than once.
  50  */
  51 void usrp_one_time_init ();
  52
  53 /*
  54  * force a rescan of the buses and devices
  55  */
  56 void usrp_rescan ();
  57
  58 /*!
  59  * \brief locate Nth (zero based) USRP device in system.
  60  * Return pointer or 0 if not found.
  61  *
  62  * The following kinds of devices are considered USRPs:
  63  *
  64  *   unconfigured USRP (no firwmare loaded)
  65  *   configured USRP (firmware loaded)
  66  *   unconfigured Cypress FX2 (only if fx2_ok_p is true)
  67  */
  68 struct usb_device *usrp_find_device (int nth, bool fx2_ok_p = false);
  69
  70 bool usrp_usrp_p (struct usb_device *q);                //< is this a USRP
  71 bool usrp_usrp0_p (struct usb_device *q);               //< is this a USRP Rev 0
  72 bool usrp_usrp1_p (struct usb_device *q);               //< is this a USRP Rev 1
  73 bool usrp_usrp2_p (struct usb_device *q);               //< is this a USRP Rev 2
  74 int  usrp_hw_rev (struct usb_device *q);                //< return h/w rev code
  75
  76 bool usrp_fx2_p (struct usb_device *q);                 //< is this an unconfigured Cypress FX2
  77
  78 bool usrp_unconfigured_usrp_p (struct usb_device *q);   //< some kind of unconfigured USRP
  79 bool usrp_configured_usrp_p (struct usb_device *q);     //< some kind of configured USRP
  80
  81 /*!
  82  * \brief given a usb_device return an instance of the appropriate usb_dev_handle
  83  *
  84  * These routines claim the specified interface and select the
  85  * correct alternate interface.  (USB nomenclature is totally screwed!)
  86  *
  87  * If interface can't be opened, or is already claimed by some other
  88  * process, 0 is returned.
  89  */
  90 struct usb_dev_handle *usrp_open_cmd_interface (struct usb_device *dev);
  91 struct usb_dev_handle *usrp_open_rx_interface (struct usb_device *dev);
  92 struct usb_dev_handle *usrp_open_tx_interface (struct usb_device *dev);
  93
  94 /*!
  95  * \brief close interface.
  96  */
  97 bool usrp_close_interface (struct usb_dev_handle *udh);
  98
  99 /*!
 100  * \brief load intel hex format file into USRP/Cypress FX2 (8051).
 101  *
 102  * The filename extension is typically *.ihx
 103  *
 104  * Note that loading firmware may cause the device to renumerate.  I.e.,
 105  * change its configuration, invalidating the current device handle.
 106  */
 107
 108 usrp_load_status_t
 109 usrp_load_firmware (struct usb_dev_handle *udh, const char *filename, bool force);
 110
 111 /*!
 112  * \brief load intel hex format file into USRP FX2 (8051).
 113  *
 114  * The filename extension is typically *.ihx
 115  *
 116  * Note that loading firmware may cause the device to renumerate.  I.e.,
 117  * change its configuration, invalidating the current device handle.
 118  * If the result is ULS_OK, usrp_load_firmware_nth delays 1 second
 119  * then rescans the busses and devices.
 120  */
 121 usrp_load_status_t
 122 usrp_load_firmware_nth (int nth, const char *filename, bool force);
 123
 124 /*!
 125  * \brief load fpga configuration bitstream
 126  */
 127 usrp_load_status_t
 128 usrp_load_fpga (struct usb_dev_handle *udh, const char *filename, bool force);
 129
 130 /*!
 131  * \brief load the regular firmware and fpga bitstream in the Nth USRP.
 132  *
 133  * This is the normal starting point...
 134  */
 135 bool usrp_load_standard_bits (int nth, bool force,
 136                               const std::string fpga_filename = "",
 137                               const std::string firmware_filename = "");
 138
 139 /*!
 140  * \brief copy the given \p hash into the USRP hash slot \p which.
 141  * The usrp implements two hash slots, 0 and 1.
 142  */
 143 bool usrp_set_hash (struct usb_dev_handle *udh, int which,
 144                     const unsigned char hash[USRP_HASH_SIZE]);
 145
 146 /*!
 147  * \brief retrieve the \p hash from the USRP hash slot \p which.
 148  * The usrp implements two hash slots, 0 and 1.
 149  */
 150 bool usrp_get_hash (struct usb_dev_handle *udh, int which,
 151                     unsigned char hash[USRP_HASH_SIZE]);
 152
 153 bool usrp_write_fpga_reg (struct usb_dev_handle *udh, int reg, int value);
 154 bool usrp_read_fpga_reg (struct usb_dev_handle *udh, int reg, int *value);
 155 bool usrp_set_fpga_reset (struct usb_dev_handle *udh, bool on);
 156 bool usrp_set_fpga_tx_enable (struct usb_dev_handle *udh, bool on);
 157 bool usrp_set_fpga_rx_enable (struct usb_dev_handle *udh, bool on);
 158 bool usrp_set_fpga_tx_reset (struct usb_dev_handle *udh, bool on);
 159 bool usrp_set_fpga_rx_reset (struct usb_dev_handle *udh, bool on);
 160 bool usrp_set_led (struct usb_dev_handle *udh, int which, bool on);
 161
 162 bool usrp_check_rx_overrun (struct usb_dev_handle *udh, bool *overrun_p);
 163 bool usrp_check_tx_underrun (struct usb_dev_handle *udh, bool *underrun_p);
 164
 165 // i2c_read and i2c_write are limited to a maximum len of 64 bytes.
 166
 167 bool usrp_i2c_write (struct usb_dev_handle *udh, int i2c_addr,
 168                      const void *buf, int len);
 169
 170 bool usrp_i2c_read (struct usb_dev_handle *udh, int i2c_addr,
 171                     void *buf, int len);
 172
 173 // spi_read and spi_write are limited to a maximum of 64 bytes
 174 // See usrp_spi_defs.h for more info
 175
 176 bool usrp_spi_write (struct usb_dev_handle *udh,
 177                      int optional_header, int enables, int format,
 178                      const void *buf, int len);
 179
 180 bool usrp_spi_read (struct usb_dev_handle *udh,
 181                      int optional_header, int enables, int format,
 182                      void *buf, int len);
 183
 184
 185 bool usrp_9862_write (struct usb_dev_handle *udh,
 186                       int which_codec,                  // [0,  1]
 187                       int regno,                        // [0, 63]
 188                       int value);                       // [0, 255]
 189
 190 bool usrp_9862_read (struct usb_dev_handle *udh,
 191                      int which_codec,                   // [0,  1]
 192                      int regno,                         // [0, 63]
 193                      unsigned char *value);             // [0, 255]
 194
 195 /*!
 196  * \brief Write multiple 9862 regs at once.
 197  *
 198  * \p buf contains alternating register_number, register_value pairs.
 199  * \p len must be even and is the length of buf in bytes.
 200  */
 201 bool usrp_9862_write_many (struct usb_dev_handle *udh, int which_codec,
 202                            const unsigned char *buf, int len);
 203
 204
 205 /*!
 206  * \brief write specified regs to all 9862's in the system
 207  */
 208 bool usrp_9862_write_many_all (struct usb_dev_handle *udh,
 209                                const unsigned char *buf, int len);
 210
 211
 212 // Write 24LC024 / 24LC025 EEPROM on motherboard or daughterboard.
 213 // Which EEPROM is determined by i2c_addr.  See i2c_addr.h
 214
 215 bool usrp_eeprom_write (struct usb_dev_handle *udh, int i2c_addr,
 216                         int eeprom_offset, const void *buf, int len);
 217
 218
 219 // Read 24LC024 / 24LC025 EEPROM on motherboard or daughterboard.
 220 // Which EEPROM is determined by i2c_addr.  See i2c_addr.h
 221
 222 bool usrp_eeprom_read (struct usb_dev_handle *udh, int i2c_addr,
 223                        int eeprom_offset, void *buf, int len);
 224
 225
 226 // Slot specific i/o routines
 227
 228 /*!
 229  * \brief write to the specified aux dac.
 230  *
 231  * \p slot: which Tx or Rx slot to write.
 232  *    N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's
 233  *          SLOT_TX_B and SLOT_RX_B share the same AUX DAC's
 234  *
 235  * \p which_dac: [0,3]  RX slots must use only 0 and 1.
 236  *                      TX slots must use only 2 and 3.
 237  *
 238  * AUX DAC 3 is really the 9862 sigma delta output.
 239  *
 240  * \p value to write to aux dac.  All dacs take straight
 241  * binary values.  Although dacs 0, 1 and 2 are 8-bit and dac 3 is 12-bit,
 242  * the interface is in terms of 12-bit values [0,4095]
 243  */
 244 bool usrp_write_aux_dac (struct usb_dev_handle *uhd, int slot,
 245                          int which_dac, int value);
 246
 247 /*!
 248  * \brief Read the specified aux adc
 249  *
 250  * \p slot: which Tx or Rx slot to read aux dac
 251  * \p which_adc: [0,1]  which of the two adcs to read
 252  * \p *value: return value, 12-bit straight binary.
 253  */
 254 bool usrp_read_aux_adc (struct usb_dev_handle *udh, int slot,
 255                         int which_adc, int *value);
 256
 257
 258 /*!
 259  * \brief usrp daughterboard id to name mapping
 260  */
 261 const std::string usrp_dbid_to_string (int dbid);
 262
 263
 264 enum usrp_dbeeprom_status_t { UDBE_OK, UDBE_BAD_SLOT, UDBE_NO_EEPROM, UDBE_INVALID_EEPROM };
 265
 266 struct usrp_dboard_eeprom {
 267   unsigned short        id;             // d'board identifier code
 268   unsigned short        oe;             // fpga output enables:
 269                                         //   If bit set, i/o pin is an output from FPGA.
 270   short                 offset[2];      // ADC/DAC offset correction
 271 };
 272
 273 /*!
 274  * \brief Read and return parsed daughterboard eeprom
 275  */
 276 usrp_dbeeprom_status_t
 277 usrp_read_dboard_eeprom (struct usb_dev_handle *udh,
 278                          int slot_id, usrp_dboard_eeprom *eeprom);
 279
 280 /*!
 281  * \brief write ADC/DAC offset calibration constants to d'board eeprom
 282  */
 283 bool usrp_write_dboard_offsets (struct usb_dev_handle *udh, int slot_id,
 284                                 short offset0, short offset1);
 285
 286 /*!
 287  * \brief return a usrp's serial number.
 288  *
 289  * Note that this only works on a configured usrp.
 290  * \returns non-zero length string iff successful.
 291  */
 292 std::string usrp_serial_number(struct usb_dev_handle *udh);
 293
 294 #endif /* _USRP_PRIMS_H_ */