drivers/usb/wusbcore/wa-hc.h

   1 /*
   2  * HWA Host Controller Driver
   3  * Wire Adapter Control/Data Streaming Iface (WUSB1.0[8])
   4  *
   5  * Copyright (C) 2005-2006 Intel Corporation
   6  * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License version
  10  * 2 as published by the Free Software Foundation.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20  * 02110-1301, USA.
  21  *
  22  *
  23  * This driver implements a USB Host Controller (struct usb_hcd) for a
  24  * Wireless USB Host Controller based on the Wireless USB 1.0
  25  * Host-Wire-Adapter specification (in layman terms, a USB-dongle that
  26  * implements a Wireless USB host).
  27  *
  28  * Check out the Design-overview.txt file in the source documentation
  29  * for other details on the implementation.
  30  *
  31  * Main blocks:
  32  *
  33  *  driver     glue with the driver API, workqueue daemon
  34  *
  35  *  lc         RC instance life cycle management (create, destroy...)
  36  *
  37  *  hcd        glue with the USB API Host Controller Interface API.
  38  *
  39  *  nep        Notification EndPoint management: collect notifications
  40  *             and queue them with the workqueue daemon.
  41  *
  42  *             Handle notifications as coming from the NEP. Sends them
  43  *             off others to their respective modules (eg: connect,
  44  *             disconnect and reset go to devconnect).
  45  *
  46  *  rpipe      Remote Pipe management; rpipe is what we use to write
  47  *             to an endpoint on a WUSB device that is connected to a
  48  *             HWA RC.
  49  *
  50  *  xfer       Transfer management -- this is all the code that gets a
  51  *             buffer and pushes it to a device (or viceversa). *
  52  *
  53  * Some day a lot of this code will be shared between this driver and
  54  * the drivers for DWA (xfer, rpipe).
  55  *
  56  * All starts at driver.c:hwahc_probe(), when one of this guys is
  57  * connected. hwahc_disconnect() stops it.
  58  *
  59  * During operation, the main driver is devices connecting or
  60  * disconnecting. They cause the HWA RC to send notifications into
  61  * nep.c:hwahc_nep_cb() that will dispatch them to
  62  * notif.c:wa_notif_dispatch(). From there they will fan to cause
  63  * device connects, disconnects, etc.
  64  *
  65  * Note much of the activity is difficult to follow. For example a
  66  * device connect goes to devconnect, which will cause the "fake" root
  67  * hub port to show a connect and stop there. Then hub_wq will notice
  68  * and call into the rh.c:hwahc_rc_port_reset() code to authenticate
  69  * the device (and this might require user intervention) and enable
  70  * the port.
  71  *
  72  * We also have a timer workqueue going from devconnect.c that
  73  * schedules in hwahc_devconnect_create().
  74  *
  75  * The rest of the traffic is in the usual entry points of a USB HCD,
  76  * which are hooked up in driver.c:hwahc_rc_driver, and defined in
  77  * hcd.c.
  78  */
  79
  80 #ifndef __HWAHC_INTERNAL_H__
  81 #define __HWAHC_INTERNAL_H__
  82
  83 #include <linux/completion.h>
  84 #include <linux/usb.h>
  85 #include <linux/mutex.h>
  86 #include <linux/spinlock.h>
  87 #include <linux/uwb.h>
  88 #include <linux/usb/wusb.h>
  89 #include <linux/usb/wusb-wa.h>
  90
  91 struct wusbhc;
  92 struct wahc;
  93 extern void wa_urb_enqueue_run(struct work_struct *ws);
  94 extern void wa_process_errored_transfers_run(struct work_struct *ws);
  95
  96 /**
  97  * RPipe instance
  98  *
  99  * @descr's fields are kept in LE, as we need to send it back and
 100  * forth.
 101  *
 102  * @wa is referenced when set
 103  *
 104  * @segs_available is the number of requests segments that still can
 105  *                 be submitted to the controller without overloading
 106  *                 it. It is initialized to descr->wRequests when
 107  *                 aiming.
 108  *
 109  * A rpipe supports a max of descr->wRequests at the same time; before
 110  * submitting seg_lock has to be taken. If segs_avail > 0, then we can
 111  * submit; if not, we have to queue them.
 112  */
 113 struct wa_rpipe {
 114         struct kref refcnt;
 115         struct usb_rpipe_descriptor descr;
 116         struct usb_host_endpoint *ep;
 117         struct wahc *wa;
 118         spinlock_t seg_lock;
 119         struct list_head seg_list;
 120         struct list_head list_node;
 121         atomic_t segs_available;
 122         u8 buffer[1];   /* For reads/writes on USB */
 123 };
 124
 125
 126 enum wa_dti_state {
 127         WA_DTI_TRANSFER_RESULT_PENDING,
 128         WA_DTI_ISOC_PACKET_STATUS_PENDING,
 129         WA_DTI_BUF_IN_DATA_PENDING
 130 };
 131
 132 enum wa_quirks {
 133         /*
 134          * The Alereon HWA expects the data frames in isochronous transfer
 135          * requests to be concatenated and not sent as separate packets.
 136          */
 137         WUSB_QUIRK_ALEREON_HWA_CONCAT_ISOC      = 0x01,
 138         /*
 139          * The Alereon HWA can be instructed to not send transfer notifications
 140          * as an optimization.
 141          */
 142         WUSB_QUIRK_ALEREON_HWA_DISABLE_XFER_NOTIFICATIONS       = 0x02,
 143 };
 144
 145 enum wa_vendor_specific_requests {
 146         WA_REQ_ALEREON_DISABLE_XFER_NOTIFICATIONS = 0x4C,
 147         WA_REQ_ALEREON_FEATURE_SET = 0x01,
 148         WA_REQ_ALEREON_FEATURE_CLEAR = 0x00,
 149 };
 150
 151 #define WA_MAX_BUF_IN_URBS      4
 152 /**
 153  * Instance of a HWA Host Controller
 154  *
 155  * Except where a more specific lock/mutex applies or atomic, all
 156  * fields protected by @mutex.
 157  *
 158  * @wa_descr  Can be accessed without locking because it is in
 159  *            the same area where the device descriptors were
 160  *            read, so it is guaranteed to exist unmodified while
 161  *            the device exists.
 162  *
 163  *            Endianess has been converted to CPU's.
 164  *
 165  * @nep_* can be accessed without locking as its processing is
 166  *        serialized; we submit a NEP URB and it comes to
 167  *        hwahc_nep_cb(), which won't issue another URB until it is
 168  *        done processing it.
 169  *
 170  * @xfer_list:
 171  *
 172  *   List of active transfers to verify existence from a xfer id
 173  *   gotten from the xfer result message. Can't use urb->list because
 174  *   it goes by endpoint, and we don't know the endpoint at the time
 175  *   when we get the xfer result message. We can't really rely on the
 176  *   pointer (will have to change for 64 bits) as the xfer id is 32 bits.
 177  *
 178  * @xfer_delayed_list:   List of transfers that need to be started
 179  *                       (with a workqueue, because they were
 180  *                       submitted from an atomic context).
 181  *
 182  * FIXME: this needs to be layered up: a wusbhc layer (for sharing
 183  *        commonalities with WHCI), a wa layer (for sharing
 184  *        commonalities with DWA-RC).
 185  */
 186 struct wahc {
 187         struct usb_device *usb_dev;
 188         struct usb_interface *usb_iface;
 189
 190         /* HC to deliver notifications */
 191         union {
 192                 struct wusbhc *wusb;
 193                 struct dwahc *dwa;
 194         };
 195
 196         const struct usb_endpoint_descriptor *dto_epd, *dti_epd;
 197         const struct usb_wa_descriptor *wa_descr;
 198
 199         struct urb *nep_urb;            /* Notification EndPoint [lockless] */
 200         struct edc nep_edc;
 201         void *nep_buffer;
 202         size_t nep_buffer_size;
 203
 204         atomic_t notifs_queued;
 205
 206         u16 rpipes;
 207         unsigned long *rpipe_bm;        /* rpipe usage bitmap */
 208         struct list_head rpipe_delayed_list;    /* delayed RPIPES. */
 209         spinlock_t rpipe_lock;  /* protect rpipe_bm and delayed list */
 210         struct mutex rpipe_mutex;       /* assigning resources to endpoints */
 211
 212         /*
 213          * dti_state is used to track the state of the dti_urb. When dti_state
 214          * is WA_DTI_ISOC_PACKET_STATUS_PENDING, dti_isoc_xfer_in_progress and
 215          * dti_isoc_xfer_seg identify which xfer the incoming isoc packet
 216          * status refers to.
 217          */
 218         enum wa_dti_state dti_state;
 219         u32 dti_isoc_xfer_in_progress;
 220         u8  dti_isoc_xfer_seg;
 221         struct urb *dti_urb;            /* URB for reading xfer results */
 222                                         /* URBs for reading data in */
 223         struct urb buf_in_urbs[WA_MAX_BUF_IN_URBS];
 224         int active_buf_in_urbs;         /* number of buf_in_urbs active. */
 225         struct edc dti_edc;             /* DTI error density counter */
 226         void *dti_buf;
 227         size_t dti_buf_size;
 228
 229         unsigned long dto_in_use;       /* protect dto endoint serialization */
 230
 231         s32 status;                     /* For reading status */
 232
 233         struct list_head xfer_list;
 234         struct list_head xfer_delayed_list;
 235         struct list_head xfer_errored_list;
 236         /*
 237          * lock for the above xfer lists.  Can be taken while a xfer->lock is
 238          * held but not in the reverse order.
 239          */
 240         spinlock_t xfer_list_lock;
 241         struct work_struct xfer_enqueue_work;
 242         struct work_struct xfer_error_work;
 243         atomic_t xfer_id_count;
 244
 245         kernel_ulong_t  quirks;
 246 };
 247
 248
 249 extern int wa_create(struct wahc *wa, struct usb_interface *iface,
 250         kernel_ulong_t);
 251 extern void __wa_destroy(struct wahc *wa);
 252 extern int wa_dti_start(struct wahc *wa);
 253 void wa_reset_all(struct wahc *wa);
 254
 255
 256 /* Miscellaneous constants */
 257 enum {
 258         /** Max number of EPROTO errors we tolerate on the NEP in a
 259          * period of time */
 260         HWAHC_EPROTO_MAX = 16,
 261         /** Period of time for EPROTO errors (in jiffies) */
 262         HWAHC_EPROTO_PERIOD = 4 * HZ,
 263 };
 264
 265
 266 /* Notification endpoint handling */
 267 extern int wa_nep_create(struct wahc *, struct usb_interface *);
 268 extern void wa_nep_destroy(struct wahc *);
 269
 270 static inline int wa_nep_arm(struct wahc *wa, gfp_t gfp_mask)
 271 {
 272         struct urb *urb = wa->nep_urb;
 273         urb->transfer_buffer = wa->nep_buffer;
 274         urb->transfer_buffer_length = wa->nep_buffer_size;
 275         return usb_submit_urb(urb, gfp_mask);
 276 }
 277
 278 static inline void wa_nep_disarm(struct wahc *wa)
 279 {
 280         usb_kill_urb(wa->nep_urb);
 281 }
 282
 283
 284 /* RPipes */
 285 static inline void wa_rpipe_init(struct wahc *wa)
 286 {
 287         INIT_LIST_HEAD(&wa->rpipe_delayed_list);
 288         spin_lock_init(&wa->rpipe_lock);
 289         mutex_init(&wa->rpipe_mutex);
 290 }
 291
 292 static inline void wa_init(struct wahc *wa)
 293 {
 294         int index;
 295
 296         edc_init(&wa->nep_edc);
 297         atomic_set(&wa->notifs_queued, 0);
 298         wa->dti_state = WA_DTI_TRANSFER_RESULT_PENDING;
 299         wa_rpipe_init(wa);
 300         edc_init(&wa->dti_edc);
 301         INIT_LIST_HEAD(&wa->xfer_list);
 302         INIT_LIST_HEAD(&wa->xfer_delayed_list);
 303         INIT_LIST_HEAD(&wa->xfer_errored_list);
 304         spin_lock_init(&wa->xfer_list_lock);
 305         INIT_WORK(&wa->xfer_enqueue_work, wa_urb_enqueue_run);
 306         INIT_WORK(&wa->xfer_error_work, wa_process_errored_transfers_run);
 307         wa->dto_in_use = 0;
 308         atomic_set(&wa->xfer_id_count, 1);
 309         /* init the buf in URBs */
 310         for (index = 0; index < WA_MAX_BUF_IN_URBS; ++index)
 311                 usb_init_urb(&(wa->buf_in_urbs[index]));
 312         wa->active_buf_in_urbs = 0;
 313 }
 314
 315 /**
 316  * Destroy a pipe (when refcount drops to zero)
 317  *
 318  * Assumes it has been moved to the "QUIESCING" state.
 319  */
 320 struct wa_xfer;
 321 extern void rpipe_destroy(struct kref *_rpipe);
 322 static inline
 323 void __rpipe_get(struct wa_rpipe *rpipe)
 324 {
 325         kref_get(&rpipe->refcnt);
 326 }
 327 extern int rpipe_get_by_ep(struct wahc *, struct usb_host_endpoint *,
 328                            struct urb *, gfp_t);
 329 static inline void rpipe_put(struct wa_rpipe *rpipe)
 330 {
 331         kref_put(&rpipe->refcnt, rpipe_destroy);
 332
 333 }
 334 extern void rpipe_ep_disable(struct wahc *, struct usb_host_endpoint *);
 335 extern void rpipe_clear_feature_stalled(struct wahc *,
 336                         struct usb_host_endpoint *);
 337 extern int wa_rpipes_create(struct wahc *);
 338 extern void wa_rpipes_destroy(struct wahc *);
 339 static inline void rpipe_avail_dec(struct wa_rpipe *rpipe)
 340 {
 341         atomic_dec(&rpipe->segs_available);
 342 }
 343
 344 /**
 345  * Returns true if the rpipe is ready to submit more segments.
 346  */
 347 static inline int rpipe_avail_inc(struct wa_rpipe *rpipe)
 348 {
 349         return atomic_inc_return(&rpipe->segs_available) > 0
 350                 && !list_empty(&rpipe->seg_list);
 351 }
 352
 353
 354 /* Transferring data */
 355 extern int wa_urb_enqueue(struct wahc *, struct usb_host_endpoint *,
 356                           struct urb *, gfp_t);
 357 extern int wa_urb_dequeue(struct wahc *, struct urb *, int);
 358 extern void wa_handle_notif_xfer(struct wahc *, struct wa_notif_hdr *);
 359
 360
 361 /* Misc
 362  *
 363  * FIXME: Refcounting for the actual @hwahc object is not correct; I
 364  *        mean, this should be refcounting on the HCD underneath, but
 365  *        it is not. In any case, the semantics for HCD refcounting
 366  *        are *weird*...on refcount reaching zero it just frees
 367  *        it...no RC specific function is called...unless I miss
 368  *        something.
 369  *
 370  * FIXME: has to go away in favour of a 'struct' hcd based solution
 371  */
 372 static inline struct wahc *wa_get(struct wahc *wa)
 373 {
 374         usb_get_intf(wa->usb_iface);
 375         return wa;
 376 }
 377
 378 static inline void wa_put(struct wahc *wa)
 379 {
 380         usb_put_intf(wa->usb_iface);
 381 }
 382
 383
 384 static inline int __wa_feature(struct wahc *wa, unsigned op, u16 feature)
 385 {
 386         return usb_control_msg(wa->usb_dev, usb_sndctrlpipe(wa->usb_dev, 0),
 387                         op ? USB_REQ_SET_FEATURE : USB_REQ_CLEAR_FEATURE,
 388                         USB_DIR_OUT | USB_TYPE_CLASS | USB_RECIP_INTERFACE,
 389                         feature,
 390                         wa->usb_iface->cur_altsetting->desc.bInterfaceNumber,
 391                         NULL, 0, USB_CTRL_SET_TIMEOUT);
 392 }
 393
 394
 395 static inline int __wa_set_feature(struct wahc *wa, u16 feature)
 396 {
 397         return  __wa_feature(wa, 1, feature);
 398 }
 399
 400
 401 static inline int __wa_clear_feature(struct wahc *wa, u16 feature)
 402 {
 403         return __wa_feature(wa, 0, feature);
 404 }
 405
 406
 407 /**
 408  * Return the status of a Wire Adapter
 409  *
 410  * @wa:         Wire Adapter instance
 411  * @returns     < 0 errno code on error, or status bitmap as described
 412  *              in WUSB1.0[8.3.1.6].
 413  *
 414  * NOTE: need malloc, some arches don't take USB from the stack
 415  */
 416 static inline
 417 s32 __wa_get_status(struct wahc *wa)
 418 {
 419         s32 result;
 420         result = usb_control_msg(
 421                 wa->usb_dev, usb_rcvctrlpipe(wa->usb_dev, 0),
 422                 USB_REQ_GET_STATUS,
 423                 USB_DIR_IN | USB_TYPE_CLASS | USB_RECIP_INTERFACE,
 424                 0, wa->usb_iface->cur_altsetting->desc.bInterfaceNumber,
 425                 &wa->status, sizeof(wa->status), USB_CTRL_GET_TIMEOUT);
 426         if (result >= 0)
 427                 result = wa->status;
 428         return result;
 429 }
 430
 431
 432 /**
 433  * Waits until the Wire Adapter's status matches @mask/@value
 434  *
 435  * @wa:         Wire Adapter instance.
 436  * @returns     < 0 errno code on error, otherwise status.
 437  *
 438  * Loop until the WAs status matches the mask and value (status & mask
 439  * == value). Timeout if it doesn't happen.
 440  *
 441  * FIXME: is there an official specification on how long status
 442  *        changes can take?
 443  */
 444 static inline s32 __wa_wait_status(struct wahc *wa, u32 mask, u32 value)
 445 {
 446         s32 result;
 447         unsigned loops = 10;
 448         do {
 449                 msleep(50);
 450                 result = __wa_get_status(wa);
 451                 if ((result & mask) == value)
 452                         break;
 453                 if (loops-- == 0) {
 454                         result = -ETIMEDOUT;
 455                         break;
 456                 }
 457         } while (result >= 0);
 458         return result;
 459 }
 460
 461
 462 /** Command @hwahc to stop, @returns 0 if ok, < 0 errno code on error */
 463 static inline int __wa_stop(struct wahc *wa)
 464 {
 465         int result;
 466         struct device *dev = &wa->usb_iface->dev;
 467
 468         result = __wa_clear_feature(wa, WA_ENABLE);
 469         if (result < 0 && result != -ENODEV) {
 470                 dev_err(dev, "error commanding HC to stop: %d\n", result);
 471                 goto out;
 472         }
 473         result = __wa_wait_status(wa, WA_ENABLE, 0);
 474         if (result < 0 && result != -ENODEV)
 475                 dev_err(dev, "error waiting for HC to stop: %d\n", result);
 476 out:
 477         return 0;
 478 }
 479
 480
 481 #endif /* #ifndef __HWAHC_INTERNAL_H__ */