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 managent: 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 khubd 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 };
 130
 131 enum wa_quirks {
 132         /*
 133          * The Alereon HWA expects the data frames in isochronous transfer
 134          * requests to be concatenated and not sent as separate packets.
 135          */
 136         WUSB_QUIRK_ALEREON_HWA_CONCAT_ISOC      = 0x01,
 137 };
 138
 139 /**
 140  * Instance of a HWA Host Controller
 141  *
 142  * Except where a more specific lock/mutex applies or atomic, all
 143  * fields protected by @mutex.
 144  *
 145  * @wa_descr  Can be accessed without locking because it is in
 146  *            the same area where the device descriptors were
 147  *            read, so it is guaranteed to exist umodified while
 148  *            the device exists.
 149  *
 150  *            Endianess has been converted to CPU's.
 151  *
 152  * @nep_* can be accessed without locking as its processing is
 153  *        serialized; we submit a NEP URB and it comes to
 154  *        hwahc_nep_cb(), which won't issue another URB until it is
 155  *        done processing it.
 156  *
 157  * @xfer_list:
 158  *
 159  *   List of active transfers to verify existence from a xfer id
 160  *   gotten from the xfer result message. Can't use urb->list because
 161  *   it goes by endpoint, and we don't know the endpoint at the time
 162  *   when we get the xfer result message. We can't really rely on the
 163  *   pointer (will have to change for 64 bits) as the xfer id is 32 bits.
 164  *
 165  * @xfer_delayed_list:   List of transfers that need to be started
 166  *                       (with a workqueue, because they were
 167  *                       submitted from an atomic context).
 168  *
 169  * FIXME: this needs to be layered up: a wusbhc layer (for sharing
 170  *        comonalities with WHCI), a wa layer (for sharing
 171  *        comonalities with DWA-RC).
 172  */
 173 struct wahc {
 174         struct usb_device *usb_dev;
 175         struct usb_interface *usb_iface;
 176
 177         /* HC to deliver notifications */
 178         union {
 179                 struct wusbhc *wusb;
 180                 struct dwahc *dwa;
 181         };
 182
 183         const struct usb_endpoint_descriptor *dto_epd, *dti_epd;
 184         const struct usb_wa_descriptor *wa_descr;
 185
 186         struct urb *nep_urb;            /* Notification EndPoint [lockless] */
 187         struct edc nep_edc;
 188         void *nep_buffer;
 189         size_t nep_buffer_size;
 190
 191         atomic_t notifs_queued;
 192
 193         u16 rpipes;
 194         unsigned long *rpipe_bm;        /* rpipe usage bitmap */
 195         struct list_head rpipe_delayed_list;    /* delayed RPIPES. */
 196         spinlock_t rpipe_lock;  /* protect rpipe_bm and delayed list */
 197         struct mutex rpipe_mutex;       /* assigning resources to endpoints */
 198
 199         /*
 200          * dti_state is used to track the state of the dti_urb.  When dti_state
 201          * is WA_DTI_ISOC_PACKET_STATUS_PENDING, dti_isoc_xfer_in_progress and
 202          * dti_isoc_xfer_seg identify which xfer the incoming isoc packet status
 203          * refers to.
 204          */
 205         enum wa_dti_state dti_state;
 206         u32 dti_isoc_xfer_in_progress;
 207         u8  dti_isoc_xfer_seg;
 208         struct urb *dti_urb;            /* URB for reading xfer results */
 209         struct urb *buf_in_urb;         /* URB for reading data in */
 210         struct edc dti_edc;             /* DTI error density counter */
 211         void *dti_buf;
 212         size_t dti_buf_size;
 213
 214         unsigned long dto_in_use;       /* protect dto endoint serialization. */
 215
 216         s32 status;                     /* For reading status */
 217
 218         struct list_head xfer_list;
 219         struct list_head xfer_delayed_list;
 220         struct list_head xfer_errored_list;
 221         /*
 222          * lock for the above xfer lists.  Can be taken while a xfer->lock is
 223          * held but not in the reverse order.
 224          */
 225         spinlock_t xfer_list_lock;
 226         struct work_struct xfer_enqueue_work;
 227         struct work_struct xfer_error_work;
 228         atomic_t xfer_id_count;
 229
 230         kernel_ulong_t  quirks;
 231 };
 232
 233
 234 extern int wa_create(struct wahc *wa, struct usb_interface *iface,
 235         kernel_ulong_t);
 236 extern void __wa_destroy(struct wahc *wa);
 237 void wa_reset_all(struct wahc *wa);
 238
 239
 240 /* Miscellaneous constants */
 241 enum {
 242         /** Max number of EPROTO errors we tolerate on the NEP in a
 243          * period of time */
 244         HWAHC_EPROTO_MAX = 16,
 245         /** Period of time for EPROTO errors (in jiffies) */
 246         HWAHC_EPROTO_PERIOD = 4 * HZ,
 247 };
 248
 249
 250 /* Notification endpoint handling */
 251 extern int wa_nep_create(struct wahc *, struct usb_interface *);
 252 extern void wa_nep_destroy(struct wahc *);
 253
 254 static inline int wa_nep_arm(struct wahc *wa, gfp_t gfp_mask)
 255 {
 256         struct urb *urb = wa->nep_urb;
 257         urb->transfer_buffer = wa->nep_buffer;
 258         urb->transfer_buffer_length = wa->nep_buffer_size;
 259         return usb_submit_urb(urb, gfp_mask);
 260 }
 261
 262 static inline void wa_nep_disarm(struct wahc *wa)
 263 {
 264         usb_kill_urb(wa->nep_urb);
 265 }
 266
 267
 268 /* RPipes */
 269 static inline void wa_rpipe_init(struct wahc *wa)
 270 {
 271         INIT_LIST_HEAD(&wa->rpipe_delayed_list);
 272         spin_lock_init(&wa->rpipe_lock);
 273         mutex_init(&wa->rpipe_mutex);
 274 }
 275
 276 static inline void wa_init(struct wahc *wa)
 277 {
 278         edc_init(&wa->nep_edc);
 279         atomic_set(&wa->notifs_queued, 0);
 280         wa->dti_state = WA_DTI_TRANSFER_RESULT_PENDING;
 281         wa_rpipe_init(wa);
 282         edc_init(&wa->dti_edc);
 283         INIT_LIST_HEAD(&wa->xfer_list);
 284         INIT_LIST_HEAD(&wa->xfer_delayed_list);
 285         INIT_LIST_HEAD(&wa->xfer_errored_list);
 286         spin_lock_init(&wa->xfer_list_lock);
 287         INIT_WORK(&wa->xfer_enqueue_work, wa_urb_enqueue_run);
 288         INIT_WORK(&wa->xfer_error_work, wa_process_errored_transfers_run);
 289         wa->dto_in_use = 0;
 290         atomic_set(&wa->xfer_id_count, 1);
 291 }
 292
 293 /**
 294  * Destroy a pipe (when refcount drops to zero)
 295  *
 296  * Assumes it has been moved to the "QUIESCING" state.
 297  */
 298 struct wa_xfer;
 299 extern void rpipe_destroy(struct kref *_rpipe);
 300 static inline
 301 void __rpipe_get(struct wa_rpipe *rpipe)
 302 {
 303         kref_get(&rpipe->refcnt);
 304 }
 305 extern int rpipe_get_by_ep(struct wahc *, struct usb_host_endpoint *,
 306                            struct urb *, gfp_t);
 307 static inline void rpipe_put(struct wa_rpipe *rpipe)
 308 {
 309         kref_put(&rpipe->refcnt, rpipe_destroy);
 310
 311 }
 312 extern void rpipe_ep_disable(struct wahc *, struct usb_host_endpoint *);
 313 extern void rpipe_clear_feature_stalled(struct wahc *,
 314                         struct usb_host_endpoint *);
 315 extern int wa_rpipes_create(struct wahc *);
 316 extern void wa_rpipes_destroy(struct wahc *);
 317 static inline void rpipe_avail_dec(struct wa_rpipe *rpipe)
 318 {
 319         atomic_dec(&rpipe->segs_available);
 320 }
 321
 322 /**
 323  * Returns true if the rpipe is ready to submit more segments.
 324  */
 325 static inline int rpipe_avail_inc(struct wa_rpipe *rpipe)
 326 {
 327         return atomic_inc_return(&rpipe->segs_available) > 0
 328                 && !list_empty(&rpipe->seg_list);
 329 }
 330
 331
 332 /* Transferring data */
 333 extern int wa_urb_enqueue(struct wahc *, struct usb_host_endpoint *,
 334                           struct urb *, gfp_t);
 335 extern int wa_urb_dequeue(struct wahc *, struct urb *);
 336 extern void wa_handle_notif_xfer(struct wahc *, struct wa_notif_hdr *);
 337
 338
 339 /* Misc
 340  *
 341  * FIXME: Refcounting for the actual @hwahc object is not correct; I
 342  *        mean, this should be refcounting on the HCD underneath, but
 343  *        it is not. In any case, the semantics for HCD refcounting
 344  *        are *weird*...on refcount reaching zero it just frees
 345  *        it...no RC specific function is called...unless I miss
 346  *        something.
 347  *
 348  * FIXME: has to go away in favour of an 'struct' hcd based sollution
 349  */
 350 static inline struct wahc *wa_get(struct wahc *wa)
 351 {
 352         usb_get_intf(wa->usb_iface);
 353         return wa;
 354 }
 355
 356 static inline void wa_put(struct wahc *wa)
 357 {
 358         usb_put_intf(wa->usb_iface);
 359 }
 360
 361
 362 static inline int __wa_feature(struct wahc *wa, unsigned op, u16 feature)
 363 {
 364         return usb_control_msg(wa->usb_dev, usb_sndctrlpipe(wa->usb_dev, 0),
 365                         op ? USB_REQ_SET_FEATURE : USB_REQ_CLEAR_FEATURE,
 366                         USB_DIR_OUT | USB_TYPE_CLASS | USB_RECIP_INTERFACE,
 367                         feature,
 368                         wa->usb_iface->cur_altsetting->desc.bInterfaceNumber,
 369                         NULL, 0, 1000 /* FIXME: arbitrary */);
 370 }
 371
 372
 373 static inline int __wa_set_feature(struct wahc *wa, u16 feature)
 374 {
 375         return  __wa_feature(wa, 1, feature);
 376 }
 377
 378
 379 static inline int __wa_clear_feature(struct wahc *wa, u16 feature)
 380 {
 381         return __wa_feature(wa, 0, feature);
 382 }
 383
 384
 385 /**
 386  * Return the status of a Wire Adapter
 387  *
 388  * @wa:         Wire Adapter instance
 389  * @returns     < 0 errno code on error, or status bitmap as described
 390  *              in WUSB1.0[8.3.1.6].
 391  *
 392  * NOTE: need malloc, some arches don't take USB from the stack
 393  */
 394 static inline
 395 s32 __wa_get_status(struct wahc *wa)
 396 {
 397         s32 result;
 398         result = usb_control_msg(
 399                 wa->usb_dev, usb_rcvctrlpipe(wa->usb_dev, 0),
 400                 USB_REQ_GET_STATUS,
 401                 USB_DIR_IN | USB_TYPE_CLASS | USB_RECIP_INTERFACE,
 402                 0, wa->usb_iface->cur_altsetting->desc.bInterfaceNumber,
 403                 &wa->status, sizeof(wa->status),
 404                 1000 /* FIXME: arbitrary */);
 405         if (result >= 0)
 406                 result = wa->status;
 407         return result;
 408 }
 409
 410
 411 /**
 412  * Waits until the Wire Adapter's status matches @mask/@value
 413  *
 414  * @wa:         Wire Adapter instance.
 415  * @returns     < 0 errno code on error, otherwise status.
 416  *
 417  * Loop until the WAs status matches the mask and value (status & mask
 418  * == value). Timeout if it doesn't happen.
 419  *
 420  * FIXME: is there an official specification on how long status
 421  *        changes can take?
 422  */
 423 static inline s32 __wa_wait_status(struct wahc *wa, u32 mask, u32 value)
 424 {
 425         s32 result;
 426         unsigned loops = 10;
 427         do {
 428                 msleep(50);
 429                 result = __wa_get_status(wa);
 430                 if ((result & mask) == value)
 431                         break;
 432                 if (loops-- == 0) {
 433                         result = -ETIMEDOUT;
 434                         break;
 435                 }
 436         } while (result >= 0);
 437         return result;
 438 }
 439
 440
 441 /** Command @hwahc to stop, @returns 0 if ok, < 0 errno code on error */
 442 static inline int __wa_stop(struct wahc *wa)
 443 {
 444         int result;
 445         struct device *dev = &wa->usb_iface->dev;
 446
 447         result = __wa_clear_feature(wa, WA_ENABLE);
 448         if (result < 0 && result != -ENODEV) {
 449                 dev_err(dev, "error commanding HC to stop: %d\n", result);
 450                 goto out;
 451         }
 452         result = __wa_wait_status(wa, WA_ENABLE, 0);
 453         if (result < 0 && result != -ENODEV)
 454                 dev_err(dev, "error waiting for HC to stop: %d\n", result);
 455 out:
 456         return 0;
 457 }
 458
 459
 460 #endif /* #ifndef __HWAHC_INTERNAL_H__ */