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