From 99d368bc9e279a2a5e56f3afe32166260e90caa7 Mon Sep 17 00:00:00 2001 From: Inaky Perez-Gonzalez Date: Wed, 17 Sep 2008 16:34:04 +0100 Subject: 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 --- Documentation/usb/WUSB-Design-overview.txt | 448 +++++++++++++++++++++++++++++ Documentation/usb/wusb-cbaf | 133 +++++++++ 2 files changed, 581 insertions(+) create mode 100644 Documentation/usb/WUSB-Design-overview.txt create mode 100644 Documentation/usb/wusb-cbaf (limited to 'Documentation') 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 @@ + +Linux UWB + Wireless USB + WiNET + + (C) 2005-2006 Intel Corporation + Inaky Perez-Gonzalez + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License version + 2 as published by the Free Software Foundation. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA. + + +Please visit http://bughost.org/thewiki/Design-overview.txt-1.8 for +updated content. + + * Design-overview.txt-1.8 + +This code implements a Ultra Wide Band stack for Linux, as well as +drivers for the the USB based UWB radio controllers defined in the +Wireless USB 1.0 specification (including Wireless USB host controller +and an Intel WiNET controller). + + 1. Introduction + 1. HWA: Host Wire adapters, your Wireless USB dongle + + 2. DWA: Device Wired Adaptor, a Wireless USB hub for wired + devices + 3. WHCI: Wireless Host Controller Interface, the PCI WUSB host + adapter + 2. The UWB stack + 1. Devices and hosts: the basic structure + + 2. Host Controller life cycle + + 3. On the air: beacons and enumerating the radio neighborhood + + 4. Device lists + 5. Bandwidth allocation + + 3. Wireless USB Host Controller drivers + + 4. Glossary + + + Introduction + +UWB is a wide-band communication protocol that is to serve also as the +low-level protocol for others (much like TCP sits on IP). Currently +these others are Wireless USB and TCP/IP, but seems Bluetooth and +Firewire/1394 are coming along. + +UWB uses a band from roughly 3 to 10 GHz, transmitting at a max of +~-41dB (or 0.074 uW/MHz--geography specific data is still being +negotiated w/ regulators, so watch for changes). That band is divided in +a bunch of ~1.5 GHz wide channels (or band groups) composed of three +subbands/subchannels (528 MHz each). Each channel is independent of each +other, so you could consider them different "busses". Initially this +driver considers them all a single one. + +Radio time is divided in 65536 us long /superframes/, each one divided +in 256 256us long /MASs/ (Media Allocation Slots), which are the basic +time/media allocation units for transferring data. At the beginning of +each superframe there is a Beacon Period (BP), where every device +transmit its beacon on a single MAS. The length of the BP depends on how +many devices are present and the length of their beacons. + +Devices have a MAC (fixed, 48 bit address) and a device (changeable, 16 +bit address) and send periodic beacons to advertise themselves and pass +info on what they are and do. They advertise their capabilities and a +bunch of other stuff. + +The different logical parts of this driver are: + + * + + *UWB*: the Ultra-Wide-Band stack -- manages the radio and + associated spectrum to allow for devices sharing it. Allows to + control bandwidth assingment, beaconing, scanning, etc + + * + + *WUSB*: the layer that sits on top of UWB to provide Wireless USB. + The Wireless USB spec defines means to control a UWB radio and to + do the actual WUSB. + + + HWA: Host Wire adapters, your Wireless USB dongle + +WUSB also defines a device called a Host Wire Adaptor (HWA), which in +mere terms is a USB dongle that enables your PC to have UWB and Wireless +USB. The Wireless USB Host Controller in a HWA looks to the host like a +[Wireless] USB controller connected via USB (!) + +The HWA itself is broken in two or three main interfaces: + + * + + *RC*: Radio control -- this implements an interface to the + Ultra-Wide-Band radio controller. The driver for this implements a + USB-based UWB Radio Controller to the UWB stack. + + * + + *HC*: the wireless USB host controller. It looks like a USB host + whose root port is the radio and the WUSB devices connect to it. + To the system it looks like a separate USB host. The driver (will) + implement a USB host controller (similar to UHCI, OHCI or EHCI) + for which the root hub is the radio...To reiterate: it is a USB + controller that is connected via USB instead of PCI. + + * + + *WINET*: some HW provide a WiNET interface (IP over UWB). This + package provides a driver for it (it looks like a network + interface, winetX). The driver detects when there is a link up for + their type and kick into gear. + + + DWA: Device Wired Adaptor, a Wireless USB hub for wired devices + +These are the complement to HWAs. They are a USB host for connecting +wired devices, but it is connected to your PC connected via Wireless +USB. To the system it looks like yet another USB host. To the untrained +eye, it looks like a hub that connects upstream wirelessly. + +We still offer no support for this; however, it should share a lot of +code with the HWA-RC driver; there is a bunch of factorization work that +has been done to support that in upcoming releases. + + + WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter + +This is your usual PCI device that implements WHCI. Similar in concept +to EHCI, it allows your wireless USB devices (including DWAs) to connect +to your host via a PCI interface. As in the case of the HWA, it has a +Radio Control interface and the WUSB Host Controller interface per se. + +There is still no driver support for this, but will be in upcoming +releases. + + + The UWB stack + +The main mission of the UWB stack is to keep a tally of which devices +are in radio proximity to allow drivers to connect to them. As well, it +provides an API for controlling the local radio controllers (RCs from +now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. + + + Devices and hosts: the basic structure + +The main building block here is the UWB device (struct uwb_dev). For +each device that pops up in radio presence (ie: the UWB host receives a +beacon from it) you get a struct uwb_dev that will show up in +/sys/class/uwb and in /sys/bus/uwb/devices. + +For each RC that is detected, a new struct uwb_rc is created. In turn, a +RC is also a device, so they also show in /sys/class/uwb and +/sys/bus/uwb/devices, but at the same time, only radio controllers show +up in /sys/class/uwb_rc. + + * + + [*] The reason for RCs being also devices is that not only we can + see them while enumerating the system device tree, but also on the + radio (their beacons and stuff), so the handling has to be + likewise to that of a device. + +Each RC driver is implemented by a separate driver that plugs into the +interface that the UWB stack provides through a struct uwb_rc_ops. The +spec creators have been nice enough to make the message format the same +for HWA and WHCI RCs, so the driver is really a very thin transport that +moves the requests from the UWB API to the device [/uwb_rc_ops->cmd()/] +and sends the replies and notifications back to the API +[/uwb_rc_neh_grok()/]. Notifications are handled to the UWB daemon, that +is chartered, among other things, to keep the tab of how the UWB radio +neighborhood looks, creating and destroying devices as they show up or +dissapear. + +Command execution is very simple: a command block is sent and a event +block or reply is expected back. For sending/receiving command/events, a +handle called /neh/ (Notification/Event Handle) is opened with +/uwb_rc_neh_open()/. + +The HWA-RC (USB dongle) driver (drivers/uwb/hwa-rc.c) does this job for +the USB connected HWA. Eventually, drivers/whci-rc.c will do the same +for the PCI connected WHCI controller. + + + Host Controller life cycle + +So let's say we connect a dongle to the system: it is detected and +firmware uploaded if needed [for Intel's i1480 +/drivers/uwb/ptc/usb.c:ptc_usb_probe()/] and then it is reenumerated. +Now we have a real HWA device connected and +/drivers/uwb/hwa-rc.c:hwarc_probe()/ picks it up, that will set up the +Wire-Adaptor environment and then suck it into the UWB stack's vision of +the world [/drivers/uwb/lc-rc.c:uwb_rc_add()/]. + + * + + [*] The stack should put a new RC to scan for devices + [/uwb_rc_scan()/] so it finds what's available around and tries to + connect to them, but this is policy stuff and should be driven + from user space. As of now, the operator is expected to do it + manually; see the release notes for documentation on the procedure. + +When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ +takes time of tearing everything down safely (or not...). + + + On the air: beacons and enumerating the radio neighborhood + +So assuming we have devices and we have agreed for a channel to connect +on (let's say 9), we put the new RC to beacon: + + * + + $ echo 9 0 > /sys/class/uwb_rc/uwb0/beacon + +Now it is visible. If there were other devices in the same radio channel +and beacon group (that's what the zero is for), the dongle's radio +control interface will send beacon notifications on its +notification/event endpoint (NEEP). The beacon notifications are part of +the event stream that is funneled into the API with +/drivers/uwb/neh.c:uwb_rc_neh_grok()/ and delivered to the UWBD, the UWB +daemon through a notification list. + +UWBD wakes up and scans the event list; finds a beacon and adds it to +the BEACON CACHE (/uwb_beca/). If he receives a number of beacons from +the same device, he considers it to be 'onair' and creates a new device +[/drivers/uwb/lc-dev.c:uwbd_dev_onair()/]. Similarly, when no beacons +are received in some time, the device is considered gone and wiped out +[uwbd calls periodically /uwb/beacon.c:uwb_beca_purge()/ that will purge +the beacon cache of dead devices]. + + + Device lists + +All UWB devices are kept in the list of the struct bus_type uwb_bus. + + + Bandwidth allocation + +The UWB stack maintains a local copy of DRP availability through +processing of incoming *DRP Availability Change* notifications. This +local copy is currently used to present the current bandwidth +availability to the user through the sysfs file +/sys/class/uwb_rc/uwbx/bw_avail. In the future the bandwidth +availability information will be used by the bandwidth reservation +routines. + +The bandwidth reservation routines are in progress and are thus not +present in the current release. When completed they will enable a user +to initiate DRP reservation requests through interaction with sysfs. DRP +reservation requests from remote UWB devices will also be handled. The +bandwidth management done by the UWB stack will include callbacks to the +higher layers will enable the higher layers to use the reservations upon +completion. [Note: The bandwidth reservation work is in progress and +subject to change.] + + + Wireless USB Host Controller drivers + +*WARNING* This section needs a lot of work! + +As explained above, there are three different types of HCs in the WUSB +world: HWA-HC, DWA-HC and WHCI-HC. + +HWA-HC and DWA-HC share that they are Wire-Adapters (USB or WUSB +connected controllers), and their transfer management system is almost +identical. So is their notification delivery system. + +HWA-HC and WHCI-HC share that they are both WUSB host controllers, so +they have to deal with WUSB device life cycle and maintenance, wireless +root-hub + +HWA exposes a Host Controller interface (HWA-HC 0xe0/02/02). This has +three endpoints (Notifications, Data Transfer In and Data Transfer +Out--known as NEP, DTI and DTO in the code). + +We reserve UWB bandwidth for our Wireless USB Cluster, create a Cluster +ID and tell the HC to use all that. Then we start it. This means the HC +starts sending MMCs. + + * + + The MMCs are blocks of data defined somewhere in the WUSB1.0 spec + that define a stream in the UWB channel time allocated for sending + WUSB IEs (host to device commands/notifications) and Device + Notifications (device initiated to host). Each host defines a + unique Wireless USB cluster through MMCs. Devices can connect to a + single cluster at the time. The IEs are Information Elements, and + among them are the bandwidth allocations that tell each device + when can they transmit or receive. + +Now it all depends on external stimuli. + +*New device connection* + +A new device pops up, it scans the radio looking for MMCs that give out +the existence of Wireless USB channels. Once one (or more) are found, +selects which one to connect to. Sends a /DN_Connect/ (device +notification connect) during the DNTS (Device Notification Time +Slot--announced in the MMCs + +HC picks the /DN_Connect/ out (nep module sends to notif.c for delivery +into /devconnect/). This process starts the authentication process for +the device. First we allocate a /fake port/ and assign an +unauthenticated address (128 to 255--what we really do is +0x80 | fake_port_idx). We fiddle with the fake port status and /khubd/ +sees a new connection, so he moves on to enable the fake port with a reset. + +So now we are in the reset path -- we know we have a non-yet enumerated +device with an unauthorized address; we ask user space to authenticate +(FIXME: not yet done, similar to bluetooth pairing), then we do the key +exchange (FIXME: not yet done) and issue a /set address 0/ to bring the +device to the default state. Device is authenticated. + +From here, the USB stack takes control through the usb_hcd ops. khubd +has seen the port status changes, as we have been toggling them. It will +start enumerating and doing transfers through usb_hcd->urb_enqueue() to +read descriptors and move our data. + +*Device life cycle and keep alives* + +Everytime there is a succesful transfer to/from a device, we update a +per-device activity timestamp. If not, every now and then we check and +if the activity timestamp gets old, we ping the device by sending it a +Keep Alive IE; it responds with a /DN_Alive/ pong during the DNTS (this +arrives to us as a notification through +devconnect.c:wusb_handle_dn_alive(). If a device times out, we +disconnect it from the system (cleaning up internal information and +toggling the bits in the fake hub port, which kicks khubd into removing +the rest of the stuff). + +This is done through devconnect:__wusb_check_devs(), which will scan the +device list looking for whom needs refreshing. + +If the device wants to disconnect, it will either die (ugly) or send a +/DN_Disconnect/ that will prompt a disconnection from the system. + +*Sending and receiving data* + +Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is +/aimed/ at an endpoint in a WUSB device. This is the same for HWAs and +DWAs. + +Each HC has a number of rpipes and buffers that can be assigned to them; +when doing a data transfer (xfer), first the rpipe has to be aimed and +prepared (buffers assigned), then we can start queueing requests for +data in or out. + +Data buffers have to be segmented out before sending--so we send first a +header (segment request) and then if there is any data, a data buffer +immediately after to the DTI interface (yep, even the request). If our +buffer is bigger than the max segment size, then we just do multiple +requests. + +[This sucks, because doing USB scatter gatter in Linux is resource +intensive, if any...not that the current approach is not. It just has to +be cleaned up a lot :)]. + +If reading, we don't send data buffers, just the segment headers saying +we want to read segments. + +When the xfer is executed, we receive a notification that says data is +ready in the DTI endpoint (handled through +xfer.c:wa_handle_notif_xfer()). In there we read from the DTI endpoint a +descriptor that gives us the status of the transfer, its identification +(given when we issued it) and the segment number. If it was a data read, +we issue another URB to read into the destination buffer the chunk of +data coming out of the remote endpoint. Done, wait for the next guy. The +callbacks for the URBs issued from here are the ones that will declare +the xfer complete at some point and call it's callback. + +Seems simple, but the implementation is not trivial. + + * + + *WARNING* Old!! + +The main xfer descriptor, wa_xfer (equivalent to a URB) contains an +array of segments, tallys on segments and buffers and callback +information. Buried in there is a lot of URBs for executing the segments +and buffer transfers. + +For OUT xfers, there is an array of segments, one URB for each, another +one of buffer URB. When submitting, we submit URBs for segment request +1, buffer 1, segment 2, buffer 2...etc. Then we wait on the DTI for xfer +result data; when all the segments are complete, we call the callback to +finalize the transfer. + +For IN xfers, we only issue URBs for the segments we want to read and +then wait for the xfer result data. + +*URB mapping into xfers* + +This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an +rpipe to the endpoint where we have to transmit, create a transfer +context (wa_xfer) and submit it. When the xfer is done, our callback is +called and we assign the status bits and release the xfer resources. + +In dequeue() we are basically cancelling/aborting the transfer. We issue +a xfer abort request to the HC, cancell all the URBs we had submitted +and not yet done and when all that is done, the xfer callback will be +called--this will call the URB callback. + + + Glossary + +*DWA* -- Device Wire Adapter + +USB host, wired for downstream devices, upstream connects wirelessly +with Wireless USB. + +*EVENT* -- Response to a command on the NEEP + +*HWA* -- Host Wire Adapter / USB dongle for UWB and Wireless USB + +*NEH* -- Notification/Event Handle + +Handle/file descriptor for receiving notifications or events. The WA +code requires you to get one of this to listen for notifications or +events on the NEEP. + +*NEEP* -- Notification/Event EndPoint + +Stuff related to the management of the first endpoint of a HWA USB +dongle that is used to deliver an stream of events and notifications to +the host. + +*NOTIFICATION* -- Message coming in the NEEP as response to something. + +*RC* -- Radio Control + +Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by +InakyPerezGonzalez) + 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 @@ +#! /bin/bash +# + +set -e + +progname=$(basename $0) +function help +{ + cat < $uwb_rc/uwb_rc/beacon + echo I: started beaconing on ch 13 in host $(basename $uwb_rc) + fi + echo $host_CHID | cat > $dev/wusb_chid + echo I: started host $(basename $dev) + done + ;; + set-chid) + shift + for dev in ${2:-$devs} + do + echo "${2:-$host_CHID}" "${3:-$host_band_group}" "${4:-$host_name}" \ + | cat > $dev/wusb_host_info + done + ;; + get-cdid) + for dev in ${2:-$devs} + do + cat $dev/wusb_cdid + done + ;; + set-cc) + for dev in ${2:-$devs} + do + shift + CDID="$(head --bytes=16 /dev/urandom | od -tx1 -An)" + CK="$(head --bytes=16 /dev/urandom | od -tx1 -An)" + cat > $dev/wusb_cc <&2 + help 1>&2 + result=1 +esac +exit $result -- cgit v1.2.3 From c8cf2465fcfc16877f4f9e8dccc6b89b543fa2c5 Mon Sep 17 00:00:00 2001 From: David Vrabel Date: Wed, 17 Sep 2008 16:34:41 +0100 Subject: uwb: document UWB and WUSB sysfs files Add some brief documentation on the UWB and WUSB related sysfs files. Signed-off-by: David Vrabel --- Documentation/ABI/testing/sysfs-bus-umc | 28 +++++ Documentation/ABI/testing/sysfs-bus-usb | 43 ++++++++ Documentation/ABI/testing/sysfs-class-usb_host | 25 +++++ Documentation/ABI/testing/sysfs-class-uwb_rc | 144 +++++++++++++++++++++++++ Documentation/ABI/testing/sysfs-wusb_cbaf | 100 +++++++++++++++++ 5 files changed, 340 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-bus-umc create mode 100644 Documentation/ABI/testing/sysfs-class-usb_host create mode 100644 Documentation/ABI/testing/sysfs-class-uwb_rc create mode 100644 Documentation/ABI/testing/sysfs-wusb_cbaf (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-umc b/Documentation/ABI/testing/sysfs-bus-umc new file mode 100644 index 000000000000..948fec412446 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-umc @@ -0,0 +1,28 @@ +What: /sys/bus/umc/ +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + The Wireless Host Controller Interface (WHCI) + specification describes a PCI-based device with + multiple capabilities; the UWB Multi-interface + Controller (UMC). + + The umc bus presents each of the individual + capabilties as a device. + +What: /sys/bus/umc/devices/.../capability_id +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + The ID of this capability, with 0 being the radio + controller capability. + +What: /sys/bus/umc/devices/.../version +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + The specification version this capability's hardware + interface complies with. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 11a3c1682cec..273a7f099f46 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -85,3 +85,46 @@ Description: Users: PowerTOP http://www.lesswatts.org/projects/powertop/ + +What: /sys/bus/usb/device/.../authorized +Date: July 2008 +KernelVersion: 2.6.26 +Contact: David Vrabel +Description: + Authorized devices are available for use by device + drivers, non-authorized one are not. By default, wired + USB devices are authorized. + + Certified Wireless USB devices are not authorized + initially and should be (by writing 1) after the + device has been authenticated. + +What: /sys/bus/usb/device/.../wusb_cdid +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + For Certified Wireless USB devices only. + + A devices's CDID, as 16 space-separated hex octets. + +What: /sys/bus/usb/device/.../wusb_ck +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + For Certified Wireless USB devices only. + + Write the device's connection key (CK) to start the + authentication of the device. The CK is 16 + space-separated hex octets. + +What: /sys/bus/usb/device/.../wusb_disconnect +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + For Certified Wireless USB devices only. + + Write a 1 to force the device to disconnect + (equivalent to unplugging a wired USB device). diff --git a/Documentation/ABI/testing/sysfs-class-usb_host b/Documentation/ABI/testing/sysfs-class-usb_host new file mode 100644 index 000000000000..46b66ad1f1b4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-usb_host @@ -0,0 +1,25 @@ +What: /sys/class/usb_host/usb_hostN/wusb_chid +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + Write the CHID (16 space-separated hex octets) for this host controller. + This starts the host controller, allowing it to accept connection from + WUSB devices. + + Set an all zero CHID to stop the host controller. + +What: /sys/class/usb_host/usb_hostN/wusb_trust_timeout +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + Devices that haven't sent a WUSB packet to the host + within 'wusb_trust_timeout' ms are considered to have + disconnected and are removed. The default value of + 4000 ms is the value required by the WUSB + specification. + + Since this relates to security (specifically, the + lifetime of PTKs and GTKs) it should not be changed + from the default. diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc new file mode 100644 index 000000000000..a0d18dbeb7a9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-uwb_rc @@ -0,0 +1,144 @@ +What: /sys/class/uwb_rc +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Interfaces for WiMedia Ultra Wideband Common Radio + Platform (UWB) radio controllers. + + Familiarity with the ECMA-368 'High Rate Ultra + Wideband MAC and PHY Specification' is assumed. + +What: /sys/class/uwb_rc/beacon_timeout_ms +Date: July 2008 +KernelVersion: 2.6.27 +Description: + If no beacons are received from a device for at least + this time, the device will be considered to have gone + and it will be removed. The default is 3 superframes + (~197 ms) as required by the specification. + +What: /sys/class/uwb_rc/uwbN/ +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + An individual UWB radio controller. + +What: /sys/class/uwb_rc/uwbN/beacon +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Write: + + [] + + to start beaconing on a specific channel, or stop + beaconing if is -1. Valid channels depends + on the radio controller's supported band groups. + + may be used to try and join a specific + beacon group if more than one was found during a scan. + +What: /sys/class/uwb_rc/uwbN/scan +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Write: + + [] + + to start (or stop) scanning on a channel. is one of: + 0 - scan + 1 - scan outside BP + 2 - scan while inactive + 3 - scanning disabled + 4 - scan (with start time of ) + +What: /sys/class/uwb_rc/uwbN/mac_address +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + The EUI-48, in colon-separated hex octets, for this + radio controller. A write will change the radio + controller's EUI-48 but only do so while the device is + not beaconing or scanning. + +What: /sys/class/uwb_rc/uwbN/wusbhc +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + A symlink to the device (if any) of the WUSB Host + Controller PAL using this radio controller. + +What: /sys/class/uwb_rc/uwbN// +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + A neighbour UWB device that has either been detected + as part of a scan or is a member of the radio + controllers beacon group. + +What: /sys/class/uwb_rc/uwbN//BPST +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + The time (using the radio controllers internal 1 ms + interval superframe timer) of the last beacon from + this device was received. + +What: /sys/class/uwb_rc/uwbN//DevAddr +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + The current DevAddr of this device in colon separated + hex octets. + +What: /sys/class/uwb_rc/uwbN//EUI_48 +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + + The EUI-48 of this device in colon separated hex + octets. + +What: /sys/class/uwb_rc/uwbN//BPST +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + +What: /sys/class/uwb_rc/uwbN//IEs +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + The latest IEs included in this device's beacon, in + space separated hex octets with one IE per line. + +What: /sys/class/uwb_rc/uwbN//LQE +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Link Quality Estimate - the Signal to Noise Ratio + (SNR) of all packets received from this device in dB. + This gives an estimate on a suitable PHY rate. Refer + to [ECMA-368] section 13.3 for more details. + +What: /sys/class/uwb_rc/uwbN//RSSI +Date: July 2008 +KernelVersion: 2.6.27 +Contact: linux-usb@vger.kernel.org +Description: + Received Signal Strength Indication - the strength of + the received signal in dB. LQE is a more useful + measure of the radio link quality. diff --git a/Documentation/ABI/testing/sysfs-wusb_cbaf b/Documentation/ABI/testing/sysfs-wusb_cbaf new file mode 100644 index 000000000000..a99c5f86a37a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-wusb_cbaf @@ -0,0 +1,100 @@ +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_* +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + Various files for managing Cable Based Association of + (wireless) USB devices. + + The sequence of operations should be: + + 1. Device is plugged in. + + 2. The connection manager (CM) sees a device with CBA capability. + (the wusb_chid etc. files in /sys/devices/blah/OURDEVICE). + + 3. The CM writes the host name, supported band groups, + and the CHID (host ID) into the wusb_host_name, + wusb_host_band_groups and wusb_chid files. These + get sent to the device and the CDID (if any) for + this host is requested. + + 4. The CM can verify that the device's supported band + groups (wusb_device_band_groups) are compatible + with the host. + + 5. The CM reads the wusb_cdid file. + + 6. The CM looks it up its database. + + - If it has a matching CHID,CDID entry, the device + has been authorized before and nothing further + needs to be done. + + - If the CDID is zero (or the CM doesn't find a + matching CDID in its database), the device is + assumed to be not known. The CM may associate + the host with device by: writing a randomly + generated CDID to wusb_cdid and then a random CK + to wusb_ck (this uploads the new CC to the + device). + + CMD may choose to prompt the user before + associating with a new device. + + 7. Device is unplugged. + + References: + [WUSB-AM] Association Models Supplement to the + Certified Wireless Universal Serial Bus + Specification, version 1.0. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_chid +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + The CHID of the host formatted as 16 space-separated + hex octets. + + Writes fetches device's supported band groups and the + the CDID for any existing association with this host. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_name +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + A friendly name for the host as a UTF-8 encoded string. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_band_groups +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + The band groups supported by the host, in the format + defined in [WUSB-AM]. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_device_band_groups +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + The band groups supported by the device, in the format + defined in [WUSB-AM]. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_cdid +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + The device's CDID formatted as 16 space-separated hex + octets. + +What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_ck +Date: August 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel +Description: + Write 16 space-separated random, hex octets to + associate with the device. -- cgit v1.2.3 From f1fa035f2bcb2b03cb90249e05ec2ae6927a7302 Mon Sep 17 00:00:00 2001 From: Felipe Zimmerle Date: Wed, 17 Sep 2008 16:34:42 +0100 Subject: wusb: wusb-cbaf (CBA driver) sysfs ABI simplification Simplify the sysfs ABI of the wusb-cbaf (Cable Based Association) driver: use one value per file and cause the write of the CHID to fetch the CDID (instead of requiring a separate read). Update the example wusb-cbaf script to work with this revised ABI. Signed-off-by: Felipe Zimmerle Signed-off-by: David Vrabel --- Documentation/usb/wusb-cbaf | 60 ++--- drivers/usb/wusbcore/Kconfig | 23 ++ drivers/usb/wusbcore/Makefile | 8 +- drivers/usb/wusbcore/cbaf.c | 521 +++++++++++++++++++++++------------------- 4 files changed, 350 insertions(+), 262 deletions(-) (limited to 'Documentation') diff --git a/Documentation/usb/wusb-cbaf b/Documentation/usb/wusb-cbaf index a385478ba12e..2e78b70f3adc 100644 --- a/Documentation/usb/wusb-cbaf +++ b/Documentation/usb/wusb-cbaf @@ -70,32 +70,42 @@ EOF # FIXME: CHID should come from a database :), band group from the host host_CHID="00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff" host_band_group="0001" -host_name="Linux-WUSB" +host_name=$(hostname) devs="$(echo /sys/bus/usb/drivers/wusb-cbaf/[0-9]*)" -hdevs="$(find /sys -name wusb_chid -printf "%h\n")" +hdevs="$(for h in /sys/class/uwb_rc/*/wusbhc; do readlink -f $h; done)" result=0 case $1 in start) for dev in ${2:-$hdevs} do - uwb_rc=$(find $(dirname $(dirname $dev)) -iname uwb_rc:uwb*) - if cat $uwb_rc/uwb_rc/beacon | grep -q "channel: -1" + uwb_rc=$(readlink -f $dev/uwb_rc) + if cat $uwb_rc/beacon | grep -q -- "-1" then - echo 13 0 | cat > $uwb_rc/uwb_rc/beacon - echo I: started beaconing on ch 13 in host $(basename $uwb_rc) + echo 13 0 > $uwb_rc/beacon + echo I: started beaconing on ch 13 on $(basename $uwb_rc) >&2 fi - echo $host_CHID | cat > $dev/wusb_chid - echo I: started host $(basename $dev) + echo $host_CHID > $dev/wusb_chid + echo I: started host $(basename $dev) >&2 + done + ;; + stop) + for dev in ${2:-$hdevs} + do + echo 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 > $dev/wusb_chid + echo I: stopped host $(basename $dev) >&2 + uwb_rc=$(readlink -f $dev/uwb_rc) + echo -1 | cat > $uwb_rc/beacon + echo I: stopped beaconing on $(basename $uwb_rc) >&2 done ;; set-chid) shift - for dev in ${2:-$devs} - do - echo "${2:-$host_CHID}" "${3:-$host_band_group}" "${4:-$host_name}" \ - | cat > $dev/wusb_host_info + for dev in ${2:-$devs}; do + echo "${4:-$host_name}" > $dev/wusb_host_name + echo "${3:-$host_band_group}" > $dev/wusb_host_band_groups + echo ${2:-$host_CHID} > $dev/wusb_chid done ;; get-cdid) @@ -105,21 +115,17 @@ case $1 in done ;; set-cc) - for dev in ${2:-$devs} - do - shift - CDID="$(head --bytes=16 /dev/urandom | od -tx1 -An)" - CK="$(head --bytes=16 /dev/urandom | od -tx1 -An)" - cat > $dev/wusb_cc < $dev/wusb_cdid + echo "$CK" > $dev/wusb_ck + + echo I: CC set >&2 + echo "CHID: $(cat $dev/wusb_chid)" + echo "CDID:$CDID" + echo "CK: $CK" done ;; help|h|--help|-h) diff --git a/drivers/usb/wusbcore/Kconfig b/drivers/usb/wusbcore/Kconfig index add077e5c5d0..4ea76693ad46 100644 --- a/drivers/usb/wusbcore/Kconfig +++ b/drivers/usb/wusbcore/Kconfig @@ -15,3 +15,26 @@ config USB_WUSB To compile this support select Y (built in). It is safe to select even if you don't have the hardware. + +config USB_WUSB_CBAF + tristate "Support WUSB Cable Based Association (CBA)" + depends on USB + help + Some WUSB devices support Cable Based Association. It's used to + enable the secure communication between the host and the + device. + + Enable this option if your WUSB device must to be connected + via wired USB before establishing a wireless link. + + It is safe to select even if you don't have a compatible + hardware. + +config USB_WUSB_CBAF_DEBUG + bool "Enable CBA debug messages" + depends on USB_WUSB_CBAF + help + Say Y here if you want the CBA to produce a bunch of debug messages + to the system log. Select this if you are having a problem with + CBA support and want to see more of what is going on. + diff --git a/drivers/usb/wusbcore/Makefile b/drivers/usb/wusbcore/Makefile index 7a4d00724039..75f1ade66258 100644 --- a/drivers/usb/wusbcore/Makefile +++ b/drivers/usb/wusbcore/Makefile @@ -1,5 +1,7 @@ -obj-$(CONFIG_USB_WUSB) += wusbcore.o wusb-cbaf.o +obj-$(CONFIG_USB_WUSB) += wusbcore.o obj-$(CONFIG_USB_HWA_HCD) += wusb-wa.o +obj-$(CONFIG_USB_WUSB_CBAF) += wusb-cbaf.o + wusbcore-objs := \ crypto.o \ @@ -18,3 +20,7 @@ wusb-wa-objs := wa-hc.o \ wa-nep.o \ wa-rpipe.o \ wa-xfer.o + +ifeq ($(CONFIG_USB_WUSB_CBAF_DEBUG),y) +EXTRA_CFLAGS += -DDEBUG +endif diff --git a/drivers/usb/wusbcore/cbaf.c b/drivers/usb/wusbcore/cbaf.c index 584eabe274b3..ab4788d1785a 100644 --- a/drivers/usb/wusbcore/cbaf.c +++ b/drivers/usb/wusbcore/cbaf.c @@ -4,6 +4,7 @@ * * Copyright (C) 2006 Intel Corporation * Inaky Perez-Gonzalez + * Copyright (C) 2008 Cambridge Silicon Radio Ltd. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License version @@ -20,14 +21,13 @@ * 02110-1301, USA. * * - * WUSB devices have to be paired (authenticated in WUSB lingo) so + * WUSB devices have to be paired (associated in WUSB lingo) so * that they can connect to the system. * - * One way of pairing is using CBA-Cable Based Authentication, devices - * that can connect via wired or wireless USB. First time you plug - * them with a cable, pairing is done between host and device and - * subsequent times, you can connect wirelessly without having to - * pair. That's the idea. + * One way of pairing is using CBA-Cable Based Association. First + * time you plug the device with a cable, association is done between + * host and device and subsequent times, you can connect wirelessly + * without having to associate again. That's the idea. * * This driver does nothing Earth shattering. It just provides an * interface to chat with the wire-connected device so we can get a @@ -42,56 +42,49 @@ * * The process goes like this: * - * 1. device plugs, cbaf is loaded, notifications happen + * 1. Device plugs, cbaf is loaded, notifications happen. * - * 2. the connection manager sees a device with CBAF capability (the - * wusb_{host_info,cdid,cc} files are in /sys/device/blah/OURDEVICE). + * 2. The connection manager (CM) sees a device with CBAF capability + * (the wusb_chid etc. files in /sys/devices/blah/OURDEVICE). * - * 3. CM (connection manager) writes the CHID (host ID) and a host - * name into the wusb_host_info file. This gets sent to the device. + * 3. The CM writes the host name, supported band groups, and the CHID + * (host ID) into the wusb_host_name, wusb_host_band_groups and + * wusb_chid files. These get sent to the device and the CDID (if + * any) for this host is requested. * - * 4. CM cats the wusb_cdid file; this asks the device if it has any - * CDID associated to the CHDI we just wrote before. If it does, it - * is printed, along with the device 'friendly name' and the band - * groups the device supports. + * 4. The CM can verify that the device's supported band groups + * (wusb_device_band_groups) are compatible with the host. * - * 5. CM looks up its database + * 5. The CM reads the wusb_cdid file. * - * 5.1 If it has a matching CHID,CDID entry, the device has been - * authorized before (paired). Now we can optionally ask the user - * if he wants to allow the device to connect. Then we generate a - * new CDID and CK, send it to the device and update the database - * (writing to the wusb_cc file so they are uploaded to the device). + * 6. The CM looks up its database * - * 5.2 If the CDID is zero (or we didn't find a matching CDID in our - * database), we assume the device is not known. We ask the user - * if s/he wants to allow the device to be connected wirelessly - * to the system. If nope, nothing else is done (FIXME: maybe - * send a zero CDID to clean up our CHID?). If yes, we generate - * random CDID and CKs (and write them to the wusb_cc file so - * they are uploaded to the device). + * 6.1 If it has a matching CHID,CDID entry, the device has been + * authorized before (paired) and nothing further needs to be + * done. * - * 6. device is unplugged + * 6.2 If the CDID is zero (or the CM doesn't find a matching CDID in + * its database), the device is assumed to be not known. The CM + * may associate the host with device by: writing a randomly + * generated CDID to wusb_cdid and then a random CK to wusb_ck + * (this uploads the new CC to the device). * - * When the device tries to connect wirelessly, it will present it's - * CDID to the WUSB host controller with ID CHID, which will query the - * database. If found, the host will (with a 4way handshake) challenge - * the device to demonstrate it has the CK secret key (from our - * database) without actually exchanging it. Once satisfied, crypto - * keys are derived from the CK, the device is connected and all - * communication is crypted. + * CMD may choose to prompt the user before associating with a new + * device. * + * 7. Device is unplugged. * - * NOTES ABOUT THE IMPLEMENTATION + * When the device tries to connect wirelessly, it will present its + * CDID to the WUSB host controller. The CM will query the + * database. If the CHID/CDID pair found, it will (with a 4-way + * handshake) challenge the device to demonstrate it has the CK secret + * key (from our database) without actually exchanging it. Once + * satisfied, crypto keys are derived from the CK, the device is + * connected and all communication is encrypted. * - * The descriptors sent back and forth use this horrible format from - * hell on which each field is actually a field ID, field length and - * then the field itself. How stupid can that get, taking into account - * the structures are defined by the spec?? oh well. - * - * - * FIXME: we don't provide a way to tell the device the pairing failed - * (ie: send a CC_DATA_FAIL). Should add some day. + * References: + * [WUSB-AM] Association Models Supplement to the Certified Wireless + * Universal Serial Bus Specification, version 1.0. */ #include #include @@ -105,9 +98,7 @@ #include #include -#undef D_LOCAL -#define D_LOCAL 6 -#include +#define CBA_NAME_LEN 0x40 /* [WUSB-AM] table 4-7 */ /* An instance of a Cable-Based-Association-Framework device */ struct cbaf { @@ -116,24 +107,27 @@ struct cbaf { void *buffer; size_t buffer_size; - struct wusb_ckhdid chid;/* Host Information */ - char host_name[65]; /* max length: - Assoc Models Suplement 1.0[T4-7] */ + struct wusb_ckhdid chid; + char host_name[CBA_NAME_LEN]; u16 host_band_groups; - struct wusb_ckhdid cdid;/* Device Information */ - char device_name[65]; /* max length: - Assoc Models Suplement 1.0[T4-7] */ + struct wusb_ckhdid cdid; + char device_name[CBA_NAME_LEN]; u16 device_band_groups; - struct wusb_ckhdid ck; /* Connection Key */ + + struct wusb_ckhdid ck; }; /* * Verify that a CBAF USB-interface has what we need * - * (like we care, we are going to fail the enumeration if not :) + * According to [WUSB-AM], CBA devices should provide at least two + * interfaces: + * - RETRIEVE_HOST_INFO + * - ASSOCIATE * - * FIXME: ugly function, need to split + * If the device doesn't provide these interfaces, we do not know how + * to deal with it. */ static int cbaf_check(struct cbaf *cbaf) { @@ -143,8 +137,7 @@ static int cbaf_check(struct cbaf *cbaf) struct wusb_cbaf_assoc_request *assoc_request; size_t assoc_size; void *itr, *top; - unsigned ar_index; - int ar_rhi_idx = -1, ar_assoc_idx = -1; + int ar_rhi = 0, ar_assoc = 0; result = usb_control_msg( cbaf->usb_dev, usb_rcvctrlpipe(cbaf->usb_dev, 0), @@ -153,93 +146,91 @@ static int cbaf_check(struct cbaf *cbaf) 0, cbaf->usb_iface->cur_altsetting->desc.bInterfaceNumber, cbaf->buffer, cbaf->buffer_size, 1000 /* FIXME: arbitrary */); if (result < 0) { - dev_err(dev, "cannot get available association types: %d\n", + dev_err(dev, "Cannot get available association types: %d\n", result); - goto error_get_assoc_types; + return result; } + assoc_info = cbaf->buffer; if (result < sizeof(*assoc_info)) { - dev_err(dev, "not enough data to decode association info " + dev_err(dev, "Not enough data to decode association info " "header (%zu vs %zu bytes required)\n", (size_t)result, sizeof(*assoc_info)); - goto error_bad_header; + return result; } + assoc_size = le16_to_cpu(assoc_info->Length); if (result < assoc_size) { - dev_err(dev, "not enough data to decode association info " + dev_err(dev, "Not enough data to decode association info " "(%zu vs %zu bytes required)\n", (size_t)assoc_size, sizeof(*assoc_info)); - goto error_bad_data; + return result; } /* * From now on, we just verify, but won't error out unless we * don't find the AR_TYPE_WUSB_{RETRIEVE_HOST_INFO,ASSOCIATE} * types. */ - ar_index = 0; itr = cbaf->buffer + sizeof(*assoc_info); top = cbaf->buffer + assoc_size; - d_printf(1, dev, "Found %u association requests (%zu bytes)\n", + dev_dbg(dev, "Found %u association requests (%zu bytes)\n", assoc_info->NumAssociationRequests, assoc_size); + while (itr < top) { u16 ar_type, ar_subtype; u32 ar_size; const char *ar_name; assoc_request = itr; + if (top - itr < sizeof(*assoc_request)) { - dev_err(dev, "not enough data to decode associaton " + dev_err(dev, "Not enough data to decode associaton " "request (%zu vs %zu bytes needed)\n", top - itr, sizeof(*assoc_request)); break; } + ar_type = le16_to_cpu(assoc_request->AssociationTypeId); ar_subtype = le16_to_cpu(assoc_request->AssociationSubTypeId); ar_size = le32_to_cpu(assoc_request->AssociationTypeInfoSize); + ar_name = "unknown"; + switch (ar_type) { case AR_TYPE_WUSB: - /* Verify we have what is mandated by AMS1.0 */ + /* Verify we have what is mandated by [WUSB-AM]. */ switch (ar_subtype) { case AR_TYPE_WUSB_RETRIEVE_HOST_INFO: - ar_name = "retrieve_host_info"; - ar_rhi_idx = ar_index; + ar_name = "RETRIEVE_HOST_INFO"; + ar_rhi = 1; break; case AR_TYPE_WUSB_ASSOCIATE: /* send assoc data */ - ar_name = "associate"; - ar_assoc_idx = ar_index; + ar_name = "ASSOCIATE"; + ar_assoc = 1; break; - default: - ar_name = "unknown"; }; break; - default: - ar_name = "unknown"; }; - d_printf(1, dev, "association request #%02u: 0x%04x/%04x " + + dev_dbg(dev, "Association request #%02u: 0x%04x/%04x " "(%zu bytes): %s\n", assoc_request->AssociationDataIndex, ar_type, ar_subtype, (size_t)ar_size, ar_name); itr += sizeof(*assoc_request); - ar_index++; } - if (ar_rhi_idx == -1) { + + if (!ar_rhi) { dev_err(dev, "Missing RETRIEVE_HOST_INFO association " "request\n"); - goto error_bad_reqs; + return -EINVAL; } - if (ar_assoc_idx == -1) { + if (!ar_assoc) { dev_err(dev, "Missing ASSOCIATE association request\n"); - goto error_bad_reqs; + return -EINVAL; } - return 0; -error_bad_header: -error_bad_data: -error_bad_reqs: -error_get_assoc_types: - return -EINVAL; + return 0; } static const struct wusb_cbaf_host_info cbaf_host_info_defaults = { @@ -256,6 +247,7 @@ static const struct wusb_cbaf_host_info cbaf_host_info_defaults = { static int cbaf_send_host_info(struct cbaf *cbaf) { struct wusb_cbaf_host_info *hi; + size_t name_len; size_t hi_size; hi = cbaf->buffer; @@ -263,11 +255,11 @@ static int cbaf_send_host_info(struct cbaf *cbaf) *hi = cbaf_host_info_defaults; hi->CHID = cbaf->chid; hi->LangID = 0; /* FIXME: I guess... */ - strncpy(hi->HostFriendlyName, cbaf->host_name, - hi->HostFriendlyName_hdr.len); - hi->HostFriendlyName_hdr.len = - cpu_to_le16(strlen(hi->HostFriendlyName)); - hi_size = sizeof(*hi) + strlen(hi->HostFriendlyName); + strlcpy(hi->HostFriendlyName, cbaf->host_name, CBA_NAME_LEN); + name_len = strlen(cbaf->host_name); + hi->HostFriendlyName_hdr.len = cpu_to_le16(name_len); + hi_size = sizeof(*hi) + name_len; + return usb_control_msg(cbaf->usb_dev, usb_sndctrlpipe(cbaf->usb_dev, 0), CBAF_REQ_SET_ASSOCIATION_RESPONSE, USB_DIR_OUT | USB_TYPE_CLASS | USB_RECIP_INTERFACE, @@ -276,8 +268,47 @@ static int cbaf_send_host_info(struct cbaf *cbaf) hi, hi_size, 1000 /* FIXME: arbitrary */); } -/* Show current CHID info we have set from user space */ -static ssize_t cbaf_wusb_host_info_show(struct device *dev, +/* + * Get device's information (CDID) associated to CHID + * + * The device will return it's information (CDID, name, bandgroups) + * associated to the CHID we have set before, or 0 CDID and default + * name and bandgroup if no CHID set or unknown. + */ +static int cbaf_cdid_get(struct cbaf *cbaf) +{ + int result; + struct device *dev = &cbaf->usb_iface->dev; + struct wusb_cbaf_device_info *di; + size_t needed; + + di = cbaf->buffer; + result = usb_control_msg( + cbaf->usb_dev, usb_rcvctrlpipe(cbaf->usb_dev, 0), + CBAF_REQ_GET_ASSOCIATION_REQUEST, + USB_DIR_IN | USB_TYPE_CLASS | USB_RECIP_INTERFACE, + 0x0200, cbaf->usb_iface->cur_altsetting->desc.bInterfaceNumber, + di, cbaf->buffer_size, 1000 /* FIXME: arbitrary */); + if (result < 0) { + dev_err(dev, "Cannot request device information: %d\n", result); + return result; + } + + needed = result < sizeof(*di) ? sizeof(*di) : le32_to_cpu(di->Length); + if (result < needed) { + dev_err(dev, "Not enough data in DEVICE_INFO reply (%zu vs " + "%zu bytes needed)\n", (size_t)result, needed); + return result; + } + + strlcpy(cbaf->device_name, di->DeviceFriendlyName, CBA_NAME_LEN); + cbaf->cdid = di->CDID; + cbaf->device_band_groups = le16_to_cpu(di->BandGroups); + + return 0; +} + +static ssize_t cbaf_wusb_chid_show(struct device *dev, struct device_attribute *attr, char *buf) { @@ -286,17 +317,10 @@ static ssize_t cbaf_wusb_host_info_show(struct device *dev, char pr_chid[WUSB_CKHDID_STRSIZE]; ckhdid_printf(pr_chid, sizeof(pr_chid), &cbaf->chid); - return scnprintf(buf, PAGE_SIZE, "CHID: %s\nName: %s\n", - pr_chid, cbaf->host_name); + return scnprintf(buf, PAGE_SIZE, "%s\n", pr_chid); } -/* - * Get a host info CHID from user space and send it to the device. - * - * The user can recover a CC from the device associated to that CHID - * by cat'ing wusb_connection_context. - */ -static ssize_t cbaf_wusb_host_info_store(struct device *dev, +static ssize_t cbaf_wusb_chid_store(struct device *dev, struct device_attribute *attr, const char *buf, size_t size) { @@ -308,8 +332,7 @@ static ssize_t cbaf_wusb_host_info_store(struct device *dev, "%02hhx %02hhx %02hhx %02hhx " "%02hhx %02hhx %02hhx %02hhx " "%02hhx %02hhx %02hhx %02hhx " - "%02hhx %02hhx %02hhx %02hhx " - "%04hx %64s\n", + "%02hhx %02hhx %02hhx %02hhx", &cbaf->chid.data[0] , &cbaf->chid.data[1], &cbaf->chid.data[2] , &cbaf->chid.data[3], &cbaf->chid.data[4] , &cbaf->chid.data[5], @@ -317,24 +340,79 @@ static ssize_t cbaf_wusb_host_info_store(struct device *dev, &cbaf->chid.data[8] , &cbaf->chid.data[9], &cbaf->chid.data[10], &cbaf->chid.data[11], &cbaf->chid.data[12], &cbaf->chid.data[13], - &cbaf->chid.data[14], &cbaf->chid.data[15], - &cbaf->host_band_groups, cbaf->host_name); - if (result != 18) { - dev_err(dev, "Unrecognized CHID (need 16 8-bit hex digits, " - "a 16 bit hex band group mask " - "and a host name, got only %d)\n", (int)result); + &cbaf->chid.data[14], &cbaf->chid.data[15]); + + if (result != 16) return -EINVAL; - } + result = cbaf_send_host_info(cbaf); if (result < 0) - dev_err(dev, "Couldn't send host information to device: %d\n", - (int)result); - else - d_printf(1, dev, "HI sent, wusb_cc can be read now\n"); - return result < 0 ? result : size; + return result; + result = cbaf_cdid_get(cbaf); + if (result < 0) + return -result; + return size; +} +static DEVICE_ATTR(wusb_chid, 0600, cbaf_wusb_chid_show, cbaf_wusb_chid_store); + +static ssize_t cbaf_wusb_host_name_show(struct device *dev, + struct device_attribute *attr, + char *buf) +{ + struct usb_interface *iface = to_usb_interface(dev); + struct cbaf *cbaf = usb_get_intfdata(iface); + + return scnprintf(buf, PAGE_SIZE, "%s\n", cbaf->host_name); +} + +static ssize_t cbaf_wusb_host_name_store(struct device *dev, + struct device_attribute *attr, + const char *buf, size_t size) +{ + ssize_t result; + struct usb_interface *iface = to_usb_interface(dev); + struct cbaf *cbaf = usb_get_intfdata(iface); + + result = sscanf(buf, "%63s", cbaf->host_name); + if (result != 1) + return -EINVAL; + + return size; +} +static DEVICE_ATTR(wusb_host_name, 0600, cbaf_wusb_host_name_show, + cbaf_wusb_host_name_store); + +static ssize_t cbaf_wusb_host_band_groups_show(struct device *dev, + struct device_attribute *attr, + char *buf) +{ + struct usb_interface *iface = to_usb_interface(dev); + struct cbaf *cbaf = usb_get_intfdata(iface); + + return scnprintf(buf, PAGE_SIZE, "0x%04x\n", cbaf->host_band_groups); +} + +static ssize_t cbaf_wusb_host_band_groups_store(struct device *dev, + struct device_attribute *attr, + const char *buf, size_t size) +{ + ssize_t result; + struct usb_interface *iface = to_usb_interface(dev); + struct cbaf *cbaf = usb_get_intfdata(iface); + u16 band_groups = 0; + + result = sscanf(buf, "%04hx", &band_groups); + if (result != 1) + return -EINVAL; + + cbaf->host_band_groups = band_groups; + + return size; } -static DEVICE_ATTR(wusb_host_info, 0600, cbaf_wusb_host_info_show, - cbaf_wusb_host_info_store); + +static DEVICE_ATTR(wusb_host_band_groups, 0600, + cbaf_wusb_host_band_groups_show, + cbaf_wusb_host_band_groups_store); static const struct wusb_cbaf_device_info cbaf_device_info_defaults = { .Length_hdr = WUSB_AR_Length, @@ -344,77 +422,72 @@ static const struct wusb_cbaf_device_info cbaf_device_info_defaults = { .DeviceFriendlyName_hdr = WUSB_AR_DeviceFriendlyName, }; -/* - * Get device's information (CDID) associated to CHID - * - * The device will return it's information (CDID, name, bandgroups) - * associated to the CHID we have set before, or 0 CDID and default - * name and bandgroup if no CHID set or unknown. - */ -static int cbaf_cdid_get(struct cbaf *cbaf) +static ssize_t cbaf_wusb_cdid_show(struct device *dev, + struct device_attribute *attr, char *buf) { - int result; - struct device *dev = &cbaf->usb_iface->dev; - struct wusb_cbaf_device_info *di; - size_t needed, dev_name_size; + struct usb_interface *iface = to_usb_interface(dev); + struct cbaf *cbaf = usb_get_intfdata(iface); + char pr_cdid[WUSB_CKHDID_STRSIZE]; - di = cbaf->buffer; - result = usb_control_msg( - cbaf->usb_dev, usb_rcvctrlpipe(cbaf->usb_dev, 0), - CBAF_REQ_GET_ASSOCIATION_REQUEST, - USB_DIR_IN | USB_TYPE_CLASS | USB_RECIP_INTERFACE, - 0x0200, cbaf->usb_iface->cur_altsetting->desc.bInterfaceNumber, - di, cbaf->buffer_size, 1000 /* FIXME: arbitrary */); - if (result < 0) { - dev_err(dev, "Cannot request device information: %d\n", result); - goto error_req_di; - } - needed = result < sizeof(*di) ? sizeof(*di) : le32_to_cpu(di->Length); - if (result < needed) { - dev_err(dev, "Not enough data in DEVICE_INFO reply (%zu vs " - "%zu bytes needed)\n", (size_t)result, needed); - goto error_bad_di; - } - cbaf->cdid = di->CDID; - dev_name_size = le16_to_cpu(di->DeviceFriendlyName_hdr.len); - dev_name_size = dev_name_size > 65 - 1 ? 65 - 1 : dev_name_size; - memcpy(cbaf->device_name, di->DeviceFriendlyName, dev_name_size); - cbaf->device_name[dev_name_size] = 0; - cbaf->device_band_groups = le16_to_cpu(di->BandGroups); - result = 0; -error_req_di: -error_bad_di: - return result; + ckhdid_printf(pr_cdid, sizeof(pr_cdid), &cbaf->cdid); + return scnprintf(buf, PAGE_SIZE, "%s\n", pr_cdid); } -/* - * Get device information and print it to sysfs - * - * See cbaf_cdid_get() - */ -static ssize_t cbaf_wusb_cdid_show(struct device *dev, - struct device_attribute *attr, char *buf) +static ssize_t cbaf_wusb_cdid_store(struct device *dev, + struct device_attribute *attr, + const char *buf, size_t size) { ssize_t result; struct usb_interface *iface = to_usb_interface(dev); struct cbaf *cbaf = usb_get_intfdata(iface); - char pr_cdid[WUSB_CKHDID_STRSIZE]; + struct wusb_ckhdid cdid; - result = cbaf_cdid_get(cbaf); - if (result < 0) { - dev_err(dev, "Cannot read device information: %d\n", - (int)result); - goto error_get_di; - } - ckhdid_printf(pr_cdid, sizeof(pr_cdid), &cbaf->cdid); - result = scnprintf(buf, PAGE_SIZE, - "CDID: %s\nName: %s\nBand_groups: 0x%04x\n", - pr_cdid, cbaf->device_name, - cbaf->device_band_groups); -error_get_di: - return result; + result = sscanf(buf, + "%02hhx %02hhx %02hhx %02hhx " + "%02hhx %02hhx %02hhx %02hhx " + "%02hhx %02hhx %02hhx %02hhx " + "%02hhx %02hhx %02hhx %02hhx", + &cdid.data[0] , &cdid.data[1], + &cdid.data[2] , &cdid.data[3], + &cdid.data[4] , &cdid.data[5], + &cdid.data[6] , &cdid.data[7], + &cdid.data[8] , &cdid.data[9], + &cdid.data[10], &cdid.data[11], + &cdid.data[12], &cdid.data[13], + &cdid.data[14], &cdid.data[15]); + if (result != 16) + return -EINVAL; + + cbaf->cdid = cdid; + + return size; +} +static DEVICE_ATTR(wusb_cdid, 0600, cbaf_wusb_cdid_show, cbaf_wusb_cdid_store); + +static ssize_t cbaf_wusb_device_band_groups_show(struct device *dev, + struct device_attribute *attr, + char *buf) +{ + struct usb_interface *iface = to_usb_interface(dev); + struct cbaf *cbaf = usb_get_intfdata(iface); + + return scnprintf(buf, PAGE_SIZE, "0x%04x\n", cbaf->device_band_groups); +} + +static DEVICE_ATTR(wusb_device_band_groups, 0600, + cbaf_wusb_device_band_groups_show, + NULL); + +static ssize_t cbaf_wusb_device_name_show(struct device *dev, + struct device_attribute *attr, + char *buf) +{ + struct usb_interface *iface = to_usb_interface(dev); + struct cbaf *cbaf = usb_get_intfdata(iface); + + return scnprintf(buf, PAGE_SIZE, "%s\n", cbaf->device_name); } -static DEVICE_ATTR(wusb_cdid, 0600, cbaf_wusb_cdid_show, NULL); +static DEVICE_ATTR(wusb_device_name, 0600, cbaf_wusb_device_name_show, NULL); static const struct wusb_cbaf_cc_data cbaf_cc_data_defaults = { .AssociationTypeId_hdr = WUSB_AR_AssociationTypeId, @@ -435,9 +508,7 @@ static const struct wusb_cbaf_cc_data_fail cbaf_cc_data_fail_defaults = { }; /* - * Send a new CC to the device - * - * So we update the CK and send the whole thing to the device + * Send a new CC to the device. */ static int cbaf_cc_upload(struct cbaf *cbaf) { @@ -452,30 +523,25 @@ static int cbaf_cc_upload(struct cbaf *cbaf) ccd->CDID = cbaf->cdid; ccd->CK = cbaf->ck; ccd->BandGroups = cpu_to_le16(cbaf->host_band_groups); + + dev_dbg(dev, "Trying to upload CC:\n"); + ckhdid_printf(pr_cdid, sizeof(pr_cdid), &ccd->CHID); + dev_dbg(dev, " CHID %s\n", pr_cdid); + ckhdid_printf(pr_cdid, sizeof(pr_cdid), &ccd->CDID); + dev_dbg(dev, " CDID %s\n", pr_cdid); + dev_dbg(dev, " Bandgroups 0x%04x\n", cbaf->host_band_groups); + result = usb_control_msg( cbaf->usb_dev, usb_sndctrlpipe(cbaf->usb_dev, 0), CBAF_REQ_SET_ASSOCIATION_RESPONSE, USB_DIR_OUT | USB_TYPE_CLASS | USB_RECIP_INTERFACE, 0x0201, cbaf->usb_iface->cur_altsetting->desc.bInterfaceNumber, ccd, sizeof(*ccd), 1000 /* FIXME: arbitrary */); - d_printf(1, dev, "Uploaded CC:\n"); - ckhdid_printf(pr_cdid, sizeof(pr_cdid), &ccd->CHID); - d_printf(1, dev, " CHID %s\n", pr_cdid); - ckhdid_printf(pr_cdid, sizeof(pr_cdid), &ccd->CDID); - d_printf(1, dev, " CDID %s\n", pr_cdid); - ckhdid_printf(pr_cdid, sizeof(pr_cdid), &ccd->CK); - d_printf(1, dev, " CK %s\n", pr_cdid); - d_printf(1, dev, " bandgroups 0x%04x\n", cbaf->host_band_groups); + return result; } -/* - * Send a new CC to the device - * - * We take the CDID and CK from user space, the rest from the info we - * set with host_info. - */ -static ssize_t cbaf_wusb_cc_store(struct device *dev, +static ssize_t cbaf_wusb_ck_store(struct device *dev, struct device_attribute *attr, const char *buf, size_t size) { @@ -484,23 +550,10 @@ static ssize_t cbaf_wusb_cc_store(struct device *dev, struct cbaf *cbaf = usb_get_intfdata(iface); result = sscanf(buf, - "CDID: %02hhx %02hhx %02hhx %02hhx " - "%02hhx %02hhx %02hhx %02hhx " "%02hhx %02hhx %02hhx %02hhx " - "%02hhx %02hhx %02hhx %02hhx\n" - "CK: %02hhx %02hhx %02hhx %02hhx " "%02hhx %02hhx %02hhx %02hhx " "%02hhx %02hhx %02hhx %02hhx " - "%02hhx %02hhx %02hhx %02hhx\n", - &cbaf->cdid.data[0] , &cbaf->cdid.data[1], - &cbaf->cdid.data[2] , &cbaf->cdid.data[3], - &cbaf->cdid.data[4] , &cbaf->cdid.data[5], - &cbaf->cdid.data[6] , &cbaf->cdid.data[7], - &cbaf->cdid.data[8] , &cbaf->cdid.data[9], - &cbaf->cdid.data[10], &cbaf->cdid.data[11], - &cbaf->cdid.data[12], &cbaf->cdid.data[13], - &cbaf->cdid.data[14], &cbaf->cdid.data[15], - + "%02hhx %02hhx %02hhx %02hhx", &cbaf->ck.data[0] , &cbaf->ck.data[1], &cbaf->ck.data[2] , &cbaf->ck.data[3], &cbaf->ck.data[4] , &cbaf->ck.data[5], @@ -509,25 +562,25 @@ static ssize_t cbaf_wusb_cc_store(struct device *dev, &cbaf->ck.data[10], &cbaf->ck.data[11], &cbaf->ck.data[12], &cbaf->ck.data[13], &cbaf->ck.data[14], &cbaf->ck.data[15]); - if (result != 32) { - dev_err(dev, "Unrecognized CHID/CK (need 32 8-bit " - "hex digits, got only %d)\n", (int)result); + if (result != 16) return -EINVAL; - } + result = cbaf_cc_upload(cbaf); if (result < 0) - dev_err(dev, "Couldn't upload connection context: %d\n", - (int)result); - else - d_printf(1, dev, "Connection context uploaded\n"); - return result < 0 ? result : size; + return result; + + return size; } -static DEVICE_ATTR(wusb_cc, 0600, NULL, cbaf_wusb_cc_store); +static DEVICE_ATTR(wusb_ck, 0600, NULL, cbaf_wusb_ck_store); static struct attribute *cbaf_dev_attrs[] = { - &dev_attr_wusb_host_info.attr, + &dev_attr_wusb_host_name.attr, + &dev_attr_wusb_host_band_groups.attr, + &dev_attr_wusb_chid.attr, &dev_attr_wusb_cdid.attr, - &dev_attr_wusb_cc.attr, + &dev_attr_wusb_device_name.attr, + &dev_attr_wusb_device_band_groups.attr, + &dev_attr_wusb_ck.attr, NULL, }; @@ -539,32 +592,33 @@ static struct attribute_group cbaf_dev_attr_group = { static int cbaf_probe(struct usb_interface *iface, const struct usb_device_id *id) { - int result; struct cbaf *cbaf; struct device *dev = &iface->dev; + int result = -ENOMEM; - result = -ENOMEM; cbaf = kzalloc(sizeof(*cbaf), GFP_KERNEL); - if (cbaf == NULL) { - dev_err(dev, "Unable to allocate instance\n"); + if (cbaf == NULL) goto error_kzalloc; - } cbaf->buffer = kmalloc(512, GFP_KERNEL); if (cbaf->buffer == NULL) goto error_kmalloc_buffer; + cbaf->buffer_size = 512; cbaf->usb_dev = usb_get_dev(interface_to_usbdev(iface)); cbaf->usb_iface = usb_get_intf(iface); result = cbaf_check(cbaf); - if (result < 0) + if (result < 0) { + dev_err(dev, "This device is not WUSB-CBAF compliant" + "and is not supported yet.\n"); goto error_check; + } + result = sysfs_create_group(&dev->kobj, &cbaf_dev_attr_group); if (result < 0) { dev_err(dev, "Can't register sysfs attr group: %d\n", result); goto error_create_group; } usb_set_intfdata(iface, cbaf); - d_printf(2, dev, "CBA attached\n"); return 0; error_create_group: @@ -587,7 +641,6 @@ static void cbaf_disconnect(struct usb_interface *iface) /* paranoia: clean up crypto keys */ memset(cbaf, 0, sizeof(*cbaf)); kfree(cbaf); - d_printf(1, dev, "CBA detached\n"); } static struct usb_device_id cbaf_id_table[] = { -- cgit v1.2.3