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