drivers/net/wireless/rt2x00/rt2x00usb.h

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