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