drivers/usb/wusbcore/wusbhc.h

   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
 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
 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
 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
 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  */
 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  */
 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
 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  */
 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  */
 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
 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__ */