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 */