Merge branch 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/linville/wirel...
[linux-2.6.git] / drivers / net / wireless / rt2x00 / rt2x00usb.h
1 /*
2         Copyright (C) 2004 - 2009 Ivo van Doorn <IvDoorn@gmail.com>
3         <http://rt2x00.serialmonkey.com>
4
5         This program is free software; you can redistribute it and/or modify
6         it under the terms of the GNU General Public License as published by
7         the Free Software Foundation; either version 2 of the License, or
8         (at your option) any later version.
9
10         This program is distributed in the hope that it will be useful,
11         but WITHOUT ANY WARRANTY; without even the implied warranty of
12         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13         GNU General Public License for more details.
14
15         You should have received a copy of the GNU General Public License
16         along with this program; if not, write to the
17         Free Software Foundation, Inc.,
18         59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
19  */
20
21 /*
22         Module: rt2x00usb
23         Abstract: Data structures for the rt2x00usb module.
24  */
25
26 #ifndef RT2X00USB_H
27 #define RT2X00USB_H
28
29 #include <linux/usb.h>
30
31 #define to_usb_device_intf(d) \
32 ({ \
33         struct usb_interface *intf = to_usb_interface(d); \
34         interface_to_usbdev(intf); \
35 })
36
37 /*
38  * For USB vendor requests we need to pass a timeout
39  * time in ms, for this we use the REGISTER_TIMEOUT,
40  * however when loading firmware a higher value is
41  * required. In that case we use the REGISTER_TIMEOUT_FIRMWARE.
42  */
43 #define REGISTER_TIMEOUT                500
44 #define REGISTER_TIMEOUT_FIRMWARE       1000
45
46 /**
47  * REGISTER_TIMEOUT16 - Determine the timeout for 16bit register access
48  * @__datalen: Data length
49  */
50 #define REGISTER_TIMEOUT16(__datalen)   \
51         ( REGISTER_TIMEOUT * ((__datalen) / sizeof(u16)) )
52
53 /**
54  * REGISTER_TIMEOUT32 - Determine the timeout for 32bit register access
55  * @__datalen: Data length
56  */
57 #define REGISTER_TIMEOUT32(__datalen)   \
58         ( REGISTER_TIMEOUT * ((__datalen) / sizeof(u32)) )
59
60 /*
61  * Cache size
62  */
63 #define CSR_CACHE_SIZE                  64
64
65 /*
66  * USB request types.
67  */
68 #define USB_VENDOR_REQUEST      ( USB_TYPE_VENDOR | USB_RECIP_DEVICE )
69 #define USB_VENDOR_REQUEST_IN   ( USB_DIR_IN | USB_VENDOR_REQUEST )
70 #define USB_VENDOR_REQUEST_OUT  ( USB_DIR_OUT | USB_VENDOR_REQUEST )
71
72 /**
73  * enum rt2x00usb_vendor_request: USB vendor commands.
74  */
75 enum rt2x00usb_vendor_request {
76         USB_DEVICE_MODE = 1,
77         USB_SINGLE_WRITE = 2,
78         USB_SINGLE_READ = 3,
79         USB_MULTI_WRITE = 6,
80         USB_MULTI_READ = 7,
81         USB_EEPROM_WRITE = 8,
82         USB_EEPROM_READ = 9,
83         USB_LED_CONTROL = 10, /* RT73USB */
84         USB_RX_CONTROL = 12,
85 };
86
87 /**
88  * enum rt2x00usb_mode_offset: Device modes offset.
89  */
90 enum rt2x00usb_mode_offset {
91         USB_MODE_RESET = 1,
92         USB_MODE_UNPLUG = 2,
93         USB_MODE_FUNCTION = 3,
94         USB_MODE_TEST = 4,
95         USB_MODE_SLEEP = 7,     /* RT73USB */
96         USB_MODE_FIRMWARE = 8,  /* RT73USB */
97         USB_MODE_WAKEUP = 9,    /* RT73USB */
98 };
99
100 /**
101  * rt2x00usb_vendor_request - Send register command to device
102  * @rt2x00dev: Pointer to &struct rt2x00_dev
103  * @request: USB vendor command (See &enum rt2x00usb_vendor_request)
104  * @requesttype: Request type &USB_VENDOR_REQUEST_*
105  * @offset: Register offset to perform action on
106  * @value: Value to write to device
107  * @buffer: Buffer where information will be read/written to by device
108  * @buffer_length: Size of &buffer
109  * @timeout: Operation timeout
110  *
111  * This is the main function to communicate with the device,
112  * the &buffer argument _must_ either be NULL or point to
113  * a buffer allocated by kmalloc. Failure to do so can lead
114  * to unexpected behavior depending on the architecture.
115  */
116 int rt2x00usb_vendor_request(struct rt2x00_dev *rt2x00dev,
117                              const u8 request, const u8 requesttype,
118                              const u16 offset, const u16 value,
119                              void *buffer, const u16 buffer_length,
120                              const int timeout);
121
122 /**
123  * rt2x00usb_vendor_request_buff - Send register command to device (buffered)
124  * @rt2x00dev: Pointer to &struct rt2x00_dev
125  * @request: USB vendor command (See &enum rt2x00usb_vendor_request)
126  * @requesttype: Request type &USB_VENDOR_REQUEST_*
127  * @offset: Register offset to perform action on
128  * @buffer: Buffer where information will be read/written to by device
129  * @buffer_length: Size of &buffer
130  * @timeout: Operation timeout
131  *
132  * This function will use a previously with kmalloc allocated cache
133  * to communicate with the device. The contents of the buffer pointer
134  * will be copied to this cache when writing, or read from the cache
135  * when reading.
136  * Buffers send to &rt2x00usb_vendor_request _must_ be allocated with
137  * kmalloc. Hence the reason for using a previously allocated cache
138  * which has been allocated properly.
139  */
140 int rt2x00usb_vendor_request_buff(struct rt2x00_dev *rt2x00dev,
141                                   const u8 request, const u8 requesttype,
142                                   const u16 offset, void *buffer,
143                                   const u16 buffer_length, const int timeout);
144
145 /**
146  * rt2x00usb_vendor_request_buff - Send register command to device (buffered)
147  * @rt2x00dev: Pointer to &struct rt2x00_dev
148  * @request: USB vendor command (See &enum rt2x00usb_vendor_request)
149  * @requesttype: Request type &USB_VENDOR_REQUEST_*
150  * @offset: Register offset to perform action on
151  * @buffer: Buffer where information will be read/written to by device
152  * @buffer_length: Size of &buffer
153  * @timeout: Operation timeout
154  *
155  * A version of &rt2x00usb_vendor_request_buff which must be called
156  * if the usb_cache_mutex is already held.
157  */
158 int rt2x00usb_vendor_req_buff_lock(struct rt2x00_dev *rt2x00dev,
159                                    const u8 request, const u8 requesttype,
160                                    const u16 offset, void *buffer,
161                                    const u16 buffer_length, const int timeout);
162
163 /**
164  * rt2x00usb_vendor_request_sw - Send single register command to device
165  * @rt2x00dev: Pointer to &struct rt2x00_dev
166  * @request: USB vendor command (See &enum rt2x00usb_vendor_request)
167  * @offset: Register offset to perform action on
168  * @value: Value to write to device
169  * @timeout: Operation timeout
170  *
171  * Simple wrapper around rt2x00usb_vendor_request to write a single
172  * command to the device. Since we don't use the buffer argument we
173  * don't have to worry about kmalloc here.
174  */
175 static inline int rt2x00usb_vendor_request_sw(struct rt2x00_dev *rt2x00dev,
176                                               const u8 request,
177                                               const u16 offset,
178                                               const u16 value,
179                                               const int timeout)
180 {
181         return rt2x00usb_vendor_request(rt2x00dev, request,
182                                         USB_VENDOR_REQUEST_OUT, offset,
183                                         value, NULL, 0, timeout);
184 }
185
186 /**
187  * rt2x00usb_eeprom_read - Read eeprom from device
188  * @rt2x00dev: Pointer to &struct rt2x00_dev
189  * @eeprom: Pointer to eeprom array to store the information in
190  * @length: Number of bytes to read from the eeprom
191  *
192  * Simple wrapper around rt2x00usb_vendor_request to read the eeprom
193  * from the device. Note that the eeprom argument _must_ be allocated using
194  * kmalloc for correct handling inside the kernel USB layer.
195  */
196 static inline int rt2x00usb_eeprom_read(struct rt2x00_dev *rt2x00dev,
197                                         __le16 *eeprom, const u16 length)
198 {
199         return rt2x00usb_vendor_request(rt2x00dev, USB_EEPROM_READ,
200                                         USB_VENDOR_REQUEST_IN, 0, 0,
201                                         eeprom, length,
202                                         REGISTER_TIMEOUT16(length));
203 }
204
205 /**
206  * rt2x00usb_register_read - Read 32bit register word
207  * @rt2x00dev: Device pointer, see &struct rt2x00_dev.
208  * @offset: Register offset
209  * @value: Pointer to where register contents should be stored
210  *
211  * This function is a simple wrapper for 32bit register access
212  * through rt2x00usb_vendor_request_buff().
213  */
214 static inline void rt2x00usb_register_read(struct rt2x00_dev *rt2x00dev,
215                                            const unsigned int offset,
216                                            u32 *value)
217 {
218         __le32 reg;
219         rt2x00usb_vendor_request_buff(rt2x00dev, USB_MULTI_READ,
220                                       USB_VENDOR_REQUEST_IN, offset,
221                                       &reg, sizeof(reg), REGISTER_TIMEOUT);
222         *value = le32_to_cpu(reg);
223 }
224
225 /**
226  * rt2x00usb_register_read_lock - Read 32bit register word
227  * @rt2x00dev: Device pointer, see &struct rt2x00_dev.
228  * @offset: Register offset
229  * @value: Pointer to where register contents should be stored
230  *
231  * This function is a simple wrapper for 32bit register access
232  * through rt2x00usb_vendor_req_buff_lock().
233  */
234 static inline void rt2x00usb_register_read_lock(struct rt2x00_dev *rt2x00dev,
235                                                 const unsigned int offset,
236                                                 u32 *value)
237 {
238         __le32 reg;
239         rt2x00usb_vendor_req_buff_lock(rt2x00dev, USB_MULTI_READ,
240                                        USB_VENDOR_REQUEST_IN, offset,
241                                        &reg, sizeof(reg), REGISTER_TIMEOUT);
242         *value = le32_to_cpu(reg);
243 }
244
245 /**
246  * rt2x00usb_register_multiread - Read 32bit register words
247  * @rt2x00dev: Device pointer, see &struct rt2x00_dev.
248  * @offset: Register offset
249  * @value: Pointer to where register contents should be stored
250  * @length: Length of the data
251  *
252  * This function is a simple wrapper for 32bit register access
253  * through rt2x00usb_vendor_request_buff().
254  */
255 static inline void rt2x00usb_register_multiread(struct rt2x00_dev *rt2x00dev,
256                                                 const unsigned int offset,
257                                                 void *value, const u32 length)
258 {
259         rt2x00usb_vendor_request_buff(rt2x00dev, USB_MULTI_READ,
260                                       USB_VENDOR_REQUEST_IN, offset,
261                                       value, length,
262                                       REGISTER_TIMEOUT32(length));
263 }
264
265 /**
266  * rt2x00usb_register_write - Write 32bit register word
267  * @rt2x00dev: Device pointer, see &struct rt2x00_dev.
268  * @offset: Register offset
269  * @value: Data which should be written
270  *
271  * This function is a simple wrapper for 32bit register access
272  * through rt2x00usb_vendor_request_buff().
273  */
274 static inline void rt2x00usb_register_write(struct rt2x00_dev *rt2x00dev,
275                                             const unsigned int offset,
276                                             u32 value)
277 {
278         __le32 reg = cpu_to_le32(value);
279         rt2x00usb_vendor_request_buff(rt2x00dev, USB_MULTI_WRITE,
280                                       USB_VENDOR_REQUEST_OUT, offset,
281                                       &reg, sizeof(reg), REGISTER_TIMEOUT);
282 }
283
284 /**
285  * rt2x00usb_register_write_lock - Write 32bit register word
286  * @rt2x00dev: Device pointer, see &struct rt2x00_dev.
287  * @offset: Register offset
288  * @value: Data which should be written
289  *
290  * This function is a simple wrapper for 32bit register access
291  * through rt2x00usb_vendor_req_buff_lock().
292  */
293 static inline void rt2x00usb_register_write_lock(struct rt2x00_dev *rt2x00dev,
294                                                  const unsigned int offset,
295                                                  u32 value)
296 {
297         __le32 reg = cpu_to_le32(value);
298         rt2x00usb_vendor_req_buff_lock(rt2x00dev, USB_MULTI_WRITE,
299                                        USB_VENDOR_REQUEST_OUT, offset,
300                                        &reg, sizeof(reg), REGISTER_TIMEOUT);
301 }
302
303 /**
304  * rt2x00usb_register_multiwrite - Write 32bit register words
305  * @rt2x00dev: Device pointer, see &struct rt2x00_dev.
306  * @offset: Register offset
307  * @value: Data which should be written
308  * @length: Length of the data
309  *
310  * This function is a simple wrapper for 32bit register access
311  * through rt2x00usb_vendor_request_buff().
312  */
313 static inline void rt2x00usb_register_multiwrite(struct rt2x00_dev *rt2x00dev,
314                                                  const unsigned int offset,
315                                                  const void *value,
316                                                  const u32 length)
317 {
318         rt2x00usb_vendor_request_buff(rt2x00dev, USB_MULTI_WRITE,
319                                       USB_VENDOR_REQUEST_OUT, offset,
320                                       (void *)value, length,
321                                       REGISTER_TIMEOUT32(length));
322 }
323
324 /**
325  * rt2x00usb_regbusy_read - Read from register with busy check
326  * @rt2x00dev: Device pointer, see &struct rt2x00_dev.
327  * @offset: Register offset
328  * @field: Field to check if register is busy
329  * @reg: Pointer to where register contents should be stored
330  *
331  * This function will read the given register, and checks if the
332  * register is busy. If it is, it will sleep for a couple of
333  * microseconds before reading the register again. If the register
334  * is not read after a certain timeout, this function will return
335  * FALSE.
336  */
337 int rt2x00usb_regbusy_read(struct rt2x00_dev *rt2x00dev,
338                            const unsigned int offset,
339                            const struct rt2x00_field32 field,
340                            u32 *reg);
341
342 /**
343  * rt2x00usb_register_read_async - Asynchronously read 32bit register word
344  * @rt2x00dev: Device pointer, see &struct rt2x00_dev.
345  * @offset: Register offset
346  * @callback: Functon to call when read completes.
347  *
348  * Submit a control URB to read a 32bit register. This safe to
349  * be called from atomic context.  The callback will be called
350  * when the URB completes. Otherwise the function is similar
351  * to rt2x00usb_register_read().
352  * When the callback function returns false, the memory will be cleaned up,
353  * when it returns true, the urb will be fired again.
354  */
355 void rt2x00usb_register_read_async(struct rt2x00_dev *rt2x00dev,
356                                    const unsigned int offset,
357                                    bool (*callback)(struct rt2x00_dev*, int, u32));
358
359 /*
360  * Radio handlers
361  */
362 void rt2x00usb_disable_radio(struct rt2x00_dev *rt2x00dev);
363
364 /**
365  * struct queue_entry_priv_usb: Per entry USB specific information
366  *
367  * @urb: Urb structure used for device communication.
368  */
369 struct queue_entry_priv_usb {
370         struct urb *urb;
371 };
372
373 /**
374  * struct queue_entry_priv_usb_bcn: Per TX entry USB specific information
375  *
376  * The first section should match &struct queue_entry_priv_usb exactly.
377  * rt2500usb can use this structure to send a guardian byte when working
378  * with beacons.
379  *
380  * @urb: Urb structure used for device communication.
381  * @guardian_data: Set to 0, used for sending the guardian data.
382  * @guardian_urb: Urb structure used to send the guardian data.
383  */
384 struct queue_entry_priv_usb_bcn {
385         struct urb *urb;
386
387         unsigned int guardian_data;
388         struct urb *guardian_urb;
389 };
390
391 /**
392  * rt2x00usb_kick_queue - Kick data queue
393  * @queue: Data queue to kick
394  *
395  * This will walk through all entries of the queue and push all pending
396  * frames to the hardware as a single burst.
397  */
398 void rt2x00usb_kick_queue(struct data_queue *queue);
399
400 /**
401  * rt2x00usb_flush_queue - Flush data queue
402  * @queue: Data queue to stop
403  * @drop: True to drop all pending frames.
404  *
405  * This will walk through all entries of the queue and will optionally
406  * kill all URB's which were send to the device, or at least wait until
407  * they have been returned from the device..
408  */
409 void rt2x00usb_flush_queue(struct data_queue *queue, bool drop);
410
411 /**
412  * rt2x00usb_watchdog - Watchdog for USB communication
413  * @rt2x00dev: Pointer to &struct rt2x00_dev
414  *
415  * Check the health of the USB communication and determine
416  * if timeouts have occurred. If this is the case, this function
417  * will reset all communication to restore functionality again.
418  */
419 void rt2x00usb_watchdog(struct rt2x00_dev *rt2x00dev);
420
421 /*
422  * Device initialization handlers.
423  */
424 void rt2x00usb_clear_entry(struct queue_entry *entry);
425 int rt2x00usb_initialize(struct rt2x00_dev *rt2x00dev);
426 void rt2x00usb_uninitialize(struct rt2x00_dev *rt2x00dev);
427
428 /*
429  * USB driver handlers.
430  */
431 int rt2x00usb_probe(struct usb_interface *usb_intf,
432                     const struct rt2x00_ops *ops);
433 void rt2x00usb_disconnect(struct usb_interface *usb_intf);
434 #ifdef CONFIG_PM
435 int rt2x00usb_suspend(struct usb_interface *usb_intf, pm_message_t state);
436 int rt2x00usb_resume(struct usb_interface *usb_intf);
437 #else
438 #define rt2x00usb_suspend       NULL
439 #define rt2x00usb_resume        NULL
440 #endif /* CONFIG_PM */
441
442 #endif /* RT2X00USB_H */