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