docs: usb: convert documents to ReST

================================

Linux UWB + Wireless USB + WiNET

================================

   Copyright (C) 2005-2006 Intel Corporation

   (C) 2005-2006 Intel Corporation

   Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>

   This program is free software; you can redistribute it and/or

Wireless USB 1.0 specification (including Wireless USB host controller

and an Intel WiNET controller).

.. Contents

   1. Introduction

         1. HWA: Host Wire adapters, your Wireless USB dongle

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

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

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

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

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

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

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

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:

Device lists

------------

All UWB devices are kept in the list of the struct bus_type uwb_bus_type.

Bandwidth allocation

--------------------

The UWB stack maintains a local copy of DRP availability through

processing of incoming *DRP Availability Change* notifications. This

Wireless USB Host Controller drivers

====================================

*WARNING* This section needs a lot of work!

Now it all depends on external stimuli.

*New device connection*

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,

start enumerating and doing transfers through usb_hcd->urb_enqueue() to

read descriptors and move our data.

*Device life cycle and keep alives*

Device life cycle and keep alives

---------------------------------

Every time there is a successful transfer to/from a device, we update a

per-device activity timestamp. If not, every now and then we check and

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*

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

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*

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

Glossary

========

*DWA* -- Device Wire Adapter

Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by

InakyPerezGonzalez)

======================

Linux ACM driver v0.16

		 (c) 1999 Vojtech Pavlik <vojtech@suse.cz>

======================

Copyright (c) 1999 Vojtech Pavlik <vojtech@suse.cz>

Sponsored by SuSE

----------------------------------------------------------------------------

0. Disclaimer

~~~~~~~~~~~~~

with this program; if not, write to the Free Software Foundation, Inc., 59

Temple Place, Suite 330, Boston, MA 02111-1307 USA

  Should you need to contact me, the author, you can do so either by e-mail

- mail your message to <vojtech@suse.cz>, or by paper mail: Vojtech Pavlik,

Should you need to contact me, the author, you can do so either by e-mail -

mail your message to <vojtech@suse.cz>, or by paper mail: Vojtech Pavlik,

Ucitelska 1576, Prague 8, 182 00 Czech Republic

For your convenience, the GNU General Public License version 2 is included

Many modems do, here is a list of those I know of:

	3Com OfficeConnect 56k

	3Com Voice FaxModem Pro

	3Com Sportster

	MultiTech MultiModem 56k

	Zoom 2986L FaxModem

	Compaq 56k FaxModem

	ELSA Microlink 56k

	- 3Com OfficeConnect 56k

	- 3Com Voice FaxModem Pro

	- 3Com Sportster

	- MultiTech MultiModem 56k

	- Zoom 2986L FaxModem

	- Compaq 56k FaxModem

	- ELSA Microlink 56k

I know of one ISDN TA that does work with the acm driver:

	3Com USR ISDN Pro TA

	- 3Com USR ISDN Pro TA

Some cell phones also connect via USB. I know the following phones work:

	SonyEricsson K800i

	- SonyEricsson K800i

Unfortunately many modems and most ISDN TAs use proprietary interfaces and

thus won't work with this drivers. Check for ACM compliance before buying.

  To use the modems you need these modules loaded:

To use the modems you need these modules loaded::

	usbcore.ko

	uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko

2. Verifying that it works

~~~~~~~~~~~~~~~~~~~~~~~~~~

The first step would be to check /sys/kernel/debug/usb/devices, it should look

like this:

like this::

  T:  Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2

  B:  Alloc=  0/900 us ( 0%), #Int=  0, #Iso=  0

The presence of these three lines (and the Cls= 'comm' and 'data' classes)

is important, it means it's an ACM device. The Driver=acm means the acm

driver is used for the device. If you see only Cls=ff(vend.) then you're out

of luck, you have a device with vendor specific-interface.

of luck, you have a device with vendor specific-interface::

  D:  Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs=  2

  I:  If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm

  I:  If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm

In the system log you should see:

In the system log you should see::

  usb.c: USB new device connect, assigned device number 2

  usb.c: kmalloc IF c7691fa0, numif 1

==============================================================

Authorizing (or not) your USB devices to connect to the system

==============================================================

(C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation

Copyright (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation

This feature allows you to control if a USB device can be used (or

not) in a system. This feature will allow you to implement a lock-down

modification, only if root authorizes the device to be configured will

then it be possible to use it.

Usage:

Usage

=====

Authorize a device to connect:

Authorize a device to connect::

	$ echo 1 > /sys/bus/usb/devices/DEVICE/authorized

Deauthorize a device:

De-authorize a device::

	$ echo 0 > /sys/bus/usb/devices/DEVICE/authorized

Set new devices connected to hostX to be deauthorized by default (ie:

lock down):

lock down)::

	$ echo 0 > /sys/bus/usb/devices/usbX/authorized_default

Remove the lock down:

Remove the lock down::

	$ echo 1 > /sys/bus/usb/devices/usbX/authorized_default

Example system lockdown (lame)

-----------------------

------------------------------

Imagine you want to implement a lockdown so only devices of type XYZ

can be connected (for example, it is a kiosk machine with a visible

USB port):

USB port)::

  boot up

  rc.local ->

      echo 0 > $host/authorized_default

   done

Hookup an script to udev, for new USB devices

Hookup an script to udev, for new USB devices::

 if device_is_my_type $DEV

 then

security verification you can make (or the best, for someone willing

to break it). If you need something secure, use crypto and Certificate

Authentication or stuff like that. Something simple for an storage key

could be:

could be::

 function device_is_my_type()

 {

Interface authorization

-----------------------

There is a similar approach to allow or deny specific USB interfaces.

That allows to block only a subset of an USB device.

Authorize an interface:

Authorize an interface::

	$ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized

Deauthorize an interface:

Deauthorize an interface::

	$ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized

The default value for new interfaces

on a particular USB bus can be changed, too.

Allow interfaces per default:

Allow interfaces per default::

	$ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default

Deny interfaces per default:

Deny interfaces per default::

	$ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default

Per default the interface_authorized_default bit is 1.

==============================================

ChipIdea Highspeed Dual Role Controller Driver

==============================================

1. How to test OTG FSM(HNP and SRP)

-----------------------------------

To show how to demo OTG HNP and SRP functions via sys input files

with 2 Freescale i.MX6Q sabre SD boards.

1.1 How to enable OTG FSM

---------------------------------------

-------------------------

1.1.1 Select CONFIG_USB_OTG_FSM in menuconfig, rebuild kernel

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Image and modules. If you want to check some internal

variables for otg fsm, mount debugfs, there are 2 files

which can show otg fsm variables and some controller registers value:

which can show otg fsm variables and some controller registers value::

	cat /sys/kernel/debug/ci_hdrc.0/otg

	cat /sys/kernel/debug/ci_hdrc.0/registers

1.1.2 Add below entries in your dts file for your controller node

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

	otg-rev = <0x0200>;

	adp-disable;

1.2 Test operations

-------------------

1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded

   (e.g. g_mass_storage).

   The A-device(with micro A plug inserted) should enumerate B-device.

3) Role switch

   On B-device:

   On B-device::

	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req

   B-device should take host role and enumerate A-device.

4) A-device switch back to host.

   On B-device:

   On B-device::

	echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req

   or, by introducing HNP polling, B-Host can know when A-peripheral wish

   to be host role, so this role switch also can be trigged in A-peripheral

   side by answering the polling from B-Host, this can be done on A-device:

   side by answering the polling from B-Host, this can be done on A-device::

	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req

   A-device should switch back to host and enumerate B-device.

   A-device should NOT enumerate B-device.

   if A-device wants to use bus:

   On A-device:

   On A-device::

	echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop

	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req

   if B-device wants to use bus:

   On B-device:

   On B-device::

	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req

7) A-device power down the bus.

   On A-device:

   On A-device::

	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop

   A-device should disconnect with B-device and power down the bus.

8) B-device does data pulse for SRP.

   On B-device:

   On B-device::

	echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req

   A-device should resume usb bus and enumerate B-device.

July 27, 2012 Revision 2.0 version 1.1a"

2. How to enable USB as system wakeup source

-----------------------------------

--------------------------------------------

Below is the example for how to enable USB as system wakeup source

at imx6 platform.

2.1 Enable core's wakeup

2.1 Enable core's wakeup::

	echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup

2.2 Enable glue layer's wakeup

2.2 Enable glue layer's wakeup::

	echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup

2.3 Enable PHY's wakeup (optional)

2.3 Enable PHY's wakeup (optional)::

	echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup

2.4 Enable roothub's wakeup

2.4 Enable roothub's wakeup::

	echo enabled > /sys/bus/usb/devices/usb1/power/wakeup

2.5 Enable related device's wakeup

2.5 Enable related device's wakeup::

	echo enabled > /sys/bus/usb/devices/1-1/power/wakeup

If the system has only one usb port, and you want usb wakeup at this port, you

can use below script to enable usb wakeup.

for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done;

can use below script to enable usb wakeup::

	for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done;

===========

DWC3 driver

===========

TODO

~~~~~~

~~~~

Please pick something while reading :)

- Convert interrupt handler to per-ep-thread-irq

  until the command completes which is bad.

  Implementation idea:

  - dwc core implements a demultiplexing irq chip for interrupts per

    endpoint. The interrupt numbers are allocated during probe and belong

    to the device. If MSI provides per-endpoint interrupt this dummy

  - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout()

    until the command completes.

  - the interrupt handler is split into the following pieces:

    - primary handler of the device

      goes through every event and calls generic_handle_irq() for event

      it. On return from generic_handle_irq() in acknowledges the event

      for command completion.

  Latency:

   There should be no increase in latency since the interrupt-thread has a

   high priority and will be run before an average task in user land

   (except the user changed priorities).