		GPIO USB device and driver
		==========================

Simon Guinot <sguinot@lacie.com>
Last updated Jun 29, 2010


1. What is a GPIO USB Port ?
----------------------------

A GPIO USB port is a pseudo device which associate a set of GPIOs with
a USB port/controller. this allow to group together the USB related GPIOs.

The following array enumerate the supported GPIO types:

 name     | direction | mode   | description
 ---------------------------------------------------------------
 vbus_out | output    | host   | enable VBUS
 fuse     | input     | host   | detect VBUS failure
 mode     | output    | all    | set the connector type (A or B)
 vbus_in  | input     | device | detect VBUS


Some rules:

- a port could provide none or all of the GPIO types.
- a port can't host several vbus_in and mode GPIOs.

2. GPIO USB types
-----------------

- vbus_out:

  This output GPIO allow to enable or disable VBUS signal for a USB connector.

- fuse:

  This input GPIO is used to handle a fuse blow interrupt. A fuse interrupt can
  happen when a buggy USB device is connected to an USB port.

  After a blow, the driver disable the VBUS signal on all the USB connectors
  and if needed, prevent user from re-enabling it during some delay. This
  delay is relative to the fuse model and can/should be defined with the
  platform specific data. If any, no delay is the default.

  Note that this driver will attempt to discard some spurious fuse interrupts.
  This wrong behaviour has been observed on some 2Big Network v2 boards.

- mode:

  This output GPIO allow to associate a device or a host connector with the USB
  controller.

- vbus_in:

  This input GPIO is used to detect when a wire (VBUS powered) is plugged into
  the USB device connector. To handle this event, the driver send a udev
  notification. Then, a listen userspace process could trigger an USB mode
  switch...

3. driver :
-----------

This driver expose all the GPIO USB port through sysfs (see section 4).

To do:

- add support for deferred VBUS-out power on.

- add support for several fuses per GPIO USB port. This imply to create a kind
  of link between vbus-out and fuse GPIOs. Actually, when _the_ fuse blow, all
  the vbus-out GPIOs are disabled.

4. sysfs API
------------

All the USB GPIO types are exported to userspace via sysfs.

  fuse     read-only  1=on   0=off
  vbus_out read-write 0=off  1=on
  vbus_in  read-only  0=off  1=on
  mode     read-write 0=host 1=device

Here is the sysfs gpio-usb sub-tree organisation:

  /sys/devices/platform/
  |-- gpio-usb
  |   |-- port0
  |   |   |-- fuse
  |   |   |-- mode
  |   |   |-- vbus_in
  |   |   |-- vbus_out0
  |   |
  |   |   [...]
  |   |
  |   |   `-- vbus_outn

  [...]

  |   |-- portn
  |   |   |-- fuse
  |   |   |-- mode
  |   |   |-- vbus_in
  |   |   |-- vbus_out0
  |   |
  |   |   [...]
  |   |
  |   |   `-- vbus_outn

  [...]

5. GPIO USB ports on LaCie NAS
------------------------------

  Network Space {,Mini,Max} v2
  d2 Network v2
  2Big Network v2
  |
  `- port0
     |-- fuse
     |-- mode
     |-- vbus_in
     `-- vbus_out

  Internet Space v2
  5Big Network v2
  Wireless Space
  |
  `- port0
     |-- fuse
     `-- vbus_out

  Network Space Plug v2 (revB)
  |
  `- port0
     |-- fuse
     |-- vbus_out0
     |-- vbus_out1,2
     `-- vbus_out3

On the Network Space Plug v2 board, there is a single fuse for all the VBUS-out
GPIOs. After a fuse blow, VBUS signal will be disabled for each ports.
Re-enable vbus_out GPIOs one by one should allow to isolate a faulty port.

6. userspace notifications
--------------------------

- udev events for fuse and vbus-in GPIOs
- sysfs attribute polling

7. Usage examples
-----------------

TODO

8. How to add board support for GPIO USB ports ?
------------------------------------------------

The GPIO USB driver is compliant with the platform device and driver model.
For an example, please refer to the network_space_v2 board setup file.
