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

   1 /*  -*- c++ -*- */
   2 /*
   3  * Copyright 2005,2009 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 #ifndef INCLUDED_USRP_PRIMS_H
  24 #define INCLUDED_USRP_PRIMS_H
  25
  26 #include <usrp/usrp_slots.h>
  27 #include <usrp/libusb_types.h>
  28 #include <string>
  29
  30 struct libusb_context;
  31
  32 static const int USRP_HASH_SIZE = 16;
  33
  34 enum usrp_load_status_t { ULS_ERROR = 0, ULS_OK, ULS_ALREADY_LOADED };
  35
  36 /*!
  37  * \brief initialize libusb; Behavior differs depending on libusb version
  38  *
  39  * libusb-0.12
  40  *
  41  * Probe busses and devices. The argument is ignored and defaults to NULL.
  42  * Safe to call more than once.
  43  *
  44  * libusb-1.0
  45  *
  46  * If an location to a libusb_context is passed in, create and write in the new
  47  * context. If no argument is provided, initialize libusb with the default
  48  * (NULL) context.
  49  *
  50  * Generally _not_ safe to call more than once with non-NULL argument since a
  51  * new context will be created each time.
  52  */
  53
  54 void usrp_one_time_init (libusb_context **ctx = NULL);
  55
  56 /*!
  57  * \brief deinitialize libusb
  58  *
  59  * libusb-0.1: No effect
  60  *
  61  * libusb-1.0: Deinitialize context ctx
  62  */
  63 void usrp_deinit (libusb_context *ctx);
  64
  65 /*
  66  * force a rescan of the buses and devices
  67  */
  68 void usrp_rescan ();
  69
  70 /*!
  71  * \brief locate Nth (zero based) USRP device in system.
  72  * Return pointer or 0 if not found.
  73  *
  74  * The following kinds of devices are considered USRPs:
  75  *
  76  *   unconfigured USRP (no firwmare loaded)
  77  *   configured USRP (firmware loaded)
  78  *   unconfigured Cypress FX2 (only if fx2_ok_p is true)
  79  */
  80 libusb_device *usrp_find_device (int nth, bool fx2_ok_p = false, libusb_context *ctx = NULL);
  81
  82 bool usrp_usrp_p (libusb_device *q);            //< is this a USRP
  83 bool usrp_usrp0_p (libusb_device *q);           //< is this a USRP Rev 0
  84 bool usrp_usrp1_p (libusb_device *q);           //< is this a USRP Rev 1
  85 bool usrp_usrp2_p (libusb_device *q);           //< is this a USRP Rev 2
  86 int  usrp_hw_rev (libusb_device *q);            //< return h/w rev code
  87
  88 bool usrp_fx2_p (libusb_device *q);                     //< is this an unconfigured Cypress FX2
  89
  90 bool usrp_unconfigured_usrp_p (libusb_device *q);       //< some kind of unconfigured USRP
  91 bool usrp_configured_usrp_p (libusb_device *q); //< some kind of configured USRP
  92
  93 /*!
  94  * \brief given a libusb_device return an instance of the appropriate libusb_device_handle
  95  *
  96  * These routines claim the specified interface and select the
  97  * correct alternate interface.  (USB nomenclature is totally screwed!)
  98  *
  99  * If interface can't be opened, or is already claimed by some other
 100  * process, 0 is returned.
 101  */
 102 libusb_device_handle *usrp_open_cmd_interface (libusb_device *dev);
 103 libusb_device_handle *usrp_open_rx_interface (libusb_device *dev);
 104 libusb_device_handle *usrp_open_tx_interface (libusb_device *dev);
 105
 106 /*!
 107  * \brief close interface.
 108  */
 109 bool usrp_close_interface (libusb_device_handle *udh);
 110
 111 /*!
 112  * \brief load intel hex format file into USRP/Cypress 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  */
 119
 120 usrp_load_status_t
 121 usrp_load_firmware (libusb_device_handle *udh, const char *filename, bool force);
 122
 123 /*!
 124  * \brief load intel hex format file into USRP FX2 (8051).
 125  *
 126  * The filename extension is typically *.ihx
 127  *
 128  * Note that loading firmware may cause the device to renumerate.  I.e.,
 129  * change its configuration, invalidating the current device handle.
 130  * If the result is ULS_OK, usrp_load_firmware_nth delays 1 second
 131  * then rescans the busses and devices.
 132  */
 133 usrp_load_status_t
 134 usrp_load_firmware_nth (int nth, const char *filename, bool force, libusb_context *ctx = NULL);
 135
 136 /*!
 137  * \brief load fpga configuration bitstream
 138  */
 139 usrp_load_status_t
 140 usrp_load_fpga (libusb_device_handle *udh, const char *filename, bool force);
 141
 142 /*!
 143  * \brief load the regular firmware and fpga bitstream in the Nth USRP.
 144  *
 145  * This is the normal starting point...
 146  */
 147 bool usrp_load_standard_bits (int nth, bool force,
 148                               const std::string fpga_filename = "",
 149                               const std::string firmware_filename = "",
 150                               libusb_context *ctx = NULL);
 151
 152 /*!
 153  * \brief copy the given \p hash into the USRP hash slot \p which.
 154  * The usrp implements two hash slots, 0 and 1.
 155  */
 156 bool usrp_set_hash (libusb_device_handle *udh, int which,
 157                     const unsigned char hash[USRP_HASH_SIZE]);
 158
 159 /*!
 160  * \brief retrieve the \p hash from the USRP hash slot \p which.
 161  * The usrp implements two hash slots, 0 and 1.
 162  */
 163 bool usrp_get_hash (libusb_device_handle *udh, int which,
 164                     unsigned char hash[USRP_HASH_SIZE]);
 165
 166 bool usrp_write_fpga_reg (libusb_device_handle *udh, int reg, int value);
 167 bool usrp_read_fpga_reg (libusb_device_handle *udh, int reg, int *value);
 168 bool usrp_set_fpga_reset (libusb_device_handle *udh, bool on);
 169 bool usrp_set_fpga_tx_enable (libusb_device_handle *udh, bool on);
 170 bool usrp_set_fpga_rx_enable (libusb_device_handle *udh, bool on);
 171 bool usrp_set_fpga_tx_reset (libusb_device_handle *udh, bool on);
 172 bool usrp_set_fpga_rx_reset (libusb_device_handle *udh, bool on);
 173 bool usrp_set_led (libusb_device_handle *udh, int which, bool on);
 174
 175 bool usrp_check_rx_overrun (libusb_device_handle *udh, bool *overrun_p);
 176 bool usrp_check_tx_underrun (libusb_device_handle *udh, bool *underrun_p);
 177
 178 // i2c_read and i2c_write are limited to a maximum len of 64 bytes.
 179
 180 bool usrp_i2c_write (libusb_device_handle *udh, int i2c_addr,
 181                      const void *buf, int len);
 182
 183 bool usrp_i2c_read (libusb_device_handle *udh, int i2c_addr,
 184                     void *buf, int len);
 185
 186 // spi_read and spi_write are limited to a maximum of 64 bytes
 187 // See usrp_spi_defs.h for more info
 188
 189 bool usrp_spi_write (libusb_device_handle *udh,
 190                      int optional_header, int enables, int format,
 191                      const void *buf, int len);
 192
 193 bool usrp_spi_read (libusb_device_handle *udh,
 194                      int optional_header, int enables, int format,
 195                      void *buf, int len);
 196
 197
 198 bool usrp_9862_write (libusb_device_handle *udh,
 199                       int which_codec,                  // [0,  1]
 200                       int regno,                        // [0, 63]
 201                       int value);                       // [0, 255]
 202
 203 bool usrp_9862_read (libusb_device_handle *udh,
 204                      int which_codec,                   // [0,  1]
 205                      int regno,                         // [0, 63]
 206                      unsigned char *value);             // [0, 255]
 207
 208 /*!
 209  * \brief Write multiple 9862 regs at once.
 210  *
 211  * \p buf contains alternating register_number, register_value pairs.
 212  * \p len must be even and is the length of buf in bytes.
 213  */
 214 bool usrp_9862_write_many (libusb_device_handle *udh, int which_codec,
 215                            const unsigned char *buf, int len);
 216
 217
 218 /*!
 219  * \brief write specified regs to all 9862's in the system
 220  */
 221 bool usrp_9862_write_many_all (libusb_device_handle *udh,
 222                                const unsigned char *buf, int len);
 223
 224
 225 // Write 24LC024 / 24LC025 EEPROM on motherboard or daughterboard.
 226 // Which EEPROM is determined by i2c_addr.  See i2c_addr.h
 227
 228 bool usrp_eeprom_write (libusb_device_handle *udh, int i2c_addr,
 229                         int eeprom_offset, const void *buf, int len);
 230
 231
 232 // Read 24LC024 / 24LC025 EEPROM on motherboard or daughterboard.
 233 // Which EEPROM is determined by i2c_addr.  See i2c_addr.h
 234
 235 bool usrp_eeprom_read (libusb_device_handle *udh, int i2c_addr,
 236                        int eeprom_offset, void *buf, int len);
 237
 238
 239 // Slot specific i/o routines
 240
 241 /*!
 242  * \brief write to the specified aux dac.
 243  *
 244  * \p slot: which Tx or Rx slot to write.
 245  *    N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's
 246  *          SLOT_TX_B and SLOT_RX_B share the same AUX DAC's
 247  *
 248  * \p which_dac: [0,3]  RX slots must use only 0 and 1.
 249  *                      TX slots must use only 2 and 3.
 250  *
 251  * AUX DAC 3 is really the 9862 sigma delta output.
 252  *
 253  * \p value to write to aux dac.  All dacs take straight
 254  * binary values.  Although dacs 0, 1 and 2 are 8-bit and dac 3 is 12-bit,
 255  * the interface is in terms of 12-bit values [0,4095]
 256  */
 257 bool usrp_write_aux_dac (libusb_device_handle *uhd, int slot,
 258                          int which_dac, int value);
 259
 260 /*!
 261  * \brief Read the specified aux adc
 262  *
 263  * \p slot: which Tx or Rx slot to read aux dac
 264  * \p which_adc: [0,1]  which of the two adcs to read
 265  * \p *value: return value, 12-bit straight binary.
 266  */
 267 bool usrp_read_aux_adc (libusb_device_handle *udh, int slot,
 268                         int which_adc, int *value);
 269
 270
 271 /*!
 272  * \brief usrp daughterboard id to name mapping
 273  */
 274 const std::string usrp_dbid_to_string (int dbid);
 275
 276
 277 enum usrp_dbeeprom_status_t { UDBE_OK, UDBE_BAD_SLOT, UDBE_NO_EEPROM, UDBE_INVALID_EEPROM };
 278
 279 struct usrp_dboard_eeprom {
 280   unsigned short        id;             // d'board identifier code
 281   unsigned short        oe;             // fpga output enables:
 282                                         //   If bit set, i/o pin is an output from FPGA.
 283   short                 offset[2];      // ADC/DAC offset correction
 284 };
 285
 286 /*!
 287  * \brief Read and return parsed daughterboard eeprom
 288  */
 289 usrp_dbeeprom_status_t
 290 usrp_read_dboard_eeprom (libusb_device_handle *udh,
 291                          int slot_id, usrp_dboard_eeprom *eeprom);
 292
 293 /*!
 294  * \brief write ADC/DAC offset calibration constants to d'board eeprom
 295  */
 296 bool usrp_write_dboard_offsets (libusb_device_handle *udh, int slot_id,
 297                                 short offset0, short offset1);
 298
 299 /*!
 300  * \brief return a usrp's serial number.
 301  *
 302  * Note that this only works on a configured usrp.
 303  * \returns non-zero length string iff successful.
 304  */
 305 std::string usrp_serial_number(libusb_device_handle *udh);
 306
 307 #endif /* INCLUDED_USRP_PRIMS_H */