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