d0c132434f1b16f8d0b9d5abda8bf5aeea6ab79e
[linux-2.6.git] / drivers / usb / wusbcore / wusbhc.h
1 /*
2  * Wireless USB Host Controller
3  * Common infrastructure for WHCI and HWA WUSB-HC drivers
4  *
5  *
6  * Copyright (C) 2005-2006 Intel Corporation
7  * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
8  *
9  * This program is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU General Public License version
11  * 2 as published by the Free Software Foundation.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21  * 02110-1301, USA.
22  *
23  *
24  * This driver implements parts common to all Wireless USB Host
25  * Controllers (struct wusbhc, embedding a struct usb_hcd) and is used
26  * by:
27  *
28  *   - hwahc: HWA, USB-dongle that implements a Wireless USB host
29  *     controller, (Wireless USB 1.0 Host-Wire-Adapter specification).
30  *
31  *   - whci: WHCI, a PCI card with a wireless host controller
32  *     (Wireless Host Controller Interface 1.0 specification).
33  *
34  * Check out the Design-overview.txt file in the source documentation
35  * for other details on the implementation.
36  *
37  * Main blocks:
38  *
39  *  rh         Root Hub emulation (part of the HCD glue)
40  *
41  *  devconnect Handle all the issues related to device connection,
42  *             authentication, disconnection, timeout, reseting,
43  *             keepalives, etc.
44  *
45  *  mmc        MMC IE broadcasting handling
46  *
47  * A host controller driver just initializes its stuff and as part of
48  * that, creates a 'struct wusbhc' instance that handles all the
49  * common WUSB mechanisms. Links in the function ops that are specific
50  * to it and then registers the host controller. Ready to run.
51  */
52
53 #ifndef __WUSBHC_H__
54 #define __WUSBHC_H__
55
56 #include <linux/usb.h>
57 #include <linux/list.h>
58 #include <linux/mutex.h>
59 #include <linux/kref.h>
60 #include <linux/workqueue.h>
61 /* FIXME: Yes, I know: BAD--it's not my fault the USB HC iface is not
62  *        public */
63 #include <linux/../../drivers/usb/core/hcd.h>
64 #include <linux/uwb.h>
65 #include <linux/usb/wusb.h>
66
67
68 /**
69  * Wireless USB device
70  *
71  * Describe a WUSB device connected to the cluster. This struct
72  * belongs to the 'struct wusb_port' it is attached to and it is
73  * responsible for putting and clearing the pointer to it.
74  *
75  * Note this "complements" the 'struct usb_device' that the usb_hcd
76  * keeps for each connected USB device. However, it extends some
77  * information that is not available (there is no hcpriv ptr in it!)
78  * *and* most importantly, it's life cycle is different. It is created
79  * as soon as we get a DN_Connect (connect request notification) from
80  * the device through the WUSB host controller; the USB stack doesn't
81  * create the device until we authenticate it. FIXME: this will
82  * change.
83  *
84  * @bos:    This is allocated when the BOS descriptors are read from
85  *          the device and freed upon the wusb_dev struct dying.
86  * @wusb_cap_descr: points into @bos, and has been verified to be size
87  *                  safe.
88  */
89 struct wusb_dev {
90         struct kref refcnt;
91         struct wusbhc *wusbhc;
92         struct list_head cack_node;     /* Connect-Ack list */
93         u8 port_idx;
94         u8 addr;
95         u8 beacon_type:4;
96         struct usb_encryption_descriptor ccm1_etd;
97         struct wusb_ckhdid cdid;
98         unsigned long entry_ts;
99         struct usb_bos_descriptor *bos;
100         struct usb_wireless_cap_descriptor *wusb_cap_descr;
101         struct uwb_mas_bm availability;
102         struct work_struct devconnect_acked_work;
103         struct urb *set_gtk_urb;
104         struct usb_ctrlrequest *set_gtk_req;
105         struct usb_device *usb_dev;
106 };
107
108 #define WUSB_DEV_ADDR_UNAUTH 0x80
109
110 static inline void wusb_dev_init(struct wusb_dev *wusb_dev)
111 {
112         kref_init(&wusb_dev->refcnt);
113         /* no need to init the cack_node */
114 }
115
116 extern void wusb_dev_destroy(struct kref *_wusb_dev);
117
118 static inline struct wusb_dev *wusb_dev_get(struct wusb_dev *wusb_dev)
119 {
120         kref_get(&wusb_dev->refcnt);
121         return wusb_dev;
122 }
123
124 static inline void wusb_dev_put(struct wusb_dev *wusb_dev)
125 {
126         kref_put(&wusb_dev->refcnt, wusb_dev_destroy);
127 }
128
129 /**
130  * Wireless USB Host Controlller root hub "fake" ports
131  * (state and device information)
132  *
133  * Wireless USB is wireless, so there are no ports; but we
134  * fake'em. Each RC can connect a max of devices at the same time
135  * (given in the Wireless Adapter descriptor, bNumPorts or WHCI's
136  * caps), referred to in wusbhc->ports_max.
137  *
138  * See rh.c for more information.
139  *
140  * The @status and @change use the same bits as in USB2.0[11.24.2.7],
141  * so we don't have to do much when getting the port's status.
142  *
143  * WUSB1.0[7.1], USB2.0[11.24.2.7.1,fig 11-10],
144  * include/linux/usb_ch9.h (#define USB_PORT_STAT_*)
145  */
146 struct wusb_port {
147         u16 status;
148         u16 change;
149         struct wusb_dev *wusb_dev;      /* connected device's info */
150         unsigned reset_count;
151         u32 ptk_tkid;
152 };
153
154 /**
155  * WUSB Host Controller specifics
156  *
157  * All fields that are common to all Wireless USB controller types
158  * (HWA and WHCI) are grouped here. Host Controller
159  * functions/operations that only deal with general Wireless USB HC
160  * issues use this data type to refer to the host.
161  *
162  * @usb_hcd        Instantiation of a USB host controller
163  *                 (initialized by upper layer [HWA=HC or WHCI].
164  *
165  * @dev            Device that implements this; initialized by the
166  *                 upper layer (HWA-HC, WHCI...); this device should
167  *                 have a refcount.
168  *
169  * @trust_timeout  After this time without hearing for device
170  *                 activity, we consider the device gone and we have to
171  *                 re-authenticate.
172  *
173  *                 Can be accessed w/o locking--however, read to a
174  *                 local variable then use.
175  *
176  * @chid           WUSB Cluster Host ID: this is supposed to be a
177  *                 unique value that doesn't change across reboots (so
178  *                 that your devices do not require re-association).
179  *
180  *                 Read/Write protected by @mutex
181  *
182  * @dev_info       This array has ports_max elements. It is used to
183  *                 give the HC information about the WUSB devices (see
184  *                 'struct wusb_dev_info').
185  *
186  *                 For HWA we need to allocate it in heap; for WHCI it
187  *                 needs to be permanently mapped, so we keep it for
188  *                 both and make it easy. Call wusbhc->dev_info_set()
189  *                 to update an entry.
190  *
191  * @ports_max      Number of simultaneous device connections (fake
192  *                 ports) this HC will take. Read-only.
193  *
194  * @port           Array of port status for each fake root port. Guaranteed to
195  *                 always be the same lenght during device existence
196  *                 [this allows for some unlocked but referenced reading].
197  *
198  * @mmcies_max     Max number of Information Elements this HC can send
199  *                 in its MMC. Read-only.
200  *
201  * @mmcie_add      HC specific operation (WHCI or HWA) for adding an
202  *                 MMCIE.
203  *
204  * @mmcie_rm       HC specific operation (WHCI or HWA) for removing an
205  *                 MMCIE.
206  *
207  * @enc_types      Array which describes the encryptions methods
208  *                 supported by the host as described in WUSB1.0 --
209  *                 one entry per supported method. As of WUSB1.0 there
210  *                 is only four methods, we make space for eight just in
211  *                 case they decide to add some more (and pray they do
212  *                 it in sequential order). if 'enc_types[enc_method]
213  *                 != 0', then it is supported by the host. enc_method
214  *                 is USB_ENC_TYPE*.
215  *
216  * @set_ptk:       Set the PTK and enable encryption for a device. Or, if
217  *                 the supplied key is NULL, disable encryption for that
218  *                 device.
219  *
220  * @set_gtk:       Set the GTK to be used for all future broadcast packets
221  *                 (i.e., MMCs).  With some hardware, setting the GTK may start
222  *                 MMC transmission.
223  *
224  * NOTE:
225  *
226  *  - If wusb_dev->usb_dev is not NULL, then usb_dev is valid
227  *    (wusb_dev has a refcount on it). Likewise, if usb_dev->wusb_dev
228  *    is not NULL, usb_dev->wusb_dev is valid (usb_dev keeps a
229  *    refcount on it).
230  *
231  *    Most of the times when you need to use it, it will be non-NULL,
232  *    so there is no real need to check for it (wusb_dev will
233  *    dissapear before usb_dev).
234  *
235  *  - The following fields need to be filled out before calling
236  *    wusbhc_create(): ports_max, mmcies_max, mmcie_{add,rm}.
237  *
238  *  - there is no wusbhc_init() method, we do everything in
239  *    wusbhc_create().
240  *
241  *  - Creation is done in two phases, wusbhc_create() and
242  *    wusbhc_create_b(); b are the parts that need to be called after
243  *    calling usb_hcd_add(&wusbhc->usb_hcd).
244  */
245 struct wusbhc {
246         struct usb_hcd usb_hcd;         /* HAS TO BE 1st */
247         struct device *dev;
248         struct uwb_rc *uwb_rc;
249         struct uwb_pal pal;
250
251         unsigned trust_timeout;                 /* in jiffies */
252         struct wuie_host_info *wuie_host_info;  /* Includes CHID */
253
254         struct mutex mutex;                     /* locks everything else */
255         u16 cluster_id;                         /* Wireless USB Cluster ID */
256         struct wusb_port *port;                 /* Fake port status handling */
257         struct wusb_dev_info *dev_info;         /* for Set Device Info mgmt */
258         u8 ports_max;
259         unsigned active:1;                      /* currently xmit'ing MMCs */
260         struct wuie_keep_alive keep_alive_ie;   /* protected by mutex */
261         struct delayed_work keep_alive_timer;
262         struct list_head cack_list;             /* Connect acknowledging */
263         size_t cack_count;                      /* protected by 'mutex' */
264         struct wuie_connect_ack cack_ie;
265         struct uwb_rsv *rsv;            /* cluster bandwidth reservation */
266
267         struct mutex mmcie_mutex;               /* MMC WUIE handling */
268         struct wuie_hdr **mmcie;                /* WUIE array */
269         u8 mmcies_max;
270         /* FIXME: make wusbhc_ops? */
271         int (*start)(struct wusbhc *wusbhc);
272         void (*stop)(struct wusbhc *wusbhc);
273         int (*mmcie_add)(struct wusbhc *wusbhc, u8 interval, u8 repeat_cnt,
274                          u8 handle, struct wuie_hdr *wuie);
275         int (*mmcie_rm)(struct wusbhc *wusbhc, u8 handle);
276         int (*dev_info_set)(struct wusbhc *, struct wusb_dev *wusb_dev);
277         int (*bwa_set)(struct wusbhc *wusbhc, s8 stream_index,
278                        const struct uwb_mas_bm *);
279         int (*set_ptk)(struct wusbhc *wusbhc, u8 port_idx,
280                        u32 tkid, const void *key, size_t key_size);
281         int (*set_gtk)(struct wusbhc *wusbhc,
282                        u32 tkid, const void *key, size_t key_size);
283         int (*set_num_dnts)(struct wusbhc *wusbhc, u8 interval, u8 slots);
284
285         struct {
286                 struct usb_key_descriptor descr;
287                 u8 data[16];                            /* GTK key data */
288         } __attribute__((packed)) gtk;
289         u8 gtk_index;
290         u32 gtk_tkid;
291         struct work_struct gtk_rekey_done_work;
292         int pending_set_gtks;
293
294         struct usb_encryption_descriptor *ccm1_etd;
295 };
296
297 #define usb_hcd_to_wusbhc(u) container_of((u), struct wusbhc, usb_hcd)
298
299
300 extern int wusbhc_create(struct wusbhc *);
301 extern int wusbhc_b_create(struct wusbhc *);
302 extern void wusbhc_b_destroy(struct wusbhc *);
303 extern void wusbhc_destroy(struct wusbhc *);
304 extern int wusb_dev_sysfs_add(struct wusbhc *, struct usb_device *,
305                               struct wusb_dev *);
306 extern void wusb_dev_sysfs_rm(struct wusb_dev *);
307 extern int wusbhc_sec_create(struct wusbhc *);
308 extern int wusbhc_sec_start(struct wusbhc *);
309 extern void wusbhc_sec_stop(struct wusbhc *);
310 extern void wusbhc_sec_destroy(struct wusbhc *);
311 extern void wusbhc_giveback_urb(struct wusbhc *wusbhc, struct urb *urb,
312                                 int status);
313 void wusbhc_reset_all(struct wusbhc *wusbhc);
314
315 int wusbhc_pal_register(struct wusbhc *wusbhc);
316 void wusbhc_pal_unregister(struct wusbhc *wusbhc);
317
318 /*
319  * Return @usb_dev's @usb_hcd (properly referenced) or NULL if gone
320  *
321  * @usb_dev: USB device, UNLOCKED and referenced (or otherwise, safe ptr)
322  *
323  * This is a safe assumption as @usb_dev->bus is referenced all the
324  * time during the @usb_dev life cycle.
325  */
326 static inline struct usb_hcd *usb_hcd_get_by_usb_dev(struct usb_device *usb_dev)
327 {
328         struct usb_hcd *usb_hcd;
329         usb_hcd = container_of(usb_dev->bus, struct usb_hcd, self);
330         return usb_get_hcd(usb_hcd);
331 }
332
333 /*
334  * Increment the reference count on a wusbhc.
335  *
336  * @wusbhc's life cycle is identical to that of the underlying usb_hcd.
337  */
338 static inline struct wusbhc *wusbhc_get(struct wusbhc *wusbhc)
339 {
340         return usb_get_hcd(&wusbhc->usb_hcd) ? wusbhc : NULL;
341 }
342
343 /*
344  * Return the wusbhc associated to a @usb_dev
345  *
346  * @usb_dev: USB device, UNLOCKED and referenced (or otherwise, safe ptr)
347  *
348  * @returns: wusbhc for @usb_dev; NULL if the @usb_dev is being torn down.
349  *           WARNING: referenced at the usb_hcd level, unlocked
350  *
351  * FIXME: move offline
352  */
353 static inline struct wusbhc *wusbhc_get_by_usb_dev(struct usb_device *usb_dev)
354 {
355         struct wusbhc *wusbhc = NULL;
356         struct usb_hcd *usb_hcd;
357         if (usb_dev->devnum > 1 && !usb_dev->wusb) {
358                 /* but root hubs */
359                 dev_err(&usb_dev->dev, "devnum %d wusb %d\n", usb_dev->devnum,
360                         usb_dev->wusb);
361                 BUG_ON(usb_dev->devnum > 1 && !usb_dev->wusb);
362         }
363         usb_hcd = usb_hcd_get_by_usb_dev(usb_dev);
364         if (usb_hcd == NULL)
365                 return NULL;
366         BUG_ON(usb_hcd->wireless == 0);
367         return wusbhc = usb_hcd_to_wusbhc(usb_hcd);
368 }
369
370
371 static inline void wusbhc_put(struct wusbhc *wusbhc)
372 {
373         usb_put_hcd(&wusbhc->usb_hcd);
374 }
375
376 int wusbhc_start(struct wusbhc *wusbhc, const struct wusb_ckhdid *chid);
377 void wusbhc_stop(struct wusbhc *wusbhc);
378 extern int wusbhc_chid_set(struct wusbhc *, const struct wusb_ckhdid *);
379
380 /* Device connect handling */
381 extern int wusbhc_devconnect_create(struct wusbhc *);
382 extern void wusbhc_devconnect_destroy(struct wusbhc *);
383 extern int wusbhc_devconnect_start(struct wusbhc *wusbhc,
384                                    const struct wusb_ckhdid *chid);
385 extern void wusbhc_devconnect_stop(struct wusbhc *wusbhc);
386 extern int wusbhc_devconnect_auth(struct wusbhc *, u8);
387 extern void wusbhc_handle_dn(struct wusbhc *, u8 srcaddr,
388                              struct wusb_dn_hdr *dn_hdr, size_t size);
389 extern int wusbhc_dev_reset(struct wusbhc *wusbhc, u8 port);
390 extern void __wusbhc_dev_disable(struct wusbhc *wusbhc, u8 port);
391 extern int wusb_usb_ncb(struct notifier_block *nb, unsigned long val,
392                         void *priv);
393 extern int wusb_set_dev_addr(struct wusbhc *wusbhc, struct wusb_dev *wusb_dev,
394                              u8 addr);
395
396 /* Wireless USB fake Root Hub methods */
397 extern int wusbhc_rh_create(struct wusbhc *);
398 extern void wusbhc_rh_destroy(struct wusbhc *);
399
400 extern int wusbhc_rh_status_data(struct usb_hcd *, char *);
401 extern int wusbhc_rh_control(struct usb_hcd *, u16, u16, u16, char *, u16);
402 extern int wusbhc_rh_suspend(struct usb_hcd *);
403 extern int wusbhc_rh_resume(struct usb_hcd *);
404 extern int wusbhc_rh_start_port_reset(struct usb_hcd *, unsigned);
405
406 /* MMC handling */
407 extern int wusbhc_mmcie_create(struct wusbhc *);
408 extern void wusbhc_mmcie_destroy(struct wusbhc *);
409 extern int wusbhc_mmcie_set(struct wusbhc *, u8 interval, u8 repeat_cnt,
410                             struct wuie_hdr *);
411 extern void wusbhc_mmcie_rm(struct wusbhc *, struct wuie_hdr *);
412
413 /* Bandwidth reservation */
414 int wusbhc_rsv_establish(struct wusbhc *wusbhc);
415 void wusbhc_rsv_terminate(struct wusbhc *wusbhc);
416
417 /*
418  * I've always said
419  * I wanted a wedding in a church...
420  *
421  * but lately I've been thinking about
422  * the Botanical Gardens.
423  *
424  * We could do it by the tulips.
425  * It'll be beautiful
426  *
427  * --Security!
428  */
429 extern int wusb_dev_sec_add(struct wusbhc *, struct usb_device *,
430                                 struct wusb_dev *);
431 extern void wusb_dev_sec_rm(struct wusb_dev *) ;
432 extern int wusb_dev_4way_handshake(struct wusbhc *, struct wusb_dev *,
433                                    struct wusb_ckhdid *ck);
434 void wusbhc_gtk_rekey(struct wusbhc *wusbhc);
435
436
437 /* WUSB Cluster ID handling */
438 extern u8 wusb_cluster_id_get(void);
439 extern void wusb_cluster_id_put(u8);
440
441 /*
442  * wusb_port_by_idx - return the port associated to a zero-based port index
443  *
444  * NOTE: valid without locking as long as wusbhc is referenced (as the
445  *       number of ports doesn't change). The data pointed to has to
446  *       be verified though :)
447  */
448 static inline struct wusb_port *wusb_port_by_idx(struct wusbhc *wusbhc,
449                                                  u8 port_idx)
450 {
451         return &wusbhc->port[port_idx];
452 }
453
454 /*
455  * wusb_port_no_to_idx - Convert port number (per usb_dev->portnum) to
456  * a port_idx.
457  *
458  * USB stack USB ports are 1 based!!
459  *
460  * NOTE: only valid for WUSB devices!!!
461  */
462 static inline u8 wusb_port_no_to_idx(u8 port_no)
463 {
464         return port_no - 1;
465 }
466
467 extern struct wusb_dev *__wusb_dev_get_by_usb_dev(struct wusbhc *,
468                                                   struct usb_device *);
469
470 /*
471  * Return a referenced wusb_dev given a @usb_dev
472  *
473  * Returns NULL if the usb_dev is being torn down.
474  *
475  * FIXME: move offline
476  */
477 static inline
478 struct wusb_dev *wusb_dev_get_by_usb_dev(struct usb_device *usb_dev)
479 {
480         struct wusbhc *wusbhc;
481         struct wusb_dev *wusb_dev;
482         wusbhc = wusbhc_get_by_usb_dev(usb_dev);
483         if (wusbhc == NULL)
484                 return NULL;
485         mutex_lock(&wusbhc->mutex);
486         wusb_dev = __wusb_dev_get_by_usb_dev(wusbhc, usb_dev);
487         mutex_unlock(&wusbhc->mutex);
488         wusbhc_put(wusbhc);
489         return wusb_dev;
490 }
491
492 /* Misc */
493
494 extern struct workqueue_struct *wusbd;
495 #endif /* #ifndef __WUSBHC_H__ */