Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit c8cf2465 authored by David Vrabel's avatar David Vrabel Committed by David Vrabel
Browse files

uwb: document UWB and WUSB sysfs files



Add some brief documentation on the UWB and WUSB related sysfs files.

Signed-off-by: default avatarDavid Vrabel <david.vrabel@csr.com>
parent b60066c1
Loading
Loading
Loading
Loading
+28 −0
Original line number Diff line number Diff line
What:           /sys/bus/umc/
Date:           July 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
Description:
                The specification version this capability's hardware
                interface complies with.
+43 −0
Original line number Diff line number Diff line
@@ -85,3 +85,46 @@ Description:
Users:
		PowerTOP <power@bughost.org>
		http://www.lesswatts.org/projects/powertop/

What:		/sys/bus/usb/device/.../authorized
Date:		July 2008
KernelVersion:	2.6.26
Contact:	David Vrabel <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
Description:
		For Certified Wireless USB devices only.

		Write a 1 to force the device to disconnect
		(equivalent to unplugging a wired USB device).
+25 −0
Original line number Diff line number Diff line
What:           /sys/class/usb_host/usb_hostN/wusb_chid
Date:           July 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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.
+144 −0
Original line number Diff line number Diff line
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:

                <channel> [<bpst offset>]

                to start beaconing on a specific channel, or stop
                beaconing if <channel> is -1.  Valid channels depends
                on the radio controller's supported band groups.

                <bpst offset> 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:

                <channel> <type> [<bpst offset>]

                to start (or stop) scanning on a channel.  <type> is one of:
                    0 - scan
                    1 - scan outside BP
                    2 - scan while inactive
                    3 - scanning disabled
                    4 - scan (with start time of <bpst offset>)

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/<EUI-48>/
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/<EUI-48>/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/<EUI-48>/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>/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/<EUI-48>/BPST
Date:           July 2008
KernelVersion:  2.6.27
Contact:        linux-usb@vger.kernel.org
Description:

What:           /sys/class/uwb_rc/uwbN/<EUI-48>/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/<EUI-48>/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/<EUI-48>/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.
+100 −0
Original line number Diff line number Diff line
What:           /sys/bus/usb/drivers/wusb_cbaf/.../wusb_*
Date:           August 2008
KernelVersion:  2.6.27
Contact:        David Vrabel <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
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 <david.vrabel@csr.com>
Description:
                Write 16 space-separated random, hex octets to
                associate with the device.