Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/jikos/hid

* HID over I2C Device-Tree bindings

HID over I2C provides support for various Human Interface Devices over the

I2C bus. These devices can be for example touchpads, keyboards, touch screens

or sensors.

The specification has been written by Microsoft and is currently available here:

http://msdn.microsoft.com/en-us/library/windows/hardware/hh852380.aspx

If this binding is used, the kernel module i2c-hid will handle the communication

with the device and the generic hid core layer will handle the protocol.

Required properties:

- compatible: must be "hid-over-i2c"

- reg: i2c slave address

- hid-descr-addr: HID descriptor address

- interrupt-parent: the phandle for the interrupt controller

- interrupts: interrupt line

Example:

	i2c-hid-dev@2c {

		compatible = "hid-over-i2c";

		reg = <0x2c>;

		hid-descr-addr = <0x0020>;

		interrupt-parent = <&gpx3>;

		interrupts = <3 2>;

	};

  is of type "struct uhid_data_req".

  This may be received even though you haven't received UHID_OPEN, yet.

  UHID_OUTPUT_EV:

  UHID_OUTPUT_EV (obsolete):

  Same as UHID_OUTPUT but this contains a "struct input_event" as payload. This

  is called for force-feedback, LED or similar events which are received through

  an input device by the HID subsystem. You should convert this into raw reports

  and send them to your device similar to events of type UHID_OUTPUT.

  This is no longer sent by newer kernels. Instead, HID core converts it into a

  raw output report and sends it via UHID_OUTPUT.

  UHID_FEATURE:

  This event is sent if the kernel driver wants to perform a feature request as

                            Linux Gamepad API

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

1. Intro

~~~~~~~~

Linux provides many different input drivers for gamepad hardware. To avoid

having user-space deal with different button-mappings for each gamepad, this

document defines how gamepads are supposed to report their data.

2. Geometry

~~~~~~~~~~~

As "gamepad" we define devices which roughly look like this:

            ____________________________              __

           / [__ZL__]          [__ZR__] \               |

          / [__ TL __]        [__ TR __] \              | Front Triggers

       __/________________________________\__         __|

      /                                  _   \          |

     /      /\           __             (N)   \         |

    /       ||      __  |MO|  __     _       _ \        | Main Pad

   |    <===DP===> |SE|      |ST|   (W) -|- (E) |       |

    \       ||    ___          ___       _     /        |

    /\      \/   /   \        /   \     (S)   /\      __|

   /  \________ | LS  | ____ |  RS | ________/  \       |

  |         /  \ \___/ /    \ \___/ /  \         |      | Control Sticks

  |        /    \_____/      \_____/    \        |    __|

  |       /                              \       |

   \_____/                                \_____/

       |________|______|    |______|___________|

         D-Pad    Left       Right   Action Pad

                 Stick       Stick

                   |_____________|

                      Menu Pad

Most gamepads have the following features:

  - Action-Pad

    4 buttons in diamonds-shape (on the right side). The buttons are

    differently labeled on most devices so we define them as NORTH,

    SOUTH, WEST and EAST.

  - D-Pad (Direction-pad)

    4 buttons (on the left side) that point up, down, left and right.

  - Menu-Pad

    Different constellations, but most-times 2 buttons: SELECT - START

    Furthermore, many gamepads have a fancy branded button that is used as

    special system-button. It often looks different to the other buttons and

    is used to pop up system-menus or system-settings.

  - Analog-Sticks

    Analog-sticks provide freely moveable sticks to control directions. Not

    all devices have both or any, but they are present at most times.

    Analog-sticks may also provide a digital button if you press them.

  - Triggers

    Triggers are located on the upper-side of the pad in vertical direction.

    Not all devices provide them, but the upper buttons are normally named

    Left- and Right-Triggers, the lower buttons Z-Left and Z-Right.

  - Rumble

    Many devices provide force-feedback features. But are mostly just

    simple rumble motors.

3. Detection

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

All gamepads that follow the protocol described here map BTN_GAMEPAD. This is

an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.

However, not all gamepads provide all features, so you need to test for all

features that you need, first. How each feature is mapped is described below.

Legacy drivers often don't comply to these rules. As we cannot change them

for backwards-compatibility reasons, you need to provide fixup mappings in

user-space yourself. Some of them might also provide module-options that

change the mappings so you can adivce users to set these.

All new gamepads are supposed to comply with this mapping. Please report any

bugs, if they don't.

There are a lot of less-featured/less-powerful devices out there, which re-use

the buttons from this protocol. However, they try to do this in a compatible

fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons

and one analog stick. It reports them as if it were a gamepad with only one

analog stick and two trigger buttons on the right side.

But that means, that if you only support "real" gamepads, you must test

devices for _all_ reported events that you need. Otherwise, you will also get

devices that report a small subset of the events.

No other devices, that do not look/feel like a gamepad, shall report these

events.

4. Events

~~~~~~~~~

Gamepads report the following events:

Action-Pad:

  Every gamepad device has at least 2 action buttons. This means, that every

  device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless

  of the labels on the buttons, the codes are sent according to the

  physical position of the buttons.

  Please note that 2- and 3-button pads are fairly rare and old. You might

  want to filter gamepads that do not report all four.

    2-Button Pad:

      If only 2 action-buttons are present, they are reported as BTN_SOUTH and

      BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For

      horizontal layouts, the button more on the right is BTN_EAST.

    3-Button Pad:

      If only 3 action-buttons are present, they are reported as (from left

      to right): BTN_WEST, BTN_SOUTH, BTN_EAST

      If the buttons are aligned perfectly vertically, they are reported as

      (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST

    4-Button Pad:

      If all 4 action-buttons are present, they can be aligned in two

      different formations. If diamond-shaped, they are reported as BTN_NORTH,

      BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location.

      If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left

      is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST.

D-Pad:

  Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right

  Some of these are available as digital buttons, some as analog buttons. Some

  may even report both. The kernel does not convert between these so

  applications should support both and choose what is more appropriate if

  both are reported.

    Digital buttons are reported as:

      BTN_DPAD_*

    Analog buttons are reported as:

      ABS_HAT0X and ABS_HAT0Y

Analog-Sticks:

  The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is

  reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present.

  If analog-sticks provide digital buttons, they are mapped accordingly as

  BTN_THUMBL (first/left) and BTN_THUMBR (second/right).

Triggers:

  Trigger buttons can be available as digital or analog buttons or both. User-

  space must correctly deal with any situation and choose the most appropriate

  mode.

  Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL

  or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or

  ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL).

  If only one trigger-button combination is present (upper+lower), they are

  reported as "right" triggers (BTN_TR/ABS_HAT1X).

Menu-Pad:

  Menu buttons are always digital and are mapped according to their location

  instead of their labels. That is:

    1-button Pad: Mapped as BTN_START

    2-button Pad: Left button mapped as BTN_SELECT, right button mapped as

                  BTN_START

  Many pads also have a third button which is branded or has a special symbol

  and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo

  "HOME" button, the XBox "X"-button or Sony "P" button.

Rumble:

  Rumble is adverticed as FF_RUMBLE.

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

  Written 2013 by David Herrmann <dh.herrmann@gmail.com>

S:	Maintained

F:	drivers/memstick/host/r592.*

ROCCAT DRIVERS

M:	Stefan Achatz <erazor_de@users.sourceforge.net>

W:	http://sourceforge.net/projects/roccat/

S:	Maintained

F:	drivers/hid/hid-roccat*

F:	include/linux/hid-roccat*

F:	Documentation/ABI/*/sysfs-driver-hid-roccat*

ROCKETPORT DRIVER

P:	Comtrol Corp.

W:	http://www.comtrol.com

	To compile this driver as a module, choose M here: the

	module will be called hid-wiimote.

config HID_XINMO

	tristate "Xin-Mo non-fully compliant devices"

	depends on HID

	---help---

	Support for Xin-Mo devices that are not fully compliant with the HID

	standard. Currently only supports the Xin-Mo Dual Arcade. Say Y here

	if you have a Xin-Mo Dual Arcade controller.

config HID_ZEROPLUS

	tristate "Zeroplus based game controller support"

	depends on HID