linux/Documentation/usb/WUSB-Design-overview.txt
<<
>>
Prefs
   1
   2Linux UWB + Wireless USB + WiNET
   3
   4   (C) 2005-2006 Intel Corporation
   5   Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
   6
   7   This program is free software; you can redistribute it and/or
   8   modify it under the terms of the GNU General Public License version
   9   2 as published by the Free Software Foundation.
  10
  11   This program is distributed in the hope that it will be useful,
  12   but WITHOUT ANY WARRANTY; without even the implied warranty of
  13   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14   GNU General Public License for more details.
  15
  16   You should have received a copy of the GNU General Public License
  17   along with this program; if not, write to the Free Software
  18   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19   02110-1301, USA.
  20
  21
  22Please visit http://bughost.org/thewiki/Design-overview.txt-1.8 for
  23updated content.
  24
  25    * Design-overview.txt-1.8
  26
  27This code implements a Ultra Wide Band stack for Linux, as well as
  28drivers for the the USB based UWB radio controllers defined in the
  29Wireless USB 1.0 specification (including Wireless USB host controller
  30and an Intel WiNET controller).
  31
  32   1. Introduction
  33         1. HWA: Host Wire adapters, your Wireless USB dongle
  34
  35         2. DWA: Device Wired Adaptor, a Wireless USB hub for wired
  36            devices
  37         3. WHCI: Wireless Host Controller Interface, the PCI WUSB host
  38            adapter
  39   2. The UWB stack
  40         1. Devices and hosts: the basic structure
  41
  42         2. Host Controller life cycle
  43
  44         3. On the air: beacons and enumerating the radio neighborhood
  45
  46         4. Device lists
  47         5. Bandwidth allocation
  48
  49   3. Wireless USB Host Controller drivers
  50
  51   4. Glossary
  52
  53
  54    Introduction
  55
  56UWB is a wide-band communication protocol that is to serve also as the
  57low-level protocol for others (much like TCP sits on IP). Currently
  58these others are Wireless USB and TCP/IP, but seems Bluetooth and
  59Firewire/1394 are coming along.
  60
  61UWB uses a band from roughly 3 to 10 GHz, transmitting at a max of
  62~-41dB (or 0.074 uW/MHz--geography specific data is still being
  63negotiated w/ regulators, so watch for changes). That band is divided in
  64a bunch of ~1.5 GHz wide channels (or band groups) composed of three
  65subbands/subchannels (528 MHz each). Each channel is independent of each
  66other, so you could consider them different "busses". Initially this
  67driver considers them all a single one.
  68
  69Radio time is divided in 65536 us long /superframes/, each one divided
  70in 256 256us long /MASs/ (Media Allocation Slots), which are the basic
  71time/media allocation units for transferring data. At the beginning of
  72each superframe there is a Beacon Period (BP), where every device
  73transmit its beacon on a single MAS. The length of the BP depends on how
  74many devices are present and the length of their beacons.
  75
  76Devices have a MAC (fixed, 48 bit address) and a device (changeable, 16
  77bit address) and send periodic beacons to advertise themselves and pass
  78info on what they are and do. They advertise their capabilities and a
  79bunch of other stuff.
  80
  81The different logical parts of this driver are:
  82
  83    *
  84
  85      *UWB*: the Ultra-Wide-Band stack -- manages the radio and
  86      associated spectrum to allow for devices sharing it. Allows to
  87      control bandwidth assignment, beaconing, scanning, etc
  88
  89    *
  90
  91      *WUSB*: the layer that sits on top of UWB to provide Wireless USB.
  92      The Wireless USB spec defines means to control a UWB radio and to
  93      do the actual WUSB.
  94
  95
  96      HWA: Host Wire adapters, your Wireless USB dongle
  97
  98WUSB also defines a device called a Host Wire Adaptor (HWA), which in
  99mere terms is a USB dongle that enables your PC to have UWB and Wireless
 100USB. The Wireless USB Host Controller in a HWA looks to the host like a
 101[Wireless] USB controller connected via USB (!)
 102
 103The HWA itself is broken in two or three main interfaces:
 104
 105    *
 106
 107      *RC*: Radio control -- this implements an interface to the
 108      Ultra-Wide-Band radio controller. The driver for this implements a
 109      USB-based UWB Radio Controller to the UWB stack.
 110
 111    *
 112
 113      *HC*: the wireless USB host controller. It looks like a USB host
 114      whose root port is the radio and the WUSB devices connect to it.
 115      To the system it looks like a separate USB host. The driver (will)
 116      implement a USB host controller (similar to UHCI, OHCI or EHCI)
 117      for which the root hub is the radio...To reiterate: it is a USB
 118      controller that is connected via USB instead of PCI.
 119
 120    *
 121
 122      *WINET*: some HW provide a WiNET interface (IP over UWB). This
 123      package provides a driver for it (it looks like a network
 124      interface, winetX). The driver detects when there is a link up for
 125      their type and kick into gear.
 126
 127
 128      DWA: Device Wired Adaptor, a Wireless USB hub for wired devices
 129
 130These are the complement to HWAs. They are a USB host for connecting
 131wired devices, but it is connected to your PC connected via Wireless
 132USB. To the system it looks like yet another USB host. To the untrained
 133eye, it looks like a hub that connects upstream wirelessly.
 134
 135We still offer no support for this; however, it should share a lot of
 136code with the HWA-RC driver; there is a bunch of factorization work that
 137has been done to support that in upcoming releases.
 138
 139
 140      WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter
 141
 142This is your usual PCI device that implements WHCI. Similar in concept
 143to EHCI, it allows your wireless USB devices (including DWAs) to connect
 144to your host via a PCI interface. As in the case of the HWA, it has a
 145Radio Control interface and the WUSB Host Controller interface per se.
 146
 147There is still no driver support for this, but will be in upcoming
 148releases.
 149
 150
 151    The UWB stack
 152
 153The main mission of the UWB stack is to keep a tally of which devices
 154are in radio proximity to allow drivers to connect to them. As well, it
 155provides an API for controlling the local radio controllers (RCs from
 156now on), such as to start/stop beaconing, scan, allocate bandwidth, etc.
 157
 158
 159      Devices and hosts: the basic structure
 160
 161The main building block here is the UWB device (struct uwb_dev). For
 162each device that pops up in radio presence (ie: the UWB host receives a
 163beacon from it) you get a struct uwb_dev that will show up in
 164/sys/class/uwb and in /sys/bus/uwb/devices.
 165
 166For each RC that is detected, a new struct uwb_rc is created. In turn, a
 167RC is also a device, so they also show in /sys/class/uwb and
 168/sys/bus/uwb/devices, but at the same time, only radio controllers show
 169up in /sys/class/uwb_rc.
 170
 171    *
 172
 173      [*] The reason for RCs being also devices is that not only we can
 174      see them while enumerating the system device tree, but also on the
 175      radio (their beacons and stuff), so the handling has to be
 176      likewise to that of a device.
 177
 178Each RC driver is implemented by a separate driver that plugs into the
 179interface that the UWB stack provides through a struct uwb_rc_ops. The
 180spec creators have been nice enough to make the message format the same
 181for HWA and WHCI RCs, so the driver is really a very thin transport that
 182moves the requests from the UWB API to the device [/uwb_rc_ops->cmd()/]
 183and sends the replies and notifications back to the API
 184[/uwb_rc_neh_grok()/]. Notifications are handled to the UWB daemon, that
 185is chartered, among other things, to keep the tab of how the UWB radio
 186neighborhood looks, creating and destroying devices as they show up or
 187disappear.
 188
 189Command execution is very simple: a command block is sent and a event
 190block or reply is expected back. For sending/receiving command/events, a
 191handle called /neh/ (Notification/Event Handle) is opened with
 192/uwb_rc_neh_open()/.
 193
 194The HWA-RC (USB dongle) driver (drivers/uwb/hwa-rc.c) does this job for
 195the USB connected HWA. Eventually, drivers/whci-rc.c will do the same
 196for the PCI connected WHCI controller.
 197
 198
 199      Host Controller life cycle
 200
 201So let's say we connect a dongle to the system: it is detected and
 202firmware uploaded if needed [for Intel's i1480
 203/drivers/uwb/ptc/usb.c:ptc_usb_probe()/] and then it is reenumerated.
 204Now we have a real HWA device connected and
 205/drivers/uwb/hwa-rc.c:hwarc_probe()/ picks it up, that will set up the
 206Wire-Adaptor environment and then suck it into the UWB stack's vision of
 207the world [/drivers/uwb/lc-rc.c:uwb_rc_add()/].
 208
 209    *
 210
 211      [*] The stack should put a new RC to scan for devices
 212      [/uwb_rc_scan()/] so it finds what's available around and tries to
 213      connect to them, but this is policy stuff and should be driven
 214      from user space. As of now, the operator is expected to do it
 215      manually; see the release notes for documentation on the procedure.
 216
 217When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/
 218takes time of tearing everything down safely (or not...).
 219
 220
 221      On the air: beacons and enumerating the radio neighborhood
 222
 223So assuming we have devices and we have agreed for a channel to connect
 224on (let's say 9), we put the new RC to beacon:
 225
 226    *
 227
 228            $ echo 9 0 > /sys/class/uwb_rc/uwb0/beacon
 229
 230Now it is visible. If there were other devices in the same radio channel
 231and beacon group (that's what the zero is for), the dongle's radio
 232control interface will send beacon notifications on its
 233notification/event endpoint (NEEP). The beacon notifications are part of
 234the event stream that is funneled into the API with
 235/drivers/uwb/neh.c:uwb_rc_neh_grok()/ and delivered to the UWBD, the UWB
 236daemon through a notification list.
 237
 238UWBD wakes up and scans the event list; finds a beacon and adds it to
 239the BEACON CACHE (/uwb_beca/). If he receives a number of beacons from
 240the same device, he considers it to be 'onair' and creates a new device
 241[/drivers/uwb/lc-dev.c:uwbd_dev_onair()/]. Similarly, when no beacons
 242are received in some time, the device is considered gone and wiped out
 243[uwbd calls periodically /uwb/beacon.c:uwb_beca_purge()/ that will purge
 244the beacon cache of dead devices].
 245
 246
 247      Device lists
 248
 249All UWB devices are kept in the list of the struct bus_type uwb_bus.
 250
 251
 252      Bandwidth allocation
 253
 254The UWB stack maintains a local copy of DRP availability through
 255processing of incoming *DRP Availability Change* notifications. This
 256local copy is currently used to present the current bandwidth
 257availability to the user through the sysfs file
 258/sys/class/uwb_rc/uwbx/bw_avail. In the future the bandwidth
 259availability information will be used by the bandwidth reservation
 260routines.
 261
 262The bandwidth reservation routines are in progress and are thus not
 263present in the current release. When completed they will enable a user
 264to initiate DRP reservation requests through interaction with sysfs. DRP
 265reservation requests from remote UWB devices will also be handled. The
 266bandwidth management done by the UWB stack will include callbacks to the
 267higher layers will enable the higher layers to use the reservations upon
 268completion. [Note: The bandwidth reservation work is in progress and
 269subject to change.]
 270
 271
 272    Wireless USB Host Controller drivers
 273
 274*WARNING* This section needs a lot of work!
 275
 276As explained above, there are three different types of HCs in the WUSB
 277world: HWA-HC, DWA-HC and WHCI-HC.
 278
 279HWA-HC and DWA-HC share that they are Wire-Adapters (USB or WUSB
 280connected controllers), and their transfer management system is almost
 281identical. So is their notification delivery system.
 282
 283HWA-HC and WHCI-HC share that they are both WUSB host controllers, so
 284they have to deal with WUSB device life cycle and maintenance, wireless
 285root-hub
 286
 287HWA exposes a Host Controller interface (HWA-HC 0xe0/02/02). This has
 288three endpoints (Notifications, Data Transfer In and Data Transfer
 289Out--known as NEP, DTI and DTO in the code).
 290
 291We reserve UWB bandwidth for our Wireless USB Cluster, create a Cluster
 292ID and tell the HC to use all that. Then we start it. This means the HC
 293starts sending MMCs.
 294
 295    *
 296
 297      The MMCs are blocks of data defined somewhere in the WUSB1.0 spec
 298      that define a stream in the UWB channel time allocated for sending
 299      WUSB IEs (host to device commands/notifications) and Device
 300      Notifications (device initiated to host). Each host defines a
 301      unique Wireless USB cluster through MMCs. Devices can connect to a
 302      single cluster at the time. The IEs are Information Elements, and
 303      among them are the bandwidth allocations that tell each device
 304      when can they transmit or receive.
 305
 306Now it all depends on external stimuli.
 307
 308*New device connection*
 309
 310A new device pops up, it scans the radio looking for MMCs that give out
 311the existence of Wireless USB channels. Once one (or more) are found,
 312selects which one to connect to. Sends a /DN_Connect/ (device
 313notification connect) during the DNTS (Device Notification Time
 314Slot--announced in the MMCs
 315
 316HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery
 317into /devconnect/). This process starts the authentication process for
 318the device. First we allocate a /fake port/ and assign an
 319unauthenticated address (128 to 255--what we really do is
 3200x80 | fake_port_idx). We fiddle with the fake port status and /khubd/
 321sees a new connection, so he moves on to enable the fake port with a reset.
 322
 323So now we are in the reset path -- we know we have a non-yet enumerated
 324device with an unauthorized address; we ask user space to authenticate
 325(FIXME: not yet done, similar to bluetooth pairing), then we do the key
 326exchange (FIXME: not yet done) and issue a /set address 0/ to bring the
 327device to the default state. Device is authenticated.
 328
 329From here, the USB stack takes control through the usb_hcd ops. khubd
 330has seen the port status changes, as we have been toggling them. It will
 331start enumerating and doing transfers through usb_hcd->urb_enqueue() to
 332read descriptors and move our data.
 333
 334*Device life cycle and keep alives*
 335
 336Every time there is a successful transfer to/from a device, we update a
 337per-device activity timestamp. If not, every now and then we check and
 338if the activity timestamp gets old, we ping the device by sending it a
 339Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this
 340arrives to us as a notification through
 341devconnect.c:wusb_handle_dn_alive(). If a device times out, we
 342disconnect it from the system (cleaning up internal information and
 343toggling the bits in the fake hub port, which kicks khubd into removing
 344the rest of the stuff).
 345
 346This is done through devconnect:__wusb_check_devs(), which will scan the
 347device list looking for whom needs refreshing.
 348
 349If the device wants to disconnect, it will either die (ugly) or send a
 350/DN_Disconnect/ that will prompt a disconnection from the system.
 351
 352*Sending and receiving data*
 353
 354Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is
 355/aimed/ at an endpoint in a WUSB device. This is the same for HWAs and
 356DWAs.
 357
 358Each HC has a number of rpipes and buffers that can be assigned to them;
 359when doing a data transfer (xfer), first the rpipe has to be aimed and
 360prepared (buffers assigned), then we can start queueing requests for
 361data in or out.
 362
 363Data buffers have to be segmented out before sending--so we send first a
 364header (segment request) and then if there is any data, a data buffer
 365immediately after to the DTI interface (yep, even the request). If our
 366buffer is bigger than the max segment size, then we just do multiple
 367requests.
 368
 369[This sucks, because doing USB scatter gatter in Linux is resource
 370intensive, if any...not that the current approach is not. It just has to
 371be cleaned up a lot :)].
 372
 373If reading, we don't send data buffers, just the segment headers saying
 374we want to read segments.
 375
 376When the xfer is executed, we receive a notification that says data is
 377ready in the DTI endpoint (handled through
 378xfer.c:wa_handle_notif_xfer()). In there we read from the DTI endpoint a
 379descriptor that gives us the status of the transfer, its identification
 380(given when we issued it) and the segment number. If it was a data read,
 381we issue another URB to read into the destination buffer the chunk of
 382data coming out of the remote endpoint. Done, wait for the next guy. The
 383callbacks for the URBs issued from here are the ones that will declare
 384the xfer complete at some point and call its callback.
 385
 386Seems simple, but the implementation is not trivial.
 387
 388    *
 389
 390      *WARNING* Old!!
 391
 392The main xfer descriptor, wa_xfer (equivalent to a URB) contains an
 393array of segments, tallys on segments and buffers and callback
 394information. Buried in there is a lot of URBs for executing the segments
 395and buffer transfers.
 396
 397For OUT xfers, there is an array of segments, one URB for each, another
 398one of buffer URB. When submitting, we submit URBs for segment request
 3991, buffer 1, segment 2, buffer 2...etc. Then we wait on the DTI for xfer
 400result data; when all the segments are complete, we call the callback to
 401finalize the transfer.
 402
 403For IN xfers, we only issue URBs for the segments we want to read and
 404then wait for the xfer result data.
 405
 406*URB mapping into xfers*
 407
 408This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an
 409rpipe to the endpoint where we have to transmit, create a transfer
 410context (wa_xfer) and submit it. When the xfer is done, our callback is
 411called and we assign the status bits and release the xfer resources.
 412
 413In dequeue() we are basically cancelling/aborting the transfer. We issue
 414a xfer abort request to the HC, cancel all the URBs we had submitted
 415and not yet done and when all that is done, the xfer callback will be
 416called--this will call the URB callback.
 417
 418
 419    Glossary
 420
 421*DWA* -- Device Wire Adapter
 422
 423USB host, wired for downstream devices, upstream connects wirelessly
 424with Wireless USB.
 425
 426*EVENT* -- Response to a command on the NEEP
 427
 428*HWA* -- Host Wire Adapter / USB dongle for UWB and Wireless USB
 429
 430*NEH* -- Notification/Event Handle
 431
 432Handle/file descriptor for receiving notifications or events. The WA
 433code requires you to get one of this to listen for notifications or
 434events on the NEEP.
 435
 436*NEEP* -- Notification/Event EndPoint
 437
 438Stuff related to the management of the first endpoint of a HWA USB
 439dongle that is used to deliver an stream of events and notifications to
 440the host.
 441
 442*NOTIFICATION* -- Message coming in the NEEP as response to something.
 443
 444*RC* -- Radio Control
 445
 446Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by
 447InakyPerezGonzalez)
 448
 449
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.