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