2 * HWA Host Controller Driver
3 * Wire Adapter Control/Data Streaming Iface (WUSB1.0[8])
5 * Copyright (C) 2005-2006 Intel Corporation
6 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
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.
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.
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
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).
28 * Check out the Design-overview.txt file in the source documentation
29 * for other details on the implementation.
33 * driver glue with the driver API, workqueue daemon
35 * lc RC instance life cycle management (create, destroy...)
37 * hcd glue with the USB API Host Controller Interface API.
39 * nep Notification EndPoint managent: collect notifications
40 * and queue them with the workqueue daemon.
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).
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
50 * xfer Transfer management -- this is all the code that gets a
51 * buffer and pushes it to a device (or viceversa). *
53 * Some day a lot of this code will be shared between this driver and
54 * the drivers for DWA (xfer, rpipe).
56 * All starts at driver.c:hwahc_probe(), when one of this guys is
57 * connected. hwahc_disconnect() stops it.
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.
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
72 * We also have a timer workqueue going from devconnect.c that
73 * schedules in hwahc_devconnect_create().
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
80 #ifndef __HWAHC_INTERNAL_H__
81 #define __HWAHC_INTERNAL_H__
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>
93 extern void wa_urb_enqueue_run(struct work_struct
*ws
);
94 extern void wa_process_errored_transfers_run(struct work_struct
*ws
);
99 * @descr's fields are kept in LE, as we need to send it back and
102 * @wa is referenced when set
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
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.
115 struct usb_rpipe_descriptor descr
;
116 struct usb_host_endpoint
*ep
;
119 struct list_head seg_list
;
120 atomic_t segs_available
;
121 u8 buffer
[1]; /* For reads/writes on USB */
126 * Instance of a HWA Host Controller
128 * Except where a more specific lock/mutex applies or atomic, all
129 * fields protected by @mutex.
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
136 * Endianess has been converted to CPU's.
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.
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.
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).
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).
160 struct usb_device
*usb_dev
;
161 struct usb_interface
*usb_iface
;
163 /* HC to deliver notifications */
169 const struct usb_endpoint_descriptor
*dto_epd
, *dti_epd
;
170 const struct usb_wa_descriptor
*wa_descr
;
172 struct urb
*nep_urb
; /* Notification EndPoint [lockless] */
175 size_t nep_buffer_size
;
177 atomic_t notifs_queued
;
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 */
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
;
190 s32 status
; /* For reading status */
192 struct list_head xfer_list
;
193 struct list_head xfer_delayed_list
;
194 struct list_head xfer_errored_list
;
196 * lock for the above xfer lists. Can be taken while a xfer->lock is
197 * held but not in the reverse order.
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
;
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
);
211 /* Miscellaneous constants */
213 /** Max number of EPROTO errors we tolerate on the NEP in a
215 HWAHC_EPROTO_MAX
= 16,
216 /** Period of time for EPROTO errors (in jiffies) */
217 HWAHC_EPROTO_PERIOD
= 4 * HZ
,
221 /* Notification endpoint handling */
222 extern int wa_nep_create(struct wahc
*, struct usb_interface
*);
223 extern void wa_nep_destroy(struct wahc
*);
225 static inline int wa_nep_arm(struct wahc
*wa
, gfp_t gfp_mask
)
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
);
233 static inline void wa_nep_disarm(struct wahc
*wa
)
235 usb_kill_urb(wa
->nep_urb
);
240 static inline void wa_rpipe_init(struct wahc
*wa
)
242 spin_lock_init(&wa
->rpipe_bm_lock
);
243 mutex_init(&wa
->rpipe_mutex
);
246 static inline void wa_init(struct wahc
*wa
)
248 edc_init(&wa
->nep_edc
);
249 atomic_set(&wa
->notifs_queued
, 0);
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);
262 * Destroy a pipe (when refcount drops to zero)
264 * Assumes it has been moved to the "QUIESCING" state.
267 extern void rpipe_destroy(struct kref
*_rpipe
);
269 void __rpipe_get(struct wa_rpipe
*rpipe
)
271 kref_get(&rpipe
->refcnt
);
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
)
277 kref_put(&rpipe
->refcnt
, rpipe_destroy
);
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
)
287 atomic_dec(&rpipe
->segs_available
);
291 * Returns true if the rpipe is ready to submit more segments.
293 static inline int rpipe_avail_inc(struct wa_rpipe
*rpipe
)
295 return atomic_inc_return(&rpipe
->segs_available
) > 0
296 && !list_empty(&rpipe
->seg_list
);
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
*);
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
316 * FIXME: has to go away in favour of an 'struct' hcd based sollution
318 static inline struct wahc
*wa_get(struct wahc
*wa
)
320 usb_get_intf(wa
->usb_iface
);
324 static inline void wa_put(struct wahc
*wa
)
326 usb_put_intf(wa
->usb_iface
);
330 static inline int __wa_feature(struct wahc
*wa
, unsigned op
, u16 feature
)
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
,
336 wa
->usb_iface
->cur_altsetting
->desc
.bInterfaceNumber
,
337 NULL
, 0, 1000 /* FIXME: arbitrary */);
341 static inline int __wa_set_feature(struct wahc
*wa
, u16 feature
)
343 return __wa_feature(wa
, 1, feature
);
347 static inline int __wa_clear_feature(struct wahc
*wa
, u16 feature
)
349 return __wa_feature(wa
, 0, feature
);
354 * Return the status of a Wire Adapter
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].
360 * NOTE: need malloc, some arches don't take USB from the stack
363 s32
__wa_get_status(struct wahc
*wa
)
366 result
= usb_control_msg(
367 wa
->usb_dev
, usb_rcvctrlpipe(wa
->usb_dev
, 0),
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 */);
380 * Waits until the Wire Adapter's status matches @mask/@value
382 * @wa: Wire Adapter instance.
383 * @returns < 0 errno code on error, otherwise status.
385 * Loop until the WAs status matches the mask and value (status & mask
386 * == value). Timeout if it doesn't happen.
388 * FIXME: is there an official specification on how long status
391 static inline s32
__wa_wait_status(struct wahc
*wa
, u32 mask
, u32 value
)
397 result
= __wa_get_status(wa
);
398 if ((result
& mask
) == value
)
404 } while (result
>= 0);
409 /** Command @hwahc to stop, @returns 0 if ok, < 0 errno code on error */
410 static inline int __wa_stop(struct wahc
*wa
)
413 struct device
*dev
= &wa
->usb_iface
->dev
;
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
);
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
);
428 #endif /* #ifndef __HWAHC_INTERNAL_H__ */