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