drivers/net/wireless/ralink/rt2x00/rt2x00usb.h

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