usrp_prims.h

Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2003,2004,2006 Free Software Foundation, Inc.
00004  * 
00005  * This file is part of GNU Radio
00006  * 
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  * 
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  * 
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 /*
00024  * Low level primitives for directly messing with USRP hardware.
00025  *
00026  * If you're trying to use the USRP, you'll probably want to take a look
00027  * at the usrp_rx and usrp_tx classes.  They hide a bunch of low level details
00028  * and provide high performance streaming i/o.
00029  *
00030  * This interface is built on top of libusb, which allegedly works under
00031  * Linux, *BSD and Mac OS/X.  http://libusb.sourceforge.net
00032  */
00033 
00034 #ifndef _USRP_PRIMS_H_
00035 #define _USRP_PRIMS_H_
00036 
00037 #include <usrp_slots.h>
00038 #include <string>
00039 
00040 static const int USRP_HASH_SIZE = 16;
00041 
00042 enum usrp_load_status_t { ULS_ERROR = 0, ULS_OK, ULS_ALREADY_LOADED };
00043 
00044 struct usb_dev_handle;
00045 struct usb_device;
00046 
00047 /*!
00048  * \brief initialize libusb; probe busses and devices.
00049  * Safe to call more than once.
00050  */
00051 void usrp_one_time_init ();
00052 
00053 /*
00054  * force a rescan of the buses and devices
00055  */
00056 void usrp_rescan ();
00057 
00058 /*!
00059  * \brief locate Nth (zero based) USRP device in system.
00060  * Return pointer or 0 if not found.
00061  *
00062  * The following kinds of devices are considered USRPs:
00063  *
00064  *   unconfigured USRP (no firwmare loaded)
00065  *   configured USRP (firmware loaded)
00066  *   unconfigured Cypress FX2 (only if fx2_ok_p is true)
00067  */
00068 struct usb_device *usrp_find_device (int nth, bool fx2_ok_p = false);
00069 
00070 bool usrp_usrp_p (struct usb_device *q);                //< is this a USRP
00071 bool usrp_usrp0_p (struct usb_device *q);               //< is this a USRP Rev 0
00072 bool usrp_usrp1_p (struct usb_device *q);               //< is this a USRP Rev 1
00073 bool usrp_usrp2_p (struct usb_device *q);               //< is this a USRP Rev 2
00074 int  usrp_hw_rev (struct usb_device *q);                //< return h/w rev code
00075 
00076 bool usrp_fx2_p (struct usb_device *q);                 //< is this an unconfigured Cypress FX2
00077 
00078 bool usrp_unconfigured_usrp_p (struct usb_device *q);   //< some kind of unconfigured USRP
00079 bool usrp_configured_usrp_p (struct usb_device *q);     //< some kind of configured USRP
00080 
00081 /*!
00082  * \brief given a usb_device return an instance of the appropriate usb_dev_handle
00083  *
00084  * These routines claim the specified interface and select the
00085  * correct alternate interface.  (USB nomenclature is totally screwed!)
00086  *
00087  * If interface can't be opened, or is already claimed by some other
00088  * process, 0 is returned.
00089  */
00090 struct usb_dev_handle *usrp_open_cmd_interface (struct usb_device *dev);
00091 struct usb_dev_handle *usrp_open_rx_interface (struct usb_device *dev);
00092 struct usb_dev_handle *usrp_open_tx_interface (struct usb_device *dev);
00093 
00094 /*!
00095  * \brief close interface.
00096  */
00097 bool usrp_close_interface (struct usb_dev_handle *udh);
00098 
00099 /*!
00100  * \brief load intel hex format file into USRP/Cypress FX2 (8051).
00101  *
00102  * The filename extension is typically *.ihx
00103  *
00104  * Note that loading firmware may cause the device to renumerate.  I.e.,
00105  * change its configuration, invalidating the current device handle.
00106  */
00107 
00108 usrp_load_status_t 
00109 usrp_load_firmware (struct usb_dev_handle *udh, const char *filename, bool force);
00110 
00111 /*!
00112  * \brief load intel hex format file into USRP FX2 (8051).
00113  *
00114  * The filename extension is typically *.ihx
00115  *
00116  * Note that loading firmware may cause the device to renumerate.  I.e.,
00117  * change its configuration, invalidating the current device handle.
00118  * If the result is ULS_OK, usrp_load_firmware_nth delays 1 second
00119  * then rescans the busses and devices.
00120  */
00121 usrp_load_status_t
00122 usrp_load_firmware_nth (int nth, const char *filename, bool force);
00123 
00124 /*!
00125  * \brief load fpga configuration bitstream
00126  */
00127 usrp_load_status_t
00128 usrp_load_fpga (struct usb_dev_handle *udh, const char *filename, bool force);
00129 
00130 /*!
00131  * \brief load the regular firmware and fpga bitstream in the Nth USRP.
00132  *
00133  * This is the normal starting point...
00134  */
00135 bool usrp_load_standard_bits (int nth, bool force,
00136                               const std::string fpga_filename = "",
00137                               const std::string firmware_filename = "");
00138 
00139 /*!
00140  * \brief copy the given \p hash into the USRP hash slot \p which.
00141  * The usrp implements two hash slots, 0 and 1.
00142  */
00143 bool usrp_set_hash (struct usb_dev_handle *udh, int which,
00144                     const unsigned char hash[USRP_HASH_SIZE]);
00145 
00146 /*!
00147  * \brief retrieve the \p hash from the USRP hash slot \p which.
00148  * The usrp implements two hash slots, 0 and 1.
00149  */
00150 bool usrp_get_hash (struct usb_dev_handle *udh, int which,
00151                     unsigned char hash[USRP_HASH_SIZE]);
00152 
00153 bool usrp_write_fpga_reg (struct usb_dev_handle *udh, int reg, int value);
00154 bool usrp_read_fpga_reg (struct usb_dev_handle *udh, int reg, int *value);
00155 bool usrp_set_fpga_reset (struct usb_dev_handle *udh, bool on);
00156 bool usrp_set_fpga_tx_enable (struct usb_dev_handle *udh, bool on);
00157 bool usrp_set_fpga_rx_enable (struct usb_dev_handle *udh, bool on);
00158 bool usrp_set_fpga_tx_reset (struct usb_dev_handle *udh, bool on);
00159 bool usrp_set_fpga_rx_reset (struct usb_dev_handle *udh, bool on);
00160 bool usrp_set_led (struct usb_dev_handle *udh, int which, bool on);
00161 
00162 bool usrp_check_rx_overrun (struct usb_dev_handle *udh, bool *overrun_p);
00163 bool usrp_check_tx_underrun (struct usb_dev_handle *udh, bool *underrun_p);
00164 
00165 // i2c_read and i2c_write are limited to a maximum len of 64 bytes.
00166 
00167 bool usrp_i2c_write (struct usb_dev_handle *udh, int i2c_addr,
00168                      const void *buf, int len);
00169 
00170 bool usrp_i2c_read (struct usb_dev_handle *udh, int i2c_addr,
00171                     void *buf, int len);
00172 
00173 // spi_read and spi_write are limited to a maximum of 64 bytes
00174 // See usrp_spi_defs.h for more info
00175 
00176 bool usrp_spi_write (struct usb_dev_handle *udh,
00177                      int optional_header, int enables, int format,
00178                      const void *buf, int len);
00179 
00180 bool usrp_spi_read (struct usb_dev_handle *udh,
00181                      int optional_header, int enables, int format,
00182                      void *buf, int len);
00183 
00184 
00185 bool usrp_9862_write (struct usb_dev_handle *udh,
00186                       int which_codec,                  // [0,  1]
00187                       int regno,                        // [0, 63]
00188                       int value);                       // [0, 255]     
00189 
00190 bool usrp_9862_read (struct usb_dev_handle *udh,
00191                      int which_codec,                   // [0,  1]
00192                      int regno,                         // [0, 63]
00193                      unsigned char *value);             // [0, 255]
00194 
00195 /*!
00196  * \brief Write multiple 9862 regs at once.
00197  *
00198  * \p buf contains alternating register_number, register_value pairs.
00199  * \p len must be even and is the length of buf in bytes.
00200  */
00201 bool usrp_9862_write_many (struct usb_dev_handle *udh, int which_codec,
00202                            const unsigned char *buf, int len);
00203                            
00204 
00205 /*!
00206  * \brief write specified regs to all 9862's in the system
00207  */
00208 bool usrp_9862_write_many_all (struct usb_dev_handle *udh,
00209                                const unsigned char *buf, int len);
00210                            
00211 
00212 // Write 24LC024 / 24LC025 EEPROM on motherboard or daughterboard.
00213 // Which EEPROM is determined by i2c_addr.  See i2c_addr.h
00214 
00215 bool usrp_eeprom_write (struct usb_dev_handle *udh, int i2c_addr,
00216                         int eeprom_offset, const void *buf, int len);
00217 
00218 
00219 // Read 24LC024 / 24LC025 EEPROM on motherboard or daughterboard.
00220 // Which EEPROM is determined by i2c_addr.  See i2c_addr.h
00221 
00222 bool usrp_eeprom_read (struct usb_dev_handle *udh, int i2c_addr,
00223                        int eeprom_offset, void *buf, int len);
00224 
00225 
00226 // Slot specific i/o routines
00227 
00228 /*!
00229  * \brief write to the specified aux dac.
00230  *
00231  * \p slot: which Tx or Rx slot to write.
00232  *    N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's
00233  *          SLOT_TX_B and SLOT_RX_B share the same AUX DAC's
00234  *
00235  * \p which_dac: [0,3]  RX slots must use only 0 and 1.
00236  *                      TX slots must use only 2 and 3.
00237  *
00238  * AUX DAC 3 is really the 9862 sigma delta output.
00239  *
00240  * \p value to write to aux dac.  All dacs take straight
00241  * binary values.  Although dacs 0, 1 and 2 are 8-bit and dac 3 is 12-bit,
00242  * the interface is in terms of 12-bit values [0,4095]
00243  */
00244 bool usrp_write_aux_dac (struct usb_dev_handle *uhd, int slot,
00245                          int which_dac, int value);
00246 
00247 /*!
00248  * \brief Read the specified aux adc
00249  *
00250  * \p slot: which Tx or Rx slot to read aux dac
00251  * \p which_adc: [0,1]  which of the two adcs to read
00252  * \p *value: return value, 12-bit straight binary.
00253  */
00254 bool usrp_read_aux_adc (struct usb_dev_handle *udh, int slot,
00255                         int which_adc, int *value);
00256 
00257 
00258 /*!
00259  * \brief usrp daughterboard id to name mapping
00260  */
00261 const std::string usrp_dbid_to_string (int dbid);
00262 
00263 
00264 enum usrp_dbeeprom_status_t { UDBE_OK, UDBE_BAD_SLOT, UDBE_NO_EEPROM, UDBE_INVALID_EEPROM };
00265 
00266 struct usrp_dboard_eeprom {
00267   unsigned short        id;             // d'board identifier code
00268   unsigned short        oe;             // fpga output enables:
00269                                         //   If bit set, i/o pin is an output from FPGA.
00270   short                 offset[2];      // ADC/DAC offset correction
00271 };
00272 
00273 /*!
00274  * \brief Read and return parsed daughterboard eeprom
00275  */
00276 usrp_dbeeprom_status_t
00277 usrp_read_dboard_eeprom (struct usb_dev_handle *udh,
00278                          int slot_id, usrp_dboard_eeprom *eeprom);
00279 
00280 /*!
00281  * \brief write ADC/DAC offset calibration constants to d'board eeprom
00282  */
00283 bool usrp_write_dboard_offsets (struct usb_dev_handle *udh, int slot_id,
00284                                 short offset0, short offset1);
00285 
00286 /*!
00287  * \brief return a usrp's serial number.
00288  *
00289  * Note that this only works on a configured usrp.
00290  * \returns non-zero length string iff successful.
00291  */
00292 std::string usrp_serial_number(struct usb_dev_handle *udh);
00293 
00294 #endif /* _USRP_PRIMS_H_ */

Generated on Wed Jul 29 06:23:30 2009 for GNU Radio 3.2.2 C++ API by  doxygen 1.5.9