3 * Copyright 2003,2004,2006,2009 Free Software Foundation, Inc.
5 * This file is part of GNU Radio
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)
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.
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.
24 * Low level primitives for directly messing with USRP hardware.
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.
30 * This interface is built on top of libusb, which allegedly works under
31 * Linux, *BSD and Mac OS/X. http://libusb.sourceforge.net
34 #ifndef _USRP_PRIMS_H_
35 #define _USRP_PRIMS_H_
37 #include <usrp/usrp_slots.h>
40 static const int USRP_HASH_SIZE = 16;
42 enum usrp_load_status_t { ULS_ERROR = 0, ULS_OK, ULS_ALREADY_LOADED };
44 struct libusb_device_handle;
46 struct libusb_context;
49 * \brief initialize libusb; probe busses and devices.
50 * If new_context is set to true, initiate and returns new libusb_context.
51 * If new_context is set to false, intiate default context if not already
52 * initiated and return NULL. It is NOT safe to call more than once with
53 * new_context set to true since a new context is initiated each time.
55 libusb_context* usrp_one_time_init (bool new_context);
58 * force a rescan of the buses and devices
63 * \brief locate Nth (zero based) USRP device in system.
64 * Return pointer or 0 if not found.
66 * The following kinds of devices are considered USRPs:
68 * unconfigured USRP (no firwmare loaded)
69 * configured USRP (firmware loaded)
70 * unconfigured Cypress FX2 (only if fx2_ok_p is true)
72 struct libusb_device *usrp_find_device (int nth, bool fx2_ok_p = false, libusb_context *ctx = NULL);
74 bool usrp_usrp_p (struct libusb_device *q); //< is this a USRP
75 bool usrp_usrp0_p (struct libusb_device *q); //< is this a USRP Rev 0
76 bool usrp_usrp1_p (struct libusb_device *q); //< is this a USRP Rev 1
77 bool usrp_usrp2_p (struct libusb_device *q); //< is this a USRP Rev 2
78 int usrp_hw_rev (struct libusb_device *q); //< return h/w rev code
80 bool usrp_fx2_p (struct libusb_device *q); //< is this an unconfigured Cypress FX2
82 bool usrp_unconfigured_usrp_p (struct libusb_device *q); //< some kind of unconfigured USRP
83 bool usrp_configured_usrp_p (struct libusb_device *q); //< some kind of configured USRP
86 * \brief given a libusb_device return an instance of the appropriate libusb_device_handle
88 * These routines claim the specified interface and select the
89 * correct alternate interface. (USB nomenclature is totally screwed!)
91 * If interface can't be opened, or is already claimed by some other
92 * process, 0 is returned.
94 struct libusb_device_handle *usrp_open_cmd_interface (struct libusb_device *dev);
95 struct libusb_device_handle *usrp_open_rx_interface (struct libusb_device *dev);
96 struct libusb_device_handle *usrp_open_tx_interface (struct libusb_device *dev);
99 * \brief close interface.
101 bool usrp_close_interface (struct libusb_device_handle *udh);
104 * \brief load intel hex format file into USRP/Cypress FX2 (8051).
106 * The filename extension is typically *.ihx
108 * Note that loading firmware may cause the device to renumerate. I.e.,
109 * change its configuration, invalidating the current device handle.
113 usrp_load_firmware (struct libusb_device_handle *udh, const char *filename, bool force);
116 * \brief load intel hex format file into USRP FX2 (8051).
118 * The filename extension is typically *.ihx
120 * Note that loading firmware may cause the device to renumerate. I.e.,
121 * change its configuration, invalidating the current device handle.
122 * If the result is ULS_OK, usrp_load_firmware_nth delays 1 second
123 * then rescans the busses and devices.
126 usrp_load_firmware_nth (int nth, const char *filename, bool force, libusb_context *ctx);
129 * \brief load fpga configuration bitstream
132 usrp_load_fpga (struct libusb_device_handle *udh, const char *filename, bool force);
135 * \brief load the regular firmware and fpga bitstream in the Nth USRP.
137 * This is the normal starting point...
139 bool usrp_load_standard_bits (int nth, bool force,
140 const std::string fpga_filename = "",
141 const std::string firmware_filename = "",
142 libusb_context *ctx = NULL);
145 * \brief copy the given \p hash into the USRP hash slot \p which.
146 * The usrp implements two hash slots, 0 and 1.
148 bool usrp_set_hash (struct libusb_device_handle *udh, int which,
149 const unsigned char hash[USRP_HASH_SIZE]);
152 * \brief retrieve the \p hash from the USRP hash slot \p which.
153 * The usrp implements two hash slots, 0 and 1.
155 bool usrp_get_hash (struct libusb_device_handle *udh, int which,
156 unsigned char hash[USRP_HASH_SIZE]);
158 bool usrp_write_fpga_reg (struct libusb_device_handle *udh, int reg, int value);
159 bool usrp_read_fpga_reg (struct libusb_device_handle *udh, int reg, int *value);
160 bool usrp_set_fpga_reset (struct libusb_device_handle *udh, bool on);
161 bool usrp_set_fpga_tx_enable (struct libusb_device_handle *udh, bool on);
162 bool usrp_set_fpga_rx_enable (struct libusb_device_handle *udh, bool on);
163 bool usrp_set_fpga_tx_reset (struct libusb_device_handle *udh, bool on);
164 bool usrp_set_fpga_rx_reset (struct libusb_device_handle *udh, bool on);
165 bool usrp_set_led (struct libusb_device_handle *udh, int which, bool on);
167 bool usrp_check_rx_overrun (struct libusb_device_handle *udh, bool *overrun_p);
168 bool usrp_check_tx_underrun (struct libusb_device_handle *udh, bool *underrun_p);
170 // i2c_read and i2c_write are limited to a maximum len of 64 bytes.
172 bool usrp_i2c_write (struct libusb_device_handle *udh, int i2c_addr,
173 const void *buf, int len);
175 bool usrp_i2c_read (struct libusb_device_handle *udh, int i2c_addr,
178 // spi_read and spi_write are limited to a maximum of 64 bytes
179 // See usrp_spi_defs.h for more info
181 bool usrp_spi_write (struct libusb_device_handle *udh,
182 int optional_header, int enables, int format,
183 const void *buf, int len);
185 bool usrp_spi_read (struct libusb_device_handle *udh,
186 int optional_header, int enables, int format,
190 bool usrp_9862_write (struct libusb_device_handle *udh,
191 int which_codec, // [0, 1]
192 int regno, // [0, 63]
193 int value); // [0, 255]
195 bool usrp_9862_read (struct libusb_device_handle *udh,
196 int which_codec, // [0, 1]
197 int regno, // [0, 63]
198 unsigned char *value); // [0, 255]
201 * \brief Write multiple 9862 regs at once.
203 * \p buf contains alternating register_number, register_value pairs.
204 * \p len must be even and is the length of buf in bytes.
206 bool usrp_9862_write_many (struct libusb_device_handle *udh, int which_codec,
207 const unsigned char *buf, int len);
211 * \brief write specified regs to all 9862's in the system
213 bool usrp_9862_write_many_all (struct libusb_device_handle *udh,
214 const unsigned char *buf, int len);
217 // Write 24LC024 / 24LC025 EEPROM on motherboard or daughterboard.
218 // Which EEPROM is determined by i2c_addr. See i2c_addr.h
220 bool usrp_eeprom_write (struct libusb_device_handle *udh, int i2c_addr,
221 int eeprom_offset, const void *buf, int len);
224 // Read 24LC024 / 24LC025 EEPROM on motherboard or daughterboard.
225 // Which EEPROM is determined by i2c_addr. See i2c_addr.h
227 bool usrp_eeprom_read (struct libusb_device_handle *udh, int i2c_addr,
228 int eeprom_offset, void *buf, int len);
231 // Slot specific i/o routines
234 * \brief write to the specified aux dac.
236 * \p slot: which Tx or Rx slot to write.
237 * N.B., SLOT_TX_A and SLOT_RX_A share the same AUX DAC's
238 * SLOT_TX_B and SLOT_RX_B share the same AUX DAC's
240 * \p which_dac: [0,3] RX slots must use only 0 and 1.
241 * TX slots must use only 2 and 3.
243 * AUX DAC 3 is really the 9862 sigma delta output.
245 * \p value to write to aux dac. All dacs take straight
246 * binary values. Although dacs 0, 1 and 2 are 8-bit and dac 3 is 12-bit,
247 * the interface is in terms of 12-bit values [0,4095]
249 bool usrp_write_aux_dac (struct libusb_device_handle *uhd, int slot,
250 int which_dac, int value);
253 * \brief Read the specified aux adc
255 * \p slot: which Tx or Rx slot to read aux dac
256 * \p which_adc: [0,1] which of the two adcs to read
257 * \p *value: return value, 12-bit straight binary.
259 bool usrp_read_aux_adc (struct libusb_device_handle *udh, int slot,
260 int which_adc, int *value);
264 * \brief usrp daughterboard id to name mapping
266 const std::string usrp_dbid_to_string (int dbid);
269 enum usrp_dbeeprom_status_t { UDBE_OK, UDBE_BAD_SLOT, UDBE_NO_EEPROM, UDBE_INVALID_EEPROM };
271 struct usrp_dboard_eeprom {
272 unsigned short id; // d'board identifier code
273 unsigned short oe; // fpga output enables:
274 // If bit set, i/o pin is an output from FPGA.
275 short offset[2]; // ADC/DAC offset correction
279 * \brief Read and return parsed daughterboard eeprom
281 usrp_dbeeprom_status_t
282 usrp_read_dboard_eeprom (struct libusb_device_handle *udh,
283 int slot_id, usrp_dboard_eeprom *eeprom);
286 * \brief write ADC/DAC offset calibration constants to d'board eeprom
288 bool usrp_write_dboard_offsets (struct libusb_device_handle *udh, int slot_id,
289 short offset0, short offset1);
292 * \brief return a usrp's serial number.
294 * Note that this only works on a configured usrp.
295 * \returns non-zero length string iff successful.
297 std::string usrp_serial_number(struct libusb_device_handle *udh);
299 #endif /* _USRP_PRIMS_H_ */