drivers/usb/wusbcore/wa-hc.h

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