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