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