GNU Linux-libre 4.19.286-gnu1
[releases.git] / 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__ */