aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/usb
diff options
context:
space:
mode:
authorInaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>2008-09-17 11:34:04 -0400
committerDavid Vrabel <dv02@dv02pc01.europe.root.pri>2008-09-17 11:54:23 -0400
commit99d368bc9e279a2a5e56f3afe32166260e90caa7 (patch)
tree44f73064afa9929f09cd2613e4e4cb737fb62b0f /Documentation/usb
parentccbe329bcd87924baed96474ec0a6725e3957897 (diff)
uwb: add initial documentation
Documentation (and example utilities) for the UWB (and WUSB) stacks. Some of the documentation may be out-of-date. Signed-off-by: David Vrabel <david.vrabel@csr.com>
Diffstat (limited to 'Documentation/usb')
-rw-r--r--Documentation/usb/WUSB-Design-overview.txt448
-rw-r--r--Documentation/usb/wusb-cbaf133
2 files changed, 581 insertions, 0 deletions
diff --git a/Documentation/usb/WUSB-Design-overview.txt b/Documentation/usb/WUSB-Design-overview.txt
new file mode 100644
index 000000000000..4c3d62c7843a
--- /dev/null
+++ b/Documentation/usb/WUSB-Design-overview.txt
@@ -0,0 +1,448 @@
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 assingment, 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
187dissapear.
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
336Everytime there is a succesful 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 it's 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, cancell 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
diff --git a/Documentation/usb/wusb-cbaf b/Documentation/usb/wusb-cbaf
new file mode 100644
index 000000000000..a385478ba12e
--- /dev/null
+++ b/Documentation/usb/wusb-cbaf
@@ -0,0 +1,133 @@
1#! /bin/bash
2#
3
4set -e
5
6progname=$(basename $0)
7function help
8{
9 cat <<EOF
10Usage: $progname COMMAND DEVICEs [ARGS]
11
12Command for manipulating the pairing/authentication credentials of a
13Wireless USB device that supports wired-mode Cable-Based-Association.
14
15Works in conjunction with the wusb-cba.ko driver from http://linuxuwb.org.
16
17
18DEVICE
19
20 sysfs path to the device to authenticate; for example, both this
21 guys are the same:
22
23 /sys/devices/pci0000:00/0000:00:1d.7/usb1/1-4/1-4.4/1-4.4:1.1
24 /sys/bus/usb/drivers/wusb-cbaf/1-4.4:1.1
25
26COMMAND/ARGS are
27
28 start
29
30 Start a WUSB host controller (by setting up a CHID)
31
32 set-chid DEVICE HOST-CHID HOST-BANDGROUP HOST-NAME
33
34 Sets host information in the device; after this you can call the
35 get-cdid to see how does this device report itself to us.
36
37 get-cdid DEVICE
38
39 Get the device ID associated to the HOST-CHDI we sent with
40 'set-chid'. We might not know about it.
41
42 set-cc DEVICE
43
44 If we allow the device to connect, set a random new CDID and CK
45 (connection key). Device saves them for the next time it wants to
46 connect wireless. We save them for that next time also so we can
47 authenticate the device (when we see the CDID he uses to id
48 itself) and the CK to crypto talk to it.
49
50CHID is always 16 hex bytes in 'XX YY ZZ...' form
51BANDGROUP is almost always 0001
52
53Examples:
54
55 You can default most arguments to '' to get a sane value:
56
57 $ $progname set-chid '' '' '' "My host name"
58
59 A full sequence:
60
61 $ $progname set-chid '' '' '' "My host name"
62 $ $progname get-cdid ''
63 $ $progname set-cc ''
64
65EOF
66}
67
68
69# Defaults
70# FIXME: CHID should come from a database :), band group from the host
71host_CHID="00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff"
72host_band_group="0001"
73host_name="Linux-WUSB"
74
75devs="$(echo /sys/bus/usb/drivers/wusb-cbaf/[0-9]*)"
76hdevs="$(find /sys -name wusb_chid -printf "%h\n")"
77
78result=0
79case $1 in
80 start)
81 for dev in ${2:-$hdevs}
82 do
83 uwb_rc=$(find $(dirname $(dirname $dev)) -iname uwb_rc:uwb*)
84 if cat $uwb_rc/uwb_rc/beacon | grep -q "channel: -1"
85 then
86 echo 13 0 | cat > $uwb_rc/uwb_rc/beacon
87 echo I: started beaconing on ch 13 in host $(basename $uwb_rc)
88 fi
89 echo $host_CHID | cat > $dev/wusb_chid
90 echo I: started host $(basename $dev)
91 done
92 ;;
93 set-chid)
94 shift
95 for dev in ${2:-$devs}
96 do
97 echo "${2:-$host_CHID}" "${3:-$host_band_group}" "${4:-$host_name}" \
98 | cat > $dev/wusb_host_info
99 done
100 ;;
101 get-cdid)
102 for dev in ${2:-$devs}
103 do
104 cat $dev/wusb_cdid
105 done
106 ;;
107 set-cc)
108 for dev in ${2:-$devs}
109 do
110 shift
111 CDID="$(head --bytes=16 /dev/urandom | od -tx1 -An)"
112 CK="$(head --bytes=16 /dev/urandom | od -tx1 -An)"
113 cat > $dev/wusb_cc <<EOF
114CDID:$CDID
115CK:$CK
116EOF
117 cat <<EOF
118I: CC set
119CHID: $host_CHID
120CDID:$CDID
121CK: $CK
122EOF
123 done
124 ;;
125 help|h|--help|-h)
126 help
127 ;;
128 *)
129 echo "E: Unknown usage" 1>&2
130 help 1>&2
131 result=1
132esac
133exit $result