12Linux UWB + Wireless USB + WiNET
34 (C) 2005-2006 Intel Corporation
5 Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
67 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.
1011 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.
1516 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.
202122Please visit http://bughost.org/thewiki/Design-overview.txt-1.8 for
23updated content.
2425 * Design-overview.txt-1.8
2627This code implements a Ultra Wide Band stack for Linux, as well as
28drivers for the USB based UWB radio controllers defined in the
29Wireless USB 1.0 specification (including Wireless USB host controller
30and an Intel WiNET controller).
3132 1. Introduction
33 1. HWA: Host Wire adapters, your Wireless USB dongle
3435 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
4142 2. Host Controller life cycle
4344 3. On the air: beacons and enumerating the radio neighborhood
4546 4. Device lists
47 5. Bandwidth allocation
4849 3. Wireless USB Host Controller drivers
5051 4. Glossary
525354 Introduction
5556UWB 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.
6061UWB 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.
6869Radio 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.
7576Devices 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.
8081The different logical parts of this driver are:
8283 *
8485 *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
8889 *
9091 *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.
949596 HWA: Host Wire adapters, your Wireless USB dongle
9798WUSB 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 (!)
102103The HWA itself is broken in two or three main interfaces:
104105 *
106107 *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.
110111 *
112113 *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.
119120 *
121122 *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.
126127128 DWA: Device Wired Adaptor, a Wireless USB hub for wired devices
129130These 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.
134135We 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.
138139140 WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter
141142This 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.
146147There is still no driver support for this, but will be in upcoming
148releases.
149150151 The UWB stack
152153The 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.
157158159 Devices and hosts: the basic structure
160161The 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/bus/uwb/devices.
165166For each RC that is detected, a new struct uwb_rc and struct uwb_dev are
167created. An entry is also created in /sys/class/uwb_rc for each RC.
168169Each RC driver is implemented by a separate driver that plugs into the
170interface that the UWB stack provides through a struct uwb_rc_ops. The
171spec creators have been nice enough to make the message format the same
172for HWA and WHCI RCs, so the driver is really a very thin transport that
173moves the requests from the UWB API to the device [/uwb_rc_ops->cmd()/]
174and sends the replies and notifications back to the API
175[/uwb_rc_neh_grok()/]. Notifications are handled to the UWB daemon, that
176is chartered, among other things, to keep the tab of how the UWB radio
177neighborhood looks, creating and destroying devices as they show up or
178disappear.
179180Command execution is very simple: a command block is sent and a event
181block or reply is expected back. For sending/receiving command/events, a
182handle called /neh/ (Notification/Event Handle) is opened with
183/uwb_rc_neh_open()/.
184185The HWA-RC (USB dongle) driver (drivers/uwb/hwa-rc.c) does this job for
186the USB connected HWA. Eventually, drivers/whci-rc.c will do the same
187for the PCI connected WHCI controller.
188189190 Host Controller life cycle
191192So let's say we connect a dongle to the system: it is detected and
193firmware uploaded if needed [for Intel's i1480
194/drivers/uwb/ptc/usb.c:ptc_usb_probe()/] and then it is reenumerated.
195Now we have a real HWA device connected and
196/drivers/uwb/hwa-rc.c:hwarc_probe()/ picks it up, that will set up the
197Wire-Adaptor environment and then suck it into the UWB stack's vision of
198the world [/drivers/uwb/lc-rc.c:uwb_rc_add()/].
199200 *
201202 [*] 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.
207208When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/
209takes time of tearing everything down safely (or not...).
210211212 On the air: beacons and enumerating the radio neighborhood
213214So assuming we have devices and we have agreed for a channel to connect
215on (let's say 9), we put the new RC to beacon:
216217 *
218219 $ echo 9 0 > /sys/class/uwb_rc/uwb0/beacon
220221Now it is visible. If there were other devices in the same radio channel
222and beacon group (that's what the zero is for), the dongle's radio
223control interface will send beacon notifications on its
224notification/event endpoint (NEEP). The beacon notifications are part of
225the 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
227daemon through a notification list.
228229UWBD wakes up and scans the event list; finds a beacon and adds it to
230the BEACON CACHE (/uwb_beca/). If he receives a number of beacons from
231the 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
233are 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
235the beacon cache of dead devices].
236237238 Device lists
239240All UWB devices are kept in the list of the struct bus_type uwb_bus_type.
241242243 Bandwidth allocation
244245The UWB stack maintains a local copy of DRP availability through
246processing of incoming *DRP Availability Change* notifications. This
247local copy is currently used to present the current bandwidth
248availability to the user through the sysfs file
249/sys/class/uwb_rc/uwbx/bw_avail. In the future the bandwidth
250availability information will be used by the bandwidth reservation
251routines.
252253The bandwidth reservation routines are in progress and are thus not
254present in the current release. When completed they will enable a user
255to initiate DRP reservation requests through interaction with sysfs. DRP
256reservation requests from remote UWB devices will also be handled. The
257bandwidth management done by the UWB stack will include callbacks to the
258higher layers will enable the higher layers to use the reservations upon
259completion. [Note: The bandwidth reservation work is in progress and
260subject to change.]
261262263 Wireless USB Host Controller drivers
264265*WARNING* This section needs a lot of work!
266267As explained above, there are three different types of HCs in the WUSB
268world: HWA-HC, DWA-HC and WHCI-HC.
269270HWA-HC and DWA-HC share that they are Wire-Adapters (USB or WUSB
271connected controllers), and their transfer management system is almost
272identical. So is their notification delivery system.
273274HWA-HC and WHCI-HC share that they are both WUSB host controllers, so
275they have to deal with WUSB device life cycle and maintenance, wireless
276root-hub
277278HWA exposes a Host Controller interface (HWA-HC 0xe0/02/02). This has
279three endpoints (Notifications, Data Transfer In and Data Transfer
280Out--known as NEP, DTI and DTO in the code).
281282We reserve UWB bandwidth for our Wireless USB Cluster, create a Cluster
283ID and tell the HC to use all that. Then we start it. This means the HC
284starts sending MMCs.
285286 *
287288 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.
296297Now it all depends on external stimuli.
298299*New device connection*
300301A new device pops up, it scans the radio looking for MMCs that give out
302the existence of Wireless USB channels. Once one (or more) are found,
303selects which one to connect to. Sends a /DN_Connect/ (device
304notification connect) during the DNTS (Device Notification Time
305Slot--announced in the MMCs
306307HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery
308into /devconnect/). This process starts the authentication process for
309the device. First we allocate a /fake port/ and assign an
310unauthenticated address (128 to 255--what we really do is
3110x80 | fake_port_idx). We fiddle with the fake port status and /hub_wq/
312sees a new connection, so he moves on to enable the fake port with a reset.
313314So now we are in the reset path -- we know we have a non-yet enumerated
315device with an unauthorized address; we ask user space to authenticate
316(FIXME: not yet done, similar to bluetooth pairing), then we do the key
317exchange (FIXME: not yet done) and issue a /set address 0/ to bring the
318device to the default state. Device is authenticated.
319320From here, the USB stack takes control through the usb_hcd ops. hub_wq
321has seen the port status changes, as we have been toggling them. It will
322start enumerating and doing transfers through usb_hcd->urb_enqueue() to
323read descriptors and move our data.
324325*Device life cycle and keep alives*
326327Every time there is a successful transfer to/from a device, we update a
328per-device activity timestamp. If not, every now and then we check and
329if the activity timestamp gets old, we ping the device by sending it a
330Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this
331arrives to us as a notification through
332devconnect.c:wusb_handle_dn_alive(). If a device times out, we
333disconnect it from the system (cleaning up internal information and
334toggling the bits in the fake hub port, which kicks hub_wq into removing
335the rest of the stuff).
336337This is done through devconnect:__wusb_check_devs(), which will scan the
338device list looking for whom needs refreshing.
339340If the device wants to disconnect, it will either die (ugly) or send a
341/DN_Disconnect/ that will prompt a disconnection from the system.
342343*Sending and receiving data*
344345Data 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
347DWAs.
348349Each HC has a number of rpipes and buffers that can be assigned to them;
350when doing a data transfer (xfer), first the rpipe has to be aimed and
351prepared (buffers assigned), then we can start queueing requests for
352data in or out.
353354Data buffers have to be segmented out before sending--so we send first a
355header (segment request) and then if there is any data, a data buffer
356immediately after to the DTI interface (yep, even the request). If our
357buffer is bigger than the max segment size, then we just do multiple
358requests.
359360[This sucks, because doing USB scatter gatter in Linux is resource
361intensive, if any...not that the current approach is not. It just has to
362be cleaned up a lot :)].
363364If reading, we don't send data buffers, just the segment headers saying
365we want to read segments.
366367When the xfer is executed, we receive a notification that says data is
368ready in the DTI endpoint (handled through
369xfer.c:wa_handle_notif_xfer()). In there we read from the DTI endpoint a
370descriptor 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,
372we issue another URB to read into the destination buffer the chunk of
373data coming out of the remote endpoint. Done, wait for the next guy. The
374callbacks for the URBs issued from here are the ones that will declare
375the xfer complete at some point and call its callback.
376377Seems simple, but the implementation is not trivial.
378379 *
380381 *WARNING* Old!!
382383The main xfer descriptor, wa_xfer (equivalent to a URB) contains an
384array of segments, tallys on segments and buffers and callback
385information. Buried in there is a lot of URBs for executing the segments
386and buffer transfers.
387388For OUT xfers, there is an array of segments, one URB for each, another
389one of buffer URB. When submitting, we submit URBs for segment request
3901, buffer 1, segment 2, buffer 2...etc. Then we wait on the DTI for xfer
391result data; when all the segments are complete, we call the callback to
392finalize the transfer.
393394For IN xfers, we only issue URBs for the segments we want to read and
395then wait for the xfer result data.
396397*URB mapping into xfers*
398399This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an
400rpipe to the endpoint where we have to transmit, create a transfer
401context (wa_xfer) and submit it. When the xfer is done, our callback is
402called and we assign the status bits and release the xfer resources.
403404In dequeue() we are basically cancelling/aborting the transfer. We issue
405a xfer abort request to the HC, cancel all the URBs we had submitted
406and not yet done and when all that is done, the xfer callback will be
407called--this will call the URB callback.
408409410 Glossary
411412*DWA* -- Device Wire Adapter
413414USB host, wired for downstream devices, upstream connects wirelessly
415with Wireless USB.
416417*EVENT* -- Response to a command on the NEEP
418419*HWA* -- Host Wire Adapter / USB dongle for UWB and Wireless USB
420421*NEH* -- Notification/Event Handle
422423Handle/file descriptor for receiving notifications or events. The WA
424code requires you to get one of this to listen for notifications or
425events on the NEEP.
426427*NEEP* -- Notification/Event EndPoint
428429Stuff related to the management of the first endpoint of a HWA USB
430dongle that is used to deliver an stream of events and notifications to
431the host.
432433*NOTIFICATION* -- Message coming in the NEEP as response to something.
434435*RC* -- Radio Control
436437Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by
438InakyPerezGonzalez)