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